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 two 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.
88 After spawning a subprocess, you get back a handle. There are various
89 fields in this handle which you can read or write:
95 C<fd> is the pty of the subprocess. You can read and write to this if
96 you want, although convenience functions are also provided (see
97 below). C<pid> is the process ID of the subprocess. You can send it
102 C<timeout> is the timeout in milliseconds (1/1000th of a second) used
103 by C<mexp_expect> (see below). You can set this before calling
104 C<mexp_expect> if you want. Setting it to -1 means no timeout. The
105 default setting is 60000 (60 seconds).
111 If C<mexp_expect> returns a match then these variables contain the
112 read buffer. Note this buffer does not contain the full input from
113 the process, but it will contain at least the part matched by the
114 regular expression (and maybe some more). C<buffer> is the read
115 buffer and C<len> is the number of bytes of data in the buffer.
119 Callers may set this to the natural size (in bytes) for reads from the
120 subprocess. The default is 1024. Most callers will not need to
125 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
126 error code returned by L<pcre_exec(3)> is available here. For a list
127 of PCRE error codes, see L<pcreapi(3)>.
133 Opaque pointers for use by the caller. The library will not touch
138 typedef struct mexp_h mexp_h;
140 =head1 CLOSING THE HANDLE
142 To close the handle and clean up the subprocess, call:
144 B<int mexp_close (mexp_h *h);>
146 This returns the status code from the subprocess. This is in the form
147 of a L<waitpid(2)>/L<system(3)> status so you have to use the macros
148 C<WIFEXITED>, C<WEXITSTATUS>, C<WIFSIGNALED>, C<WTERMSIG> etc defined
149 in C<E<lt>sys/wait.hE<gt>> to parse it.
151 If there was a system call error, then C<-1> is returned. The error
160 Even in error cases, the handle is always closed and its memory is
165 It is normal for the kernel to send SIGHUP to the subprocess.
167 If the subprocess doesn't catch the SIGHUP, then it will die
170 WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP
172 This case should not necessarily be considered an error.
176 =head1 EXPECT FUNCTION
178 Miniexpect contains a powerful regular expression matching function
181 B<int mexp_expect (mexp_h *h, const mexp_regexp *regexps,
182 int *ovector, int ovecsize);>
184 The output of the subprocess is matched against the list of PCRE
185 regular expressions in C<regexps>. C<regexps> is a list of regular
186 expression structures:
191 const pcre_extra *extra;
194 typedef struct mexp_regexp mexp_regexp;
196 C<r> is the integer code returned from C<mexp_expect> if this regular
197 expression matches. It B<must> be E<gt> 0. C<r == 0> indicates the
198 end of the list of regular expressions. C<re> is the compiled regular
201 Possible return values are:
205 =item C<MEXP_TIMEOUT>
207 No input matched before the timeout (C<h-E<gt>timeout>) was
212 The subprocess closed the connection.
216 There was a system call error (eg. from the read call). The error is
217 returned in C<errno>.
219 =item C<MEXP_PCRE_ERROR>
221 There was a C<pcre_exec> error. C<h-E<gt>pcre_error> is set to the
222 error code. See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
227 If any regexp matches, the associated integer code (C<regexps[].r>)
238 C<regexps> may be NULL or an empty list, which means we don't match
239 against a regular expression. This is useful if you just want to wait
244 C<regexps[].re>, C<regexps[].extra>, C<regexps[].options>, C<ovector>
245 and C<ovecsize> are passed through to the L<pcre_exec(3)> function.
249 =head2 mexp_expect example
251 It is easier to understand C<mexp_expect> by considering a simple
254 In this example we are waiting for ssh to either send us a password
255 prompt, or (if no password was required) a command prompt, and based
256 on the output we will either send back a password or a command.
258 The unusual C<(mexp_regexp[]){...}> syntax is called a "compound
259 literal" and is available in C99. If you need to use an older
260 compiler, you can just use a local variable instead.
265 pcre *password_re, *prompt_re;
266 const int ovecsize = 12;
267 int ovector[ovecsize];
269 password_re = pcre_compile ("assword", 0, &errptr, &offset, NULL);
270 prompt_re = pcre_compile ("[$#] ", 0, &errptr, &offset, NULL);
272 switch (mexp_expect (h,
274 { 100, .re = password_re },
275 { 101, .re = prompt_re },
277 }, ovector, ovecsize)) {
279 /* here you would send a password */
282 /* here you would send a command */
285 fprintf (stderr, "error: ssh closed the connection unexpectedly\n");
288 fprintf (stderr, "error: timeout before reaching the prompt\n");
291 perror ("mexp_expect");
293 case MEXP_PCRE_ERROR:
294 fprintf (stderr, "error: PCRE error: %d\n", h->pcre_error);
298 =head1 SENDING COMMANDS TO THE SUBPROCESS
300 You can write to the subprocess simply by writing to C<h-E<gt>fd>.
301 However we also provide a convenience function:
303 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
305 This returns the number of bytes, if the whole message was written OK.
306 If there was an error, -1 is returned and the error is available in
315 C<mexp_printf> will not do a partial write. If it cannot write all
316 the data, then it will return an error.
320 This function does not write a newline automatically. If you want to
321 send a command followed by a newline you have to do something like:
323 mexp_printf (h, "exit\n");
329 Source is available from:
330 L<http://git.annexia.org/?p=miniexpect.git;a=summary>
342 Richard W.M. Jones (C<rjones at redhat dot com>)
346 The library is released under the Library GPL (LGPL) version 2 or at
347 your option any later version.
351 Copyright (C) 2014 Red Hat Inc.