X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=miniexpect.pod;h=e93ff67ec24a1e949c973b44b857f010e5a7d614;hb=fcf73607913050d246dbcc4f39e7717d0960763f;hp=9fe235e031e7567bd829988cf2a208d1188f54e4;hpb=fb0eeddc671039cabd9c53934e324ae218b21000;p=miniexpect.git diff --git a/miniexpect.pod b/miniexpect.pod index 9fe235e..e93ff67 100644 --- a/miniexpect.pod +++ b/miniexpect.pod @@ -8,17 +8,18 @@ miniexpect - A very simple expect library for C. #include #include - #include + #define PCRE2_CODE_UNIT_WIDTH 8 + #include #include 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. The PCRE dependency is fundamental because +requires the PCRE2 (Perl Compatible Regular Expressions) library from +L. 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 @@ -60,8 +61,9 @@ B This creates a subprocess running the external program C (the current C<$PATH> is searched unless you give an absolute path). -C are the arguments to the program. Usually the first -argument should be the name of the program. +C are the arguments to the program. You should terminate +the list of arguments with C. 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. 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 is: @@ -93,7 +95,7 @@ The flags may contain the following values, logically ORed together: =over 4 -=item C +=item B Do not reset signal handlers to C in the subprocess. @@ -151,30 +153,24 @@ The default is 1024. Most callers will not need to change this. B When C [see below] calls the PCRE function -L, it stashes the return value in the C +L, it stashes the return value in the C field in the handle, and that field is returned by this method. -There are two uses for this: - -=over 4 - -=item 1. - If C returns C, then the actual PCRE -error code returned by L is available by calling this -method. For a list of PCRE error codes, see L. +error code returned by L is available by calling this +method. For a list of PCRE error codes, see L. -=item 2. +B -A more unusual use is if you ever need to get the captured substrings -from your regular expression (calling L). The -third parameter of that function (C) is the value -returned by L, and so you can call it like this: +B - 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 file handle, eg. C. To disable debugging, pass +C. 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 instead of C. The following fields in the handle do not have methods, but can be accessed directly instead: @@ -265,10 +261,10 @@ This is how code should check for and print errors from C: =head1 EXPECT FUNCTION Miniexpect contains a powerful regular expression matching function -based on L: +based on L: B +pcre2_match_data *match_data);> The output of the subprocess is matched against the list of PCRE regular expressions in C. C is a list of regular @@ -276,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; @@ -307,7 +302,7 @@ returned in C. =item C -There was a C error. Cpcre_error> is set to the +There was a C error. Cpcre_error> is set to the error code. See L for a list of the C error codes and what they mean. @@ -330,8 +325,8 @@ for EOF or timeout. =item * -C, C, C, C -and C are passed through to the L function. +C, C and C are passed +through to the L function. =item * @@ -372,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; @@ -414,6 +410,8 @@ However we also provide a convenience function: B +B + 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. @@ -434,6 +432,13 @@ send a command followed by a newline you have to do something like: mexp_printf (h, "exit\n"); +=item * + +C works identically to C except +that the output is I 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 @@ -454,9 +459,9 @@ L =head1 SEE ALSO -L, -L, -L, +L, +L, +L, L, L. @@ -471,4 +476,4 @@ your option any later version. =head1 COPYRIGHT -Copyright (C) 2014 Red Hat Inc. +Copyright (C) 2014-2022 Red Hat Inc.