www.delorie.com/gnu/docs/uucp/uucp_59.html

search

	Buy GNU books!

Taylor UUCP

5.5 Chat Scripts

Chat scripts are used in several different places, such as dialing out on modems or logging in to remote systems. Chat scripts are made up of pairs of strings. The program waits until it sees the first string, known as the expect string, and then sends out the second string, the send string.

Each chat script is defined using a set of commands. These commands always end in a string beginning with chat, but may start with different strings. For example, in the `sys' file there is one set of commands beginning with chat and another set beginning with called-chat. The prefixes are only used to disambiguate different types of chat scripts, and this section ignores the prefixes when describing the commands.

chat strings

Specify a chat script. The arguments to the chat command are pairs of strings separated by whitespace. The first string of each pair is an expect string, the second is a send string. The program will wait for the expect string to appear; when it does, the program will send the send string. If the expect string does not appear within a certain number of seconds (as set by the chat-timeout command), the chat script fails and, typically, the call is aborted. If the final expect string is seen (and the optional final send string has been sent), the chat script is successful.

An expect string may contain additional subsend and subexpect strings, separated by hyphens. If the expect string is not seen, the subsend string is sent and the chat script continues by waiting for the subexpect string. This means that a hyphen may not appear in an expect string; on an ASCII system, use `\055' instead.

An expect string may simply be `""', meaning to skip the expect phase. Otherwise, the following escape characters may appear in expect strings:

`\b'

a backspace character

`\n'

a newline or line feed character

`\N'

a null character (for HDB compatibility)

`\r'

a carriage return character

`\s'

a space character

`\t'

a tab character

`\\'

a backslash character

`\ddd'

character ddd, where ddd are up to three octal digits

`\xddd'

character ddd, where ddd are hexadecimal digits.

As in C, there may be up to three octal digits following a backslash, but the hexadecimal escape sequence continues as far as possible. To follow a hexadecimal escape sequence with a hex digit, interpose a send string of `""'.

A chat script expect string may also specify a timeout. This is done by using the escape sequence `\Wseconds'. This escape sequence may only appear at the very end of the expect string. It temporarily overrides the timeout set by chat-timeout (described below) only for the expect string to which it is attached.

A send string may simply be `""' to skip the send phase. Otherwise, all of the escape characters legal for expect strings may be used, and the following escape characters are also permitted:

`EOT'

send an end of transmission character (^D)

`BREAK'

send a break character (may not work on all systems)

`\c'

suppress trailing carriage return at end of send string

`\d'

delay sending for 1 or 2 seconds

`\e'

disable echo checking

`\E'

enable echo checking

`\K'

same as `BREAK' (for HDB compatibility)

`\p'

pause sending for a fraction of a second

Some specific types of chat scripts also define additional escape sequences that may appear in the send string. For example, the login chat script defines `\L' and `\P' to send the login name and password, respectively.

A carriage return will be sent at the end of each send string, unless the \c escape sequence appears in the string. Note that some UUCP packages use \b for break, but here it means backspace.

Echo checking means that after writing each character the program will wait until the character is echoed. Echo checking must be turned on separately for each send string for which it is desired; it will be turned on for characters following \E and turned off for characters following \e.

chat-timeout number

The number of seconds to wait for an expect string in the chat script, before timing out and sending the next subsend, or failing the chat script entirely. The default value is 10 for a login chat or 60 for any other type of chat.

chat-fail string

If the string is seen at any time during a chat script, the chat script is aborted. The string may not contain any whitespace characters: escape sequences must be used for them. Multiple chat-fail commands may appear in a single chat script. The default is to have none.

This permits a chat script to be quickly aborted if an error string is seen. For example, a script used to dial out on a modem might use the command `chat-fail BUSY' to stop the chat script immediately if the string `BUSY' was seen.

The chat-fail strings are considered in the order they are listed, so if one string is a suffix of another the longer one should be listed first. This affects the error message which will be logged. Of course, if one string is contained within another, but is not a suffix, the smaller string will always be found before the larger string could match.

chat-seven-bit boolean

If the argument is true, all incoming characters are stripped to seven bits when being compared to the expect string. Otherwise all eight bits are used in the comparison. The default is true, because some Unix systems generate parity bits during the login prompt which must be ignored while running a chat script. This has no effect on any chat-program, which must ignore parity by itself if necessary.

chat-program strings

Specify a program to run before executing the chat script. This program could run its own version of a chat script, or it could do whatever it wants. If both chat-program and chat are specified, the program is executed first followed by the chat script.

The first argument to the chat-program command is the program name to run. The remaining arguments are passed to the program. The following escape sequences are recognized in the arguments:

\Y

port device name

\S

port speed

\\

backslash

Some specific uses of chat-program define additional escape sequences.

Arguments other than escape sequences are passed exactly as they appear in the configuration file, except that sequences of whitespace are compressed to a single space character (this exception may be removed in the future).

If the chat-program command is not used, no program is run.

On Unix, the standard input and standard output of the program will be attached to the port in use. Anything the program writes to standard error will be written to the UUCP log file. No other file descriptors will be open. If the program does not exit with a status of 0, it will be assumed to have failed. This means that the dialing programs used by some versions of HDB may not be used directly, but you may be able to run them via the dialHDB program in the `contrib' directory.

The program will be run as the uucp user, and the environment will be that of the process that started uucico, so care must be taken to maintain security.

No search path is used to find the program; a full file name must be given. If the program is an executable shell script, it will be passed to `/bin/sh' even on systems which are unable to execute shell scripts.

Here is a simple example of a chat script that might be used to reset a Hayes compatible modem.

chat "" ATZ OK-ATZ-OK

The first expect string is `""', so it is ignored. The chat script then sends `ATZ'. If the modem responds with `OK', the chat script finishes. If 60 seconds (the default timeout) pass before seeing `OK', the chat script sends another `ATZ'. If it then sees `OK', the chat script succeeds. Otherwise, the chat script fails.

For a more complex chat script example, see 5.7.3.3 Logging In.