| 1 |
.TH LIBEXPECT 3 "12 December 1991" |
| 2 |
.SH NAME |
| 3 |
libexpect \- programmed dialogue library with interactive programs |
| 4 |
.SH DESCRIPTION |
| 5 |
This library contains functions that allow Expect to be used as |
| 6 |
a Tcl extension or to be used directly from C or C++ (without Tcl). |
| 7 |
Adding Expect as a Tcl extension is very short and simple, so that will be |
| 8 |
covered first. |
| 9 |
.SH SYNOPSIS |
| 10 |
.nf |
| 11 |
|
| 12 |
.B #include "expect_tcl.h" |
| 13 |
.B Expect_Init(interp); |
| 14 |
|
| 15 |
.B cc files... \-lexpect5.20 \-ltcl7.5 \-lm |
| 16 |
|
| 17 |
.fi |
| 18 |
Note: library versions may differ in the actual release. |
| 19 |
|
| 20 |
The Expect_Init function adds expect commands to the named |
| 21 |
interpreter. It avoids overwriting commands that already exist, |
| 22 |
however aliases beginning with "exp_" are always created for expect |
| 23 |
commands. So for example, "send" can be used as "exp_send". |
| 24 |
|
| 25 |
Generally, you should only call Expect commands via Tcl_Eval. |
| 26 |
Certain auxiliary functions may be called directly. They are summarized |
| 27 |
below. They may be useful in constructing your own main. Look |
| 28 |
at the file exp_main_exp.c in the Expect distribution as |
| 29 |
a prototype main. Another prototype is tclAppInit.c in the |
| 30 |
Tcl source distribution. A prototype for working with Tk is in |
| 31 |
exp_main_tk.c in the Expect distribution. |
| 32 |
.nf |
| 33 |
|
| 34 |
int exp_cmdlinecmds; |
| 35 |
int exp_interactive; |
| 36 |
FILE *exp_cmdfile; |
| 37 |
char *exp_cmdfilename; |
| 38 |
int exp_tcl_debugger_available; |
| 39 |
|
| 40 |
void exp_parse_argv(Tcl_Interp *,int argc,char **argv); |
| 41 |
int exp_interpreter(Tcl_Interp *); |
| 42 |
void exp_interpret_cmdfile(Tcl_Interp *,FILE *); |
| 43 |
void exp_interpret_cmdfilename(Tcl_Interp *,char *); |
| 44 |
void exp_interpret_rcfiles(Tcl_Interp *,int my_rc,int sys_rc); |
| 45 |
char * exp_cook(char *s,int *len); |
| 46 |
void (*exp_app_exit)EXP_PROTO((Tcl_Interp *); |
| 47 |
void exp_exit(Tcl_Interp *,int status); |
| 48 |
void exp_exit_handlers(Tcl_Interp *); |
| 49 |
void exp_error(Tcl_Interp,char *,...); |
| 50 |
|
| 51 |
.fi |
| 52 |
.B exp_cmdlinecmds |
| 53 |
is 1 if Expect has been invoked with commands on the program command-line (using "-c" for example). |
| 54 |
.B exp_interactive |
| 55 |
is 1 if Expect has been invoked with the -i flag or if no commands or script is being invoked. |
| 56 |
.B exp_cmdfile |
| 57 |
is a stream from which Expect will read commands. |
| 58 |
.B exp_cmdfilename |
| 59 |
is the name of a file which Expect will open and read commands from. |
| 60 |
.B exp_tcl_debugger_available |
| 61 |
is 1 if the debugger has been armed. |
| 62 |
|
| 63 |
.B exp_parse_argv |
| 64 |
reads the representation of the command line. |
| 65 |
Based on what is found, any of the other variables listed here |
| 66 |
are initialized appropriately. |
| 67 |
.B exp_interpreter |
| 68 |
interactively prompts the user for commands and evaluates them. |
| 69 |
.B exp_interpret_cmdfile |
| 70 |
reads the given stream and evaluates any commands found. |
| 71 |
.B exp_interpret_cmdfilename |
| 72 |
opens the named file and evaluates any commands found. |
| 73 |
.B exp_interpret_rcfiles |
| 74 |
reads and evalutes the .rc files. If my_rc is zero, |
| 75 |
then ~/.expectrc is skipped. If sys_rc is zero, then the system-wide |
| 76 |
expectrc file is skipped. |
| 77 |
.B exp_cook |
| 78 |
returns a static buffer containing the argument reproduced with |
| 79 |
newlines replaced by carriage-return linefeed sequences. |
| 80 |
The primary purpose of this is to allow messages to be produced |
| 81 |
without worrying about whether the terminal is in raw mode or |
| 82 |
cooked mode. |
| 83 |
If length is zero, it is computed via strlen. |
| 84 |
.B exp_error is a printf-like function that writes the result |
| 85 |
to interp->result. |
| 86 |
.SH SYNOPSIS |
| 87 |
.nf |
| 88 |
.B #include <expect.h> |
| 89 |
|
| 90 |
.B int |
| 91 |
.B "exp_spawnl(file, arg0 [, arg1, ..., argn] (char *)0);" |
| 92 |
.B char *file; |
| 93 |
.B char *arg0, *arg1, ... *argn; |
| 94 |
|
| 95 |
.B int |
| 96 |
.B exp_spawnv(file,argv); |
| 97 |
.B char *file, *argv[ ]; |
| 98 |
|
| 99 |
.B int |
| 100 |
.B exp_spawnfd(fd); |
| 101 |
.B int fd; |
| 102 |
|
| 103 |
.B FILE * |
| 104 |
.B exp_popen(command); |
| 105 |
.B char *command; |
| 106 |
|
| 107 |
.B extern int exp_pid; |
| 108 |
.B extern int exp_ttyinit; |
| 109 |
.B extern int exp_ttycopy; |
| 110 |
.B extern int exp_console; |
| 111 |
.B extern char *exp_stty_init; |
| 112 |
.B extern void (*exp_close_in_child)(); |
| 113 |
.B extern void (*exp_child_exec_prelude)(); |
| 114 |
.B extern void exp_close_tcl_files(); |
| 115 |
|
| 116 |
.B cc files... \-lexpect \-ltcl \-lm |
| 117 |
.fi |
| 118 |
|
| 119 |
.SH DESCRIPTION |
| 120 |
.B exp_spawnl |
| 121 |
and |
| 122 |
.B exp_spawnv |
| 123 |
fork a new process so that its stdin, |
| 124 |
stdout, and stderr can be written and read by the current process. |
| 125 |
.I file |
| 126 |
is the name of a file to be executed. The |
| 127 |
.I arg |
| 128 |
pointers are |
| 129 |
null-terminated strings. Following the style of execve(), |
| 130 |
.I arg0 |
| 131 |
(or |
| 132 |
.IR argv[0] ) |
| 133 |
is customarily a duplicate of the name of the file. |
| 134 |
.PP |
| 135 |
Four interfaces are available, |
| 136 |
.B exp_spawnl |
| 137 |
is useful when the number of |
| 138 |
arguments is known at compile time. |
| 139 |
.B exp_spawnv |
| 140 |
is useful when the number of arguments is not known at compile time. |
| 141 |
.B exp_spawnfd |
| 142 |
is useful when an open file descriptor is already available as a source. |
| 143 |
.B exp_popen |
| 144 |
is explained later on. |
| 145 |
.PP |
| 146 |
If the process is successfully created, a file descriptor is returned |
| 147 |
which corresponds to the process's stdin, stdout and stderr. |
| 148 |
A stream may be associated with the file descriptor by using fdopen(). |
| 149 |
(This should almost certainly be followed by setbuf() to unbuffer the I/O.) |
| 150 |
.PP |
| 151 |
Closing the file descriptor will typically be detected by the |
| 152 |
process as an EOF. Once such a process exits, it should be waited |
| 153 |
upon (via wait) in order to free up the kernel process slot. (Some systems |
| 154 |
allow you to avoid this if you ignore the SIGCHLD signal). |
| 155 |
.PP |
| 156 |
.B exp_popen |
| 157 |
is yet another interface, styled after popen(). It takes a Bourne |
| 158 |
shell command line, and returns a stream that corresponds to the process's |
| 159 |
stdin, stdout and stderr. The actual implementation of |
| 160 |
.B exp_popen |
| 161 |
below demonstrates |
| 162 |
.BR exp_spawnl . |
| 163 |
.nf |
| 164 |
|
| 165 |
FILE * |
| 166 |
exp_popen(program) |
| 167 |
char *program; |
| 168 |
{ |
| 169 |
FILE *fp; |
| 170 |
int ec; |
| 171 |
|
| 172 |
if (0 > (ec = exp_spawnl("sh","sh","-c",program,(char *)0))) |
| 173 |
return(0); |
| 174 |
if (NULL == (fp = fdopen(ec,"r+")) return(0); |
| 175 |
setbuf(fp,(char *)0); |
| 176 |
return(fp); |
| 177 |
} |
| 178 |
.fi |
| 179 |
|
| 180 |
After a process is started, the variable |
| 181 |
.B exp_pid |
| 182 |
is set to the process-id of the new process. The variable |
| 183 |
.B exp_pty_slave_name |
| 184 |
is set to the name of the slave side of the pty. |
| 185 |
|
| 186 |
The spawn functions uses a pty to communicate with the process. By |
| 187 |
default, the pty is initialized the same way as the user's tty (if |
| 188 |
possible, i.e., if the environment has a controlling terminal.) This |
| 189 |
initialization can be skipped by setting exp_ttycopy to 0. |
| 190 |
|
| 191 |
The pty is further initialized to some system wide defaults if |
| 192 |
exp_ttyinit is non-zero. The default is generally comparable to "stty sane". |
| 193 |
|
| 194 |
The tty setting can be further modified by setting the variable |
| 195 |
.BR exp_stty_init . |
| 196 |
This variable is interpreted in the style of stty arguments. For |
| 197 |
example, exp_stty_init = "sane"; repeats the default initialization. |
| 198 |
|
| 199 |
On some systems, it is possible to redirect console output to ptys. |
| 200 |
If this is supported, you can force the next spawn to obtain the |
| 201 |
console output by setting the variable |
| 202 |
.B exp_console |
| 203 |
to 1. |
| 204 |
|
| 205 |
Between the time a process is started and the new program is given |
| 206 |
control, the spawn functions can clean up the environment by closing |
| 207 |
file descriptors. By default, the only file descriptors closed are |
| 208 |
ones internal to Expect and any marked "close-on-exec". |
| 209 |
|
| 210 |
If needed, you can close additional file descriptors by creating |
| 211 |
an appropriate function and assigning it to exp_close_in_child. |
| 212 |
The function will be called after the fork and before the exec. |
| 213 |
(This also modifies the behavior of the spawn command in Expect.) |
| 214 |
|
| 215 |
If you are also using Tcl, it may be convenient to use the function |
| 216 |
exp_close_tcl_files which closes all files between the default |
| 217 |
standard file descriptors and the highest descriptor known to Tcl. |
| 218 |
(Expect does this.) |
| 219 |
|
| 220 |
The function exp_child_exec_prelude is the last function called prior |
| 221 |
to the actual exec in the child. You can redefine this for effects |
| 222 |
such as manipulating the uid or the signals. |
| 223 |
|
| 224 |
.SH "IF YOU WANT TO ALLOCATE YOUR OWN PTY" |
| 225 |
.nf |
| 226 |
|
| 227 |
.B extern int exp_autoallocpty; |
| 228 |
.B extern int exp_pty[2]; |
| 229 |
.fi |
| 230 |
|
| 231 |
The spawn functions use a pty to communicate with the process. By |
| 232 |
default, a pty is automatically allocated each time a process is spawned. |
| 233 |
If you want to allocate ptys yourself, before calling one of the spawn |
| 234 |
functions, set |
| 235 |
.B exp_autoallocpty |
| 236 |
to 0, |
| 237 |
.B exp_pty[0] |
| 238 |
to the master pty file descriptor and |
| 239 |
.B exp_pty[1] |
| 240 |
to the slave pty file descriptor. |
| 241 |
The expect library will not do any pty initializations (e.g., exp_stty_init will not be used). |
| 242 |
The slave pty file descriptor will be |
| 243 |
automatically closed when the process is spawned. After the process is |
| 244 |
started, all further communication takes place with the master pty file |
| 245 |
descriptor. |
| 246 |
.PP |
| 247 |
.B exp_spawnl |
| 248 |
and |
| 249 |
.B exp_spawnv |
| 250 |
duplicate the shell's actions |
| 251 |
in searching for an executable file in a list of directories. The |
| 252 |
directory list is obtained from the environment. |
| 253 |
.SH EXPECT PROCESSING |
| 254 |
While it is possible to use read() to read information from a process |
| 255 |
spawned by |
| 256 |
.B exp_spawnl |
| 257 |
or |
| 258 |
.BR exp_spawnv , |
| 259 |
more convenient functions are provided. They are as |
| 260 |
follows: |
| 261 |
.nf |
| 262 |
|
| 263 |
.B int |
| 264 |
.B exp_expectl(fd,type1,pattern1,[re1,],value1,type2,...,exp_end); |
| 265 |
.B int fd; |
| 266 |
.B enum exp_type type; |
| 267 |
.B char *pattern1, *pattern2, ...; |
| 268 |
.B regexp *re1, *re2, ...; |
| 269 |
.B int value1, value2, ...; |
| 270 |
.B |
| 271 |
|
| 272 |
.B int |
| 273 |
.B exp_fexpectl(fp,type1,pattern1,[re1,]value1,type2,...,exp_end); |
| 274 |
.B FILE *fp; |
| 275 |
.B enum exp_type type; |
| 276 |
.B char *pattern1, *pattern2, ...; |
| 277 |
.B regexp *re1, *re2, ...; |
| 278 |
.B int value1, value2, ...; |
| 279 |
|
| 280 |
.B enum exp_type { |
| 281 |
.B exp_end, |
| 282 |
.B exp_glob, |
| 283 |
.B exp_exact, |
| 284 |
.B exp_regexp, |
| 285 |
.B exp_compiled, |
| 286 |
.B exp_null, |
| 287 |
.B }; |
| 288 |
|
| 289 |
.B struct exp_case { |
| 290 |
.B char *pattern; |
| 291 |
.B regexp *re; |
| 292 |
.B enum exp_type type; |
| 293 |
.B int value; |
| 294 |
.B }; |
| 295 |
|
| 296 |
.B int |
| 297 |
.B exp_expectv(fd,cases); |
| 298 |
.B int fd; |
| 299 |
.B struct exp_case *cases; |
| 300 |
|
| 301 |
.B int |
| 302 |
.B exp_fexpectv(fp,cases); |
| 303 |
.B FILE *fp; |
| 304 |
.B struct exp_case *cases; |
| 305 |
|
| 306 |
.B extern int exp_timeout; |
| 307 |
.B extern char *exp_match; |
| 308 |
.B extern char *exp_match_end; |
| 309 |
.B extern char *exp_buffer; |
| 310 |
.B extern char *exp_buffer_end; |
| 311 |
.B extern int exp_match_max; |
| 312 |
.B extern int exp_full_buffer; |
| 313 |
.B extern int exp_remove_nulls; |
| 314 |
.fi |
| 315 |
|
| 316 |
The functions wait until the output from a process matches one of the |
| 317 |
patterns, a specified time period has passed, or an EOF is seen. |
| 318 |
.PP |
| 319 |
The first argument to each function is either a file descriptor or a stream. |
| 320 |
Successive sets of arguments describe patterns and associated integer values |
| 321 |
to return when the pattern matches. |
| 322 |
.PP |
| 323 |
The type argument is one of four values. exp_end indicates that no more |
| 324 |
patterns appear. |
| 325 |
exp_glob indicates that the pattern is a glob-style string pattern. |
| 326 |
exp_exact indicates that the pattern is an exact string. |
| 327 |
exp_regexp indicates that the pattern is a regexp-style string pattern. |
| 328 |
exp_compiled indicates that the pattern is a regexp-style string pattern, |
| 329 |
and that its compiled form is also provided. |
| 330 |
exp_null indicates that the pattern is a null (for debugging purposes, |
| 331 |
a string pattern must also follow). |
| 332 |
.PP |
| 333 |
If the compiled form is not provided with the functions |
| 334 |
.B exp_expectl |
| 335 |
and |
| 336 |
.BR exp_fexpectl , |
| 337 |
any pattern compilation done internally is |
| 338 |
thrown away after the function returns. The functions |
| 339 |
.B exp_expectv |
| 340 |
and |
| 341 |
.B exp_fexpectv |
| 342 |
will automatically compile patterns and will not throw them away. |
| 343 |
Instead, they must be discarded by the user, by calling free on each |
| 344 |
pattern. It is only necessary to discard them, the last time the |
| 345 |
cases are used. |
| 346 |
.PP |
| 347 |
Regexp subpatterns matched are stored in the compiled regexp. |
| 348 |
Assuming "re" contains a compiled regexp, the matched string can be |
| 349 |
found in re->startp[0]. The match substrings (according to the parentheses) |
| 350 |
in the original pattern can be found in re->startp[1], re->startp[2], and |
| 351 |
so on, up to re->startp[9]. The corresponding strings ends are re->endp[x] |
| 352 |
where x is that same index as for the string start. |
| 353 |
|
| 354 |
The type exp_null matches if a null appears in the input. The |
| 355 |
variable exp_remove_nulls must be set to 0 to prevent nulls from |
| 356 |
being automatically stripped. By default, exp_remove_nulls is set |
| 357 |
to 1 and nulls are automatically stripped. |
| 358 |
|
| 359 |
.B exp_expectv |
| 360 |
and |
| 361 |
.B exp_fexpectv |
| 362 |
are useful when the number of patterns is |
| 363 |
not known in advance. In this case, the sets are provided in an array. |
| 364 |
The end of the array is denoted by a struct exp_case with type exp_end. |
| 365 |
For the rest |
| 366 |
of this discussion, these functions will be referred to generically as |
| 367 |
.IR expect. |
| 368 |
.PP |
| 369 |
If a pattern matches, then the corresponding integer value is returned. |
| 370 |
Values need not be unique, however they should be positive to avoid |
| 371 |
being mistaken for EXP_EOF, EXP_TIMEOUT, or EXP_FULLBUFFER. |
| 372 |
Upon EOF or timeout, the value |
| 373 |
.B EXP_EOF |
| 374 |
or |
| 375 |
.B EXP_TIMEOUT |
| 376 |
is returned. The |
| 377 |
default timeout period is 10 seconds but may be changed by setting the |
| 378 |
variable |
| 379 |
.BR exp_timeout . |
| 380 |
A value of -1 |
| 381 |
disables a timeout from occurring. |
| 382 |
A value of 0 causes the expect function to return immediately (i.e., poll) |
| 383 |
after one read(). |
| 384 |
However it must be preceded by a function such as select, poll, or |
| 385 |
an event manager callback to guarantee that there is data to be read. |
| 386 |
|
| 387 |
If the variable exp_full_buffer is 1, then EXP_FULLBUFFER is returned |
| 388 |
if exp_buffer fills with no pattern having matched. |
| 389 |
|
| 390 |
When the expect function returns, |
| 391 |
.B exp_buffer |
| 392 |
points to the buffer |
| 393 |
of characters that was being considered for matching. |
| 394 |
.B exp_buffer_end |
| 395 |
points to one past the last character in exp_buffer. |
| 396 |
If a match occurred, |
| 397 |
.B exp_match |
| 398 |
points into |
| 399 |
.B exp_buffer |
| 400 |
where the match began. |
| 401 |
.B exp_match_end |
| 402 |
points to one character past where the match ended. |
| 403 |
.PP |
| 404 |
Each time new input arrives, it is compared to each pattern in the |
| 405 |
order they are listed. Thus, you may test for absence of a match by |
| 406 |
making the last pattern something guaranteed to appear, such as a |
| 407 |
prompt. In situations where there is no prompt, you must check for |
| 408 |
.B EXP_TIMEOUT |
| 409 |
(just like you would if you were interacting manually). More philosophy |
| 410 |
and strategies on specifying |
| 411 |
.B expect |
| 412 |
patterns can be found in the |
| 413 |
documentation on the |
| 414 |
.B expect |
| 415 |
program itself. See SEE ALSO below. |
| 416 |
.PP |
| 417 |
Patterns are the usual C-shell-style regular expressions. For |
| 418 |
example, the following fragment looks for a successful login, such |
| 419 |
as from a telnet dialogue. |
| 420 |
.nf |
| 421 |
|
| 422 |
switch (exp_expectl( |
| 423 |
exp_glob,"connected",CONN, |
| 424 |
exp_glob,"busy",BUSY, |
| 425 |
exp_glob,"failed",ABORT, |
| 426 |
exp_glob,"invalid password",ABORT, |
| 427 |
exp_end)) { |
| 428 |
case CONN: /* logged in successfully */ |
| 429 |
break; |
| 430 |
case BUSY: /* couldn't log in at the moment */ |
| 431 |
break; |
| 432 |
case EXP_TIMEOUT: |
| 433 |
case ABORT: /* can't log in at any moment! */ |
| 434 |
break; |
| 435 |
default: /* problem with expect */ |
| 436 |
} |
| 437 |
.fi |
| 438 |
|
| 439 |
Asterisks (as in the |
| 440 |
example above) are a useful shorthand for omitting line-termination |
| 441 |
characters and other detail. |
| 442 |
Patterns must match the entire output of the current process (since |
| 443 |
the previous read on the descriptor or stream). |
| 444 |
More than 2000 bytes of output can |
| 445 |
force earlier bytes to be "forgotten". This may be changed by setting |
| 446 |
the variable |
| 447 |
.BR exp_match_max . |
| 448 |
Note that excessively large values can slow down the pattern matcher. |
| 449 |
.SH RUNNING IN THE BACKGROUND |
| 450 |
.nf |
| 451 |
|
| 452 |
.B extern int exp_disconnected; |
| 453 |
.B int exp_disconnect(); |
| 454 |
|
| 455 |
.fi |
| 456 |
It is possible to move a process into the background after it has |
| 457 |
begun running. A typical use for this is to read passwords and then |
| 458 |
go into the background to sleep before using the passwords to do real |
| 459 |
work. |
| 460 |
.PP |
| 461 |
To move a process into the background, fork, call exp_disconnect() in the |
| 462 |
child process and exit() in the parent process. This disassociates |
| 463 |
your process from the controlling terminal. If you wish to move a |
| 464 |
process into the background in a different way, you must set the |
| 465 |
variable exp_disconnected to 1. This allows processes spawned after |
| 466 |
this point to be started correctly. |
| 467 |
.SH MULTIPLEXING |
| 468 |
By default, the expect functions block inside of a read on a single file |
| 469 |
descriptor. If you want to wait on patterns from multiple file |
| 470 |
descriptors, |
| 471 |
use select, poll, or an event manager. |
| 472 |
They will tell you what file descriptor is ready to read. |
| 473 |
|
| 474 |
When a file descriptor is ready to read, you can use the expect |
| 475 |
functions to do one and only read by setting timeout to 0. |
| 476 |
.SH SLAVE CONTROL |
| 477 |
|
| 478 |
.nf |
| 479 |
|
| 480 |
.B void |
| 481 |
.B exp_slave_control(fd,enable) |
| 482 |
.B int fd; |
| 483 |
.B int enable; |
| 484 |
|
| 485 |
.fi |
| 486 |
|
| 487 |
Pty trapping is normally done automatically by the expect functions. |
| 488 |
However, if you want to issue an ioctl, for example, directly on the |
| 489 |
slave device, you should temporary disable trapping. |
| 490 |
|
| 491 |
Pty trapping can be controlled with exp_slave_control. The first |
| 492 |
argument is the file descriptor corresponding to the spawned process. |
| 493 |
The second argument is a 0 if trapping is to be disabled and 1 if it |
| 494 |
is to be enabled. |
| 495 |
|
| 496 |
.SH ERRORS |
| 497 |
All functions indicate errors by returning \-1 and setting errno. |
| 498 |
.PP |
| 499 |
Errors that occur after the spawn functions fork (e.g., attempting to |
| 500 |
spawn a non-existent program) are written to the process's stderr, |
| 501 |
and will be read by the first |
| 502 |
.BR expect . |
| 503 |
.SH SIGNALS |
| 504 |
.nf |
| 505 |
.B extern int exp_reading; |
| 506 |
.B extern jmp_buf exp_readenv; |
| 507 |
.fi |
| 508 |
|
| 509 |
.B expect |
| 510 |
uses alarm() to timeout, thus if you generate alarms during |
| 511 |
.BR expect , |
| 512 |
it will timeout prematurely. |
| 513 |
.PP |
| 514 |
Internally, |
| 515 |
.B expect |
| 516 |
calls read() which can be interrupted by signals. If |
| 517 |
you define signal handlers, you can choose to restart or abort |
| 518 |
.BR expect 's |
| 519 |
internal read. The variable, |
| 520 |
.BR exp_reading , |
| 521 |
is true if (and only if) |
| 522 |
.BR expect 's |
| 523 |
read has been interrupted. longjmp(exp_readenv,EXP_ABORT) will abort |
| 524 |
the read. longjmp(exp_readenv,EXP_RESTART) will restart the read. |
| 525 |
.SH LOGGING |
| 526 |
.nf |
| 527 |
|
| 528 |
.B extern int exp_loguser; |
| 529 |
.B extern int exp_logfile_all |
| 530 |
.B extern FILE *exp_logfile; |
| 531 |
.fi |
| 532 |
|
| 533 |
If |
| 534 |
.B exp_loguser |
| 535 |
is nonzero, |
| 536 |
.B expect |
| 537 |
sends any output from the spawned process to |
| 538 |
stdout. Since interactive programs typically echo their input, this |
| 539 |
usually suffices to show both sides of the conversation. If |
| 540 |
.B exp_logfile |
| 541 |
is also nonzero, this same output is written to the stream defined by |
| 542 |
.BR exp_logfile . |
| 543 |
If |
| 544 |
.B exp_logfile_all |
| 545 |
is non-zero, |
| 546 |
.B exp_logfile |
| 547 |
is written regardless of the value of |
| 548 |
.BR exp_loguser . |
| 549 |
|
| 550 |
.SH DEBUGGING |
| 551 |
While I consider the library to be easy to use, I think that the |
| 552 |
standalone expect program is much, much, easier to use than working |
| 553 |
with the C compiler and its usual edit, compile, debug cycle. Unlike |
| 554 |
typical C programs, most of the debugging isn't getting the C compiler |
| 555 |
to accept your programs - rather, it is getting the dialogue correct. |
| 556 |
Also, translating scripts from expect to C is usually not necessary. |
| 557 |
For example, the speed of interactive dialogues is virtually never an |
| 558 |
issue. So please try the standalone 'expect' program first. I |
| 559 |
suspect it is a more appropriate solution for most people than the |
| 560 |
library. |
| 561 |
.PP |
| 562 |
Nonetheless, if you feel compelled to debug in C, |
| 563 |
here are some tools to help you. |
| 564 |
.nf |
| 565 |
|
| 566 |
.B extern int exp_is_debugging; |
| 567 |
.B extern FILE *exp_debugfile; |
| 568 |
.fi |
| 569 |
|
| 570 |
While expect dialogues seem very intuitive, trying to codify them in a |
| 571 |
program can reveal many surprises in a program's interface. Therefore |
| 572 |
a variety of debugging aids are available. They are controlled by the |
| 573 |
above variables, all 0 by default. |
| 574 |
|
| 575 |
Debugging information internal to |
| 576 |
.B expect |
| 577 |
is sent to stderr when |
| 578 |
.B exp_is_debugging |
| 579 |
is non-zero. The debugging information includes |
| 580 |
every character received, and every attempt made to match the current |
| 581 |
input against the patterns. In addition, non-printable characters are |
| 582 |
translated to a printable form. For example, a control-C appears as a |
| 583 |
caret followed by a C. If |
| 584 |
.B exp_logfile |
| 585 |
is non-zero, this information |
| 586 |
is also written to that stream. |
| 587 |
.PP |
| 588 |
If |
| 589 |
.B exp_debugfile |
| 590 |
is non-zero, all normal and debugging information is |
| 591 |
written to that stream, regardless of the value of |
| 592 |
.BR exp_is_debugging . |
| 593 |
.SH CAVEATS |
| 594 |
The stream versions of the |
| 595 |
.B expect |
| 596 |
functions are much slower than the |
| 597 |
file descriptor versions because there is no way to portably read |
| 598 |
an unknown number of bytes without the potential of timing out. |
| 599 |
Thus, characters are read one at a time. You are therefore strongly |
| 600 |
encouraged to use the file descriptor versions of |
| 601 |
.B expect |
| 602 |
(although, |
| 603 |
automated versions of interactive programs don't usually demand high speed |
| 604 |
anyway). |
| 605 |
.PP |
| 606 |
You can actually get the best of both worlds, writing with the usual |
| 607 |
stream functions and reading with the file descriptor versions of |
| 608 |
.B expect |
| 609 |
as long as you don't attempt to intermix other stream input |
| 610 |
functions (e.g., fgetc). |
| 611 |
To do this, pass fileno(stream) as the file descriptor each time. |
| 612 |
Fortunately, there is little reason to use anything but the |
| 613 |
.B expect |
| 614 |
functions when reading from interactive programs. |
| 615 |
.PP |
| 616 |
There is no matching exp_pclose to exp_popen (unlike popen and pclose). |
| 617 |
It only takes two functions to close down a connection (fclose() followed |
| 618 |
by waiting on the pid), but it is not uncommon to separate these two |
| 619 |
actions by large time intervals, so the function seems of little value. |
| 620 |
.PP |
| 621 |
If you are running on a Cray running Unicos (all I know for sure from |
| 622 |
experience), you must run your compiled program as root or setuid. The |
| 623 |
problem is that the Cray only allows root processes to open ptys. |
| 624 |
You should observe as much precautions as possible: If you don't need |
| 625 |
permissions, setuid(0) only immediately before calling one of the spawn |
| 626 |
functions and immediately set it back afterwards. |
| 627 |
.PP |
| 628 |
Normally, |
| 629 |
.B spawn |
| 630 |
takes little time to execute. If you notice spawn taking a |
| 631 |
significant amount of time, it is probably encountering ptys that are |
| 632 |
wedged. A number of tests are run on ptys to avoid entanglements with |
| 633 |
errant processes. (These take 10 seconds per wedged pty.) Running |
| 634 |
expect with the \-d option will show if |
| 635 |
.B expect |
| 636 |
is encountering many ptys in odd states. If you cannot kill |
| 637 |
the processes to which these ptys are attached, your only recourse may |
| 638 |
be to reboot. |
| 639 |
.SH BUGS |
| 640 |
The |
| 641 |
.B exp_fexpect |
| 642 |
functions don't work at all under HP-UX - it appears to be a bug in getc. |
| 643 |
Follow the |
| 644 |
advice (above) about using the |
| 645 |
.B exp_expect |
| 646 |
functions (which doesn't need to call getc). If you fix the problem (before |
| 647 |
I do - please check the latest release) let me know. |
| 648 |
.SH SEE ALSO |
| 649 |
An alternative to this library is the |
| 650 |
.B expect |
| 651 |
program. |
| 652 |
.B expect |
| 653 |
interprets scripts written in a high-level language |
| 654 |
which direct the dialogue. |
| 655 |
In addition, the user can take control and interact directly when desired. |
| 656 |
If it is not absolutely necessary to write your own C program, it is much |
| 657 |
easier to use |
| 658 |
.B expect |
| 659 |
to perform the entire interaction. |
| 660 |
It is described further in the following references: |
| 661 |
.PP |
| 662 |
.I |
| 663 |
"expect: Curing Those Uncontrollable Fits of Interactivity" \fRby Don Libes, |
| 664 |
Proceedings of the Summer 1990 USENIX Conference, |
| 665 |
Anaheim, California, June 11-15, 1990. |
| 666 |
.PP |
| 667 |
.I |
| 668 |
"Using expect to Automate System Administration Tasks" \fRby Don Libes, |
| 669 |
Proceedings of the 1990 USENIX Large Installation Systems Administration |
| 670 |
Conference, Colorado Springs, Colorado, October 17-19, 1990. |
| 671 |
.PP |
| 672 |
expect(1), alarm(3), read(2), write(2), fdopen(3), execve(2), execvp(3), |
| 673 |
longjmp(3), pty(4). |
| 674 |
.PP |
| 675 |
There are several examples C programs in the test directory of |
| 676 |
.BR expect 's |
| 677 |
source distribution which use the expect library. |
| 678 |
.PP |
| 679 |
.SH AUTHOR |
| 680 |
Don Libes, [email protected], National Institute of Standards and Technology |
| 681 |
.SH ACKNOWLEDGEMENTS |
| 682 |
Thanks to John Ousterhout (UCBerkeley) for supplying the pattern |
| 683 |
matcher. |
| 684 |
.PP |
| 685 |
Design and implementation of the |
| 686 |
.B expect |
| 687 |
library was paid for by the U.S. government and is therefore in the public |
| 688 |
domain. |
| 689 |
However the author and NIST would like credit |
| 690 |
if this program and documentation or portions of them are used. |