1 .TH LIBEXPECT 3 "12 December 1991"
3 libexpect \- programmed dialogue with interactive programs \- C functions
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
12 .B #include "expect_tcl.h"
13 .B Expect_Init(interp);
15 .B cc files... \-lexpect5.20 \-ltcl7.5 \-lm
18 Note: library versions may differ in the actual release.
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".
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.
37 char *exp_cmdfilename;
38 int exp_tcl_debugger_available;
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 *,...);
53 is 1 if Expect has been invoked with commands on the program command-line (using "-c" for example).
55 is 1 if Expect has been invoked with the -i flag or if no commands or script is being invoked.
57 is a stream from which Expect will read commands.
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.
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.
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.
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
83 If length is zero, it is computed via strlen.
84 .B exp_error is a printf-like function that writes the result
88 .B #include <expect.h>
91 .B "exp_spawnl(file, arg0 [, arg1, ..., argn] (char *)0);"
93 .B char *arg0, *arg1, ... *argn;
96 .B exp_spawnv(file,argv);
97 .B char *file, *argv[ ];
104 .B exp_popen(command);
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();
116 .B cc files... \-lexpect \-ltcl \-lm
123 fork a new process so that its stdin,
124 stdout, and stderr can be written and read by the current process.
126 is the name of a file to be executed. The
129 null-terminated strings. Following the style of execve(),
133 is customarily a duplicate of the name of the file.
135 Four interfaces are available,
137 is useful when the number of
138 arguments is known at compile time.
140 is useful when the number of arguments is not known at compile time.
142 is useful when an open file descriptor is already available as a source.
144 is explained later on.
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.)
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).
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
172 if (0 > (ec = exp_spawnl("sh","sh","-c",program,(char *)0)))
174 if (NULL == (fp = fdopen(ec,"r+")) return(0);
175 setbuf(fp,(char *)0);
180 After a process is started, the variable
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.
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.
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".
194 The tty setting can be further modified by setting the variable
196 This variable is interpreted in the style of stty arguments. For
197 example, exp_stty_init = "sane"; repeats the default initialization.
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
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".
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.)
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.
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.
224 .SH "IF YOU WANT TO ALLOCATE YOUR OWN PTY"
227 .B extern int exp_autoallocpty;
228 .B extern int exp_pty[2];
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
238 to the master pty file descriptor and
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
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
259 more convenient functions are provided. They are as
264 .B exp_expectl(fd,type1,pattern1,[re1,],value1,type2,...,exp_end);
266 .B enum exp_type type;
267 .B char *pattern1, *pattern2, ...;
268 .B regexp *re1, *re2, ...;
269 .B int value1, value2, ...;
273 .B exp_fexpectl(fp,type1,pattern1,[re1,]value1,type2,...,exp_end);
275 .B enum exp_type type;
276 .B char *pattern1, *pattern2, ...;
277 .B regexp *re1, *re2, ...;
278 .B int value1, value2, ...;
292 .B enum exp_type type;
297 .B exp_expectv(fd,cases);
299 .B struct exp_case *cases;
302 .B exp_fexpectv(fp,cases);
304 .B struct exp_case *cases;
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;
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.
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.
323 The type argument is one of four values. exp_end indicates that no more
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).
333 If the compiled form is not provided with the functions
337 any pattern compilation done internally is
338 thrown away after the function returns. The functions
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
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.
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.
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.
366 of this discussion, these functions will be referred to generically as
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
377 default timeout period is 10 seconds but may be changed by setting the
381 disables a timeout from occurring.
382 A value of 0 causes the expect function to return immediately (i.e., poll)
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.
387 If the variable exp_full_buffer is 1, then EXP_FULLBUFFER is returned
388 if exp_buffer fills with no pattern having matched.
390 When the expect function returns,
393 of characters that was being considered for matching.
395 points to one past the last character in exp_buffer.
400 where the match began.
402 points to one character past where the match ended.
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
409 (just like you would if you were interacting manually). More philosophy
410 and strategies on specifying
412 patterns can be found in the
415 program itself. See SEE ALSO below.
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.
423 exp_glob,"connected",CONN,
424 exp_glob,"busy",BUSY,
425 exp_glob,"failed",ABORT,
426 exp_glob,"invalid password",ABORT,
428 case CONN: /* logged in successfully */
430 case BUSY: /* couldn't log in at the moment */
433 case ABORT: /* can't log in at any moment! */
435 default: /* problem with expect */
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
448 Note that excessively large values can slow down the pattern matcher.
449 .SH RUNNING IN THE BACKGROUND
452 .B extern int exp_disconnected;
453 .B int exp_disconnect();
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
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.
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
471 use select, poll, or an event manager.
472 They will tell you what file descriptor is ready to read.
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.
481 .B exp_slave_control(fd,enable)
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.
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
497 All functions indicate errors by returning \-1 and setting errno.
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
505 .B extern int exp_reading;
506 .B extern jmp_buf exp_readenv;
510 uses alarm() to timeout, thus if you generate alarms during
512 it will timeout prematurely.
516 calls read() which can be interrupted by signals. If
517 you define signal handlers, you can choose to restart or abort
519 internal read. The variable,
521 is true if (and only if)
523 read has been interrupted. longjmp(exp_readenv,EXP_ABORT) will abort
524 the read. longjmp(exp_readenv,EXP_RESTART) will restart the read.
528 .B extern int exp_loguser;
529 .B extern int exp_logfile_all
530 .B extern FILE *exp_logfile;
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
541 is also nonzero, this same output is written to the stream defined by
547 is written regardless of the value of
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
562 Nonetheless, if you feel compelled to debug in C,
563 here are some tools to help you.
566 .B extern int exp_is_debugging;
567 .B extern FILE *exp_debugfile;
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.
575 Debugging information internal to
577 is sent to stderr when
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
585 is non-zero, this information
586 is also written to that stream.
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 .
594 The stream versions of the
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
603 automated versions of interactive programs don't usually demand high speed
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
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
614 functions when reading from interactive programs.
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.
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.
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
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
642 functions don't work at all under HP-UX - it appears to be a bug in getc.
644 advice (above) about using the
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.
649 An alternative to this library is the
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
659 to perform the entire interaction.
660 It is described further in the following references:
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.
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.
672 expect(1), alarm(3), read(2), write(2), fdopen(3), execve(2), execvp(3),
675 There are several examples C programs in the test directory of
677 source distribution which use the expect library.
680 Don Libes, libes@nist.gov, National Institute of Standards and Technology
682 Thanks to John Ousterhout (UCBerkeley) for supplying the pattern
685 Design and implementation of the
687 library was paid for by the U.S. government and is therefore in the public
689 However the author and NIST would like credit
690 if this program and documentation or portions of them are used.