5 miniexpect - A very simple expect library for C.
12 #include <miniexpect.h>
15 h = mexp_spawnl ("ssh", "ssh", "host", NULL);
16 switch (mexp_expect (h, regexps, ovector, ovecsize)) {
21 cc prog.c -o prog -lminiexpect -lpcre
25 Miniexpect is a very simple expect-like library for C. Expect is a
26 way to control an external program that wants to be run interactively.
28 Miniexpect has a saner interface than libexpect, and doesn't depend on
29 Tcl. It is also thread safe, const-correct and uses modern C
32 Miniexpect is a standalone library, except for a single dependency: it
33 requires the PCRE (Perl Compatible Regular Expressions) library from
34 L<http://www.pcre.org/>. The PCRE dependency is fundamental because
35 we want to offer the most powerful regular expression syntax to match
36 on, but more importantly because PCRE has a convenient way to detect
37 partial matches which made this library very simple to implement.
39 This manual page documents the API. Examples of how to use the API
40 can be found in the source directory.
44 Miniexpect lets you start up an external program, control it (by
45 sending commands to it), and close it down gracefully. Two things
46 make this different from other APIs like L<popen(3)> and L<system(3)>:
47 Firstly miniexpect creates a pseudoterminal (pty). Secondly
48 miniexpect lets you match the output of the program using regular
49 expressions. Both of these are handy for controlling interactive
50 programs that might (for example) ask for passwords, but you can use
51 miniexpect on just about any external program.
53 You can control multiple programs at the same time.
55 =head1 SPAWNING THE SUBPROCESS
57 There are four calls for creating a subprocess:
59 B<mexp_h *mexp_spawnl (const char *file, const char *arg, ...);>
61 This creates a subprocess running the external program C<file> (the
62 current C<$PATH> is searched unless you give an absolute path).
63 C<arg, ...> are the arguments to the program. You should terminate
64 the list of arguments with C<NULL>. Usually the first argument should
65 be the name of the program.
67 The return value is a handle (see next section).
69 If there was an error running the subprocess, C<NULL> is returned and
70 the error is available in C<errno>.
72 For example, to run an ssh subprocess you could do:
74 h = mexp_spawnl ("ssh", "ssh", "-l", "root", "host", NULL);
76 or to run a particular ssh binary:
78 h = mexp_spawnl ("/usr/local/bin/ssh", "ssh", "-l", "root", "host", NULL);
80 An alternative to C<mexp_spawnl> is:
82 B<mexp_h *mexp_spawnv (const char *file, char **argv);>
84 This is the same as C<mexp_spawnl> except that you pass the arguments
85 in a NULL-terminated array.
87 There are also two versions of the above calls which take flags:
89 B<mexp_h *mexp_spawnlf (unsigned flags, const char *file, const char *arg, ...);>
91 B<mexp_h *mexp_spawnvf (unsigned flags, const char *file, char **argv);>
93 The flags may contain the following values, logically ORed together:
97 =item B<MEXP_SPAWN_KEEP_SIGNALS>
99 Do not reset signal handlers to C<SIG_DFL> in the subprocess.
101 =item B<MEXP_SPAWN_KEEP_FDS>
103 Do not close file descriptors E<ge> 3 in the subprocess.
105 =item B<MEXP_SPAWN_COOKED_MODE> or B<MEXP_SPAWN_RAW_MODE>
107 Configure the pty in cooked mode or raw mode. Raw mode is the
114 After spawning a subprocess, you get back a handle which is a pointer
118 typedef struct mexp_h mexp_h;
120 Various methods can be used on the handle:
122 B<int mexp_get_fd (mexp_h *h);>
124 Return the file descriptor of the pty of the subprocess. You can read
125 and write to this if you want, although convenience functions are also
126 provided (see below).
128 B<pid_t mexp_get_pid (mexp_h *h);>
130 Return the process ID of the subprocess. You can send it signals if
133 B<int mexp_get_timeout_ms (mexp_h *h);>
135 B<void mexp_set_timeout_ms (mexp_h *h, int millisecs);>
137 B<void mexp_set_timeout (mexp_h *h, int secs);>
139 Get or set the timeout used by C<mexp_expect> [see below]. The
140 resolution is milliseconds (1/1000th of a second). Set this before
141 calling C<mexp_expect>. Passing -1 to either of the C<set_> methods
142 means no timeout. The default setting is 60000 milliseconds (60
145 B<size_t mexp_get_read_size (mexp *h);>
147 B<void mexp_set_read_size (mexp *h, size_t read_size);>
149 Get or set the natural size (in bytes) for reads from the subprocess.
150 The default is 1024. Most callers will not need to change this.
152 B<int mexp_get_pcre_error (mexp *h);>
154 When C<mexp_expect> [see below] calls the PCRE function
155 L<pcre_exec(3)>, it stashes the return value in the C<pcre_error>
156 field in the handle, and that field is returned by this method.
158 There are two uses for this:
164 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
165 error code returned by L<pcre_exec(3)> is available by calling this
166 method. For a list of PCRE error codes, see L<pcreapi(3)>.
170 A more unusual use is if you ever need to get the captured substrings
171 from your regular expression (calling L<pcre_get_substring(3)>). The
172 third parameter of that function (C<stringcount>) is the value
173 returned by L<pcre_exec(3)>, and so you can call it like this:
175 pcre_get_substring (h->buffer, ovector,
176 mexp_get_pcre_error (h), 1, &matched);
180 B<void mexp_set_debug_file (mexp *h, FILE *fp);>
182 B<FILE *mexp_get_debug_file (mexp *h);>
184 Set or get the debug file of the handle. To enable debugging, pass a
185 non-C<NULL> file handle, eg. C<stderr>. To disable debugging, pass
186 C<NULL>. Debugging messages are printed on the file handle.
188 Note that all output and input gets printed, including passwords. To
189 prevent passwords from being printed, modify your code to call
190 C<mexp_printf_password> instead of C<mexp_printf>.
192 The following fields in the handle do not have methods, but can be
193 accessed directly instead:
199 If C<mexp_expect> returns a match then these variables contain the
200 read buffer. Note this buffer does not contain the full input from
201 the process, but it will contain at least the part matched by the
202 regular expression (and maybe some more). C<buffer> is the read
203 buffer and C<len> is the number of bytes of data in the buffer.
207 If C<mexp_expect> returns a match, then C<next_match> points to the
208 first byte in the buffer I<after> the fully matched expression. (It
209 may be C<-1> which means it is invalid). The next time that
210 C<mexp_expect> is called, it will start by consuming the data
211 C<buffer[next_match...len-1]>. Callers may also need to read from
212 that point in the buffer before calling L<read(2)> on the file
213 descriptor. Callers may also set this, for example setting it to
214 C<-1> in order to ignore the remainder of the buffer. In most cases
215 callers can ignore this field, and C<mexp_expect> will just do the
216 right thing when called repeatedly.
222 Opaque pointers for use by the caller. The library will not touch
225 =head1 CLOSING THE HANDLE
227 To close the handle and clean up the subprocess, call:
229 B<int mexp_close (mexp_h *h);>
231 This returns the status code from the subprocess. This is in the form
232 of a L<waitpid(2)>/L<system(3)> status so you have to use the macros
233 C<WIFEXITED>, C<WEXITSTATUS>, C<WIFSIGNALED>, C<WTERMSIG> etc defined
234 in C<E<lt>sys/wait.hE<gt>> to parse it.
236 If there was a system call error, then C<-1> is returned. The error
245 Even in error cases, the handle is always closed and its memory is
250 It is normal for the kernel to send SIGHUP to the subprocess.
252 If the subprocess doesn't catch the SIGHUP, then it will die
255 WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP
257 This case should not necessarily be considered an error.
261 This is how code should check for and print errors from C<mexp_close>:
263 status = mexp_close (h);
265 perror ("mexp_close");
268 if (WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP)
269 goto ignore; /* not an error */
270 if (!WIFEXITED (status) || WEXITSTATUS (status) != 0)
271 /* You could use the W* macros to print a better error message. */
272 fprintf (stderr, "error: subprocess failed, status = %d", status);
278 =head1 EXPECT FUNCTION
280 Miniexpect contains a powerful regular expression matching function
283 B<int mexp_expect (mexp_h *h, const mexp_regexp *regexps,
284 int *ovector, int ovecsize);>
286 The output of the subprocess is matched against the list of PCRE
287 regular expressions in C<regexps>. C<regexps> is a list of regular
288 expression structures:
293 const pcre_extra *extra;
296 typedef struct mexp_regexp mexp_regexp;
298 C<r> is the integer code returned from C<mexp_expect> if this regular
299 expression matches. It B<must> be E<gt> 0. C<r == 0> indicates the
300 end of the list of regular expressions. C<re> is the compiled regular
303 Possible return values are:
307 =item C<MEXP_TIMEOUT>
309 No input matched before the timeout (C<h-E<gt>timeout>) was
314 The subprocess closed the connection.
318 There was a system call error (eg. from the read call). The error is
319 returned in C<errno>.
321 =item C<MEXP_PCRE_ERROR>
323 There was a C<pcre_exec> error. C<h-E<gt>pcre_error> is set to the
324 error code. See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
329 If any regexp matches, the associated integer code (C<regexps[].r>)
340 C<regexps> may be NULL or an empty list, which means we don't match
341 against a regular expression. This is useful if you just want to wait
346 C<regexps[].re>, C<regexps[].extra>, C<regexps[].options>, C<ovector>
347 and C<ovecsize> are passed through to the L<pcre_exec(3)> function.
351 If multiple regular expressions are passed, then they are checked in
352 turn and the I<first> regular expression that matches is returned
353 I<even if the match happens later in the input than another regular
356 For example if the input is C<"hello world"> and you pass the two
359 regexps[0].re = world
360 regexps[1].re = hello
362 then the first regular expression (C<"world">) may match and the
363 C<"hello"> part of the input may be ignored.
365 In some cases this can even lead to unpredictable matching. In the
366 case above, if we only happened to read C<"hello wor">, then the
367 second regular expression (C<"hello">) I<would> match.
369 If this is a concern, combine your regular expressions into a single
370 one, eg. C<(hello)|(world)>.
374 =head2 mexp_expect example
376 It is easier to understand C<mexp_expect> by considering a simple
379 In this example we are waiting for ssh to either send us a password
380 prompt, or (if no password was required) a command prompt, and based
381 on the output we will either send back a password or a command.
383 The unusual C<(mexp_regexp[]){...}> syntax is called a "compound
384 literal" and is available in C99. If you need to use an older
385 compiler, you can just use a local variable instead.
390 pcre *password_re, *prompt_re;
391 const int ovecsize = 12;
392 int ovector[ovecsize];
394 password_re = pcre_compile ("assword", 0, &errptr, &offset, NULL);
395 prompt_re = pcre_compile ("[$#] ", 0, &errptr, &offset, NULL);
397 switch (mexp_expect (h,
399 { 100, .re = password_re },
400 { 101, .re = prompt_re },
402 }, ovector, ovecsize)) {
404 /* here you would send a password */
407 /* here you would send a command */
410 fprintf (stderr, "error: ssh closed the connection unexpectedly\n");
413 fprintf (stderr, "error: timeout before reaching the prompt\n");
416 perror ("mexp_expect");
418 case MEXP_PCRE_ERROR:
419 fprintf (stderr, "error: PCRE error: %d\n", h->pcre_error);
423 =head1 SENDING COMMANDS TO THE SUBPROCESS
425 You can write to the subprocess simply by writing to C<h-E<gt>fd>.
426 However we also provide a convenience function:
428 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
430 B<int mexp_printf_password (mexp_h *h, const char *fs, ...);>
432 This returns the number of bytes, if the whole message was written OK.
433 If there was an error, -1 is returned and the error is available in
442 C<mexp_printf> will not do a partial write. If it cannot write all
443 the data, then it will return an error.
447 This function does not write a newline automatically. If you want to
448 send a command followed by a newline you have to do something like:
450 mexp_printf (h, "exit\n");
454 C<mexp_printf_password> works identically to C<mexp_printf> except
455 that the output is I<not> sent to the debugging file if debugging is
456 enabled. As the name suggests, use this for passwords so that they
457 don't appear in debugging output.
461 B<int mexp_send_interrupt (mexp_h *h);>
463 Send the interrupt character (C<^C>, Ctrl-C, C<\003>). This is like
464 pressing C<^C> - the subprocess (or remote process, if using C<ssh>)
465 is gracefully killed.
467 Note this only works if the pty is in cooked mode
468 (ie. C<MEXP_SPAWN_COOKED_MODE> was passed to C<mexp_spawnlf> or
469 C<mexp_spawnvf>). In raw mode, all characters are passed through
470 without any special interpretation.
474 Source is available from:
475 L<http://git.annexia.org/?p=miniexpect.git;a=summary>
487 Richard W.M. Jones (C<rjones at redhat dot com>)
491 The library is released under the Library GPL (LGPL) version 2 or at
492 your option any later version.
496 Copyright (C) 2014 Red Hat Inc.