Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for expect (redhat section 1)

EXPECT(1)			     General Commands Manual				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 programs according to a script.
       Following the script, Expect knows what can be expected from a program and what	the  cor-
       rect  response  should be.  An interpreted language provides branching and high-level con-
       trol structures to direct the dialogue.	In addition, the user can take control and inter-
       act directly when desired, afterward returning 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 libexpect(3).

       The name "Expect" comes from the idea of send/expect sequences popularized by uucp, kermit
       and  other  modem control 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 control 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	automati-
		  cally  retrieve  your  mail  so that it appears as if it was originally sent to
		  your local system.

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

       There  are  a  variety  of reasons why the shell cannot perform 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 character-
       ized programmatically.  Expect can also give the user back control  (without  halting  the
       program	being  controlled)  if	desired.   Similarly,  the user can return control 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  multi-
       ple  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 primarily 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
       command is useful for tracing statements, and the trace	command  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 debug-
       ger 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 executed 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 commands instead of reading them
       from a file.  Prompting is terminated via the exit command or upon EOF.	 See  interpreter
       (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 use-
       fully 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 argu-
       ments 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 automatically, unless the -n flag is used.  If the envi-
       ronment 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 exam-
       ple, 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 def-
       inition,  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 current 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
	     processes.

	     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 implicitly 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 closing 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  argument  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.  Compare 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  back-
	     ground.   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  back-
	     ground.

		 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  termi-
	     nal's  parameters	since  the  terminal  is  already disconnected 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 current exit handler is returned.

	     The -noexit flag causes Expect to prepare to exit but stop short of actually return-
	     ing 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  window  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 handlers 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 system-depen-
	     dent, 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 [-continue_timer]
	     The command exp_continue allows expect itself  to	continue  executing  rather  than
	     returning	as  it	normally would. By default exp_continue resets the timeout timer.
	     The -continue_timer flag prevents timer from being restarted. (See expect	for  more
	     information.)

       exp_internal [-f file] value
	     causes  further commands to send diagnostic information internal to Expect to stderr
	     if value is non-zero.  This output is disabled if value is 0.  The diagnostic infor-
	     mation  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 executed on the spawn id.

       exp_pid [-i spawn_id]
	     returns the process id corresponding to the currently 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 earlier version.

	     Versions consist of three numbers separated by dots.  First  is  the  major  number.
	     Scripts  written  for  versions  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 num-
	     ber  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 ver-
	     sion.

	     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.	Patterns 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 back-
	     slash.  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 executed 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 appearing 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 pattern some-
	     thing 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 pat-
	     tern  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 successful 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") command.  regexp patterns are introduced with the flag -re.  The previ-
	     ous 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 unnatu-
	     ral.  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  respec-
	     tively.  However,	because  expect  is not line oriented, these characters 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 indigestion.")

	     The  -ex flag causes the pattern to be matched as an "exact" string.  No interpreta-
	     tion 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 characters.  The pattern is not affected.

	     While reading output, more than 2000 bytes can force earlier bytes  to  be  "forgot-
	     ten".   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
	     corresponding  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  forgot-
	     ten characters are written to expect_out(buffer).

	     If  patlist  is  the  keyword null, and nulls are allowed (via the remove_nulls com-
	     mand), the corresponding 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  sub-
	     string   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 variables expect_out(X,start) and expect_out(X,end) where X is a  digit,  corre-
	     sponds  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 "abbb-
	     cabkkkka\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  espe-
	     cially  useful  in  experimenting	(and can be abbreviated to "-not" for convenience
	     while experimenting).

	     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 white-
	     space  separated  list  of  spawn_ids  or	a  variable  referring	to such a list of
	     spawn_ids.

	     For example, the following example waits for "connected" 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 associated pattern (i.e., followed immediately by
	     another -i) is made available to any other patterns in the same expect command asso-
	     ciated 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  fol-
	     lowing  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  exe-
	     cuting 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_background
	     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  com-
	     pletes.  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  pat-
	     tern  removes  the  given	spawn  id from the ability to match patterns in the back-
	     ground.

       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 patterns match against the spawn id
	     defined at the time that the expect_before command was executed (not when	its  pat-
	     tern 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, reading 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, reading 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 process 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 processes, 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	corresponding  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 characters 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 substrings 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 substrings are stored in the variable interact_out similarly  to  the
	     way expect stores its output in the variable expect_out.  The -indices flag is simi-
	     larly supported.

	     The pattern eof introduces an action that is executed 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 seconds) and action that is executed
	     after no characters have been read for a given time.  The timeout pattern applies to
	     the  most	recently  specified  process.	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 com-
	     mand), the corresponding 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 inter-
	     act to return to its caller.)

	     During interact, raw mode is used so that all characters may be passed to	the  cur-
	     rent  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 call interpreter
	     (perhaps by using an escape character), and then press ^Z.

	     String-body pairs can be used as a shorthand for avoiding having to enter the inter-
	     preter 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  ter-
	     minal  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  unfor-
	     tunate  feature  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 following 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 process.  If the spawned process then echoes them, the user will see
	     the characters twice.  -echo is probably 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 directory recursively.  These are so far away
	     from the normal ftp commands, that the user is unlikely to type ~ followed  by  any-
	     thing  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  out-
	     put process as characters 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 interact 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 argument (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 information).  For the same reason, the interpreter
	     command 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
	     supplying 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 specified, it overrides $user_spawn_id.  If a second -input is  speci-
	     fied, it overrides $spawn_id.  Additional -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 indi-
	     rect spawn ids.  (Indirect spawn ids are described in the section on the expect com-
	     mand.)  Indirect spawn ids may be specified with the  -i,	-u,  -input,  or  -output
	     flags.

       interpreter  [args]
	     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  prompting  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 proce-
	     dure 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	procedure
	     called "prompt2".

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

	     If  stdin	is closed, interpreter will return unless the -eof flag is used, in which
	     case the subsequent argument is invoked.

       log_file [args] [[-a] file]
	     If a filename is provided, log_file will record a transcript of the session  (begin-
	     ning  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 suppressed by the log_user command.

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

	     The  -info  flag causes log_file to return a description 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  stdout  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 description 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 exam-
	     ple, 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 interaction since the Expect process is no longer in control.

	     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 process.

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

       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 com-
	     plex strings.)

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

	     The -- flag forces the next argument to be interpreted 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 mechanism 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 trans-
	     lated to return-newline sequences so that they appear as  if  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 sepa-
	     rated.  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 elements are average interarrival time of characters in
	     seconds.  The first is used by default.  The second is used at word endings, to sim-
	     ulate  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
	     variable, and 10 is quite invariable.  The extremes are 0 to infinity.  The last two
	     parameters are, respectively, a minimum and maximum interarrival time.  The  minimum
	     and  maximum  are	used last and "clip" the final time.  The ultimate average can be
	     quite different from the given average if the minimum and maximum clip  enough  val-
	     ues.

	     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 situa-
	     tions yourself by embedding mistakes and corrections in a send argument.

	     The flags for sending null characters, for sending breaks, for forcing  slow  output
	     and  for human-style output are mutually exclusive. Only the one specified last will
	     be used. Furthermore, no string argument 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 process 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  pur-
	     pose.  exp_send is provided for compatibility 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 stdout rather than the current
	     process.

       sleep seconds
	     causes the script to sleep for the given number of seconds.  Seconds may be a  deci-
	     mal number.  Interrupts (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  con-
	     nected  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
	     identifiers.

	     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 considered the cur-
	     rent 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 arguments.  The -noecho flag stops
	     spawn from doing this.

	     The -console flag causes console output to be redirected  to  the	spawned  process.
	     This is not supported 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  terminals  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 signifi-
	     cant  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 behav-
	     ior 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 interpreted 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 identifier.  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 process 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 com-
	     mand traces variables.)  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 arguments 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 controlling 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 argu-
	     ments -raw or cooked put the terminal into cooked	mode.	The  arguments	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 ter-
	     minal.  Expect waits until the shell terminates.  The return status from sh is  han-
	     dled 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 possi-
	     ble  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  abbre-
	     viated 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	characters 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 sig-
	     nals.   The command is executed in the global scope.  If command is absent, the sig-
	     nal 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 currently 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 executed.

	     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 during subsequent spawn commands.

	     See signal(3) for more info.

       wait [args]
	     delays until a spawned process (or the current process 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	corresponding  spawn  id.
	     The  third  integer is -1 if an operating system error occurred, or 0 otherwise.  If
	     the third integer was 0, the fourth integer is the status 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 variable 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 pos-
	     sible 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 corresponding 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 immediately with the indication of a suc-
	     cessful wait.  When the process exits (later), it will automatically disappear with-
	     out 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	architec-
       ture-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 dis-
       tribution.   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 corre-
       sponding 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  com-
       patibility between environments.

       Expect  takes a rather liberal view of scoping.	In particular, 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 obviates 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.  Unfortunately, this can make things unpleas-
       ant for other programs.	As an example, the emacs shell wants to change the  "usual"  map-
       pings: 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 setting 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 echoing 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 argu-
       ment which has multiple embedded \n's with non-whitespace characters between  them.   This
       seems sufficiently improbable, however the argument "-nobrace" can be used to force a sin-
       gle argument to be handled 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) considers 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 suffices 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  environment
       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 kernel throws away any unread output
       after  10  to 15 seconds (actual number is implementation-dependent) after the process 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 situation in
       which the final output of a truly interactive program 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  inter-
       face  is  changing  UART  settings  or matching baud rates by looking for start/stop bits.
       Usually, all this is require is to sleep for a second 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
	   }

       trap -code will not work with any command that sits in Tcl's event loop,  such  as  sleep.
       The problem is that in the event loop, Tcl discards the return codes from async event han-
       dlers.  A workaround is to set a flag in the trap code.	Then check the	flag  immediately
       after the command (i.e., sleep).

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 people 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 environ-
       ment 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 possibility 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 explic-
       itly.

       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 confusing
       because the phrase "last thing received" can vary depending upon the speed of the computer
       and the processing 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 out-
       put that had been received.

       expect  has  no	way of knowing that further output is coming unless your pattern specifi-
       cally 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 better, 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, linefeed 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 prob-
       lem, as the program expects a true return.  (Some programs are actually forgiving in  that
       they  will  automatically  translate newlines 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 prompting 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  exe-
       cutable	but  unreadable.  Systems which support setgid shell scripts may indirectly simu-
       late 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 Interactivity" 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 Installation Systems Administration Conference, Colorado Springs, Col-
       orado, October 17-19, 1990.
       "Tcl: An Embeddable Command Language" by John Ousterhout, Proceedings of the  Winter  1990
       USENIX Conference, Washington, 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,  Proceed-
       ings 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, Proceedings 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 autoconfiguration 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				EXPECT(1)


All times are GMT -4. The time now is 09:11 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password