ChorusOS man pages section 1M: System Management Utilities

chat(1M)

NAME

chat- automated conversational script with a modem

SYNOPSIS

chat [[options]] script

DESCRIPTION

chat is a target utility.

chat defines a conversational exchange between the computer and the modem. Its primary purpose is to establish the connection between the Point-to-Point Protocol daemon (pppd) and a remote pppd process.

OPTIONS

chat takes the following options:

-e: Start with the echo option turned on. Echoing may also be turned on or off at specific points in the chat script by using the ECHO keyword. When echoing is enabled, all output from the modem is echoed to stderr.
-f chat_file: Read the chat script from chat_file. If you use this option, then you cannot use script parameters as well. The user must have read access to the file. Multiple lines are permitted in the file. Spaces and horizontal tab characters are used to separate the strings.
-r report_file: Set the file for output of the report strings. If you use the keyword REPORT, the resulting strings are written to this file. If this option is not used and you still use the keyword REPORT, report strings are written to stderr.
-S: Do not use syslog(). By default, error messages are sent to syslog(). Using -S prevents both log messages from -v and error messages from being sent to syslog().
-s: Use stderr. All log messages from -v and all error messages are sent to stderr.
-t timeout: Set the timeout for the expected string to be received. If the string is not received within the time limit set by timeout, then the reply string is not sent. An alternate reply may be sent or the script will fail if no alternate reply string is available. Script failure causes chat to terminate with a non-zero error code.
-V: Request that the chat script be executed in stderr verbose mode. In stderr verbose mode chat logs the all text received from the modem, and the output strings sent to the modem, to stderr. stderr is usually the local console where chat or pppd is running.
-v: Request that the chat script be executed in verbose mode. In verbose mode chat logs the execution state of the chat script as well as all text received from the modem and the output strings sent to the modem. The default is to log through syslog(). The logging method may be altered using the -S and -s options. Logging is done to the local2 facility at the info level for verbose tracking and the err level for errors only.
script: If the script is not specified in a file with the -f option, then the script is included as parameters to chat.

CHAT SCRIPT

The chat script defines the communications.

A script consists of one or more expect-send pairs of strings, separated by spaces, with an optional subexpect-subsend string pair, separated by a dash, as in the following example:

ogin:-BREAK-ogin: ppp ssword: hello2u2

This line indicates that chat should expect the string ogin:. If it fails to receive a login prompt within the time interval allotted, it is to send a break sequence to the remote process and then expect the string ogin:. If the first ogin: is received then the break sequence is not generated.

Once chat receives the login prompt, it sends the string ppp and then expects the prompt ssword:. When chat receives the prompt for the password, it sends the password hello2u2.

A carriage return is normally sent following the reply string. It is not expected in the expect string unless it is specifically requested using the \r character sequence.

The expect sequence should contain only what is needed to identify the string. Since the script is normally stored in a file on disk, it should not contain variable information. It is not generally acceptable to look for time strings, network identification strings, or other variable pieces of data as an expect string.

A very simple script might look like this:

ogin: ppp ssword: hello2u2

In other words, expect ...ogin:, send ppp, expect ...ssword:, send hello2u2.

In actual practice, simple scripts are rare. At the very least, you should include sub-expect sequences to handle cases where the original string is not received. For example, consider the following script:

ogin:--ogin: ppp ssword: hello2u2

This would be a better script that the simple one shown above. This script would look for the same login: prompt. However, if the prompt were not received, a single return sequence is sent, and then the chat would look for login: again. If line noise obscures the first login prompt, then sending the empty line usually generates a login prompt again.

COMMENTS

Comments can be embedded in the chat script. A comment is a line starting with the # character in column 1. chat ignores comment lines. If a # is expected as the first character of the expect sequence, then you must quote the expect string. If you want to wait for a prompt that starts with the # character, then you must write something like this:

# Now wait for the prompt and send the logout string
'# ' logout

ABORT STRINGS

Many modems report the status of a call as a string. Such strings may be CONNECTED, NO CARRIER, or BUSY. It is often desirable to terminate the script if the modem fails to connect to the remote process. The difficulty is that a script does not know exactly which modem string it may receive. On one attempt, it may receive BUSY while the next time it may receive NO CARRIER.

Such ABORT strings may be specified in the script using the ABORT sequence. An ABORT sequence is written in the script as in the following example:

ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT

This sequence causes chat to expect nothing. chat then sends the string ATZ. The expected response is the string OK. When it receives OK, chat sends the modem ATDT5551212, telling it to dial the telephone. The expected string is CONNECT. If the string CONNECT is received, then the remainder of the script is executed. However, if the modem reaches a busy telephone, then it sends the string BUSY, causing the string to match the abort character sequence. The script then fails because it finds a match to the abort string. The string NO CARRIER causes it to abort for the same reason. Either string may be received. Either string terminates the chat script.

CLR_ABORT STRINGS

CLR_ABORT makes it possible to clear previously set ABORT strings. ABORT strings are kept in an array of pre-determined size (size is determined at compilation time). CLR_ABORT reclaims the space so that new strings can use it.

SAY STRINGS

SAY strings allow the script to send strings to the user at the terminal via stderr. If chat is being run by pppd, and if pppd is running as a daemon detached from its controlling terminal, then stderr is normally redirected to the file /etc/ppp/connect-errors.

SAY strings must be enclosed in single or double quotes. If carriage return and line feed characters are needed as output in the string, you must explicitly add them to the string.

SAY strings may be used to provide progress messages in sections of the script where you want to have ECHO OFF but still let the user know what is happening. An example is:

ABORT           BUSY
ECHO            OFF
SAY             "Dialing your ISP...\n"
''              ATDT5551212
TIMEOUT         120
SAY             "Waiting up to two minutes for connection...\n"
CONNECT         ''
SAY             "Connected. Now logging in...\n"
ogin:           account
ssword:         pass
SAY             "Logged in OK..."

The above example only presents the SAY strings to the user. All the details of the script remain hidden. For example, if the above script works, then the user sees:

Dialing your ISP...
Waiting up to two minutes for connection...
Connected. Now logging in...
Logged in OK...

REPORT STRINGS

REPORT strings are similar to ABORT strings. The difference is that the strings and all characters until the next control character, such as a carriage return, are written to a report file.

REPORT strings may be used to isolate the transmission rate of the modem's connect string and return the value to the chat user. Analysis of the REPORT string occurs in conjunction with other string processing such as looking for the expect string. The use of the same string for a report and abort sequence is not useful. However, it is possible.

REPORT strings do not change the completion code of the program.

REPORT strings may be specified in the script using the REPORT sequence. A REPORT sequence is written in the script as in the following example:

REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account

The above sequence expects nothing. It causes chat to send the modem ATDT5551212, telling it to dial the telephone. The expected string is CONNECT. If CONNECT is received, then the remainder of the script is executed. In addition, the program writes the string CONNECT and any characters which follow it, such as the connection rate, to the expect file.

CLR_REPORT STRINGS

CLR_REPORT makes it possible to clear previously set REPORT strings. REPORT strings are kept in an array of pre-determined size (size determined at compilation time). CLR_REPORT reclaims the space so that new strings can use it.

ECHO

The ECHO option controls whether the output from the modem is echoed to stderr. This option may be set using -e, but it can also be controlled using the ECHO keyword. The expect-send pair ECHO ON enables echoing, and ECHO OFF disables it. Using the ECHO keyword, you can select which parts of the conversation should be visible. For example, with the following script:

ABORT           BUSY
ABORT           'NO CARRIER'
OK\r\n          ATDT5551212
\r\n            \c
ECHO     	ON
CONNECT  	\c
ogin:    	account

all output resulting from modem configuration and dialing remains hidden. However, starting with the CONNECT or BUSY message, everything is echoed.

HANGUP

The HANGUP option controls whether a modem hang up should be considered an error. This option is useful in scripts for dialing systems which hang up and call your system back. The HANGUP option can be ON or OFF.

When HANGUP is set to OFF and the modem hangs up. for example, after the first stage of logging in to a callback system, chat continues running the script. An example of this is: expecting the incoming call and second stage login prompt. As soon as the incoming call is connected, you must use HANGUP ON to reinstate normal hang up signal behavior. Below is an example script:

ABORT                 BUSY
OK\r\n                ATDT5551212
\r\n                  \c
CONNECT               \c
'Callback login:'     call_back_ID
HANGUP                OFF
ABORT                 "Bad Login"
'Callback password:'  call_back_password
TIMEOUT               120
CONNECT               \c
HANGUP                ON
ABORT                 'NO CARRIER'
ogin:--BREAK--ogin:   real_account

TIMEOUT

The initial timeout value is 45 seconds. This may be changed using the -t option.

To change the timeout value for the next expect string, the following example may be used:

ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 ssword: hello2u2

The above example changes the timeout to 10 seconds, during which the login prompt is expected. The timeout is then changed to five seconds, during which the password prompt is expected.

The timeout, once changed, remains in effect until it is changed again.

SENDING EOT

The special reply string EOT indicates that chat should send an EOT character to the remote process. The EOT character is normally the end-of-file character sequence. No return character is sent following the EOT. The EOT sequence can be embedded in the send string using the sequence ^D.

GENERATING BREAK

The special reply string BREAK causes a break condition to be sent. BREAK indicates a special signal on the transmitter. The normal processing on the receiver is to change the transmission rate. BREAK may be used to cycle through the available transmission rates on the remote until you are able to receive a valid login prompt. The break sequence may be embedded in the send string using the \K sequence.

ESCAPE SEQUENCES

The expect and reply strings may contain escape sequences. All escape sequences are legal in the reply string. Many are legal in the expect string. Those that are not valid in the expect sequence are so indicated.

'': Expect or send a null string. If you send a null string then the return character is also sent. This sequence may be either a pair of apostrophes or quote characters.
\\: Expect or send a backslash character.
\b: Expect or send a backspace character.
\c: Suppress the newline at the end of the reply string. This is the only way to send a string without a trailing return character. \c must be at the end of the send string. For example, the sequence hello\c simply sends the characters h, e, l, l, o. (Not valid in expect sequences.)
\d: Delay for one second. chat uses threadDelay. (Not valid in expect sequences.)
\ddd: Collapse the octal digits ddd to a single ASCII character, and send that character. (Some characters are not valid in expect sequences.)
\K: Insert a BREAK. (Not valid in expect sequences.)
\N: Send a null character. The same sequence may also be written as \0. (Not valid in expect sequences.)
\n: Send a newline or linefeed character. (Not valid in expect sequences.)
\p: Pause for one-tenth of a second. (Not valid in expect sequences.)
\q: Suppress writing the string to syslogd. The string is written to the log in its place. (Not valid in expect sequences.)
\r: Expect or send a carriage return.
\s: Expect or send a space character. This may be used when it is not desirable to quote the strings that contain spaces. For example, 'HI SCOTT' and HI\sSCOTT are equivalent.
\t: Expect or send a tab character.
^C: Substitute the sequence with the control character represented by C. For example, the character DC1 (17) is shown as ^Q. (Some characters are not valid in expect sequences.)

TERMINATION CODES

chat terminates with the following completion codes:

0: The normal termination of the program. This indicates that the script was executed without error to the normal conclusion.
1: One or more of the parameters are invalid, or an expect string was too large for the internal buffers. This indicates that the program was not properly executed.
2: An error occurred during the execution of the program. This may be due to a read or write operation failing for some reason, or to chat receiving a signal such as SIGINT.
3: A timeout event occurred when there was an expect string without a subsend string. This may mean that you did not program the script correctly for the condition or that some unexpected event has occurred and the expected string could not be found.
4: The first string marked as an ABORT condition occurred.
5: The second string marked as an ABORT condition occurred.
6: The third string marked as an ABORT condition occurred.
7: The fourth string marked as an ABORT condition occurred.
...: Other termination codes indicate the occurrence of strings marked as ABORT conditions.

Using the termination code, it is possible to determine which event terminated the script. It is possible to determine, for example, if the string received from the modem was BUSY as opposed to 'NO DIAL TONE'.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving