Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CW(1)			    General Commands Manual			 CW(1)

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

       cw     [-s --system=SYSTEM]     [-d --device=DEVICE]	[-w --wpm=WPM]
       [-t --tone=HZ]	[-v --volume=PERCENT]	[-g --gap=GAP]	 [-k --weight-
       ing=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	prece-

       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 er-

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

       cw  understands	the following command line options.  The long form op-
       tions 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 val-
	      ues can be shortened to 'n', 'c',	'a', 'o', 'p', or 's', respec-
	      tively.  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 de-
	      vices are: /dev/console for sound	produced through console,  de-
	      fault  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  be-
	      tween  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 val-
	      ues 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 de-
	      fault 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-

       -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  hon-
	      ored,  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

       -h, --help
	      Prints short help	message.

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

       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:

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

       and  accepts  the  following as single character	forms of common	proce-
       dural signals:


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

       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  '{'

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

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


       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

       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 dis-
	      abled, this command cannot re-enable them.

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

       P      Disables or re-enables recognition of {...} comments.  When com-
	      ments 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


       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 se-


       will turn off error messages, and then turn off the processing  of  em-
       bedded commands.

       If a parameter is set successfully, cw reports the new setting on stan-
       dard error (except if no	error messages is set).	 If an	error  is  de-
       tected 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


       queries the value of the	parameter normally set with command C.	cw re-
       ports 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


       will generate Morse output reporting the	value of  the  parameter  nor-
       mally 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, spe-
       cial characters,	and status codes of cw.

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


       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


       is returned.

       Where an	invalid	command	is encountered,	the message format


       is used.	 For an	invalid	query, the message is


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


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


       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-

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

       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 com-
       bination	 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


       is one way to form the VA procedural signal, though


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


       or the C-cedilla	in international Morse code with


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


       Finally,	three alternative ways of sending 73 might be


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

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

       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.

       cw first	tries to access	sound card using PulseAudio sound system,  us-
       ing  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 ('de-
       fault'),	unless user specifies other audio device  with	option	-d  or

       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 prac-
       tice 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.

       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	refer-
       ence 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

       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 typi-
       cal 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  resolu-
       tions becomes more pronounced.

       To test itimer timing, first try


	      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	speci-
       fied period (higher WPM rates make more itimer calls).  That's  itimers
       for  you, not perfect for this job, but the best	there is without writ-
       ing 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.

       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, spec-
       ifying 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

       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.

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

cw ver.	3.5.1		       CW Tutor	Package				 CW(1)


Want to link to this manual page? Use this URL:

home | help