diff options
Diffstat (limited to 'libexpect.man')
| -rw-r--r-- | libexpect.man | 690 |
1 files changed, 690 insertions, 0 deletions
diff --git a/libexpect.man b/libexpect.man new file mode 100644 index 0000000..bbb141e --- /dev/null +++ b/libexpect.man @@ -0,0 +1,690 @@ +.TH LIBEXPECT 3 "12 December 1991" +.SH NAME +libexpect \- programmed dialogue library with interactive programs +.SH DESCRIPTION +This library contains functions that allow Expect to be used as +a Tcl extension or to be used directly from C or C++ (without Tcl). +Adding Expect as a Tcl extension is very short and simple, so that will be +covered first. +.SH SYNOPSIS +.nf + +.B #include "expect_tcl.h" +.B Expect_Init(interp); + +.B cc files... \-lexpect5.20 \-ltcl7.5 \-lm + +.fi +Note: library versions may differ in the actual release. + +The Expect_Init function adds expect commands to the named +interpreter. It avoids overwriting commands that already exist, +however aliases beginning with "exp_" are always created for expect +commands. So for example, "send" can be used as "exp_send". + +Generally, you should only call Expect commands via Tcl_Eval. +Certain auxiliary functions may be called directly. They are summarized +below. They may be useful in constructing your own main. Look +at the file exp_main_exp.c in the Expect distribution as +a prototype main. Another prototype is tclAppInit.c in the +Tcl source distribution. A prototype for working with Tk is in +exp_main_tk.c in the Expect distribution. +.nf + +int exp_cmdlinecmds; +int exp_interactive; +FILE *exp_cmdfile; +char *exp_cmdfilename; +int exp_tcl_debugger_available; + +void exp_parse_argv(Tcl_Interp *,int argc,char **argv); +int exp_interpreter(Tcl_Interp *); +void exp_interpret_cmdfile(Tcl_Interp *,FILE *); +void exp_interpret_cmdfilename(Tcl_Interp *,char *); +void exp_interpret_rcfiles(Tcl_Interp *,int my_rc,int sys_rc); +char * exp_cook(char *s,int *len); +void (*exp_app_exit)EXP_PROTO((Tcl_Interp *); +void exp_exit(Tcl_Interp *,int status); +void exp_exit_handlers(Tcl_Interp *); +void exp_error(Tcl_Interp,char *,...); + +.fi +.B exp_cmdlinecmds +is 1 if Expect has been invoked with commands on the program command-line (using "-c" for example). +.B exp_interactive +is 1 if Expect has been invoked with the -i flag or if no commands or script is being invoked. +.B exp_cmdfile +is a stream from which Expect will read commands. +.B exp_cmdfilename +is the name of a file which Expect will open and read commands from. +.B exp_tcl_debugger_available +is 1 if the debugger has been armed. + +.B exp_parse_argv +reads the representation of the command line. +Based on what is found, any of the other variables listed here +are initialized appropriately. +.B exp_interpreter +interactively prompts the user for commands and evaluates them. +.B exp_interpret_cmdfile +reads the given stream and evaluates any commands found. +.B exp_interpret_cmdfilename +opens the named file and evaluates any commands found. +.B exp_interpret_rcfiles +reads and evalutes the .rc files. If my_rc is zero, +then ~/.expectrc is skipped. If sys_rc is zero, then the system-wide +expectrc file is skipped. +.B exp_cook +returns a static buffer containing the argument reproduced with +newlines replaced by carriage-return linefeed sequences. +The primary purpose of this is to allow messages to be produced +without worrying about whether the terminal is in raw mode or +cooked mode. +If length is zero, it is computed via strlen. +.B exp_error is a printf-like function that writes the result +to interp->result. +.SH SYNOPSIS +.nf +.B #include <expect.h> + +.B int +.B "exp_spawnl(file, arg0 [, arg1, ..., argn] (char *)0);" +.B char *file; +.B char *arg0, *arg1, ... *argn; + +.B int +.B exp_spawnv(file,argv); +.B char *file, *argv[ ]; + +.B int +.B exp_spawnfd(fd); +.B int fd; + +.B FILE * +.B exp_popen(command); +.B char *command; + +.B extern int exp_pid; +.B extern int exp_ttyinit; +.B extern int exp_ttycopy; +.B extern int exp_console; +.B extern char *exp_stty_init; +.B extern void (*exp_close_in_child)(); +.B extern void (*exp_child_exec_prelude)(); +.B extern void exp_close_tcl_files(); + +.B cc files... \-lexpect \-ltcl \-lm +.fi + +.SH DESCRIPTION +.B exp_spawnl +and +.B exp_spawnv +fork a new process so that its stdin, +stdout, and stderr can be written and read by the current process. +.I file +is the name of a file to be executed. The +.I arg +pointers are +null-terminated strings. Following the style of execve(), +.I arg0 +(or +.IR argv[0] ) +is customarily a duplicate of the name of the file. +.PP +Four interfaces are available, +.B exp_spawnl +is useful when the number of +arguments is known at compile time. +.B exp_spawnv +is useful when the number of arguments is not known at compile time. +.B exp_spawnfd +is useful when an open file descriptor is already available as a source. +.B exp_popen +is explained later on. +.PP +If the process is successfully created, a file descriptor is returned +which corresponds to the process's stdin, stdout and stderr. +A stream may be associated with the file descriptor by using fdopen(). +(This should almost certainly be followed by setbuf() to unbuffer the I/O.) +.PP +Closing the file descriptor will typically be detected by the +process as an EOF. Once such a process exits, it should be waited +upon (via wait) in order to free up the kernel process slot. (Some systems +allow you to avoid this if you ignore the SIGCHLD signal). +.PP +.B exp_popen +is yet another interface, styled after popen(). It takes a Bourne +shell command line, and returns a stream that corresponds to the process's +stdin, stdout and stderr. The actual implementation of +.B exp_popen +below demonstrates +.BR exp_spawnl . +.nf + +FILE * +exp_popen(program) +char *program; +{ + FILE *fp; + int ec; + + if (0 > (ec = exp_spawnl("sh","sh","-c",program,(char *)0))) + return(0); + if (NULL == (fp = fdopen(ec,"r+")) return(0); + setbuf(fp,(char *)0); + return(fp); +} +.fi + +After a process is started, the variable +.B exp_pid +is set to the process-id of the new process. The variable +.B exp_pty_slave_name +is set to the name of the slave side of the pty. + +The spawn functions uses a pty to communicate with the process. By +default, the pty is initialized the same way as the user's tty (if +possible, i.e., if the environment has a controlling terminal.) This +initialization can be skipped by setting exp_ttycopy to 0. + +The pty is further initialized to some system wide defaults if +exp_ttyinit is non-zero. The default is generally comparable to "stty sane". + +The tty setting can be further modified by setting the variable +.BR exp_stty_init . +This variable is interpreted in the style of stty arguments. For +example, exp_stty_init = "sane"; repeats the default initialization. + +On some systems, it is possible to redirect console output to ptys. +If this is supported, you can force the next spawn to obtain the +console output by setting the variable +.B exp_console +to 1. + +Between the time a process is started and the new program is given +control, the spawn functions can clean up the environment by closing +file descriptors. By default, the only file descriptors closed are +ones internal to Expect and any marked "close-on-exec". + +If needed, you can close additional file descriptors by creating +an appropriate function and assigning it to exp_close_in_child. +The function will be called after the fork and before the exec. +(This also modifies the behavior of the spawn command in Expect.) + +If you are also using Tcl, it may be convenient to use the function +exp_close_tcl_files which closes all files between the default +standard file descriptors and the highest descriptor known to Tcl. +(Expect does this.) + +The function exp_child_exec_prelude is the last function called prior +to the actual exec in the child. You can redefine this for effects +such as manipulating the uid or the signals. + +.SH "IF YOU WANT TO ALLOCATE YOUR OWN PTY" +.nf + +.B extern int exp_autoallocpty; +.B extern int exp_pty[2]; +.fi + +The spawn functions use a pty to communicate with the process. By +default, a pty is automatically allocated each time a process is spawned. +If you want to allocate ptys yourself, before calling one of the spawn +functions, set +.B exp_autoallocpty +to 0, +.B exp_pty[0] +to the master pty file descriptor and +.B exp_pty[1] +to the slave pty file descriptor. +The expect library will not do any pty initializations (e.g., exp_stty_init will not be used). +The slave pty file descriptor will be +automatically closed when the process is spawned. After the process is +started, all further communication takes place with the master pty file +descriptor. +.PP +.B exp_spawnl +and +.B exp_spawnv +duplicate the shell's actions +in searching for an executable file in a list of directories. The +directory list is obtained from the environment. +.SH EXPECT PROCESSING +While it is possible to use read() to read information from a process +spawned by +.B exp_spawnl +or +.BR exp_spawnv , +more convenient functions are provided. They are as +follows: +.nf + +.B int +.B exp_expectl(fd,type1,pattern1,[re1,],value1,type2,...,exp_end); +.B int fd; +.B enum exp_type type; +.B char *pattern1, *pattern2, ...; +.B regexp *re1, *re2, ...; +.B int value1, value2, ...; +.B + +.B int +.B exp_fexpectl(fp,type1,pattern1,[re1,]value1,type2,...,exp_end); +.B FILE *fp; +.B enum exp_type type; +.B char *pattern1, *pattern2, ...; +.B regexp *re1, *re2, ...; +.B int value1, value2, ...; + +.B enum exp_type { +.B exp_end, +.B exp_glob, +.B exp_exact, +.B exp_regexp, +.B exp_compiled, +.B exp_null, +.B }; + +.B struct exp_case { +.B char *pattern; +.B regexp *re; +.B enum exp_type type; +.B int value; +.B }; + +.B int +.B exp_expectv(fd,cases); +.B int fd; +.B struct exp_case *cases; + +.B int +.B exp_fexpectv(fp,cases); +.B FILE *fp; +.B struct exp_case *cases; + +.B extern int exp_timeout; +.B extern char *exp_match; +.B extern char *exp_match_end; +.B extern char *exp_buffer; +.B extern char *exp_buffer_end; +.B extern int exp_match_max; +.B extern int exp_full_buffer; +.B extern int exp_remove_nulls; +.fi + +The functions wait until the output from a process matches one of the +patterns, a specified time period has passed, or an EOF is seen. +.PP +The first argument to each function is either a file descriptor or a stream. +Successive sets of arguments describe patterns and associated integer values +to return when the pattern matches. +.PP +The type argument is one of four values. exp_end indicates that no more +patterns appear. +exp_glob indicates that the pattern is a glob-style string pattern. +exp_exact indicates that the pattern is an exact string. +exp_regexp indicates that the pattern is a regexp-style string pattern. +exp_compiled indicates that the pattern is a regexp-style string pattern, +and that its compiled form is also provided. +exp_null indicates that the pattern is a null (for debugging purposes, +a string pattern must also follow). +.PP +If the compiled form is not provided with the functions +.B exp_expectl +and +.BR exp_fexpectl , +any pattern compilation done internally is +thrown away after the function returns. The functions +.B exp_expectv +and +.B exp_fexpectv +will automatically compile patterns and will not throw them away. +Instead, they must be discarded by the user, by calling free on each +pattern. It is only necessary to discard them, the last time the +cases are used. +.PP +Regexp subpatterns matched are stored in the compiled regexp. +Assuming "re" contains a compiled regexp, the matched string can be +found in re->startp[0]. The match substrings (according to the parentheses) +in the original pattern can be found in re->startp[1], re->startp[2], and +so on, up to re->startp[9]. The corresponding strings ends are re->endp[x] +where x is that same index as for the string start. + +The type exp_null matches if a null appears in the input. The +variable exp_remove_nulls must be set to 0 to prevent nulls from +being automatically stripped. By default, exp_remove_nulls is set +to 1 and nulls are automatically stripped. + +.B exp_expectv +and +.B exp_fexpectv +are useful when the number of patterns is +not known in advance. In this case, the sets are provided in an array. +The end of the array is denoted by a struct exp_case with type exp_end. +For the rest +of this discussion, these functions will be referred to generically as +.IR expect. +.PP +If a pattern matches, then the corresponding integer value is returned. +Values need not be unique, however they should be positive to avoid +being mistaken for EXP_EOF, EXP_TIMEOUT, or EXP_FULLBUFFER. +Upon EOF or timeout, the value +.B EXP_EOF +or +.B EXP_TIMEOUT +is returned. The +default timeout period is 10 seconds but may be changed by setting the +variable +.BR exp_timeout . +A value of -1 +disables a timeout from occurring. +A value of 0 causes the expect function to return immediately (i.e., poll) +after one read(). +However it must be preceded by a function such as select, poll, or +an event manager callback to guarantee that there is data to be read. + +If the variable exp_full_buffer is 1, then EXP_FULLBUFFER is returned +if exp_buffer fills with no pattern having matched. + +When the expect function returns, +.B exp_buffer +points to the buffer +of characters that was being considered for matching. +.B exp_buffer_end +points to one past the last character in exp_buffer. +If a match occurred, +.B exp_match +points into +.B exp_buffer +where the match began. +.B exp_match_end +points to one character past where the match ended. +.PP +Each time new input arrives, it is compared to each pattern in the +order they are listed. Thus, you may test for absence of a match by +making the last pattern something guaranteed to appear, such as a +prompt. In situations where there is no prompt, you must check for +.B EXP_TIMEOUT +(just like you would if you were interacting manually). More philosophy +and strategies on specifying +.B expect +patterns can be found in the +documentation on the +.B expect +program itself. See SEE ALSO below. +.PP +Patterns are the usual C-shell-style regular expressions. For +example, the following fragment looks for a successful login, such +as from a telnet dialogue. +.nf + + switch (exp_expectl( + exp_glob,"connected",CONN, + exp_glob,"busy",BUSY, + exp_glob,"failed",ABORT, + exp_glob,"invalid password",ABORT, + exp_end)) { + case CONN: /* logged in successfully */ + break; + case BUSY: /* couldn't log in at the moment */ + break; + case EXP_TIMEOUT: + case ABORT: /* can't log in at any moment! */ + break; + default: /* problem with expect */ + } +.fi + +Asterisks (as in the +example above) are a useful shorthand for omitting line-termination +characters and other detail. +Patterns must match the entire output of the current process (since +the previous read on the descriptor or stream). +More than 2000 bytes of output can +force earlier bytes to be "forgotten". This may be changed by setting +the variable +.BR exp_match_max . +Note that excessively large values can slow down the pattern matcher. +.SH RUNNING IN THE BACKGROUND +.nf + +.B extern int exp_disconnected; +.B int exp_disconnect(); + +.fi +It is possible to move a process into the background after it has +begun running. A typical use for this is to read passwords and then +go into the background to sleep before using the passwords to do real +work. +.PP +To move a process into the background, fork, call exp_disconnect() in the +child process and exit() in the parent process. This disassociates +your process from the controlling terminal. If you wish to move a +process into the background in a different way, you must set the +variable exp_disconnected to 1. This allows processes spawned after +this point to be started correctly. +.SH MULTIPLEXING +By default, the expect functions block inside of a read on a single file +descriptor. If you want to wait on patterns from multiple file +descriptors, +use select, poll, or an event manager. +They will tell you what file descriptor is ready to read. + +When a file descriptor is ready to read, you can use the expect +functions to do one and only read by setting timeout to 0. +.SH SLAVE CONTROL + +.nf + +.B void +.B exp_slave_control(fd,enable) +.B int fd; +.B int enable; + +.fi + +Pty trapping is normally done automatically by the expect functions. +However, if you want to issue an ioctl, for example, directly on the +slave device, you should temporary disable trapping. + +Pty trapping can be controlled with exp_slave_control. The first +argument is the file descriptor corresponding to the spawned process. +The second argument is a 0 if trapping is to be disabled and 1 if it +is to be enabled. + +.SH ERRORS +All functions indicate errors by returning \-1 and setting errno. +.PP +Errors that occur after the spawn functions fork (e.g., attempting to +spawn a non-existent program) are written to the process's stderr, +and will be read by the first +.BR expect . +.SH SIGNALS +.nf +.B extern int exp_reading; +.B extern jmp_buf exp_readenv; +.fi + +.B expect +uses alarm() to timeout, thus if you generate alarms during +.BR expect , +it will timeout prematurely. +.PP +Internally, +.B expect +calls read() which can be interrupted by signals. If +you define signal handlers, you can choose to restart or abort +.BR expect 's +internal read. The variable, +.BR exp_reading , +is true if (and only if) +.BR expect 's +read has been interrupted. longjmp(exp_readenv,EXP_ABORT) will abort +the read. longjmp(exp_readenv,EXP_RESTART) will restart the read. +.SH LOGGING +.nf + +.B extern int exp_loguser; +.B extern int exp_logfile_all +.B extern FILE *exp_logfile; +.fi + +If +.B exp_loguser +is nonzero, +.B expect +sends any output from the spawned process to +stdout. Since interactive programs typically echo their input, this +usually suffices to show both sides of the conversation. If +.B exp_logfile +is also nonzero, this same output is written to the stream defined by +.BR exp_logfile . +If +.B exp_logfile_all +is non-zero, +.B exp_logfile +is written regardless of the value of +.BR exp_loguser . + +.SH DEBUGGING +While I consider the library to be easy to use, I think that the +standalone expect program is much, much, easier to use than working +with the C compiler and its usual edit, compile, debug cycle. Unlike +typical C programs, most of the debugging isn't getting the C compiler +to accept your programs - rather, it is getting the dialogue correct. +Also, translating scripts from expect to C is usually not necessary. +For example, the speed of interactive dialogues is virtually never an +issue. So please try the standalone 'expect' program first. I +suspect it is a more appropriate solution for most people than the +library. +.PP +Nonetheless, if you feel compelled to debug in C, +here are some tools to help you. +.nf + +.B extern int exp_is_debugging; +.B extern FILE *exp_debugfile; +.fi + +While expect dialogues seem very intuitive, trying to codify them in a +program can reveal many surprises in a program's interface. Therefore +a variety of debugging aids are available. They are controlled by the +above variables, all 0 by default. + +Debugging information internal to +.B expect +is sent to stderr when +.B exp_is_debugging +is non-zero. The debugging information includes +every character received, and every attempt made to match the current +input against the patterns. In addition, non-printable characters are +translated to a printable form. For example, a control-C appears as a +caret followed by a C. If +.B exp_logfile +is non-zero, this information +is also written to that stream. +.PP +If +.B exp_debugfile +is non-zero, all normal and debugging information is +written to that stream, regardless of the value of +.BR exp_is_debugging . +.SH CAVEATS +The stream versions of the +.B expect +functions are much slower than the +file descriptor versions because there is no way to portably read +an unknown number of bytes without the potential of timing out. +Thus, characters are read one at a time. You are therefore strongly +encouraged to use the file descriptor versions of +.B expect +(although, +automated versions of interactive programs don't usually demand high speed +anyway). +.PP +You can actually get the best of both worlds, writing with the usual +stream functions and reading with the file descriptor versions of +.B expect +as long as you don't attempt to intermix other stream input +functions (e.g., fgetc). +To do this, pass fileno(stream) as the file descriptor each time. +Fortunately, there is little reason to use anything but the +.B expect +functions when reading from interactive programs. +.PP +There is no matching exp_pclose to exp_popen (unlike popen and pclose). +It only takes two functions to close down a connection (fclose() followed +by waiting on the pid), but it is not uncommon to separate these two +actions by large time intervals, so the function seems of little value. +.PP +If you are running on a Cray running Unicos (all I know for sure from +experience), you must run your compiled program as root or setuid. The +problem is that the Cray only allows root processes to open ptys. +You should observe as much precautions as possible: If you don't need +permissions, setuid(0) only immediately before calling one of the spawn +functions and immediately set it back afterwards. +.PP +Normally, +.B spawn +takes little time to execute. If you notice spawn taking a +significant amount of time, it is probably encountering ptys that are +wedged. A number of tests are run on ptys to avoid entanglements with +errant processes. (These take 10 seconds per wedged pty.) Running +expect with the \-d option will show if +.B expect +is encountering many ptys in odd states. If you cannot kill +the processes to which these ptys are attached, your only recourse may +be to reboot. +.SH BUGS +The +.B exp_fexpect +functions don't work at all under HP-UX - it appears to be a bug in getc. +Follow the +advice (above) about using the +.B exp_expect +functions (which doesn't need to call getc). If you fix the problem (before +I do - please check the latest release) let me know. +.SH SEE ALSO +An alternative to this library is the +.B expect +program. +.B expect +interprets scripts written in a high-level language +which direct the dialogue. +In addition, the user can take control and interact directly when desired. +If it is not absolutely necessary to write your own C program, it is much +easier to use +.B expect +to perform the entire interaction. +It is described further in the following references: +.PP +.I +"expect: Curing Those Uncontrollable Fits of Interactivity" \fRby Don Libes, +Proceedings of the Summer 1990 USENIX Conference, +Anaheim, California, June 11-15, 1990. +.PP +.I +"Using expect to Automate System Administration Tasks" \fRby Don Libes, +Proceedings of the 1990 USENIX Large Installation Systems Administration +Conference, Colorado Springs, Colorado, October 17-19, 1990. +.PP +expect(1), alarm(3), read(2), write(2), fdopen(3), execve(2), execvp(3), +longjmp(3), pty(4). +.PP +There are several examples C programs in the test directory of +.BR expect 's +source distribution which use the expect library. +.PP +.SH AUTHOR +Don Libes, libes@nist.gov, National Institute of Standards and Technology +.SH ACKNOWLEDGEMENTS +Thanks to John Ousterhout (UCBerkeley) for supplying the pattern +matcher. +.PP +Design and implementation of the +.B expect +library was paid for by the U.S. government and is therefore in the public +domain. +However the author and NIST would like credit +if this program and documentation or portions of them are used. |