CW(1)							      General Commands Manual							     CW(1)

NAME

       cw - sound characters as Morse code on the soundcard or console speaker

SYNOPSIS

       cw  [-s --system=SYSTEM]  [-d --device=DEVICE]  [-w --wpm=WPM] [-t --tone=HZ] [-v --volume=PERCENT] [-g --gap=GAP] [-k --weighting=WEIGHT]
       [-e --noecho] [-m --nomessages] [-c --nocommands] [-o --nocombinations] [-p --nocomments] [-f --infile=FILE]  [-h --help] [-V --version]

       cw installed on GNU/Linux systems understands both short form and long form command line options.  cw installed on other operating  systems
       may understand only the short form options.

       There are no mandatory options.

       Options	may  be  predefined  in  the environment variable CW_OPTIONS.  If defined, these options are used first; command line options take
       precedence.

DESCRIPTION

       cw reads characters from an input file, or from standard input, and sounds each valid character as Morse code on either	the  system  sound
       card,  or the system console speaker.  After it sounds a character, cw echoes it to standard output.  The input stream can contain embedded
       command strings.  These change the parameters used when sounding the Morse code.  cw reports any errors in embedded  commands  on  standard
       error.

       Use 'Ctrl+D' key combination to exit cw.

   COMMAND LINE OPTIONS
       cw understands the following command line options.  The long form options may not be available in non-LINUX versions.

       -s, --system=SYSTEM
	      Specifies  the  way that cw generates tones.  Valid values are: console for tones through the console speaker, alsa for tones gener-
	      ated through the system sound card using ALSA sound system, oss for tones generated through system sound card using OSS  sound  sys-
	      tem,  soundcard  for tones generated through the system sound card, but without explicit selection of sound system. These values can
	      be shortened to 'c', 'a', 'o', or 's', respectively. The default value is 'oss'.

       -d, --device=DEVICE
	      Specifies the device file to open for generating a sound.  cw will use default device if none is specified. The default devices are:
	      /dev/console  for sound produced through console, default for ALSA sound system, /dev/audio for OSS sound system.  See also NOTES ON
	      USING A SOUND CARD below.

       -w, --wpm=WPM
	      Sets the initial sending speed in words per minute.  The value must be between 4 and 60.	The default value is 12 WPM.

       -t, --tone=HZ
	      Sets the initial sounder pitch in Hz.  This value must be between 0 and 4,000.  A value of 0 selects silent operation,  and  can	be
	      used for timing checks or other testing.	The default value is 800Hz,

       -v, --volume=PERCENT
	      Sets  the  initial sending volume, as a percentage of full scale volume.	The value must be between 0 and 100.  The default value is
	      70 %.  Sound volumes work fully for sound card tones, but cw cannot control the volume of tones from the console speaker.   In  this
	      case, a volume of zero is silent, and all other volume values are simply sounded.

       -g, --gap=GAP
	      Sets  the initial extra gap, in dot lengths, between characters (the 'Farnsworth' delay).  It must be between 0 and 60.  The default
	      is 0.

       -k, --weighting=WEIGHT
	      Sets the initial weighting, as a percentage of dot lengths.  It must be between 20 and 80.  The default is 50.

       -e, --noecho
	      Stops cw echoing characters on standard output after they are sounded.  The default is to have echoing on.

       -m, --nomessages
	      Stops cw printing error messages on standard error.  The default is to print messages.

       -c, --nocommands
	      Stops cw from interpreting commands embedded in the input stream.  The default is to interpret embedded commands.

       -o, --nocombinations
	      Stops cw from treating character strings bracketed by [...] as a single combination character.  The default  is  to  honor  combina-
	      tions.

       -p, --nocomments
	      Stops  cw  from treating character strings bracketed by {...} as 'comments'.  Characters inside these braces will be echoed to stan-
	      dard output, but not sounded.  When comments are being honored, any embedded commands  inside  the  braces  will	be  ignored.   The
	      default is to honor comments.

       -f, --infile=FILE
	      Specifies a text file that cw can read to configure its practice text.

       -h, --help
	      Prints short help message.

       -V, --version
	      Prints information about program's version, authors and license.

   SOUNDING CHARACTERS
       cw  reads  characters, one at a time, from its standard input or from its input file.  Lowercase letters are converted internally to upper-
       case. The following list shows the valid IS0 8859-1 (Latin-1) characters that can be sounded by cw:

	      ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"$()+-./:;=?_@ and space

       In addition, the program also understands the following ISO 8859-1 and ISO 8859-2 accented characters:

	      UACOEEANS (S with cedilla),  (Z with caron/hacek),

       and accepts the following as single character forms of common procedural signals:

	      <>!&^~

       See cw(7,LOCAL) for more information on the above characters and Morse code.

       If cw receives a character not in this set, it prints an error message '?c', where c is the error character.  The only exceptions  to  this
       may  be	the cw command escape character '%', the combination start and stop characters '[' and ']', and the comment start and stop charac-
       ters '{' and '}'.  See EMBEDDED COMMANDS and MORSE CODE COMBINATIONS below.

   EMBEDDED COMMANDS
       cw recognizes special sequences in the input stream as embedded commands.  These commands alter the parameters of the cw while it  is  run-
       ning, or query current values.  All commands are prefixed by the command escape character '%', and those which set a value end with a semi-
       colon.

       The format of an embedded command to change a parameter value is

	      %Cvalue;

       where C is a command letter indicating what action cw is to take, and value is the argument or value for the command.

       Valid command letters are

       T      Sets the tone pitch used to sound a character.

       W      Sets the sending speed.

       G      Sets the 'Farnsworth' gap between characters.

       K      Sets the weighting.

       E      Disables or re-enables echoing of sent characters on standard output.

       M      Disables or re-enables error messages on standard error.

       S      Disables or re-enables speaker tone generation.

       C      Disables processing of embedded commands.  Note that once disabled, this command cannot re-enable them.

       O      Disables or re-enables recognition of [...] character combinations.

       P      Disables or re-enables recognition of {...} comments.  When comments are being recognized, any character after an  opening  '{'  and
	      before any closing '}' will be echoed to standard output, but will not be sounded, or have any other effect.

       For example, the embedded command sequence

	      %W25;%T1200;

       will set cw to a speed of 25 WPM, and a tone pitch of 1200Hz.

       The  'T',  'W', 'G', and 'A' commands take values along with the command.  The limits on values given for embedded commands are the same as
       the limits available for command line options, detailed above.

       The 'E', 'M', 'S', 'C' and 'O' commands are flags, and treat a value of zero as clear, and any other value as set.  So,	for  example,  the
       sequence

	      %M0;%C0;

       will turn off error messages, and then turn off the processing of embedded commands.

       If  a  parameter  is  set  successfully, cw reports the new setting on standard error (except if no error messages is set).  If an error is
       detected in an embedded command, cw reports an error.  For the formats of error messages see the MESSAGE FORMATS section below.

       The current values of parameters within cw may be queried, as well as set.  The command format

	      %?C

       queries the value of the parameter normally set with command C.	cw reports the current value on standard error, using the same	format	as
       when new values are set.

       The current values of parameters within cw may also be requested as output in Morse code.  The command format

	      %>C

       will generate Morse output reporting the value of the parameter normally set with command C.

       If embedded commands are disabled, '%' characters are treated as any other (in this case, invalid) input character.

       Once  processing  of  embedded commands has been switched off, any command to switch this feature back on will not be recognized.  That is,
       after '%C0;', an '%C1;' will not be recognized.

       There is one additional command, and that is '%Q'.  This command closes all open files and terminates cw.  Any characters after	this  com-
       mand in the input stream will be lost.

       The file cw.h provides a full set of definitions for the commands, special characters, and status codes of cw.

   MESSAGE FORMATS
       Where a parameter value is set correctly with an embedded command, the message format

	      =Cvalue

       is returned.  C is the command used, and value is the new value.

       If an invalid value is supplied for a parameter in an embedded command, a message

	      ?Cvalue

       is returned.

       Where an invalid command is encountered, the message format

	      ?%C

       is used.  For an invalid query, the message is

	      ??C

       and for an invalid request for a parameter in Morse code the message is

	      ?>C

       A character in the input stream that cannot be sounded produces a message

	      ?C

       These  messages are not intended to be user-friendly, but are designed to be easily and quickly interpreted by another program.	Similarly,
       the format of embedded commands is more computer-friendly than user-friendly.

       If error messages are disabled, no messages of any type are printed on standard error.

   MORSE CODE COMBINATIONS
       The standard set of characters offered by cw may not be sufficient for some purposes.  For example, some international  characters  do  not
       have equivalent ISO 8859-1 and ISO 8859-2 that cw can sound directly.

       To  help  in  sounding  such  characters,  cw  offers the ability to form combination characters by placing individual character components
       between [...] brackets.	Cw sounds characters inside a combination without the usual gap between them.  In this way, any missing  character
       in the set can be built.

       For example

	      [VA]

       is one way to form the VA procedural signal, though

	      [SK]

       works just as well.  The eight-dot error signal can be sounded with

	      [HSE]

       or the C-cedilla in international Morse code with

	      [CE]

       There can be as many valid letters, numbers, or figures inside the [...]  brackets as required.	For example, an alternative way of sending
       the error signal could be

	      [EEEEEEEE]

       Finally, three alternative ways of sending 73 might be

	      [TTEEE][EEETT]
	      [TDE][EUT]
	      [GEE][VT]

       Embedded commands may be placed inside [...] combinations if required.  Combinations do not nest.

       This feature can be disabled by using the -O or --nocombinations command line flags, or with the 'O' embedded command.  If combinations are
       disabled, '[' and ']' characters are treated as any other (invalid) input character.

   NOTES ON USING A SOUND CARD
       By default, cw tries to open OSS device "/dev/audio" to access the system sound card.  This is generally the correct device to use, but for
       systems with special requirements, or those with multiple sound cards, the option -d or --device, combined with -s or --system can be  used
       to specify the device and audio system for sound card access.  If the sound card device cannot be set up, cw prints the error message

	      cannot set up soundcard sound

       and exits.

       Sound  card  devices,  when  opened  through  OSS  sound system, are usually single-access devices, so that when one process has opened the
       device, other processes are prevented from using it. In such cases cw will of course conflict with any other programs that expect exclusive
       use of the system sound card (for example, MP3 players).  If cw finds that the sound card is already busy, it prints the error message

	      open /dev/audio: Device or resource busy

       and exits.

       The sound card device is not used if cw is only sending tones on the console speaker.

   AUDIO OUTPUT - DEFAULTS AND SELECTION
       cw  first  tries  to access sound card using OSS audio system and default OSS audio device name ('/dev/audio'), unless user specifies other
       audio device with option -d or --device.

       If opening soundcard through OSS fails, cw tries to access the sound card using ALSA audio system,  and	default  ALSA  audio  device  name
       ('default'), unless user specifies other audio device with option -d or --device.

       If  opening  soundcard through ALSA also fails, cw tries to access system console buzzer using default buzzer device '/dev/console', unless
       user specifies other audio device with option -d or --device.

       It is very common that in order to access the console buzzer device user has to have root privileges.  For that reason trying to open  con-
       sole  buzzer  almost  always  fails.   This is not a program's bug, this is a result of operating system's restrictions.  Making cw an suid
       binary bypasses this restriction.  The program does not fork() or exec(), so making it suid should be relatively safe.  Note  however  that
       this practice is discouraged for security reasons.

       As stated, user can tell cw which device to use, using -d or --device option.  Which device files are suitable will depend on which operat-
       ing system is running, which system user ID runs cw, and which user groups user belongs to.

NOTES

       Despite the fact that this manual page constantly and consistently refers to Morse code elements as dots and dashes, DO NOT think in  these
       terms when trying to learn Morse code.  Always think of them as 'dit's and 'dah's.

       The  Morse  code table in the cw(7,LOCAL) man page is provided for reference only.  If learning for the first time, you will be much better
       off learning by hearing the characters sent, rather than by looking at the table.

       Other programs running in the system may interfere with the timing of the Morse code that cw is sending.  If this is a problem, either  try
       to  run	on a quiescent system, or try running cw with nice(1L,C,1).  UNIX is not really designed for user-level programs to do the sort of
       fine timing required to send Morse code.  cw is therefore more sensitive than most programs to other system activity.

       cw uses system itimers for its internal timing.	On most UNIX flavors, itimers are not guaranteed to signal a program exactly at the speci-
       fied  time,  and  they  generally  offer a resolution only as good as the normal system 'clock tick' resolution.  An itimer SIGALRM usually
       falls on a system clock tick, making it accurate to no better than 10mS on a typical 100Hz kernel.

       The effect of this is that an itimer period is generally either exactly as specified, or, more likely, slightly longer.	At higher WPM set-
       tings,  the  cumulative effect of this affects timing accuracy, because at higher speeds, there are fewer 10mS clock ticks in a dot period.
       For example, at 12 WPM, the dot length is 100mS, enough to contain five kernel clock ticks.  But at 60 WPM, the dot length is 20mS, or just
       two kernel clock ticks.	So at higher speeds, the effect of itimer resolutions becomes more pronounced.

       To test itimer timing, first try

	      X="PARIS PARIS PARIS PARIS "

	      echo "$X" | time cw -w 4

       and note the elapsed time, which should be very close to one minute.  Next, try

	      echo "$X$X$X$X$X$X$X$X$X$X$X$X" | time cw -w 48

       The elapsed time should be the same.  If it has increased, this is the effect of system itimers delaying for slightly longer than the spec-
       ified period (higher WPM rates make more itimer calls).	That's itimers for you, not perfect for this job, but the best	there  is  without
       writing some, and perhaps a lot of, kernel code.

       Except for zero, which is silent, tone values lower than 10Hz may not sound at the expected pitch.

EXAMPLES

       Send a string of characters at 25 WPM, 700Hz, with no extra gaps:

	      echo "UNIX CW SOUNDER" | cw -w 25 -t 700

       Send a string at varying speeds and tones on both the sound card and the console speaker, specifying a system console device:

	      echo "%W12;%T400;400HZ 12WPM %W25;%T1500;1500HZ 25WPM" | cw -m -sb -d /dev/tty2

       Send C-cedilla, VA, and a report of the WPM setting, with extra spacing at half volume:

	      echo "[CE] [VA] %>W" | cw -g 10 -v 50

ERRORS AND OMISSIONS

       Cut numbers are not provided, though they can be emulated, up to a point, by pre-filtering.

       An output to an optional external device, for example, keying a line on the parallel port, or a serial line, might also be useful.

SEE ALSO

       Man pages for cw(7,LOCAL), libcw(3,LOCAL), cwgen(1,LOCAL), cwcp(1,LOCAL), and xcwcp(1,LOCAL).

cw ver. 3.0.1							 CW Tutor Package							     CW(1)