5 miniexpect - A very simple expect library
11 #define PCRE2_CODE_UNIT_WIDTH 8
13 #include <miniexpect.h>
16 h = mexp_spawnl ("ssh", "ssh", "host", NULL);
17 switch (mexp_expect (h, regexps, match_data)) {
22 cc prog.c -o prog -lminiexpect -lpcre2-8
26 Miniexpect is a very simple expect-like library for C. Expect is a
27 way to control an external program that wants to be run interactively.
29 Miniexpect has a saner interface than libexpect, and doesn't depend on
30 Tcl. It is also thread safe, const-correct and uses modern C
33 Miniexpect is a standalone library, except for a single dependency: it
34 requires the PCRE2 (Perl Compatible Regular Expressions) library from
35 L<http://www.pcre.org/>. The PCRE2 dependency is fundamental because
36 we want to offer the most powerful regular expression syntax to match
37 on, but more importantly because PCRE2 has a convenient way to detect
38 partial matches which made this library very simple to implement.
40 This manual page documents the API. Examples of how to use the API
41 can be found in the source directory.
45 Miniexpect lets you start up an external program, control it (by
46 sending commands to it), and close it down gracefully. Two things
47 make this different from other APIs like L<popen(3)> and L<system(3)>:
48 Firstly miniexpect creates a pseudoterminal (pty). Secondly
49 miniexpect lets you match the output of the program using regular
50 expressions. Both of these are handy for controlling interactive
51 programs that might (for example) ask for passwords, but you can use
52 miniexpect on just about any external program.
54 You can control multiple programs at the same time.
56 =head1 SPAWNING THE SUBPROCESS
58 There are four calls for creating a subprocess:
60 B<mexp_h *mexp_spawnl (const char *file, const char *arg, ...);>
62 This creates a subprocess running the external program C<file> (the
63 current C<$PATH> is searched unless you give an absolute path).
64 C<arg, ...> are the arguments to the program. You should terminate
65 the list of arguments with C<NULL>. Usually the first argument should
66 be the name of the program.
68 The return value is a handle (see next section).
70 If there was an error running the subprocess, C<NULL> is returned and
71 the error is available in C<errno>.
73 For example, to run an ssh subprocess you could do:
75 h = mexp_spawnl ("ssh", "ssh", "-l", "root", "host", NULL);
77 or to run a particular ssh binary:
79 h = mexp_spawnl ("/usr/local/bin/ssh", "ssh", "-l", "root", "host", NULL);
81 An alternative to C<mexp_spawnl> is:
83 B<mexp_h *mexp_spawnv (const char *file, char **argv);>
85 This is the same as C<mexp_spawnl> except that you pass the arguments
86 in a NULL-terminated array.
88 There are also two versions of the above calls which take flags:
90 B<mexp_h *mexp_spawnlf (unsigned flags, const char *file, const char *arg, ...);>
92 B<mexp_h *mexp_spawnvf (unsigned flags, const char *file, char **argv);>
94 The flags may contain the following values, logically ORed together:
98 =item B<MEXP_SPAWN_KEEP_SIGNALS>
100 Do not reset signal handlers to C<SIG_DFL> in the subprocess.
102 =item B<MEXP_SPAWN_KEEP_FDS>
104 Do not close file descriptors E<ge> 3 in the subprocess.
106 =item B<MEXP_SPAWN_COOKED_MODE> or B<MEXP_SPAWN_RAW_MODE>
108 Configure the pty in cooked mode or raw mode. Raw mode is the
115 After spawning a subprocess, you get back a handle which is a pointer
119 typedef struct mexp_h mexp_h;
121 Various methods can be used on the handle:
123 B<int mexp_get_fd (mexp_h *h);>
125 Return the file descriptor of the pty of the subprocess. You can read
126 and write to this if you want, although convenience functions are also
127 provided (see below).
129 B<pid_t mexp_get_pid (mexp_h *h);>
131 Return the process ID of the subprocess. You can send it signals if
134 B<int mexp_get_timeout_ms (mexp_h *h);>
136 B<void mexp_set_timeout_ms (mexp_h *h, int millisecs);>
138 B<void mexp_set_timeout (mexp_h *h, int secs);>
140 Get or set the timeout used by C<mexp_expect> [see below]. The
141 resolution is milliseconds (1/1000th of a second). Set this before
142 calling C<mexp_expect>. Passing -1 to either of the C<set_> methods
143 means no timeout. The default setting is 60000 milliseconds (60
146 B<size_t mexp_get_read_size (mexp *h);>
148 B<void mexp_set_read_size (mexp *h, size_t read_size);>
150 Get or set the natural size (in bytes) for reads from the subprocess.
151 The default is 1024. Most callers will not need to change this.
153 B<int mexp_get_pcre_error (mexp *h);>
155 When C<mexp_expect> [see below] calls the PCRE function
156 L<pcre2_match(3)>, it stashes the return value in the C<pcre_error>
157 field in the handle, and that field is returned by this method.
159 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
160 error code returned by L<pcre2_match(3)> is available by calling this
161 method. For a list of PCRE error codes, see L<pcre2api(3)>.
163 B<void mexp_set_debug_file (mexp *h, FILE *fp);>
165 B<FILE *mexp_get_debug_file (mexp *h);>
167 Set or get the debug file of the handle. To enable debugging, pass a
168 non-C<NULL> file handle, eg. C<stderr>. To disable debugging, pass
169 C<NULL>. Debugging messages are printed on the file handle.
171 Note that all output and input gets printed, including passwords. To
172 prevent passwords from being printed, modify your code to call
173 C<mexp_printf_password> instead of C<mexp_printf>.
175 The following fields in the handle do not have methods, but can be
176 accessed directly instead:
182 If C<mexp_expect> returns a match then these variables contain the
183 read buffer. Note this buffer does not contain the full input from
184 the process, but it will contain at least the part matched by the
185 regular expression (and maybe some more). C<buffer> is the read
186 buffer and C<len> is the number of bytes of data in the buffer.
190 If C<mexp_expect> returns a match, then C<next_match> points to the
191 first byte in the buffer I<after> the fully matched expression. (It
192 may be C<-1> which means it is invalid). The next time that
193 C<mexp_expect> is called, it will start by consuming the data
194 C<buffer[next_match...len-1]>. Callers may also need to read from
195 that point in the buffer before calling L<read(2)> on the file
196 descriptor. Callers may also set this, for example setting it to
197 C<-1> in order to ignore the remainder of the buffer. In most cases
198 callers can ignore this field, and C<mexp_expect> will just do the
199 right thing when called repeatedly.
205 Opaque pointers for use by the caller. The library will not touch
208 =head1 CLOSING THE HANDLE
210 To close the handle and clean up the subprocess, call:
212 B<int mexp_close (mexp_h *h);>
214 This returns the status code from the subprocess. This is in the form
215 of a L<waitpid(2)>/L<system(3)> status so you have to use the macros
216 C<WIFEXITED>, C<WEXITSTATUS>, C<WIFSIGNALED>, C<WTERMSIG> etc defined
217 in C<E<lt>sys/wait.hE<gt>> to parse it.
219 If there was a system call error, then C<-1> is returned. The error
228 Even in error cases, the handle is always closed and its memory is
233 It is normal for the kernel to send SIGHUP to the subprocess.
235 If the subprocess doesn't catch the SIGHUP, then it will die
238 WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP
240 This case should not necessarily be considered an error.
244 This is how code should check for and print errors from C<mexp_close>:
246 status = mexp_close (h);
248 perror ("mexp_close");
251 if (WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP)
252 goto ignore; /* not an error */
253 if (!WIFEXITED (status) || WEXITSTATUS (status) != 0)
254 /* You could use the W* macros to print a better error message. */
255 fprintf (stderr, "error: subprocess failed, status = %d", status);
261 =head1 EXPECT FUNCTION
263 Miniexpect contains a powerful regular expression matching function
264 based on L<pcre2(3)>:
266 B<int mexp_expect (mexp_h *h, const mexp_regexp *regexps,
267 pcre2_match_data *match_data);>
269 The output of the subprocess is matched against the list of PCRE
270 regular expressions in C<regexps>. C<regexps> is a list of regular
271 expression structures:
275 const pcre2_code *re;
278 typedef struct mexp_regexp mexp_regexp;
280 C<r> is the integer code returned from C<mexp_expect> if this regular
281 expression matches. It B<must> be E<gt> 0. C<r == 0> indicates the
282 end of the list of regular expressions. C<re> is the compiled regular
285 Possible return values are:
289 =item C<MEXP_TIMEOUT>
291 No input matched before the timeout (C<h-E<gt>timeout>) was
296 The subprocess closed the connection.
300 There was a system call error (eg. from the read call). The error is
301 returned in C<errno>.
303 =item C<MEXP_PCRE_ERROR>
305 There was a C<pcre2_match> error. C<h-E<gt>pcre_error> is set to the
306 error code. See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
311 If any regexp matches, the associated integer code (C<regexps[].r>)
322 C<regexps> may be NULL or an empty list, which means we don't match
323 against a regular expression. This is useful if you just want to wait
328 C<regexps[].re>, C<regexps[].options> and C<match_data> are passed
329 through to the L<pcre2_match(3)> function.
333 If multiple regular expressions are passed, then they are checked in
334 turn and the I<first> regular expression that matches is returned
335 I<even if the match happens later in the input than another regular
338 For example if the input is C<"hello world"> and you pass the two
341 regexps[0].re = world
342 regexps[1].re = hello
344 then the first regular expression (C<"world">) may match and the
345 C<"hello"> part of the input may be ignored.
347 In some cases this can even lead to unpredictable matching. In the
348 case above, if we only happened to read C<"hello wor">, then the
349 second regular expression (C<"hello">) I<would> match.
351 If this is a concern, combine your regular expressions into a single
352 one, eg. C<(hello)|(world)>.
356 =head2 mexp_expect example
358 It is easier to understand C<mexp_expect> by considering a simple
361 In this example we are waiting for ssh to either send us a password
362 prompt, or (if no password was required) a command prompt, and based
363 on the output we will either send back a password or a command.
365 The unusual C<(mexp_regexp[]){...}> syntax is called a "compound
366 literal" and is available in C99. If you need to use an older
367 compiler, you can just use a local variable instead.
372 pcre2_code *password_re, *prompt_re;
373 pcre2_match_data *match_data = pcre2_match_data_create (4, NULL);
375 password_re = pcre2_compile ("assword", PCRE2_ZERO_TERMINATED,
376 0, &errcode, &offset, NULL);
377 prompt_re = pcre2_compile ("[$#] ", PCRE2_ZERO_TERMINATED,
378 0, &errcode, &offset, NULL);
380 switch (mexp_expect (h,
382 { 100, .re = password_re },
383 { 101, .re = prompt_re },
387 /* server printed a password prompt, so send a password */
388 mexp_printf_password (h, "%s", password);
391 /* server sent a shell prompt, send a command */
392 mexp_printf (h, "ls\n");
395 fprintf (stderr, "error: ssh closed the connection unexpectedly\n");
398 fprintf (stderr, "error: timeout before reaching the prompt\n");
401 perror ("mexp_expect");
403 case MEXP_PCRE_ERROR:
404 fprintf (stderr, "error: PCRE error: %d\n", h->pcre_error);
408 =head1 SENDING COMMANDS TO THE SUBPROCESS
410 You can write to the subprocess simply by writing to C<h-E<gt>fd>.
411 However we also provide a convenience function:
413 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
415 B<int mexp_printf_password (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 C<mexp_printf_password> works identically to C<mexp_printf> except
440 that the output is I<not> sent to the debugging file if debugging is
441 enabled. As the name suggests, use this for passwords so that they
442 don't appear in debugging output.
446 B<int mexp_send_interrupt (mexp_h *h);>
448 Send the interrupt character (C<^C>, Ctrl-C, C<\003>). This is like
449 pressing C<^C> - the subprocess (or remote process, if using C<ssh>)
450 is gracefully killed.
452 Note this only works if the pty is in cooked mode
453 (ie. C<MEXP_SPAWN_COOKED_MODE> was passed to C<mexp_spawnlf> or
454 C<mexp_spawnvf>). In raw mode, all characters are passed through
455 without any special interpretation.
459 Source is available from:
460 L<http://git.annexia.org/?p=miniexpect.git;a=summary>
472 Richard W.M. Jones (C<rjones at redhat dot com>)
476 The library is released under the Library GPL (LGPL) version 2 or at
477 your option any later version.
481 Copyright (C) 2014-2022 Red Hat Inc.