1 .TH EXPECT 1 "29 December 1994"
3 expect \- programmed dialogue with interactive programs, Version 5
24 is a program that "talks" to other interactive programs according to a
25 script. Following the script,
27 knows what can be expected from
28 a program and what the correct response should be. An interpreted
29 language provides branching and high-level control structures to
30 direct the dialogue. In addition, the user can take control
31 and interact directly when desired, afterward returning control to the
45 can also be used directly in C or C++ (that is, without Tcl).
48 The name "Expect" comes from the idea of
51 by uucp, kermit and other modem control programs.
54 is generalized so that it can be run as a user-level command
55 with any program and task in mind.
57 can actually talk to several programs at the same time.
59 For example, here are some things
65 Cause your computer to dial you back,
66 so that you can login without paying for the call.
69 Start a game (e.g., rogue) and if the optimal configuration doesn't appear,
70 restart it (again and again) until it does,
71 then hand over control to you.
74 Run fsck, and in response to its questions, answer "yes", "no" or give control back to you,
75 based on predetermined criteria.
78 Connect to another network or BBS (e.g., MCI Mail, CompuServe) and
79 automatically retrieve your mail so that it appears as if
80 it was originally sent to your local system.
83 Carry environment variables, current directory,
84 or any kind of information across rlogin, telnet, tip, su, chgrp, etc.
87 There are a variety of reasons why the shell cannot perform these tasks.
94 is useful for running any program which requires
95 interaction between the program and the user.
96 All that is necessary is that the interaction can be characterized
99 can also give the user back control
100 (without halting the program being controlled) if desired.
101 Similarly, the user can return control to the script at any time.
106 for a list of commands to execute.
108 may also be invoked implicitly on systems which support the #! notation
109 by marking the script executable, and making the first line in your script:
111 #!/usr/local/bin/expect \-f
113 Of course, the path must accurately describe where
115 lives. /usr/local/bin is just an example.
119 flag prefaces a command to be executed before any in the script.
120 The command should be quoted to prevent being broken up by the shell.
121 This option may be used multiple times.
122 Multiple commands may be
123 executed with a single
125 by separating them with semicolons.
126 Commands are executed in the order they appear.
127 (When using Expectk, this option is specified as
132 flag enables some diagnostic output, which
133 primarily reports internal activity of commands such as
137 This flag has the same effect as "exp_internal 1" at the beginning of an Expect
138 script, plus the version of
143 command is useful for tracing statements, and the
145 command is useful for tracing variable assignments.)
146 (When using Expectk, this option is specified as
151 flag enables an interactive debugger. An integer value should follow.
152 The debugger will take control before the next Tcl procedure
153 if the value is non-zero
154 or if a ^C is pressed (or a breakpoint is hit, or other appropriate debugger
155 command appears in the script). See the README file or SEE ALSO (below)
156 for more information on the debugger.
157 (When using Expectk, this option is specified as
162 flag prefaces a file from which to read commands from.
163 The flag itself is optional as it is only useful when using
164 the #! notation (see above),
165 so that other arguments may be supplied on the command line.
166 (When using Expectk, this option is specified as
169 By default, the command file is read into memory and executed in its entirety.
170 It is occasionally desirable to read files one line at a time. For example,
171 stdin is read this way. In order to force arbitrary files to be handled this
175 (When using Expectk, this option is specified as
177 Note that stdio-buffering may still take place however this shouldn't cause
178 problems when reading from a fifo or stdin.
180 If the string "\-" is supplied as a filename, standard input is read instead.
181 (Use "./\-" to read from a file actually named "\-".)
187 to interactively prompt for commands instead of reading
189 Prompting is terminated via the
194 (below) for more information.
196 is assumed if neither a command file nor
199 (When using Expectk, this option is specified as
203 may be used to delimit the end of the options. This is useful if
204 you want to pass an option-like argument to your script without it being
207 This can usefully be placed in the #! line to prevent any flag-like
208 interpretation by Expect. For example, the following will leave the
209 original arguments (including the script name) in the variable
212 #!/usr/local/bin/expect \-\-
214 Note that the usual getopt(3) and execve(2) conventions must be observed
215 when adding arguments to the #! line.
217 The file $exp_library/expect.rc is sourced automatically if present, unless
221 (When using Expectk, this option is specified as
223 Immediately after this,
224 the file ~/.expect.rc is sourced automatically, unless the
226 flag is used. If the environment variable DOTDIR is defined,
227 it is treated as a directory and .expect.rc is read from there.
228 (When using Expectk, this option is specified as
230 This sourcing occurs only after executing any
235 causes Expect to print its version number and exit. (The corresponding flag
236 in Expectk, which uses long flag names, is \-version.)
240 are constructed into a list and stored in the variable named
243 is initialized to the length of argv.
246 is defined to be the name of the script (or binary if no script is used).
248 the following prints out the name of the script and the first three arguments:
251 send_user "$argv0 [lrange $argv 0 2]\\n"
258 (Tool Command Language).
259 Tcl provides control flow (e.g., if, for, break),
260 expression evaluation and several other features such as recursion,
261 procedure definition, etc.
262 Commands used here but not defined (e.g.,
266 are Tcl commands (see tcl(3)).
268 supports additional commands, described below.
269 Unless otherwise specified, commands return the empty string.
271 Commands are listed alphabetically so that they can be quickly located.
272 However, new users may find it easier to start by reading the descriptions
281 Note that the best introduction to the language (both Expect and Tcl)
282 is provided in the book "Exploring Expect" (see SEE ALSO below).
283 Examples are included in this man page but they are very limited since
284 this man page is meant primarily as reference material.
286 Note that in the text of this man page, "Expect" with an uppercase "E"
289 program while "expect" with a lower-case "e" refers to the
296 .BI close " [-slave] [\-onexec 0|1] [\-i spawn_id]"
297 closes the connection to the current process.
298 Most interactive programs will detect EOF on their stdin and exit;
301 usually suffices to kill the process as well.
304 flag declares the process to close corresponding to the named spawn_id.
310 will detect when the current process exits and implicitly do a
312 But if you kill the process by, say, "exec kill $pid",
313 you will need to explicitly call
318 flag determines whether the spawn id will be closed in any new spawned
319 processes or if the process is overlayed. To leave a spawn id open,
320 use the value 0. A non-zero integer value will force the spawn closed
321 (the default) in any new processes.
325 flag closes the slave associated with the spawn id. (See "spawn -pty".)
326 When the connection is closed, the slave is automatically closed as
329 No matter whether the connection is closed implicitly or explicitly,
332 to clear up the corresponding kernel process slot.
336 since there is no guarantee that closing a process connection will cause
342 .BI debug " [[-now] 0|1]"
343 controls a Tcl debugger allowing you to step through statements, set
346 With no arguments, a 1 is returned if the debugger is not running, otherwise
349 With a 1 argument, the debugger is started. With a 0 argument, the
350 debugger is stopped. If a 1 argument is preceded by the
352 flag, the debugger is started immediately (i.e., in the middle of the
354 command itself). Otherwise, the debugger is started with the next
359 command does not change any traps. Compare this to starting Expect with the
363 See the README file or SEE ALSO (below)
364 for more information on the debugger.
367 disconnects a forked process from the terminal. It continues running in the
368 background. The process is given its own process group (if possible).
369 Standard I/O is redirected to /dev/null.
371 The following fragment uses
373 to continue running the script in the background.
381 The following script reads a password, and then runs a program
382 every hour that demands a password each time it is run. The script supplies
383 the password so that you only have to type it once.
386 command which demonstrates how to turn off password echoing.)
389 send_user "password?\\ "
390 expect_user -re "(.*)\\n"
392 if {[fork]!=0} {sleep 3600;continue}
396 send "$expect_out(1,string)\\r"
402 An advantage to using
404 over the shell asynchronous process feature (&) is that
407 save the terminal parameters prior to disconnection, and then later
408 apply them to new ptys. With &,
410 does not have a chance
411 to read the terminal's parameters since the terminal is already
412 disconnected by the time
416 .BI exit " [\-opts] [status]"
419 to exit or otherwise prepare to do so.
423 flag causes the next argument to be used as an exit handler.
424 Without an argument, the current exit handler is returned.
430 to prepare to exit but stop short of actually returning control to the
431 operating system. The user-defined exit handler is run as well as Expect's
432 own internal handlers.
433 No further Expect commands should be executed.
434 This is useful if you are running Expect with other Tcl extensions.
435 The current interpreter (and main window if in the Tk environment) remain
436 so that other Tcl extensions can clean up. If Expect's
438 is called again (however this might occur), the handlers are not rerun.
441 all connections to spawned processes are closed. Closure will be detected
442 as an EOF by spawned processes.
444 takes no other actions beyond what the normal _exit(2) procedure does.
445 Thus, spawned processes that do not check for EOF may continue to run.
446 (A variety of conditions are important to determining, for example, what
447 signals a spawned process will be sent, but these are system-dependent,
448 typically documented under exit(3).)
449 Spawned processes that continue to run will be inherited by init.
452 (or 0 if not specified) is returned as the exit status of
455 is implicitly executed if the end of the script is reached.
457 \fBexp_continue\fR [-continue_timer]
463 executing rather than returning as it normally would. By
466 resets the timeout timer. The
468 flag prevents timer from being restarted. (See
470 for more information.)
472 .BI exp_internal " [\-f file] value"
473 causes further commands to send diagnostic information internal to
477 is non-zero. This output is disabled if
479 is 0. The diagnostic information includes every character received,
480 and every attempt made to match the current output against the patterns.
484 is supplied, all normal and debugging output is written to that file
485 (regardless of the value of
487 Any previous diagnostic output file is closed.
491 flag causes exp_internal to return a description of the
492 most recent non-info arguments given.
494 .BI exp_open " [args] [\-i spawn_id]"
495 returns a Tcl file identifier that corresponds to the original spawn id.
496 The file identifier can then be used as if it were opened by Tcl's
498 command. (The spawn id should no longer be used. A
500 should not be executed.
504 flag leaves the spawn id open for access through
507 must be executed on the spawn id.
509 .BI exp_pid " [\-i spawn_id]"
510 returns the process id corresponding to the currently spawned process.
513 flag is used, the pid returned corresponds to that of the given spawn id.
535 .BI exp_version " [[\-exit] version]"
536 is useful for assuring that the script is compatible with the current
539 With no arguments, the current version of
541 is returned. This version
542 may then be encoded in your script. If you actually know that you are not
543 using features of recent versions, you can specify an earlier version.
545 Versions consist of three numbers separated by dots. First
546 is the major number. Scripts written for versions of
549 different major number will almost certainly not work.
551 returns an error if the major numbers do not match.
553 Second is the minor number. Scripts written for a version with a
554 greater minor number than the current version
555 may depend upon some new feature and might not run.
557 returns an error if the major numbers match, but the script minor number
558 is greater than that of the running
561 Third is a number that plays no part in the version comparison.
562 However, it is incremented when the
565 distribution is changed in any way, such as by additional documentation
566 or optimization. It is reset to 0 upon each new minor version.
572 prints an error and exits if the version is out of date.
574 .BI expect " [[\-opts] pat1 body1] ... [\-opts] patn [bodyn]"
575 waits until one of the patterns matches the output of a spawned process,
576 a specified time period has passed, or an end-of-file is seen.
577 If the final body is empty, it may be omitted.
579 Patterns from the most recent
581 command are implicitly used before any other patterns.
582 Patterns from the most recent
584 command are implicitly used after any other patterns.
586 If the arguments to the entire
588 statement require more than one line,
589 all the arguments may be "braced" into one so as to avoid terminating each
590 line with a backslash. In this one case, the usual Tcl substitutions will
591 occur despite the braces.
593 If a pattern is the keyword
595 the corresponding body is executed upon end-of-file.
596 If a pattern is the keyword
598 the corresponding body is executed upon timeout. If no timeout keyword
599 is used, an implicit null action is executed upon timeout.
600 The default timeout period is 10 seconds but may be set, for example to 30,
601 by the command "set timeout 30". An infinite timeout may be designated
603 If a pattern is the keyword
605 the corresponding body is executed upon either timeout or end-of-file.
607 If a pattern matches, then the corresponding body is executed.
609 returns the result of the body (or the empty string if no pattern matched).
610 In the event that multiple patterns match, the one appearing first is
611 used to select a body.
613 Each time new output arrives, it is compared to each pattern in the order
614 they are listed. Thus, you may test for absence of a match by making
615 the last pattern something guaranteed to appear, such as a prompt.
616 In situations where there is no prompt, you must use
618 (just like you would if you were interacting manually).
620 Patterns are specified in three ways. By default,
621 patterns are specified as with Tcl's
623 command. (Such patterns are also similar to C-shell regular expressions
624 usually referred to as "glob" patterns). The
627 be used to protect patterns that might otherwise match
630 Any pattern beginning with a "-" should be protected this way. (All strings
631 starting with "-" are reserved for future options.)
634 For example, the following fragment looks for a successful login.
637 is presumed to be a procedure defined elsewhere in the script.)
640 .ta \w' expect 'u +\w'invalid password 'u
642 busy {puts busy\\n ; exp_continue}
644 "invalid password" abort
650 Quotes are necessary on the fourth pattern since it contains a space, which
651 would otherwise separate the pattern from the action.
652 Patterns with the same action (such as the 3rd and 4th) require listing the
653 actions again. This can be avoid by using regexp-style patterns (see below).
654 More information on forming glob-style patterns can be found in the Tcl manual.
656 Regexp-style patterns follow the syntax defined by Tcl's
658 (short for "regular expression") command.
659 regexp patterns are introduced with the flag
661 The previous example can be rewritten using a regexp as:
664 .ta \w' expect 'u +\w'connected 'u
666 busy {puts busy\\n ; exp_continue}
667 \-re "failed|invalid password" abort
673 Both types of patterns are "unanchored". This means that patterns
674 do not have to match the entire string, but can begin and end the
675 match anywhere in the string (as long as everything else matches).
676 Use ^ to match the beginning of a string, and $ to match the end.
677 Note that if you do not wait for the end of a string, your responses
678 can easily end up in the middle of the string as they are echoed from
679 the spawned process. While still producing correct results, the output
680 can look unnatural. Thus, use of $ is encouraged if you can exactly
681 describe the characters at the end of a string.
683 Note that in many editors, the ^ and $ match the beginning and end of
684 lines respectively. However, because expect is not line oriented,
685 these characters match the beginning and end of the data (as opposed
686 to lines) currently in the expect matching buffer. (Also, see the
687 note below on "system indigestion.")
691 flag causes the pattern to be matched as an "exact" string. No
692 interpretation of *, ^, etc is made (although the usual Tcl
693 conventions must still be observed).
694 Exact patterns are always unanchored.
699 flag causes uppercase characters of the output to compare as if they were
700 lowercase characters. The pattern is not affected.
702 While reading output,
703 more than 2000 bytes can force earlier bytes to be "forgotten".
704 This may be changed with the function
706 (Note that excessively large values can slow down the pattern matcher.)
711 the corresponding body is executed if
713 bytes have been received and no other patterns have matched.
716 keyword is used, the forgotten characters are written to
723 and nulls are allowed (via the
725 command), the corresponding body is executed if a single ASCII
727 It is not possible to
728 match 0 bytes via glob or regexp patterns.
730 Upon matching a pattern (or eof or full_buffer),
731 any matching and previously unmatched output is saved in the variable
732 .IR expect_out(buffer) .
733 Up to 9 regexp substring matches are saved in the variables
734 .I expect_out(1,string)
736 .IR expect_out(9,string) .
739 flag is used before a pattern,
740 the starting and ending indices (in a form suitable for
743 10 strings are stored in the variables
744 .I expect_out(X,start)
747 where X is a digit, corresponds to the substring position in the buffer.
748 0 refers to strings which matched the entire pattern
749 and is generated for glob patterns as well as regexp patterns.
750 For example, if a process has produced output of "abcdefgh\\n", the result of:
756 is as if the following statements had executed:
759 set expect_out(0,string) cd
760 set expect_out(buffer) abcd
763 and "efgh\\n" is left in the output buffer.
764 If a process produced the output "abbbcabkkkka\\n", the result of:
767 expect \-indices \-re "b(b*).*(k+)"
770 is as if the following statements had executed:
773 set expect_out(0,start) 1
774 set expect_out(0,end) 10
775 set expect_out(0,string) bbbcabkkkk
776 set expect_out(1,start) 2
777 set expect_out(1,end) 3
778 set expect_out(1,string) bb
779 set expect_out(2,start) 10
780 set expect_out(2,end) 10
781 set expect_out(2,string) k
782 set expect_out(buffer) abbbcabkkkk
785 and "a\\n" is left in the output buffer. The pattern "*" (and -re ".*") will
786 flush the output buffer without reading any more output from the
789 Normally, the matched output is discarded from Expect's internal buffers.
790 This may be prevented by prefixing a pattern with the
792 flag. This flag is especially useful in experimenting (and can be
793 abbreviated to "-not" for convenience while experimenting).
795 The spawn id associated with the matching output (or eof or
796 full_buffer) is stored in
797 .IR expect_out(spawn_id) .
801 flag causes the current expect command to use the following value
802 as a timeout instead of using the value of the timeout variable.
805 patterns are matched against output from the current process, however the
807 flag declares the output from the named spawn_id list be matched against
808 any following patterns (up to the next
810 The spawn_id list should either be a whitespace separated list of spawn_ids
811 or a variable referring to such a list of spawn_ids.
813 For example, the following example waits for
814 "connected" from the current process, or "busy", "failed" or "invalid
815 password" from the spawn_id named by $proc2.
819 \-i $proc2 busy {puts busy\\n ; exp_continue}
820 \-re "failed|invalid password" abort
826 The value of the global variable
828 may be used to match patterns to any spawn_ids that are named
836 flag with no associated pattern (i.e., followed immediately
839 is made available to any other patterns
842 command associated with
847 flag may also name a global variable in which case the variable is read
848 for a list of spawn ids. The variable is reread whenever it changes.
849 This provides a way of changing the I/O source while the command is in
850 execution. Spawn ids provided this way are called "indirect" spawn ids.
856 cause control structures (i.e.,
859 to behave in the usual way.
865 executing rather than returning as it normally would.
867 This is useful for avoiding explicit loops or repeated expect statements.
868 The following example is part of a fragment to automate rlogin. The
870 avoids having to write a second
872 statement (to look for the prompt again) if the rlogin prompts for a password.
878 send_user "password (for $user) on $host: "
879 expect_user -re "(.*)\\n"
881 send "$expect_out(1,string)\\r"
885 send_user "invalid password or account\\n"
888 send_user "connection to $host timed out\\n"
892 "connection to host failed: $expect_out(buffer)"
898 For example, the following fragment might help a user guide
899 an interaction that is already totally automated. In this case, the terminal
900 is put into raw mode. If the user presses "+", a variable is incremented.
901 If "p" is pressed, several returns are sent to the process,
902 perhaps to poke it in some way, and "i" lets the user interact with the
903 process, effectively stealing away control from the script.
908 to continue pattern matching after executing the
915 "p" {send "\\r\\r\\r"; exp_continue}
916 "+" {incr foo; exp_continue}
917 "i" {interact; exp_continue}
925 resets the timeout timer. The timer is not restarted, if
931 .BI expect_after " [expect_args]"
932 works identically to the
934 except that if patterns from both
940 pattern is used. See the
942 command for more information.
944 .BI expect_background " [expect_args]"
945 takes the same arguments as
947 however it returns immediately.
948 Patterns are tested whenever new input arrives.
954 .BR expect_background
955 and are silently discarded.
968 actions are being evaluated, background processing for the same
969 spawn id is blocked. Background processing is unblocked when
970 the action completes. While background processing is blocked,
971 it is possible to do a (foreground)
973 on the same spawn id.
975 It is not possible to execute an
981 for a particular spawn id is deleted by
982 declaring a new expect_background with the same spawn id. Declaring
984 with no pattern removes the given spawn id
985 from the ability to match patterns in the background.
987 .BI expect_before " [expect_args]"
988 takes the same arguments as
990 however it returns immediately.
991 Pattern-action pairs from the most recent
993 with the same spawn id are implicitly added to any following
995 commands. If a pattern matches, it is treated as if it had been
998 command itself, and the associated body is executed in the context
1002 If patterns from both
1010 If no pattern is specified, the spawn id is not checked for any patterns.
1012 Unless overridden by a
1016 patterns match against the spawn id defined at the time that the
1018 command was executed (not when its pattern is matched).
1020 The \-info flag causes
1022 to return the current specifications of what patterns it will match.
1023 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
1026 expect_before -info -i $proc
1029 At most one spawn id specification may be given. The flag \-indirect
1030 suppresses direct spawn ids that come only from indirect specifications.
1032 Instead of a spawn id specification, the flag "-all" will cause
1033 "-info" to report on all spawn ids.
1035 The output of the \-info flag can be reused as the argument to expect_before.
1037 .BI expect_tty " [expect_args]"
1040 but it reads characters from /dev/tty (i.e. keystrokes from the user).
1041 By default, reading is performed in cooked mode.
1042 Thus, lines must end with a return in order for
1045 This may be changed via
1051 .BI expect_user " [expect_args]"
1054 but it reads characters from stdin (i.e. keystrokes from the user).
1055 By default, reading is performed in cooked mode.
1056 Thus, lines must end with a return in order for
1059 This may be changed via
1066 creates a new process. The new process is an exact copy of the current
1068 process. On success,
1070 returns 0 to the new (child) process and returns the process ID of the child
1071 process to the parent process.
1072 On failure (invariably due to lack of resources, e.g., swap space, memory),
1074 returns \-1 to the parent process, and no child process is created.
1076 Forked processes exit via the
1078 command, just like the original process.
1079 Forked processes are allowed to write to the log files. If you do not
1080 disable debugging or logging in most of the processes, the result can be
1083 Some pty implementations may be confused by multiple readers and writers,
1084 even momentarily. Thus, it is safest to
1086 before spawning processes.
1088 .BI interact " [string1 body1] ... [stringn [bodyn]]"
1089 gives control of the current process to the user, so that
1090 keystrokes are sent to the current process,
1091 and the stdout and stderr of the current process are returned.
1093 String-body pairs may be specified as arguments, in which case the
1094 body is executed when the corresponding string is entered. (By default, the
1095 string is not sent to the current process.) The
1097 command is assumed, if the final body is missing.
1099 If the arguments to the entire
1101 statement require more than one line,
1102 all the arguments may be "braced" into one so as to avoid terminating each
1103 line with a backslash. In this one case, the usual Tcl substitutions will
1104 occur despite the braces.
1106 For example, the following command runs interact with the following
1107 string-body pairs defined: When ^Z is pressed,
1112 flag restores the terminal modes.)
1113 When ^A is pressed, the user sees "you typed a control-A" and the
1114 process is sent a ^A. When $ is pressed, the user sees the date.
1117 exits. If "foo" is entered, the user sees "bar".
1118 When ~~ is pressed, the
1120 interpreter runs interactively.
1123 .ta \w' interact 'u +\w'$CTRLZ 'u +\w'{'u
1126 -reset $CTRLZ {exec kill \-STOP [pid]}
1127 \\001 {send_user "you typed a control\-A\\n";
1130 $ {send_user "The date is [clock format [clock seconds]]."}
1132 foo {send_user "bar"}
1138 In string-body pairs, strings are matched in the order they are listed
1139 as arguments. Strings that partially match are not sent to the
1140 current process in anticipation of the remainder coming. If
1141 characters are then entered such that there can no longer possibly be
1142 a match, only the part of the string will be sent to the process that cannot
1143 possibly begin another match. Thus, strings that are substrings of
1144 partial matches can match later, if the original strings that was attempting
1145 to be match ultimately fails.
1147 By default, string matching is exact with no wild cards. (In contrast,
1150 command uses glob-style patterns by default.) The
1152 flag may be used to protect patterns that might otherwise match
1154 flags from doing so.
1155 Any pattern beginning with a "-" should be protected this way. (All strings
1156 starting with "-" are reserved for future options.)
1160 flag forces the string to be interpreted as a regexp-style pattern. In this
1161 case, matching substrings are stored in the variable
1163 similarly to the way
1165 stores its output in the variable
1169 flag is similarly supported.
1173 introduces an action that is
1174 executed upon end-of-file. A separate
1176 pattern may also follow the
1178 flag in which case it is matched if an eof is detected while writing output.
1181 action is "return", so that
1183 simply returns upon any EOF.
1187 introduces a timeout (in seconds) and action that is executed
1188 after no characters have been read for a given time.
1191 pattern applies to the most recently specified process.
1192 There is no default timeout.
1193 The special variable "timeout" (used by the
1195 command) has no affect on this timeout.
1197 For example, the following statement could be used to autologout users who have
1198 not typed anything for an hour but who still get frequent system
1202 interact -input $user_spawn_id timeout 3600 return -output \\
1207 If the pattern is the keyword
1209 and nulls are allowed (via the
1211 command), the corresponding body is executed if a single ASCII
1213 It is not possible to
1214 match 0 bytes via glob or regexp patterns.
1216 Prefacing a pattern with the flag
1219 .I interact_out(spawn_id)
1220 to be set to the spawn_id which matched the pattern
1227 cause control structures (i.e.,
1230 to behave in the usual way.
1233 causes interact to return to its caller, while
1237 to cause a return in its caller. For example, if "proc foo" called
1239 which then executed the action
1242 would return. (This means that if
1246 interactively typing
1248 will cause the interact to continue, while
1250 will cause the interact to return to its caller.)
1254 raw mode is used so that all characters may be passed to the current process.
1255 If the current process does not catch job control signals,
1256 it will stop if sent a stop signal (by default ^Z).
1257 To restart it, send a continue signal (such as by "kill \-CONT <pid>").
1258 If you really want to send a SIGSTOP to such a process (by ^Z),
1259 consider spawning csh first and then running your program.
1260 On the other hand, if you want to send a SIGSTOP to
1262 itself, first call interpreter (perhaps by using an escape character), and then press ^Z.
1264 String-body pairs can be used as a shorthand for avoiding having
1265 to enter the interpreter and execute commands interactively. The previous
1266 terminal mode is used while the body of a string-body pair is being executed.
1268 For speed, actions execute in raw mode by default. The
1270 flag resets the terminal to the mode it had before
1272 was executed (invariably, cooked mode).
1273 Note that characters entered when the mode is being switched may be lost
1274 (an unfortunate feature of the terminal driver on some systems).
1275 The only reason to use
1278 depends on running in cooked mode.
1282 flag sends characters that match the following pattern back to the process
1283 that generated them as each character is read. This may be useful
1284 when the user needs to see feedback from partially typed patterns.
1286 If a pattern is being echoed but eventually fails to match,
1287 the characters are sent to the spawned process. If the spawned
1288 process then echoes them, the user will see the characters twice.
1290 is probably only appropriate in situations where the user is
1291 unlikely to not complete the pattern. For example, the following
1292 excerpt is from rftp, the recursive-ftp script, where the user is
1293 prompted to enter ~g, ~p, or ~l, to get, put, or list the current
1294 directory recursively. These are so far away from the normal ftp
1295 commands, that the user is unlikely to type ~ followed by anything
1296 else, except mistakenly, in which case, they'll probably just ignore
1301 -echo ~g {getcurdirectory 1}
1302 -echo ~l {getcurdirectory 0}
1303 -echo ~p {putcurdirectory}
1309 flag sends characters that match the following pattern on to
1310 the output process as characters are read.
1312 This is useful when you wish to let a program echo back the pattern.
1313 For example, the following might be used to monitor where a person is
1314 dialing (a Hayes-style modem). Each time "atd" is seen the script
1315 logs the rest of the line.
1319 interact -nobuffer -re "(.*)\\r" return
1320 puts $log "[clock format [clock seconds]]: dialed $interact_out(1,string)"
1323 interact -nobuffer "atd" lognumber
1331 is ignored. In particular,
1333 will force its output to be logged (sent to the standard output)
1334 since it is presumed the user doesn't wish to interact blindly.
1338 flag causes any following key-body pairs to be applied to the output of
1339 the current process.
1340 This can be useful, for example, when dealing with hosts that
1341 send unwanted characters during a telnet session.
1345 expects the user to be writing stdin and reading stdout of the
1351 flag (for "user") makes
1353 look for the user as the process named by its argument
1354 (which must be a spawned id).
1356 This allows two unrelated processes to be joined
1357 together without using an explicit loop. To aid in debugging, Expect
1358 diagnostics always go to stderr (or stdout for certain logging and
1359 debugging information). For the same reason, the
1361 command will read interactively from stdin.
1363 For example, the following fragment creates a login process.
1364 Then it dials the user (not shown), and finally connects the two together.
1365 Of course, any process may be substituted for login.
1366 A shell, for example, would allow the user to work without supplying an
1367 account and password.
1373 # dial back out to user
1374 # connect user to login
1378 To send output to multiple processes, list each spawn id list prefaced by a
1380 flag. Input for a group of output spawn ids may be determined
1381 by a spawn id list prefaced by a
1387 may take lists in the same form as the
1391 command, except that any_spawn_id is not meaningful in
1393 All following flags and
1394 strings (or patterns) apply to this input until another -input flag appears.
1399 implies "\-input $user_spawn_id \-output".
1400 (Similarly, with patterns that do not have
1404 is specified, it overrides $user_spawn_id. If a second
1407 it overrides $spawn_id. Additional
1409 flags may be specified.
1411 The two implied input processes default to having their outputs specified as
1412 $spawn_id and $user_spawn_id (in reverse).
1418 flag, characters from that process are discarded.
1422 flag introduces a replacement for the current spawn_id when no
1427 flags are used. A \-i flag implies a \-o flag.
1429 It is possible to change the processes that are being interacted with
1430 by using indirect spawn ids. (Indirect spawn ids are described in the
1431 section on the expect command.) Indirect spawn ids may be specified
1432 with the -i, -u, -input, or -output flags.
1434 .B interpreter " [args]"
1435 causes the user to be interactively prompted for
1438 The result of each command is printed.
1444 cause control structures (i.e.,
1447 to behave in the usual way.
1450 causes interpreter to return to its caller, while
1454 to cause a return in its caller. For example, if "proc foo" called
1456 which then executed the action
1460 Any other command causes
1462 to continue prompting for new commands.
1464 By default, the prompt contains two integers.
1465 The first integer describes the depth of
1466 the evaluation stack (i.e., how many times Tcl_Eval has been called). The
1467 second integer is the Tcl history identifier. The prompt can be set by
1468 defining a procedure called "prompt1" whose return value becomes the next
1469 prompt. If a statement has open quotes, parens, braces, or brackets, a
1470 secondary prompt (by default "+> ") is issued upon newline. The secondary
1471 prompt may be set by defining a procedure called "prompt2".
1475 cooked mode is used, even if the its caller was using raw mode.
1479 will return unless the
1481 flag is used, in which case the subsequent argument is invoked.
1483 .BI log_file " [args] [[\-a] file]"
1484 If a filename is provided,
1486 will record a transcript of the session (beginning at that point) in the file.
1488 will stop recording if no argument is given. Any previous log file is closed.
1490 Instead of a filename, a Tcl file identifier may be provided by using the
1494 flags. This is similar to the
1502 flag forces output to be logged that was suppressed by the
1510 to old files rather than truncating them,
1511 for the convenience of being able to turn logging off and on multiple
1512 times in one session.
1513 To truncate files, use the
1519 flag causes log_file to return a description of the
1520 most recent non-info arguments given.
1522 .BI log_user " -info|0|1"
1523 By default, the send/expect dialogue is logged to stdout
1524 (and a logfile if open).
1525 The logging to stdout is disabled by the command "log_user 0"
1526 and reenabled by "log_user 1". Logging to the logfile is unchanged.
1530 flag causes log_user to return a description of the
1531 most recent non-info arguments given.
1533 .BI match_max " [\-d] [\-i spawn_id] [size]"
1534 defines the size of the buffer (in bytes) used internally by
1538 argument, the current size is returned.
1542 flag, the default size is set. (The initial default is 2000.)
1545 flag, the size is set for the named spawn id, otherwise it is set for
1546 the current process.
1548 .BI overlay " [\-# spawn_id] [\-# spawn_id] [...] program [args]"
1551 in place of the current
1553 program, which terminates.
1554 A bare hyphen argument forces a hyphen in front of the command name as if
1555 it was a login shell.
1556 All spawn_ids are closed except for those named as arguments. These
1557 are mapped onto the named file identifiers.
1559 Spawn_ids are mapped to file identifiers for the new program to inherit.
1560 For example, the following line runs chess and allows it to be
1561 controlled by the current process \- say, a chess master.
1564 overlay \-0 $spawn_id \-1 $spawn_id \-2 $spawn_id chess
1567 This is more efficient than
1568 "interact \-u", however, it sacrifices the ability to do programmed
1569 interaction since the
1571 process is no longer in control.
1573 Note that no controlling terminal is provided. Thus, if you
1574 disconnect or remap standard input, programs that do
1575 job control (shells, login, etc) will not function properly.
1577 .BI parity " [\-d] [\-i spawn_id] [value]"
1578 defines whether parity should be retained or stripped from the output of
1579 spawned processes. If
1581 is zero, parity is stripped, otherwise it is not stripped.
1584 argument, the current value is returned.
1588 flag, the default parity value is set. (The initial default is 1, i.e.,
1589 parity is not stripped.)
1592 flag, the parity value is set for the named spawn id, otherwise it is set for
1593 the current process.
1595 .BI remove_nulls " [\-d] [\-i spawn_id] [value]"
1596 defines whether nulls are retained or removed from the output of
1597 spawned processes before pattern matching
1598 or storing in the variable
1604 is 1, nulls are removed. If
1606 is 0, nulls are not removed.
1609 argument, the current value is returned.
1613 flag, the default value is set. (The initial default is 1, i.e.,
1617 flag, the value is set for the named spawn id, otherwise it is set for
1618 the current process.
1620 Whether or not nulls are removed,
1622 will record null bytes to the log and stdout.
1624 .BI send " [\-flags] string"
1627 to the current process.
1628 For example, the command
1631 send "hello world\\r"
1634 sends the characters, h e l l o <blank> w o r l d <return> to the
1636 (Tcl includes a printf-like command (called
1638 which can build arbitrarily complex strings.)
1640 Characters are sent immediately although programs with line-buffered input
1641 will not read the characters until a return character is sent. A return
1642 character is denoted "\\r".
1646 flag forces the next argument to be interpreted as a string rather than a flag.
1647 Any string can be preceded by "\-\-" whether or not it actually looks
1648 like a flag. This provides a reliable mechanism to specify variable strings
1649 without being tripped up by those that accidentally look like flags.
1650 (All strings starting with "-" are reserved for future options.)
1654 flag declares that the string be sent to the named spawn_id.
1657 and the terminal is in raw mode, newlines in the string are translated
1659 sequences so that they appear as if the terminal was in cooked mode.
1662 flag disables this translation.
1666 flag sends null characters (0 bytes). By default, one null is sent.
1667 An integer may follow the
1669 to indicate how many nulls to send.
1673 flag generates a break condition. This only makes sense if the spawn
1674 id refers to a tty device opened via "spawn -open". If you have
1675 spawned a process such as tip, you should use tip's convention for
1680 flag forces output to be sent "slowly", thus avoid the common situation
1681 where a computer outtypes an input buffer that was designed for a
1682 human who would never outtype the same buffer. This output is
1683 controlled by the value of the variable "send_slow" which takes a two
1684 element list. The first element is an integer that describes the
1685 number of bytes to send atomically. The second element is a real
1686 number that describes the number of seconds by which the atomic sends
1687 must be separated. For example, "set send_slow {10 .001}" would force
1688 "send \-s" to send strings with 1 millisecond in between each 10
1693 flag forces output to be sent (somewhat) like a human actually typing.
1694 Human-like delays appear between the characters. (The algorithm is
1695 based upon a Weibull distribution, with modifications to suit this
1696 particular application.) This output is controlled by the value of
1697 the variable "send_human" which takes a five element list. The first
1698 two elements are average interarrival time of characters in seconds.
1699 The first is used by default. The second is used at word endings, to
1700 simulate the subtle pauses that occasionally occur at such
1701 transitions. The third parameter is a measure of variability where .1
1702 is quite variable, 1 is reasonably variable, and 10 is quite
1703 invariable. The extremes are 0 to infinity. The last two parameters
1704 are, respectively, a minimum and maximum interarrival time.
1705 The minimum and maximum are used last and "clip" the final time.
1706 The ultimate average can be quite different from the given average
1707 if the minimum and maximum clip enough values.
1710 example, the following command emulates a fast and
1714 set send_human {.1 .3 1 .05 2}
1715 send \-h "I'm hungry. Let's do lunch."
1718 while the following might be more suitable after a hangover:
1721 set send_human {.4 .4 .2 .5 100}
1722 send \-h "Goodd party lash night!"
1725 Note that errors are not simulated, although you can set up error
1726 correction situations yourself by embedding mistakes and corrections
1729 The flags for sending null characters, for sending breaks, for forcing slow
1730 output and for human-style output are mutually exclusive. Only the one
1731 specified last will be used. Furthermore, no
1733 argument can be specified with the flags for sending null characters or breaks.
1735 It is a good idea to precede the first
1740 will wait for the process to start, while
1743 In particular, if the first
1745 completes before the process starts running,
1746 you run the risk of having your data ignored.
1747 In situations where interactive programs offer no initial prompt,
1753 # To avoid giving hackers hints on how to break in,
1754 # this system does not prompt for an external password.
1755 # Wait for 5 seconds for exec to complete
1756 spawn telnet very.secure.gov
1764 If you are using Expectk or some other variant of Expect in the Tk environment,
1766 is defined by Tk for an entirely different purpose.
1768 is provided for compatibility between environments.
1769 Similar aliases are provided for other Expect's other send commands.
1771 .BI send_error " [\-flags] string"
1774 except that the output is sent to stderr rather than the current
1777 .BI send_log " [\--] string"
1780 except that the string is only sent to the log file (see
1782 The arguments are ignored if no log file is open.
1784 .BI send_tty " [\-flags] string"
1787 except that the output is sent to /dev/tty rather than the current
1790 .BI send_user " [\-flags] string"
1793 except that the output is sent to stdout rather than the current
1796 .BI sleep " seconds"
1797 causes the script to sleep for the given number of seconds.
1798 Seconds may be a decimal number. Interrupts (and Tk events if you
1799 are using Expectk) are processed while Expect sleeps.
1801 .BI spawn " [args] program [args]"
1802 creates a new process running
1803 .IR "program args" .
1804 Its stdin, stdout and stderr are connected to Expect,
1805 so that they may be read and written by other
1808 The connection is broken by
1810 or if the process itself closes any of the file identifiers.
1812 When a process is started by
1816 is set to a descriptor referring to that process.
1817 The process described by
1820 .IR "current process" .
1822 may be read or written, in effect providing job control.
1825 is a global variable containing a descriptor which refers to the user.
1828 is set to this value,
1835 is a global variable containing a descriptor which refers to the standard
1839 is set to this value,
1845 is a global variable containing a descriptor which refers to /dev/tty.
1846 If /dev/tty does not exist (such as in a cron, at, or batch script), then
1848 is not defined. This may be tested as:
1851 if {[info vars tty_spawn_id]} {
1854 # /dev/tty doesn't exist
1855 # probably in cron, batch, or at script
1861 returns the UNIX process id. If no process is spawned, 0 is returned.
1863 .I spawn_out(slave,name)
1864 is set to the name of the pty slave device.
1868 echoes the command name and arguments. The
1876 flag causes console output to be redirected to the spawned process.
1877 This is not supported on all systems.
1881 uses a pty, initialized the same way as the user's tty. This is further
1882 initialized so that all settings are "sane" (according to stty(1)).
1885 is defined, it is interpreted in the style of stty arguments
1886 as further configuration.
1887 For example, "set stty_init raw" will cause further spawned processes's
1888 terminals to start in raw mode.
1890 skips the initialization based on the user's tty.
1892 skips the "sane" initialization.
1896 takes little time to execute. If you notice spawn taking a
1897 significant amount of time, it is probably encountering ptys that are
1898 wedged. A number of tests are run on ptys to avoid entanglements with
1899 errant processes. (These take 10 seconds per wedged pty.) Running
1904 is encountering many ptys in odd states. If you cannot kill
1905 the processes to which these ptys are attached, your only recourse may
1910 cannot be spawned successfully because exec(2) fails (e.g. when
1912 doesn't exist), an error message will be returned by the next
1918 had run and produced the error message as output.
1919 This behavior is a natural consequence of the implementation of
1921 Internally, spawn forks, after which the spawned process has no
1922 way to communicate with the original
1924 process except by communication
1929 flag causes the next argument to be interpreted as a Tcl file identifier
1932 The spawn id can then be used as if it were a spawned process. (The file
1933 identifier should no longer be used.)
1934 This lets you treat raw devices, files, and
1935 pipelines as spawned processes without using a pty. 0 is returned to
1936 indicate there is no associated process. When the connection to
1937 the spawned process is closed, so is the Tcl file identifier.
1944 causes the file identifier to be left open even after the spawn id is closed.
1948 flag causes a pty to be opened but no process spawned. 0 is returned
1949 to indicate there is no associated process. Spawn_id is set as usual.
1952 .I spawn_out(slave,fd)
1953 is set to a file identifier corresponding to the pty slave.
1954 It can be closed using "close -slave".
1958 flag names a signal to be ignored in the spawned process.
1959 Otherwise, signals get the default behavior.
1960 Signals are named as in the
1962 command, except that each signal requires a separate flag.
1965 causes following statements to be printed before being executed.
1966 (Tcl's trace command traces variables.)
1968 indicates how far down in the call stack to trace.
1970 the following command runs
1972 while tracing the first 4 levels of calls,
1973 but none below that.
1976 expect \-c "strace 4" script.exp
1982 flag causes strace to return a description of the
1983 most recent non-info arguments given.
1986 changes terminal modes similarly to the external stty command.
1988 By default, the controlling terminal is accessed. Other terminals can
1989 be accessed by appending "< /dev/tty..." to the command. (Note that
1990 the arguments should not be grouped into a single argument.)
1992 Requests for status return it as the result of the command. If no status
1993 is requested and the controlling terminal is accessed, the previous
1994 status of the raw and echo attributes are returned in a form which can
1995 later be used by the command.
1997 For example, the arguments
2001 put the terminal into raw mode.
2006 put the terminal into cooked mode.
2011 put the terminal into echo and noecho mode respectively.
2013 The following example illustrates how to temporarily disable echoing.
2014 This could be used in otherwise-automatic
2015 scripts to avoid embedding passwords in them.
2016 (See more discussion on this under EXPECT HINTS below.)
2020 send_user "Password: "
2021 expect_user -re "(.*)\\n"
2022 set password $expect_out(1,string)
2031 just as if it had been typed as a command from a terminal.
2033 waits until the shell terminates.
2034 The return status from sh is handled the same way that
2036 handles its return status.
2040 which redirects stdin and stdout to the script,
2042 performs no redirection
2043 (other than that indicated by the string itself).
2044 Thus, it is possible to use programs which must talk directly to /dev/tty.
2045 For the same reason, the results of
2047 are not recorded in the log.
2049 .BI timestamp " [args]"
2050 returns a timestamp.
2051 With no arguments, the number of
2052 seconds since the epoch is returned.
2056 flag introduces a string which is returned but with
2057 substitutions made according to the
2058 POSIX rules for strftime. For example %a is replaced by an abbreviated
2059 weekday name (i.e., Sat). Others are:
2061 %a abbreviated weekday name
2062 %A full weekday name
2063 %b abbreviated month name
2065 %c date-time as in: Wed Oct 6 11:45:56 1993
2066 %d day of the month (01-31)
2074 %u day (1-7, Monday is first day of week)
2075 %U week (00-53, first Sunday is first day of week one)
2076 %V week (01-53, ISO 8601 style)
2078 %W week (00-53, first Monday is first day of week one)
2079 %x date-time as in: Wed Oct 6 1993
2080 %X time as in: 23:59:59
2083 %Z timezone (or nothing if not determinable)
2084 %% a bare percent sign
2087 Other % specifications are undefined. Other characters will be passed
2088 through untouched. Only the C locale is supported.
2092 flag introduces a number of seconds since the epoch to be used as a source
2093 from which to format. Otherwise, the current time is used.
2097 flag forces timestamp output to use the GMT timezone. With no flag,
2098 the local timezone is used.
2100 .BI trap " [[command] signals]"
2103 to be executed upon future receipt of any of the given signals.
2104 The command is executed in the global scope.
2107 is absent, the signal action is returned.
2110 is the string SIG_IGN, the signals are ignored.
2113 is the string SIG_DFL, the signals are result to the system default.
2115 is either a single signal or a list of signals. Signals may be specified
2116 numerically or symbolically as per signal(3). The "SIG" prefix may be omitted.
2118 With no arguments (or the argument \-number),
2120 returns the signal number of the trap command currently being executed.
2124 flag uses the return code of the command in place of whatever code Tcl
2125 was about to return when the command originally started running.
2129 flag causes the command to be evaluated using the interpreter
2130 active at the time the command started running
2131 rather than when the trap was declared.
2137 command to return the signal name of the trap command currently being executed.
2143 command to return the largest signal number that can be set.
2145 For example, the command "trap {send_user "Ouch!"} SIGINT" will print "Ouch!"
2146 each time the user presses ^C.
2148 By default, SIGINT (which can usually be generated by pressing ^C) and
2149 SIGTERM cause Expect to exit. This is due to the following trap, created
2150 by default when Expect starts.
2153 trap exit {SIGINT SIGTERM}
2156 If you use the -D flag to start the debugger, SIGINT is redefined
2157 to start the interactive debugger. This is due to the following trap:
2160 trap {exp_debug 1} SIGINT
2163 The debugger trap can be changed by setting the environment variable
2164 EXPECT_DEBUG_INIT to a new trap command.
2166 You can, of course, override both of these just by adding trap
2167 commands to your script. In particular, if you have your own "trap
2168 exit SIGINT", this will override the debugger trap. This is useful
2169 if you want to prevent users from getting to the debugger at all.
2171 If you want to define your own trap on SIGINT but still trap to the
2172 debugger when it is running, use:
2175 if {![exp_debug]} {trap mystuff SIGINT}
2178 Alternatively, you can trap to the debugger using some other signal.
2181 will not let you override the action for SIGALRM as this is used internally
2184 The disconnect command sets SIGALRM to SIG_IGN (ignore). You can reenable
2185 this as long as you disable it during subsequent spawn commands.
2187 See signal(3) for more info.
2190 delays until a spawned process (or
2191 the current process if none is named) terminates.
2194 normally returns a list of four integers.
2195 The first integer is the pid of the process that was waited upon.
2196 The second integer is the corresponding spawn id.
2197 The third integer is -1 if an operating system error occurred, or 0 otherwise.
2198 If the third integer was 0, the fourth integer is the status returned by
2199 the spawned process. If the third integer was -1, the fourth integer is
2200 the value of errno set by the operating system. The global variable
2201 errorCode is also set.
2203 Additional elements may appear at the end of the return value from
2205 An optional fifth element identifies a class of information.
2206 Currently, the only possible value for this element is CHILDKILLED in
2207 which case the next two values are the C-style signal name and a short
2208 textual description.
2212 flag declares the process to wait corresponding to the named spawn_id
2213 (NOT the process id).
2214 Inside a SIGCHLD handler,
2215 it is possible to wait for any spawned process by using the spawn id -1.
2219 flag causes the wait to return immediately with the indication of a
2220 successful wait. When the process exits (later), it will automatically
2221 disappear without the need for an explicit wait.
2225 command may also be used wait for a forked process using the arguments
2226 "-i -1". Unlike its use with spawned processes, this command can be
2227 executed at any time. There is no control over which process is
2228 reaped. However, the return value can be checked for the process id.
2231 Expect automatically knows about two built-in libraries for Expect scripts.
2232 These are defined by the directories named in the variables
2233 exp_library and exp_exec_library. Both are meant to contain utility
2234 files that can be used by other scripts.
2236 exp_library contains architecture-independent files. exp_exec_library
2237 contains architecture-dependent files. Depending on your system, both
2238 directories may be totally empty. The existence of the file
2239 $exp_exec_library/cat-buffers describes whether your /bin/cat buffers
2242 A vgrind definition is available for pretty-printing
2245 Assuming the vgrind definition supplied with the
2248 correctly installed, you can use it as:
2251 vgrind \-lexpect file
2255 It many not be apparent how to put everything together that the man page
2256 describes. I encourage you to read and try out the examples in
2257 the example directory of the
2260 Some of them are real programs. Others are simply illustrative
2261 of certain techniques, and of course, a couple are just quick hacks.
2262 The INSTALL file has a quick overview of these programs.
2266 papers (see SEE ALSO) are also useful. While some papers
2267 use syntax corresponding to earlier versions of Expect, the accompanying
2268 rationales are still valid and go into a lot more detail than this
2271 Extensions may collide with Expect's command names. For example,
2273 is defined by Tk for an entirely different purpose.
2274 For this reason, most of the
2276 commands are also available as "exp_XXXX".
2277 Commands and variables beginning with "exp", "inter", "spawn",
2278 and "timeout" do not have aliases.
2279 Use the extended command names if you need this compatibility between environments.
2282 takes a rather liberal view of scoping.
2283 In particular, variables read by commands specific to the
2285 program will be sought first from the local scope, and if not found, in the
2286 global scope. For example, this
2287 obviates the need to place "global timeout" in every
2288 procedure you write that uses
2290 On the other hand, variables written are always in the local scope (unless
2291 a "global" command has been issued). The most common problem this causes
2292 is when spawn is executed in a procedure. Outside the procedure,
2294 no longer exists, so the spawned process is no longer accessible
2295 simply because of scoping. Add a "global spawn_id" to such a procedure.
2297 If you cannot enable the multispawning capability
2298 (i.e., your system supports neither select (BSD *.*), poll (SVR>2),
2299 nor something equivalent),
2301 will only be able to control a single process at a time.
2302 In this case, do not attempt to set
2304 nor should you execute processes via exec while a spawned process
2305 is running. Furthermore, you will not be able to
2307 from multiple processes (including the user as one) at the same time.
2309 Terminal parameters can have a big effect on scripts. For example, if
2310 a script is written to look for echoing, it will misbehave if echoing
2311 is turned off. For this reason, Expect forces sane terminal
2312 parameters by default. Unfortunately, this can make things unpleasant
2313 for other programs. As an example, the emacs shell wants to change
2314 the "usual" mappings: newlines get mapped to newlines instead of
2315 carriage-return newlines, and echoing is disabled. This allows one to
2316 use emacs to edit the input line. Unfortunately, Expect cannot
2317 possibly guess this.
2319 You can request that Expect not override its default setting of
2320 terminal parameters, but you must then be very careful when writing
2321 scripts for such environments. In the case of emacs, avoid depending
2322 upon things like echoing and end-of-line mappings.
2324 The commands that accepted arguments braced into a single list (the
2328 use a heuristic to decide if the list is actually one argument or
2329 many. The heuristic can fail only in the case when the list actually
2330 does represent a single argument which has multiple embedded \\n's
2331 with non-whitespace characters between them. This seems sufficiently
2332 improbable, however the argument "\-nobrace" can be used to force a
2333 single argument to be handled as a single argument. This could
2334 conceivably be used with machine-generated Expect code. Similarly,
2335 -brace forces a single argument to be handle as multiple patterns/actions.
2338 It was really tempting to name the program "sex" (for either "Smart EXec"
2339 or "Send-EXpect"), but good sense (or perhaps just Puritanism) prevailed.
2341 On some systems, when a shell is spawned, it complains about not being
2342 able to access the tty but runs anyway. This means your system has a
2343 mechanism for gaining the controlling tty that
2345 doesn't know about. Please find out what it is, and send this information
2348 Ultrix 4.1 (at least the latest versions around here) considers
2349 timeouts of above 1000000 to be equivalent to 0.
2351 Digital UNIX 4.0A (and probably other versions) refuses to allocate
2352 ptys if you define a SIGCHLD handler. See grantpt page for more info.
2354 IRIX 6.0 does not handle pty permissions correctly so that if Expect
2355 attempts to allocate a pty previously used by someone else, it fails.
2356 Upgrade to IRIX 6.1.
2358 Telnet (verified only under SunOS 4.1.2) hangs if TERM is not set.
2359 This is a problem under cron, at and in cgi scripts, which do not
2360 define TERM. Thus, you must set it explicitly - to what type is
2361 usually irrelevant. It just has to be set to something! The
2362 following probably suffices for most cases.
2369 Tip (verified only under BSDI BSD/OS 3.1 i386) hangs if SHELL and HOME
2370 are not set. This is a problem under cron, at and in cgi scripts,
2371 which do not define these environment variables. Thus, you must set
2372 them explicitly - to what type is usually irrelevant. It just has to
2373 be set to something! The following probably suffices for most cases.
2376 set env(SHELL) /bin/sh
2377 set env(HOME) /usr/local/bin
2382 Some implementations of ptys are designed so that the kernel throws
2383 away any unread output after 10 to 15 seconds (actual number is
2384 implementation-dependent) after the process has closed the file
2395 will fail. To avoid this, invoke non-interactive programs with
2399 While such situations are conceivable, in practice I have never
2400 encountered a situation in which the final output of a truly
2401 interactive program would be lost due to this behavior.
2403 On the other hand, Cray UNICOS ptys throw away any unread output
2404 immediately after the process has closed the file descriptor. I have
2405 reported this to Cray and they are working on a fix.
2407 Sometimes a delay is required between a prompt and a response, such as
2408 when a tty interface is changing UART settings or matching baud rates
2409 by looking for start/stop bits. Usually, all this is require is to
2410 sleep for a second or two. A more robust technique is to retry until
2411 the hardware is ready to receive input. The following example uses
2415 send "speed 9600\\r";
2418 timeout {send "\\r"; exp_continue}
2424 trap \-code will not work with any command that sits in Tcl's event
2425 loop, such as sleep. The problem is that in the event loop, Tcl
2426 discards the return codes from async event handlers. A workaround is
2427 to set a flag in the trap code. Then check the flag immediately after
2428 the command (i.e., sleep).
2430 The expect_background command ignores -timeout arguments and has no
2431 concept of timeouts in general.
2434 There are a couple of things about
2436 that may be non-intuitive.
2437 This section attempts to address some of these things with a couple of
2440 A common expect problem is how to recognize shell prompts. Since
2441 these are customized differently by differently people and different
2442 shells, portably automating rlogin can be difficult without knowing
2443 the prompt. A reasonable convention is to have users store a regular
2444 expression describing their prompt (in particular, the end of it) in
2445 the environment variable EXPECT_PROMPT. Code like the following
2446 can be used. If EXPECT_PROMPT doesn't exist, the code still has a good chance of functioning correctly.
2449 set prompt "(%|#|\\\\$) $" ;# default prompt
2450 catch {set prompt $env(EXPECT_PROMPT)}
2455 I encourage you to write
2457 patterns that include the end of whatever
2458 you expect to see. This avoids the possibility of answering a question
2459 before seeing the entire thing. In addition, while you may well be
2460 able to answer questions before seeing them entirely, if you answer
2461 early, your answer may appear echoed back in the middle of the question.
2462 In other words, the resulting dialogue will be correct but look scrambled.
2464 Most prompts include a space character at the end.
2465 For example, the prompt from ftp is 'f', 't', 'p', '>' and <blank>.
2466 To match this prompt, you must account for each of these characters.
2467 It is a common mistake not to include the blank.
2468 Put the blank in explicitly.
2470 If you use a pattern of the form X*, the * will match all the output
2471 received from the end of X to the last thing received.
2472 This sounds intuitive but can be somewhat confusing because the phrase
2473 "last thing received" can vary depending upon the speed of the computer
2474 and the processing of I/O both by the kernel and the device driver.
2476 In particular, humans tend to see program output arriving in huge chunks
2477 (atomically) when in reality most programs produce output one
2478 line at a time. Assuming this is the case, the * in the pattern of the
2479 previous paragraph may only match the end of the current line even though
2480 there seems to be more, because at the time of the match that was all
2481 the output that had been received.
2484 has no way of knowing that further output is coming unless your
2485 pattern specifically accounts for it.
2487 Even depending on line-oriented buffering is unwise. Not only do programs
2488 rarely make promises about the type of buffering they do, but system
2489 indigestion can break output lines up so that lines break at seemingly
2490 random places. Thus, if you can express the last few characters
2491 of a prompt when writing patterns, it is wise to do so.
2493 If you are waiting for a pattern in the last output of a program
2494 and the program emits something else instead, you will not be able to
2495 detect that with the
2497 keyword. The reason is that
2499 will not timeout \- instead it will get an
2502 Use that instead. Even better, use both. That way if that line
2503 is ever moved around, you won't have to edit the line itself.
2505 Newlines are usually converted to carriage return, linefeed sequences
2506 when output by the terminal driver. Thus, if you want a pattern that
2507 explicitly matches the two lines, from, say, printf("foo\\nbar"),
2508 you should use the pattern "foo\\r\\nbar".
2510 A similar translation occurs when reading from the user, via
2512 In this case, when you press return, it will be
2513 translated to a newline. If
2515 then passes that to a program
2516 which sets its terminal to raw mode (like telnet), there is going to
2517 be a problem, as the program expects a true return. (Some programs
2518 are actually forgiving in that they will automatically translate
2519 newlines to returns, but most don't.) Unfortunately, there is no way to find
2520 out that a program put its terminal into raw mode.
2522 Rather than manually replacing newlines with returns, the solution is to
2523 use the command "stty raw", which will stop the translation.
2524 Note, however, that this means that you will no longer get the cooked
2525 line-editing features.
2528 implicitly sets your terminal to raw mode so this problem will not arise then.
2530 It is often useful to store passwords (or other private information)
2533 scripts. This is not recommended since anything that is
2534 stored on a computer is susceptible to being accessed by anyone.
2535 Thus, interactively prompting for passwords from a script is a smarter
2536 idea than embedding them literally. Nonetheless, sometimes such embedding
2537 is the only possibility.
2539 Unfortunately, the UNIX file system has no direct way of creating
2540 scripts which are executable but unreadable. Systems which support
2541 setgid shell scripts may indirectly simulate this as follows:
2545 script (that contains the secret data) as usual.
2546 Make its permissions be 750 (\-rwxr\-x\-\-\-) and owned by a trusted group,
2547 i.e., a group which is allowed to read it. If necessary, create a new
2548 group for this purpose. Next, create a /bin/sh script with
2549 permissions 2751 (\-rwxr\-s\-\-x) owned by the same group as before.
2551 The result is a script which may be executed (and read) by anyone.
2552 When invoked, it runs the
2560 "Exploring Expect: A Tcl-Based Toolkit for Automating Interactive Programs"
2561 \fRby Don Libes, pp. 602, ISBN 1-56592-090-2, O'Reilly and Associates, 1995.
2564 "expect: Curing Those Uncontrollable Fits of Interactivity" \fRby Don Libes,
2565 Proceedings of the Summer 1990 USENIX Conference,
2566 Anaheim, California, June 11-15, 1990.
2571 to Automate System Administration Tasks" \fRby Don Libes,
2572 Proceedings of the 1990 USENIX Large Installation Systems Administration
2573 Conference, Colorado Springs, Colorado, October 17-19, 1990.
2576 "Tcl: An Embeddable Command Language" \fRby John Ousterhout,
2577 Proceedings of the Winter 1990 USENIX Conference,
2578 Washington, D.C., January 22-26, 1990.
2581 "expect: Scripts for Controlling Interactive Programs" \fRby Don Libes,
2582 Computing Systems, Vol. 4, No. 2, University of California Press Journals,
2586 "Regression Testing and Conformance Testing Interactive Programs", \fRby Don
2587 Libes, Proceedings of the Summer 1992 USENIX Conference, pp. 135-144,
2588 San Antonio, TX, June 12-15, 1992.
2591 "Kibitz \- Connecting Multiple Interactive Programs Together", \fRby Don Libes,
2592 Software \- Practice & Experience, John Wiley & Sons, West Sussex, England,
2593 Vol. 23, No. 5, May, 1993.
2596 "A Debugger for Tcl Applications", \fRby Don Libes,
2597 Proceedings of the 1993 Tcl/Tk Workshop, Berkeley, CA, June 10-11, 1993.
2599 Don Libes, National Institute of Standards and Technology
2601 Thanks to John Ousterhout for Tcl, and Scott Paisley for inspiration.
2602 Thanks to Rob Savoye for Expect's autoconfiguration code.
2604 The HISTORY file documents much of the evolution of
2606 It makes interesting reading and might give you further insight to this
2607 software. Thanks to the people mentioned in it who sent me bug fixes
2608 and gave other assistance.
2610 Design and implementation of
2612 was paid for in part by the U.S. government and is therefore in the public
2614 However the author and NIST would like credit
2615 if this program and documentation or portions of them are used.
projects / platform / upstream / expect.git / blob