documentation: Fix markup in flags.

[miniexpect.git] / miniexpect.pod

diff --git a/miniexpect.pod b/miniexpect.pod
index e27a4cc..cd008fc 100644 (file)
--- a/miniexpect.pod
+++ b/miniexpect.pod
@@ -12,7 +12,7 @@ miniexpect - A very simple expect library for C.
  #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)) {
    ...
  }
@@ -54,14 +54,15 @@ You can control multiple programs at the same time.
 
 =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).
 
@@ -70,11 +71,11 @@ the error is available in C<errno>.
 
 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:
 
@@ -83,6 +84,31 @@ B<mexp_h *mexp_spawnv (const char *file, char **argv);>
 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 which is a pointer
@@ -110,7 +136,7 @@ B<void mexp_set_timeout_ms (mexp_h *h, int millisecs);>
 
 B<void mexp_set_timeout (mexp_h *h, int secs);>
 
-Get and set the timeout used by C<mexp_expect> [see below].  The
+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
@@ -411,6 +437,17 @@ send a command followed by a newline you have to do something like:
 
 =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: