#include <miniexpect.h>
mexp_h *h;
- h = mexp_spawnl ("ssh", "ssh", "host");
+ h = mexp_spawnl ("ssh", "ssh", "host", NULL);
switch (mexp_expect (h, regexps, ovector, ovecsize)) {
...
}
=head1 SPAWNING THE SUBPROCESS
-There are two calls for creating a subprocess:
+There are four calls for creating a subprocess:
B<mexp_h *mexp_spawnl (const char *file, const char *arg, ...);>
This creates a subprocess running the external program C<file> (the
current C<$PATH> is searched unless you give an absolute path).
-C<arg, ...> are the arguments to the program. Usually the first
-argument should be the name of the program.
+C<arg, ...> are the arguments to the program. You should terminate
+the list of arguments with C<NULL>. Usually the first argument should
+be the name of the program.
The return value is a handle (see next section).
For example, to run an ssh subprocess you could do:
- h = mexp_spawnl ("ssh", "ssh", "-l", "root", "host");
+ h = mexp_spawnl ("ssh", "ssh", "-l", "root", "host", NULL);
or to run a particular ssh binary:
- h = mexp_spawnl ("/usr/local/bin/ssh", "ssh", "-l", "root", "host");
+ h = mexp_spawnl ("/usr/local/bin/ssh", "ssh", "-l", "root", "host", NULL);
An alternative to C<mexp_spawnl> is:
This is the same as C<mexp_spawnl> except that you pass the arguments
in a NULL-terminated array.
+There are also two versions of the above calls which take flags:
+
+B<mexp_h *mexp_spawnlf (unsigned flags, const char *file, const char *arg, ...);>
+
+B<mexp_h *mexp_spawnvf (unsigned flags, const char *file, char **argv);>
+
+The flags may contain the following values, logically ORed together:
+
+=over 4
+
+=item B<MEXP_SPAWN_KEEP_SIGNALS>
+
+Do not reset signal handlers to C<SIG_DFL> in the subprocess.
+
+=item B<MEXP_SPAWN_KEEP_FDS>
+
+Do not close file descriptors E<ge> 3 in the subprocess.
+
+=item B<MEXP_SPAWN_COOKED_MODE> or B<MEXP_SPAWN_RAW_MODE>
+
+Configure the pty in cooked mode or raw mode. Raw mode is the
+default.
+
+=back
+
=head1 HANDLES
-After spawning a subprocess, you get back a handle. There are various
-fields in this handle which you can read or write:
+After spawning a subprocess, you get back a handle which is a pointer
+to a struct:
+
+ struct mexp_h;
+ typedef struct mexp_h mexp_h;
+
+Various methods can be used on the handle:
+
+B<int mexp_get_fd (mexp_h *h);>
+
+Return the file descriptor of the pty of the subprocess. You can read
+and write to this if you want, although convenience functions are also
+provided (see below).
+
+B<pid_t mexp_get_pid (mexp_h *h);>
+
+Return the process ID of the subprocess. You can send it signals if
+you want.
+
+B<int mexp_get_timeout_ms (mexp_h *h);>
+
+B<void mexp_set_timeout_ms (mexp_h *h, int millisecs);>
+
+B<void mexp_set_timeout (mexp_h *h, int secs);>
+
+Get or set the timeout used by C<mexp_expect> [see below]. The
+resolution is milliseconds (1/1000th of a second). Set this before
+calling C<mexp_expect>. Passing -1 to either of the C<set_> methods
+means no timeout. The default setting is 60000 milliseconds (60
+seconds).
+
+B<size_t mexp_get_read_size (mexp *h);>
- struct mexp_h {
- int fd;
- pid_t pid;
+B<void mexp_set_read_size (mexp *h, size_t read_size);>
-C<fd> is the pty of the subprocess. You can read and write to this if
-you want, although convenience functions are also provided (see
-below). C<pid> is the process ID of the subprocess. You can send it
-signals if you want.
+Get or set the natural size (in bytes) for reads from the subprocess.
+The default is 1024. Most callers will not need to change this.
- int timeout;
+B<int mexp_get_pcre_error (mexp *h);>
-C<timeout> is the timeout in milliseconds (1/1000th of a second) used
-by C<mexp_expect> (see below). You can set this before calling
-C<mexp_expect> if you want. Setting it to -1 means no timeout. The
-default setting is 60000 (60 seconds).
+When C<mexp_expect> [see below] calls the PCRE function
+L<pcre_exec(3)>, it stashes the return value in the C<pcre_error>
+field in the handle, and that field is returned by this method.
- char *buffer;
- size_t len;
- size_t alloc;
+There are two uses for this:
+
+=over 4
+
+=item 1.
+
+If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
+error code returned by L<pcre_exec(3)> is available by calling this
+method. For a list of PCRE error codes, see L<pcreapi(3)>.
+
+=item 2.
+
+A more unusual use is if you ever need to get the captured substrings
+from your regular expression (calling L<pcre_get_substring(3)>). The
+third parameter of that function (C<stringcount>) is the value
+returned by L<pcre_exec(3)>, and so you can call it like this:
+
+ pcre_get_substring (h->buffer, ovector,
+ mexp_get_pcre_error (h), 1, &matched);
+
+=back
+
+The following fields in the handle do not have methods, but can be
+accessed directly instead:
+
+ char *buffer;
+ size_t len;
+ size_t alloc;
If C<mexp_expect> returns a match then these variables contain the
read buffer. Note this buffer does not contain the full input from
regular expression (and maybe some more). C<buffer> is the read
buffer and C<len> is the number of bytes of data in the buffer.
- ssize_t next_match;
+ ssize_t next_match;
If C<mexp_expect> returns a match, then C<next_match> points to the
first byte in the buffer I<after> the fully matched expression. (It
callers can ignore this field, and C<mexp_expect> will just do the
right thing when called repeatedly.
- size_t read_size;
-
-Callers may set this to the natural size (in bytes) for reads from the
-subprocess. The default is 1024. Most callers will not need to
-change this.
-
- int pcre_error;
-
-If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
-error code returned by L<pcre_exec(3)> is available here. For a list
-of PCRE error codes, see L<pcreapi(3)>.
-
- void *user1;
- void *user2;
- void *user3;
+ void *user1;
+ void *user2;
+ void *user3;
Opaque pointers for use by the caller. The library will not touch
these.
- };
-
- typedef struct mexp_h mexp_h;
-
=head1 CLOSING THE HANDLE
To close the handle and clean up the subprocess, call:
=back
+This is how code should check for and print errors from C<mexp_close>:
+
+ status = mexp_close (h);
+ if (status == -1) {
+ perror ("mexp_close");
+ return -1;
+ }
+ if (WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP)
+ goto ignore; /* not an error */
+ if (!WIFEXITED (status) || WEXITSTATUS (status) != 0)
+ /* You could use the W* macros to print a better error message. */
+ fprintf (stderr, "error: subprocess failed, status = %d", status);
+ return -1;
+ }
+ ignore:
+ /* no error case */
+
=head1 EXPECT FUNCTION
Miniexpect contains a powerful regular expression matching function
=back
+B<int mexp_send_interrupt (mexp_h *h);>
+
+Send the interrupt character (C<^C>, Ctrl-C, C<\003>). This is like
+pressing C<^C> - the subprocess (or remote process, if using C<ssh>)
+is gracefully killed.
+
+Note this only works if the pty is in cooked mode
+(ie. C<MEXP_SPAWN_COOKED_MODE> was passed to C<mexp_spawnlf> or
+C<mexp_spawnvf>). In raw mode, all characters are passed through
+without any special interpretation.
+
=head1 SOURCE
Source is available from:
git.annexia.org / miniexpect.git / blobdiff