2930 beadm should sort by creation date
[illumos-gate.git] / usr / src / man / man1m / chat.1m
blob0f3b594215904dd80e00d3cdf1f4670d065dc4d8
1 '\" te
2 .\" This manual page is based on documentation obtained from Karl Fox.
3 .\" Portions Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH CHAT 1M "May 4, 2001"
8 .SH NAME
9 chat \- automated conversational exchange tool
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBchat\fR [\fIoptions\fR] \fIscript\fR
14 .fi
16 .SH DESCRIPTION
17 .sp
18 .LP
19 The \fBchat\fR program implements a conversational text-based exchange between
20 the computer and any serial device, including (but not limited to) a modem, an
21 ISDN TA, and the remote peer itself, establishing a connection between the
22 Point-To-Point Protocol daemon (\fBpppd\fR) and the remote \fBpppd\fR process.
23 .SH OPTIONS
24 .sp
25 .LP
26 The  \fBchat\fR command supports the following options:
27 .sp
28 .ne 2
29 .na
30 \fB\fB-f\fR \fI<chat file>\fR\fR
31 .ad
32 .RS 23n
33 Read the \fBchat\fR script from the  \fBchat\fR file. This option is mutually
34 exclusive with the  \fBchat\fR script parameters. You must have \fBread\fR
35 access to use the file. Multiple lines are permitted in the file. Use the space
36 or horizontal tab characters to separate the strings.
37 .RE
39 .sp
40 .ne 2
41 .na
42 \fB\fB-t\fR \fB\fI<timeout>\fR\fR \fR
43 .ad
44 .RS 23n
45 Set the timeout for the expected string to be received. If the string is not
46 received within the time limit, the reply string is not sent. If specified,
47 a 'subexpect' (alternate reply) string can be sent. Otherwise, if no alternate
48 reply strings remain, the \fBchat\fR script fails.. A failed script will cause
49 the  \fBchat\fR program to terminate with a non-zero error code.
50 .RE
52 .sp
53 .ne 2
54 .na
55 \fB\fB-r\fR \fB\fI<report file> \fR\fR \fR
56 .ad
57 .RS 23n
58 Set the file for output of the report strings. If you use the keyword
59 \fBREPORT\fR, the resulting strings are written to this file. If  the \fB-r\fR
60 option is not used and you use the \fBREPORT\fR keyword, the  \fBstderr\fR file
61 is used for the report strings.
62 .RE
64 .sp
65 .ne 2
66 .na
67 \fB\fB-e\fR \fR
68 .ad
69 .RS 23n
70 Start with the echo option turned on. You turn echo on or off at specific
71 points in the \fBchat\fR script using the \fBECHO\fR keyword. When echoing is
72 enabled, all output from the modem is echoed to \fBstderr\fR.
73 .RE
75 .sp
76 .ne 2
77 .na
78 \fB\fB-E\fR \fR
79 .ad
80 .RS 23n
81 Enables environment variable substitution within \fBchat\fR scripts using the
82 standard \fI$xxx\fR syntax.
83 .RE
85 .sp
86 .ne 2
87 .na
88 \fB\fB-v\fR \fR
89 .ad
90 .RS 23n
91 Request that the \fBchat\fR script execute in a verbose mode. The  \fBchat\fR
92 program logs the execution state of the \fBchat\fR script as well as all text
93 received from the modem and output strings sent to the modem. The default is to
94 log through \fBsyslog\fR(3C) with facility \fBlocal\fR2; the logging method is
95 alterable using the \fB-S\fR and \fB-s\fR options.
96 .RE
98 .sp
99 .ne 2
101 \fB\fB-V\fR \fR
103 .RS 23n
104 Request that the  \fBchat\fR script be executed in a \fBstderr\fR verbose mode.
105 The \fBchat\fR program logs all text received from the modem and output strings
106 sent to the modem to \fBstderr\fR. \fBstderr\fR is usually the local console at
107 the station running the  \fBchat\fR or \fBpppd\fR program.
111 .ne 2
113 \fB\fB-s\fR\fR
115 .RS 23n
116 Use \fBstderr\fR.  Log messages from \fB-v\fR and error messages are sent to
117 \fBstderr\fR.
121 .ne 2
123 \fB\fB-S\fR\fR
125 .RS 23n
126 Do not use syslog.  By default, error messages are set to syslog. This option
127 prevents log messages from \fB-v\fR and error messages from being sent to
128 syslog.
132 .ne 2
134 \fB\fB-T\fR \fB\fI<phone number>\fR\fR\fR
136 .RS 23n
137 Pass in an arbitrary string (usually a telephone number) that will be
138 substituted for the \fB\eT\fR substitution metacharacter in a send string.
142 .ne 2
144 \fB\fB-U\fR \fB\fI<phone number 2>\fR\fR\fR
146 .RS 23n
147 Pass in a second string (usually a telephone number) that will be substituted
148 for the \fB\eU\fR substitution metacharacter in a send string. This is useful
149 when dialing an ISDN terminal adapter that requires two numbers.
153 .ne 2
155 \fB\fBscript\fR \fR
157 .RS 23n
158 If the script is not specified in a file with the \fB-f\fR option, the script
159 is included as parameters to the \fBchat\fR program.
162 .SH EXTENDED DESCRIPTION
163 .SS "Chat Script"
166 The \fBchat\fR script defines communications. A script consists of one or more
167 "expect-send" pairs of strings separated by spaces, with an optional
168 "subexpect-subsend" string pair, separated by a dash (as in the following
169 example:)
172 ogin:-BREAK-ogin: ppp ssword: hello2u2
175 The example indicates that the \fBchat\fR program should expect the string
176 "ogin:". If it fails to receive a login prompt within the time interval
177 allotted, it sends a break sequence to the remote and then expects the string
178 "ogin:". If the first "ogin:" is received, the break sequence is not generated.
181 Upon receiving the login prompt, the  \fBchat\fR program sends the string "ppp"
182 and then expects the prompt "ssword:". When the password prompt is received, it
183 sends the password hello2u2.
186 A carriage return is normally sent following the reply string. It is not
187 expected in the "expect" string unless it is specifically requested by using
188 the \fB\er\fR character sequence.
191 The expect sequence should contain only what is needed to identify the received
192 data. Because it's stored on a disk file, it should not contain variable
193 information. Generally it is not acceptable to look for time strings, network
194 identification strings, or other variable pieces of data as an expect string.
197 To correct for characters that are corrupted during the initial sequence, look
198 for the string "ogin:" rather than "login:". The leading "l" character may be
199 received in error, creating problems in finding the string. For this reason,
200 scripts look for "ogin:" rather than "login:" and "ssword:" rather than
201 "password:".
204 An example of a simple script follows:
206 .in +2
208 ogin: ppp ssword: hello2u2
210 .in -2
214 The example can be intrepreted as: expect ogin:, send ppp, expect ...ssword:,
215 send hello2u2.
218 When login to a remote peer is necessary, simple scripts are rare. At minimum,
219 you should include sub-expect sequences in case the original string is not
220 received. For example, consider the following script:
222 .in +2
224 ogin:--ogin: ppp ssword: hello2u2
226 .in -2
230 This script is more effective than the simple one used earlier. The string
231 looks for the same login prompt; however, if one is not received, a single
232 return sequence is sent and then the script looks for login: again. If line
233 noise obscures the first login prompt, send the empty line to generate a login
234 prompt again.
235 .SS "Comments"
238 Comments can be embedded in the \fBchat\fR script. Comment lines are ignored by
239 the chat program. A comment starts with the hash ("#") character in column one.
240 If a \fB#\fR character is expected as the first character of the expect
241 sequence, quote the expect string. If you want to wait for a prompt that starts
242 with a \fB#\fR character, write something like this:
244 .in +2
246 # Now wait for the prompt and send logout string
247 \&'# ' logout
249 .in -2
251 .SS "Sending Data From A File"
254 If the string to send begins with an at sign ("@"), the remainder of the string
255 is interpreted as the name of the file that contains the string. If the last
256 character of the data read is a newline, it is removed. The file can be a named
257 pipe (or fifo) instead of a regular file. This enables \fBchat\fR to
258 communicate with another program, for example, a program to prompt the user and
259 receive a password typed in.
260 .SS "Abort "
263 Many modems report the status of a call as a string. These status strings are
264 often "CONNECTED" or "NO CARRIER" or "BUSY." If the modem fails to connect to
265 the remote, you can terminate the script. Abort strings may be specified in the
266 script using the ABORT sequence. For example:
268 .in +2
270 ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT
272 .in -2
276 This sequence expects nothing and sends the string ATZ. The expected response
277 is the string OK. When OK is received, the string ATDT5551212 dials the
278 telephone. The expected string is CONNECT. If CONNECT is received, the
279 remainder of the script is executed. When the modem finds a busy telephone, it
280 sends the string BUSY, causing the string to match the abort character
281 sequence. The script fails because it found a match to the abort string. If the
282 NO CARRIER string is received, it aborts for the same reason.
283 .SS "Clr_Abort "
286 The CLR_ABORT sequence clears previously set ABORT strings. ABORT strings are
287 kept in an array of a pre-determined size; CLR_ABORT reclaims the space for
288 cleared entries, enabling new strings to use that space.
289 .SS "Say "
292 The SAY string enables the script to send strings to a user at a terminal via
293 standard error. If \fBchat\fR is being run by \fBpppd\fR and \fBpppd\fR is
294 running as a daemon (detached from its controlling terminal), standard error is
295 normally redirected to the \fB/etc/ppp/connect-errors\fR file.
298 SAY strings must be enclosed in single or double quotes. If carriage return and
299 line feed are required for the output, you must explicitly add them to your
300 string.
303 The SAY string can provide progress messages to users even with "ECHO OFF." For
304 example, add a line similar to the following to the script:
306 .in +2
308 ABORT BUSY
309 ECHO OFF
310 SAY "Dialing your ISP...\en"
311 \&'' ATDT5551212
312 TIMEOUT 120
313 SAY "Waiting up to 2 minutes for connection ..."
314 CONNECT ''
315 SAY "Connected, now logging in ...\en"
316 ogin: account
317 ssword: pass
318 $ \ec
319 SAY "Logged in OK ... \en"
321 .in -2
325 This sequence hides script detail while presenting the SAY string to the user.
326 In this case, you will see:
328 .in +2
330 Dialing your ISP...
331 Waiting up to 2 minutes for connection...Connected, now logging in...
332 Logged in OK ...
334 .in -2
336 .SS "Report"
339 REPORT is similar to the ABORT string. With REPORT, however, strings and all
340 characters to the next control character (such as a carriage return), are
341 written to the report file.
344 REPORT strings can be used to isolate a modem's transmission rate from its
345 CONNECT string and return the value to the \fBchat\fR user. Analysis of the
346 REPORT string logic occurs in conjunction with other string processing, such as
347 looking for the expect string. It's possible to use the same string for a
348 REPORT and ABORT sequence, but probably not useful.
351 Report strings may be specified in the script using the REPORT sequence. For
352 example:
354 .in +2
356 REPORT CONNECT
357 ABORT BUSY
358 ATDT5551212 CONNECT
359 ogin: account
361 .in -2
365 The above sequence expects nothing, then sends the string ATDT5551212 to dial
366 the telephone. The expected string is CONNECT. If CONNECT is received, the
367 remainder of the script is executed. In addition, the program writes the string
368 CONNECT to the report file (specified by \fB-r\fR) in addition to any
369 characters that follow.
370 .SS "Clr_Report"
373 CLR_REPORT clears previously set REPORT strings. REPORT strings are kept in an
374 array of a pre-determined size; CLR_REPORT reclaims the space for cleared
375 entries so that new strings can use that space.
376 .SS "Echo"
379 ECHO determines if modem output is echoed to \fBstderr\fR. This option may be
380 set with the \fB-e\fR option, but can also be controlled by the ECHO keyword.
381 The "expect-send" pair  ECHO ON enables echoing, and ECHO OFF disables it. With
382 ECHO, you can select which parts of the conversation should be visible. In the
383 following script:
385 .in +2
387 ABORT   'BUSY'
388 ABORT   'NO CARRIER'
389 ""    AT&F
390 OK\er\en  ATD1234567
391 \er\en    \ec
392 ECHO    ON
393 CONNECT \ec
394 ogin:   account
396 .in -2
400 All output resulting from modem configuration and dialing is not visible, but
401 output is echoed beginning with the CONNECT (or BUSY) message.
402 .SS "Hangup"
405 The HANGUP option determines if a modem hangup is considered as an error.
406 HANGUP is useful for dialing systems that hang up and call your system back.
407 HANGUP can be ON or OFF. When HANGUP is set to OFF and the modem hangs up (for
408 example, following the first stage of logging in to a callback system),
409 \fBchat\fR continues running the script (for example, waiting for the incoming
410 call and second stage login prompt). When the incoming call is connected, use
411 the HANGUP ON string to reinstall normal hang up signal behavior. An example of
412 a simple script follows:
414 .in +2
416 ABORT   'BUSY'
417  ""  AT&F
418  OK\er\en  ATD1234567
419  \er\en    \ec
420  CONNECT \ec
421  'Callback login:' call_back_ID
422  HANGUP OFF
423  ABORT "Bad Login"
424  'Callback Password:' Call_back_password
425  TIMEOUT 120
426  CONNECT \ec
427  HANGUP ON
428  ABORT "NO CARRIER"
429  ogin:--BREAK--ogin: real_account
431 .in -2
433 .SS "Timeout"
436 The initial timeout value is 45 seconds. Use the \fB-t\fR parameter to change
437 the intial timeout value.
440 To change the timeout value for the next expect string, the following example
441 can be used:
443 .in +2
445 \&''"AT&F
446  OK ATDT5551212
447  CONNECT \ec
448  TIMEOUT 10
449  ogin:--ogin: username
450  TIMEOUT 5
451  assword: hello2u2
453 .in -2
457 The example changes the timeout to ten seconds when it expects the login:
458 prompt. The timeout is changed to five seconds when it looks for the password
459 prompt.
462 Once changed, the timeout value remains in effect until it is changed again.
463 .SS " EOT"
466 The EOT special reply string instructs the \fBchat\fR program to send an EOT
467 character to the remote. This is equivalent to using ^D\ec as the reply string.
468 The EOT string normally indicates the end-of-file character sequence. A return
469 character is not sent following the EOT. The EOT sequence can embedded into the
470 send string using the sequence ^D.
471 .SS " BREAK"
474 The BREAK special reply string sends a break condition. The break is a special
475 transmitter signal. Many UNIX systems handle break by cycling through available
476 bit rates, and sending break is often needed when the remote system does not
477 support autobaud. BREAK is equivalent to using \eK\ec as the reply string.
478 You embed the break sequence into the send string using the \eK sequence.
479 .SS "Escape Sequences"
482 Expect and reply strings can contain escape sequences. Reply strings accept all
483 escape sequences, while expect strings accept most sequences. A list of escape
484 sequences is presented below. Sequences that are not accepted by expect strings
485 are indicated.
487 .ne 2
489 \fB\fB\&''\fR \fR
491 .RS 10n
492 Expects or sends a null string. If you send a null string, \fBchat\fR sends
493 the return character.  If you expect a null string, \fBchat\fR proceeds to the
494 reply string without waiting.  This sequence can be a pair of apostrophes or
495 quote mark characters.
499 .ne 2
501 \fB\fB\eb\fR \fR
503 .RS 10n
504 Represents a backspace character.
508 .ne 2
510 \fB\fB\ec\fR \fR
512 .RS 10n
513 Suppresses the newline at the end of the reply string. This is the only method
514 to send a string without a trailing return character. This sequence must be at
515 the end of the send string. For example, the sequence hello\ec will simply send
516 the characters h, e, l, l, o. (Not valid  in expect.)
520 .ne 2
522 \fB\fB\ed\fR \fR
524 .RS 10n
525 Delay for one second. The program uses \fBsleep\fR(1) which delays to a maximum
526 of one second.  (Not valid  in expect.)
530 .ne 2
532 \fB\fB\eK\fR \fR
534 .RS 10n
535 Insert a BREAK.  (Not valid  in expect.)
539 .ne 2
541 \fB\fB\en\fR \fR
543 .RS 10n
544 Send a newline or linefeed character.
548 .ne 2
550 \fB\fB\eN\fR \fR
552 .RS 10n
553 Send a null character. The same sequence may be represented by \e0.  (Not valid
554 in expect.)
558 .ne 2
560 \fB\fB\ep\fR \fR
562 .RS 10n
563 Pause for 1/10th of a second.  (Not valid  in expect.)
567 .ne 2
569 \fB\fB\eq\fR \fR
571 .RS 10n
572 Suppress writing the string to syslog.  The string ?????? is written to the log
573 in its place. (Not valid  in expect.)
577 .ne 2
579 \fB\fB\er\fR \fR
581 .RS 10n
582 Send or expect a carriage return.
586 .ne 2
588 \fB\fB\es\fR \fR
590 .RS 10n
591 Represents a space character in the string. Can be used when it is not
592 desirable to quote the strings which contains spaces. The sequence 'HI\ TIM'
593 and HI\esTIM are the same.
597 .ne 2
599 \fB\fB\et\fR \fR
601 .RS 10n
602 Send or expect a tab character.
606 .ne 2
608 \fB\fB\eT\fR \fR
610 .RS 10n
611 Send the phone number string as specified with the \fB-T\fR option.  (Not valid
612 in expect.)
616 .ne 2
618 \fB\fB\eU\fR \fR
620 .RS 10n
621 Send the phone number 2 string as specified with the \fB-U\fR option. (Not
622 valid  in expect.)
626 .ne 2
628 \fB\fB\e\e\fR \fR
630 .RS 10n
631 Send or expect a backslash character.
635 .ne 2
637 \fB\fB\eddd\fR \fR
639 .RS 10n
640 Collapse the octal digits (ddd) into a single ASCII character and send that
641 character. (\e000 is not valid in an expect string.)
645 .ne 2
647 \fB\fB^C\fR \fR
649 .RS 10n
650 Substitute the sequence with the control character represented by C. For
651 example, the character DC1 (17) is shown as ^Q. (Some characters are not valid
652 in expect.)
655 .SH ENVIRONMENT VARIABLES
658 Environment variables are available within \fBchat\fR scripts if the \fB-E\fR
659 option is specified on the command line. The metacharacter \fB$\fR introduces
660 the name of the environment variable to substitute. If the substition fails
661 because the requested environment variable is not set, nothing is replaced for
662 the variable.
663 .SH EXIT STATUS
666 The \fBchat\fR program terminates with the following completion codes:
668 .ne 2
670 \fB\fB0\fR \fR
672 .RS 10n
673 Normal program termination. Indicates that the script was executed without
674 error to normal conclusion.
678 .ne 2
680 \fB\fB1\fR \fR
682 .RS 10n
683 One or more of the parameters are invalid or an expect string was too large for
684 the internal buffers. Indicates that the program was not properly executed.
688 .ne 2
690 \fB\fB2\fR \fR
692 .RS 10n
693 An error occurred during the execution of the program. This may be due to a
694 read or write operation failing or \fBchat\fR receiving a signal such as
695 SIGINT.
699 .ne 2
701 \fB\fB3\fR \fR
703 .RS 10n
704 A timeout event occurred when there was an expect string without having a
705 "-subsend" string. This indicates that you may not have programmed the script
706 correctly for the condition or that an unexpected event occurred and the
707 expected string could not be found.
711 .ne 2
713 \fB\fB4\fR \fR
715 .RS 10n
716 The first string marked as an ABORT condition occurred.
720 .ne 2
722 \fB\fB5\fR \fR
724 .RS 10n
725 The second string marked as an ABORT condition occurred.
729 .ne 2
731 \fB\fB6\fR \fR
733 .RS 10n
734 The third string marked as an ABORT  condition occurred.
738 .ne 2
740 \fB\fB7\fR \fR
742 .RS 10n
743 The fourth string marked as an ABORT condition occurred.
747 .ne 2
749 \fB\fB\&...\fR \fR
751 .RS 10n
752 The other termination codes are also strings marked as an ABORT condition.
757 To determine which event terminated the script, use the termination code. It is
758 possible to decide if the string "BUSY" was received from the modem versus "NO
759 DIALTONE." While the first event may be retried, the second probably will not
760 succeed during a retry.
761 .SH ATTRIBUTES
764 See \fBattributes\fR(5)  for descriptions of the following attributes:
769 box;
770 c | c
771 l | l .
772 ATTRIBUTE TYPE  ATTRIBUTE VALUE
774 Interface Stability     Evolving
777 .SH SEE ALSO
780 \fBsleep\fR(1), \fBuucp\fR(1C), \fBpppd\fR(1M), \fBuucico\fR(1M),
781 \fBsyslog\fR(3C), \fBattributes\fR(5)
784 Additional information on \fBchat\fR scripts are available with UUCP
785 documentation. The  \fBchat\fR script format was taken from scripts used by the
786 \fBuucico\fR program.