sexpect − Expect for Shells
sexpect [OPTION] SUB−COMMAND [OPTION]
sexpect is another implementation of Expect which is specifically designed for Shell scripts (sh, bash, ksh, zsh, ...).
sexpect is designed in the client/server model. 'sexpect spawn' starts the server (running as a daemon) and runs the specified PROGRAM in background. Other sexpect sub−commands (send, expect, wait, ...) communicate to the server as client commands.
−debug | −d
Debug mode. The server (sexpect spawn) will run in foreground and more information will be displayed.
−help | −−help | −h
Show brief sexpect help.
−sock SOCKFILE | −s SOCKFILE
The socket file used for client/server communication. This option is required for most sub−commands.
You can save the SOCKFILE in the SEXPECT_SOCKFILE environment variable so you don’t need to specify the '−sock' option for each command. For example:
export
SEXPECT_SOCKFILE=˜/.sexpect−bash.sock
sexpect spawn bash −−norc
... ...
The socket file will be automatically created if it does not exist.
−version | −−version
Show sexpect version.
Sub−commands may have aliases. For example, 'sexpect spawn' can also be written as 'sexpect sp' or 'sexpect fork'. For each sub−command, the supported aliases are listed in parentheses.
sexpect spawn [OPTION] PROGRAM [ARGS]
The 'spawn' sub−command will first make itself run as a background server. Then the server will start the specified PROGRAM on a new allocated pty.
The 'spawn' sub−command supports the following options:
−append
See option '−logfile'.
−autowait | −nowait
Turn on the 'autowait' flag which by default is off. See sub−command 'set' for more information.
−close−on−exit | −cloexit
Close the pty after the spawned process has exited even if the spawned process’s child processes are still opening the pty. (Example: 'ssh −f')
−nonblock | −nb
Turn on the 'nonblock' flag which by default is off. See sub−command 'set' for more information.
−idle−close N | −idle N
The background server process will close the PTY and exit if there are no client requests in the last N seconds. Closing the PTY would usually cause the spawned process to receive SIGHUP and be killed.
−logfile FILE | −logf FILE | −log FILE
All output from the spawned process will be copied to the specified FILE. By default the FILE will be overwritten. Use '−append' if you want to append to it.
−nohup
Make the spawned process ignore SIGHUP. (Example: 'ssh −f')
−term TERM | −T TERM
Set the environment variable TERM for the spawned process. This is useful when the TERM variable is not set (for example for jobs started by cron/crond or atd).
−timeout N | −t N
Set the default timeout for 'sexpect expect'. A negative value means no timeout. The default value is −1.
−ttl N
The background server process will close the PTY and exit N seconds after the process is spawned. Usually this would cause the process to receive SIGHUP and be killed.
−zombie−idle N | −z N
When the spawned process closes the pty and exits, if there are no client requests in the last N seconds the server will automatically wait the spawned process and then exit. This helps avoid too many zombie processes running around. The default value is 86400 (24 hours). Use −1 to disable this.
Exit status:
0 will be returned if the background server has successfully started. This does not necessarily mean the PROGRAM has been successfully spawned (e.g. if the specified PROGRAM cannot be found). Non−zero will be returned if the server fails to start for some reason.
sexpect expect [OPTION] [ <[−exact] | −glob | −re> PATTERN] [−eof]
If the PATTERN is specified, it’ll wait until the PATTERN matches the output of the spawned process. If −eof is specified, it’ll wait until EOF (end−of−file) is seen. If neither PATTERN nor −eof is specified, then it defaults to
expect −timeout 0 −re '.*'
The 'expect' sub−command supports the following options:
−anchor−newline | −anchor
Used with '−re PATTERN'. Compile the PATTERN for newline−sensitive matching by passing the REG_NEWLINE flag to regcomp(3). By default, newline is a completely ordinary character with no special meaning. With this flag, bracket expressions [ˆ...] and '.' never match newline, a 'ˆ' anchor matches the null string after any newline in the string in addition to its normal function, and the '$' anchor matches the null string before any newline in the string in addition to its normal function.
−cstring | −cstr | −c
C style backslash escapes would be recognized and replaced in PATTERN. See sub−command 'send' for the list of supported backslash escapes.
−eof
Wait until EOF is seen from the spawned process.
Note that receiving EOF from the process does not necessarily mean the process has exited.
−exact PATTERN | −ex PATTERN
Match the PATTERN as an "exact" string.
−glob PATTERN | −gl PATTERN
Match the PATTERN as a glob style pattern.
For convenience, the glob patterns also support ˆ and $ which match the beginning and end of data currently in the internal matching buffer.
−lookback N | −lb N
Show the most recent last N lines of output so you’d know where you were last time.
−nocase | −icase | −i
Ignore case when matching PATTERN. Used with '−exact', '−glob' or '−re'.
−re PATTERN
Match the PATTERN as an extended regular expression (ERE).
−timeout N | −t N
Override the default 'expect' timeout (see 'spawn −timeout').
Exit status:
0 will be returned if the match succeeds before timeout or EOF.
If the command fails, the 'chkerr' sub−command can be used to check if the failure is caused by EOF or TIMEOUT. For example (in Bash):
sexpect expect
−re foobar
ret=$?
if [[ $ret == 0 ]]; then
# Cool we got the expected output
elif sexpect chkerr −errno $ret −is eof; then
# EOF from the spawned process (most probably dead)
elif sexpect chkerr −errno $ret −is timeout;
then
# Timed out waiting for the expected output
else
# Other errors
fi
sexpect send [OPTION] [ [−−] STRING | −file FILE | −env NAME]
The 'send' sub−command sends data to the spawned process.
Note that the data to be sent must be less than 1024 bytes. To send more data, use multiple 'sexpect send' commands.
The 'send' sub−command supports the following options:
−cstring | −cstr | −c
C language style backslash escapes would be recognized and replaced in STRING before sending to the spawned process.
The following standard C language escapes are supported:
\\ \a \b \f \n
\r \t \v
\xHH \xH
\ooo \oo \o
Other supported escapes:
\e \E : ESC,
the escape char.
\cX : CTRL−X, e.g. \cc will be converted to the
CTRL−C char.
−enter | −cr
Append ENTER (\r) to the specified STRING before sending to the spawned process.
−fd FD
Read data from file descriptor FD and send to the spawned process. Option '−limit' must be specified with '−fd'. Use '−strip' to remove trailing white space chars.
−file FILE | −f FILE
Send the content of the FILE to the spawned process. If FILE is '−' then stdin will be used. Option '−limit' must be specified if FILE is not a regular file. Use '−strip' to remove trailing white space chars.
−env NAME | −var NAME
Send the value of environment variable NAME to the spawned process.
−limit LIMIT
Used with '−file' or '−fd'. Read at most LIMIT chars from the file. LIMIT should be in range [1, 1024].
−strip
See option '−file'.
sexpect interact [OPTION]
The 'interact' sub−command is used to attach to the spawned process and manually interact with it. To detach from the process, press CTRL−] .
'interact' would fail if it’s not running on a tty/pty.
If the spawned process exits when you’re interacting with it then 'interact' will exit with the same exit code of the spawned process and you don’t need to call the 'wait' sub−command any more. And the background server will also exit.
The 'interact' sub−command supports the following options:
−lookback N | −lb N
Show the most recent last N lines of output after attaching to the process so you’d know where you were last time.
−nodetach | −nodet
Disable CTRL−]. This may be useful in scripts.
−re PATTERN
Automatically detach from the spawned process when the output matches the RE pattern. After a successful match, you can use 'expect_out' to get substring matches.
<−subst | −sub> PATTERN::REPLACE
Dynamically monitor output from the spawned process and if the output matches the PATTERN then change the matching part to REPLACE.
REPLACE can include (0), (1), (2), ..., (9) for RE match groups. (0) is for the whole match and (1) .. (9) for corresponding subgroups. For example, −subst "(foo)(bar)::(0)−(1)−(2)" would change "foobar" to "foobar−foo−bar".
The PATTERN cannot include "::".
At most 10 −subst options can be specified.
−cstring | −cstr | −c
Used with '−re PATTERN' or '−subst PATTERN::REPLACE'. C style backslash escapes would be recognized and replaced in PATTERN or REPLACE. See sub−command 'send' for the list of supported backslash escapes.
−nocase | −icase | −i
Used with '−re PATTERN' or '−subst PATTERN::REPLACE'. Ignore case when matching PATTERN.
−anchor−newline | −anchor
Used with '−re PATTERN' or '−subst PATTERN::REPLACE'. See sub−command 'expect' for more details..
sexpect wait
The 'wait' sub−command waits for the spawned process to complete and return the spawned process' exit code.
sexpect expect_out [< −index | −i> INDEX]
After the 'expect' sub−command successfully matches the specified PATTERN, you can use the 'expect_out' sub−command to get substring matches. Up to 9 (1−9) RE substring matches are saved in the server side. 0 refers to the string which matched the whole PATTERN. INDEX defaults to 0 if it’s not specified.
For example, if the command
sexpect expect −re 'a(bc)d(ef)g'
succeeds (exits 0) then the following commands
sexpect
expect_out −index 0
sexpect expect_out −index 1
sexpect expect_out −index 2
would output abcdefg, bc and ef, respectively.
sexpect chkerr −errno NUM −is REASON
If the previous 'expect' sub−command fails, the 'chkerr' sub−command can be used to check if the failure is caused by EOF or TIMEOUT.
See the 'expect' sub−command for an example.
The 'chkerr' sub−command supports the following options:
−errno NUM | −err NUM
NUM is the exit code of the previous failed 'expect' sub−command.
−is REASON
REASON can be 'eof', 'timeout'.
Exit status
0 will be returned if the specified error NUM is caused by the REASON. 1 will be returned if the specified error NUM is NOT caused by the REASON.
sexpect close
The 'close' sub−command closes the spawned process’s pty by force. This would usually cause the process to receive SIGHUP and be killed.
sexpect kill [−SIGNAME | −SIGNUM]
The 'kill' sub−command sends the specified signal to the spawned process. The default signal is SIGTERM.
The 'kill' sub−command supports the following options:
−SIGNAME
Specify the signal with name. Only the following signal names are supported:
SIGCONT SIGHUP
SIGINT SIGKILL SIGQUIT
SIGSTOP SIGTERM SIGUSR1 SIGUSR2
The SIGNAME is case insensitive and the prefix 'SIG' is optional.
−SIGNUM
Specify the signal with number.
sexpect set [OPTION]
The 'set' sub−command can be used to dynamically change server side’s parameters after 'spawn'.
The 'set' sub−command supports the following options:
−autowait FLAG | −nowait FLAG
FLAG can be 0, 1, on, off.
By default, after the spawned process exits, the server side will wait for the client to call 'wait' to get the exit status of the process and then the server will exit.
When 'autowait' is turned on, after the spawned process exits it’ll be automatically waited and then the server will exit.
−nonblock FLAG | −nb FLAG
FLAG can be 0, 1, on, off.
By default, the spawned process will be blocked if it outputs too much and the client (either 'expect', 'interact' or 'wait') does not read the output in time.
When 'nonblock' is turned on, the output from the process will not be blocked so the process can continue running.
−idle−close N | −idle N
Set the IDLE value. See the 'spawn' sub−command for details.
−timeout N | −t N
See the 'spawn' sub−command for details.
−ttl N
See the 'spawn' sub−command for details.
sexpect get [OPTION]
Retrieve server side information.
The 'get' sub−command supports the following options:
−all | −a
Get all available information from server side.
−autowait | −nowait
Get the 'autowait' flag.
−nonblock | −nb
Get the 'nonblock' flag.
−idle−close | −idle
Get the IDLE value. See 'spawn' for details.
−pid
Get the spawned process’s PID.
−ppid
Get the spawned process’s PPID.
−tty | −pty | −pts
Get the spawned process’s tty.
−timeout | −t
Get the current default timeout value.
−ttl
Get the TTL value. See 'spawn' for details.
−expect−buf N | −expbuf N
Dump the most recent N (at most 4096) chars from the internal expect buffer.
SEXPECT_SOCKFILE
See GLOBAL OPTIONS for details.
Project home: <https://github.com/clarkwang/sexpect/>
expect(1), pty(7), pts(4), glob(3), fnmatch(3)
Written by Clark Wang <dearvoid AT gmail.com>.
Report bugs to Clark Wang <dearvoid AT gmail.com> or open an issue at <https://github.com/clarkwang/sexpect/issues/>