docs: Fix example in the manual

[miniexpect.git] / miniexpect.pod

diff --git a/miniexpect.pod b/miniexpect.pod
index 3c3be82..e93ff67 100644 (file)
--- 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 <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", NULL);
  #include <miniexpect.h>
  
  mexp_h *h;
  h = mexp_spawnl ("ssh", "ssh", "host", NULL);

- switch (mexp_expect (h, regexps, ovector, ovecsize)) {
+ switch (mexp_expect (h, regexps, match_data)) {

    ...
  }
  mexp_close (h);
 
    ...
  }
  mexp_close (h);
 

- cc prog.c -o prog -lminiexpect -lpcre
+ cc prog.c -o prog -lminiexpect -lpcre2-8

 
 =head1 DESCRIPTION
 
 
 =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
 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
 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
 partial matches which made this library very simple to implement.
 
 This manual page documents the API.  Examples of how to use the API


@@ -94,7 +95,7 @@ The flags may contain the following values, logically ORed together:
 
 =over 4
 
 
 =over 4
 

-=item C<MEXP_SPAWN_KEEP_SIGNALS>
+=item B<MEXP_SPAWN_KEEP_SIGNALS>

 
 Do not reset signal handlers to C<SIG_DFL> in the subprocess.
 
 
 Do not reset signal handlers to C<SIG_DFL> in the subprocess.
 


@@ -152,30 +153,24 @@ 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
 B<int mexp_get_pcre_error (mexp *h);>
 
 When C<mexp_expect> [see below] calls the PCRE function

-L<pcre_exec(3)>, it stashes the return value in the C<pcre_error>
+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.
 
 field in the handle, and that field is returned by this method.
 

-There are two uses for this:
-
-=over 4
-
-=item 1.
-

 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
 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)>.

 
 

-=item 2.
+B<void mexp_set_debug_file (mexp *h, FILE *fp);>

 
 

-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:
+B<FILE *mexp_get_debug_file (mexp *h);>

 
 

- pcre_get_substring (h->buffer, ovector,
-                     mexp_get_pcre_error (h), 1, &matched);
+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.

 
 

-=back
+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:
 
 The following fields in the handle do not have methods, but can be
 accessed directly instead:


@@ -266,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
 =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,
 
 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
 
 The output of the subprocess is matched against the list of PCRE
 regular expressions in C<regexps>.  C<regexps> is a list of regular


@@ -277,8 +272,7 @@ expression structures:
 
  struct mexp_regexp {
    int r;
 
  struct mexp_regexp {
    int r;

-   const pcre *re;
-   const pcre_extra *extra;
+   const pcre2_code *re;

    int options;
  };
  typedef struct mexp_regexp mexp_regexp;
    int options;
  };
  typedef struct mexp_regexp mexp_regexp;


@@ -308,7 +302,7 @@ returned in C<errno>.
 
 =item C<MEXP_PCRE_ERROR>
 
 
 =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.
 
 error code.  See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
 and what they mean.
 


@@ -331,8 +325,8 @@ for EOF or timeout.
 
 =item *
 
 
 =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 *
 
 
 =item *
 


@@ -373,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;
 compiler, you can just use a local variable instead.
 
  mexp_h *h;

- char *errptr;
+ int errcode;

  int offset;
  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 },
  
  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;
   case 100:
     /* here you would send a password */
     break;


@@ -415,6 +410,8 @@ However we also provide a convenience function:
 
 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
 
 
 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>.
 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>.


@@ -435,6 +432,13 @@ send a command followed by a newline you have to do something like:
 
  mexp_printf (h, "exit\n");
 
 
  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);>
 =back
 
 B<int mexp_send_interrupt (mexp_h *h);>


@@ -455,9 +459,9 @@ L<http://git.annexia.org/?p=miniexpect.git;a=summary>
 
 =head1 SEE ALSO
 
 
 =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)>.
 
 L<waitpid(2)>,
 L<system(3)>.
 


@@ -472,4 +476,4 @@ your option any later version.
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright (C) 2014 Red Hat Inc.
+Copyright (C) 2014-2022 Red Hat Inc.