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