| 1 |
.TH EXPECT 1 "29 December 1994" |
| 2 |
.SH NAME |
| 3 |
expect \- programmed dialogue with interactive programs, Version 5 |
| 4 |
.SH SYNOPSIS |
| 5 |
.B expect |
| 6 |
[ |
| 7 |
.B \-dDinN |
| 8 |
] |
| 9 |
[ |
| 10 |
.B \-c |
| 11 |
.I cmds |
| 12 |
] |
| 13 |
[ |
| 14 |
[ |
| 15 |
.BR \- [ f | b ] |
| 16 |
] |
| 17 |
.I cmdfile |
| 18 |
] |
| 19 |
[ |
| 20 |
.I args |
| 21 |
] |
| 22 |
.SH INTRODUCTION |
| 23 |
.B Expect |
| 24 |
is a program that "talks" to other interactive programs according to a |
| 25 |
script. Following the script, |
| 26 |
.B Expect |
| 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 |
| 32 |
script. |
| 33 |
.PP |
| 34 |
.B Expectk |
| 35 |
is a mixture of |
| 36 |
.B Expect |
| 37 |
and |
| 38 |
.BR Tk . |
| 39 |
It behaves just like |
| 40 |
.B Expect |
| 41 |
and |
| 42 |
.BR Tk 's |
| 43 |
.BR wish . |
| 44 |
.B Expect |
| 45 |
can also be used directly in C or C++ (that is, without Tcl). |
| 46 |
See libexpect(3). |
| 47 |
.PP |
| 48 |
The name "Expect" comes from the idea of |
| 49 |
.I send/expect |
| 50 |
sequences popularized |
| 51 |
by uucp, kermit and other modem control programs. |
| 52 |
However unlike uucp, |
| 53 |
.B Expect |
| 54 |
is generalized so that it can be run as a user-level command |
| 55 |
with any program and task in mind. |
| 56 |
.B Expect |
| 57 |
can actually talk to several programs at the same time. |
| 58 |
.PP |
| 59 |
For example, here are some things |
| 60 |
.B Expect |
| 61 |
can do: |
| 62 |
.RS |
| 63 |
.TP 4 |
| 64 |
\(bu |
| 65 |
Cause your computer to dial you back, |
| 66 |
so that you can login without paying for the call. |
| 67 |
.TP |
| 68 |
\(bu |
| 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. |
| 72 |
.TP |
| 73 |
\(bu |
| 74 |
Run fsck, and in response to its questions, answer "yes", "no" or give control back to you, |
| 75 |
based on predetermined criteria. |
| 76 |
.TP |
| 77 |
\(bu |
| 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. |
| 81 |
.TP |
| 82 |
\(bu |
| 83 |
Carry environment variables, current directory, |
| 84 |
or any kind of information across rlogin, telnet, tip, su, chgrp, etc. |
| 85 |
.RE |
| 86 |
.PP |
| 87 |
There are a variety of reasons why the shell cannot perform these tasks. |
| 88 |
(Try, you'll see.) |
| 89 |
All are possible with |
| 90 |
.BR Expect . |
| 91 |
.PP |
| 92 |
In general, |
| 93 |
.B Expect |
| 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 |
| 97 |
programmatically. |
| 98 |
.B Expect |
| 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. |
| 102 |
.SH USAGE |
| 103 |
.B Expect |
| 104 |
reads |
| 105 |
.I cmdfile |
| 106 |
for a list of commands to execute. |
| 107 |
.B Expect |
| 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: |
| 110 |
|
| 111 |
#!/usr/bin/expect \-f |
| 112 |
|
| 113 |
Of course, the path must accurately describe where |
| 114 |
.B Expect |
| 115 |
lives. /usr/bin is just an example. |
| 116 |
|
| 117 |
The |
| 118 |
.B \-c |
| 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 |
| 124 |
.B \-c |
| 125 |
by separating them with semicolons. |
| 126 |
Commands are executed in the order they appear. |
| 127 |
(When using Expectk, this option is specified as |
| 128 |
.BR \-command .) |
| 129 |
.PP |
| 130 |
The |
| 131 |
.B \-d |
| 132 |
flag enables some diagnostic output, which |
| 133 |
primarily reports internal activity of commands such as |
| 134 |
.B expect |
| 135 |
and |
| 136 |
.BR interact . |
| 137 |
This flag has the same effect as "exp_internal 1" at the beginning of an Expect |
| 138 |
script, plus the version of |
| 139 |
.B Expect |
| 140 |
is printed. |
| 141 |
(The |
| 142 |
.B strace |
| 143 |
command is useful for tracing statements, and the |
| 144 |
.B trace |
| 145 |
command is useful for tracing variable assignments.) |
| 146 |
(When using Expectk, this option is specified as |
| 147 |
.BR \-diag .) |
| 148 |
.PP |
| 149 |
The |
| 150 |
.B \-D |
| 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 |
| 158 |
.BR \-Debug .) |
| 159 |
.PP |
| 160 |
The |
| 161 |
.B \-f |
| 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 |
| 167 |
.BR \-file .) |
| 168 |
.PP |
| 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 |
| 172 |
way, use the |
| 173 |
.B \-b |
| 174 |
flag. |
| 175 |
(When using Expectk, this option is specified as |
| 176 |
.BR \-buffer .) |
| 177 |
Note that stdio-buffering may still take place however this shouldn't cause |
| 178 |
problems when reading from a fifo or stdin. |
| 179 |
.PP |
| 180 |
If the string "\-" is supplied as a filename, standard input is read instead. |
| 181 |
(Use "./\-" to read from a file actually named "\-".) |
| 182 |
.PP |
| 183 |
The |
| 184 |
.B \-i |
| 185 |
flag causes |
| 186 |
.B Expect |
| 187 |
to interactively prompt for commands instead of reading |
| 188 |
them from a file. |
| 189 |
Prompting is terminated via the |
| 190 |
.B exit |
| 191 |
command or upon EOF. |
| 192 |
See |
| 193 |
.B interpreter |
| 194 |
(below) for more information. |
| 195 |
.B \-i |
| 196 |
is assumed if neither a command file nor |
| 197 |
.B \-c |
| 198 |
is used. |
| 199 |
(When using Expectk, this option is specified as |
| 200 |
.BR \-interactive .) |
| 201 |
.PP |
| 202 |
.B \-\- |
| 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 |
| 205 |
interpreted by |
| 206 |
.BR Expect . |
| 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 |
| 210 |
.IR argv . |
| 211 |
|
| 212 |
#!/usr/bin/expect \-\- |
| 213 |
|
| 214 |
Note that the usual getopt(3) and execve(2) conventions must be observed |
| 215 |
when adding arguments to the #!\& line. |
| 216 |
.PP |
| 217 |
The file $exp_library/expect.rc is sourced automatically if present, unless |
| 218 |
the |
| 219 |
.B \-N |
| 220 |
flag is used. |
| 221 |
(When using Expectk, this option is specified as |
| 222 |
.BR \-NORC .) |
| 223 |
Immediately after this, |
| 224 |
the file ~/.expect.rc is sourced automatically, unless the |
| 225 |
.B \-n |
| 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 |
| 229 |
.BR \-norc .) |
| 230 |
This sourcing occurs only after executing any |
| 231 |
.B \-c |
| 232 |
flags. |
| 233 |
.PP |
| 234 |
.B \-v |
| 235 |
causes Expect to print its version number and exit. (The corresponding flag |
| 236 |
in Expectk, which uses long flag names, is \-version.) |
| 237 |
.PP |
| 238 |
Optional |
| 239 |
.I args |
| 240 |
are constructed into a list and stored in the variable named |
| 241 |
.IR argv . |
| 242 |
.I argc |
| 243 |
is initialized to the length of argv. |
| 244 |
.PP |
| 245 |
.I argv0 |
| 246 |
is defined to be the name of the script (or binary if no script is used). |
| 247 |
For example, |
| 248 |
the following prints out the name of the script and the first three arguments: |
| 249 |
.nf |
| 250 |
|
| 251 |
send_user "$argv0 [lrange $argv 0 2]\en" |
| 252 |
|
| 253 |
.fi |
| 254 |
.SH COMMANDS |
| 255 |
.B Expect |
| 256 |
uses |
| 257 |
.I Tcl |
| 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., |
| 263 |
.BR set , |
| 264 |
.BR if , |
| 265 |
.BR exec ) |
| 266 |
are Tcl commands (see tcl(3)). |
| 267 |
.B Expect |
| 268 |
supports additional commands, described below. |
| 269 |
Unless otherwise specified, commands return the empty string. |
| 270 |
.PP |
| 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 |
| 273 |
of |
| 274 |
.BR spawn , |
| 275 |
.BR send , |
| 276 |
.BR expect , |
| 277 |
and |
| 278 |
.BR interact , |
| 279 |
in that order. |
| 280 |
|
| 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. |
| 285 |
|
| 286 |
Note that in the text of this man page, "Expect" with an uppercase "E" |
| 287 |
refers to the |
| 288 |
.B Expect |
| 289 |
program while "expect" with a lower-case "e" refers to the |
| 290 |
.B expect |
| 291 |
command within the |
| 292 |
.B Expect |
| 293 |
program.) |
| 294 |
.I |
| 295 |
.TP 6 |
| 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; |
| 299 |
thus |
| 300 |
.B close |
| 301 |
usually suffices to kill the process as well. |
| 302 |
The |
| 303 |
.B \-i |
| 304 |
flag declares the process to close corresponding to the named spawn_id. |
| 305 |
|
| 306 |
Both |
| 307 |
.B expect |
| 308 |
and |
| 309 |
.B interact |
| 310 |
will detect when the current process exits and implicitly do a |
| 311 |
.BR close . |
| 312 |
But if you kill the process by, say, "exec kill $pid", |
| 313 |
you will need to explicitly call |
| 314 |
.BR close . |
| 315 |
|
| 316 |
The |
| 317 |
.B \-onexec |
| 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. |
| 322 |
|
| 323 |
The |
| 324 |
.B \-slave |
| 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 |
| 327 |
well if still open. |
| 328 |
|
| 329 |
No matter whether the connection is closed implicitly or explicitly, |
| 330 |
you should call |
| 331 |
.B wait |
| 332 |
to clear up the corresponding kernel process slot. |
| 333 |
.B close |
| 334 |
does not call |
| 335 |
.B wait |
| 336 |
since there is no guarantee that closing a process connection will cause |
| 337 |
it to exit. |
| 338 |
See |
| 339 |
.B wait |
| 340 |
below for more info. |
| 341 |
.TP |
| 342 |
.BI debug " [[\-now] 0|1]" |
| 343 |
controls a Tcl debugger allowing you to step through statements, set |
| 344 |
breakpoints, etc. |
| 345 |
|
| 346 |
With no arguments, a 1 is returned if the debugger is not running, otherwise |
| 347 |
a 0 is returned. |
| 348 |
|
| 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 |
| 351 |
.B \-now |
| 352 |
flag, the debugger is started immediately (i.e., in the middle of the |
| 353 |
.B debug |
| 354 |
command itself). Otherwise, the debugger is started with the next |
| 355 |
Tcl statement. |
| 356 |
|
| 357 |
The |
| 358 |
.B debug |
| 359 |
command does not change any traps. Compare this to starting Expect with the |
| 360 |
.B \-D |
| 361 |
flag (see above). |
| 362 |
|
| 363 |
See the README file or SEE ALSO (below) |
| 364 |
for more information on the debugger. |
| 365 |
.TP |
| 366 |
.B disconnect |
| 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. |
| 370 |
.IP |
| 371 |
The following fragment uses |
| 372 |
.B disconnect |
| 373 |
to continue running the script in the background. |
| 374 |
.nf |
| 375 |
|
| 376 |
if {[fork]!=0} exit |
| 377 |
disconnect |
| 378 |
. . . |
| 379 |
|
| 380 |
.fi |
| 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. |
| 384 |
(See the |
| 385 |
.B stty |
| 386 |
command which demonstrates how to turn off password echoing.) |
| 387 |
.nf |
| 388 |
|
| 389 |
send_user "password?\e " |
| 390 |
expect_user \-re "(.*)\en" |
| 391 |
for {} 1 {} { |
| 392 |
if {[fork]!=0} {sleep 3600;continue} |
| 393 |
disconnect |
| 394 |
spawn priv_prog |
| 395 |
expect Password: |
| 396 |
send "$expect_out(1,string)\er" |
| 397 |
. . . |
| 398 |
exit |
| 399 |
} |
| 400 |
|
| 401 |
.fi |
| 402 |
An advantage to using |
| 403 |
.B disconnect |
| 404 |
over the shell asynchronous process feature (&) is that |
| 405 |
.B Expect |
| 406 |
can |
| 407 |
save the terminal parameters prior to disconnection, and then later |
| 408 |
apply them to new ptys. With &, |
| 409 |
.B Expect |
| 410 |
does not have a chance |
| 411 |
to read the terminal's parameters since the terminal is already |
| 412 |
disconnected by the time |
| 413 |
.B Expect |
| 414 |
receives control. |
| 415 |
.TP |
| 416 |
.BI exit " [\-opts] [status]" |
| 417 |
causes |
| 418 |
.B Expect |
| 419 |
to exit or otherwise prepare to do so. |
| 420 |
|
| 421 |
The |
| 422 |
.B \-onexit |
| 423 |
flag causes the next argument to be used as an exit handler. |
| 424 |
Without an argument, the current exit handler is returned. |
| 425 |
|
| 426 |
The |
| 427 |
.B \-noexit |
| 428 |
flag causes |
| 429 |
.B Expect |
| 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 |
| 437 |
.B exit |
| 438 |
is called again (however this might occur), the handlers are not rerun. |
| 439 |
|
| 440 |
Upon exiting, |
| 441 |
all connections to spawned processes are closed. Closure will be detected |
| 442 |
as an EOF by spawned processes. |
| 443 |
.B exit |
| 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. |
| 450 |
|
| 451 |
.I status |
| 452 |
(or 0 if not specified) is returned as the exit status of |
| 453 |
.BR Expect . |
| 454 |
.B exit |
| 455 |
is implicitly executed if the end of the script is reached. |
| 456 |
.TP |
| 457 |
\fBexp_continue\fR [\-continue_timer] |
| 458 |
The command |
| 459 |
.B exp_continue |
| 460 |
allows |
| 461 |
.B expect |
| 462 |
itself to continue |
| 463 |
executing rather than returning as it normally would. By |
| 464 |
default |
| 465 |
.B exp_continue |
| 466 |
resets the timeout timer. The |
| 467 |
.I \-continue_timer |
| 468 |
flag prevents timer from being restarted. (See |
| 469 |
.B expect |
| 470 |
for more information.) |
| 471 |
.TP |
| 472 |
.BI exp_internal " [\-f file] value" |
| 473 |
causes further commands to send diagnostic information internal to |
| 474 |
.B Expect |
| 475 |
to stderr if |
| 476 |
.I value |
| 477 |
is non-zero. This output is disabled if |
| 478 |
.I value |
| 479 |
is 0. The diagnostic information includes every character received, |
| 480 |
and every attempt made to match the current output against the patterns. |
| 481 |
.IP |
| 482 |
If the optional |
| 483 |
.I file |
| 484 |
is supplied, all normal and debugging output is written to that file |
| 485 |
(regardless of the value of |
| 486 |
.IR value ). |
| 487 |
Any previous diagnostic output file is closed. |
| 488 |
|
| 489 |
The |
| 490 |
.B \-info |
| 491 |
flag causes exp_internal to return a description of the |
| 492 |
most recent non-info arguments given. |
| 493 |
.TP |
| 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 |
| 497 |
.B open |
| 498 |
command. (The spawn id should no longer be used. A |
| 499 |
.B wait |
| 500 |
should not be executed. |
| 501 |
|
| 502 |
The |
| 503 |
.B \-leaveopen |
| 504 |
flag leaves the spawn id open for access through |
| 505 |
Expect commands. A |
| 506 |
.B wait |
| 507 |
must be executed on the spawn id. |
| 508 |
.TP |
| 509 |
.BI exp_pid " [\-i spawn_id]" |
| 510 |
returns the process id corresponding to the currently spawned process. |
| 511 |
If the |
| 512 |
.B \-i |
| 513 |
flag is used, the pid returned corresponds to that of the given spawn id. |
| 514 |
.TP |
| 515 |
.B exp_send |
| 516 |
is an alias for |
| 517 |
.BR send . |
| 518 |
.TP |
| 519 |
.B exp_send_error |
| 520 |
is an alias for |
| 521 |
.BR send_error . |
| 522 |
.TP |
| 523 |
.B exp_send_log |
| 524 |
is an alias for |
| 525 |
.BR send_log . |
| 526 |
.TP |
| 527 |
.B exp_send_tty |
| 528 |
is an alias for |
| 529 |
.BR send_tty . |
| 530 |
.TP |
| 531 |
.B exp_send_user |
| 532 |
is an alias for |
| 533 |
.BR send_user . |
| 534 |
.TP |
| 535 |
.BI exp_version " [[\-exit] version]" |
| 536 |
is useful for assuring that the script is compatible with the current |
| 537 |
version of Expect. |
| 538 |
.IP |
| 539 |
With no arguments, the current version of |
| 540 |
.B Expect |
| 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. |
| 544 |
.IP |
| 545 |
Versions consist of three numbers separated by dots. First |
| 546 |
is the major number. Scripts written for versions of |
| 547 |
.B Expect |
| 548 |
with a |
| 549 |
different major number will almost certainly not work. |
| 550 |
.B exp_version |
| 551 |
returns an error if the major numbers do not match. |
| 552 |
.IP |
| 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. |
| 556 |
.B exp_version |
| 557 |
returns an error if the major numbers match, but the script minor number |
| 558 |
is greater than that of the running |
| 559 |
.BR Expect . |
| 560 |
.IP |
| 561 |
Third is a number that plays no part in the version comparison. |
| 562 |
However, it is incremented when the |
| 563 |
.B Expect |
| 564 |
software |
| 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. |
| 567 |
.IP |
| 568 |
With the |
| 569 |
.B \-exit |
| 570 |
flag, |
| 571 |
.B Expect |
| 572 |
prints an error and exits if the version is out of date. |
| 573 |
.TP |
| 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. |
| 578 |
.IP |
| 579 |
Patterns from the most recent |
| 580 |
.B expect_before |
| 581 |
command are implicitly used before any other patterns. |
| 582 |
Patterns from the most recent |
| 583 |
.B expect_after |
| 584 |
command are implicitly used after any other patterns. |
| 585 |
.IP |
| 586 |
If the arguments to the entire |
| 587 |
.B expect |
| 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. |
| 592 |
.IP |
| 593 |
If a pattern is the keyword |
| 594 |
.BR eof , |
| 595 |
the corresponding body is executed upon end-of-file. |
| 596 |
If a pattern is the keyword |
| 597 |
.BR timeout , |
| 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 |
| 602 |
by the value \-1. |
| 603 |
If a pattern is the keyword |
| 604 |
.BR default , |
| 605 |
the corresponding body is executed upon either timeout or end-of-file. |
| 606 |
.IP |
| 607 |
If a pattern matches, then the corresponding body is executed. |
| 608 |
.B expect |
| 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. |
| 612 |
.IP |
| 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 |
| 617 |
.B timeout |
| 618 |
(just like you would if you were interacting manually). |
| 619 |
.IP |
| 620 |
Patterns are specified in three ways. By default, |
| 621 |
patterns are specified as with Tcl's |
| 622 |
.B string match |
| 623 |
command. (Such patterns are also similar to C-shell regular expressions |
| 624 |
usually referred to as "glob" patterns). The |
| 625 |
.B \-gl |
| 626 |
flag may |
| 627 |
be used to protect patterns that might otherwise match |
| 628 |
.B expect |
| 629 |
flags from doing so. |
| 630 |
Any pattern beginning with a "\-" should be protected this way. (All strings |
| 631 |
starting with "\-" are reserved for future options.) |
| 632 |
|
| 633 |
.IP |
| 634 |
For example, the following fragment looks for a successful login. |
| 635 |
(Note that |
| 636 |
.B abort |
| 637 |
is presumed to be a procedure defined elsewhere in the script.) |
| 638 |
.nf |
| 639 |
|
| 640 |
.ta \w' expect 'u +\w'invalid password 'u |
| 641 |
expect { |
| 642 |
busy {puts busy\en ; exp_continue} |
| 643 |
failed abort |
| 644 |
"invalid password" abort |
| 645 |
timeout abort |
| 646 |
connected |
| 647 |
} |
| 648 |
|
| 649 |
.fi |
| 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. |
| 655 |
.IP |
| 656 |
Regexp-style patterns follow the syntax defined by Tcl's |
| 657 |
.B regexp |
| 658 |
(short for "regular expression") command. |
| 659 |
regexp patterns are introduced with the flag |
| 660 |
.BR \-re . |
| 661 |
The previous example can be rewritten using a regexp as: |
| 662 |
.nf |
| 663 |
|
| 664 |
.ta \w' expect 'u +\w'connected 'u |
| 665 |
expect { |
| 666 |
busy {puts busy\en ; exp_continue} |
| 667 |
\-re "failed|invalid password" abort |
| 668 |
timeout abort |
| 669 |
connected |
| 670 |
} |
| 671 |
|
| 672 |
.fi |
| 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. |
| 682 |
|
| 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".) |
| 688 |
|
| 689 |
The |
| 690 |
.B \-ex |
| 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. |
| 695 |
|
| 696 |
.IP |
| 697 |
The |
| 698 |
.B \-nocase |
| 699 |
flag causes uppercase characters of the output to compare as if they were |
| 700 |
lowercase characters. The pattern is not affected. |
| 701 |
.IP |
| 702 |
While reading output, |
| 703 |
more than 2000 bytes can force earlier bytes to be "forgotten". |
| 704 |
This may be changed with the function |
| 705 |
.BR match_max . |
| 706 |
(Note that excessively large values can slow down the pattern matcher.) |
| 707 |
If |
| 708 |
.I patlist |
| 709 |
is |
| 710 |
.BR full_buffer , |
| 711 |
the corresponding body is executed if |
| 712 |
.I match_max |
| 713 |
bytes have been received and no other patterns have matched. |
| 714 |
Whether or not the |
| 715 |
.B full_buffer |
| 716 |
keyword is used, the forgotten characters are written to |
| 717 |
expect_out(buffer). |
| 718 |
|
| 719 |
If |
| 720 |
.I patlist |
| 721 |
is the keyword |
| 722 |
.BR null , |
| 723 |
and nulls are allowed (via the |
| 724 |
.B remove_nulls |
| 725 |
command), the corresponding body is executed if a single ASCII |
| 726 |
0 is matched. |
| 727 |
It is not possible to |
| 728 |
match 0 bytes via glob or regexp patterns. |
| 729 |
|
| 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) |
| 735 |
through |
| 736 |
.IR expect_out(9,string) . |
| 737 |
If the |
| 738 |
.B \-indices |
| 739 |
flag is used before a pattern, |
| 740 |
the starting and ending indices (in a form suitable for |
| 741 |
.BR lrange ) |
| 742 |
of the |
| 743 |
10 strings are stored in the variables |
| 744 |
.I expect_out(X,start) |
| 745 |
and |
| 746 |
.I expect_out(X,end) |
| 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\en", the result of: |
| 751 |
.nf |
| 752 |
|
| 753 |
expect "cd" |
| 754 |
|
| 755 |
.fi |
| 756 |
is as if the following statements had executed: |
| 757 |
.nf |
| 758 |
|
| 759 |
set expect_out(0,string) cd |
| 760 |
set expect_out(buffer) abcd |
| 761 |
|
| 762 |
.fi |
| 763 |
and "efgh\en" is left in the output buffer. |
| 764 |
If a process produced the output "abbbcabkkkka\en", the result of: |
| 765 |
.nf |
| 766 |
|
| 767 |
expect \-indices \-re "b(b*).*(k+)" |
| 768 |
|
| 769 |
.fi |
| 770 |
is as if the following statements had executed: |
| 771 |
.nf |
| 772 |
|
| 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 |
| 783 |
|
| 784 |
.fi |
| 785 |
and "a\en" is left in the output buffer. The pattern "*" (and \-re ".*") will |
| 786 |
flush the output buffer without reading any more output from the |
| 787 |
process. |
| 788 |
.IP |
| 789 |
Normally, the matched output is discarded from Expect's internal buffers. |
| 790 |
This may be prevented by prefixing a pattern with the |
| 791 |
.B \-notransfer |
| 792 |
flag. This flag is especially useful in experimenting (and can be |
| 793 |
abbreviated to "\-not" for convenience while experimenting). |
| 794 |
|
| 795 |
The spawn id associated with the matching output (or eof or |
| 796 |
full_buffer) is stored in |
| 797 |
.IR expect_out(spawn_id) . |
| 798 |
|
| 799 |
The |
| 800 |
.B \-timeout |
| 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. |
| 803 |
|
| 804 |
By default, |
| 805 |
patterns are matched against output from the current process, however the |
| 806 |
.B \-i |
| 807 |
flag declares the output from the named spawn_id list be matched against |
| 808 |
any following patterns (up to the next |
| 809 |
.BR \-i ). |
| 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. |
| 812 |
|
| 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. |
| 816 |
.nf |
| 817 |
|
| 818 |
expect { |
| 819 |
\-i $proc2 busy {puts busy\en ; exp_continue} |
| 820 |
\-re "failed|invalid password" abort |
| 821 |
timeout abort |
| 822 |
connected |
| 823 |
} |
| 824 |
|
| 825 |
.fi |
| 826 |
The value of the global variable |
| 827 |
.IR any_spawn_id |
| 828 |
may be used to match patterns to any spawn_ids that are named |
| 829 |
with all other |
| 830 |
.B \-i |
| 831 |
flags in the current |
| 832 |
.B expect |
| 833 |
command. |
| 834 |
The spawn_id from a |
| 835 |
.B \-i |
| 836 |
flag with no associated pattern (i.e., followed immediately |
| 837 |
by another |
| 838 |
.BR \-i ) |
| 839 |
is made available to any other patterns |
| 840 |
in the same |
| 841 |
.B expect |
| 842 |
command associated with |
| 843 |
.I any_spawn_id. |
| 844 |
|
| 845 |
The |
| 846 |
.B \-i |
| 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. |
| 851 |
|
| 852 |
Actions such as |
| 853 |
.B break |
| 854 |
and |
| 855 |
.B continue |
| 856 |
cause control structures (i.e., |
| 857 |
.BR for , |
| 858 |
.BR proc ) |
| 859 |
to behave in the usual way. |
| 860 |
The command |
| 861 |
.B exp_continue |
| 862 |
allows |
| 863 |
.B expect |
| 864 |
itself to continue |
| 865 |
executing rather than returning as it normally would. |
| 866 |
.IP |
| 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 |
| 869 |
.B exp_continue |
| 870 |
avoids having to write a second |
| 871 |
.B expect |
| 872 |
statement (to look for the prompt again) if the rlogin prompts for a password. |
| 873 |
.nf |
| 874 |
|
| 875 |
expect { |
| 876 |
Password: { |
| 877 |
stty \-echo |
| 878 |
send_user "password (for $user) on $host: " |
| 879 |
expect_user \-re "(.*)\en" |
| 880 |
send_user "\en" |
| 881 |
send "$expect_out(1,string)\er" |
| 882 |
stty echo |
| 883 |
exp_continue |
| 884 |
} incorrect { |
| 885 |
send_user "invalid password or account\en" |
| 886 |
exit |
| 887 |
} timeout { |
| 888 |
send_user "connection to $host timed out\en" |
| 889 |
exit |
| 890 |
} eof { |
| 891 |
send_user \e |
| 892 |
"connection to host failed: $expect_out(buffer)" |
| 893 |
exit |
| 894 |
} \-re $prompt |
| 895 |
} |
| 896 |
|
| 897 |
.fi |
| 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. |
| 904 |
In each case, the |
| 905 |
.B exp_continue |
| 906 |
allows the current |
| 907 |
.B expect |
| 908 |
to continue pattern matching after executing the |
| 909 |
current action. |
| 910 |
.nf |
| 911 |
|
| 912 |
stty raw \-echo |
| 913 |
expect_after { |
| 914 |
\-i $user_spawn_id |
| 915 |
"p" {send "\er\er\er"; exp_continue} |
| 916 |
"+" {incr foo; exp_continue} |
| 917 |
"i" {interact; exp_continue} |
| 918 |
"quit" exit |
| 919 |
} |
| 920 |
|
| 921 |
.fi |
| 922 |
.IP |
| 923 |
By default, |
| 924 |
.B exp_continue |
| 925 |
resets the timeout timer. The timer is not restarted, if |
| 926 |
.B exp_continue |
| 927 |
is called with the |
| 928 |
.B \-continue_timer |
| 929 |
flag. |
| 930 |
.TP |
| 931 |
.BI expect_after " [expect_args]" |
| 932 |
works identically to the |
| 933 |
.B expect_before |
| 934 |
except that if patterns from both |
| 935 |
.B expect |
| 936 |
and |
| 937 |
.B expect_after |
| 938 |
can match, the |
| 939 |
.B expect |
| 940 |
pattern is used. See the |
| 941 |
.B expect_before |
| 942 |
command for more information. |
| 943 |
.TP |
| 944 |
.BI expect_background " [expect_args]" |
| 945 |
takes the same arguments as |
| 946 |
.BR expect , |
| 947 |
however it returns immediately. |
| 948 |
Patterns are tested whenever new input arrives. |
| 949 |
The pattern |
| 950 |
.B timeout |
| 951 |
and |
| 952 |
.B default |
| 953 |
are meaningless to |
| 954 |
.B expect_background |
| 955 |
and are silently discarded. |
| 956 |
Otherwise, the |
| 957 |
.B expect_background |
| 958 |
command uses |
| 959 |
.B expect_before |
| 960 |
and |
| 961 |
.B expect_after |
| 962 |
patterns just like |
| 963 |
.B expect |
| 964 |
does. |
| 965 |
|
| 966 |
When |
| 967 |
.B expect_background |
| 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) |
| 972 |
.B expect |
| 973 |
on the same spawn id. |
| 974 |
|
| 975 |
It is not possible to execute an |
| 976 |
.B expect |
| 977 |
while an |
| 978 |
.B expect_background |
| 979 |
is unblocked. |
| 980 |
.B expect_background |
| 981 |
for a particular spawn id is deleted by |
| 982 |
declaring a new expect_background with the same spawn id. Declaring |
| 983 |
.B expect_background |
| 984 |
with no pattern removes the given spawn id |
| 985 |
from the ability to match patterns in the background. |
| 986 |
.TP |
| 987 |
.BI expect_before " [expect_args]" |
| 988 |
takes the same arguments as |
| 989 |
.BR expect , |
| 990 |
however it returns immediately. |
| 991 |
Pattern-action pairs from the most recent |
| 992 |
.B expect_before |
| 993 |
with the same spawn id are implicitly added to any following |
| 994 |
.B expect |
| 995 |
commands. If a pattern matches, it is treated as if it had been |
| 996 |
specified in the |
| 997 |
.B expect |
| 998 |
command itself, and the associated body is executed in the context |
| 999 |
of the |
| 1000 |
.B expect |
| 1001 |
command. |
| 1002 |
If patterns from both |
| 1003 |
.B expect_before |
| 1004 |
and |
| 1005 |
.B expect |
| 1006 |
can match, the |
| 1007 |
.B expect_before |
| 1008 |
pattern is used. |
| 1009 |
|
| 1010 |
If no pattern is specified, the spawn id is not checked for any patterns. |
| 1011 |
|
| 1012 |
Unless overridden by a |
| 1013 |
.B \-i |
| 1014 |
flag, |
| 1015 |
.B expect_before |
| 1016 |
patterns match against the spawn id defined at the time that the |
| 1017 |
.B expect_before |
| 1018 |
command was executed (not when its pattern is matched). |
| 1019 |
|
| 1020 |
The \-info flag causes |
| 1021 |
.B expect_before |
| 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 |
| 1024 |
.nf |
| 1025 |
|
| 1026 |
expect_before \-info \-i $proc |
| 1027 |
|
| 1028 |
.fi |
| 1029 |
At most one spawn id specification may be given. The flag \-indirect |
| 1030 |
suppresses direct spawn ids that come only from indirect specifications. |
| 1031 |
|
| 1032 |
Instead of a spawn id specification, the flag "\-all" will cause |
| 1033 |
"\-info" to report on all spawn ids. |
| 1034 |
|
| 1035 |
The output of the \-info flag can be reused as the argument to expect_before. |
| 1036 |
.TP |
| 1037 |
.BI expect_tty " [expect_args]" |
| 1038 |
is like |
| 1039 |
.B expect |
| 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 |
| 1043 |
.B expect |
| 1044 |
to see them. |
| 1045 |
This may be changed via |
| 1046 |
.B stty |
| 1047 |
(see the |
| 1048 |
.B stty |
| 1049 |
command below). |
| 1050 |
.TP |
| 1051 |
.BI expect_user " [expect_args]" |
| 1052 |
is like |
| 1053 |
.B expect |
| 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 |
| 1057 |
.B expect |
| 1058 |
to see them. |
| 1059 |
This may be changed via |
| 1060 |
.B stty |
| 1061 |
(see the |
| 1062 |
.B stty |
| 1063 |
command below). |
| 1064 |
.TP |
| 1065 |
.B fork |
| 1066 |
creates a new process. The new process is an exact copy of the current |
| 1067 |
.B Expect |
| 1068 |
process. On success, |
| 1069 |
.B fork |
| 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), |
| 1073 |
.B fork |
| 1074 |
returns \-1 to the parent process, and no child process is created. |
| 1075 |
.IP |
| 1076 |
Forked processes exit via the |
| 1077 |
.B exit |
| 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 |
| 1081 |
confusing. |
| 1082 |
.IP |
| 1083 |
Some pty implementations may be confused by multiple readers and writers, |
| 1084 |
even momentarily. Thus, it is safest to |
| 1085 |
.B fork |
| 1086 |
before spawning processes. |
| 1087 |
.TP |
| 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. |
| 1092 |
.IP |
| 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 |
| 1096 |
.B interpreter |
| 1097 |
command is assumed, if the final body is missing. |
| 1098 |
.IP |
| 1099 |
If the arguments to the entire |
| 1100 |
.B interact |
| 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. |
| 1105 |
.IP |
| 1106 |
For example, the following command runs interact with the following |
| 1107 |
string-body pairs defined: When ^Z is pressed, |
| 1108 |
.B Expect |
| 1109 |
is suspended. |
| 1110 |
(The |
| 1111 |
.B \-reset |
| 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. |
| 1115 |
When ^C is pressed, |
| 1116 |
.B Expect |
| 1117 |
exits. If "foo" is entered, the user sees "bar". |
| 1118 |
When ~~ is pressed, the |
| 1119 |
.B Expect |
| 1120 |
interpreter runs interactively. |
| 1121 |
.nf |
| 1122 |
|
| 1123 |
.ta \w' interact 'u +\w'$CTRLZ 'u +\w'{'u |
| 1124 |
set CTRLZ \e032 |
| 1125 |
interact { |
| 1126 |
\-reset $CTRLZ {exec kill \-STOP [pid]} |
| 1127 |
\e001 {send_user "you typed a control\-A\en"; |
| 1128 |
send "\e001" |
| 1129 |
} |
| 1130 |
$ {send_user "The date is [clock format [clock seconds]]."} |
| 1131 |
\e003 exit |
| 1132 |
foo {send_user "bar"} |
| 1133 |
~~ |
| 1134 |
} |
| 1135 |
|
| 1136 |
.fi |
| 1137 |
.IP |
| 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. |
| 1146 |
.IP |
| 1147 |
By default, string matching is exact with no wild cards. (In contrast, |
| 1148 |
the |
| 1149 |
.B expect |
| 1150 |
command uses glob-style patterns by default.) The |
| 1151 |
.B \-ex |
| 1152 |
flag may be used to protect patterns that might otherwise match |
| 1153 |
.B interact |
| 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.) |
| 1157 |
|
| 1158 |
The |
| 1159 |
.B \-re |
| 1160 |
flag forces the string to be interpreted as a regexp-style pattern. In this |
| 1161 |
case, matching substrings are stored in the variable |
| 1162 |
.I interact_out |
| 1163 |
similarly to the way |
| 1164 |
.B expect |
| 1165 |
stores its output in the variable |
| 1166 |
.BR expect_out . |
| 1167 |
The |
| 1168 |
.B \-indices |
| 1169 |
flag is similarly supported. |
| 1170 |
|
| 1171 |
The pattern |
| 1172 |
.B eof |
| 1173 |
introduces an action that is |
| 1174 |
executed upon end-of-file. A separate |
| 1175 |
.B eof |
| 1176 |
pattern may also follow the |
| 1177 |
.B \-output |
| 1178 |
flag in which case it is matched if an eof is detected while writing output. |
| 1179 |
The default |
| 1180 |
.B eof |
| 1181 |
action is "return", so that |
| 1182 |
.B interact |
| 1183 |
simply returns upon any EOF. |
| 1184 |
|
| 1185 |
The pattern |
| 1186 |
.B timeout |
| 1187 |
introduces a timeout (in seconds) and action that is executed |
| 1188 |
after no characters have been read for a given time. |
| 1189 |
The |
| 1190 |
.B timeout |
| 1191 |
pattern applies to the most recently specified process. |
| 1192 |
There is no default timeout. |
| 1193 |
The special variable "timeout" (used by the |
| 1194 |
.B expect |
| 1195 |
command) has no affect on this timeout. |
| 1196 |
|
| 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 |
| 1199 |
messages: |
| 1200 |
.nf |
| 1201 |
|
| 1202 |
interact \-input $user_spawn_id timeout 3600 return \-output \e |
| 1203 |
$spawn_id |
| 1204 |
|
| 1205 |
.fi |
| 1206 |
|
| 1207 |
If the pattern is the keyword |
| 1208 |
.BR null , |
| 1209 |
and nulls are allowed (via the |
| 1210 |
.B remove_nulls |
| 1211 |
command), the corresponding body is executed if a single ASCII |
| 1212 |
0 is matched. |
| 1213 |
It is not possible to |
| 1214 |
match 0 bytes via glob or regexp patterns. |
| 1215 |
|
| 1216 |
Prefacing a pattern with the flag |
| 1217 |
.B \-iwrite |
| 1218 |
causes the variable |
| 1219 |
.I interact_out(spawn_id) |
| 1220 |
to be set to the spawn_id which matched the pattern |
| 1221 |
(or eof). |
| 1222 |
|
| 1223 |
Actions such as |
| 1224 |
.B break |
| 1225 |
and |
| 1226 |
.B continue |
| 1227 |
cause control structures (i.e., |
| 1228 |
.BR for , |
| 1229 |
.BR proc ) |
| 1230 |
to behave in the usual way. |
| 1231 |
However |
| 1232 |
.B return |
| 1233 |
causes interact to return to its caller, while |
| 1234 |
.B inter_return |
| 1235 |
causes |
| 1236 |
.B interact |
| 1237 |
to cause a return in its caller. For example, if "proc foo" called |
| 1238 |
.B interact |
| 1239 |
which then executed the action |
| 1240 |
.BR inter_return , |
| 1241 |
.B proc foo |
| 1242 |
would return. (This means that if |
| 1243 |
.B interact |
| 1244 |
calls |
| 1245 |
.B interpreter |
| 1246 |
interactively typing |
| 1247 |
.B return |
| 1248 |
will cause the interact to continue, while |
| 1249 |
.B inter_return |
| 1250 |
will cause the interact to return to its caller.) |
| 1251 |
.IP |
| 1252 |
During |
| 1253 |
.BR interact , |
| 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 |
| 1261 |
.B Expect |
| 1262 |
itself, first call interpreter (perhaps by using an escape character), and then press ^Z. |
| 1263 |
.IP |
| 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. |
| 1267 |
.IP |
| 1268 |
For speed, actions execute in raw mode by default. The |
| 1269 |
.B \-reset |
| 1270 |
flag resets the terminal to the mode it had before |
| 1271 |
.B interact |
| 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 |
| 1276 |
.B \-reset |
| 1277 |
is if your action |
| 1278 |
depends on running in cooked mode. |
| 1279 |
.IP |
| 1280 |
The |
| 1281 |
.B \-echo |
| 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. |
| 1285 |
.IP |
| 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. |
| 1289 |
.B \-echo |
| 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 |
| 1297 |
the result anyway. |
| 1298 |
.nf |
| 1299 |
|
| 1300 |
interact { |
| 1301 |
\-echo ~g {getcurdirectory 1} |
| 1302 |
\-echo ~l {getcurdirectory 0} |
| 1303 |
\-echo ~p {putcurdirectory} |
| 1304 |
} |
| 1305 |
|
| 1306 |
.fi |
| 1307 |
The |
| 1308 |
.B \-nobuffer |
| 1309 |
flag sends characters that match the following pattern on to |
| 1310 |
the output process as characters are read. |
| 1311 |
|
| 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. |
| 1316 |
.nf |
| 1317 |
|
| 1318 |
proc lognumber {} { |
| 1319 |
interact \-nobuffer \-re "(.*)\er" return |
| 1320 |
puts $log "[clock format [clock seconds]]: dialed $interact_out(1,string)" |
| 1321 |
} |
| 1322 |
|
| 1323 |
interact \-nobuffer "atd" lognumber |
| 1324 |
|
| 1325 |
.fi |
| 1326 |
.IP |
| 1327 |
During |
| 1328 |
.BR interact , |
| 1329 |
previous use of |
| 1330 |
.B log_user |
| 1331 |
is ignored. In particular, |
| 1332 |
.B interact |
| 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. |
| 1335 |
.IP |
| 1336 |
The |
| 1337 |
.B \-o |
| 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. |
| 1342 |
.IP |
| 1343 |
By default, |
| 1344 |
.B interact |
| 1345 |
expects the user to be writing stdin and reading stdout of the |
| 1346 |
.B Expect |
| 1347 |
process |
| 1348 |
itself. |
| 1349 |
The |
| 1350 |
.B \-u |
| 1351 |
flag (for "user") makes |
| 1352 |
.B interact |
| 1353 |
look for the user as the process named by its argument |
| 1354 |
(which must be a spawned id). |
| 1355 |
.IP |
| 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 |
| 1360 |
.B interpreter |
| 1361 |
command will read interactively from stdin. |
| 1362 |
.IP |
| 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. |
| 1368 |
.nf |
| 1369 |
|
| 1370 |
spawn login |
| 1371 |
set login $spawn_id |
| 1372 |
spawn tip modem |
| 1373 |
# dial back out to user |
| 1374 |
# connect user to login |
| 1375 |
interact \-u $login |
| 1376 |
|
| 1377 |
.fi |
| 1378 |
To send output to multiple processes, list each spawn id list prefaced by a |
| 1379 |
.B \-output |
| 1380 |
flag. Input for a group of output spawn ids may be determined |
| 1381 |
by a spawn id list prefaced by a |
| 1382 |
.B \-input |
| 1383 |
flag. (Both |
| 1384 |
.B \-input |
| 1385 |
and |
| 1386 |
.B \-output |
| 1387 |
may take lists in the same form as the |
| 1388 |
.B \-i |
| 1389 |
flag in the |
| 1390 |
.B expect |
| 1391 |
command, except that any_spawn_id is not meaningful in |
| 1392 |
.BR interact .) |
| 1393 |
All following flags and |
| 1394 |
strings (or patterns) apply to this input until another \-input flag appears. |
| 1395 |
If no |
| 1396 |
.B \-input |
| 1397 |
appears, |
| 1398 |
.B \-output |
| 1399 |
implies "\-input $user_spawn_id \-output". |
| 1400 |
(Similarly, with patterns that do not have |
| 1401 |
.BR \-input .) |
| 1402 |
If one |
| 1403 |
.B \-input |
| 1404 |
is specified, it overrides $user_spawn_id. If a second |
| 1405 |
.B \-input |
| 1406 |
is specified, |
| 1407 |
it overrides $spawn_id. Additional |
| 1408 |
.B \-input |
| 1409 |
flags may be specified. |
| 1410 |
|
| 1411 |
The two implied input processes default to having their outputs specified as |
| 1412 |
$spawn_id and $user_spawn_id (in reverse). |
| 1413 |
If a |
| 1414 |
.B \-input |
| 1415 |
flag appears |
| 1416 |
with no |
| 1417 |
.B \-output |
| 1418 |
flag, characters from that process are discarded. |
| 1419 |
|
| 1420 |
The |
| 1421 |
.B \-i |
| 1422 |
flag introduces a replacement for the current spawn_id when no |
| 1423 |
other |
| 1424 |
.B \-input |
| 1425 |
or |
| 1426 |
.B \-output |
| 1427 |
flags are used. A \-i flag implies a \-o flag. |
| 1428 |
|
| 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. |
| 1433 |
.TP |
| 1434 |
.B interpreter " [args]" |
| 1435 |
causes the user to be interactively prompted for |
| 1436 |
.B Expect |
| 1437 |
and Tcl commands. |
| 1438 |
The result of each command is printed. |
| 1439 |
.IP |
| 1440 |
Actions such as |
| 1441 |
.B break |
| 1442 |
and |
| 1443 |
.B continue |
| 1444 |
cause control structures (i.e., |
| 1445 |
.BR for , |
| 1446 |
.BR proc ) |
| 1447 |
to behave in the usual way. |
| 1448 |
However |
| 1449 |
.B return |
| 1450 |
causes interpreter to return to its caller, while |
| 1451 |
.B inter_return |
| 1452 |
causes |
| 1453 |
.B interpreter |
| 1454 |
to cause a return in its caller. For example, if "proc foo" called |
| 1455 |
.B interpreter |
| 1456 |
which then executed the action |
| 1457 |
.BR inter_return , |
| 1458 |
.B proc foo |
| 1459 |
would return. |
| 1460 |
Any other command causes |
| 1461 |
.B interpreter |
| 1462 |
to continue prompting for new commands. |
| 1463 |
.IP |
| 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". |
| 1472 |
.IP |
| 1473 |
During |
| 1474 |
.BR interpreter , |
| 1475 |
cooked mode is used, even if the its caller was using raw mode. |
| 1476 |
.IP |
| 1477 |
If stdin is closed, |
| 1478 |
.B interpreter |
| 1479 |
will return unless the |
| 1480 |
.B \-eof |
| 1481 |
flag is used, in which case the subsequent argument is invoked. |
| 1482 |
.TP |
| 1483 |
.BI log_file " [args] [[\-a] file]" |
| 1484 |
If a filename is provided, |
| 1485 |
.B log_file |
| 1486 |
will record a transcript of the session (beginning at that point) in the file. |
| 1487 |
.B log_file |
| 1488 |
will stop recording if no argument is given. Any previous log file is closed. |
| 1489 |
|
| 1490 |
Instead of a filename, a Tcl file identifier may be provided by using the |
| 1491 |
.B \-open |
| 1492 |
or |
| 1493 |
.B \-leaveopen |
| 1494 |
flags. This is similar to the |
| 1495 |
.B spawn |
| 1496 |
command. (See |
| 1497 |
.B spawn |
| 1498 |
for more info.) |
| 1499 |
|
| 1500 |
The |
| 1501 |
.B \-a |
| 1502 |
flag forces output to be logged that was suppressed by the |
| 1503 |
.B log_user |
| 1504 |
command. |
| 1505 |
|
| 1506 |
By default, the |
| 1507 |
.B log_file |
| 1508 |
command |
| 1509 |
.I appends |
| 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 |
| 1514 |
.B \-noappend |
| 1515 |
flag. |
| 1516 |
|
| 1517 |
The |
| 1518 |
.B \-info |
| 1519 |
flag causes log_file to return a description of the |
| 1520 |
most recent non-info arguments given. |
| 1521 |
.TP |
| 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. |
| 1527 |
|
| 1528 |
The |
| 1529 |
.B \-info |
| 1530 |
flag causes log_user to return a description of the |
| 1531 |
most recent non-info arguments given. |
| 1532 |
.TP |
| 1533 |
.BI match_max " [\-d] [\-i spawn_id] [size]" |
| 1534 |
defines the size of the buffer (in bytes) used internally by |
| 1535 |
.BR expect . |
| 1536 |
With no |
| 1537 |
.I size |
| 1538 |
argument, the current size is returned. |
| 1539 |
.IP |
| 1540 |
With the |
| 1541 |
.B \-d |
| 1542 |
flag, the default size is set. (The initial default is 2000.) |
| 1543 |
With the |
| 1544 |
.B \-i |
| 1545 |
flag, the size is set for the named spawn id, otherwise it is set for |
| 1546 |
the current process. |
| 1547 |
.TP |
| 1548 |
.BI overlay " [\-# spawn_id] [\-# spawn_id] [...] program [args]" |
| 1549 |
executes |
| 1550 |
.I "program args" |
| 1551 |
in place of the current |
| 1552 |
.B Expect |
| 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. |
| 1558 |
.IP |
| 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. |
| 1562 |
.nf |
| 1563 |
|
| 1564 |
overlay \-0 $spawn_id \-1 $spawn_id \-2 $spawn_id chess |
| 1565 |
|
| 1566 |
.fi |
| 1567 |
This is more efficient than |
| 1568 |
"interact \-u", however, it sacrifices the ability to do programmed |
| 1569 |
interaction since the |
| 1570 |
.B Expect |
| 1571 |
process is no longer in control. |
| 1572 |
.IP |
| 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. |
| 1576 |
.TP |
| 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 |
| 1580 |
.I value |
| 1581 |
is zero, parity is stripped, otherwise it is not stripped. |
| 1582 |
With no |
| 1583 |
.I value |
| 1584 |
argument, the current value is returned. |
| 1585 |
.IP |
| 1586 |
With the |
| 1587 |
.B \-d |
| 1588 |
flag, the default parity value is set. (The initial default is 1, i.e., |
| 1589 |
parity is not stripped.) |
| 1590 |
With the |
| 1591 |
.B \-i |
| 1592 |
flag, the parity value is set for the named spawn id, otherwise it is set for |
| 1593 |
the current process. |
| 1594 |
.TP |
| 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 |
| 1599 |
.I expect_out |
| 1600 |
or |
| 1601 |
.IR interact_out . |
| 1602 |
If |
| 1603 |
.I value |
| 1604 |
is 1, nulls are removed. If |
| 1605 |
.I value |
| 1606 |
is 0, nulls are not removed. |
| 1607 |
With no |
| 1608 |
.I value |
| 1609 |
argument, the current value is returned. |
| 1610 |
.IP |
| 1611 |
With the |
| 1612 |
.B \-d |
| 1613 |
flag, the default value is set. (The initial default is 1, i.e., |
| 1614 |
nulls are removed.) |
| 1615 |
With the |
| 1616 |
.B \-i |
| 1617 |
flag, the value is set for the named spawn id, otherwise it is set for |
| 1618 |
the current process. |
| 1619 |
|
| 1620 |
Whether or not nulls are removed, |
| 1621 |
.B Expect |
| 1622 |
will record null bytes to the log and stdout. |
| 1623 |
.TP |
| 1624 |
.BI send " [\-flags] string" |
| 1625 |
Sends |
| 1626 |
.I string |
| 1627 |
to the current process. |
| 1628 |
For example, the command |
| 1629 |
.nf |
| 1630 |
|
| 1631 |
send "hello world\er" |
| 1632 |
|
| 1633 |
.fi |
| 1634 |
sends the characters, h e l l o <blank> w o r l d <return> to the |
| 1635 |
current process. |
| 1636 |
(Tcl includes a printf-like command (called |
| 1637 |
.BR format ) |
| 1638 |
which can build arbitrarily complex strings.) |
| 1639 |
.IP |
| 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 "\er". |
| 1643 |
|
| 1644 |
The |
| 1645 |
.B \-\- |
| 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.) |
| 1651 |
|
| 1652 |
The |
| 1653 |
.B \-i |
| 1654 |
flag declares that the string be sent to the named spawn_id. |
| 1655 |
If the spawn_id is |
| 1656 |
.IR user_spawn_id , |
| 1657 |
and the terminal is in raw mode, newlines in the string are translated |
| 1658 |
to return-newline |
| 1659 |
sequences so that they appear as if the terminal was in cooked mode. |
| 1660 |
The |
| 1661 |
.B \-raw |
| 1662 |
flag disables this translation. |
| 1663 |
|
| 1664 |
The |
| 1665 |
.B \-null |
| 1666 |
flag sends null characters (0 bytes). By default, one null is sent. |
| 1667 |
An integer may follow the |
| 1668 |
.B \-null |
| 1669 |
to indicate how many nulls to send. |
| 1670 |
|
| 1671 |
The |
| 1672 |
.B \-break |
| 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 |
| 1676 |
generating a break. |
| 1677 |
|
| 1678 |
The |
| 1679 |
.B \-s |
| 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 |
| 1689 |
characters sent. |
| 1690 |
|
| 1691 |
The |
| 1692 |
.B \-h |
| 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. |
| 1708 |
|
| 1709 |
As an |
| 1710 |
example, the following command emulates a fast and |
| 1711 |
consistent typist: |
| 1712 |
.nf |
| 1713 |
|
| 1714 |
set send_human {.1 .3 1 .05 2} |
| 1715 |
send \-h "I'm hungry. Let's do lunch." |
| 1716 |
|
| 1717 |
.fi |
| 1718 |
while the following might be more suitable after a hangover: |
| 1719 |
.nf |
| 1720 |
|
| 1721 |
set send_human {.4 .4 .2 .5 100} |
| 1722 |
send \-h "Goodd party lash night!" |
| 1723 |
|
| 1724 |
.fi |
| 1725 |
Note that errors are not simulated, although you can set up error |
| 1726 |
correction situations yourself by embedding mistakes and corrections |
| 1727 |
in a send argument. |
| 1728 |
|
| 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 |
| 1732 |
.I string |
| 1733 |
argument can be specified with the flags for sending null characters or breaks. |
| 1734 |
|
| 1735 |
It is a good idea to precede the first |
| 1736 |
.B send |
| 1737 |
to a process by an |
| 1738 |
.BR expect . |
| 1739 |
.B expect |
| 1740 |
will wait for the process to start, while |
| 1741 |
.B send |
| 1742 |
cannot. |
| 1743 |
In particular, if the first |
| 1744 |
.B send |
| 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, |
| 1748 |
you can precede |
| 1749 |
.B send |
| 1750 |
by a delay as in: |
| 1751 |
.nf |
| 1752 |
|
| 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 |
| 1757 |
sleep 5 |
| 1758 |
send password\er |
| 1759 |
|
| 1760 |
.fi |
| 1761 |
.B exp_send |
| 1762 |
is an alias for |
| 1763 |
.BI send . |
| 1764 |
If you are using Expectk or some other variant of Expect in the Tk environment, |
| 1765 |
.B send |
| 1766 |
is defined by Tk for an entirely different purpose. |
| 1767 |
.B exp_send |
| 1768 |
is provided for compatibility between environments. |
| 1769 |
Similar aliases are provided for other Expect's other send commands. |
| 1770 |
.TP |
| 1771 |
.BI send_error " [\-flags] string" |
| 1772 |
is like |
| 1773 |
.BR send , |
| 1774 |
except that the output is sent to stderr rather than the current |
| 1775 |
process. |
| 1776 |
.TP |
| 1777 |
.BI send_log " [\-\-] string" |
| 1778 |
is like |
| 1779 |
.BR send , |
| 1780 |
except that the string is only sent to the log file (see |
| 1781 |
.BR log_file .) |
| 1782 |
The arguments are ignored if no log file is open. |
| 1783 |
.TP |
| 1784 |
.BI send_tty " [\-flags] string" |
| 1785 |
is like |
| 1786 |
.BR send , |
| 1787 |
except that the output is sent to /dev/tty rather than the current |
| 1788 |
process. |
| 1789 |
.TP |
| 1790 |
.BI send_user " [\-flags] string" |
| 1791 |
is like |
| 1792 |
.BR send , |
| 1793 |
except that the output is sent to stdout rather than the current |
| 1794 |
process. |
| 1795 |
.TP |
| 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. |
| 1800 |
.TP |
| 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 |
| 1806 |
.B Expect |
| 1807 |
commands. |
| 1808 |
The connection is broken by |
| 1809 |
.B close |
| 1810 |
or if the process itself closes any of the file identifiers. |
| 1811 |
.IP |
| 1812 |
When a process is started by |
| 1813 |
.BR spawn , |
| 1814 |
the variable |
| 1815 |
.I spawn_id |
| 1816 |
is set to a descriptor referring to that process. |
| 1817 |
The process described by |
| 1818 |
.I spawn_id |
| 1819 |
is considered the |
| 1820 |
.IR "current process" . |
| 1821 |
.I spawn_id |
| 1822 |
may be read or written, in effect providing job control. |
| 1823 |
.IP |
| 1824 |
.I user_spawn_id |
| 1825 |
is a global variable containing a descriptor which refers to the user. |
| 1826 |
For example, when |
| 1827 |
.I spawn_id |
| 1828 |
is set to this value, |
| 1829 |
.B expect |
| 1830 |
behaves like |
| 1831 |
.BR expect_user . |
| 1832 |
|
| 1833 |
.I |
| 1834 |
.I error_spawn_id |
| 1835 |
is a global variable containing a descriptor which refers to the standard |
| 1836 |
error. |
| 1837 |
For example, when |
| 1838 |
.I spawn_id |
| 1839 |
is set to this value, |
| 1840 |
.B send |
| 1841 |
behaves like |
| 1842 |
.BR send_error . |
| 1843 |
.IP |
| 1844 |
.I tty_spawn_id |
| 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 |
| 1847 |
.I tty_spawn_id |
| 1848 |
is not defined. This may be tested as: |
| 1849 |
.nf |
| 1850 |
|
| 1851 |
if {[info vars tty_spawn_id]} { |
| 1852 |
# /dev/tty exists |
| 1853 |
} else { |
| 1854 |
# /dev/tty doesn't exist |
| 1855 |
# probably in cron, batch, or at script |
| 1856 |
} |
| 1857 |
|
| 1858 |
.fi |
| 1859 |
.IP |
| 1860 |
.B spawn |
| 1861 |
returns the UNIX process id. If no process is spawned, 0 is returned. |
| 1862 |
The variable |
| 1863 |
.I spawn_out(slave,name) |
| 1864 |
is set to the name of the pty slave device. |
| 1865 |
.IP |
| 1866 |
By default, |
| 1867 |
.B spawn |
| 1868 |
echoes the command name and arguments. The |
| 1869 |
.B \-noecho |
| 1870 |
flag stops |
| 1871 |
.B spawn |
| 1872 |
from doing this. |
| 1873 |
.IP |
| 1874 |
The |
| 1875 |
.B \-console |
| 1876 |
flag causes console output to be redirected to the spawned process. |
| 1877 |
This is not supported on all systems. |
| 1878 |
|
| 1879 |
Internally, |
| 1880 |
.B spawn |
| 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)). |
| 1883 |
If the variable |
| 1884 |
.I stty_init |
| 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. |
| 1889 |
.B \-nottycopy |
| 1890 |
skips the initialization based on the user's tty. |
| 1891 |
.B \-nottyinit |
| 1892 |
skips the "sane" initialization. |
| 1893 |
.IP |
| 1894 |
Normally, |
| 1895 |
.B spawn |
| 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 |
| 1900 |
Expect with the |
| 1901 |
.B \-d |
| 1902 |
option will show if |
| 1903 |
.B Expect |
| 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 |
| 1906 |
be to reboot. |
| 1907 |
|
| 1908 |
If |
| 1909 |
.I program |
| 1910 |
cannot be spawned successfully because |
| 1911 |
.BR exec (2) |
| 1912 |
fails (e.g. when |
| 1913 |
.I program |
| 1914 |
doesn't exist), an error message will be returned by the next |
| 1915 |
.B interact |
| 1916 |
or |
| 1917 |
.B expect |
| 1918 |
command as if |
| 1919 |
.I program |
| 1920 |
had run and produced the error message as output. |
| 1921 |
This behavior is a natural consequence of the implementation of |
| 1922 |
.BR spawn . |
| 1923 |
Internally, spawn forks, after which the spawned process has no |
| 1924 |
way to communicate with the original |
| 1925 |
.B Expect |
| 1926 |
process except by communication |
| 1927 |
via the spawn_id. |
| 1928 |
|
| 1929 |
The |
| 1930 |
.B \-open |
| 1931 |
flag causes the next argument to be interpreted as a Tcl file identifier |
| 1932 |
(i.e., returned by |
| 1933 |
.BR open .) |
| 1934 |
The spawn id can then be used as if it were a spawned process. (The file |
| 1935 |
identifier should no longer be used.) |
| 1936 |
This lets you treat raw devices, files, and |
| 1937 |
pipelines as spawned processes without using a pty. 0 is returned to |
| 1938 |
indicate there is no associated process. When the connection to |
| 1939 |
the spawned process is closed, so is the Tcl file identifier. |
| 1940 |
The |
| 1941 |
.B \-leaveopen |
| 1942 |
flag is similar to |
| 1943 |
.B \-open |
| 1944 |
except that |
| 1945 |
.B \-leaveopen |
| 1946 |
causes the file identifier to be left open even after the spawn id is closed. |
| 1947 |
|
| 1948 |
The |
| 1949 |
.B \-pty |
| 1950 |
flag causes a pty to be opened but no process spawned. 0 is returned |
| 1951 |
to indicate there is no associated process. Spawn_id is set as usual. |
| 1952 |
|
| 1953 |
The variable |
| 1954 |
.I spawn_out(slave,fd) |
| 1955 |
is set to a file identifier corresponding to the pty slave. |
| 1956 |
It can be closed using "close \-slave". |
| 1957 |
|
| 1958 |
The |
| 1959 |
.B \-ignore |
| 1960 |
flag names a signal to be ignored in the spawned process. |
| 1961 |
Otherwise, signals get the default behavior. |
| 1962 |
Signals are named as in the |
| 1963 |
.B trap |
| 1964 |
command, except that each signal requires a separate flag. |
| 1965 |
.TP |
| 1966 |
.BI strace " level" |
| 1967 |
causes following statements to be printed before being executed. |
| 1968 |
(Tcl's trace command traces variables.) |
| 1969 |
.I level |
| 1970 |
indicates how far down in the call stack to trace. |
| 1971 |
For example, |
| 1972 |
the following command runs |
| 1973 |
.B Expect |
| 1974 |
while tracing the first 4 levels of calls, |
| 1975 |
but none below that. |
| 1976 |
.nf |
| 1977 |
|
| 1978 |
expect \-c "strace 4" script.exp |
| 1979 |
|
| 1980 |
.fi |
| 1981 |
|
| 1982 |
The |
| 1983 |
.B \-info |
| 1984 |
flag causes strace to return a description of the |
| 1985 |
most recent non-info arguments given. |
| 1986 |
.TP |
| 1987 |
.BI stty " args" |
| 1988 |
changes terminal modes similarly to the external stty command. |
| 1989 |
|
| 1990 |
By default, the controlling terminal is accessed. Other terminals can |
| 1991 |
be accessed by appending "< /dev/tty...\&" to the command. (Note that |
| 1992 |
the arguments should not be grouped into a single argument.) |
| 1993 |
|
| 1994 |
Requests for status return it as the result of the command. If no status |
| 1995 |
is requested and the controlling terminal is accessed, the previous |
| 1996 |
status of the raw and echo attributes are returned in a form which can |
| 1997 |
later be used by the command. |
| 1998 |
|
| 1999 |
For example, the arguments |
| 2000 |
.B raw |
| 2001 |
or |
| 2002 |
.B \-cooked |
| 2003 |
put the terminal into raw mode. |
| 2004 |
The arguments |
| 2005 |
.B \-raw |
| 2006 |
or |
| 2007 |
.B cooked |
| 2008 |
put the terminal into cooked mode. |
| 2009 |
The arguments |
| 2010 |
.B echo |
| 2011 |
and |
| 2012 |
.B \-echo |
| 2013 |
put the terminal into echo and noecho mode respectively. |
| 2014 |
.IP |
| 2015 |
The following example illustrates how to temporarily disable echoing. |
| 2016 |
This could be used in otherwise-automatic |
| 2017 |
scripts to avoid embedding passwords in them. |
| 2018 |
(See more discussion on this under EXPECT HINTS below.) |
| 2019 |
.nf |
| 2020 |
|
| 2021 |
stty \-echo |
| 2022 |
send_user "Password: " |
| 2023 |
expect_user \-re "(.*)\en" |
| 2024 |
set password $expect_out(1,string) |
| 2025 |
stty echo |
| 2026 |
|
| 2027 |
.fi |
| 2028 |
.TP |
| 2029 |
.BI system " args" |
| 2030 |
gives |
| 2031 |
.I args |
| 2032 |
to sh(1) as input, |
| 2033 |
just as if it had been typed as a command from a terminal. |
| 2034 |
.B Expect |
| 2035 |
waits until the shell terminates. |
| 2036 |
The return status from sh is handled the same way that |
| 2037 |
.B exec |
| 2038 |
handles its return status. |
| 2039 |
.IP |
| 2040 |
In contrast to |
| 2041 |
.B exec |
| 2042 |
which redirects stdin and stdout to the script, |
| 2043 |
.B system |
| 2044 |
performs no redirection |
| 2045 |
(other than that indicated by the string itself). |
| 2046 |
Thus, it is possible to use programs which must talk directly to /dev/tty. |
| 2047 |
For the same reason, the results of |
| 2048 |
.B system |
| 2049 |
are not recorded in the log. |
| 2050 |
.TP |
| 2051 |
.BI timestamp " [args]" |
| 2052 |
returns a timestamp. |
| 2053 |
With no arguments, the number of |
| 2054 |
seconds since the epoch is returned. |
| 2055 |
|
| 2056 |
The |
| 2057 |
.B \-format |
| 2058 |
flag introduces a string which is returned but with |
| 2059 |
substitutions made according to the |
| 2060 |
POSIX rules for strftime. For example %a is replaced by an abbreviated |
| 2061 |
weekday name (i.e., Sat). Others are: |
| 2062 |
.nf |
| 2063 |
%a abbreviated weekday name |
| 2064 |
%A full weekday name |
| 2065 |
%b abbreviated month name |
| 2066 |
%B full month name |
| 2067 |
%c date-time as in: Wed Oct 6 11:45:56 1993 |
| 2068 |
%d day of the month (01\(en31) |
| 2069 |
%H hour (00\(en23) |
| 2070 |
%I hour (01\(en12) |
| 2071 |
%j day (001\(en366) |
| 2072 |
%m month (01\(en12) |
| 2073 |
%M minute (00\(en59) |
| 2074 |
%p am or pm |
| 2075 |
%S second (00\(en61) |
| 2076 |
%u day (1\(en7, Monday is first day of week) |
| 2077 |
%U week (00\(en53, first Sunday is first day of week one) |
| 2078 |
%V week (01\(en53, ISO 8601 style) |
| 2079 |
%w day (0\(en6) |
| 2080 |
%W week (00\(en53, first Monday is first day of week one) |
| 2081 |
%x date-time as in: Wed Oct 6 1993 |
| 2082 |
%X time as in: 23:59:59 |
| 2083 |
%y year (00\(en99) |
| 2084 |
%Y year as in: 1993 |
| 2085 |
%Z timezone (or nothing if not determinable) |
| 2086 |
%% a bare percent sign |
| 2087 |
|
| 2088 |
.fi |
| 2089 |
Other % specifications are undefined. Other characters will be passed |
| 2090 |
through untouched. Only the C locale is supported. |
| 2091 |
|
| 2092 |
The |
| 2093 |
.B \-seconds |
| 2094 |
flag introduces a number of seconds since the epoch to be used as a source |
| 2095 |
from which to format. Otherwise, the current time is used. |
| 2096 |
|
| 2097 |
The |
| 2098 |
.B \-gmt |
| 2099 |
flag forces timestamp output to use the GMT timezone. With no flag, |
| 2100 |
the local timezone is used. |
| 2101 |
.TP |
| 2102 |
.BI trap " [[command] signals]" |
| 2103 |
causes the given |
| 2104 |
.I command |
| 2105 |
to be executed upon future receipt of any of the given signals. |
| 2106 |
The command is executed in the global scope. |
| 2107 |
If |
| 2108 |
.I command |
| 2109 |
is absent, the signal action is returned. |
| 2110 |
If |
| 2111 |
.I command |
| 2112 |
is the string SIG_IGN, the signals are ignored. |
| 2113 |
If |
| 2114 |
.I command |
| 2115 |
is the string SIG_DFL, the signals are result to the system default. |
| 2116 |
.I signals |
| 2117 |
is either a single signal or a list of signals. Signals may be specified |
| 2118 |
numerically or symbolically as per |
| 2119 |
.BR signal (3). |
| 2120 |
The "SIG" prefix may be omitted. |
| 2121 |
|
| 2122 |
With no arguments (or the argument \-number), |
| 2123 |
.B trap |
| 2124 |
returns the signal number of the trap command currently being executed. |
| 2125 |
|
| 2126 |
The |
| 2127 |
.B \-code |
| 2128 |
flag uses the return code of the command in place of whatever code Tcl |
| 2129 |
was about to return when the command originally started running. |
| 2130 |
|
| 2131 |
The |
| 2132 |
.B \-interp |
| 2133 |
flag causes the command to be evaluated using the interpreter |
| 2134 |
active at the time the command started running |
| 2135 |
rather than when the trap was declared. |
| 2136 |
|
| 2137 |
The |
| 2138 |
.B \-name |
| 2139 |
flag causes the |
| 2140 |
.B trap |
| 2141 |
command to return the signal name of the trap command currently being executed. |
| 2142 |
|
| 2143 |
The |
| 2144 |
.B \-max |
| 2145 |
flag causes the |
| 2146 |
.B trap |
| 2147 |
command to return the largest signal number that can be set. |
| 2148 |
|
| 2149 |
For example, the command "trap {send_user "Ouch!"} SIGINT" will print "Ouch!" |
| 2150 |
each time the user presses ^C. |
| 2151 |
|
| 2152 |
By default, SIGINT (which can usually be generated by pressing ^C) and |
| 2153 |
SIGTERM cause Expect to exit. This is due to the following trap, created |
| 2154 |
by default when Expect starts. |
| 2155 |
.nf |
| 2156 |
|
| 2157 |
trap exit {SIGINT SIGTERM} |
| 2158 |
|
| 2159 |
.fi |
| 2160 |
If you use the \-D flag to start the debugger, SIGINT is redefined |
| 2161 |
to start the interactive debugger. This is due to the following trap: |
| 2162 |
.nf |
| 2163 |
|
| 2164 |
trap {exp_debug 1} SIGINT |
| 2165 |
|
| 2166 |
.fi |
| 2167 |
The debugger trap can be changed by setting the environment variable |
| 2168 |
EXPECT_DEBUG_INIT to a new trap command. |
| 2169 |
|
| 2170 |
You can, of course, override both of these just by adding trap |
| 2171 |
commands to your script. In particular, if you have your own "trap |
| 2172 |
exit SIGINT", this will override the debugger trap. This is useful |
| 2173 |
if you want to prevent users from getting to the debugger at all. |
| 2174 |
|
| 2175 |
If you want to define your own trap on SIGINT but still trap to the |
| 2176 |
debugger when it is running, use: |
| 2177 |
.nf |
| 2178 |
|
| 2179 |
if {![exp_debug]} {trap mystuff SIGINT} |
| 2180 |
|
| 2181 |
.fi |
| 2182 |
Alternatively, you can trap to the debugger using some other signal. |
| 2183 |
|
| 2184 |
.B trap |
| 2185 |
will not let you override the action for SIGALRM as this is used internally |
| 2186 |
to |
| 2187 |
.BR Expect . |
| 2188 |
The disconnect command sets SIGALRM to SIG_IGN (ignore). You can reenable |
| 2189 |
this as long as you disable it during subsequent spawn commands. |
| 2190 |
|
| 2191 |
See signal(3) for more info. |
| 2192 |
.TP |
| 2193 |
.BI wait " [args]" |
| 2194 |
delays until a spawned process (or |
| 2195 |
the current process if none is named) terminates. |
| 2196 |
.IP |
| 2197 |
.B wait |
| 2198 |
normally returns a list of four integers. |
| 2199 |
The first integer is the pid of the process that was waited upon. |
| 2200 |
The second integer is the corresponding spawn id. |
| 2201 |
The third integer is \-1 if an operating system error occurred, or 0 otherwise. |
| 2202 |
If the third integer was 0, the fourth integer is the status returned by |
| 2203 |
the spawned process. If the third integer was \-1, the fourth integer is |
| 2204 |
the value of errno set by the operating system. The global variable |
| 2205 |
errorCode is also set. |
| 2206 |
|
| 2207 |
Additional elements may appear at the end of the return value from |
| 2208 |
.BR wait . |
| 2209 |
An optional fifth element identifies a class of information. |
| 2210 |
Currently, the only possible value for this element is CHILDKILLED in |
| 2211 |
which case the next two values are the C-style signal name and a short |
| 2212 |
textual description. |
| 2213 |
.IP |
| 2214 |
The |
| 2215 |
.B \-i |
| 2216 |
flag declares the process to wait corresponding to the named spawn_id |
| 2217 |
(NOT the process id). |
| 2218 |
Inside a SIGCHLD handler, |
| 2219 |
it is possible to wait for any spawned process by using the spawn id \-1. |
| 2220 |
|
| 2221 |
The |
| 2222 |
.B \-nowait |
| 2223 |
flag causes the wait to return immediately with the indication of a |
| 2224 |
successful wait. When the process exits (later), it will automatically |
| 2225 |
disappear without the need for an explicit wait. |
| 2226 |
|
| 2227 |
The |
| 2228 |
.B wait |
| 2229 |
command may also be used wait for a forked process using the arguments |
| 2230 |
"\-i \-1". Unlike its use with spawned processes, this command can be |
| 2231 |
executed at any time. There is no control over which process is |
| 2232 |
reaped. However, the return value can be checked for the process id. |
| 2233 |
|
| 2234 |
.SH LIBRARIES |
| 2235 |
Expect automatically knows about two built-in libraries for Expect scripts. |
| 2236 |
These are defined by the directories named in the variables |
| 2237 |
exp_library and exp_exec_library. Both are meant to contain utility |
| 2238 |
files that can be used by other scripts. |
| 2239 |
|
| 2240 |
exp_library contains architecture-independent files. exp_exec_library |
| 2241 |
contains architecture-dependent files. Depending on your system, both |
| 2242 |
directories may be totally empty. The existence of the file |
| 2243 |
$exp_exec_library/cat-buffers describes whether your /bin/cat buffers |
| 2244 |
by default. |
| 2245 |
.SH PRETTY-PRINTING |
| 2246 |
A vgrind definition is available for pretty-printing |
| 2247 |
.B Expect |
| 2248 |
scripts. |
| 2249 |
Assuming the vgrind definition supplied with the |
| 2250 |
.B Expect |
| 2251 |
distribution is |
| 2252 |
correctly installed, you can use it as: |
| 2253 |
.nf |
| 2254 |
|
| 2255 |
vgrind \-lexpect file |
| 2256 |
|
| 2257 |
.fi |
| 2258 |
.SH EXAMPLES |
| 2259 |
It many not be apparent how to put everything together that the man page |
| 2260 |
describes. I encourage you to read and try out the examples in |
| 2261 |
the example directory of the |
| 2262 |
.B Expect |
| 2263 |
distribution. |
| 2264 |
Some of them are real programs. Others are simply illustrative |
| 2265 |
of certain techniques, and of course, a couple are just quick hacks. |
| 2266 |
The INSTALL file has a quick overview of these programs. |
| 2267 |
.PP |
| 2268 |
The |
| 2269 |
.B Expect |
| 2270 |
papers (see SEE ALSO) are also useful. While some papers |
| 2271 |
use syntax corresponding to earlier versions of Expect, the accompanying |
| 2272 |
rationales are still valid and go into a lot more detail than this |
| 2273 |
man page. |
| 2274 |
.SH CAVEATS |
| 2275 |
Extensions may collide with Expect's command names. For example, |
| 2276 |
.B send |
| 2277 |
is defined by Tk for an entirely different purpose. |
| 2278 |
For this reason, most of the |
| 2279 |
.B Expect |
| 2280 |
commands are also available as "exp_XXXX". |
| 2281 |
Commands and variables beginning with "exp", "inter", "spawn", |
| 2282 |
and "timeout" do not have aliases. |
| 2283 |
Use the extended command names if you need this compatibility between environments. |
| 2284 |
|
| 2285 |
.B Expect |
| 2286 |
takes a rather liberal view of scoping. |
| 2287 |
In particular, variables read by commands specific to the |
| 2288 |
.B Expect |
| 2289 |
program will be sought first from the local scope, and if not found, in the |
| 2290 |
global scope. For example, this |
| 2291 |
obviates the need to place "global timeout" in every |
| 2292 |
procedure you write that uses |
| 2293 |
.BR expect . |
| 2294 |
On the other hand, variables written are always in the local scope (unless |
| 2295 |
a "global" command has been issued). The most common problem this causes |
| 2296 |
is when spawn is executed in a procedure. Outside the procedure, |
| 2297 |
.I spawn_id |
| 2298 |
no longer exists, so the spawned process is no longer accessible |
| 2299 |
simply because of scoping. Add a "global spawn_id" to such a procedure. |
| 2300 |
|
| 2301 |
If you cannot enable the multispawning capability |
| 2302 |
(i.e., your system supports neither select (BSD *.*), poll (SVR>2), |
| 2303 |
nor something equivalent), |
| 2304 |
.B Expect |
| 2305 |
will only be able to control a single process at a time. |
| 2306 |
In this case, do not attempt to set |
| 2307 |
.IR spawn_id , |
| 2308 |
nor should you execute processes via exec while a spawned process |
| 2309 |
is running. Furthermore, you will not be able to |
| 2310 |
.B expect |
| 2311 |
from multiple processes (including the user as one) at the same time. |
| 2312 |
|
| 2313 |
Terminal parameters can have a big effect on scripts. For example, if |
| 2314 |
a script is written to look for echoing, it will misbehave if echoing |
| 2315 |
is turned off. For this reason, Expect forces sane terminal |
| 2316 |
parameters by default. Unfortunately, this can make things unpleasant |
| 2317 |
for other programs. As an example, the emacs shell wants to change |
| 2318 |
the "usual" mappings: newlines get mapped to newlines instead of |
| 2319 |
carriage-return newlines, and echoing is disabled. This allows one to |
| 2320 |
use emacs to edit the input line. Unfortunately, Expect cannot |
| 2321 |
possibly guess this. |
| 2322 |
|
| 2323 |
You can request that Expect not override its default setting of |
| 2324 |
terminal parameters, but you must then be very careful when writing |
| 2325 |
scripts for such environments. In the case of emacs, avoid depending |
| 2326 |
upon things like echoing and end-of-line mappings. |
| 2327 |
|
| 2328 |
The commands that accepted arguments braced into a single list (the |
| 2329 |
.B expect |
| 2330 |
variants and |
| 2331 |
.BR interact ) |
| 2332 |
use a heuristic to decide if the list is actually one argument or |
| 2333 |
many. The heuristic can fail only in the case when the list actually |
| 2334 |
does represent a single argument which has multiple embedded \en's |
| 2335 |
with non-whitespace characters between them. This seems sufficiently |
| 2336 |
improbable, however the argument "\-nobrace" can be used to force a |
| 2337 |
single argument to be handled as a single argument. This could |
| 2338 |
conceivably be used with machine-generated Expect code. Similarly, |
| 2339 |
\-brace forces a single argument to be handle as multiple patterns/actions. |
| 2340 |
|
| 2341 |
.SH BUGS |
| 2342 |
It was really tempting to name the program "sex" (for either "Smart EXec" |
| 2343 |
or "Send-EXpect"), but good sense (or perhaps just Puritanism) prevailed. |
| 2344 |
|
| 2345 |
On some systems, when a shell is spawned, it complains about not being |
| 2346 |
able to access the tty but runs anyway. This means your system has a |
| 2347 |
mechanism for gaining the controlling tty that |
| 2348 |
.B Expect |
| 2349 |
doesn't know about. Please find out what it is, and send this information |
| 2350 |
back to me. |
| 2351 |
|
| 2352 |
Ultrix 4.1 (at least the latest versions around here) considers |
| 2353 |
timeouts of above 1000000 to be equivalent to 0. |
| 2354 |
|
| 2355 |
Digital UNIX 4.0A (and probably other versions) refuses to allocate |
| 2356 |
ptys if you define a SIGCHLD handler. See grantpt page for more info. |
| 2357 |
|
| 2358 |
IRIX 6.0 does not handle pty permissions correctly so that if Expect |
| 2359 |
attempts to allocate a pty previously used by someone else, it fails. |
| 2360 |
Upgrade to IRIX 6.1. |
| 2361 |
|
| 2362 |
Telnet (verified only under SunOS 4.1.2) hangs if TERM is not set. |
| 2363 |
This is a problem under cron, at and in cgi scripts, which do not |
| 2364 |
define TERM. Thus, you must set it explicitly \(en to what type is |
| 2365 |
usually irrelevant. It just has to be set to something! The |
| 2366 |
following probably suffices for most cases. |
| 2367 |
.nf |
| 2368 |
|
| 2369 |
set env(TERM) vt100 |
| 2370 |
|
| 2371 |
.fi |
| 2372 |
|
| 2373 |
Tip (verified only under BSDI BSD/OS 3.1 i386) hangs if SHELL and HOME |
| 2374 |
are not set. This is a problem under cron, at and in cgi scripts, |
| 2375 |
which do not define these environment variables. Thus, you must set |
| 2376 |
them explicitly \(en to what type is usually irrelevant. It just has to |
| 2377 |
be set to something! The following probably suffices for most cases. |
| 2378 |
.nf |
| 2379 |
|
| 2380 |
set env(SHELL) /bin/sh |
| 2381 |
set env(HOME) /usr/bin |
| 2382 |
|
| 2383 |
.fi |
| 2384 |
|
| 2385 |
|
| 2386 |
Some implementations of ptys are designed so that the kernel throws |
| 2387 |
away any unread output after 10 to 15 seconds (actual number is |
| 2388 |
implementation-dependent) after the process has closed the file |
| 2389 |
descriptor. Thus |
| 2390 |
.B Expect |
| 2391 |
programs such as |
| 2392 |
.nf |
| 2393 |
|
| 2394 |
spawn date |
| 2395 |
sleep 20 |
| 2396 |
expect |
| 2397 |
|
| 2398 |
.fi |
| 2399 |
will fail. To avoid this, invoke non-interactive programs with |
| 2400 |
.B exec |
| 2401 |
rather than |
| 2402 |
.BR spawn . |
| 2403 |
While such situations are conceivable, in practice I have never |
| 2404 |
encountered a situation in which the final output of a truly |
| 2405 |
interactive program would be lost due to this behavior. |
| 2406 |
|
| 2407 |
On the other hand, Cray UNICOS ptys throw away any unread output |
| 2408 |
immediately after the process has closed the file descriptor. I have |
| 2409 |
reported this to Cray and they are working on a fix. |
| 2410 |
|
| 2411 |
Sometimes a delay is required between a prompt and a response, such as |
| 2412 |
when a tty interface is changing UART settings or matching baud rates |
| 2413 |
by looking for start/stop bits. Usually, all this is require is to |
| 2414 |
sleep for a second or two. A more robust technique is to retry until |
| 2415 |
the hardware is ready to receive input. The following example uses |
| 2416 |
both strategies: |
| 2417 |
.nf |
| 2418 |
|
| 2419 |
send "speed 9600\er"; |
| 2420 |
sleep 1 |
| 2421 |
expect { |
| 2422 |
timeout {send "\er"; exp_continue} |
| 2423 |
$prompt |
| 2424 |
} |
| 2425 |
|
| 2426 |
.fi |
| 2427 |
|
| 2428 |
trap \-code will not work with any command that sits in Tcl's event |
| 2429 |
loop, such as sleep. The problem is that in the event loop, Tcl |
| 2430 |
discards the return codes from async event handlers. A workaround is |
| 2431 |
to set a flag in the trap code. Then check the flag immediately after |
| 2432 |
the command (i.e., sleep). |
| 2433 |
|
| 2434 |
The expect_background command ignores \-timeout arguments and has no |
| 2435 |
concept of timeouts in general. |
| 2436 |
|
| 2437 |
.SH "EXPECT HINTS" |
| 2438 |
There are a couple of things about |
| 2439 |
.B Expect |
| 2440 |
that may be non-intuitive. |
| 2441 |
This section attempts to address some of these things with a couple of |
| 2442 |
suggestions. |
| 2443 |
|
| 2444 |
A common expect problem is how to recognize shell prompts. Since |
| 2445 |
these are customized differently by differently people and different |
| 2446 |
shells, portably automating rlogin can be difficult without knowing |
| 2447 |
the prompt. A reasonable convention is to have users store a regular |
| 2448 |
expression describing their prompt (in particular, the end of it) in |
| 2449 |
the environment variable EXPECT_PROMPT. Code like the following |
| 2450 |
can be used. If EXPECT_PROMPT doesn't exist, the code still has a good chance of functioning correctly. |
| 2451 |
.nf |
| 2452 |
|
| 2453 |
set prompt "(%|#|\e\e$) $" ;# default prompt |
| 2454 |
catch {set prompt $env(EXPECT_PROMPT)} |
| 2455 |
|
| 2456 |
expect \-re $prompt |
| 2457 |
|
| 2458 |
.fi |
| 2459 |
I encourage you to write |
| 2460 |
.B expect |
| 2461 |
patterns that include the end of whatever |
| 2462 |
you expect to see. This avoids the possibility of answering a question |
| 2463 |
before seeing the entire thing. In addition, while you may well be |
| 2464 |
able to answer questions before seeing them entirely, if you answer |
| 2465 |
early, your answer may appear echoed back in the middle of the question. |
| 2466 |
In other words, the resulting dialogue will be correct but look scrambled. |
| 2467 |
|
| 2468 |
Most prompts include a space character at the end. |
| 2469 |
For example, the prompt from ftp is 'f', 't', 'p', '>' and <blank>. |
| 2470 |
To match this prompt, you must account for each of these characters. |
| 2471 |
It is a common mistake not to include the blank. |
| 2472 |
Put the blank in explicitly. |
| 2473 |
|
| 2474 |
If you use a pattern of the form X*, the * will match all the output |
| 2475 |
received from the end of X to the last thing received. |
| 2476 |
This sounds intuitive but can be somewhat confusing because the phrase |
| 2477 |
"last thing received" can vary depending upon the speed of the computer |
| 2478 |
and the processing of I/O both by the kernel and the device driver. |
| 2479 |
.PP |
| 2480 |
In particular, humans tend to see program output arriving in huge chunks |
| 2481 |
(atomically) when in reality most programs produce output one |
| 2482 |
line at a time. Assuming this is the case, the * in the pattern of the |
| 2483 |
previous paragraph may only match the end of the current line even though |
| 2484 |
there seems to be more, because at the time of the match that was all |
| 2485 |
the output that had been received. |
| 2486 |
.PP |
| 2487 |
.B expect |
| 2488 |
has no way of knowing that further output is coming unless your |
| 2489 |
pattern specifically accounts for it. |
| 2490 |
.PP |
| 2491 |
Even depending on line-oriented buffering is unwise. Not only do programs |
| 2492 |
rarely make promises about the type of buffering they do, but system |
| 2493 |
indigestion can break output lines up so that lines break at seemingly |
| 2494 |
random places. Thus, if you can express the last few characters |
| 2495 |
of a prompt when writing patterns, it is wise to do so. |
| 2496 |
|
| 2497 |
If you are waiting for a pattern in the last output of a program |
| 2498 |
and the program emits something else instead, you will not be able to |
| 2499 |
detect that with the |
| 2500 |
.B timeout |
| 2501 |
keyword. The reason is that |
| 2502 |
.B expect |
| 2503 |
will not timeout \- instead it will get an |
| 2504 |
.B eof |
| 2505 |
indication. |
| 2506 |
Use that instead. Even better, use both. That way if that line |
| 2507 |
is ever moved around, you won't have to edit the line itself. |
| 2508 |
|
| 2509 |
Newlines are usually converted to carriage return, linefeed sequences |
| 2510 |
when output by the terminal driver. Thus, if you want a pattern that |
| 2511 |
explicitly matches the two lines, from, say, printf("foo\enbar"), |
| 2512 |
you should use the pattern "foo\er\enbar". |
| 2513 |
.PP |
| 2514 |
A similar translation occurs when reading from the user, via |
| 2515 |
.BR expect_user . |
| 2516 |
In this case, when you press return, it will be |
| 2517 |
translated to a newline. If |
| 2518 |
.B Expect |
| 2519 |
then passes that to a program |
| 2520 |
which sets its terminal to raw mode (like telnet), there is going to |
| 2521 |
be a problem, as the program expects a true return. (Some programs |
| 2522 |
are actually forgiving in that they will automatically translate |
| 2523 |
newlines to returns, but most don't.) Unfortunately, there is no way to find |
| 2524 |
out that a program put its terminal into raw mode. |
| 2525 |
.PP |
| 2526 |
Rather than manually replacing newlines with returns, the solution is to |
| 2527 |
use the command "stty raw", which will stop the translation. |
| 2528 |
Note, however, that this means that you will no longer get the cooked |
| 2529 |
line-editing features. |
| 2530 |
.PP |
| 2531 |
.B interact |
| 2532 |
implicitly sets your terminal to raw mode so this problem will not arise then. |
| 2533 |
|
| 2534 |
It is often useful to store passwords (or other private information) |
| 2535 |
in |
| 2536 |
.B Expect |
| 2537 |
scripts. This is not recommended since anything that is |
| 2538 |
stored on a computer is susceptible to being accessed by anyone. |
| 2539 |
Thus, interactively prompting for passwords from a script is a smarter |
| 2540 |
idea than embedding them literally. Nonetheless, sometimes such embedding |
| 2541 |
is the only possibility. |
| 2542 |
.PP |
| 2543 |
Unfortunately, the UNIX file system has no direct way of creating |
| 2544 |
scripts which are executable but unreadable. Systems which support |
| 2545 |
setgid shell scripts may indirectly simulate this as follows: |
| 2546 |
.PP |
| 2547 |
Create the |
| 2548 |
.B Expect |
| 2549 |
script (that contains the secret data) as usual. |
| 2550 |
Make its permissions be 750 (\-rwxr\-x\-\-\-) and owned by a trusted group, |
| 2551 |
i.e., a group which is allowed to read it. If necessary, create a new |
| 2552 |
group for this purpose. Next, create a /bin/sh script with |
| 2553 |
permissions 2751 (\-rwxr\-s\-\-x) owned by the same group as before. |
| 2554 |
.PP |
| 2555 |
The result is a script which may be executed (and read) by anyone. |
| 2556 |
When invoked, it runs the |
| 2557 |
.B Expect |
| 2558 |
script. |
| 2559 |
.SH "SEE ALSO" |
| 2560 |
.BR Tcl (3), |
| 2561 |
.BR libexpect (3) |
| 2562 |
.br |
| 2563 |
.I |
| 2564 |
"Exploring Expect: A Tcl-Based Toolkit for Automating Interactive Programs" |
| 2565 |
\fRby Don Libes, pp.\& 602, ISBN 1-56592-090-2, O'Reilly and Associates, 1995. |
| 2566 |
.br |
| 2567 |
.I |
| 2568 |
"expect: Curing Those Uncontrollable Fits of Interactivity" \fRby Don Libes, |
| 2569 |
Proceedings of the Summer 1990 USENIX Conference, |
| 2570 |
Anaheim, California, June 11\(en15, 1990. |
| 2571 |
.br |
| 2572 |
.I |
| 2573 |
"Using |
| 2574 |
.B expect |
| 2575 |
to Automate System Administration Tasks" \fRby Don Libes, |
| 2576 |
Proceedings of the 1990 USENIX Large Installation Systems Administration |
| 2577 |
Conference, Colorado Springs, Colorado, October 17\(en19, 1990. |
| 2578 |
.br |
| 2579 |
.I |
| 2580 |
"Tcl: An Embeddable Command Language" \fRby John Ousterhout, |
| 2581 |
Proceedings of the Winter 1990 USENIX Conference, |
| 2582 |
Washington, D.C., January 22\(en26, 1990. |
| 2583 |
.br |
| 2584 |
.I |
| 2585 |
"expect: Scripts for Controlling Interactive Programs" \fRby Don Libes, |
| 2586 |
Computing Systems, Vol. 4, No.\& 2, University of California Press Journals, |
| 2587 |
November 1991. |
| 2588 |
.br |
| 2589 |
.I |
| 2590 |
"Regression Testing and Conformance Testing Interactive Programs", \fRby Don |
| 2591 |
Libes, Proceedings of the Summer 1992 USENIX Conference, pp. 135\(en144, |
| 2592 |
San Antonio, TX, June 12\(en15, 1992. |
| 2593 |
.br |
| 2594 |
.I |
| 2595 |
"Kibitz \- Connecting Multiple Interactive Programs Together", \fRby Don Libes, |
| 2596 |
Software \- Practice & Experience, John Wiley & Sons, West Sussex, England, |
| 2597 |
Vol. 23, No.\& 5, May, 1993. |
| 2598 |
.br |
| 2599 |
.I |
| 2600 |
"A Debugger for Tcl Applications", \fRby Don Libes, |
| 2601 |
Proceedings of the 1993 Tcl/Tk Workshop, Berkeley, CA, June 10\(en11, 1993. |
| 2602 |
.SH AUTHOR |
| 2603 |
Don Libes, National Institute of Standards and Technology |
| 2604 |
.SH ACKNOWLEDGMENTS |
| 2605 |
Thanks to John Ousterhout for Tcl, and Scott Paisley for inspiration. |
| 2606 |
Thanks to Rob Savoye for Expect's autoconfiguration code. |
| 2607 |
.PP |
| 2608 |
The HISTORY file documents much of the evolution of |
| 2609 |
.BR expect . |
| 2610 |
It makes interesting reading and might give you further insight to this |
| 2611 |
software. Thanks to the people mentioned in it who sent me bug fixes |
| 2612 |
and gave other assistance. |
| 2613 |
.PP |
| 2614 |
Design and implementation of |
| 2615 |
.B Expect |
| 2616 |
was paid for in part by the U.S.\& government and is therefore in the public |
| 2617 |
domain. |
| 2618 |
However the author and NIST would like credit |
| 2619 |
if this program and documentation or portions of them are used. |