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.

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.

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

    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
    }

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

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

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

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

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

Note that in many editors, the ^ and $ match the beginning and end of lines respectively. 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 interpretation of *, ^, etc is made (although the usual Tcl conventions must still be observed). Exact patterns are always unanchored.

If patlist is the keyword null, and nulls are allowed (via the remove_nulls command), 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 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 variables 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"

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

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

    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

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

    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
    }

    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
    }

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 patterns in the background.

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

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.

    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 [clock format [clock seconds]]."}
        \003   exit
        foo    {send_user "bar"}
        ~~
    }

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 similarly 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 command), 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 interact to return to its caller.)

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

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 "[clock format [clock seconds]]: dialed $interact_out(1,string)"
    }
    interact -nobuffer "atd" lognumber

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

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.

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.

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

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

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

    send "hello world\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 translated 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 number 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 elements 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 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 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."

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

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

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.

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

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.

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

    expect -c "strace 4" script.exp

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

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 arguments -raw or cooked put the terminal into cooked mode. The arguments echo and -echo put the terminal into echo and noecho mode respectively.

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

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

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.

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}

    trap {exp_debug 1} SIGINT

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}

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.

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 -nowait flag causes the wait to return immediately with the indication of a successful wait. When the process exits (later), it will automatically 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.