---

   libexpect    ( 3 )

---

EXPECT PROCESSING

While it is possible to use read() to read information from a process spawned by exp_spawnl or exp_spawnv, more convenient functions are provided. They are as follows:

int exp_expectl(fd,type1,pattern1,[re1,],value1,type2,...,exp_end); int fd; enum exp_type type; char *pattern1, *pattern2, ...; regexp *re1, *re2, ...; int value1, value2, ...;

int exp_fexpectl(fp,type1,pattern1,[re1,]value1,type2,...,exp_end); FILE *fp; enum exp_type type; char *pattern1, *pattern2, ...; regexp *re1, *re2, ...; int value1, value2, ...;

enum exp_type { exp_end, exp_glob, exp_exact, exp_regexp, exp_compiled, exp_null, };

struct exp_case { char *pattern; regexp *re; enum exp_type type; int value; };

int exp_expectv(fd,cases); int fd; struct exp_case *cases;

int exp_fexpectv(fp,cases); FILE *fp; struct exp_case *cases;

extern int exp_timeout; extern char *exp_match; extern char *exp_match_end; extern char *exp_buffer; extern char *exp_buffer_end; extern int exp_match_max; extern int exp_full_buffer; extern int exp_remove_nulls;

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. 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).

If the compiled form is not provided with the functions exp_expectl and exp_fexpectl, any pattern compilation done internally is thrown away after the function returns. The functions exp_expectv and 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.

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.

exp_expectv and 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 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 EXP_EOF, EXP_TIMEOUT, or EXP_FULLBUFFER. Upon EOF or timeout, the value EXP_EOF or EXP_TIMEOUT is returned. The default timeout period is 10 seconds but may be changed by setting the variable 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, exp_buffer points to the buffer of characters that was being considered for matching. exp_buffer_end points to one past the last character in exp_buffer. If a match occurred, exp_match points into exp_buffer where the match began. exp_match_end 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 EXP_TIMEOUT (just like you would if you were interacting manually). More philosophy 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 login, such as from a telnet dialogue.

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 */ }

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 exp_match_max. Note that excessively large values can slow down the pattern matcher.