Provided by: cw_3.5.1-3build1_amd64 bug

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: null  for  no  tones,
              just  timings,  console  for  tones  through  the  console  speaker, alsa for tones
              generated through the system sound card using ALSA  sound  system,  oss  for  tones
              generated  through  system  sound card using OSS sound system, pulseaudio for tones
              generated through system sound card using PulseAudio sound  system,  soundcard  for
              tones  generated  through  the system sound card, but without explicit selection of
              sound system. These values can be shortened to 'n', 'c', 'a',  'o',  'p',  or  's',
              respectively.  The  default  value  is  'pulseaudio'  (on  systems  with PulseAudio
              installed), followed by '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,  a  default  device for PulseAudio 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 combinations.

       -p, --nocomments
              Stops  cw  from  treating  character  strings  bracketed  by  {...}  as 'comments'.
              Characters inside these braces will be echoed to standard 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 uppercase. 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:

              ÜÄÇÖÉÈÀÑŞ (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
       characters '{' 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 running, or query current values.  All commands
       are prefixed by the command escape character '%', and those which set a value end  with  a
       semicolon.

       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 command 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 default PulseAudio. If PulseAudio server is  not  accessible,
       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 PulseAudio sound system, using default device
       name, unless user specifies other audio device with option -d or --device.

       cw then 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 console 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 operating 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 specified 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 settings, 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 specified 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 the console speaker, specifying a system
       console device:

              echo "%W12;%T400;400HZ 12WPM %W25;%T1500;1500HZ 25WPM" | cw -m -sc -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).