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 See Logging In.