1LIBEXPECT(3)               Library Functions Manual               LIBEXPECT(3)
2
3
4

NAME

6       libexpect - programmed dialogue library with interactive programs
7

DESCRIPTION

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

SYNOPSIS

15       #include expect_tcl.h
16       Expect_Init(interp);
17
18       cc files... -lexpect5.20 -ltcl7.5 -lm
19
20       Note: library versions may differ in the actual release.
21
22       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
27       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
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       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
59       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

SYNOPSIS

75       #include <expect.h>
76
77       int
78       exp_spawnl(file, arg0 [, arg1, ..., argn] (char *)0);
79       char *file;
80       char *arg0, *arg1, ... *argn;
81
82       int
83       exp_spawnv(file,argv);
84       char *file, *argv[ ];
85
86       int
87       exp_spawnfd(fd);
88       int fd;
89
90       FILE *
91       exp_popen(command);
92       char *command;
93
94       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
103       cc files... -lexpect -ltcl -lm
104
105

DESCRIPTION

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
113       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
119       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
124       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
129       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
134       FILE *
135       exp_popen(program)
136       char *program;
137       {
138            FILE *fp;
139            int ec;
140
141            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
148       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
152       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
157       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
161       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
166       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
170       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
175       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
180       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
185       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
189

IF YOU WANT TO ALLOCATE YOUR OWN PTY

191       extern int exp_autoallocpty;
192       extern int exp_pty[2];
193
194       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
205       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

EXPECT PROCESSING

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
214       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
222       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
230       enum exp_type {
231       exp_end,
232       exp_glob,
233       exp_exact,
234       exp_regexp,
235       exp_compiled,
236       exp_null,
237       };
238
239       struct exp_case {
240       char *pattern;
241       regexp *re;
242       enum exp_type type;
243       int value;
244       };
245
246       int
247       exp_expectv(fd,cases);
248       int fd;
249       struct exp_case *cases;
250
251       int
252       exp_fexpectv(fp,cases);
253       FILE *fp;
254       struct exp_case *cases;
255
256       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
265       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
268       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
272       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
281       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
289       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
296       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
301       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
307       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
318       If  the  variable exp_full_buffer is 1, then EXP_FULLBUFFER is returned
319       if exp_buffer fills with no pattern having matched.
320
321       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
327       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
336       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
340            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
356       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

RUNNING IN THE BACKGROUND

365       extern int exp_disconnected;
366       int exp_disconnect();
367
368       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
372       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

MULTIPLEXING

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
385       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

SLAVE CONTROL

389       void
390       exp_slave_control(fd,enable)
391       int fd;
392       int enable;
393
394
395       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
399       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
404

ERRORS

406       All functions indicate errors by returning -1 and setting errno.
407
408       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

SIGNALS

413       extern int exp_reading;
414       extern jmp_buf exp_readenv;
415
416       expect  uses  alarm()  to  timeout,  thus if you generate alarms during
417       expect, it will timeout prematurely.
418
419       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

LOGGING

427       extern int exp_loguser;
428       extern int exp_logfile_all
429       extern FILE *exp_logfile;
430
431       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
438

DEBUGGING

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
450       Nonetheless, if you feel compelled to debug in C, here are  some  tools
451       to help you.
452
453       extern int exp_is_debugging;
454       extern FILE *exp_debugfile;
455
456       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
461       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
469       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

CAVEATS

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
481       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
488       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
494       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
501       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

BUGS

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

SEE ALSO

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
523       "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
527       "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
531       expect(1),   alarm(3),   read(2),   write(2),   fdopen(3),   execve(2),
532       execvp(3), longjmp(3), pty(4).
533
534       There are several examples C programs in the test directory of expect's
535       source distribution which use the expect library.
536

AUTHOR

538       Don Libes, libes@nist.gov, National Institute of Standards and Technol‐
539       ogy
540

ACKNOWLEDGEMENTS

542       Thanks to  John  Ousterhout  (UCBerkeley)  for  supplying  the  pattern
543       matcher.
544
545       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
550
551
552                               12 December 1991                   LIBEXPECT(3)
Impressum