X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=miniexpect.pod;h=e93ff67ec24a1e949c973b44b857f010e5a7d614;hb=fcf73607913050d246dbcc4f39e7717d0960763f;hp=baca020bc55f5ae5145010c2ef607db44a544e84;hpb=3df4c0d3e4192cb6bb8e9ed7126346ab6aa98043;p=miniexpect.git

diff --git a/miniexpect.pod b/miniexpect.pod
index baca020..e93ff67 100644
--- a/miniexpect.pod
+++ b/miniexpect.pod
@@ -8,17 +8,18 @@ miniexpect - A very simple expect library for C.
 
  #include <errno.h>
  #include <sys/wait.h>
- #include <pcre.h>
+ #define PCRE2_CODE_UNIT_WIDTH 8
+ #include <pcre2.h>
  #include <miniexpect.h>
  
  mexp_h *h;
- h = mexp_spawnl ("ssh", "ssh", "host");
- switch (mexp_expect (h, regexps, ovector, ovecsize)) {
+ h = mexp_spawnl ("ssh", "ssh", "host", NULL);
+ switch (mexp_expect (h, regexps, match_data)) {
    ...
  }
  mexp_close (h);
 
- cc prog.c -o prog -lminiexpect -lpcre
+ cc prog.c -o prog -lminiexpect -lpcre2-8
 
 =head1 DESCRIPTION
 
@@ -30,10 +31,10 @@ Tcl.  It is also thread safe, const-correct and uses modern C
 standards.
 
 Miniexpect is a standalone library, except for a single dependency: it
-requires the PCRE (Perl Compatible Regular Expressions) library from
-L<http://www.pcre.org/>.  The PCRE dependency is fundamental because
+requires the PCRE2 (Perl Compatible Regular Expressions) library from
+L<http://www.pcre.org/>.  The PCRE2 dependency is fundamental because
 we want to offer the most powerful regular expression syntax to match
-on, but more importantly because PCRE has a convenient way to detect
+on, but more importantly because PCRE2 has a convenient way to detect
 partial matches which made this library very simple to implement.
 
 This manual page documents the API.  Examples of how to use the API
@@ -54,14 +55,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 +72,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 +85,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 +137,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
@@ -125,9 +152,25 @@ The default is 1024.  Most callers will not need to change this.
 
 B<int mexp_get_pcre_error (mexp *h);>
 
+When C<mexp_expect> [see below] calls the PCRE function
+L<pcre2_match(3)>, it stashes the return value in the C<pcre_error>
+field in the handle, and that field is returned by this method.
+
 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)>.
+error code returned by L<pcre2_match(3)> is available by calling this
+method.  For a list of PCRE error codes, see L<pcre2api(3)>.
+
+B<void mexp_set_debug_file (mexp *h, FILE *fp);>
+
+B<FILE *mexp_get_debug_file (mexp *h);>
+
+Set or get the debug file of the handle.  To enable debugging, pass a
+non-C<NULL> file handle, eg. C<stderr>.  To disable debugging, pass
+C<NULL>.  Debugging messages are printed on the file handle.
+
+Note that all output and input gets printed, including passwords.  To
+prevent passwords from being printed, modify your code to call
+C<mexp_printf_password> instead of C<mexp_printf>.
 
 The following fields in the handle do not have methods, but can be
 accessed directly instead:
@@ -218,10 +261,10 @@ This is how code should check for and print errors from C<mexp_close>:
 =head1 EXPECT FUNCTION
 
 Miniexpect contains a powerful regular expression matching function
-based on L<pcre(3)>:
+based on L<pcre2(3)>:
 
 B<int mexp_expect (mexp_h *h, const mexp_regexp *regexps,
-int *ovector, int ovecsize);>
+pcre2_match_data *match_data);>
 
 The output of the subprocess is matched against the list of PCRE
 regular expressions in C<regexps>.  C<regexps> is a list of regular
@@ -229,8 +272,7 @@ expression structures:
 
  struct mexp_regexp {
    int r;
-   const pcre *re;
-   const pcre_extra *extra;
+   const pcre2_code *re;
    int options;
  };
  typedef struct mexp_regexp mexp_regexp;
@@ -260,7 +302,7 @@ returned in C<errno>.
 
 =item C<MEXP_PCRE_ERROR>
 
-There was a C<pcre_exec> error.  C<h-E<gt>pcre_error> is set to the
+There was a C<pcre2_match> error.  C<h-E<gt>pcre_error> is set to the
 error code.  See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
 and what they mean.
 
@@ -283,8 +325,8 @@ for EOF or timeout.
 
 =item *
 
-C<regexps[].re>, C<regexps[].extra>, C<regexps[].options>, C<ovector>
-and C<ovecsize> are passed through to the L<pcre_exec(3)> function.
+C<regexps[].re>, C<regexps[].options> and C<match_data> are passed
+through to the L<pcre2_match(3)> function.
 
 =item *
 
@@ -325,21 +367,22 @@ literal" and is available in C99.  If you need to use an older
 compiler, you can just use a local variable instead.
 
  mexp_h *h;
- char *errptr;
+ int errcode;
  int offset;
- pcre *password_re, *prompt_re;
- const int ovecsize = 12;
- int ovector[ovecsize];
+ pcre2_code *password_re, *prompt_re;
+ pcre2_match_data *match_data = pcre2_match_data_create (4, NULL);
  
- password_re = pcre_compile ("assword", 0, &errptr, &offset, NULL);
- prompt_re = pcre_compile ("[$#] ", 0, &errptr, &offset, NULL);
+ password_re = pcre2_compile ("assword", PCRE2_ZERO_TERMINATED,
+                              0, &errcode, &offset, NULL);
+ prompt_re = pcre2_compile ("[$#] ", PCRE2_ZERO_TERMINATED,
+                            0, &errcode, &offset, NULL);
  
  switch (mexp_expect (h,
                       (mexp_regexp[]) {
                         { 100, .re = password_re },
                         { 101, .re = prompt_re },
                         { 0 },
-                      }, ovector, ovecsize)) {
+                      }, match_data)) {
   case 100:
     /* here you would send a password */
     break;
@@ -367,6 +410,8 @@ However we also provide a convenience function:
 
 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
 
+B<int mexp_printf_password (mexp_h *h, const char *fs, ...);>
+
 This returns the number of bytes, if the whole message was written OK.
 If there was an error, -1 is returned and the error is available in
 C<errno>.
@@ -387,8 +432,26 @@ send a command followed by a newline you have to do something like:
 
  mexp_printf (h, "exit\n");
 
+=item *
+
+C<mexp_printf_password> works identically to C<mexp_printf> except
+that the output is I<not> sent to the debugging file if debugging is
+enabled.  As the name suggests, use this for passwords so that they
+don't appear in debugging output.
+
 =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:
@@ -396,9 +459,9 @@ L<http://git.annexia.org/?p=miniexpect.git;a=summary>
 
 =head1 SEE ALSO
 
-L<pcre(3)>,
-L<pcre_exec(3)>,
-L<pcreapi(3)>,
+L<pcre2(3)>,
+L<pcre2_match(3)>,
+L<pcre2api(3)>,
 L<waitpid(2)>,
 L<system(3)>.
 
@@ -413,4 +476,4 @@ your option any later version.
 
 =head1 COPYRIGHT
 
-Copyright (C) 2014 Red Hat Inc.
+Copyright (C) 2014-2022 Red Hat Inc.