Introduction to Library Functions LIBEXPECT(3)
NAME
libexpect - programmed dialogue library with interactive
programs
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.
SYNOPSIS
#include expecttcl.h
ExpectInit(interp);
cc files... -lexpect5.20 -ltcl7.5 -lm
Note: library versions may differ in the actual release.
The ExpectInit 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 "expsend".
Generally, you should only call Expect commands via
TclEval. Certain auxiliary functions may be called
directly. They are summarized below. They may be useful in
constructing your own main. Look at the file expmainexp.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 expmaintk.c in the
Expect distribution.
int expcmdlinecmds;
int expinteractive;
FILE *expcmdfile;
char *expcmdfilename;
int exptcldebuggeravailable;
void expparseargv(TclInterp *,int argc,char **argv);
int expinterpreter(TclInterp *);
void expinterpretcmdfile(TclInterp *,FILE *);
void expinterpretcmdfilename(TclInterp *,char *);
void expinterpretrcfiles(TclInterp *,int myrc,int sysrc);
char * expcook(char *s,int *len);
void (*expappexit)EXPROTO((TclInterp *);
void expexit(TclInterp *,int status);
void expexithandlers(TclInterp *);
void experror(TclInterp,char *,...);
expcmdlinecmds is 1 if Expect has been invoked with com-
mands on the program command-line (using "-c" for example).
SunOS 5.10 Last change: 12 December 1991 1
Introduction to Library Functions LIBEXPECT(3)
expinteractive is 1 if Expect has been invoked with the -i
flag or if no commands or script is being invoked.
expcmdfile is a stream from which Expect will read com-
mands. expcmdfilename is the name of a file which Expect
will open and read commands from.
exptcldebuggeravailable is 1 if the debugger has been
armed.
expparseargv reads the representation of the command line.
Based on what is found, any of the other variables listed
here are initialized appropriately. expinterpreter
interactively prompts the user for commands and evaluates
them. expinterpretcmdfile reads the given stream and
evaluates any commands found. expinterpretcmdfilename
opens the named file and evaluates any commands found.
expinterpretrcfiles reads and evalutes the .rc files. If
myrc is zero, then ~/.expectrc is skipped. If sysrc is
zero, then the system-wide expectrc file is skipped.
expcook 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. experror is a printf-like func-
tion that to interp->result.
SYNOPSIS
#include
int
expspawnl(file, arg0 [, arg1, ..., argn] (char *)0);
char *file;
char *arg0, *arg1, ... *argn;
int
expspawnv(file,argv);
char *file, *argv[ ];
int
expspawnfd(fd);
int fd;
FILE *
exppopen(command);
char *command;
extern int exppid;
extern int expttyinit;
extern int expttycopy;
extern int expconsole;
extern char *expsttyinit;
extern void (*expcloseinchild)();
SunOS 5.10 Last change: 12 December 1991 2
Introduction to Library Functions LIBEXPECT(3)
extern void (*expchildexecprelude)();
extern void expclosetclfiles();
cc files... -lexpect -ltcl -lm
DESCRIPTION
expspawnl and expspawnv fork a new process so that its
stdin, stdout, and stderr can be written and read by the
current process. file is the name of a file to be executed.
The arg pointers are null-terminated strings. Following the
style of execve(), arg0 (or argv[0]) is customarily a dupli-
cate of the name of the file.
Four interfaces are available, expspawnl is useful when the
number of arguments is known at compile time. expspawnv is
useful when the number of arguments is not known at compile
time. expspawnfd is useful when an open file descriptor is
already available as a source. exppopen is explained later
on.
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.)
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).
exppopen 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 exppopen below demonstrates
expspawnl.
FILE *
exppopen(program)
char *program;
{
FILE *fp;
int ec;
if (0 > (ec = expspawnl("sh","sh","-c",program,(char *)0)))
return(0);
if (NUL == (fp = fdopen(ec,"r]")) return(0);
setbuf(fp,(char *)0);
return(fp);
}
SunOS 5.10 Last change: 12 December 1991 3
Introduction to Library Functions LIBEXPECT(3)
After a process is started, the variable exppid is set to
the process-id of the new process. The variable
expptyslavename is set to the name of the slave side of
the pty.
The spawn functions uses a pty to communicate with the pro-
cess. 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 expttycopy to 0.
The pty is further initialized to some system wide defaults
if expttyinit is non-zero. The default is generally com-
parable to "stty sane".
The tty setting can be further modified by setting the vari-
able expsttyinit. This variable is interpreted in the
style of stty arguments. For example, expsttyinit =
"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
expconsole to 1.
Between the time a process is started and the new program is
given control, the spawn functions can clean up the environ-
ment 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
expcloseinchild. 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 expclosetclfiles which closes all files between
the default standard file descriptors and the highest
descriptor known to Tcl. (Expect does this.)
The function expchildexecprelude is the last function
called prior to the actual exec in the child. You can rede-
fine this for effects such as manipulating the uid or the
signals.
IF YOU WANT TO ALOCATE YOUR OWN PTY
extern int expautoallocpty;
extern int exppty[2];
SunOS 5.10 Last change: 12 December 1991 4
Introduction to Library Functions LIBEXPECT(3)
The spawn functions use a pty to communicate with the pro-
cess. 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
expautoallocpty to 0, exppty[0] to the master pty file
descriptor and exppty[1] to the slave pty file descriptor.
The expect library will not do any pty initializations
(e.g., expsttyinit 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 communi-
cation takes place with the master pty file descriptor.
expspawnl and expspawnv duplicate the shell's actions in
searching for an executable file in a list of directories.
The directory list is obtained from the environment.
EXPECT PROCESING
While it is possible to use read() to read information from
a process spawned by expspawnl or expspawnv, more con-
venient functions are provided. They are as follows:
int
expexpectl(fd,type1,pattern1,[re1,],value1,type2,...,expend);
int fd;
enum exptype type;
char *pattern1, *pattern2, ...;
regexp *re1, *re2, ...;
int value1, value2, ...;
int
expfexpectl(fp,type1,pattern1,[re1,]value1,type2,...,expend);
FILE *fp;
enum exptype type;
char *pattern1, *pattern2, ...;
regexp *re1, *re2, ...;
int value1, value2, ...;
enum exptype {
expend,
expglob,
expexact,
expregexp,
expcompiled,
expnull,
};
struct expcase {
char *pattern;
regexp *re;
enum exptype type;
int value;
};
SunOS 5.10 Last change: 12 December 1991 5
Introduction to Library Functions LIBEXPECT(3)
int
expexpectv(fd,cases);
int fd;
struct expcase *cases;
int
expfexpectv(fp,cases);
FILE *fp;
struct expcase *cases;
extern int exptimeout;
extern char *expmatch;
extern char *expmatchend;
extern char *expbuffer;
extern char *expbufferend;
extern int expmatchmax;
extern int expfullbuffer;
extern int expremovenulls;
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.
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.
The type argument is one of four values. expend indicates
that no more patterns appear. expglob indicates that the
pattern is a glob-style string pattern. expexact indicates
that the pattern is an exact string. expregexp indicates
that the pattern is a regexp-style string pattern.
expcompiled indicates that the pattern is a regexp-style
string pattern, and that its compiled form is also provided.
expnull indicates that the pattern is a null (for debugging
purposes, a string pattern must also follow).
If the compiled form is not provided with the functions
expexpectl and expfexpectl, any pattern compilation done
internally is thrown away after the function returns. The
functions expexpectv and expfexpectv 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.
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
SunOS 5.10 Last change: 12 December 1991 6
Introduction to Library Functions LIBEXPECT(3)
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 expnull matches if a null appears in the input.
The variable expremovenulls must be set to 0 to prevent
nulls from being automatically stripped. By default,
expremovenulls is set to 1 and nulls are automatically
stripped.
expexpectv and expfexpectv 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 expcase with type expend. For the rest of
this discussion, these functions will be referred to generi-
cally as expect.
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 EXPEOF,
EXPTIMEOUT, or EXPFULBUFER. Upon EOF or timeout, the
value EXPEOF or EXPTIMEOUT is returned. The default
timeout period is 10 seconds but may be changed by setting
the variable exptimeout. 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 expfullbuffer is 1, then EXPFULBUFER is
returned if expbuffer fills with no pattern having matched.
When the expect function returns, expbuffer points to the
buffer of characters that was being considered for matching.
expbufferend points to one past the last character in
expbuffer. If a match occurred, expmatch points into
expbuffer where the match began. expmatchend points to
one character past where the match ended.
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 EXPTIMEOUT (just
like you would if you were interacting manually). More phi-
losophy and strategies on specifying expect patterns can be
found in the documentation on the expect program itself.
See SEE ALSO below.
Patterns are the usual C-shell-style regular expressions.
For example, the following fragment looks for a successful
SunOS 5.10 Last change: 12 December 1991 7
Introduction to Library Functions LIBEXPECT(3)
login, such as from a telnet dialogue.
switch (expexpectl(
expglob,"connected",CON,
expglob,"busy",BUSY,
expglob,"failed",ABORT,
expglob,"invalid password",ABORT,
expend)) {
case CON: /* logged in successfully */
break;
case BUSY: /* couldn't log in at the moment */
break;
case EXPTIMEOUT:
case ABORT: /* can't log in at any moment! */
break;
default: /* problem with expect */
}
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
expmatchmax. Note that excessively large values can slow
down the pattern matcher.
RUNING IN THE BACKGROUND
extern int expdisconnected;
int expdisconnect();
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.
To move a process into the background, fork, call
expdisconnect() 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
expdisconnected to 1. This allows processes spawned after
this point to be started correctly.
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
SunOS 5.10 Last change: 12 December 1991 8
Introduction to Library Functions LIBEXPECT(3)
expect functions to do one and only read by setting timeout
to 0.
SLAVE CONTROL
void
expslavecontrol(fd,enable)
int fd;
int enable;
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 expslavecontrol. 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.
ERORS
All functions indicate errors by returning -1 and setting
errno.
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 expect.
SIGNALS
extern int expreading;
extern jmpbuf expreadenv;
expect uses alarm() to timeout, thus if you generate alarms
during expect, it will timeout prematurely.
Internally, expect calls read() which can be interrupted by
signals. If you define signal handlers, you can choose to
restart or abort expect's internal read. The variable,
expreading, is true if (and only if) expect's read has been
interrupted. longjmp(expreadenv,EXPABORT) will abort the
read. longjmp(expreadenv,EXPRESTART) will restart the
read.
LOGING
extern int exploguser;
extern int explogfileall
extern FILE *explogfile;
If exploguser is nonzero, expect sends any output from the
spawned process to stdout. Since interactive programs typi-
cally echo their input, this usually suffices to show both
SunOS 5.10 Last change: 12 December 1991 9
Introduction to Library Functions LIBEXPECT(3)
sides of the conversation. If explogfile is also nonzero,
this same output is written to the stream defined by
explogfile. If explogfileall is non-zero, explogfile is
written regardless of the value of exploguser.
DEBUGING
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, com-
pile, debug cycle. Unlike typical C programs, most of the
debugging isn't getting the C compiler to accept your pro-
grams - rather, it is getting the dialogue correct. Also,
translating scripts from expect to C is usually not neces-
sary. 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.
Nonetheless, if you feel compelled to debug in C, here are
some tools to help you.
extern int expisdebugging;
extern FILE *expdebugfile;
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 avail-
able. They are controlled by the above variables, all 0 by
default.
Debugging information internal to expect is sent to stderr
when expisdebugging is non-zero. The debugging informa-
tion 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 explogfile is non-zero, this informa-
tion is also written to that stream.
If expdebugfile is non-zero, all normal and debugging
information is written to that stream, regardless of the
value of expisdebugging.
CAVEATS
The stream versions of the 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 poten-
tial of timing out. Thus, characters are read one at a
time. You are therefore strongly encouraged to use the file
descriptor versions of expect (although, automated versions
of interactive programs don't usually demand high speed
SunOS 5.10 Last change: 12 December 1991 10
Introduction to Library Functions LIBEXPECT(3)
anyway).
You can actually get the best of both worlds, writing with
the usual stream functions and reading with the file
descriptor versions of 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 expect functions when reading from interactive pro-
grams.
There is no matching exppclose to exppopen (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.
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 pre-
cautions 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.
Normally, 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 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.
BUGS
The expfexpect functions don't work at all under HP-UX - it
appears to be a bug in getc. Follow the advice (above)
about using the expexpect functions (which doesn't need to
call getc). If you fix the problem (before I do - please
check the latest release) let me know.
SEE ALSO
An alternative to this library is the expect program.
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 expect to perform the entire interaction. It
is described further in the following references:
SunOS 5.10 Last change: 12 December 1991 11
Introduction to Library Functions LIBEXPECT(3)
"expect: Curing Those Uncontrollable Fits of Interactivity"
by Don Libes, Proceedings of the Summer 1990 USENIX Confer-
ence, Anaheim, California, June 11-15, 1990.
"Using expect to Automate System Administration Tasks" by
Don Libes, Proceedings of the 1990 USENIX Large Installation
Systems Administration Conference, Colorado Springs,
Colorado, October 17-19, 1990.
expect(1), alarm(3), read(2), write(2), fdopen(3),
execve(2), execvp(3), longjmp(3), pty(4).
There are several examples C programs in the test directory
of expect's source distribution which use the expect
library.
AUTHOR
Don Libes, libes@nist.gov, National Institute of Standards
and Technology
ACKNOWLEDGEMENTS
Thanks to John Ousterhout (UCBerkeley) for supplying the
pattern matcher.
Design and implementation of the 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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWexpect
Interface Stability Uncommitted
NOTES
Source for expect is available on http:/opensolaris.org.
SunOS 5.10 Last change: 12 December 1991 12
|
