cw understands the following command line options. Only the short form options are available in non-LINUX versions.

-s, --sound

Specifies the way that cw generates tones. Valid values are 'soundcard' for tones through the system sound card, 'console' for tones through the console speaker, or 'both'. These may be shortened to 's', 'c', or 'b'. The default value is 'soundcard'.

-x, --sdevice

Specifies the device file to open for access to the sound card. The default device is /dev/dsp, and this is generally the correct device on most systems. See NOTES ON USING A SOUND CARD below. This option is invalid if cw is generating tones only on the console.

-y, --mdevice

Specifies the device file to open for access to the sound mixer. The default device is /dev/mixer. See NOTES ON USING A SOUND CARD below. This option is invalid if cw is generating tones only on the console.

-d, --cdevice

Specifies the device file to open for sound using the console speaker. The default device here is /dev/tty1, which is only marginally likely to be correct on Linux, and most likely incorrect on other platforms. In general, it is likely to be necessary to provide a suitable value for this option if console sound is selected. The value should be a console device file, capable of KIOCSOUND. See SELECTING SUITABLE SOUND DEVICE FILES below. This option is invalid if cw is generating tones only on the soundcard.

-f, --file

Specifies the input file to open. The default input file is standard input.

-w, --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, --hz, --tone

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

Sets the initial sending volume, as a percentage. 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

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

-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 honour combinations.

-p, --nocomments

Stops cw from treating character strings bracketed by {...} as output, but not sounded. When comments are being honoured, any embedded commands inside the braces will be ignored. The default is to honour comments.

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:

ÜÄÇÖÉÈÀѪ®

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.

cw recognises 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

Resets the tone pitch used to sound a character.

W

Resets the sending speed.

G

Resets the 'Farnsworth' gap between characters.

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 recognised, 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 recognised; that is, after '@C0;', an '@C1;' will not be recognised.

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.

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.

The standard set of characters offered by cw may not be sufficient for some purposes. For example, certain procedural signals, such as VA (also known as SK), have no ASCII equivalent, and cw cannot therefore sound them 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.

Note that it's usually correct for timing purposes to place the final character of a combination outside the [...] brackets, otherwise the gap that would normally appear between the combination character and the next character to be sent is lost.

For example

[V]A

is one way to form the VA procedural signal, though

[S]K

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

[HS]E

or the C-cedilla in international Morse code with

[C]E

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

[EEEEEEE]E

Finally, three alternative ways of sending 73 might be

[TTEE]E[EEET]T

[TD]E[EU]T

[GE]E[V]T

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.

By default, cw uses the sound device "/dev/dsp" 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 -x or --sdevice can be used to specify the device 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 are usually single-access devices; that is, when one process has opened the device, other processes are prevented from using it. If cw finds that the sound card is busy, it prints the error message

open /dev/dsp: Device or resource busy

but continues to retry on each new tone until it can access the device. Once it has control of the sound card, cw will only use it as long as it has Morse code tones to sound. It will close the device during pauses in output, to allow other programs to use it.

The main sound card device will often allow cw to control tone volumes directly, but where this is not possible, cw uses the mixer device instead. By default, this is "/dev/mixer", but the device can be specified with the -y or --mdevice options. In general, as with the main sound card device, the default mixer device is usually the correct one to use.

The mixer device is only used if the sound card does not allow volume control through the main sound card device.

cw will of course conflict with any other programs that expect exclusive use of the system sound card (for example, MP3 players).

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

When cw sounds Morse code on the UNIX console speaker, it uses the KIOCSOUND ioctl. By default, it will try to use the device "/dev/tty1", unless the -d or --cdevice option is used. If the device refuses to create tones, cw prints the error message

cannot set up console sound

and exits.

If the default device is not available, or if cw has no permissions to use it, cw will need to be told which device to use. Which device files are suitable will depend on which operating system is running, and which system user ID runs cw. They must however be console multiscreen devices: /dev/tty1 and up on LINUX, /dev/tty01 and up on OpenServer, and /dev/vt01 and up on UnixWare and OpenUNIX.

For console sound on LINUX, it is normally possible to run cw as superuser, with the default /dev/tty1 as the sound device; this combination will usually work. Unless running as superuser, cw won't have the necessary permission to access a 'foreign' tty. Making cw an suid binary avoids this problem; the program does not fork() or exec(), so making it suid should be relatively safe.

There is no need to worry about console sound devices if cw is only sending tones on the system sound card.