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
25 miniexpect is a very simple expect-like library for C.
27 It has a saner interface than libexpect, and doesn't depend on Tcl.
28 It is also thread safe, const-correct and uses modern C standards.
30 It is standalone, except that it requires the PCRE (Perl Compatible
31 Regular Expressions) library from http://www.pcre.org/. The PCRE
32 dependency is fundamental because we want to offer the most powerful
33 regular expression syntax to match on, but more importantly because
34 PCRE has a convenient way to detect partial matches which made this
35 library very simple to implement.
37 This manual page documents the API. Examples of how to use the API
38 can be found in the source directory.
42 Miniexpect lets you start up an external program, control it (by
43 sending commands to it), and close it down gracefully. Two things
44 make this different from other APIs like L<popen(3)> and L<system(3)>:
45 Firstly miniexpect creates a pseudoterminal (pty). Secondly
46 miniexpect lets you match the output of the program using regular
47 expressions. Both of these are handy for controlling interactive
48 programs that might (for example) ask for passwords, but you can use
49 miniexpect on just about any external program.
51 You can control multiple programs at the same time.
53 =head1 SPAWNING THE SUBPROCESS
55 There are two calls for creating a subprocess:
57 B<mexp_h *mexp_spawnl (const char *file, const char *arg, ...);>
59 This creates a subprocess running the external program C<file> (the
60 current C<$PATH> is searched unless you give an absolute path).
61 C<arg, ...> are the arguments to the program. Usually the first
62 argument should be the name of the program.
64 The return value is a handle (see next section).
66 If there was an error running the subprocess, C<NULL> is returned and
67 the error is available in C<errno>.
69 For example, to run an ssh subprocess you could do:
71 h = mexp_spawnl ("ssh", "ssh", "-l", "root", "host");
73 or to run a particular ssh binary:
75 h = mexp_spawnl ("/usr/local/bin/ssh", "ssh", "-l", "root", "host");
77 An alternative to C<mexp_spawnl> is:
79 B<mexp_h *mexp_spawnv (const char *file, char **argv);>
81 This is the same as C<mexp_spawnl> except that you pass the arguments
82 in a NULL-terminated array.
86 After spawning a subprocess, you get back a handle. There are various
87 fields in this handle which you can read or write:
93 C<fd> is the pty of the subprocess. You can read and write to this if
94 you want, although convenience functions are also provided (see
95 below). C<pid> is the process ID of the subprocess. You can send it
100 C<timeout> is the timeout in milliseconds (1/1000th of a second) used
101 by C<mexp_expect> (see below). You can set this before calling
102 C<mexp_expect> if you want. Setting it to -1 means no timeout. The
103 default setting is 60000 (60 seconds).
109 If C<mexp_expect> returns a match then these variables contain the
110 read buffer. Note this buffer does not contain the full input from
111 the process, but it will contain at least the part matched by the
112 regular expression (and maybe some more). C<buffer> is the read
113 buffer and C<len> is the number of bytes of data in the buffer.
117 Callers may set this to the natural size (in bytes) for reads from the
118 subprocess. The default is 1024. Most callers will not need to
123 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
124 error code returned by L<pcre_exec(3)> is available here. For a list
125 of PCRE error codes, see L<pcreapi(3)>.
131 Opaque pointers for use by the caller. The library will not touch
136 typedef struct mexp_h mexp_h;
138 =head1 CLOSING THE HANDLE
140 To close the handle and clean up the subprocess, call:
142 B<int mexp_close (mexp_h *h);>
144 This returns the status code from the subprocess. This is in the form
145 of a L<waitpid(2)>/L<system(3)> status so you have to use the macros
146 C<WIFEXITED>, C<WEXITSTATUS>, C<WIFSIGNALED>, C<WTERMSIG> etc defined
147 in C<E<lt>sys/wait.hE<gt>> to parse it.
149 If there was a system call error, then C<-1> is returned. The error
158 Even in error cases, the handle is always closed and its memory is
163 It is normal for the kernel to send SIGHUP to the subprocess.
165 If the subprocess doesn't catch the SIGHUP, then it will die
168 WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP
170 This case should not necessarily be considered an error.
174 =head1 EXPECT FUNCTION
176 Miniexpect contains a powerful regular expression matching function
179 B<int mexp_expect (mexp_h *h, const mexp_regexp *regexps,
180 int *ovector, int ovecsize);>
182 The output of the subprocess is matched against the list of PCRE
183 regular expressions in C<regexps>. C<regexps> is a list of regular
184 expression structures:
189 const pcre_extra *extra;
192 typedef struct mexp_regexp mexp_regexp;
194 C<r> is the integer code returned from C<mexp_expect> if this regular
195 expression matches. It B<must> be E<gt> 0. C<r == 0> indicates the
196 end of the list of regular expressions. C<re> is the compiled regular
199 Possible return values are:
203 =item C<MEXP_TIMEOUT>
205 No input matched before the timeout (C<h-E<gt>timeout>) was
210 The subprocess closed the connection.
214 There was a system call error (eg. from the read call). The error is
215 returned in C<errno>.
217 =item C<MEXP_PCRE_ERROR>
219 There was a C<pcre_exec> error. C<h-E<gt>pcre_error> is set to the
220 error code. See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
225 If any regexp matches, the associated integer code (C<regexps[].r>)
236 C<regexps> may be NULL or an empty list, which means we don't match
237 against a regular expression. This is useful if you just want to wait
242 C<regexps[].re>, C<regexps[].extra>, C<regexps[].options>, C<ovector>
243 and C<ovecsize> are passed through to the L<pcre_exec(3)> function.
247 =head2 mexp_expect example
249 It is easier to understand C<mexp_expect> by considering a simple
252 In this example we are waiting for ssh to either send us a password
253 prompt, or (if no password was required) a command prompt, and based
254 on the output we will either send back a password or a command.
256 The unusual C<(mexp_regexp[]){...}> syntax is called a "compound
257 literal" and is available in C99. If you need to use an older
258 compiler, you can just use a local variable instead.
263 pcre *password_re, *prompt_re;
265 int ovector[ovecsize];
267 password_re = pcre_compile ("assword", 0, &errptr, &offset, NULL);
268 prompt_re = pcre_compile ("[$#] ", 0, &errptr, &offset, NULL);
270 switch (mexp_expect (h,
272 { 100, .re = password_re },
273 { 101, .re = prompt_re },
275 }, ovector, ovecsize)) {
277 /* here you would send a password */
280 /* here you would send a command */
283 fprintf (stderr, "error: ssh closed the connection unexpectedly\n");
286 fprintf (stderr, "error: timeout before reaching the prompt\n");
289 perror ("mexp_expect");
291 case MEXP_PCRE_ERROR:
292 fprintf (stderr, "error: PCRE error: %d\n", h->pcre_error);
296 =head1 SENDING COMMANDS TO THE SUBPROCESS
298 You can write to the subprocess simply by writing to C<h-E<gt>fd>.
299 However we also provide a convenience function:
301 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
303 This returns the number of bytes, if the whole message was written OK.
304 If there was an error, -1 is returned and the error is available in
305 C<errno>. Note that this function will not do a partial write. If it
306 cannot write all the data, then it will return an error.
310 Source is available from:
311 L<http://git.annexia.org/?p=miniexpect.git;a=summary>
323 Richard W.M. Jones (C<rjones at redhat dot com>)
327 The library is released under the Library GPL (LGPL) version 2 or at
328 your option any later version.
332 Copyright (C) 2014 Red Hat Inc.