chat man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

chat(8)								       chat(8)

       chat - Automated conversational script with a modem

       /usr/sbin/chat [options] script

       Start  with the echo option turned on. Echoing may also be turned on or
       off at specific points in the chat script by using  the	ECHO  keyword.
       When  echoing  is enabled, all output from the modem is echoed to stan‐
       dard error.  Reads the chat script from the chatfile.  The use of  this
       option  is mutually exclusive with the chat script parameters. The user
       must have read access to the file.  Multiple lines are permitted in the
       file.   Space  or  horizontal tab characters should be used to separate
       the strings.  Set the file for output of the report strings. If you use
       the  keyword REPORT, the resulting strings are written to this file. If
       this option is not used and you still use REPORT keywords, the standard
       error  file  is	used for the report strings.  Sets the timeout for the
       expected string to be received.	If the string is not  received	within
       the  time  limit, the reply string is not sent.	An alternate reply may
       be sent or the script will fail if there is no alternate reply  string.
       A  failed  script  causes  the chat program to terminate with a nonzero
       error code.  Requests that the chat script be  executed	in  a  verbose
       mode.   The  chat program logs all text received from the modem and the
       output strings that it sends to the syslog command.  Requests that  the
       chat script be executed in a standard error verbose mode. The chat pro‐
       gram then logs all text received from the modem and the output  strings
       which it sends to the standard error device. This device is usually the
       local console at the station running the chat  or  pppd	program.  This
       option  does  not  work properly if the standard error is redirected to
       the /dev/null location as is the case when pppd runs  in	 the  detached
       mode. In that case, use the -v option to record the session on the SYS‐
       LOG device.  If the script is not specified  in	a  file	 with  the  -f
       option then the script is included as parameters to the chat program.

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

       The chat script defines the communications between the local system and
       a  remote  system. A script consists of one or more “expect-send” pairs
       of strings, separated by spaces, with an	 optional  “subexpect-subsend”
       string pair, separated by a dash as in the following example:

       ogin:-BREAK-ogin: ppp ssword: hello2u2

       In  the	previous example, the chat program expects the string “ogin:”.
       If it fails to receive a login prompt within the time  interval	allot‐
       ted,  the chat program sends a break sequence to the remote system, and
       then expects to receive the string “ogin:”.  If the  first  “ogin:”  is
       received, the break sequence is not generated.

       Once  it	 receives  the login prompt, the chat program sends the string
       ppp, and expects to receive the “ssword:” prompt.   When	 prompted  for
       the password, it sends the password hello2u2.

       A  carriage  return is normally sent following the reply string.	 It is
       not expected in the “expect” string unless it is requested by  specify‐
       ing the \r escape sequence.

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

       The  leading  “l”  character may be received in error and you may never
       find the string even though it was sent by the system.  For  this  rea‐
       son, scripts look for “ogin:” rather than “login:” and “ssword:” rather
       than “password:”.

       A very simple script is as follows:

       ogin: ppp ssword: hello2u2

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

       In practice, simple scripts are rare.  At the very  least,  you	should
       include	subexpect  sequences  in  case	the  original  string  is  not
       received, as in the following script:

       ogin:--ogin: ppp ssword: hello2u2

       The preceding script is better than the simple one used earlier.	  This
       looks  for the same login: prompt, but if one is not received, it sends
       a single return sequence and looks for login:  again.   If  line	 noise
       obscures	 the  first login prompt, sending an empty line usually gener‐
       ates a login prompt again.

       Comments can be embedded in the chat script by beginning	 a  line  with
       the number (#) character in column 1. Such comment lines are ignored by
       the chat program. If a number (#) character is expected	as  the	 first
       character  of  the expect sequence, you should quote the expect string.
       If you want to wait for a prompt that starts with a number (#)  charac‐
       ter, enter a text string similar to the following:

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

       Many  modems  report  the  status  of  the call as one of the following
       strings: CONNECTED, NO CARRIER, or BUSY.	 It is often desirable to ter‐
       minate  the  script if the modem fails to connect to the remote system.
       The difficulty is that a script does not know  which  modem  string  it
       might  receive.	 On  one attempt, it might receive BUSY while the next
       time it might receive NO CARRIER.

       These abort strings may be specified in	the  script  using  the	 ABORT
       sequence as shown in the following example:


       Using this sequence, the chat program expects nothing, sends the string
       ATZ, and then expects the string OK.  When it receives OK, the  program
       sends  the  string  ATDT5551212	to dial the telephone, and expects the
       string CONNECT.	If the string CONNECT is received,  the	 remainder  of
       the script is executed.

       If the telephone is busy, the modem sends the string BUSY.  This causes
       the string to match the abort character sequence, and the script	 fails
       because	it  found  a match to the abort string.	 If it receives the NO
       CARRIER string, it aborts for the same reason.	Either	string	termi‐
       nates the chat script.

       This  sequence  allows  for  clearing previously set ABORT strings. The
       ABORT strings are kept in an array of a predetermined size (at compila‐
       tion  time);  CLR_ABORT	reclaims the space for cleared entries so that
       new strings can use that space.

       The SAY directive allows the script to send strings to the user at  the
       terminal via standard error.  If the chat program is being run by pppd,
       and pppd is running as a daemon (detached from its  controlling	termi‐
       nal),  standard	error will normally be redirected to the /etc/ppp/con‐
       nect-errors file.

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

       The SAY strings could be used to give progress messages in sections  of
       the  script  where  you	want to have `ECHO OFF' but still let the user
       know what is happening, for example:


       ECHO OFF

       SAY "Dialing your ISP...\n"

       '' ATDT5551212

       TIMEOUT 120

       SAY "Waiting up to 2 minutes for connection ... "

       CONNECT ''

       SAY "Connected, now logging in ...0"

       ogin: account

       ssword: pass

       $ SAY "Logged in OK ...0" etc ...

       This sequence presents the SAY strings to  the  user;  details  of  the
       script  remain hidden. For example, if the above script works, the fol‐
       lowing information is displayed.	 Dialing your ISP...

       Waiting up to 2 minutes for connection ... Connected,  now  logging  in

       Logged in OK ...

       A REPORT string is different from the ABORT string in that the strings,
       and all characters to the next control character	 such  as  a  carriage
       return, are written to the report file.

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

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

       You can specify these report strings in the  script  using  the	REPORT
       sequence, as shown in the following example:

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

       Using  this sequence the chat program expects nothing, sends the string
       ATDT5551212 to dial the telephone, and expects the string  CONNECT.  If
       the  CONNECT  string is received, the remainder of the script executes.
       In addition, the program writes to the expect-file the  CONNECT	string
       plus any characters, such as the connection rate which follow it.

       This  sequence  allows for clearing previously set REPORT strings.  The
       REPORT strings are kept in an array of a predetermined size (at	compi‐
       lation time); CLR_REPORT reclaims the space for cleared entries so that
       new strings can use that space.

       The echo option controls whether the output from the modem is echoed to
       standard	 error.	 This option may be set with the -e option, but it can
       also be controlled by the ECHO keyword. The expect-send	pair  ECHO  ON
       enables	echoing,  and  ECHO OFF disables it. With this keyword you can
       select  which  parts  of	 the  conversation  should  be	visible.   For
       instance,  with	the  following script, all output resulting from modem
       configuration and dialing is not visible, but starting with the CONNECT
       (or BUSY) message, everything is echoed.

       ABORT	'BUSY' .br ABORT   'NO CARRIER' .br .br ''	ATZ .br OK\r\n
       ATD1234567 .br \r\n    \c .br ECHO     ON  .br  CONNECT	\c  .br	 ogin:

       The  HANGUP  option controls whether a modem hangup is considered as an
       error or not.  This option is useful in scripts to  dial	 systems  that
       hang  up	 and  call  your system back.  The HANGUP options can be ON or
       OFF. When HANGUP is set OFF and the modem hangs up (for example,	 after
       the  first  stage  of  logging in to a callback system), chat continues
       running the script (for example, waiting for the incoming call and sec‐
       ond  stage  login  prompt). When the incoming call connects, you should
       use the HANGUP ON directive to reinstall normal hang up	signal	behav‐
       ior, as shown in the following example:

       ABORT   'BUSY'

       ''      ATZ

       OK\r\n  ATD1234567

       \r\n    \c

       CONNECT \c

       'Callback login:' call_back_ID


       ABORT "Bad Login"

       'Callback Password:' Call_back_password

       TIMEOUT 120

       CONNECT \c

       HANGUP ON


       ogin:--BREAK--ogin: real_account

       etc ...

       The  initial timeout value of 45 seconds can be changed by using the -t
       timeout option, for example: ATZ	 OK  ATDT5551212  CONNECT  TIMEOUT  10
       ogin:--ogin: TIMEOUT 5 assword: \ hello2u2

       This  sequence  changes	the  timeout to 10 seconds when it expects the
       login: prompt, then changes the timeout to 5 seconds when it looks  for
       the password prompt.

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

       The  special reply string of EOT indicates that the chat program should
       send an EOT character to the remote system.  This is normally the  End-
       of-file	character  sequence.  A return character is not sent following
       the EOT.

       The EOT sequence may  be	 embedded  into	 the  send  string  using  the
       sequence ^D.

       The  BREAK reply string causes a break condition to be sent.  The break
       is a special signal on the transmitter.	The normal processing  on  the
       receiver	 is  to	 change the transmission rate. It may be used to cycle
       through the available transmission rates on the remote system until you
       are able to receive a valid login prompt.

       You  can	 embed the break sequence into the send string by using the \K
       escape sequence.

       The expect and reply strings may contain escape sequences.  All of  the
       sequences  are  valid in the reply string; many are legal in the expect
       string.	Those sequences which are not valid in the expect  string  are
       so  indicated.	Expects	 or  sends  a  null string. If you send a null
       string then it will still send the return character. This sequence  may
       either  be  a  pair  of	apostrophe  or quote characters.  Represents a
       backspace character.  Suppresses the newline at the end	of  the	 reply
       string.	 This is the only means of sending a string without a trailing
       return character.  It must be at the end of the send string.  For exam‐
       ple,  the sequence hello\c will send the characters h, e, l, l, o. (Not
       valid in expect.)  Delays for one second.  The program uses  the	 sleep
       command,	 which	will  delay to a maximum of one second.	 (Not valid in
       expect.)	 Inserts a BREAK. (Not valid in expect.)  Sends a  newline  or
       linefeed	 character.  Sends a null character.  The same sequence may be
       represented by \0. (Not valid in expect.)  Pauses for a fraction	 of  a
       second.	 The delay is 1/10th of a second. (Not valid in expect.)  Sup‐
       presses writing the string to the syslog file.  The  string  ??????  is
       written	to  the	 log  in  its  place. (Not valid in expect.)  Sends or
       expects a carriage return.  Represents a space character in the string.
       Use  this  when	it  is not desirable to quote the strings that contain
       spaces. The sequence `HI TIM' and  HI\sTIM  are	the  same.   Sends  or
       expects a tab character.	 Sends or expects a backslash character.  Col‐
       lapses the octal digits (ddd) into a single ASCII character  and	 sends
       that character. (Some characters are not valid in expect.)  Substitutes
       the sequence with the control character represented by C. For  example,
       the  character  DC1 (17) is shown as ^Q. (Some characters are not valid
       in expect.)

       The chat program terminates with the following completion  codes.   The
       normal  termination  of the program. This indicates that the script was
       executed without error to the normal conclusion.	 One or	 more  of  the
       parameters are invalid or an expect string was too large for the inter‐
       nal buffers. This indicates that the program as not properly  executed.
       An  error occurred during the execution of the program. This may be due
       to failure of a read or write operation or chat receiving a signal such
       as  SIGINT.  A timeout event occurred due to an expect string without a
       -subsend string. This may mean that you did not program the script cor‐
       rectly for the condition or that some unexpected event occurred and the
       expected string was not found.  The first string	 marked	 as  an	 ABORT
       condition  occurred.   The  second  string marked as an ABORT condition
       occurred.  The third string marked as an ABORT condition occurred.  The
       fourth  string marked as an ABORT condition occurred.  The other termi‐
       nation codes are also strings marked as an ABORT condition.

       You can use the termination code to determine  which  event  terminated
       the  script. It is possible to decide if the string “BUSY” was received
       from the modem as opposed to “NO DIAL TONE”. While the first event  may
       be  retried,  the second will probably have little chance of succeeding
       during a retry.

       Commands: uucp(1), pppd(8), uucico(8)


List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net