2 * Copyright (C) 2014 Red Hat Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
26 /* This handle is created per subprocess that is spawned. */
28 int fd; /* File descriptor pointing to pty. */
29 pid_t pid; /* Subprocess PID. */
31 /* Timeout (milliseconds, 1/1000th seconds). The caller may set
32 * this before calling mexp_expect. Set it to -1 to mean no
33 * timeout. The default is 60000 (= 60 seconds).
37 /* The read buffer is allocated by the library when mexp_expect is
38 * called. It is available so you can examine the buffer to see
39 * what part of the regexp matched. Note this buffer does not
40 * contain the full input from the process, but it will contain at
41 * least the part matched by the regular expression (and maybe some
44 char *buffer; /* Read buffer. */
45 size_t len; /* Length of data in the buffer. */
46 size_t alloc; /* Allocated size of the buffer. */
48 /* The caller may set this to set the size (in bytes) for reads from
49 * the subprocess. The default is 1024.
53 /* Opaque pointers for use of the caller. The library will not
60 typedef struct mexp_h mexp_h;
62 /* Spawn a subprocess.
64 * If successful it returns a handle. If it fails, it returns NULL
67 extern mexp_h *mexp_spawnv (const char *file, char **argv);
69 /* Same as mexp_spawnv, but it uses a NULL-terminated variable length
72 extern mexp_h *mexp_spawnl (const char *file, const char *arg, ...);
74 /* Close the handle and clean up the subprocess.
77 * 0: successful close, subprocess exited cleanly.
78 * -1: error in system call, see errno.
79 * > 0: exit status of subprocess if it didn't exit cleanly. Use
80 * WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG etc macros to
85 * - Even in the error cases, the handle is always closed and
88 * - It is normal for the kernel to send SIGHUP to the subprocess.
89 * If the subprocess doesn't catch the SIGHUP, then it will die
90 * (WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP). This
91 * case should not necessarily be considered an error.
93 extern int mexp_close (mexp_h *h);
103 /* Expect some output from the subprocess. Match the output against
104 * the PCRE regular expression.
106 * 'code', 'extra', 'options', 'ovector' and 'ovecsize' are passed
107 * through to the pcre_exec function. See pcreapi(3).
109 * If you want to match multiple strings, you have to combine them
110 * into a single regexp, eg. "([Pp]assword)|([Ll]ogin)|([Ff]ailed)".
111 * Then examine ovector[2], ovector[4], ovector[6] to see if they
112 * contain '>= 0' or '-1'. See the pcreapi(3) man page for further
115 * 'code' may be NULL, which means we don't match against a regular
116 * expression. This is useful if you just want to wait for EOF or
122 * The input matched the regular expression. Use ovector
123 * to find out what matched in the buffer (mexp_h->buffer).
125 * No input matched before the timeout (mexp_h->timeout) was reached.
127 * The subprocess closed the connection.
129 * There was a system call error (eg. from the read call). See errno.
131 * There was a pcre_exec error. *pcre_ret is set to the error code
132 * (see pcreapi(3) for a list of PCRE_* error codes and what they mean).
134 extern enum mexp_status mexp_expect (mexp_h *h, const pcre *code,
135 const pcre_extra *extra,
136 int options, int *ovector, int ovecsize,
139 /* This is a convenience function for writing something (eg. a
140 * password or command) to the subprocess. You could do this by
141 * writing directly to 'h->fd', but this function does all the error
144 * Returns the number of bytes if the whole message was written OK
145 * (partial writes are not possible with this function), or -1 if
146 * there was an error (check errno).
148 extern int mexp_printf (mexp_h *h, const char *fs, ...)
149 __attribute__((format(printf,2,3)));
151 #endif /* MINIEXPECT_H_ */