EXPECT(1)                                               EXPECT(1)

NAME
       expect  -  programmed  dialogue with interactive programs,
       Version 5

SYNOPSIS
       expect [ -dDinN ] [ -c cmds ] [ -[f|b] ] cmdfile ] [  args
       ]

INTRODUCTION
       Expect is a program that "talks" to other interactive pro-
       grams according to a script.  Following the script, Expect
       knows  what  can  be  expected from a program and what the
       correct response should be.  An interpreted language  pro-
       vides  branching  and  high-level  control  structures  to
       direct the dialogue.  In addition, the user can take  con-
       trol and interact directly when desired, afterward return-
       ing control to the script.

       Expectk is a mixture of Expect and Tk.   It  behaves  just
       like  Expect  and  Tk's  wish.   Expect  can  also be used
       directly in C or C++ (that is, without Tcl).   See  libex-
       pect(3).

       The  name  "Expect"  comes  from  the  idea of send/expect
       sequences popularized by uucp, kermit and other modem con-
       trol programs.  However unlike uucp, Expect is generalized
       so that it can be run as a  user-level  command  with  any
       program  and  task  in  mind.  Expect can actually talk to
       several programs at the same time.

       For example, here are some things Expect can do:

              o   Cause your computer to dial you back,  so  that
                  you can login without paying for the call.

              o   Start  a  game (e.g., rogue) and if the optimal
                  configuration doesn't appear, restart it (again
                  and  again)  until it does, then hand over con-
                  trol to you.

              o   Run fsck, and in  response  to  its  questions,
                  answer "yes", "no" or give control back to you,
                  based on predetermined criteria.

              o   Connect to another network or  BBS  (e.g.,  MCI
                  Mail,  CompuServe)  and  automatically retrieve
                  your mail so that it appears as if it was orig-
                  inally sent to your local system.

              o   Carry environment variables, current directory,
                  or any kind of information across rlogin,  tel-
                  net, tip, su, chgrp, etc.

       There  are  a variety of reasons why the shell cannot per-
       form these tasks.  (Try, you'll see.)   All  are  possible
       with Expect.

       In general, Expect is useful for running any program which
       requires interaction between the  program  and  the  user.
       All that is necessary is that the interaction can be char-
       acterized programmatically.  Expect can also give the user
       back  control  (without  halting  the  program  being con-
       trolled) if desired.  Similarly, the user can return  con-
       trol to the script at any time.

USAGE
       Expect  reads  cmdfile  for a list of commands to execute.
       Expect may also be invoked  implicitly  on  systems  which
       support  the #! notation by marking the script executable,
       and making the first line in your script:

           #!/usr/local/bin/expect -f

       Of course, the path must accurately describe where  Expect
       lives.  /usr/local/bin is just an example.

       The  -c  flag prefaces a command to be executed before any
       in the script.  The command should be  quoted  to  prevent
       being  broken  up  by  the shell.  This option may be used
       multiple times.  Multiple commands may be executed with  a
       single  -c  by  separating them with semicolons.  Commands
       are executed  in  the  order  they  appear.   (When  using
       Expectk, this option is specified as -command.)

       The  -d flag enables some diagnostic output, which primar-
       ily reports internal activity of commands such  as  expect
       and   interact.    This   flag  has  the  same  effect  as
       "exp_internal 1" at the beginning  of  an  Expect  script,
       plus  the  version of Expect is printed.  (The strace com-
       mand is useful for tracing statements, and the trace  com-
       mand  is  useful for tracing variable assignments.)  (When
       using Expectk, this option is specified as -diag.)

       The -D flag enables an interactive debugger.   An  integer
       value  should  follow.   The  debugger  will  take control
       before the next Tcl procedure if the value is non-zero  or
       if  a  ^C  is  pressed  (or  a breakpoint is hit, or other
       appropriate debugger command appears in the script).   See
       the  README  file or SEE ALSO (below) for more information
       on the debugger.  (When  using  Expectk,  this  option  is
       specified as -Debug.)

       The  -f  flag  prefaces a file from which to read commands
       from.  The flag itself is optional as it  is  only  useful
       when  using  the  #!  notation  (see above), so that other
       arguments may be supplied  on  the  command  line.   (When
       using Expectk, this option is specified as -file.)

       By  default, the command file is read into memory and exe-
       cuted in its entirety.  It is  occasionally  desirable  to
       read files one line at a time.  For example, stdin is read
       this way.  In order to force arbitrary files to be handled
       this  way,  use  the  -b  flag.  (When using Expectk, this
       option is specified as -buffer.)

       If the string "-" is  supplied  as  a  filename,  standard
       input  is  read  instead.   (Use "./-" to read from a file
       actually named "-".)

       The -i flag causes Expect to interactively prompt for com-
       mands  instead  of reading them from a file.  Prompting is
       terminated via the exit command or upon EOF.   See  inter-
       preter  (below)  for  more  information.  -i is assumed if
       neither a command  file  nor  -c  is  used.   (When  using
       Expectk, this option is specified as -interactive.)

       -- may be used to delimit the end of the options.  This is
       useful if you want to pass an option-like argument to your
       script  without  it being interpreted by Expect.  This can
       usefully be placed in the #! line to prevent any flag-like
       interpretation by Expect.  For example, the following will
       leave the original arguments (including the  script  name)
       in the variable argv.

           #!/usr/local/bin/expect --

       Note  that  the  usual getopt(3) and execve(2) conventions
       must be observed when adding arguments to the #! line.

       The file $exp_library/expect.rc is  sourced  automatically
       if  present,  unless  the  -N  flag  is used.  (When using
       Expectk, this option is specified as -NORC.)   Immediately
       after  this,  the  file  ~/.expect.rc is sourced automati-
       cally, unless the -n flag is  used.   If  the  environment
       variable  DOTDIR  is defined, it is treated as a directory
       and .expect.rc is read from there.  (When  using  Expectk,
       this  option is specified as -norc.)  This sourcing occurs
       only after executing any -c flags.

       -v causes Expect to print its  version  number  and  exit.
       (The  corresponding  flag in Expectk, which uses long flag
       names, is -version.)

       Optional args are constructed into a list  and  stored  in
       the  variable  named  argv.   argc  is  initialized to the
       length of argv.

       argv0 is defined to be the name of the script  (or  binary
       if  no script is used).  For example, the following prints
       out the name of the script and the first three arguments:

           send_user "$argv0 [lrange $argv 0 2]\n"

COMMANDS
       Expect uses Tcl (Tool  Command  Language).   Tcl  provides
       control flow (e.g., if, for, break), expression evaluation
       and several other features such  as  recursion,  procedure
       definition,  etc.   Commands  used  here  but  not defined
       (e.g., set, if,  exec)  are  Tcl  commands  (see  tcl(3)).
       Expect  supports  additional  commands,  described  below.
       Unless otherwise  specified,  commands  return  the  empty
       string.

       Commands  are  listed  alphabetically  so that they can be
       quickly located.  However, new users may find it easier to
       start  by reading the descriptions of spawn, send, expect,
       and interact, in that order.

       Note that the best  introduction  to  the  language  (both
       Expect and Tcl) is provided in the book "Exploring Expect"
       (see SEE ALSO below).  Examples are included in  this  man
       page  but  they  are  very  limited since this man page is
       meant primarily as reference material.

       Note that in the text of this man page, "Expect"  with  an
       uppercase  "E" refers to the Expect program while "expect"
       with a lower-case "e" refers to the expect command  within
       the Expect program.)

       close [-slave] [-onexec 0|1] [-i spawn_id]
             closes  the connection to the current process.  Most
             interactive programs will detect EOF on their  stdin
             and  exit;  thus  close usually suffices to kill the
             process as well.  The -i flag declares  the  process
             to close corresponding to the named spawn_id.

             Both  expect  and interact will detect when the cur-
             rent process exits and implicitly do a  close.   But
             if  you  kill the process by, say, "exec kill $pid",
             you will need to explicitly call close.

             The -onexec flag determines  whether  the  spawn  id
             will  be  closed  in any new spawned processes or if
             the process is overlayed.  To leave a spawn id open,
             use  the  value  0.   A  non-zero integer value will
             force the spawn closed (the default) in any new pro-
             cesses.

             The -slave flag closes the slave associated with the
             spawn id.  (See "spawn -pty".)  When the  connection
             is closed, the slave is automatically closed as well
             if still open.

             No matter whether the connection is  closed  implic-
             itly or explicitly, you should call wait to clear up
             the corresponding kernel process slot.   close  does
             not call wait since there is no guarantee that clos-
             ing a process connection will cause it to exit.  See
             wait below for more info.

       debug [[-now] 0|1]
             controls a Tcl debugger allowing you to step through
             statements, set breakpoints, etc.

             With no arguments, a 1 is returned if  the  debugger
             is not running, otherwise a 0 is returned.

             With  a 1 argument, the debugger is started.  With a
             0 argument, the debugger is stopped.  If a  1  argu-
             ment  is  preceded by the -now flag, the debugger is
             started immediately (i.e.,  in  the  middle  of  the
             debug  command  itself).  Otherwise, the debugger is
             started with the next Tcl statement.

             The debug command does not change any  traps.   Com-
             pare  this  to starting Expect with the -D flag (see
             above).

             See the README file or SEE  ALSO  (below)  for  more
             information on the debugger.

       disconnect
             disconnects  a forked process from the terminal.  It
             continues running in the background.  The process is
             given its own process group (if possible).  Standard
             I/O is redirected to /dev/null.

             The following fragment uses disconnect  to  continue
             running the script in the background.

                 if [fork]!=0 exit
                 disconnect
                 . . .

             The following script reads a password, and then runs
             a program every hour that demands  a  password  each
             time it is run.  The script supplies the password so
             that you only have to type it once.  (See  the  stty
             command  which demonstrates how to turn off password
             echoing.)

                 send_user "password?\ "
                 expect_user -re "(.*)\n"
                 for {} 1 {} {
                     if [fork]!=0 {sleep 3600;continue}
                     disconnect
                     spawn priv_prog
                     expect Password:
                     send "$expect_out(1,string)\r"
                     . . .
                     exit
                 }

             An advantage to  using  disconnect  over  the  shell
             asynchronous  process feature (&) is that Expect can
             save the terminal parameters prior to disconnection,
             and  then  later  apply  them  to new ptys.  With &,
             Expect does not have a chance to read the terminal's
             parameters  since  the  terminal  is already discon-
             nected by the time Expect receives control.

       exit [-opts] [status]
             causes Expect to exit or otherwise prepare to do so.

             The -onexit flag causes the next argument to be used
             as an exit handler.  Without an argument,  the  cur-
             rent exit handler is returned.

             The  -noexit  flag  causes Expect to prepare to exit
             but stop short of actually returning control to  the
             operating  system.  The user-defined exit handler is
             run as well as Expect's own internal  handlers.   No
             further Expect commands should be executed.  This is
             useful if you are  running  Expect  with  other  Tcl
             extensions.   The current interpreter (and main win-
             dow if in the Tk environment) remain so  that  other
             Tcl  extensions  can  clean up.  If Expect's exit is
             called again (however this might  occur),  the  han-
             dlers are not rerun.

             Upon  exiting,  all connections to spawned processes
             are closed.  Closure will be detected as an  EOF  by
             spawned  processes.   exit  takes  no  other actions
             beyond what  the  normal  _exit(2)  procedure  does.
             Thus,  spawned  processes  that do not check for EOF
             may continue to run.  (A variety of  conditions  are
             important  to determining, for example, what signals
             a spawned process will be sent, but these  are  sys-
             tem-dependent,  typically documented under exit(3).)
             Spawned processes  that  continue  to  run  will  be
             inherited by init.

             status  (or  0  if not specified) is returned as the
             exit status of Expect.  exit is implicitly  executed
             if the end of the script is reached.

       exp_continue
             The  command  exp_continue  allows  expect itself to
             continue executing rather than returning as it  nor-
             mally would.  (See expect for more information.)

       exp_internal [-f file] value
             causes  further commands to send diagnostic informa-
             tion internal to Expect to stderr if value  is  non-
             zero.   This  output is disabled if value is 0.  The
             diagnostic  information  includes  every   character
             received,  and  every attempt made to match the cur-
             rent output against the patterns.

             If the optional file is  supplied,  all  normal  and
             debugging output is written to that file (regardless
             of the value of  value).   Any  previous  diagnostic
             output file is closed.

             The  -info  flag  causes  exp_internal  to  return a
             description of the most  recent  non-info  arguments
             given.

       exp_open [args] [-i spawn_id]
             returns  a  Tcl  file identifier that corresponds to
             the original spawn id.  The file identifier can then
             be  used as if it were opened by Tcl's open command.
             (The spawn id should no  longer  be  used.   A  wait
             should not be executed.

             The  -leaveopen  flag  leaves  the spawn id open for
             access through Expect commands.  A wait must be exe-
             cuted on the spawn id.

       exp_pid [-i spawn_id]
             returns  the  process  id  corresponding to the cur-
             rently spawned process.  If the -i flag is used, the
             pid  returned corresponds to that of the given spawn
             id.

       exp_send
             is an alias for send.

       exp_send_error
             is an alias for send_error.

       exp_send_log
             is an alias for send_log.

       exp_send_tty
             is an alias for send_tty.

       exp_send_user
             is an alias for send_user.

       exp_version [[-exit] version]
             is useful for assuring that the script is compatible
             with the current version of Expect.

             With  no arguments, the current version of Expect is
             returned.  This version may then be encoded in  your
             script.  If you actually know that you are not using
             features of recent versions, you can specify an ear-
             lier version.

             Versions consist of three numbers separated by dots.
             First is the major number.  Scripts written for ver-
             sions  of  Expect with a different major number will
             almost certainly not work.  exp_version  returns  an
             error if the major numbers do not match.

             Second  is  the minor number.  Scripts written for a
             version with a greater minor number than the current
             version  may  depend upon some new feature and might
             not run.  exp_version returns an error if the  major
             numbers  match,  but  the  script  minor  number  is
             greater than that of the running Expect.

             Third is a number that plays no part in the  version
             comparison.   However,  it  is  incremented when the
             Expect software distribution is changed in any  way,
             such as by additional documentation or optimization.
             It is reset to 0 upon each new minor version.

             With the -exit flag,  Expect  prints  an  error  and
             exits if the version is out of date.

       expect [[-opts] pat1 body1] ... [-opts] patn [bodyn]
             waits  until  one of the patterns matches the output
             of a spawned process, a specified  time  period  has
             passed,  or  an  end-of-file  is seen.  If the final
             body is empty, it may be omitted.

             Patterns from the most recent expect_before  command
             are implicitly used before any other patterns.  Pat-
             terns from the most recent expect_after command  are
             implicitly used after any other patterns.

             If  the  arguments  to  the  entire expect statement
             require more than one line, all the arguments may be
             "braced"  into  one  so as to avoid terminating each
             line with a backslash.  In this one case, the  usual
             Tcl substitutions will occur despite the braces.

             If  a  pattern is the keyword eof, the corresponding
             body is executed upon end-of-file.  If a pattern  is
             the  keyword timeout, the corresponding body is exe-
             cuted upon timeout.  If no timeout keyword is  used,
             an  implicit  null  action is executed upon timeout.
             The default timeout period is 10 seconds but may  be
             set,  for example to 30, by the command "set timeout
             30".  An infinite timeout may be designated  by  the
             value  -1.  If a pattern is the keyword default, the
             corresponding body is executed upon  either  timeout
             or end-of-file.

             If a pattern matches, then the corresponding body is
             executed.  expect returns the result of the body (or
             the  empty  string  if  no pattern matched).  In the
             event that multiple patterns match, the one  appear-
             ing first is used to select a body.

             Each time new output arrives, it is compared to each
             pattern in the order they are listed.  Thus, you may
             test  for absence of a match by making the last pat-
             tern something  guaranteed  to  appear,  such  as  a
             prompt.  In situations where there is no prompt, you
             must use timeout (just like you would  if  you  were
             interacting manually).

             Patterns  are  specified in three ways.  By default,
             patterns are specified as with  Tcl's  string  match
             command.  (Such patterns are also similar to C-shell
             regular expressions usually referred  to  as  "glob"
             patterns).   The -gl flag may may be used to protect
             patterns that might  otherwise  match  expect  flags
             from  doing  so.   Any  pattern beginning with a "-"
             should be protected this way.  (All strings starting
             with "-" are reserved for future options.)

             For example, the following fragment looks for a suc-
             cessful login.  (Note that abort is presumed to be a
             procedure defined elsewhere in the script.)

                 expect {
                     busy               {puts busy\n ; exp_continue}
                     failed             abort
                     "invalid password" abort
                     timeout            abort
                     connected
                 }

             Quotes  are necessary on the fourth pattern since it
             contains a space, which would otherwise separate the
             pattern  from  the  action.   Patterns with the same
             action (such as the 3rd and 4th) require listing the
             actions  again.   This can be avoid by using regexp-
             style patterns (see  below).   More  information  on
             forming  glob-style patterns can be found in the Tcl
             manual.

             Regexp-style patterns follow the syntax  defined  by
             Tcl's  regexp  (short for "regular expression") com-
             mand.  regexp patterns are introduced with the  flag
             -re.   The previous example can be rewritten using a
             regexp as:

                 expect {
                     busy       {puts busy\n ; exp_continue}
                     -re "failed|invalid password" abort
                     timeout    abort
                     connected
                 }

             Both types of patterns are "unanchored".  This means
             that  patterns  do  not  have  to  match  the entire
             string, but can begin and end the match anywhere  in
             the  string  (as  long  as everything else matches).
             Use ^ to match the beginning of a string, and  $  to
             match the end.  Note that if you do not wait for the
             end of a string, your responses can easily end up in
             the middle of the string as they are echoed from the
             spawned  process.   While  still  producing  correct
             results,  the  output can look unnatural.  Thus, use
             of $ is encouraged if you can exactly  describe  the
             characters at the end of a string.

             Note  that  in  many  editors, the ^ and $ match the
             beginning and end of  lines  respectively.  However,
             because  expect  is not line oriented, these charac-
             ters match the beginning and end  of  the  data  (as
             opposed  to  lines) currently in the expect matching
             buffer.  (Also, see the note below on "system  indi-
             gestion.")

             The  -ex flag causes the pattern to be matched as an
             "exact" string.  No interpretation of *, ^,  etc  is
             made  (although the usual Tcl conventions must still
             be observed).  Exact patterns are always unanchored.

             The  -nocase flag causes uppercase characters of the
             output to compare as if they were lowercase  charac-
             ters.  The pattern is not affected.

             While reading output, more than 2000 bytes can force
             earlier  bytes  to  be  "forgotten".   This  may  be
             changed  with  the  function  match_max.  (Note that
             excessively large values can slow down  the  pattern
             matcher.)   If  patlist  is  full_buffer, the corre-
             sponding body is executed if  match_max  bytes  have
             been  received  and  no other patterns have matched.
             Whether or not the full_buffer keyword is used,  the
             forgotten      characters     are     written     to
             expect_out(buffer).

             If patlist  is  the  keyword  null,  and  nulls  are
             allowed  (via  the remove_nulls command), the corre-
             sponding body is executed if a  single  ASCII  0  is
             matched.   It  is  not possible to match 0 bytes via
             glob or regexp patterns.

             Upon matching a pattern (or eof or full_buffer), any
             matching and previously unmatched output is saved in
             the variable expect_out(buffer).   Up  to  9  regexp
             substring   matches   are  saved  in  the  variables
             expect_out(1,string)  through  expect_out(9,string).
             If  the  -indices flag is used before a pattern, the
             starting and ending indices (in a form suitable  for
             lrange)  of  the  10 strings are stored in the vari-
             ables  expect_out(X,start)   and   expect_out(X,end)
             where  X  is  a  digit, corresponds to the substring
             position in the buffer.  0 refers to  strings  which
             matched the entire pattern and is generated for glob
             patterns as well as regexp patterns.   For  example,
             if  a  process  has produced output of "abcdefgh\n",
             the result of:

                 expect "cd"

             is as if the following statements had executed:

                 set expect_out(0,string) cd
                 set expect_out(buffer) abcd

             and "efgh\n" is left in the  output  buffer.   If  a
             process  produced  the  output "abbbcabkkkka\n", the
             result of:

                 expect -indices -re "b(b*).*(k+)"

             is as if the following statements had executed:

                 set expect_out(0,start) 1
                 set expect_out(0,end) 10
                 set expect_out(0,string) bbbcabkkkk
                 set expect_out(1,start) 2
                 set expect_out(1,end) 3
                 set expect_out(1,string) bb
                 set expect_out(2,start) 10
                 set expect_out(2,end) 10
                 set expect_out(2,string) k
                 set expect_out(buffer) abbbcabkkkk

             and "a\n" is left in the output buffer.  The pattern
             "*"  (and  -re  ".*")  will  flush the output buffer
             without reading any more output from the process.

             Normally,  the  matched  output  is  discarded  from
             Expect's internal buffers.  This may be prevented by
             prefixing a pattern with the -notransfer flag.  This
             flag  is especially useful in experimenting (and can
             be abbreviated to "-n" for convenience while experi-
             menting).

             The spawn id associated with the matching output (or
             eof     or     full_buffer)     is     stored     in
             expect_out(spawn_id).

             The  -timeout flag causes the current expect command
             to use the following value as a timeout  instead  of
             using the value of the timeout variable.

             By default, patterns are matched against output from
             the current process, however the  -i  flag  declares
             the  output  from the named spawn_id list be matched
             against any following patterns (up to the next  -i).
             The spawn_id list should either be a whitespace sep-
             arated list of spawn_ids or a variable referring  to
             such a list of spawn_ids.

             For  example,  the following example waits for "con-
             nected"  from  the  current  process,   or   "busy",
             "failed"  or  "invalid  password"  from the spawn_id
             named by $proc2.

                 expect {
                     -i $proc2 busy {puts busy\n ; exp_continue}
                     -re "failed|invalid password" abort
                     timeout abort
                     connected
                 }

             The value of the global variable any_spawn_id may be
             used  to  match  patterns  to any spawn_ids that are
             named with all other -i flags in the current  expect
             command.   The spawn_id from a -i flag with no asso-
             ciated  pattern  (i.e.,  followed   immediately   by
             another  -i) is made available to any other patterns
             in  the  same   expect   command   associated   with
             any_spawn_id.

             The -i flag may also name a global variable in which
             case the variable is read for a list of  spawn  ids.
             The  variable  is  reread whenever it changes.  This
             provides a way of changing the I/O source while  the
             command  is  in  execution.  Spawn ids provided this
             way are called "indirect" spawn ids.

             Actions such as break  and  continue  cause  control
             structures  (i.e., for, proc) to behave in the usual
             way.  The command exp_continue allows expect  itself
             to  continue  executing  rather than returning as it
             normally would.

             This  is  useful  for  avoiding  explicit  loops  or
             repeated  expect  statements.  The following example
             is part of  a  fragment  to  automate  rlogin.   The
             exp_continue  avoids having to write a second expect
             statement (to look for  the  prompt  again)  if  the
             rlogin prompts for a password.

                 expect {
                     Password: {
                         stty -echo
                         send_user "password (for $user) on $host: "
                         expect_user -re "(.*)\n"
                         send_user "\n"
                         send "$expect_out(1,string)\r"
                         stty echo
                         exp_continue
                     } incorrect {
                         send_user "invalid password or account\n"
                         exit
                     } timeout {
                         send_user "connection to $host timed out\n"
                         exit
                     } eof {
                         send_user \
                             "connection to host failed: $expect_out(buffer)"
                         exit
                     } -re $prompt
                 }

             For  example,  the  following  fragment might help a
             user guide an interaction that  is  already  totally
             automated.   In  this case, the terminal is put into
             raw mode.  If the user presses "+",  a  variable  is
             incremented.  If "p" is pressed, several returns are
             sent to the process, perhaps to poke it in some way,
             and  "i"  lets  the  user interact with the process,
             effectively stealing away control from  the  script.
             In  each  case,  the exp_continue allows the current
             expect to continue pattern matching after  executing
             the current action.

                 stty raw -echo
                 expect_after {
                     -i $user_spawn_id
                     "p" {send "\r\r\r"; exp_continue}
                     "+" {incr foo; exp_continue}
                     "i" {interact; exp_continue}
                     "quit" exit
                 }

             By  default,  exp_continue resets the timeout timer.
             The timer  is  not  restarted,  if  exp_continue  is
             called with the -continue_timer flag.

       expect_after [expect_args]
             works  identically  to the expect_before except that
             if patterns from both expect  and  expect_after  can
             match,   the   expect  pattern  is  used.   See  the
             expect_before command for more information.

       expect_background [expect_args]
             takes the  same  arguments  as  expect,  however  it
             returns  immediately.   Patterns are tested whenever
             new input arrives.  The pattern timeout and  default
             are   meaningless   to   expect_background  and  are
             silently  discarded.   Otherwise,  the  expect_back-
             ground  command  uses expect_before and expect_after
             patterns just like expect does.

             When expect_background actions are being  evaluated,
             background  processing  for  the  same  spawn  id is
             blocked.  Background processing  is  unblocked  when
             the  action  completes.  While background processing
             is blocked, it is  possible  to  do  a  (foreground)
             expect on the same spawn id.

             It  is  not  possible  to execute an expect while an
             expect_background is  unblocked.   expect_background
             for  a particular spawn id is deleted by declaring a
             new  expect_background  with  the  same  spawn   id.
             Declaring  expect_background with no pattern removes
             the given spawn id from the ability  to  match  pat-
             terns in the background.

       expect_before [expect_args]
             takes  the  same  arguments  as  expect,  however it
             returns immediately.  Pattern-action pairs from  the
             most recent expect_before with the same spawn id are
             implicitly added to any following  expect  commands.
             If  a  pattern  matches,  it is treated as if it had
             been specified in the expect command itself, and the
             associated  body  is  executed in the context of the
             expect command.  If patterns from both expect_before
             and  expect  can match, the expect_before pattern is
             used.

             If no pattern is specified,  the  spawn  id  is  not
             checked for any patterns.

             Unless  overridden  by a -i flag, expect_before pat-
             terns match against the spawn id defined at the time
             that  the  expect_before  command  was executed (not
             when its pattern is matched).

             The -info flag causes expect_before  to  return  the
             current  specifications  of  what  patterns  it will
             match.  By default, it reports on the current  spawn
             id.  An optional spawn id specification may be given
             for information on that spawn id.  For example

                 expect_before -info -i $proc

             At most one spawn id  specification  may  be  given.
             The  flag -indirect suppresses direct spawn ids that
             come only from indirect specifications.

             Instead of a spawn id specification, the flag "-all"
             will cause "-info" to report on all spawn ids.

             The  output  of  the -info flag can be reused as the
             argument to expect_before.

       expect_tty [expect_args]
             is like expect but it reads characters from /dev/tty
             (i.e.  keystrokes from the user).  By default, read-
             ing is performed in cooked mode.  Thus,  lines  must
             end  with  a return in order for expect to see them.
             This may be changed via stty (see the  stty  command
             below).

       expect_user [expect_args]
             is  like  expect  but it reads characters from stdin
             (i.e. keystrokes from the user).  By default,  read-
             ing  is  performed in cooked mode.  Thus, lines must
             end with a return in order for expect to  see  them.
             This  may  be changed via stty (see the stty command
             below).

       fork  creates a new process.  The new process is an  exact
             copy  of  the  current  Expect process.  On success,
             fork returns  0  to  the  new  (child)  process  and
             returns  the  process ID of the child process to the
             parent process.  On failure (invariably due to  lack
             of   resources,  e.g.,  swap  space,  memory),  fork
             returns -1 to the parent process, and no child  pro-
             cess is created.

             Forked  processes  exit  via  the exit command, just
             like the original  process.   Forked  processes  are
             allowed  to  write  to the log files.  If you do not
             disable debugging or logging in  most  of  the  pro-
             cesses, the result can be confusing.

             Some pty implementations may be confused by multiple
             readers and writers, even momentarily.  Thus, it  is
             safest to fork before spawning processes.

       interact [string1 body1] ... [stringn [bodyn]]
             gives control of the current process to the user, so
             that keystrokes are sent to the current process, and
             the  stdout  and  stderr  of the current process are
             returned.

             String-body pairs may be specified as arguments,  in
             which case the body is executed when the correspond-
             ing string is entered.  (By default, the  string  is
             not  sent to the current process.)   The interpreter
             command is assumed, if the final body is missing.

             If the arguments to the  entire  interact  statement
             require more than one line, all the arguments may be
             "braced" into one so as to  avoid  terminating  each
             line  with a backslash.  In this one case, the usual
             Tcl substitutions will occur despite the braces.

             For example, the  following  command  runs  interact
             with  the following string-body pairs defined:  When
             ^Z is pressed, Expect  is  suspended.   (The  -reset
             flag  restores  the  terminal  modes.)   When  ^A is
             pressed, the user sees "you typed a  control-A"  and
             the  process  is  sent a ^A.  When $ is pressed, the
             user sees the date.   When  ^C  is  pressed,  Expect
             exits.   If  "foo"  is entered, the user sees "bar".
             When ~~ is  pressed,  the  Expect  interpreter  runs
             interactively.

                 set CTRLZ \032
                 interact {
                     -reset $CTRLZ {exec kill -STOP [pid]}
                     \001   {send_user "you typed a control-A\n";
                             send "\001"
                            }
                     $      {send_user "The date is [exec date]."}
                     \003   exit
                     foo    {send_user "bar"}
                     ~~
                 }

             In  string-body  pairs,  strings  are matched in the
             order they are listed as  arguments.   Strings  that
             partially  match are not sent to the current process
             in anticipation of the remainder coming.  If charac-
             ters  are then entered such that there can no longer
             possibly be a match, only the  part  of  the  string
             will  be  sent  to  the process that cannot possibly
             begin another match.  Thus, strings  that  are  sub-
             strings  of  partial matches can match later, if the
             original strings that was  attempting  to  be  match
             ultimately fails.

             By  default,  string  matching is exact with no wild
             cards.  (In contrast, the expect command uses  glob-
             style  patterns  by  default.)   The -ex flag may be
             used to protect patterns that might otherwise  match
             interact flags from doing so.  Any pattern beginning
             with a "-" should be  protected  this  way.     (All
             strings  starting  with  "-" are reserved for future
             options.)

             The -re flag forces the string to be interpreted  as
             a regexp-style pattern.  In this case, matching sub-
             strings are stored in the variable interact_out sim-
             ilarly  to  the  way expect stores its output in the
             variable expect_out.  The -indices flag is similarly
             supported.

             The  pattern  eof  introduces an action that is exe-
             cuted upon end-of-file.  A separate eof pattern  may
             also  follow  the  -output  flag in which case it is
             matched if an eof is detected while writing  output.
             The default eof action is "return", so that interact
             simply returns upon any EOF.

             The pattern timeout introduces a  timeout  (in  sec-
             onds)  and  action that is executed after no charac-
             ters have been read for a given time.   The  timeout
             pattern  applies to the most recently specified pro-
             cess.  There is no  default  timeout.   The  special
             variable  "timeout" (used by the expect command) has
             no affect on this timeout.

             For example, the following statement could  be  used
             to  autologout users who have not typed anything for
             an hour but who still get frequent system messages:

                 interact -input $user_spawn_id timeout 3600 return -output \
                     $spawn_id

             If the pattern is the keyword null,  and  nulls  are
             allowed  (via  the remove_nulls command), the corre-
             sponding body is executed if a  single  ASCII  0  is
             matched.   It  is  not possible to match 0 bytes via
             glob or regexp patterns.

             Prefacing a pattern with the flag -iwrite causes the
             variable  interact_out(spawn_id)  to  be  set to the
             spawn_id which matched the pattern (or eof).

             Actions such as break  and  continue  cause  control
             structures  (i.e., for, proc) to behave in the usual
             way.  However return causes interact  to  return  to
             its  caller,  while  inter_return causes interact to
             cause a return in its caller.  For example, if "proc
             foo"  called interact which then executed the action
             inter_return, proc foo would  return.   (This  means
             that  if  interact  calls  interpreter interactively
             typing return will cause the interact  to  continue,
             while inter_return will cause the interact to return
             to its caller.)

             During interact, raw mode is used so that all  char-
             acters may be passed to the current process.  If the
             current process does not catch job control  signals,
             it  will stop if sent a stop signal (by default ^Z).
             To restart it, send a continue signal  (such  as  by
             "kill  -CONT  <pid>").  If you really want to send a
             SIGSTOP to such a process (by ^Z), consider spawning
             csh  first  and  then  running your program.  On the
             other hand, if you want to send a SIGSTOP to  Expect
             itself,  first  press the escape character, and then
             press ^Z.

             String-body pairs can be used  as  a  shorthand  for
             avoiding having to enter the interpreter and execute
             commands interactively.  The previous terminal  mode
             is  used  while  the  body  of a string-body pair is
             being executed.

             For speed, actions execute in raw mode  by  default.
             The  -reset  flag resets the terminal to the mode it
             had before interact was executed (invariably, cooked
             mode).   Note  that characters entered when the mode
             is being switched may be lost (an  unfortunate  fea-
             ture  of  the terminal driver on some systems).  The
             only reason to use -reset is if your action  depends
             on running in cooked mode.

             The  -echo flag sends characters that match the fol-
             lowing pattern back to the  process  that  generated
             them  as each character is read.  This may be useful
             when the user needs to see feedback  from  partially
             typed patterns.

             If a pattern is being echoed but eventually fails to
             match, the characters are sent to the  spawned  pro-
             cess.   If the spawned process then echoes them, the
             user will see the characters twice.  -echo is proba-
             bly only appropriate in situations where the user is
             unlikely to not complete the pattern.  For  example,
             the  following  excerpt is from rftp, the recursive-
             ftp script, where the user is prompted to enter  ~g,
             ~p,  or  ~l, to get, put, or list the current direc-
             tory recursively.  These are so far  away  from  the
             normal  ftp  commands,  that the user is unlikely to
             type ~ followed by anything else, except mistakenly,
             in  which  case,  they'll  probably  just ignore the
             result anyway.

                 interact {
                     -echo ~g {getcurdirectory 1}
                     -echo ~l {getcurdirectory 0}
                     -echo ~p {putcurdirectory}
                 }

             The -nobuffer flag sends characters that  match  the
             following  pattern on to the output process as char-
             acters are read.

             This is useful when you wish to let a  program  echo
             back  the pattern.  For example, the following might
             be used to monitor where  a  person  is  dialing  (a
             Hayes-style  modem).   Each  time  "atd" is seen the
             script logs the rest of the line.

                 proc lognumber {} {
                     interact -nobuffer -re "(.*)\r" return
                     puts $log "[exec date]: dialed $interact_out(1,string)"
                 }

                 interact -nobuffer "atd" lognumber

             During  interact,  previous  use  of   log_user   is
             ignored.   In  particular,  interact  will force its
             output to be logged (sent to  the  standard  output)
             since it is presumed the user doesn't wish to inter-
             act blindly.

             The -o flag causes any following key-body  pairs  to
             be  applied  to  the  output of the current process.
             This can be useful, for example, when  dealing  with
             hosts  that send unwanted characters during a telnet
             session.

             By default, interact expects the user to be  writing
             stdin  and  reading  stdout  of  the  Expect process
             itself.  The -u flag  (for  "user")  makes  interact
             look  for the user as the process named by its argu-
             ment (which must be a spawned id).

             This allows two unrelated  processes  to  be  joined
             together  without using an explicit loop.  To aid in
             debugging, Expect diagnostics always  go  to  stderr
             (or  stdout for certain logging and debugging infor-
             mation).  For the same reason, the interpreter  com-
             mand will read interactively from stdin.

             For  example, the following fragment creates a login
             process.  Then it dials the user  (not  shown),  and
             finally  connects  the two together.  Of course, any
             process may be substituted for login.  A shell,  for
             example,  would  allow the user to work without sup-
             plying an account and password.

                 spawn login
                 set login $spawn_id
                 spawn tip modem
                 # dial back out to user
                 # connect user to login
                 interact -u $login

             To send output  to  multiple  processes,  list  each
             spawn id list prefaced by a -output flag.  Input for
             a group of output spawn ids may be determined  by  a
             spawn  id  list  prefaced  by  a -input flag.  (Both
             -input and -output may take lists in the  same  form
             as  the  -i  flag in the expect command, except that
             any_spawn_id is not meaningful  in  interact.)   All
             following  flags  and strings (or patterns) apply to
             this input until another -input flag appears.  If no
             -input     appears,    -output    implies    "-input
             $user_spawn_id -output".  (Similarly, with  patterns
             that  do  not have -input.)  If one -input is speci-
             fied, it  overrides  $user_spawn_id.   If  a  second
             -input  is specified, it overrides $spawn_id.  Addi-
             tional -input flags may be specified.

             The two implied input processes  default  to  having
             their    outputs    specified   as   $spawn_id   and
             $user_spawn_id  (in  reverse).   If  a  -input  flag
             appears  with  no -output flag, characters from that
             process are discarded.

             The -i flag introduces a replacement for the current
             spawn_id  when  no other -input or -output flags are
             used.  A -i flag implies a -o flag.

             It is possible to  change  the  processes  that  are
             being  interacted  with by using indirect spawn ids.
             (Indirect spawn ids are described in the section  on
             the  expect  command.)   Indirect  spawn  ids may be
             specified with the -i, -u, -input, or -output flags.

       interpreter
             causes  the  user  to  be interactively prompted for
             Expect and Tcl commands.  The result of each command
             is printed.

             Actions  such  as  break  and continue cause control
             structures (i.e., for, proc) to behave in the  usual
             way.  However return causes interpreter to return to
             its caller, while inter_return causes interpreter to
             cause a return in its caller.  For example, if "proc
             foo" called  interpreter  which  then  executed  the
             action  inter_return,  proc  foo  would return.  Any
             other command causes interpreter to continue prompt-
             ing for new commands.

             By  default,  the prompt contains two integers.  The
             first integer describes the depth of the  evaluation
             stack  (i.e.,  how  many  times  Tcl_Eval  has  been
             called).  The second  integer  is  the  Tcl  history
             identifier.   The  prompt  can  be set by defining a
             procedure  called  "prompt1"  whose   return   value
             becomes  the  next  prompt.  If a statement has open
             quotes, parens, braces,  or  brackets,  a  secondary
             prompt  (by  default  "+> ") is issued upon newline.
             The secondary prompt may be set by defining a proce-
             dure called "prompt2".

             During interpreter, cooked mode is used, even if the
             its caller was using raw mode.

       log_file [args] [[-a] file]
             If a filename is provided, log_file  will  record  a
             transcript  of the session (beginning at that point)
             in the file.  log_file will  stop  recording  if  no
             argument is given.  Any previous log file is closed.

             Instead of a filename, a Tcl file identifier may  be
             provided  by  using  the  -open or -leaveopen flags.
             This is similar to the spawn  command.   (See  spawn
             for more info.)

             The -a flag forces output to be logged that was sup-
             pressed by the log_user command.

             By default, the  log_file  command  appends  to  old
             files  rather  than  truncating them, for the conve-
             nience of being able to turn logging off and on mul-
             tiple  times in one session.  To truncate files, use
             the -noappend flag.

             The -info flag causes log_file to return a  descrip-
             tion of the most recent non-info arguments given.

       log_user -info|0|1
             By  default,  the  send/expect dialogue is logged to
             stdout (and a logfile if open).  The logging to std-
             out  is  disabled  by  the  command "log_user 0" and
             reenabled by "log_user 1".  Logging to  the  logfile
             is unchanged.

             The  -info flag causes log_user to return a descrip-
             tion of the most recent non-info arguments given.

       match_max [-d] [-i spawn_id] [size]
             defines the size  of  the  buffer  (in  bytes)  used
             internally  by  expect.   With no size argument, the
             current size is returned.

             With the -d flag, the default  size  is  set.   (The
             initial  default  is  2000.)   With the -i flag, the
             size is set for the named spawn id, otherwise it  is
             set for the current process.

       overlay [-# spawn_id] [-# spawn_id] [...] program [args]
             executes program args in place of the current Expect
             program, which terminates.  A bare  hyphen  argument
             forces  a  hyphen in front of the command name as if
             it was a login  shell.   All  spawn_ids  are  closed
             except  for  those  named  as  arguments.  These are
             mapped onto the named file identifiers.

             Spawn_ids are mapped to file identifiers for the new
             program to inherit.  For example, the following line
             runs chess and allows it to  be  controlled  by  the
             current process - say, a chess master.

                 overlay -0 $spawn_id -1 $spawn_id -2 $spawn_id chess

             This  is more efficient than "interact -u", however,
             it sacrifices the ability to do programmed  interac-
             tion  since  the Expect process is no longer in con-
             trol.

             Note  that  no  controlling  terminal  is  provided.
             Thus,  if  you  disconnect  or remap standard input,
             programs that do job control  (shells,  login,  etc)
             will not function properly.

       parity [-d] [-i spawn_id] [value]
             defines   whether   parity  should  be  retained  or
             stripped from the output of spawned  processes.   If
             value  is  zero, parity is stripped, otherwise it is
             not stripped.  With no value argument,  the  current
             value is returned.

             With  the  -d flag, the default parity value is set.
             (The initial default  is  1,  i.e.,  parity  is  not
             stripped.)   With  the  -i flag, the parity value is
             set for the named spawn id, otherwise it is set  for
             the current process.

       remove_nulls [-d] [-i spawn_id] [value]
             defines  whether  nulls are retained or removed from
             the  output  of  spawned  processes  before  pattern
             matching  or  storing  in the variable expect_out or
             interact_out.  If value is 1, nulls are removed.  If
             value  is  0,  nulls are not removed.  With no value
             argument, the current value is returned.

             With the -d flag, the default value  is  set.   (The
             initial  default  is  1,  i.e.,  nulls are removed.)
             With the -i flag, the value is  set  for  the  named
             spawn  id,  otherwise it is set for the current pro-
             cess.

             Whether or not nulls are removed, Expect will record
             null bytes to the log and stdout.

       send [-flags] string
             Sends  string  to the current process.  For example,
             the command

                 send "hello world\r"

             sends the characters, h e l l o <blank> w o  r  l  d
             <return>  to  the  current process.  (Tcl includes a
             printf-like command (called format) which can  build
             arbitrarily complex strings.)

             Characters  are  sent  immediately although programs
             with line-buffered input will not read  the  charac-
             ters  until  a  return  character is sent.  A return
             character is denoted "\r".

             The -- flag forces the next argument  to  be  inter-
             preted  as  a string rather than a flag.  Any string
             can be preceded by "--" whether or not  it  actually
             looks  like a flag.  This provides a reliable mecha-
             nism  to  specify  variable  strings  without  being
             tripped  up  by  those  that  accidentally look like
             flags.  (All strings starting with "-" are  reserved
             for future options.)

             The  -i flag declares that the string be sent to the
             named spawn_id.  If the spawn_id  is  user_spawn_id,
             and  the  terminal  is  in raw mode, newlines in the
             string are translated to return-newline sequences so
             that  they  appear  as it the terminal was in cooked
             mode.  The -raw flag disables this translation.

             The -null flag sends null characters (0 bytes).   By
             default,  one  null  is sent.  An integer may follow
             the -null to indicate how many nulls to send.

             The -break flag generates a break  condition.   This
             only  makes  sense  if  the spawn id refers to a tty
             device  opened  via  "spawn  -open".   If  you  have
             spawned  a process such as tip, you should use tip's
             convention for generating a break.

             The -s flag forces output to be sent "slowly",  thus
             avoid the common situation where a computer outtypes
             an input buffer that was designed for  a  human  who
             would never outtype the same buffer.  This output is
             controlled by the value of the variable  "send_slow"
             which  takes  a two element list.  The first element
             is an integer that describes the number of bytes  to
             send  atomically.  The second element is a real num-
             ber that describes the number of  seconds  by  which
             the  atomic  sends  must be separated.  For example,
             "set send_slow {10 .001}" would force "send  -s"  to
             send  strings  with 1 millisecond in between each 10
             characters sent.

             The -h flag forces output to be sent (somewhat) like
             a  human  actually typing.  Human-like delays appear
             between the characters.   (The  algorithm  is  based
             upon  a  Weibull distribution, with modifications to
             suit this particular application.)  This  output  is
             controlled by the value of the variable "send_human"
             which takes a five element list.  The first two ele-
             ments are average interarrival time of characters in
             seconds.  The first is used by default.  The  second
             is  used  at  word  endings,  to simulate the subtle
             pauses that occasionally occur at such  transitions.
             The  third  parameter  is  a  measure of variability
             where .1 is quite variable, 1  is  reasonably  vari-
             able,  and 10 is quite invariable.  The extremes are
             0 to infinity.  The last two parameters are, respec-
             tively,  a  minimum  and  maximum interarrival time.
             The minimum and maximum are used last and "clip" the
             final  time.  The ultimate average can be quite dif-
             ferent from the given average  if  the  minimum  and
             maximum clip enough values.

             As an example, the following command emulates a fast
             and consistent typist:

                 set send_human {.1 .3 1 .05 2}
                 send -h "I'm hungry.  Let's do lunch."

             while the following might be more suitable  after  a
             hangover:

                 set send_human {.4 .4 .2 .5 100}
                 send -h "Goodd party lash night!"

             Note that errors are not simulated, although you can
             set  up  error  correction  situations  yourself  by
             embedding  mistakes  and corrections in a send argu-
             ment.

             The flags for sending null characters,  for  sending
             breaks,  for forcing slow output and for human-style
             output are mutually exclusive. Only the  one  speci-
             fied last will be used. Furthermore, no string argu-
             ment can be specified with  the  flags  for  sending
             null characters or breaks.

             It  is  a  good  idea to precede the first send to a
             process by an expect.  expect will wait for the pro-
             cess to start, while send cannot.  In particular, if
             the first send completes before the  process  starts
             running,  you  run  the  risk  of  having  your data
             ignored.  In situations where  interactive  programs
             offer  no  initial prompt, you can precede send by a
             delay as in:

                 # To avoid giving hackers hints on how to break in,
                 # this system does not prompt for an external password.
                 # Wait for 5 seconds for exec to complete
                 spawn telnet very.secure.gov
                 sleep 5
                 send password\r

             exp_send is an alias for send.   If  you  are  using
             Expectk  or  some  other variant of Expect in the Tk
             environment, send is defined by Tk for  an  entirely
             different purpose.  exp_send is provided for compat-
             ibility between environments.  Similar  aliases  are
             provided for other Expect's other send commands.

       send_error [-flags] string
             is  like  send,  except  that  the output is sent to
             stderr rather than the current process.

       send_log [--] string
             is like send, except that the string is only sent to
             the  log  file  (see  log_file.)   The arguments are
             ignored if no log file is open.

       send_tty [-flags] string
             is like send, except that  the  output  is  sent  to
             /dev/tty rather than the current process.

       send_user [-flags] string
             is like send, except that the output is sent to std-
             out rather than the current process.

       sleep seconds
             causes the script to sleep for the given  number  of
             seconds.   Seconds  may be a decimal number.  Inter-
             rupts (and Tk events if you are using  Expectk)  are
             processed while Expect sleeps.

       spawn [args] program [args]
             creates  a  new  process  running program args.  Its
             stdin, stdout and stderr are connected to Expect, so
             that  they  may  be read and written by other Expect
             commands.  The connection is broken by close  or  if
             the  process  itself  closes any of the file identi-
             fiers.

             When a process is started  by  spawn,  the  variable
             spawn_id  is  set  to a descriptor referring to that
             process.  The process described by spawn_id is  con-
             sidered  the  current process.  spawn_id may be read
             or written, in effect providing job control.

             user_spawn_id is  a  global  variable  containing  a
             descriptor  which  refers to the user.  For example,
             when spawn_id is set to this value,  expect  behaves
             like expect_user.

             error_spawn_id  is  a  global  variable containing a
             descriptor which refers to the standard error.   For
             example,  when  spawn_id  is set to this value, send
             behaves like send_error.

             tty_spawn_id  is  a  global  variable  containing  a
             descriptor  which  refers  to /dev/tty.  If /dev/tty
             does not exist (such as in  a  cron,  at,  or  batch
             script), then tty_spawn_id is not defined.  This may
             be tested as:

                 if [info vars tty_spawn_id] {
                     # /dev/tty exists
                 } else {
                     # /dev/tty doesn't exist
                     # probably in cron, batch, or at script
                 }

             spawn returns the UNIX process id.  If no process is
             spawned,    0    is    returned.     The    variable
             spawn_out(slave,name) is set to the name of the  pty
             slave device.

             By  default, spawn echoes the command name and argu-
             ments.  The -noecho  flag  stops  spawn  from  doing
             this.

             The  -console flag causes console output to be redi-
             rected to the spawned process.   This  is  not  sup-
             ported on all systems.

             Internally,  spawn  uses a pty, initialized the same
             way as the user's tty.  This is further  initialized
             so  that  all  settings  are  "sane"  (according  to
             stty(1)).  If the variable stty_init is defined,  it
             is  interpreted  in  the  style of stty arguments as
             further configuration.  For example, "set  stty_init
             raw"  will  cause further spawned processes's termi-
             nals to start in raw  mode.   -nottycopy  skips  the
             initialization  based on the user's tty.  -nottyinit
             skips the "sane" initialization.

             Normally, spawn takes little time  to  execute.   If
             you  notice  spawn  taking  a  significant amount of
             time, it is  probably  encountering  ptys  that  are
             wedged.   A number of tests are run on ptys to avoid
             entanglements with errant processes.  (These take 10
             seconds per wedged pty.)  Running Expect with the -d
             option will show if Expect is encountering many ptys
             in  odd states.  If you cannot kill the processes to
             which these ptys are attached,  your  only  recourse
             may be to reboot.

             If  program  cannot  be spawned successfully because
             exec(2) fails (e.g. when program doesn't exist),  an
             error  message will be returned by the next interact
             or expect command as if program had run and produced
             the  error  message  as  output.  This behavior is a
             natural consequence of the implementation of  spawn.
             Internally,  spawn  forks,  after  which the spawned
             process has no way to communicate with the  original
             Expect  process  except  by  communication  via  the
             spawn_id.

             The -open flag causes the next argument to be inter-
             preted  as  a Tcl file identifier (i.e., returned by
             open.)  The spawn id can then be used as if it  were
             a  spawned  process.  (The file identifier should no
             longer be used.)  This lets you treat  raw  devices,
             files,  and  pipelines  as spawned processes without
             using a pty.  0 is returned to indicate there is  no
             associated  process.   When  the  connection  to the
             spawned process is closed, so is the Tcl file  iden-
             tifier.   The  -leaveopen  flag  is similar to -open
             except that -leaveopen causes the file identifier to
             be left open even after the spawn id is closed.

             The  -pty flag causes a pty to be opened but no pro-
             cess spawned.  0 is returned to indicate there is no
             associated process.  Spawn_id is set as usual.

             The  variable  spawn_out(slave,fd)  is set to a file
             identifier corresponding to the pty slave.   It  can
             be closed using "close -slave".

             The -ignore flag names a signal to be ignored in the
             spawned process.  Otherwise, signals get the default
             behavior.  Signals are named as in the trap command,
             except that each signal requires a separate flag.

       strace level
             causes following statements  to  be  printed  before
             being  executed.   (Tcl's trace command traces vari-
             ables.)  level indicates how far down  in  the  call
             stack  to trace.  For example, the following command
             runs Expect while tracing  the  first  4  levels  of
             calls, but none below that.

                 expect -c "strace 4" script.exp

             The -info flag causes strace to return a description
             of the most recent non-info arguments given.

       stty args
             changes terminal modes  similarly  to  the  external
             stty command.

             By  default,  the  controlling terminal is accessed.
             Other terminals can  be  accessed  by  appending  "<
             /dev/tty..."  to  the command.  (Note that the argu-
             ments should not be grouped into a single argument.)

             Requests  for  status return it as the result of the
             command.  If no status is requested and the control-
             ling  terminal  is  accessed, the previous status of
             the raw and echo attributes are returned in  a  form
             which can later be used by the command.

             For  example,  the  arguments raw or -cooked put the
             terminal into  raw  mode.   The  arguments  -raw  or
             cooked put the terminal into cooked mode.  The argu-
             ments echo and -echo put the terminal into echo  and
             noecho mode respectively.

             The following example illustrates how to temporarily
             disable echoing.  This could be used  in  otherwise-
             automatic  scripts  to  avoid embedding passwords in
             them.  (See more discussion  on  this  under  EXPECT
             HINTS below.)

                 stty -echo
                 send_user "Password: "
                 expect_user -re "(.*)\n"
                 set password $expect_out(1,string)
                 stty echo

       system args
             gives args to sh(1) as input, just as if it had been
             typed as a command from a  terminal.   Expect  waits
             until  the shell terminates.  The return status from
             sh is handled the same way  that  exec  handles  its
             return status.

             In contrast to exec which redirects stdin and stdout
             to the script, system performs no redirection (other
             than that indicated by the string itself).  Thus, it
             is possible to use programs which must talk directly
             to  /dev/tty.   For  the same reason, the results of
             system are not recorded in the log.

       timestamp [args]
             returns a timestamp.  With no arguments, the  number
             of seconds since the epoch is returned.

             The  -format  flag  introduces  a  string  which  is
             returned but with substitutions  made  according  to
             the  POSIX  rules  for  strftime.  For example %a is
             replaced by an abbreviated weekday name (i.e., Sat).
             Others are:
                 %a      abbreviated weekday name
                 %A      full weekday name
                 %b      abbreviated month name
                 %B      full month name
                 %c      date-time as in: Wed Oct  6 11:45:56 1993
                 %d      day of the month (01-31)
                 %H      hour (00-23)
                 %I      hour (01-12)
                 %j      day (001-366)
                 %m      month (01-12)
                 %M      minute (00-59)
                 %p      am or pm
                 %S      second (00-61)
                 %u      day (1-7, Monday is first day of week)
                 %U      week (00-53, first Sunday is first day of week one)
                 %V      week (01-53, ISO 8601 style)
                 %w      day (0-6)
                 %W      week (00-53, first Monday is first day of week one)
                 %x      date-time as in: Wed Oct  6 1993
                 %X      time as in: 23:59:59
                 %y      year (00-99)
                 %Y      year as in: 1993
                 %Z      timezone (or nothing if not determinable)
                 %%      a bare percent sign

             Other % specifications are undefined.  Other charac-
             ters will be passed through untouched.  Only  the  C
             locale is supported.

             The  -seconds  flag  introduces  a number of seconds
             since the epoch to be used as a source from which to
             format.  Otherwise, the current time is used.

             The -gmt flag forces timestamp output to use the GMT
             timezone.  With no flag, the local timezone is used.

       trap [[command] signals]
             causes  the given command to be executed upon future
             receipt of any of the given signals.  The command is
             executed in the global scope.  If command is absent,
             the signal action is returned.  If  command  is  the
             string SIG_IGN, the signals are ignored.  If command
             is the string SIG_DFL, the signals are result to the
             system  default.   signals is either a single signal
             or a list of  signals.   Signals  may  be  specified
             numerically  or  symbolically as per signal(3).  The
             "SIG" prefix may be omitted.

             With no arguments (or the  argument  -number),  trap
             returns  the  signal number of the trap command cur-
             rently being executed.

             The -code flag uses the return code of  the  command
             in  place  of  whatever code Tcl was about to return
             when the command originally started running.

             The -interp flag causes the command to be  evaluated
             using the interpreter active at the time the command
             started  running  rather  than  when  the  trap  was
             declared.

             The -name flag causes the trap command to return the
             signal name of the trap command currently being exe-
             cuted.

             The  -max flag causes the trap command to return the
             largest signal number that can be set.

             For example, the command "trap  {send_user  "Ouch!"}
             SIGINT"  will  print  "Ouch!"   each  time  the user
             presses ^C.

             By default, SIGINT (which can usually  be  generated
             by  pressing  ^C)  and SIGTERM cause Expect to exit.
             This is  due  to  the  following  trap,  created  by
             default when Expect starts.

                 trap exit {SIGINT SIGTERM}

             If you use the -D flag to start the debugger, SIGINT
             is redefined  to  start  the  interactive  debugger.
             This is due to the following trap:

                 trap {exp_debug 1} SIGINT

             The  debugger  trap  can  be  changed by setting the
             environment variable EXPECT_DEBUG_INIT to a new trap
             command.

             You  can,  of course, override both of these just by
             adding trap commands to your script.  In particular,
             if  you  have your own "trap exit SIGINT", this will
             override the debugger trap.  This is useful  if  you
             want  to  prevent users from getting to the debugger
             at all.

             If you want to define your own trap  on  SIGINT  but
             still trap to the debugger when it is running, use:

                 if ![exp_debug] {trap mystuff SIGINT}

             Alternatively,  you  can  trap to the debugger using
             some other signal.

             trap will  not  let  you  override  the  action  for
             SIGALRM  as  this is used internally to Expect.  The
             disconnect command sets SIGALRM to SIG_IGN (ignore).
             You can reenable this as long as you disable it dur-
             ing subsequent spawn commands.

             See signal(3) for more info.

       wait [args]
             delays until a spawned process (or the current  pro-
             cess if none is named) terminates.

             wait  normally returns a list of four integers.  The
             first integer is the pid of  the  process  that  was
             waited  upon.  The second integer is the correspond-
             ing spawn id.  The third integer is -1 if an operat-
             ing  system  error occurred, or 0 otherwise.  If the
             third integer was 0, the fourth integer is the  sta-
             tus  returned  by the spawned process.  If the third
             integer was -1, the fourth integer is the  value  of
             errno set by the operating system.  The global vari-
             able errorCode is also set.

             Additional elements may appear at  the  end  of  the
             return  value  from wait.  An optional fifth element
             identifies a class of information.   Currently,  the
             only  possible value for this element is CHILDKILLED
             in which case the next two values  are  the  C-style
             signal name and a short textual description.

             The -i flag declares the process to wait correspond-
             ing to the named  spawn_id  (NOT  the  process  id).
             Inside a SIGCHLD handler, it is possible to wait for
             any spawned process by using the spawn id -1.

             The -nowait flag causes the wait to  return  immedi-
             ately  with  the  indication  of  a successful wait.
             When the process exits (later),  it  will  automati-
             cally  disappear  without  the  need for an explicit
             wait.

             The wait command may also be used wait for a  forked
             process using the arguments "-i -1".  Unlike its use
             with spawned processes, this command can be executed
             at any time.  There is no control over which process
             is reaped.  However, the return value can be checked
             for the process id.

LIBRARIES
       Expect  automatically  knows  about two built-in libraries
       for Expect scripts.  These are defined by the  directories
       named  in  the variables exp_library and exp_exec_library.
       Both are meant to contain utility files that can  be  used
       by other scripts.

       exp_library   contains   architecture-independent   files.
       exp_exec_library  contains  architecture-dependent  files.
       Depending  on your system, both directories may be totally
       empty.  The existence of the  file  $exp_exec_library/cat-
       buffers   describes   whether  your  /bin/cat  buffers  by
       default.

PRETTY-PRINTING
       A  vgrind  definition  is  available  for  pretty-printing
       Expect  scripts.   Assuming the vgrind definition supplied
       with the Expect distribution is correctly  installed,  you
       can use it as:

           vgrind -lexpect file

EXAMPLES
       It  many  not  be  apparent how to put everything together
       that the man page describes.  I encourage you to read  and
       try  out  the  examples  in  the  example directory of the
       Expect distribution.  Some  of  them  are  real  programs.
       Others  are simply illustrative of certain techniques, and
       of course, a couple are just  quick  hacks.   The  INSTALL
       file has a quick overview of these programs.

       The  Expect  papers (see SEE ALSO) are also useful.  While
       some papers use syntax corresponding to  earlier  versions
       of Expect, the accompanying rationales are still valid and
       go into a lot more detail than this man page.

CAVEATS
       Extensions may collide with Expect's command  names.   For
       example,  send  is defined by Tk for an entirely different
       purpose.  For this reason, most of the Expect commands are
       also  available  as  "exp_XXXX".   Commands  and variables
       beginning with "exp", "inter", "spawn", and  "timeout"  do
       not  have  aliases.  Use the extended command names if you
       need this compatibility between environments.

       Expect takes a rather liberal view of scoping.  In partic-
       ular,  variables  read  by commands specific to the Expect
       program will be sought first from the local scope, and  if
       not  found,  in the global scope.  For example, this obvi-
       ates the need to place "global timeout" in every procedure
       you  write that uses expect.  On the other hand, variables
       written are always in the local scope (unless  a  "global"
       command  has  been  issued).  The most common problem this
       causes is when spawn is executed in a procedure.   Outside
       the  procedure,  spawn_id no longer exists, so the spawned
       process is no longer accessible simply because of scoping.
       Add a "global spawn_id" to such a procedure.

       If  you  cannot enable the multispawning capability (i.e.,
       your  system  supports  neither  select  (BSD  *.*),  poll
       (SVR>2),  nor  something  equivalent), Expect will only be
       able to control a single process at a time.  In this case,
       do  not  attempt  to  set spawn_id, nor should you execute
       processes via exec while a  spawned  process  is  running.
       Furthermore,  you will not be able to expect from multiple
       processes (including the user as one) at the same time.

       Terminal parameters can have a big effect on scripts.  For
       example,  if  a  script is written to look for echoing, it
       will misbehave if echoing is turned off.  For this reason,
       Expect forces sane terminal parameters by default.  Unfor-
       tunately, this can make things unpleasant for  other  pro-
       grams.  As an example, the emacs shell wants to change the
       "usual" mappings: newlines get mapped to newlines  instead
       of  carriage-return  newlines,  and  echoing  is disabled.
       This allows one to use  emacs  to  edit  the  input  line.
       Unfortunately, Expect cannot possibly guess this.

       You  can request that Expect not override its default set-
       ting of terminal parameters, but you  must  then  be  very
       careful  when  writing  scripts for such environments.  In
       the case of emacs, avoid depending upon things like  echo-
       ing and end-of-line mappings.

       The  commands that accepted arguments braced into a single
       list (the expect variants and interact) use a heuristic to
       decide  if the list is actually one argument or many.  The
       heuristic can fail only in the case when the list actually
       does represent a single argument which has multiple embed-
       ded \n's  with  non-whitespace  characters  between  them.
       This  seems  sufficiently improbable, however the argument
       "-brace" can be used to force a single argument to be han-
       dled as a single argument.  This could conceivably be used
       with machine-generated Expect code.

BUGS
       It was really tempting to  name  the  program  "sex"  (for
       either  "Smart EXec" or "Send-EXpect"), but good sense (or
       perhaps just Puritanism) prevailed.

       On some systems, when a shell  is  spawned,  it  complains
       about  not  being  able to access the tty but runs anyway.
       This means your system has a  mechanism  for  gaining  the
       controlling  tty  that  Expect doesn't know about.  Please
       find out what it is, and send this information back to me.

       Ultrix 4.1 (at least the latest versions around here) con-
       siders timeouts of above 1000000 to be equivalent to 0.

       Digital UNIX 4.0A (and probably other versions) refuses to
       allocate  ptys  if  you  define  a  SIGCHLD  handler.  See
       grantpt page for more info.

       IRIX 6.0 does not handle pty permissions correctly so that
       if  Expect  attempts  to allocate a pty previously used by
       someone else, it fails.  Upgrade to IRIX 6.1.

       Telnet (verified only under SunOS 4.1.2) hangs if TERM  is
       not  set.   This  is  a  problem under cron, at and in cgi
       scripts, which do not define TERM.  Thus, you must set  it
       explicitly  - to what type is usually irrelevant.  It just
       has to be set to something!  The following  probably  suf-
       fices for most cases.

           set env(TERM) vt100

       Tip  (verified  only  under BSDI BSD/OS 3.1 i386) hangs if
       SHELL and HOME are not set.  This is a problem under cron,
       at  and in cgi scripts, which do not define these environ-
       ment variables.  Thus, you must set them explicitly  -  to
       what type is usually irrelevant.  It just has to be set to
       something!   The  following  probably  suffices  for  most
       cases.

           set env(SHELL) /bin/sh
           set env(HOME) /usr/local/bin

       Some implementations of ptys are designed so that the ker-
       nel throws away any unread output after 10 to  15  seconds
       (actual number is implementation-dependent) after the pro-
       cess has closed the file descriptor.  Thus Expect programs
       such as

           spawn date
           sleep 20
           expect

       will fail.  To avoid this, invoke non-interactive programs
       with exec rather than spawn.  While  such  situations  are
       conceivable, in practice I have never encountered a situa-
       tion in which the final output of a truly interactive pro-
       gram would be lost due to this behavior.

       On  the other hand, Cray UNICOS ptys throw away any unread
       output immediately after the process has closed  the  file
       descriptor.   I  have  reported  this to Cray and they are
       working on a fix.

       Sometimes a delay is  required  between  a  prompt  and  a
       response,  such  as  when a tty interface is changing UART
       settings or matching baud rates by looking for  start/stop
       bits.  Usually, all this is require is to sleep for a sec-
       ond or two.  A more robust technique is to retry until the
       hardware is ready to receive input.  The following example
       uses both strategies:

           send "speed 9600\r";
           sleep 1
           expect {
               timeout {send "\r"; exp_continue}
               $prompt
           }

EXPECT HINTS
       There are a couple of things about Expect that may be non-
       intuitive.  This section attempts to address some of these
       things with a couple of suggestions.

       A common expect problem is how to recognize shell prompts.
       Since these are customized differently by differently peo-
       ple and different shells, portably automating  rlogin  can
       be  difficult  without  knowing  the prompt.  A reasonable
       convention is to have users  store  a  regular  expression
       describing  their prompt (in particular, the end of it) in
       the environment variable  EXPECT_PROMPT.   Code  like  the
       following  can  be  used.  If EXPECT_PROMPT doesn't exist,
       the code still has a good chance of functioning correctly.

           set prompt "(%|#|\\$) $"          ;# default prompt
           catch {set prompt $env(EXPECT_PROMPT)}

           expect -re $prompt

       I  encourage you to write expect patterns that include the
       end of whatever you expect to see.  This avoids the possi-
       bility  of  answering  a question before seeing the entire
       thing.  In addition, while you may well be able to  answer
       questions  before  seeing  them  entirely,  if  you answer
       early,  your answer may appear echoed back in  the  middle
       of  the  question.  In other words, the resulting dialogue
       will be correct but look scrambled.

       Most prompts include a space character at  the  end.   For
       example,  the  prompt  from  ftp is 'f', 't', 'p', '>' and
       <blank>.  To match this prompt, you must account for  each
       of  these  characters.   It  is  a  common  mistake not to
       include the blank.  Put the blank in explicitly.

       If you use a pattern of the form X*, the * will match  all
       the  output  received  from the end of X to the last thing
       received.  This sounds intuitive but can be somewhat  con-
       fusing  because  the phrase "last thing received" can vary
       depending upon the speed of the computer and the  process-
       ing of I/O both by the kernel and the device driver.

       In  particular, humans tend to see program output arriving
       in huge chunks (atomically) when in reality most  programs
       produce  output  one line at a time.  Assuming this is the
       case, the * in the pattern of the previous  paragraph  may
       only  match  the end of the current line even though there
       seems to be more, because at the time of  the  match  that
       was all the output that had been received.

       expect has no way of knowing that further output is coming
       unless your pattern specifically accounts for it.

       Even depending on line-oriented buffering is unwise.   Not
       only  do  programs  rarely make promises about the type of
       buffering they do, but system indigestion can break output
       lines  up  so that lines break at seemingly random places.
       Thus, if you can express the  last  few  characters  of  a
       prompt when writing patterns, it is wise to do so.

       If  you  are waiting for a pattern in the last output of a
       program and the program emits something else instead,  you
       will  not be able to detect that with the timeout keyword.
       The reason is that expect will not timeout  -  instead  it
       will  get an eof indication.  Use that instead.  Even bet-
       ter, use both.  That  way  if  that  line  is  ever  moved
       around, you won't have to edit the line itself.

       Newlines  are  usually converted to carriage return, line-
       feed sequences when output by the terminal driver.   Thus,
       if  you  want  a  pattern  that explicitly matches the two
       lines, from, say, printf("foo\nbar"), you should  use  the
       pattern "foo\r\nbar".

       A  similar  translation occurs when reading from the user,
       via expect_user.  In this case, when you press return,  it
       will  be  translated  to a newline.  If Expect then passes
       that to a program which sets  its  terminal  to  raw  mode
       (like telnet), there is going to be a problem, as the pro-
       gram expects a true return.  (Some programs  are  actually
       forgiving  in  that they will automatically translate new-
       lines to returns, but most don't.)   Unfortunately,  there
       is no way to find out that a program put its terminal into
       raw mode.

       Rather than manually replacing newlines with returns,  the
       solution is to use the command "stty raw", which will stop
       the translation.  Note, however, that this means that  you
       will no longer get the cooked line-editing features.

       interact implicitly sets your terminal to raw mode so this
       problem will not arise then.

       It is often useful to store passwords  (or  other  private
       information)  in  Expect scripts.  This is not recommended
       since anything that is stored on a computer is susceptible
       to  being accessed by anyone.  Thus, interactively prompt-
       ing for passwords from a script is  a  smarter  idea  than
       embedding  them  literally.   Nonetheless,  sometimes such
       embedding is the only possibility.

       Unfortunately, the UNIX file system has no direct  way  of
       creating  scripts  which  are  executable  but unreadable.
       Systems which support setgid shell scripts may  indirectly
       simulate this as follows:

       Create  the  Expect script (that contains the secret data)
       as usual.  Make its permissions be  750  (-rwxr-x---)  and
       owned  by  a trusted group, i.e., a group which is allowed
       to read it.  If necessary, create a  new  group  for  this
       purpose.   Next,  create a /bin/sh script with permissions
       2751 (-rwxr-s--x) owned by the same group as before.

       The result is a script which may be executed (and read) by
       anyone.  When invoked, it runs the Expect script.

SEE ALSO
       Tcl(3), libexpect(3)
       "Exploring  Expect:  A  Tcl-Based  Toolkit  for Automating
       Interactive  Programs"  by  Don  Libes,  pp.   602,   ISBN
       1-56592-090-2, O'Reilly and Associates, 1995.
       "expect:  Curing  Those Uncontrollable Fits of Interactiv-
       ity" by Don Libes, Proceedings of the Summer  1990  USENIX
       Conference, Anaheim, California, June 11-15, 1990.
       "Using  expect to Automate System Administration Tasks" by
       Don Libes, Proceedings of the 1990 USENIX Large  Installa-
       tion  Systems Administration Conference, Colorado Springs,
       Colorado, October 17-19, 1990.
       "Tcl: An Embeddable Command Language" by John  Ousterhout,
       Proceedings of the Winter 1990 USENIX Conference, Washing-
       ton, D.C., January 22-26, 1990.
       "expect: Scripts for Controlling Interactive Programs"  by
       Don Libes, Computing Systems, Vol. 4, No. 2, University of
       California Press Journals, November 1991.
       "Regression Testing and  Conformance  Testing  Interactive
       Programs",  by  Don  Libes, Proceedings of the Summer 1992
       USENIX Conference, pp.  135-144,  San  Antonio,  TX,  June
       12-15, 1992.
       "Kibitz   -   Connecting   Multiple  Interactive  Programs
       Together", by Don Libes, Software - Practice & Experience,
       John  Wiley  & Sons, West Sussex, England, Vol. 23, No. 5,
       May, 1993.
       "A Debugger for Tcl Applications", by Don Libes,  Proceed-
       ings  of  the  1993  Tcl/Tk  Workshop,  Berkeley, CA, June
       10-11, 1993.

AUTHOR
       Don Libes, National Institute of Standards and Technology

ACKNOWLEDGMENTS
       Thanks to John Ousterhout for Tcl, and Scott  Paisley  for
       inspiration.   Thanks  to Rob Savoye for Expect's autocon-
       figuration code.

       The HISTORY  file  documents  much  of  the  evolution  of
       expect.   It  makes interesting reading and might give you
       further insight to this software.  Thanks  to  the  people
       mentioned  in  it  who  sent  me  bug fixes and gave other
       assistance.

       Design and implementation of Expect was paid for  in  part
       by  the  U.S.  government  and  is therefore in the public
       domain.  However the author and NIST would like credit  if
       this  program  and  documentation  or portions of them are
       used.

                         29 December 1994                       1