| 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, libes@nist.gov, 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. |