.\" -*- nroff -*-
.\" manual page [] for chat 1.8
-.\" $Id: chat.8,v 1.5 1997/07/14 03:49:41 paulus Exp $
+.\" $Id: chat.8,v 1.11 2004/11/13 12:22:49 paulus Exp $
.\" SH section heading
.\" SS subsection heading
.\" LP paragraph
.\" IP indented paragraph
.\" TP hanging label
-.TH CHAT 8 "5 May 1995" "Chat Version 1.9"
+.TH CHAT 8 "22 May 1999" "Chat Version 1.22"
.SH NAME
chat \- Automated conversational script with a modem
.SH SYNOPSIS
the remote's \fIpppd\fR process.
.SH OPTIONS
.TP
-.B -f \fI<chat file>
+.B \-f \fI<chat file>
Read the chat script from the chat \fIfile\fR. The use of this option
is mutually exclusive with the chat script parameters. The user must
have read access to the file. Multiple lines are permitted in the
file. Space or horizontal tab characters should be used to separate
the strings.
.TP
-.B -t \fI<timeout>
+.B \-t \fI<timeout>
Set the timeout for the expected string to be received. If the string
is not received within the time limit then the reply string is not
sent. An alternate reply may be sent or the script will fail if there
is no alternate reply string. A failed script will cause the
\fIchat\fR program to terminate with a non-zero error code.
.TP
-.B -r \fI<report file>
+.B \-r \fI<report file>
Set the file for output of the report strings. If you use the keyword
\fIREPORT\fR, the resulting strings are written to this file. If this
option is not used and you still use \fIREPORT\fR keywords, the
\fIstderr\fR file is used for the report strings.
.TP
-.B -e
+.B \-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 \fIECHO\fR
keyword. When echoing is enabled, all output from the modem is echoed
to \fIstderr\fR.
.TP
-.B -v
+.B \-E
+Enables environment variable substitution within chat scripts using the
+standard \fI$xxx\fR syntax.
+.TP
+.B \-v
Request that the \fIchat\fR script be executed in a verbose mode. The
-\fIchat\fR program will then log all text received from the modem and
-the output strings which it sends to the SYSLOG.
+\fIchat\fR program will then log 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 the SYSLOG;
+the logging method may be altered with the \-S and \-s flags.
.TP
-.B -V
+.B \-V
Request that the \fIchat\fR script be executed in a stderr verbose
mode. The \fIchat\fR program will then log all text received from the
-modem and the output strings which it sends to the stderr device. This
+modem and the output strings sent to the modem to the stderr device. This
device is usually the local console at the station running the chat or
-pppd program. This option will not work properly if the stderr is
-redirected to the /dev/null location as is the case should pppd be run
-in the 'detached' mode. In that case, use the '-v' option to record
-the session on the SYSLOG device.
+pppd program.
+.TP
+.B \-s
+Use stderr. All log messages from '\-v' and all error messages will be
+sent to stderr.
+.TP
+.B \-S
+Do not use the SYSLOG. By default, error messages are sent to the
+SYSLOG. The use of \-S will prevent both log messages from '\-v' and
+error messages from being sent to the SYSLOG.
+.TP
+.B \-T \fI<phone number>
+Pass in an arbitrary string, usually a phone number, that will be
+substituted for the \eT substitution metacharacter in a send string.
+.TP
+.B \-U \fI<phone number 2>
+Pass in a second string, usually a phone number, that will be
+substituted for the \eU substitution metacharacter in a send string.
+This is useful when dialing an ISDN terminal adapter that requires two
+numbers.
.TP
.B script
-If the script is not specified in a file with the \fI-f\fR option then
+If the script is not specified in a file with the \fI\-f\fR option then
the script is included as parameters to the \fIchat\fR program.
.SH CHAT SCRIPT
.LP
The \fIchat\fR script defines the communications.
.LP
-A script consists of one or more "expect-send" pairs of strings,
-separated by spaces, with an optional "subexpect-subsend" string pair,
+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:
.IP
-ogin:-BREAK-ogin: ppp ssword: hello2u2
+ogin:\-BREAK\-ogin: ppp ssword: hello2u2
.LP
This line indicates that the \fIchat\fR program should expect the string
"ogin:". If it fails to receive a login prompt within the time interval
.LP
A carriage return is normally sent following the reply string. It is not
expected in the "expect" string unless it is specifically requested by using
-the \\r character sequence.
+the \er character sequence.
.LP
The expect sequence should contain only what is needed to identify the
string. Since it is normally stored on a disk file, it should not contain
should include sub-expect sequences should the original string not be
received. For example, consider the following script:
.IP
-ogin:--ogin: ppp ssword: hello2u2
+ogin:\-\-ogin: ppp ssword: hello2u2
.LP
This would be a better script than the simple one used earlier. This would look
for the same login: prompt, however, if one was not received, a single
.IP
# Now wait for the prompt and send logout string
.br
-\'# ' logout
+\&'# ' logout
+.LP
+
+.SH SENDING DATA FROM A FILE
+If the string to send starts with an at sign (@), the rest of the
+string is taken to be the name of a file to read to get the string to
+send. If the last character of the data read is a newline, it is
+removed. The file can be a named pipe (or fifo) instead of a regular
+file. This provides a way for \fBchat\fR to communicate with another
+program, for example, a program to prompt the user and receive a
+password typed in.
.LP
.SH ABORT STRINGS
at the terminal via standard error. If \fBchat\fR is being run by
pppd, and pppd is running as a daemon (detached from its controlling
terminal), standard error will normally be redirected to the file
-/etc/ppp/connect-errors.
+/etc/ppp/connect\-errors.
.LP
\fBSAY\fR strings must be enclosed in single or double quotes. If
carriage return and line feed are needed in the string to be output,
-you must explicitely add them to your string.
+you must explicitly add them to your string.
.LP
The SAY strings could be used to give progress messages in sections of
the script where you want to have 'ECHO OFF' but still let the user
.br
ECHO OFF
.br
-SAY "Dialling your ISP...\\n"
+SAY "Dialling your ISP...\en"
.br
-\'' ATDT5551212
+\&'' ATDT5551212
.br
TIMEOUT 120
.br
.br
CONNECT ''
.br
-SAY "Connected, now logging in ...\n"
+SAY "Connected, now logging in ...\en"
.br
ogin: account
.br
ssword: pass
.br
-$ \c
-SAY "Logged in OK ...\n"
+$ \ec
+.br
+SAY "Logged in OK ...\en"
\fIetc ...\fR
.LP
This sequence will only present the SAY strings to the user and all
ATDT5551212 to dial the telephone. The expected string is
\fICONNECT\fR. If the string \fICONNECT\fR is received the remainder
of the script is executed. In addition the program will write to the
-expect-file the string "CONNECT" plus any characters which follow it
+expect\-file the string "CONNECT" plus any characters which follow it
such as the connection rate.
.SH CLR_REPORT STRINGS
This sequence allows for clearing previously set \fBREPORT\fR strings.
entries so that new strings can use that space.
.SH ECHO
The echo options controls whether the output from the modem is echoed
-to \fIstderr\fR. This option may be set with the \fI-e\fR option, but
-it can also be controlled by the \fIECHO\fR keyword. The "expect-send"
+to \fIstderr\fR. This option may be set with the \fI\-e\fR option, but
+it can also be controlled by the \fIECHO\fR keyword. The "expect\-send"
pair \fIECHO\fR \fION\fR enables echoing, and \fIECHO\fR \fIOFF\fR
disables it. With this keyword you can select which parts of the
conversation should be visible. For instance, with the following
.br
ABORT 'NO CARRIER'
.br
-'' ATZ
+\&'' ATZ
.br
-OK\\r\\n ATD1234567
+OK\er\en ATD1234567
.br
-\\r\\n \\c
+\er\en \ec
.br
ECHO ON
.br
-CONNECT \\c
+CONNECT \ec
.br
ogin: account
.LP
.IP
ABORT 'BUSY'
.br
-'' ATZ
+\&'' ATZ
.br
-OK\\r\\n ATD1234567
+OK\er\en ATD1234567
.br
-\\r\\n \\c
+\er\en \ec
.br
-CONNECT \\c
+CONNECT \ec
.br
-\'Callback login:' call_back_ID
+\&'Callback login:' call_back_ID
.br
HANGUP OFF
.br
ABORT "Bad Login"
.br
-\'Callback Password:' Call_back_password
+\&'Callback Password:' Call_back_password
.br
TIMEOUT 120
.br
-CONNECT \\c
+CONNECT \ec
.br
HANGUP ON
.br
ABORT "NO CARRIER"
.br
-ogin:--BREAK--ogin: real_account
+ogin:\-\-BREAK\-\-ogin: real_account
.br
\fIetc ...\fR
.LP
.SH TIMEOUT
-The initial timeout value is 45 seconds. This may be changed using the \fB-t\fR
+The initial timeout value is 45 seconds. This may be changed using the \fB\-t\fR
parameter.
.LP
To change the timeout value for the next expect string, the following
example may be used:
.IP
-ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2
+ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:\-\-ogin: TIMEOUT 5 assword: hello2u2
.LP
This will change the timeout to 10 seconds when it expects the login:
prompt. The timeout is then changed to 5 seconds when it looks for the
should send an EOT character to the remote. This is normally the
End-of-file character sequence. A return character is not sent
following the EOT.
-.PR
The EOT sequence may be embedded into the send string using the
sequence \fI^D\fR.
.SH GENERATING BREAK
normal processing on the receiver is to change the transmission rate.
It may be used to cycle through the available transmission rates on
the remote until you are able to receive a valid login prompt.
-.PR
The break sequence may be embedded into the send string using the
-\fI\\K\fR sequence.
+\fI\eK\fR sequence.
.SH ESCAPE SEQUENCES
The expect and reply strings may contain escape sequences. All of the
sequences are legal in the reply string. Many are legal in the expect.
send the return character. This sequence may either be a pair of apostrophe
or quote characters.
.TP
-.B \\\\b
+.B \eb
represents a backspace character.
.TP
-.B \\\\c
+.B \ec
Suppresses the newline at the end of the reply string. This is the only
method to send a string without a trailing return character. It must
be at the end of the send string. For example,
-the sequence hello\\c will simply send the characters h, e, l, l, o.
+the sequence hello\ec will simply send the characters h, e, l, l, o.
.I (not valid in expect.)
.TP
-.B \\\\d
+.B \ed
Delay for one second. The program uses sleep(1) which will delay to a
maximum of one second.
.I (not valid in expect.)
.TP
-.B \\\\K
+.B \eK
Insert a BREAK
.I (not valid in expect.)
.TP
-.B \\\\n
+.B \en
Send a newline or linefeed character.
.TP
-.B \\\\N
-Send a null character. The same sequence may be represented by \\0.
+.B \eN
+Send a null character. The same sequence may be represented by \e0.
.I (not valid in expect.)
.TP
-.B \\\\p
+.B \ep
Pause for a fraction of a second. The delay is 1/10th of a second.
.I (not valid in expect.)
.TP
-.B \\\\q
+.B \eq
Suppress writing the string to the SYSLOG file. The string ?????? is
written to the log in its place.
.I (not valid in expect.)
.TP
-.B \\\\r
+.B \er
Send or expect a carriage return.
.TP
-.B \\\\s
+.B \es
Represents a space character in the string. This may be used when it
is not desirable to quote the strings which contains spaces. The
-sequence 'HI TIM' and HI\\sTIM are the same.
+sequence 'HI TIM' and HI\esTIM are the same.
.TP
-.B \\\\t
+.B \et
Send or expect a tab character.
.TP
-.B \\\\\\\\
+.B \eT
+Send the phone number string as specified with the \fI\-T\fR option
+.I (not valid in expect.)
+.TP
+.B \eU
+Send the phone number 2 string as specified with the \fI\-U\fR option
+.I (not valid in expect.)
+.TP
+.B \e\e
Send or expect a backslash character.
.TP
-.B \\\\ddd
+.B \eddd
Collapse the octal digits (ddd) into a single ASCII character and send that
character.
.I (some characters are not valid in expect.)
Substitute the sequence with the control character represented by C.
For example, the character DC1 (17) is shown as \^^Q.
.I (some characters are not valid in expect.)
+.SH ENVIRONMENT VARIABLES
+Environment variables are available within chat scripts, if the \fI\-E\fR
+option was specified in the command line. The metacharacter \fI$\fR is used
+to introduce the name of the environment variable to substitute. If the
+substitution fails, because the requested environment variable is not set,
+\fInothing\fR is replaced for the variable.
.SH TERMINATION CODES
The \fIchat\fR program will terminate with the following completion
codes.
.TP
.B 3
A timeout event occurred when there was an \fIexpect\fR string without
-having a "-subsend" string. This may mean that you did not program the
+having 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.
.TP
projects / ppp.git / blobdiff