Mon May 4 19:52:34 2009 UTC ()
New sentence, new line.


(wiz)
diff -r1.3 -r1.4 src/dist/pppd/chat/chat.8

cvs diff -r1.3 -r1.4 src/dist/pppd/chat/Attic/chat.8 (expand / switch to unified diff)

--- src/dist/pppd/chat/Attic/chat.8 2007/07/18 18:36:57 1.3
+++ src/dist/pppd/chat/Attic/chat.8 2009/05/04 19:52:34 1.4
@@ -1,333 +1,387 @@ @@ -1,333 +1,387 @@
1.\" $NetBSD: chat.8,v 1.3 2007/07/18 18:36:57 christos Exp $ 1.\" $NetBSD: chat.8,v 1.4 2009/05/04 19:52:34 wiz Exp $
2.\" 2.\"
3.\" -*- nroff -*- 3.\" -*- nroff -*-
4.\" manual page [] for chat 1.8 4.\" manual page [] for chat 1.8
5.\" Id: chat.8,v 1.11 2004/11/13 12:22:49 paulus Exp 5.\" Id: chat.8,v 1.11 2004/11/13 12:22:49 paulus Exp
6.\" SH section heading 6.\" SH section heading
7.\" SS subsection heading 7.\" SS subsection heading
8.\" LP paragraph 8.\" LP paragraph
9.\" IP indented paragraph 9.\" IP indented paragraph
10.\" TP hanging label 10.\" TP hanging label
11.TH CHAT 8 "22 May 1999" "Chat Version 1.22" 11.TH CHAT 8 "22 May 1999" "Chat Version 1.22"
12.SH NAME 12.SH NAME
13chat \- Automated conversational script with a modem 13chat \- Automated conversational script with a modem
14.SH SYNOPSIS 14.SH SYNOPSIS
15.B chat 15.B chat
16[ 16[
17.I options 17.I options
18] 18]
19.I script 19.I script
20.SH DESCRIPTION 20.SH DESCRIPTION
21.LP 21.LP
22The \fIchat\fR program defines a conversational exchange between the 22The \fIchat\fR program defines a conversational exchange between the
23computer and the modem. Its primary purpose is to establish the 23computer and the modem.
 24Its primary purpose is to establish the
24connection between the Point-to-Point Protocol Daemon (\fIpppd\fR) and 25connection between the Point-to-Point Protocol Daemon (\fIpppd\fR) and
25the remote's \fIpppd\fR process. 26the remote's \fIpppd\fR process.
26.SH OPTIONS 27.SH OPTIONS
27.TP 28.TP
28.B \-f \fI\*[Lt]chat file\*[Gt] 29.B \-f \fI\*[Lt]chat file\*[Gt]
29Read the chat script from the chat \fIfile\fR. The use of this option 30Read the chat script from the chat \fIfile\fR.
30is mutually exclusive with the chat script parameters. The user must 31The use of this option
31have read access to the file. Multiple lines are permitted in the 32is mutually exclusive with the chat script parameters.
32file. Space or horizontal tab characters should be used to separate 33The user must have read access to the file.
 34Multiple lines are permitted in the file.
 35Space or horizontal tab characters should be used to separate
33the strings. 36the strings.
34.TP 37.TP
35.B \-t \fI\*[Lt]timeout\*[Gt] 38.B \-t \fI\*[Lt]timeout\*[Gt]
36Set the timeout for the expected string to be received. If the string 39Set the timeout for the expected string to be received.
 40If the string
37is not received within the time limit then the reply string is not 41is not received within the time limit then the reply string is not
38sent. An alternate reply may be sent or the script will fail if there 42sent.
39is no alternate reply string. A failed script will cause the 43An alternate reply may be sent or the script will fail if there
 44is no alternate reply string.
 45A failed script will cause the
40\fIchat\fR program to terminate with a non-zero error code. 46\fIchat\fR program to terminate with a non-zero error code.
41.TP 47.TP
42.B \-r \fI\*[Lt]report file\*[Gt] 48.B \-r \fI\*[Lt]report file\*[Gt]
43Set the file for output of the report strings. If you use the keyword 49Set the file for output of the report strings.
44\fIREPORT\fR, the resulting strings are written to this file. If this 50If you use the keyword
 51\fIREPORT\fR, the resulting strings are written to this file.
 52If this
45option is not used and you still use \fIREPORT\fR keywords, the 53option is not used and you still use \fIREPORT\fR keywords, the
46\fIstderr\fR file is used for the report strings. 54\fIstderr\fR file is used for the report strings.
47.TP 55.TP
48.B \-e 56.B \-e
49Start with the echo option turned on. Echoing may also be turned on 57Start with the echo option turned on.
 58Echoing may also be turned on
50or off at specific points in the chat script by using the \fIECHO\fR 59or off at specific points in the chat script by using the \fIECHO\fR
51keyword. When echoing is enabled, all output from the modem is echoed 60keyword.
 61When echoing is enabled, all output from the modem is echoed
52to \fIstderr\fR. 62to \fIstderr\fR.
53.TP 63.TP
54.B \-E 64.B \-E
55Enables environment variable substitution within chat scripts using the 65Enables environment variable substitution within chat scripts using the
56standard \fI$xxx\fR syntax. 66standard \fI$xxx\fR syntax.
57.TP 67.TP
58.B \-v 68.B \-v
59Request that the \fIchat\fR script be executed in a verbose mode. The 69Request that the \fIchat\fR script be executed in a verbose mode.
 70The
60\fIchat\fR program will then log the execution state of the chat 71\fIchat\fR program will then log the execution state of the chat
61script as well as all text received from the modem and the output 72script as well as all text received from the modem and the output
62strings sent to the modem. The default is to log through the SYSLOG; 73strings sent to the modem.
63the logging method may be altered with the \-S and \-s flags. SYSLOGs 74The default is to log through the SYSLOG;
64are logged to facility LOG_LOCAL2. 75the logging method may be altered with the \-S and \-s flags.
 76SYSLOGs are logged to facility LOG_LOCAL2.
65.TP 77.TP
66.B \-V 78.B \-V
67Request that the \fIchat\fR script be executed in a stderr verbose 79Request that the \fIchat\fR script be executed in a stderr verbose
68mode. The \fIchat\fR program will then log all text received from the 80mode.
69modem and the output strings sent to the modem to the stderr device. This 81The \fIchat\fR program will then log all text received from the
70device is usually the local console at the station running the chat or 82modem and the output strings sent to the modem to the stderr device.
 83This device is usually the local console at the station running the chat or
71pppd program. 84pppd program.
72.TP 85.TP
73.B \-s 86.B \-s
74Use stderr. All log messages from '\-v' and all error messages will be 87Use stderr.
 88All log messages from '\-v' and all error messages will be
75sent to stderr. 89sent to stderr.
76.TP 90.TP
77.B \-S 91.B \-S
78Do not use the SYSLOG. By default, error messages are sent to the 92Do not use the SYSLOG.
79SYSLOG. The use of \-S will prevent both log messages from '\-v' and 93By default, error messages are sent to the SYSLOG.
 94The use of \-S will prevent both log messages from '\-v' and
80error messages from being sent to the SYSLOG (to facility LOG_LOCAL2). 95error messages from being sent to the SYSLOG (to facility LOG_LOCAL2).
81.TP 96.TP
82.B \-T \fI\*[Lt]phone number\*[Gt] 97.B \-T \fI\*[Lt]phone number\*[Gt]
83Pass in an arbitrary string, usually a phone number, that will be 98Pass in an arbitrary string, usually a phone number, that will be
84substituted for the \\T substitution metacharacter in a send string. 99substituted for the \\T substitution metacharacter in a send string.
85.TP 100.TP
86.B \-U \fI\*[Lt]phone number 2\*[Gt] 101.B \-U \fI\*[Lt]phone number 2\*[Gt]
87Pass in a second string, usually a phone number, that will be 102Pass in a second string, usually a phone number, that will be
88substituted for the \\U substitution metacharacter in a send string. 103substituted for the \\U substitution metacharacter in a send string.
89This is useful when dialing an ISDN terminal adapter that requires two 104This is useful when dialing an ISDN terminal adapter that requires two
90numbers. 105numbers.
91.TP 106.TP
92.B script 107.B script
93If the script is not specified in a file with the \fI\-f\fR option then 108If the script is not specified in a file with the \fI\-f\fR option then
94the script is included as parameters to the \fIchat\fR program. 109the script is included as parameters to the \fIchat\fR program.
95.SH CHAT SCRIPT 110.SH CHAT SCRIPT
96.LP 111.LP
97The \fIchat\fR script defines the communications. 112The \fIchat\fR script defines the communications.
98.LP 113.LP
99A script consists of one or more "expect\-send" pairs of strings, 114A script consists of one or more "expect\-send" pairs of strings,
100separated by spaces, with an optional "subexpect\-subsend" string pair, 115separated by spaces, with an optional "subexpect\-subsend" string pair,
101separated by a dash as in the following example: 116separated by a dash as in the following example:
102.IP 117.IP
103ogin:\-BREAK\-ogin: ppp ssword: hello2u2 118ogin:\-BREAK\-ogin: ppp ssword: hello2u2
104.LP 119.LP
105This line indicates that the \fIchat\fR program should expect the string 120This line indicates that the \fIchat\fR program should expect the string
106"ogin:". If it fails to receive a login prompt within the time interval 121"ogin:".
 122If it fails to receive a login prompt within the time interval
107allotted, it is to send a break sequence to the remote and then expect the 123allotted, it is to send a break sequence to the remote and then expect the
108string "ogin:". If the first "ogin:" is received then the break sequence is 124string "ogin:".
 125If the first "ogin:" is received then the break sequence is
109not generated. 126not generated.
110.LP 127.LP
111Once it received the login prompt the \fIchat\fR program will send the 128Once it received the login prompt the \fIchat\fR program will send the
112string ppp and then expect the prompt "ssword:". When it receives the 129string ppp and then expect the prompt "ssword:".
 130When it receives the
113prompt for the password, it will send the password hello2u2. 131prompt for the password, it will send the password hello2u2.
114.LP 132.LP
115A carriage return is normally sent following the reply string. It is not 133A carriage return is normally sent following the reply string.
 134It is not
116expected in the "expect" string unless it is specifically requested by using 135expected in the "expect" string unless it is specifically requested by using
117the \\r character sequence. 136the \\r character sequence.
118.LP 137.LP
119The expect sequence should contain only what is needed to identify the 138The expect sequence should contain only what is needed to identify the
120string. Since it is normally stored on a disk file, it should not contain 139string.
121variable information. It is generally not acceptable to look for time 140Since it is normally stored on a disk file, it should not contain
 141variable information.
 142It is generally not acceptable to look for time
122strings, network identification strings, or other variable pieces of data as 143strings, network identification strings, or other variable pieces of data as
123an expect string. 144an expect string.
124.LP 145.LP
125To help correct for characters which may be corrupted during the initial 146To help correct for characters which may be corrupted during the initial
126sequence, look for the string "ogin:" rather than "login:". It is possible 147sequence, look for the string "ogin:" rather than "login:".
 148It is possible
127that the leading "l" character may be received in error and you may never 149that the leading "l" character may be received in error and you may never
128find the string even though it was sent by the system. For this reason, 150find the string even though it was sent by the system.
 151For this reason,
129scripts look for "ogin:" rather than "login:" and "ssword:" rather than 152scripts look for "ogin:" rather than "login:" and "ssword:" rather than
130"password:". 153"password:".
131.LP 154.LP
132A very simple script might look like this: 155A very simple script might look like this:
133.IP 156.IP
134ogin: ppp ssword: hello2u2 157ogin: ppp ssword: hello2u2
135.LP 158.LP
136In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2. 159In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2.
137.LP 160.LP
138In actual practice, simple scripts are rare. At the vary least, you 161In actual practice, simple scripts are rare.
 162At the vary least, you
139should include sub-expect sequences should the original string not be 163should include sub-expect sequences should the original string not be
140received. For example, consider the following script: 164received.
 165For example, consider the following script:
141.IP 166.IP
142ogin:\-\-ogin: ppp ssword: hello2u2 167ogin:\-\-ogin: ppp ssword: hello2u2
143.LP 168.LP
144This would be a better script than the simple one used earlier. This would look 169This would be a better script than the simple one used earlier.
 170This would look
145for the same login: prompt, however, if one was not received, a single 171for the same login: prompt, however, if one was not received, a single
146return sequence is sent and then it will look for login: again. Should line 172return sequence is sent and then it will look for login: again.
 173Should line
147noise obscure the first login prompt then sending the empty line will 174noise obscure the first login prompt then sending the empty line will
148usually generate a login prompt again. 175usually generate a login prompt again.
149.SH COMMENTS 176.SH COMMENTS
150Comments can be embedded in the chat script. A comment is a line which 177Comments can be embedded in the chat script.
151starts with the \fB#\fR (hash) character in column 1. Such comment 178A comment is a line which
152lines are just ignored by the chat program. If a '#' character is to 179starts with the \fB#\fR (hash) character in column 1.
 180Such comment lines are just ignored by the chat program.
 181If a '#' character is to
153be expected as the first character of the expect sequence, you should 182be expected as the first character of the expect sequence, you should
154quote the expect string. 183quote the expect string.
155If you want to wait for a prompt that starts with a # (hash) 184If you want to wait for a prompt that starts with a # (hash)
156character, you would have to write something like this: 185character, you would have to write something like this:
157.IP 186.IP
158# Now wait for the prompt and send logout string 187# Now wait for the prompt and send logout string
159.br 188.br
160\&'# ' logout 189\&'# ' logout
161.LP 190.LP
162 191
163.SH SENDING DATA FROM A FILE 192.SH SENDING DATA FROM A FILE
164If the string to send starts with an at sign (@), the rest of the 193If the string to send starts with an at sign (@), the rest of the
165string is taken to be the name of a file to read to get the string to 194string is taken to be the name of a file to read to get the string to
166send. If the last character of the data read is a newline, it is 195send.
167removed. The file can be a named pipe (or fifo) instead of a regular 196If the last character of the data read is a newline, it is removed.
168file. This provides a way for \fBchat\fR to communicate with another 197The file can be a named pipe (or fifo) instead of a regular file.
 198This provides a way for \fBchat\fR to communicate with another
169program, for example, a program to prompt the user and receive a 199program, for example, a program to prompt the user and receive a
170password typed in. 200password typed in.
171.LP 201.LP
172 202
173.SH ABORT STRINGS 203.SH ABORT STRINGS
174Many modems will report the status of the call as a string. These 204Many modems will report the status of the call as a string.
175strings may be \fBCONNECTED\fR or \fBNO CARRIER\fR or \fBBUSY\fR. It 205These
176is often desirable to terminate the script should the modem fail to 206strings may be \fBCONNECTED\fR or \fBNO CARRIER\fR or \fBBUSY\fR.
177connect to the remote. The difficulty is that a script would not know 207It is often desirable to terminate the script should the modem fail to
178exactly which modem string it may receive. On one attempt, it may 208connect to the remote.
 209The difficulty is that a script would not know
 210exactly which modem string it may receive.
 211On one attempt, it may
179receive \fBBUSY\fR while the next time it may receive \fBNO CARRIER\fR. 212receive \fBBUSY\fR while the next time it may receive \fBNO CARRIER\fR.
180.LP 213.LP
181These "abort" strings may be specified in the script using the \fIABORT\fR 214These "abort" strings may be specified in the script using the \fIABORT\fR
182sequence. It is written in the script as in the following example: 215sequence.
 216It is written in the script as in the following example:
183.IP 217.IP
184ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT 218ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT
185.LP 219.LP
186This sequence will expect nothing; and then send the string ATZ. The 220This sequence will expect nothing; and then send the string ATZ.
187expected response to this is the string \fIOK\fR. When it receives \fIOK\fR, 221The expected response to this is the string \fIOK\fR.
188the string ATDT5551212 to dial the telephone. The expected string is 222When it receives \fIOK\fR,
189\fICONNECT\fR. If the string \fICONNECT\fR is received the remainder of the 223the string ATDT5551212 to dial the telephone.
190script is executed. However, should the modem find a busy telephone, it will 224The expected string is
191send the string \fIBUSY\fR. This will cause the string to match the abort 225\fICONNECT\fR.
192character sequence. The script will then fail because it found a match to 226If the string \fICONNECT\fR is received the remainder of the
193the abort string. If it received the string \fINO CARRIER\fR, it will abort 227script is executed.
194for the same reason. Either string may be received. Either string will 228However, should the modem find a busy telephone, it will
195terminate the \fIchat\fR script. 229send the string \fIBUSY\fR.
 230This will cause the string to match the abort character sequence.
 231The script will then fail because it found a match to the abort string.
 232If it received the string \fINO CARRIER\fR, it will abort
 233for the same reason.
 234Either string may be received.
 235Either string will terminate the \fIchat\fR script.
196.SH CLR_ABORT STRINGS 236.SH CLR_ABORT STRINGS
197This sequence allows for clearing previously set \fBABORT\fR strings. 237This sequence allows for clearing previously set \fBABORT\fR strings.
198\fBABORT\fR strings are kept in an array of a pre-determined size (at 238\fBABORT\fR strings are kept in an array of a pre-determined size (at
199compilation time); \fBCLR_ABORT\fR will reclaim the space for cleared 239compilation time); \fBCLR_ABORT\fR will reclaim the space for cleared
200entries so that new strings can use that space. 240entries so that new strings can use that space.
201.SH SAY STRINGS 241.SH SAY STRINGS
202The \fBSAY\fR directive allows the script to send strings to the user 242The \fBSAY\fR directive allows the script to send strings to the user
203at the terminal via standard error. If \fBchat\fR is being run by 243at the terminal via standard error.
 244If \fBchat\fR is being run by
204pppd, and pppd is running as a daemon (detached from its controlling 245pppd, and pppd is running as a daemon (detached from its controlling
205terminal), standard error will normally be redirected to the file 246terminal), standard error will normally be redirected to the file
206/etc/ppp/connect\-errors. 247/etc/ppp/connect\-errors.
207.LP 248.LP
208\fBSAY\fR strings must be enclosed in single or double quotes. If 249\fBSAY\fR strings must be enclosed in single or double quotes.
209carriage return and line feed are needed in the string to be output, 250If carriage return and line feed are needed in the string to be output,
210you must explicitly add them to your string. 251you must explicitly add them to your string.
211.LP 252.LP
212The SAY strings could be used to give progress messages in sections of 253The SAY strings could be used to give progress messages in sections of
213the script where you want to have 'ECHO OFF' but still let the user 254the script where you want to have 'ECHO OFF' but still let the user
214know what is happening. An example is: 255know what is happening.
 256An example is:
215.IP 257.IP
216ABORT BUSY 258ABORT BUSY
217.br 259.br
218ECHO OFF 260ECHO OFF
219.br 261.br
220SAY "Dialing your ISP...\\n" 262SAY "Dialing your ISP...\\n"
221.br 263.br
222\&'' ATDT5551212 264\&'' ATDT5551212
223.br 265.br
224TIMEOUT 120 266TIMEOUT 120
225.br 267.br
226SAY "Waiting up to 2 minutes for connection ... " 268SAY "Waiting up to 2 minutes for connection ... "
227.br 269.br
228CONNECT '' 270CONNECT ''
229.br 271.br
230SAY "Connected, now logging in ...\n" 272SAY "Connected, now logging in ...\n"
231.br 273.br
232ogin: account 274ogin: account
233.br 275.br
234ssword: pass 276ssword: pass
235.br 277.br
236$ \c 278$ \c
237SAY "Logged in OK ...\n" 279SAY "Logged in OK ...\n"
238\fIetc ...\fR 280\fIetc ...\fR
239.LP 281.LP
240This sequence will only present the SAY strings to the user and all 282This sequence will only present the SAY strings to the user and all
241the details of the script will remain hidden. For example, if the 283the details of the script will remain hidden.
242above script works, the user will see: 284For example, if the above script works, the user will see:
243.IP 285.IP
244Dialing your ISP... 286Dialing your ISP...
245.br 287.br
246Waiting up to 2 minutes for connection ... Connected, now logging in ... 288Waiting up to 2 minutes for connection ... Connected, now logging in ...
247.br 289.br
248Logged in OK ... 290Logged in OK ...
249.LP 291.LP
250 292
251.SH REPORT STRINGS 293.SH REPORT STRINGS
252A \fBreport\fR string is similar to the ABORT string. The difference 294A \fBreport\fR string is similar to the ABORT string.
 295The difference
253is that the strings, and all characters to the next control character 296is that the strings, and all characters to the next control character
254such as a carriage return, are written to the report file. 297such as a carriage return, are written to the report file.
255.LP 298.LP
256The report strings may be used to isolate the transmission rate of the 299The report strings may be used to isolate the transmission rate of the
257modem's connect string and return the value to the chat user. The 300modem's connect string and return the value to the chat user.
258analysis of the report string logic occurs in conjunction with the 301The analysis of the report string logic occurs in conjunction with the
259other string processing such as looking for the expect string. The use 302other string processing such as looking for the expect string.
 303The use
260of the same string for a report and abort sequence is probably not 304of the same string for a report and abort sequence is probably not
261very useful, however, it is possible. 305very useful, however, it is possible.
262.LP 306.LP
263The report strings to no change the completion code of the program. 307The report strings to no change the completion code of the program.
264.LP 308.LP
265These "report" strings may be specified in the script using the \fIREPORT\fR 309These "report" strings may be specified in the script using the \fIREPORT\fR
266sequence. It is written in the script as in the following example: 310sequence.
 311It is written in the script as in the following example:
267.IP 312.IP
268REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account 313REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account
269.LP 314.LP
270This sequence will expect nothing; and then send the string 315This sequence will expect nothing; and then send the string
271ATDT5551212 to dial the telephone. The expected string is 316ATDT5551212 to dial the telephone.
272\fICONNECT\fR. If the string \fICONNECT\fR is received the remainder 317The expected string is
273of the script is executed. In addition the program will write to the 318\fICONNECT\fR.
 319If the string \fICONNECT\fR is received the remainder
 320of the script is executed.
 321In addition the program will write to the
274expect\-file the string "CONNECT" plus any characters which follow it 322expect\-file the string "CONNECT" plus any characters which follow it
275such as the connection rate. 323such as the connection rate.
276.SH CLR_REPORT STRINGS 324.SH CLR_REPORT STRINGS
277This sequence allows for clearing previously set \fBREPORT\fR strings. 325This sequence allows for clearing previously set \fBREPORT\fR strings.
278\fBREPORT\fR strings are kept in an array of a pre-determined size (at 326\fBREPORT\fR strings are kept in an array of a pre-determined size (at
279compilation time); \fBCLR_REPORT\fR will reclaim the space for cleared 327compilation time); \fBCLR_REPORT\fR will reclaim the space for cleared
280entries so that new strings can use that space. 328entries so that new strings can use that space.
281.SH ECHO 329.SH ECHO
282The echo options controls whether the output from the modem is echoed 330The echo options controls whether the output from the modem is echoed
283to \fIstderr\fR. This option may be set with the \fI\-e\fR option, but 331to \fIstderr\fR.
284it can also be controlled by the \fIECHO\fR keyword. The "expect\-send" 332This option may be set with the \fI\-e\fR option, but
 333it can also be controlled by the \fIECHO\fR keyword.
 334The "expect\-send"
285pair \fIECHO\fR \fION\fR enables echoing, and \fIECHO\fR \fIOFF\fR 335pair \fIECHO\fR \fION\fR enables echoing, and \fIECHO\fR \fIOFF\fR
286disables it. With this keyword you can select which parts of the 336disables it.
287conversation should be visible. For instance, with the following 337With this keyword you can select which parts of the
288script: 338conversation should be visible.
 339For instance, with the following script:
289.IP 340.IP
290ABORT 'BUSY' 341ABORT 'BUSY'
291.br 342.br
292ABORT 'NO CARRIER' 343ABORT 'NO CARRIER'
293.br 344.br
294'' ATZ 345'' ATZ
295.br 346.br
296OK\\r\\n ATD1234567 347OK\\r\\n ATD1234567
297.br 348.br
298\\r\\n \\c 349\\r\\n \\c
299.br 350.br
300ECHO ON 351ECHO ON
301.br 352.br
302CONNECT \\c 353CONNECT \\c
303.br 354.br
304ogin: account 355ogin: account
305.LP 356.LP
306all output resulting from modem configuration and dialing is not visible, 357all output resulting from modem configuration and dialing is not visible,
307but starting with the \fICONNECT\fR (or \fIBUSY\fR) message, everything 358but starting with the \fICONNECT\fR (or \fIBUSY\fR) message, everything
308will be echoed. 359will be echoed.
309.SH HANGUP 360.SH HANGUP
310The HANGUP options control whether a modem hangup should be considered 361The HANGUP options control whether a modem hangup should be considered
311as an error or not. This option is useful in scripts for dialing 362as an error or not.
312systems which will hang up and call your system back. The HANGUP 363This option is useful in scripts for dialing
313options can be \fBON\fR or \fBOFF\fR. 364systems which will hang up and call your system back.
 365The HANGUP options can be \fBON\fR or \fBOFF\fR.
314.br 366.br
315When HANGUP is set OFF and the modem hangs up (e.g., after the first 367When HANGUP is set OFF and the modem hangs up (e.g., after the first
316stage of logging in to a callback system), \fBchat\fR will continue 368stage of logging in to a callback system), \fBchat\fR will continue
317running the script (e.g., waiting for the incoming call and second 369running the script (e.g., waiting for the incoming call and second
318stage login prompt). As soon as the incoming call is connected, you 370stage login prompt).
 371As soon as the incoming call is connected, you
319should use the \fBHANGUP ON\fR directive to reinstall normal hang up 372should use the \fBHANGUP ON\fR directive to reinstall normal hang up
320signal behavior. Here is an (simple) example script: 373signal behavior.
 374Here is an (simple) example script:
321.IP 375.IP
322ABORT 'BUSY' 376ABORT 'BUSY'
323.br 377.br
324'' ATZ 378'' ATZ
325.br 379.br
326OK\\r\\n ATD1234567 380OK\\r\\n ATD1234567
327.br 381.br
328\\r\\n \\c 382\\r\\n \\c
329.br 383.br
330CONNECT \\c 384CONNECT \\c
331.br 385.br
332\&'Callback login:' call_back_ID 386\&'Callback login:' call_back_ID
333.br 387.br
@@ -340,173 +394,190 @@ ABORT "Bad Login" @@ -340,173 +394,190 @@ ABORT "Bad Login"
340TIMEOUT 120 394TIMEOUT 120
341.br 395.br
342CONNECT \\c 396CONNECT \\c
343.br 397.br
344HANGUP ON 398HANGUP ON
345.br 399.br
346ABORT "NO CARRIER" 400ABORT "NO CARRIER"
347.br 401.br
348ogin:\-\-BREAK\-\-ogin: real_account 402ogin:\-\-BREAK\-\-ogin: real_account
349.br 403.br
350\fIetc ...\fR 404\fIetc ...\fR
351.LP 405.LP
352.SH TIMEOUT 406.SH TIMEOUT
353The initial timeout value is 45 seconds. This may be changed using the \fB\-t\fR 407The initial timeout value is 45 seconds.
354parameter. 408This may be changed using the \fB\-t\fR parameter.
355.LP 409.LP
356To change the timeout value for the next expect string, the following 410To change the timeout value for the next expect string, the following
357example may be used: 411example may be used:
358.IP 412.IP
359ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:\-\-ogin: TIMEOUT 5 assword: hello2u2 413ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:\-\-ogin: TIMEOUT 5 assword: hello2u2
360.LP 414.LP
361This will change the timeout to 10 seconds when it expects the login: 415This will change the timeout to 10 seconds when it expects the login:
362prompt. The timeout is then changed to 5 seconds when it looks for the 416prompt.
 417The timeout is then changed to 5 seconds when it looks for the
363password prompt. 418password prompt.
364.LP 419.LP
365The timeout, once changed, remains in effect until it is changed again. 420The timeout, once changed, remains in effect until it is changed again.
366.SH SENDING EOT 421.SH SENDING EOT
367The special reply string of \fIEOT\fR indicates that the chat program 422The special reply string of \fIEOT\fR indicates that the chat program
368should send an EOT character to the remote. This is normally the 423should send an EOT character to the remote.
369End-of-file character sequence. A return character is not sent 424This is normally the End-of-file character sequence.
370following the EOT. 425A return character is not sent following the EOT.
371.PR 426.PR
372The EOT sequence may be embedded into the send string using the 427The EOT sequence may be embedded into the send string using the
373sequence \fI^D\fR. 428sequence \fI^D\fR.
374.SH GENERATING BREAK 429.SH GENERATING BREAK
375The special reply string of \fIBREAK\fR will cause a break condition 430The special reply string of \fIBREAK\fR will cause a break condition
376to be sent. The break is a special signal on the transmitter. The 431to be sent.
377normal processing on the receiver is to change the transmission rate. 432The break is a special signal on the transmitter.
 433The normal processing on the receiver is to change the transmission rate.
378It may be used to cycle through the available transmission rates on 434It may be used to cycle through the available transmission rates on
379the remote until you are able to receive a valid login prompt. 435the remote until you are able to receive a valid login prompt.
380.PR 436.PR
381The break sequence may be embedded into the send string using the 437The break sequence may be embedded into the send string using the
382\fI\\K\fR sequence. 438\fI\\K\fR sequence.
383.SH ESCAPE SEQUENCES 439.SH ESCAPE SEQUENCES
384The expect and reply strings may contain escape sequences. All of the 440The expect and reply strings may contain escape sequences.
385sequences are legal in the reply string. Many are legal in the expect. 441All of the sequences are legal in the reply string.
 442Many are legal in the expect.
386Those which are not valid in the expect sequence are so indicated. 443Those which are not valid in the expect sequence are so indicated.
387.TP 444.TP
388.B '' 445.B ''
389Expects or sends a null string. If you send a null string then it will still 446Expects or sends a null string.
390send the return character. This sequence may either be a pair of apostrophe 447If you send a null string then it will still send the return character.
391or quote characters. 448This sequence may either be a pair of apostrophe or quote characters.
392.TP 449.TP
393.B \\\\b 450.B \\\\b
394represents a backspace character. 451represents a backspace character.
395.TP 452.TP
396.B \\\\c 453.B \\\\c
397Suppresses the newline at the end of the reply string. This is the only 454Suppresses the newline at the end of the reply string.
398method to send a string without a trailing return character. It must 455This is the only
399be at the end of the send string. For example, 456method to send a string without a trailing return character.
 457It must be at the end of the send string.
 458For example,
400the sequence hello\\c will simply send the characters h, e, l, l, o. 459the sequence hello\\c will simply send the characters h, e, l, l, o.
401.I (not valid in expect.) 460.I (not valid in expect.)
402.TP 461.TP
403.B \\\\d 462.B \\\\d
404Delay for one second. The program uses sleep(1) which will delay to a 463Delay for one second.
405maximum of one second. 464The program uses sleep(1) which will delay to a maximum of one second.
406.I (not valid in expect.) 465.I (not valid in expect.)
407.TP 466.TP
408.B \\\\K 467.B \\\\K
409Insert a BREAK 468Insert a BREAK
410.I (not valid in expect.) 469.I (not valid in expect.)
411.TP 470.TP
412.B \\\\n 471.B \\\\n
413Send a newline or linefeed character. 472Send a newline or linefeed character.
414.TP 473.TP
415.B \\\\N 474.B \\\\N
416Send a null character. The same sequence may be represented by \\0. 475Send a null character.
 476The same sequence may be represented by \\0.
417.I (not valid in expect.) 477.I (not valid in expect.)
418.TP 478.TP
419.B \\\\p 479.B \\\\p
420Pause for a fraction of a second. The delay is 1/10th of a second. 480Pause for a fraction of a second.
 481The delay is 1/10th of a second.
421.I (not valid in expect.) 482.I (not valid in expect.)
422.TP 483.TP
423.B \\\\q 484.B \\\\q
424Suppress writing the string to the SYSLOG. The string ?????? is 485Suppress writing the string to the SYSLOG.
425written to the log in its place. 486The string ?????? is written to the log in its place.
426.I (not valid in expect.) 487.I (not valid in expect.)
427.TP 488.TP
428.B \\\\r 489.B \\\\r
429Send or expect a carriage return. 490Send or expect a carriage return.
430.TP 491.TP
431.B \\\\s 492.B \\\\s
432Represents a space character in the string. This may be used when it 493Represents a space character in the string.
433is not desirable to quote the strings which contains spaces. The 494This may be used when it
434sequence 'HI\ TIM' and HI\\sTIM are the same. 495is not desirable to quote the strings which contains spaces.
 496The sequence 'HI\ TIM' and HI\\sTIM are the same.
435.TP 497.TP
436.B \\\\t 498.B \\\\t
437Send or expect a tab character. 499Send or expect a tab character.
438.TP 500.TP
439.B \\\\T 501.B \\\\T
440Send the phone number string as specified with the \fI\-T\fR option 502Send the phone number string as specified with the \fI\-T\fR option
441.I (not valid in expect.) 503.I (not valid in expect.)
442.TP 504.TP
443.B \\\\U 505.B \\\\U
444Send the phone number 2 string as specified with the \fI\-U\fR option 506Send the phone number 2 string as specified with the \fI\-U\fR option
445.I (not valid in expect.) 507.I (not valid in expect.)
446.TP 508.TP
447.B \\\\\\\\ 509.B \\\\\\\\
448Send or expect a backslash character. 510Send or expect a backslash character.
449.TP 511.TP
450.B \\\\ddd 512.B \\\\ddd
451Collapse the octal digits (ddd) into a single ASCII character and send that 513Collapse the octal digits (ddd) into a single ASCII character and send that
452character. 514character.
453.I (some characters are not valid in expect.) 515.I (some characters are not valid in expect.)
454.TP 516.TP
455.B \^^C 517.B \^^C
456Substitute the sequence with the control character represented by C. 518Substitute the sequence with the control character represented by C.
457For example, the character DC1 (17) is shown as \^^Q. 519For example, the character DC1 (17) is shown as \^^Q.
458.I (some characters are not valid in expect.) 520.I (some characters are not valid in expect.)
459.SH ENVIRONMENT VARIABLES 521.SH ENVIRONMENT VARIABLES
460Environment variables are available within chat scripts, if the \fI\-E\fR 522Environment variables are available within chat scripts, if the \fI\-E\fR
461option was specified in the command line. The metacharacter \fI$\fR is used 523option was specified in the command line.
462to introduce the name of the environment variable to substitute. If the 524The metacharacter \fI$\fR is used
 525to introduce the name of the environment variable to substitute.
 526If the
463substitution fails, because the requested environment variable is not set, 527substitution fails, because the requested environment variable is not set,
464\fInothing\fR is replaced for the variable. 528\fInothing\fR is replaced for the variable.
465.SH TERMINATION CODES 529.SH TERMINATION CODES
466The \fIchat\fR program will terminate with the following completion 530The \fIchat\fR program will terminate with the following completion
467codes. 531codes.
468.TP 532.TP
469.B 0 533.B 0
470The normal termination of the program. This indicates that the script 534The normal termination of the program.
 535This indicates that the script
471was executed without error to the normal conclusion. 536was executed without error to the normal conclusion.
472.TP 537.TP
473.B 1 538.B 1
474One or more of the parameters are invalid or an expect string was too 539One or more of the parameters are invalid or an expect string was too
475large for the internal buffers. This indicates that the program as not 540large for the internal buffers.
 541This indicates that the program as not
476properly executed. 542properly executed.
477.TP 543.TP
478.B 2 544.B 2
479An error occurred during the execution of the program. This may be due 545An error occurred during the execution of the program.
 546This may be due
480to a read or write operation failing for some reason or chat receiving 547to a read or write operation failing for some reason or chat receiving
481a signal such as SIGINT. 548a signal such as SIGINT.
482.TP 549.TP
483.B 3 550.B 3
484A timeout event occurred when there was an \fIexpect\fR string without 551A timeout event occurred when there was an \fIexpect\fR string without
485having a "\-subsend" string. This may mean that you did not program the 552having a "\-subsend" string.
 553This may mean that you did not program the
486script correctly for the condition or that some unexpected event has 554script correctly for the condition or that some unexpected event has
487occurred and the expected string could not be found. 555occurred and the expected string could not be found.
488.TP 556.TP
489.B 4 557.B 4
490The first string marked as an \fIABORT\fR condition occurred. 558The first string marked as an \fIABORT\fR condition occurred.
491.TP 559.TP
492.B 5 560.B 5
493The second string marked as an \fIABORT\fR condition occurred. 561The second string marked as an \fIABORT\fR condition occurred.
494.TP 562.TP
495.B 6 563.B 6
496The third string marked as an \fIABORT\fR condition occurred. 564The third string marked as an \fIABORT\fR condition occurred.
497.TP 565.TP
498.B 7 566.B 7
499The fourth string marked as an \fIABORT\fR condition occurred. 567The fourth string marked as an \fIABORT\fR condition occurred.
500.TP 568.TP
501.B ... 569.B ...
502The other termination codes are also strings marked as an \fIABORT\fR 570The other termination codes are also strings marked as an \fIABORT\fR
503condition. 571condition.
504.LP 572.LP
505Using the termination code, it is possible to determine which event 573Using the termination code, it is possible to determine which event
506terminated the script. It is possible to decide if the string "BUSY" 574terminated the script.
507was received from the modem as opposed to "NO DIAL TONE". While the 575It is possible to decide if the string "BUSY"
 576was received from the modem as opposed to "NO DIAL TONE".
 577While the
508first event may be retried, the second will probably have little 578first event may be retried, the second will probably have little
509chance of succeeding during a retry. 579chance of succeeding during a retry.
510.SH COPYRIGHT 580.SH COPYRIGHT
511The \fIchat\fR program is in public domain. This is not the GNU public 581The \fIchat\fR program is in public domain.
512license. If it breaks then you get to keep both pieces. 582This is not the GNU public license.
 583If it breaks then you get to keep both pieces.