Commit | Line | Data |
---|---|---|
920dae64 AT |
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. |