1LIBEXPECT(3) Library Functions Manual LIBEXPECT(3)
2
6 libexpect - programmed dialogue library with interactive programs
7
9 This library contains functions that allow Expect to be used as a Tcl
10 extension or to be used directly from C or C++ (without Tcl). Adding
11 Expect as a Tcl extension is very short and simple, so that will be
12 covered first.
13
15 #include expect_tcl.h
16 Expect_Init(interp);
17 cc files... -lexpect5.20 -ltcl7.5 -lm
19 Note: library versions may differ in the actual release.
21 The Expect_Init function adds expect commands to the named interpreter.
23 It avoids overwriting commands that already exist, however aliases
24 beginning with "exp_" are always created for expect commands. So for
25 example, "send" can be used as "exp_send".
26 Generally, you should only call Expect commands via Tcl_Eval. Certain
28 auxiliary functions may be called directly. They are summarized below.
29 They may be useful in constructing your own main. Look at the file
30 exp_main_exp.c in the Expect distribution as a prototype main. Another
31 prototype is tclAppInit.c in the Tcl source distribution. A prototype
32 for working with Tk is in exp_main_tk.c in the Expect distribution.
33 int exp_cmdlinecmds;
35 int exp_interactive;
36 FILE *exp_cmdfile;
37 char *exp_cmdfilename;
38 int exp_tcl_debugger_available;
39 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 exp_cmdlinecmds is 1 if Expect has been invoked with commands on the
52 program command-line (using "-c" for example). exp_interactive is 1 if
53 Expect has been invoked with the -i flag or if no commands or script is
54 being invoked. exp_cmdfile is a stream from which Expect will read
55 commands. exp_cmdfilename is the name of a file which Expect will open
56 and read commands from. exp_tcl_debugger_available is 1 if the debug‐
57 ger has been armed.
58 exp_parse_argv reads the representation of the command line. Based on
60 what is found, any of the other variables listed here are initialized
61 appropriately. exp_interpreter interactively prompts the user for com‐
62 mands and evaluates them. exp_interpret_cmdfile reads the given stream
63 and evaluates any commands found. exp_interpret_cmdfilename opens the
64 named file and evaluates any commands found. exp_interpret_rcfiles
65 reads and evalutes the .rc files. If my_rc is zero, then ~/.expectrc
66 is skipped. If sys_rc is zero, then the system-wide expectrc file is
67 skipped. exp_cook returns a static buffer containing the argument
68 reproduced with newlines replaced by carriage-return linefeed
69 sequences. The primary purpose of this is to allow messages to be pro‐
70 duced without worrying about whether the terminal is in raw mode or
71 cooked mode. If length is zero, it is computed via strlen. exp_error
72 is a printf-like function that writes the result to interp->result.
73
75 #include <expect.h>
76 int
78 exp_spawnl(file, arg0 [, arg1, ..., argn] (char *)0);
79 char *file;
80 char *arg0, *arg1, ... *argn;
81 int
83 exp_spawnv(file,argv);
84 char *file, *argv[ ];
85 int
87 exp_spawnfd(fd);
88 int fd;
89 FILE *
91 exp_popen(command);
92 char *command;
93 extern int exp_pid;
95 extern int exp_ttyinit;
96 extern int exp_ttycopy;
97 extern int exp_console;
98 extern char *exp_stty_init;
99 extern void (*exp_close_in_child)();
100 extern void (*exp_child_exec_prelude)();
101 extern void exp_close_tcl_files();
102 cc files... -lexpect -ltcl -lm
104
107 exp_spawnl and exp_spawnv fork a new process so that its stdin, stdout,
108 and stderr can be written and read by the current process. file is the
109 name of a file to be executed. The arg pointers are null-terminated
110 strings. Following the style of execve(), arg0 (or argv[0]) is custom‐
111 arily a duplicate of the name of the file.
112 Four interfaces are available, exp_spawnl is useful when the number of
114 arguments is known at compile time. exp_spawnv is useful when the num‐
115 ber of arguments is not known at compile time. exp_spawnfd is useful
116 when an open file descriptor is already available as a source.
117 exp_popen is explained later on.
118 If the process is successfully created, a file descriptor is returned
120 which corresponds to the process's stdin, stdout and stderr. A stream
121 may be associated with the file descriptor by using fdopen(). (This
122 should almost certainly be followed by setbuf() to unbuffer the I/O.)
123 Closing the file descriptor will typically be detected by the process
125 as an EOF. Once such a process exits, it should be waited upon (via
126 wait) in order to free up the kernel process slot. (Some systems allow
127 you to avoid this if you ignore the SIGCHLD signal).
128 exp_popen is yet another interface, styled after popen(). It takes a
130 Bourne shell command line, and returns a stream that corresponds to the
131 process's stdin, stdout and stderr. The actual implementation of
132 exp_popen below demonstrates exp_spawnl.
133 FILE *
135 exp_popen(program)
136 char *program;
137 {
138 FILE *fp;
139 int ec;
140 if (0 > (ec = exp_spawnl("sh","sh","-c",program,(char *)0)))
142 return(0);
143 if (NULL == (fp = fdopen(ec,"r+")) return(0);
144 setbuf(fp,(char *)0);
145 return(fp);
146 }
147 After a process is started, the variable exp_pid is set to the process-
149 id of the new process. The variable exp_pty_slave_name is set to the
150 name of the slave side of the pty.
151 The spawn functions uses a pty to communicate with the process. By
153 default, the pty is initialized the same way as the user's tty (if pos‐
154 sible, i.e., if the environment has a controlling terminal.) This ini‐
155 tialization can be skipped by setting exp_ttycopy to 0.
156 The pty is further initialized to some system wide defaults if
158 exp_ttyinit is non-zero. The default is generally comparable to "stty
159 sane".
160 The tty setting can be further modified by setting the variable
162 exp_stty_init. This variable is interpreted in the style of stty argu‐
163 ments. For example, exp_stty_init = "sane"; repeats the default ini‐
164 tialization.
165 On some systems, it is possible to redirect console output to ptys. If
167 this is supported, you can force the next spawn to obtain the console
168 output by setting the variable exp_console to 1.
169 Between the time a process is started and the new program is given con‐
171 trol, the spawn functions can clean up the environment by closing file
172 descriptors. By default, the only file descriptors closed are ones
173 internal to Expect and any marked "close-on-exec".
174 If needed, you can close additional file descriptors by creating an
176 appropriate function and assigning it to exp_close_in_child. The func‐
177 tion will be called after the fork and before the exec. (This also
178 modifies the behavior of the spawn command in Expect.)
179 If you are also using Tcl, it may be convenient to use the function
181 exp_close_tcl_files which closes all files between the default standard
182 file descriptors and the highest descriptor known to Tcl. (Expect does
183 this.)
184 The function exp_child_exec_prelude is the last function called prior
186 to the actual exec in the child. You can redefine this for effects
187 such as manipulating the uid or the signals.
188
191 extern int exp_autoallocpty;
192 extern int exp_pty[2];
193 The spawn functions use a pty to communicate with the process. By
195 default, a pty is automatically allocated each time a process is
196 spawned. If you want to allocate ptys yourself, before calling one of
197 the spawn functions, set exp_autoallocpty to 0, exp_pty[0] to the mas‐
198 ter pty file descriptor and exp_pty[1] to the slave pty file descrip‐
199 tor. The expect library will not do any pty initializations (e.g.,
200 exp_stty_init will not be used). The slave pty file descriptor will be
201 automatically closed when the process is spawned. After the process is
202 started, all further communication takes place with the master pty file
203 descriptor.
204 exp_spawnl and exp_spawnv duplicate the shell's actions in searching
206 for an executable file in a list of directories. The directory list is
207 obtained from the environment.
208
210 While it is possible to use read() to read information from a process
211 spawned by exp_spawnl or exp_spawnv, more convenient functions are pro‐
212 vided. They are as follows:
213 int
215 exp_expectl(fd,type1,pattern1,[re1,],value1,type2,...,exp_end);
216 int fd;
217 enum exp_type type;
218 char *pattern1, *pattern2, ...;
219 regexp *re1, *re2, ...;
220 int value1, value2, ...;
221 int
223 exp_fexpectl(fp,type1,pattern1,[re1,]value1,type2,...,exp_end);
224 FILE *fp;
225 enum exp_type type;
226 char *pattern1, *pattern2, ...;
227 regexp *re1, *re2, ...;
228 int value1, value2, ...;
229 enum exp_type {
231 exp_end,
232 exp_glob,
233 exp_exact,
234 exp_regexp,
235 exp_compiled,
236 exp_null,
237 };
238 struct exp_case {
240 char *pattern;
241 regexp *re;
242 enum exp_type type;
243 int value;
244 };
245 int
247 exp_expectv(fd,cases);
248 int fd;
249 struct exp_case *cases;
250 int
252 exp_fexpectv(fp,cases);
253 FILE *fp;
254 struct exp_case *cases;
255 extern int exp_timeout;
257 extern char *exp_match;
258 extern char *exp_match_end;
259 extern char *exp_buffer;
260 extern char *exp_buffer_end;
261 extern int exp_match_max;
262 extern int exp_full_buffer;
263 extern int exp_remove_nulls;
264 The functions wait until the output from a process matches one of the
266 patterns, a specified time period has passed, or an EOF is seen.
267 The first argument to each function is either a file descriptor or a
269 stream. Successive sets of arguments describe patterns and associated
270 integer values to return when the pattern matches.
271 The type argument is one of four values. exp_end indicates that no
273 more patterns appear. exp_glob indicates that the pattern is a glob-
274 style string pattern. exp_exact indicates that the pattern is an exact
275 string. exp_regexp indicates that the pattern is a regexp-style string
276 pattern. exp_compiled indicates that the pattern is a regexp-style
277 string pattern, and that its compiled form is also provided. exp_null
278 indicates that the pattern is a null (for debugging purposes, a string
279 pattern must also follow).
280 If the compiled form is not provided with the functions exp_expectl and
282 exp_fexpectl, any pattern compilation done internally is thrown away
283 after the function returns. The functions exp_expectv and exp_fexpectv
284 will automatically compile patterns and will not throw them away.
285 Instead, they must be discarded by the user, by calling free on each
286 pattern. It is only necessary to discard them, the last time the cases
287 are used.
288 Regexp subpatterns matched are stored in the compiled regexp. Assuming
290 "re" contains a compiled regexp, the matched string can be found in
291 re->startp[0]. The match substrings (according to the parentheses) in
292 the original pattern can be found in re->startp[1], re->startp[2], and
293 so on, up to re->startp[9]. The corresponding strings ends are
294 re->endp[x] where x is that same index as for the string start.
295 The type exp_null matches if a null appears in the input. The variable
297 exp_remove_nulls must be set to 0 to prevent nulls from being automati‐
298 cally stripped. By default, exp_remove_nulls is set to 1 and nulls are
299 automatically stripped.
300 exp_expectv and exp_fexpectv are useful when the number of patterns is
302 not known in advance. In this case, the sets are provided in an array.
303 The end of the array is denoted by a struct exp_case with type exp_end.
304 For the rest of this discussion, these functions will be referred to
305 generically as expect.
306 If a pattern matches, then the corresponding integer value is returned.
308 Values need not be unique, however they should be positive to avoid
309 being mistaken for EXP_EOF, EXP_TIMEOUT, or EXP_FULLBUFFER. Upon EOF
310 or timeout, the value EXP_EOF or EXP_TIMEOUT is returned. The default
311 timeout period is 10 seconds but may be changed by setting the variable
312 exp_timeout. A value of -1 disables a timeout from occurring. A value
313 of 0 causes the expect function to return immediately (i.e., poll)
314 after one read(). However it must be preceded by a function such as
315 select, poll, or an event manager callback to guarantee that there is
316 data to be read.
317 If the variable exp_full_buffer is 1, then EXP_FULLBUFFER is returned
319 if exp_buffer fills with no pattern having matched.
320 When the expect function returns, exp_buffer points to the buffer of
322 characters that was being considered for matching. exp_buffer_end
323 points to one past the last character in exp_buffer. If a match
324 occurred, exp_match points into exp_buffer where the match began.
325 exp_match_end points to one character past where the match ended.
326 Each time new input arrives, it is compared to each pattern in the
328 order they are listed. Thus, you may test for absence of a match by
329 making the last pattern something guaranteed to appear, such as a
330 prompt. In situations where there is no prompt, you must check for
331 EXP_TIMEOUT (just like you would if you were interacting manually).
332 More philosophy and strategies on specifying expect patterns can be
333 found in the documentation on the expect program itself. See SEE ALSO
334 below.
335 Patterns are the usual C-shell-style regular expressions. For example,
337 the following fragment looks for a successful login, such as from a
338 telnet dialogue.
339 switch (exp_expectl(
341 exp_glob,"connected",CONN,
342 exp_glob,"busy",BUSY,
343 exp_glob,"failed",ABORT,
344 exp_glob,"invalid password",ABORT,
345 exp_end)) {
346 case CONN: /* logged in successfully */
347 break;
348 case BUSY: /* couldn't log in at the moment */
349 break;
350 case EXP_TIMEOUT:
351 case ABORT: /* can't log in at any moment! */
352 break;
353 default: /* problem with expect */
354 }
355 Asterisks (as in the example above) are a useful shorthand for omitting
357 line-termination characters and other detail. Patterns must match the
358 entire output of the current process (since the previous read on the
359 descriptor or stream). More than 2000 bytes of output can force ear‐
360 lier bytes to be "forgotten". This may be changed by setting the vari‐
361 able exp_match_max. Note that excessively large values can slow down
362 the pattern matcher.
363
365 extern int exp_disconnected;
366 int exp_disconnect();
367 It is possible to move a process into the background after it has begun
369 running. A typical use for this is to read passwords and then go into
370 the background to sleep before using the passwords to do real work.
371 To move a process into the background, fork, call exp_disconnect() in
373 the child process and exit() in the parent process. This disassociates
374 your process from the controlling terminal. If you wish to move a
375 process into the background in a different way, you must set the vari‐
376 able exp_disconnected to 1. This allows processes spawned after this
377 point to be started correctly.
378
380 By default, the expect functions block inside of a read on a single
381 file descriptor. If you want to wait on patterns from multiple file
382 descriptors, use select, poll, or an event manager. They will tell you
383 what file descriptor is ready to read.
384 When a file descriptor is ready to read, you can use the expect func‐
386 tions to do one and only read by setting timeout to 0.
387
389 void
390 exp_slave_control(fd,enable)
391 int fd;
392 int enable;
393 Pty trapping is normally done automatically by the expect functions.
396 However, if you want to issue an ioctl, for example, directly on the
397 slave device, you should temporary disable trapping.
398 Pty trapping can be controlled with exp_slave_control. The first argu‐
400 ment is the file descriptor corresponding to the spawned process. The
401 second argument is a 0 if trapping is to be disabled and 1 if it is to
402 be enabled.
403
406 All functions indicate errors by returning -1 and setting errno.
407 Errors that occur after the spawn functions fork (e.g., attempting to
409 spawn a non-existent program) are written to the process's stderr, and
410 will be read by the first expect.
411
413 extern int exp_reading;
414 extern jmp_buf exp_readenv;
415 expect uses alarm() to timeout, thus if you generate alarms during
417 expect, it will timeout prematurely.
418 Internally, expect calls read() which can be interrupted by signals.
420 If you define signal handlers, you can choose to restart or abort
421 expect's internal read. The variable, exp_reading, is true if (and
422 only if) expect's read has been interrupted. longjmp(exp_read‐
423 env,EXP_ABORT) will abort the read. longjmp(exp_readenv,EXP_RESTART)
424 will restart the read.
425
427 extern int exp_loguser;
428 extern int exp_logfile_all
429 extern FILE *exp_logfile;
430 If exp_loguser is nonzero, expect sends any output from the spawned
432 process to stdout. Since interactive programs typically echo their
433 input, this usually suffices to show both sides of the conversation.
434 If exp_logfile is also nonzero, this same output is written to the
435 stream defined by exp_logfile. If exp_logfile_all is non-zero,
436 exp_logfile is written regardless of the value of exp_loguser.
437
440 While I consider the library to be easy to use, I think that the stand‐
441 alone expect program is much, much, easier to use than working with the
442 C compiler and its usual edit, compile, debug cycle. Unlike typical C
443 programs, most of the debugging isn't getting the C compiler to accept
444 your programs - rather, it is getting the dialogue correct. Also,
445 translating scripts from expect to C is usually not necessary. For
446 example, the speed of interactive dialogues is virtually never an
447 issue. So please try the standalone 'expect' program first. I suspect
448 it is a more appropriate solution for most people than the library.
449 Nonetheless, if you feel compelled to debug in C, here are some tools
451 to help you.
452 extern int exp_is_debugging;
454 extern FILE *exp_debugfile;
455 While expect dialogues seem very intuitive, trying to codify them in a
457 program can reveal many surprises in a program's interface. Therefore
458 a variety of debugging aids are available. They are controlled by the
459 above variables, all 0 by default.
460 Debugging information internal to expect is sent to stderr when
462 exp_is_debugging is non-zero. The debugging information includes every
463 character received, and every attempt made to match the current input
464 against the patterns. In addition, non-printable characters are trans‐
465 lated to a printable form. For example, a control-C appears as a caret
466 followed by a C. If exp_logfile is non-zero, this information is also
467 written to that stream.
468 If exp_debugfile is non-zero, all normal and debugging information is
470 written to that stream, regardless of the value of exp_is_debugging.
471
473 The stream versions of the expect functions are much slower than the
474 file descriptor versions because there is no way to portably read an
475 unknown number of bytes without the potential of timing out. Thus,
476 characters are read one at a time. You are therefore strongly encour‐
477 aged to use the file descriptor versions of expect (although, automated
478 versions of interactive programs don't usually demand high speed any‐
479 way).
480 You can actually get the best of both worlds, writing with the usual
482 stream functions and reading with the file descriptor versions of
483 expect as long as you don't attempt to intermix other stream input
484 functions (e.g., fgetc). To do this, pass fileno(stream) as the file
485 descriptor each time. Fortunately, there is little reason to use any‐
486 thing but the expect functions when reading from interactive programs.
487 There is no matching exp_pclose to exp_popen (unlike popen and pclose).
489 It only takes two functions to close down a connection (fclose() fol‐
490 lowed by waiting on the pid), but it is not uncommon to separate these
491 two actions by large time intervals, so the function seems of little
492 value.
493 If you are running on a Cray running Unicos (all I know for sure from
495 experience), you must run your compiled program as root or setuid. The
496 problem is that the Cray only allows root processes to open ptys. You
497 should observe as much precautions as possible: If you don't need per‐
498 missions, setuid(0) only immediately before calling one of the spawn
499 functions and immediately set it back afterwards.
500 Normally, spawn takes little time to execute. If you notice spawn tak‐
502 ing a significant amount of time, it is probably encountering ptys that
503 are wedged. A number of tests are run on ptys to avoid entanglements
504 with errant processes. (These take 10 seconds per wedged pty.) Run‐
505 ning expect with the -d option will show if expect is encountering many
506 ptys in odd states. If you cannot kill the processes to which these
507 ptys are attached, your only recourse may be to reboot.
508
510 The exp_fexpect functions don't work at all under HP-UX - it appears to
511 be a bug in getc. Follow the advice (above) about using the exp_expect
512 functions (which doesn't need to call getc). If you fix the problem
513 (before I do - please check the latest release) let me know.
514
516 An alternative to this library is the expect program. expect inter‐
517 prets scripts written in a high-level language which direct the dia‐
518 logue. In addition, the user can take control and interact directly
519 when desired. If it is not absolutely necessary to write your own C
520 program, it is much easier to use expect to perform the entire interac‐
521 tion. It is described further in the following references:
522 "expect: Curing Those Uncontrollable Fits of Interactivity" by Don
524 Libes, Proceedings of the Summer 1990 USENIX Conference, Anaheim, Cali‐
525 fornia, June 11-15, 1990.
526 "Using expect to Automate System Administration Tasks" by Don Libes,
528 Proceedings of the 1990 USENIX Large Installation Systems Administra‐
529 tion Conference, Colorado Springs, Colorado, October 17-19, 1990.
530 expect(1), alarm(3), read(2), write(2), fdopen(3), execve(2),
532 execvp(3), longjmp(3), pty(4).
533 There are several examples C programs in the test directory of expect's
535 source distribution which use the expect library.
536
538 Don Libes, libes@nist.gov, National Institute of Standards and Technol‐
539 ogy
540
542 Thanks to John Ousterhout (UCBerkeley) for supplying the pattern
543 matcher.
544 Design and implementation of the expect library was paid for by the
546 U.S. government and is therefore in the public domain. However the
547 author and NIST would like credit if this program and documentation or
548 portions of them are used.
549 12 December 1991 LIBEXPECT(3)