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 which is a pointer
92 typedef struct mexp_h mexp_h;
94 Various methods can be used on the handle:
96 B<int mexp_get_fd (mexp_h *h);>
98 Return the file descriptor of the pty of the subprocess. You can read
99 and write to this if you want, although convenience functions are also
100 provided (see below).
102 B<pid_t mexp_get_pid (mexp_h *h);>
104 Return the process ID of the subprocess. You can send it signals if
107 B<int mexp_get_timeout_ms (mexp_h *h);>
109 B<void mexp_set_timeout_ms (mexp_h *h, int millisecs);>
111 B<void mexp_set_timeout (mexp_h *h, int secs);>
113 Get or set the timeout used by C<mexp_expect> [see below]. The
114 resolution is milliseconds (1/1000th of a second). Set this before
115 calling C<mexp_expect>. Passing -1 to either of the C<set_> methods
116 means no timeout. The default setting is 60000 milliseconds (60
119 B<size_t mexp_get_read_size (mexp *h);>
121 B<void mexp_set_read_size (mexp *h, size_t read_size);>
123 Get or set the natural size (in bytes) for reads from the subprocess.
124 The default is 1024. Most callers will not need to change this.
126 B<int mexp_get_pcre_error (mexp *h);>
128 When C<mexp_expect> [see below] calls the PCRE function
129 L<pcre_exec(3)>, it stashes the return value in the C<pcre_error>
130 field in the handle, and that field is returned by this method.
132 There are two uses for this:
138 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
139 error code returned by L<pcre_exec(3)> is available by calling this
140 method. For a list of PCRE error codes, see L<pcreapi(3)>.
144 A more unusual use is if you ever need to get the captured substrings
145 from your regular expression (calling L<pcre_get_substring(3)>). The
146 third parameter of that function (C<stringcount>) is the value
147 returned by L<pcre_exec(3)>, and so you can call it like this:
149 pcre_get_substring (h->buffer, ovector,
150 mexp_get_pcre_error (h), 1, &matched);
154 The following fields in the handle do not have methods, but can be
155 accessed directly instead:
161 If C<mexp_expect> returns a match then these variables contain the
162 read buffer. Note this buffer does not contain the full input from
163 the process, but it will contain at least the part matched by the
164 regular expression (and maybe some more). C<buffer> is the read
165 buffer and C<len> is the number of bytes of data in the buffer.
169 If C<mexp_expect> returns a match, then C<next_match> points to the
170 first byte in the buffer I<after> the fully matched expression. (It
171 may be C<-1> which means it is invalid). The next time that
172 C<mexp_expect> is called, it will start by consuming the data
173 C<buffer[next_match...len-1]>. Callers may also need to read from
174 that point in the buffer before calling L<read(2)> on the file
175 descriptor. Callers may also set this, for example setting it to
176 C<-1> in order to ignore the remainder of the buffer. In most cases
177 callers can ignore this field, and C<mexp_expect> will just do the
178 right thing when called repeatedly.
184 Opaque pointers for use by the caller. The library will not touch
187 =head1 CLOSING THE HANDLE
189 To close the handle and clean up the subprocess, call:
191 B<int mexp_close (mexp_h *h);>
193 This returns the status code from the subprocess. This is in the form
194 of a L<waitpid(2)>/L<system(3)> status so you have to use the macros
195 C<WIFEXITED>, C<WEXITSTATUS>, C<WIFSIGNALED>, C<WTERMSIG> etc defined
196 in C<E<lt>sys/wait.hE<gt>> to parse it.
198 If there was a system call error, then C<-1> is returned. The error
207 Even in error cases, the handle is always closed and its memory is
212 It is normal for the kernel to send SIGHUP to the subprocess.
214 If the subprocess doesn't catch the SIGHUP, then it will die
217 WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP
219 This case should not necessarily be considered an error.
223 This is how code should check for and print errors from C<mexp_close>:
225 status = mexp_close (h);
227 perror ("mexp_close");
230 if (WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP)
231 goto ignore; /* not an error */
232 if (!WIFEXITED (status) || WEXITSTATUS (status) != 0)
233 /* You could use the W* macros to print a better error message. */
234 fprintf (stderr, "error: subprocess failed, status = %d", status);
240 =head1 EXPECT FUNCTION
242 Miniexpect contains a powerful regular expression matching function
245 B<int mexp_expect (mexp_h *h, const mexp_regexp *regexps,
246 int *ovector, int ovecsize);>
248 The output of the subprocess is matched against the list of PCRE
249 regular expressions in C<regexps>. C<regexps> is a list of regular
250 expression structures:
255 const pcre_extra *extra;
258 typedef struct mexp_regexp mexp_regexp;
260 C<r> is the integer code returned from C<mexp_expect> if this regular
261 expression matches. It B<must> be E<gt> 0. C<r == 0> indicates the
262 end of the list of regular expressions. C<re> is the compiled regular
265 Possible return values are:
269 =item C<MEXP_TIMEOUT>
271 No input matched before the timeout (C<h-E<gt>timeout>) was
276 The subprocess closed the connection.
280 There was a system call error (eg. from the read call). The error is
281 returned in C<errno>.
283 =item C<MEXP_PCRE_ERROR>
285 There was a C<pcre_exec> error. C<h-E<gt>pcre_error> is set to the
286 error code. See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
291 If any regexp matches, the associated integer code (C<regexps[].r>)
302 C<regexps> may be NULL or an empty list, which means we don't match
303 against a regular expression. This is useful if you just want to wait
308 C<regexps[].re>, C<regexps[].extra>, C<regexps[].options>, C<ovector>
309 and C<ovecsize> are passed through to the L<pcre_exec(3)> function.
313 If multiple regular expressions are passed, then they are checked in
314 turn and the I<first> regular expression that matches is returned
315 I<even if the match happens later in the input than another regular
318 For example if the input is C<"hello world"> and you pass the two
321 regexps[0].re = world
322 regexps[1].re = hello
324 then the first regular expression (C<"world">) may match and the
325 C<"hello"> part of the input may be ignored.
327 In some cases this can even lead to unpredictable matching. In the
328 case above, if we only happened to read C<"hello wor">, then the
329 second regular expression (C<"hello">) I<would> match.
331 If this is a concern, combine your regular expressions into a single
332 one, eg. C<(hello)|(world)>.
336 =head2 mexp_expect example
338 It is easier to understand C<mexp_expect> by considering a simple
341 In this example we are waiting for ssh to either send us a password
342 prompt, or (if no password was required) a command prompt, and based
343 on the output we will either send back a password or a command.
345 The unusual C<(mexp_regexp[]){...}> syntax is called a "compound
346 literal" and is available in C99. If you need to use an older
347 compiler, you can just use a local variable instead.
352 pcre *password_re, *prompt_re;
353 const int ovecsize = 12;
354 int ovector[ovecsize];
356 password_re = pcre_compile ("assword", 0, &errptr, &offset, NULL);
357 prompt_re = pcre_compile ("[$#] ", 0, &errptr, &offset, NULL);
359 switch (mexp_expect (h,
361 { 100, .re = password_re },
362 { 101, .re = prompt_re },
364 }, ovector, ovecsize)) {
366 /* here you would send a password */
369 /* here you would send a command */
372 fprintf (stderr, "error: ssh closed the connection unexpectedly\n");
375 fprintf (stderr, "error: timeout before reaching the prompt\n");
378 perror ("mexp_expect");
380 case MEXP_PCRE_ERROR:
381 fprintf (stderr, "error: PCRE error: %d\n", h->pcre_error);
385 =head1 SENDING COMMANDS TO THE SUBPROCESS
387 You can write to the subprocess simply by writing to C<h-E<gt>fd>.
388 However we also provide a convenience function:
390 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
392 This returns the number of bytes, if the whole message was written OK.
393 If there was an error, -1 is returned and the error is available in
402 C<mexp_printf> will not do a partial write. If it cannot write all
403 the data, then it will return an error.
407 This function does not write a newline automatically. If you want to
408 send a command followed by a newline you have to do something like:
410 mexp_printf (h, "exit\n");
416 Source is available from:
417 L<http://git.annexia.org/?p=miniexpect.git;a=summary>
429 Richard W.M. Jones (C<rjones at redhat dot com>)
433 The library is released under the Library GPL (LGPL) version 2 or at
434 your option any later version.
438 Copyright (C) 2014 Red Hat Inc.