5 miniexpect - A very simple expect library for C.
12 #include <miniexpect.h>
15 h = mexp_spawnl ("ssh", "ssh", "host");
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. Usually the first
64 argument should be the name of the program.
66 The return value is a handle (see next section).
68 If there was an error running the subprocess, C<NULL> is returned and
69 the error is available in C<errno>.
71 For example, to run an ssh subprocess you could do:
73 h = mexp_spawnl ("ssh", "ssh", "-l", "root", "host");
75 or to run a particular ssh binary:
77 h = mexp_spawnl ("/usr/local/bin/ssh", "ssh", "-l", "root", "host");
79 An alternative to C<mexp_spawnl> is:
81 B<mexp_h *mexp_spawnv (const char *file, char **argv);>
83 This is the same as C<mexp_spawnl> except that you pass the arguments
84 in a NULL-terminated array.
86 There are also two versions of the above calls which take flags:
88 B<mexp_h *mexp_spawnlf (unsigned flags, const char *file, const char *arg, ...);>
90 B<mexp_h *mexp_spawnvf (unsigned flags, const char *file, char **argv);>
92 The flags may contain the following values, logically ORed together:
96 =item C<MEXP_SPAWN_KEEP_SIGNALS>
98 Do not reset signal handlers to C<SIG_DFL> in the subprocess.
100 =item B<MEXP_SPAWN_KEEP_FDS>
102 Do not close file descriptors E<ge> 3 in the subprocess.
104 =item B<MEXP_SPAWN_COOKED_MODE> or B<MEXP_SPAWN_RAW_MODE>
106 Configure the pty in cooked mode or raw mode. Raw mode is the
113 After spawning a subprocess, you get back a handle which is a pointer
117 typedef struct mexp_h mexp_h;
119 Various methods can be used on the handle:
121 B<int mexp_get_fd (mexp_h *h);>
123 Return the file descriptor of the pty of the subprocess. You can read
124 and write to this if you want, although convenience functions are also
125 provided (see below).
127 B<pid_t mexp_get_pid (mexp_h *h);>
129 Return the process ID of the subprocess. You can send it signals if
132 B<int mexp_get_timeout_ms (mexp_h *h);>
134 B<void mexp_set_timeout_ms (mexp_h *h, int millisecs);>
136 B<void mexp_set_timeout (mexp_h *h, int secs);>
138 Get or set the timeout used by C<mexp_expect> [see below]. The
139 resolution is milliseconds (1/1000th of a second). Set this before
140 calling C<mexp_expect>. Passing -1 to either of the C<set_> methods
141 means no timeout. The default setting is 60000 milliseconds (60
144 B<size_t mexp_get_read_size (mexp *h);>
146 B<void mexp_set_read_size (mexp *h, size_t read_size);>
148 Get or set the natural size (in bytes) for reads from the subprocess.
149 The default is 1024. Most callers will not need to change this.
151 B<int mexp_get_pcre_error (mexp *h);>
153 When C<mexp_expect> [see below] calls the PCRE function
154 L<pcre_exec(3)>, it stashes the return value in the C<pcre_error>
155 field in the handle, and that field is returned by this method.
157 There are two uses for this:
163 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
164 error code returned by L<pcre_exec(3)> is available by calling this
165 method. For a list of PCRE error codes, see L<pcreapi(3)>.
169 A more unusual use is if you ever need to get the captured substrings
170 from your regular expression (calling L<pcre_get_substring(3)>). The
171 third parameter of that function (C<stringcount>) is the value
172 returned by L<pcre_exec(3)>, and so you can call it like this:
174 pcre_get_substring (h->buffer, ovector,
175 mexp_get_pcre_error (h), 1, &matched);
179 The following fields in the handle do not have methods, but can be
180 accessed directly instead:
186 If C<mexp_expect> returns a match then these variables contain the
187 read buffer. Note this buffer does not contain the full input from
188 the process, but it will contain at least the part matched by the
189 regular expression (and maybe some more). C<buffer> is the read
190 buffer and C<len> is the number of bytes of data in the buffer.
194 If C<mexp_expect> returns a match, then C<next_match> points to the
195 first byte in the buffer I<after> the fully matched expression. (It
196 may be C<-1> which means it is invalid). The next time that
197 C<mexp_expect> is called, it will start by consuming the data
198 C<buffer[next_match...len-1]>. Callers may also need to read from
199 that point in the buffer before calling L<read(2)> on the file
200 descriptor. Callers may also set this, for example setting it to
201 C<-1> in order to ignore the remainder of the buffer. In most cases
202 callers can ignore this field, and C<mexp_expect> will just do the
203 right thing when called repeatedly.
209 Opaque pointers for use by the caller. The library will not touch
212 =head1 CLOSING THE HANDLE
214 To close the handle and clean up the subprocess, call:
216 B<int mexp_close (mexp_h *h);>
218 This returns the status code from the subprocess. This is in the form
219 of a L<waitpid(2)>/L<system(3)> status so you have to use the macros
220 C<WIFEXITED>, C<WEXITSTATUS>, C<WIFSIGNALED>, C<WTERMSIG> etc defined
221 in C<E<lt>sys/wait.hE<gt>> to parse it.
223 If there was a system call error, then C<-1> is returned. The error
232 Even in error cases, the handle is always closed and its memory is
237 It is normal for the kernel to send SIGHUP to the subprocess.
239 If the subprocess doesn't catch the SIGHUP, then it will die
242 WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP
244 This case should not necessarily be considered an error.
248 This is how code should check for and print errors from C<mexp_close>:
250 status = mexp_close (h);
252 perror ("mexp_close");
255 if (WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP)
256 goto ignore; /* not an error */
257 if (!WIFEXITED (status) || WEXITSTATUS (status) != 0)
258 /* You could use the W* macros to print a better error message. */
259 fprintf (stderr, "error: subprocess failed, status = %d", status);
265 =head1 EXPECT FUNCTION
267 Miniexpect contains a powerful regular expression matching function
270 B<int mexp_expect (mexp_h *h, const mexp_regexp *regexps,
271 int *ovector, int ovecsize);>
273 The output of the subprocess is matched against the list of PCRE
274 regular expressions in C<regexps>. C<regexps> is a list of regular
275 expression structures:
280 const pcre_extra *extra;
283 typedef struct mexp_regexp mexp_regexp;
285 C<r> is the integer code returned from C<mexp_expect> if this regular
286 expression matches. It B<must> be E<gt> 0. C<r == 0> indicates the
287 end of the list of regular expressions. C<re> is the compiled regular
290 Possible return values are:
294 =item C<MEXP_TIMEOUT>
296 No input matched before the timeout (C<h-E<gt>timeout>) was
301 The subprocess closed the connection.
305 There was a system call error (eg. from the read call). The error is
306 returned in C<errno>.
308 =item C<MEXP_PCRE_ERROR>
310 There was a C<pcre_exec> error. C<h-E<gt>pcre_error> is set to the
311 error code. See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
316 If any regexp matches, the associated integer code (C<regexps[].r>)
327 C<regexps> may be NULL or an empty list, which means we don't match
328 against a regular expression. This is useful if you just want to wait
333 C<regexps[].re>, C<regexps[].extra>, C<regexps[].options>, C<ovector>
334 and C<ovecsize> are passed through to the L<pcre_exec(3)> function.
338 If multiple regular expressions are passed, then they are checked in
339 turn and the I<first> regular expression that matches is returned
340 I<even if the match happens later in the input than another regular
343 For example if the input is C<"hello world"> and you pass the two
346 regexps[0].re = world
347 regexps[1].re = hello
349 then the first regular expression (C<"world">) may match and the
350 C<"hello"> part of the input may be ignored.
352 In some cases this can even lead to unpredictable matching. In the
353 case above, if we only happened to read C<"hello wor">, then the
354 second regular expression (C<"hello">) I<would> match.
356 If this is a concern, combine your regular expressions into a single
357 one, eg. C<(hello)|(world)>.
361 =head2 mexp_expect example
363 It is easier to understand C<mexp_expect> by considering a simple
366 In this example we are waiting for ssh to either send us a password
367 prompt, or (if no password was required) a command prompt, and based
368 on the output we will either send back a password or a command.
370 The unusual C<(mexp_regexp[]){...}> syntax is called a "compound
371 literal" and is available in C99. If you need to use an older
372 compiler, you can just use a local variable instead.
377 pcre *password_re, *prompt_re;
378 const int ovecsize = 12;
379 int ovector[ovecsize];
381 password_re = pcre_compile ("assword", 0, &errptr, &offset, NULL);
382 prompt_re = pcre_compile ("[$#] ", 0, &errptr, &offset, NULL);
384 switch (mexp_expect (h,
386 { 100, .re = password_re },
387 { 101, .re = prompt_re },
389 }, ovector, ovecsize)) {
391 /* here you would send a password */
394 /* here you would send a command */
397 fprintf (stderr, "error: ssh closed the connection unexpectedly\n");
400 fprintf (stderr, "error: timeout before reaching the prompt\n");
403 perror ("mexp_expect");
405 case MEXP_PCRE_ERROR:
406 fprintf (stderr, "error: PCRE error: %d\n", h->pcre_error);
410 =head1 SENDING COMMANDS TO THE SUBPROCESS
412 You can write to the subprocess simply by writing to C<h-E<gt>fd>.
413 However we also provide a convenience function:
415 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
417 This returns the number of bytes, if the whole message was written OK.
418 If there was an error, -1 is returned and the error is available in
427 C<mexp_printf> will not do a partial write. If it cannot write all
428 the data, then it will return an error.
432 This function does not write a newline automatically. If you want to
433 send a command followed by a newline you have to do something like:
435 mexp_printf (h, "exit\n");
439 B<int mexp_send_interrupt (mexp_h *h);>
441 Send the interrupt character (C<^C>, Ctrl-C, C<\003>). This is like
442 pressing C<^C> - the subprocess (or remote process, if using C<ssh>)
443 is gracefully killed.
445 Note this only works if the pty is in cooked mode
446 (ie. C<MEXP_SPAWN_COOKED_MODE> was passed to C<mexp_spawnlf> or
447 C<mexp_spawnvf>). In raw mode, all characters are passed through
448 without any special interpretation.
452 Source is available from:
453 L<http://git.annexia.org/?p=miniexpect.git;a=summary>
465 Richard W.M. Jones (C<rjones at redhat dot com>)
469 The library is released under the Library GPL (LGPL) version 2 or at
470 your option any later version.
474 Copyright (C) 2014 Red Hat Inc.