*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> chat (8)              



NAME    [Toc]    [Back]

     chat - automated conversational script with a modem

SYNOPSIS    [Toc]    [Back]

     chat [options] [script]

DESCRIPTION    [Toc]    [Back]

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

OPTIONS    [Toc]    [Back]

     -f chat_file
             Read the chat script from the chat_file.  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.

     -t timeout
             Set  the  timeout  for the expected string to be received.  If the
             string is not received within the  time  limit  then
the reply
             string  is not sent.  An alternate reply may be sent
or the script
             will fail if there is no alternate reply string.   A
failed script
             will cause the chat program to terminate with a nonzero error

     -r report_file
             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
             stderr file is used for the report strings.

     -e       Start  with the echo option turned on.  Echoing may
also be turned
             on or off at specific points in the chat  script  by
using the ECHO
             keyword.   When  echoing is enabled, all output from
the modem is
             echoed to stderr.

     -v      Request that the chat script be executed in  a  verbose mode.  The
             chat  program  will  then log the execution state of
the chat script
             as well as all text received from the modem and  the
             strings  sent  to  the modem.  The default is to log
via syslog(3);
             the logging method may be altered with the -S and -s

     -V      Request that the chat script be executed in a stderr
             mode.  The chat program will then log all  text  received from the
             modem  and  the  output strings sent to the modem to
the stderr device.
  This device is usually the local  console  at
the station
             running the chat or pppd(8) program.

     -s       Use stderr.  All log messages from -v and all error
messages will
             be sent to stderr.

     -S      Do not use syslog(3).  By  default,  error  messages
are logged via
             syslog(3).  The use of -S will prevent both log messages from -v
             and error messages from being logged via  syslog(3).

     -T phone_number
             Pass in an arbitrary string, usually a phone number,
that will be
             substituted for the T substitution metacharacter  in
a send

     -U phone_number_2
             Pass  in  a  second  string, usually a phone number,
that will be
             substituted for the U substitution metacharacter  in
a send
             string.   This is useful when dialing an ISDN terminal adapter
             that requires two numbers.

     script  If the script is not specified in a file with the -f
option, then
             the  script  is  included  as parameters to the chat

CHAT SCRIPT    [Toc]    [Back]

     The chat script defines the communications.

     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

     This line indicates that the chat program should expect  the
     ``ogin:''.  If it fails to receive a login prompt within the
time interval
 allotted, it is to send a break sequence to  the  remote
and then expect
  the  string  ``ogin:''.  If the first ``ogin:'' is received then the
     break sequence is not generated.

     Once it receives the login prompt,  the  chat  program  will
send the string
     ppp  and  then  expect  the prompt ``ssword:''.  When it receives the prompt
     for the password, it will send the password hello2u2.

     A carriage return  is  normally  sent  following  the  reply
string.  It is not
     expected  in the ``expect'' string unless it is specifically
requested by    character sequence.
     using the

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

     To help correct for characters which may be corrupted during
the initial
     sequence,  look  for  the string ``ogin:'' rather than ``login:''.  It is
     possible that 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 reason, scripts look for ``ogin:''  rather  than  ``login:'' and
     ``ssword:'' rather than ``password:''.

     A very simple script might look like this:

           ogin: ppp ssword: hello2u2

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

     In actual practice, simple scripts are rare.   At  the  very
least, you
     should  include  sub-expect  sequences  should  the original
string not be received.
  For example, consider the following script:

           ogin:--ogin: ppp ssword: hello2u2

     This would be a better script than the simple one used  earlier.  This
     would  look  for  the same login: prompt.  If one is not received, a single
     return sequence is sent and then it  will  look  for  login:
again.  Should
     line  noise  obscure the first login prompt then sending the
empty line
     will usually generate a login prompt again.

COMMENTS    [Toc]    [Back]

     Comments can be embedded in the chat script.  A comment is a
line which
     starts with the `#' (hash) character in column 1.  Such comment lines are
     just ignored by the chat program.  If a `#' character is  to
be 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 `#'
     (hash)  character,  you  would  have to write something like

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

ABORT STRINGS    [Toc]    [Back]

     Many modems will report the status of the call as a  string.
     strings  may  be CONNECT or NO CARRIER or BUSY.  It is often
desirable to
     terminate the script should the modem fail to connect to the
remote.  The
     difficulty is that a script would not know exactly which modem string it
     may receive.  On one attempt it may receive BUSY, while  the
next time it
     may receive NO CARRIER.

     These ``abort'' strings may be specified in the script using
     sequence.  It is written in the script as in  the  following

           ABORT  BUSY  ABORT  'NO CARRIER' '' ATZ OK ATDT5551212

     This sequence will expect nothing; and then send the  string
ATZ.  The expected
  response to this is the string OK.  When it receives
OK, it sends
     the string ATDT5551212 to dial the telephone.  The  expected
string is
     CONNECT.  If the string CONNECT is received the remainder of
the script
     is executed.  However, should the modem find  a  busy  telephone, it will
     send  the  string BUSY.  This will cause the string to match
the abort
     character sequence.  The script will then  fail  because  it
found a match
     to  the abort string.  If it received the string NO CARRIER,
it will abort
     for the same reason.  Either string may be received.  Either
string will
     terminate the chat script.

CLR_ABORT STRINGS    [Toc]    [Back]

     This  sequence  allows  for  clearing  previously  set ABORT
strings.  ABORT
     strings are kept in an array of a  pre-determined  size  (at
     time);  CLR_ABORT will reclaim the space for cleared entries
so that new
     strings can use that space.

SAY STRINGS    [Toc]    [Back]

     The SAY directive allows the script to send strings  to  the
user at the
     terminal  via  standard  error.  If chat is being run by pppd(8), and pppd
     is running as a daemon (detached from its controlling terminal), standard
     error    will   normally   be   redirected   to   the   file

     SAY strings must be enclosed in single or double quotes.  If
carriage return
  and  line  feed are needed in the string to be output,
you must 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.  An example is:

           ABORT BUSY
           ECHO OFF
           SAY "Dialling your ISP...0
           '' ATDT5551212
           TIMEOUT 120
           SAY "Waiting up to 2 minutes for connection ... "
           CONNECT ''
           SAY "0onnected, now logging in ...0
           ogin: account
           ssword: pass
           $ SAY "Logged in OK ...0
           etc ...

     This sequence will only present the SAY strings to the  user
and all the
     details  of  the script will remain hidden.  For example, if
the above
     script works, the user will see:

           Dialling your ISP...
           Waiting up to 2 minutes for connection ...
           Connected, now logging in ...
           Logged in OK ...

REPORT STRINGS    [Toc]    [Back]

     A report string is similar to the ABORT string.  The difference is 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 analysis
 of the report string logic occurs  in  conjunction  with
the 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
very useful;
     however, it is possible.

     The  report strings do not change the completion code of the

     These ``report'' strings may be specified in the script  using the REPORT
     sequence.   It  is written in the script as in the following

ogin: account

     This  sequence will expect nothing; and then send the string
     to dial the telephone.  The expected string is CONNECT.   If
the string
     CONNECT is received the remainder of the script is executed.
In addition
     the program will write to the expect-file the string  ``CONNECT'' plus any
     characters which follow it such as the connection rate.

CLR_REPORT STRINGS    [Toc]    [Back]

     This  sequence  allows  for  clearing  previously set REPORT
strings.  REPORT
     strings are kept in an array of a  pre-determined  size  (at
     time); CLR_REPORT will reclaim the space for cleared entries
so that new
     strings can use that space.

ECHO    [Toc]    [Back]

     The echo options controls whether the output from the  modem
is echoed to
     stderr.   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:

           ABORT   'BUSY'
           ABORT   'NO CARRIER'
           '' ATD1234567
           OK            ECHO    ON

           CONNECT            ogin:   account

     all output resulting from modem configuration and dialing is
not visible,
     but starting with the CONNECT (or BUSY) message,  everything
will be

HANGUP    [Toc]    [Back]

     The  HANGUP options control whether a modem hangup should be
considered as
     an error or not.  This option is useful in scripts for dialing systems
     which  will  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  (e.g.,  after
the first
     stage of logging in to a callback system), chat will continue running the
     script (e.g., waiting for the incoming call and second-stage
     prompt).   As  soon  as  the incoming call is connected, you
should use the
     HANGUP ON directive to reinstall normal hangup signal behavior.  Here is
     an example script:

           ABORT   'BUSY'
           '' ATD1234567
           OK              CONNECT              'Callback login:'

           HANGUP OFF
           ABORT "Bad Login"
           'Callback Password:' Call_back_password
           TIMEOUT 120
           CONNECT            HANGUP ON
           ABORT "NO CARRIER"
           ogin:--BREAK--ogin: real_account
           etc ...

TIMEOUT    [Toc]    [Back]

     The initial timeout  value  is  45  seconds.   This  may  be
changed using the
     -t parameter.

     The  following example illustrates how to change the timeout
value for the
     next expect string:

           ATZ OK ATDT5551212  CONNECT  TIMEOUT  10  ogin:--ogin:
           assword: hello2u2

     This  will  change the timeout to 10 seconds when it expects
the login:
     prompt.  The timeout is then changed to 5  seconds  when  it
looks for the
     password prompt.

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

SENDING EOT    [Toc]    [Back]

     The special reply string of EOT indicates that the chat program should
     send  an  EOT character to the remote.  This is normally the
     character sequence.  A return character is not sent  following the EOT.
     The  EOT sequence may be embedded into the send string using
the sequence

GENERATING BREAK    [Toc]    [Back]

     The special reply string of BREAK will cause 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 until
 you are able to receive a valid login prompt.  The break
sequence may
     be embedded into the send string using the _

ESCAPE SEQUENCES    [Toc]    [Back]

     The  expect  and reply strings may contain escape sequences.
All of the
     sequences are legal in the reply string.  Many are legal  in
the expect
     string.   Those  which  are not valid in the expect sequence
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 be a
             pair of either apostrophe or quote characters.

         Represents a backspace character.

                  the only method to  send  a  string  without  a
trailing return character.
   It  must  be at the end of the send string.
For example,
             the sequence "hello             l, o.  (Not valid in

            Delay  for  one second.  The program uses sleep(3) to
sleep for one
             second.  (Not valid in expect.)

     K      Insert a BREAK.  (Not valid in expect.)

          Send a newline or linefeed character.

          Send a NUL character.  The same sequence may be  represented by
              .  (Not valid in expect.)

Pause for a fraction of a second.  The delay is 1/10th of a second.
  (Not valid in expect.)

     q      Suppress writing the string to  the  syslog(3)  file.
The string
             ??????  is  written  to  the log in its place.  (Not
valid in expect.)

           Send or expect a carriage return.

          Represents a space character in the string.   This  may
be used
             when  it is not desirable to quote the strings which
             spaces.  The sequence 'HI TIM' and HIM are the same.

           Send or expect a tab character.

     \      Send or expect a backslash character.

     dd     Collapse  the  octal digits (ddd) into a single ASCII
character and
             send that character.  (Some characters are not valid
in expect.)

     ^C       Substitute  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.)

TERMINATION CODES    [Toc]    [Back]

     The  chat  program will terminate with the following completion codes:

     0       The normal termination of the program.   This  indicates that the
             script was executed without error to the normal conclusion.

     1       One or more of the parameters are invalid or an  expect string was
             too  large for the internal buffers.  This indicates
that the program
 was not properly executed.

     2       An error occurred during the execution of  the  program.  This may
             be due to a read or write operation failing for some
reason or
             chat receiving a signal such as SIGINT.

     3       A timeout event occurred when  there  was  an  ``expect'' string
             without having a ``-subsend'' string.  This may mean
that you did
             not program the script correctly for  the  condition
or that some
             unexpected  event  has  occurred  and  the  expected
string could not
             be found.

     4       The first string marked as an  ABORT  condition  occurred.

     5        The  second string marked as an ABORT condition occurred.

     6       The third string marked as an  ABORT  condition  occurred.

     7        The  fourth string marked as an ABORT condition occurred.

     ...     The other termination codes are also strings  marked
as an ABORT

     Using  the  termination  code,  it  is possible 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.

COPYRIGHT    [Toc]    [Back]

     The  chat  program is in the public domain.  This is not the
GNU public license.
  If it breaks then you get to keep both pieces.

OpenBSD     3.6                       September     27,      1997
[ Back ]
 Similar pages
Name OS Title
dxshutdown Tru64 Performs various types of automated system shutdown.
maze Tru64 an automated X11 demo repeatedly creating and solving a random maze
umodem OpenBSD USB modem support
addModem IRIX add a modem to the system
umodem FreeBSD USB modem support
getallpppinmodem IRIX get all PPP incoming modem entries
deleteModem IRIX delete a modem from the system
getallpppoutmodem IRIX get all PPP outgoing modem entries
modem HP-UX asynchronous serial modem line control
terminfo HP-UX printer, terminal, and modem capability database
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service