Update POSIX wrapper to use macros in the .h file, but also have the POSIX

function names in the library.


git-svn-id: svn://vcs.exim.org/pcre2/code/trunk@1064 6239d852-aaf2-0410-a92c-79f79f948069

2 files changed, 84 insertions, 96 deletions

diff --git a/doc/html/README.txt b/doc/html/README.txt
index 9c46ac4..af5af63 100644
--- a/doc/html/README.txt
+++ b/doc/html/README.txt
@@ -53,19 +53,8 @@ The header file for the POSIX-style functions is called pcre2posix.h. The
 official POSIX name is regex.h, but I did not want to risk possible problems
 with existing files of that name by distributing it that way. To use PCRE2 with
 an existing program that uses the POSIX API, pcre2posix.h will have to be
-renamed or pointed at by a link (or the program modified, of course).
-
-If you are using the POSIX interface to PCRE2 and there is already a POSIX
-regex library installed on your system, as well as worrying about the regex.h
-header file (as mentioned above), you must also take care when linking programs
-to ensure that they link with PCRE2's libpcre2-posix library. Otherwise they
-may pick up the POSIX functions of the same name from the other library.
-
-To help with this issue, the libpcre2-posix library provides alternative names
-for the POSIX functions. These are the POSIX names, prefixed with "pcre2_", for 
-example, pcre2_regcomp(). If an application can be compiled to use the 
-alternative names (for example by the use of -Dregcomp=pcre2_regcomp etc.) it 
-can be sure of linking with the PCRE2 functions.
+renamed or pointed at by a link (or the program modified, of course). See the 
+pcre2posix documentation for more details.
 
 
 Documentation for PCRE2
@@ -897,4 +886,4 @@ The distribution should contain the files listed below.
 Philip Hazel
 Email local part: ph10
 Email domain: cam.ac.uk
-Last updated: 15 November 2018
+Last updated: 29 January 2019
diff --git a/doc/html/pcre2posix.html b/doc/html/pcre2posix.html
index b1acd35..b03948e 100644
--- a/doc/html/pcre2posix.html
+++ b/doc/html/pcre2posix.html
@@ -15,73 +15,74 @@ please consult the man page, in case the conversion went wrong.
 <ul>
 <li><a name="TOC1" href="#SEC1">SYNOPSIS</a>
 <li><a name="TOC2" href="#SEC2">DESCRIPTION</a>
-<li><a name="TOC3" href="#SEC3">COMPILING A PATTERN</a>
-<li><a name="TOC4" href="#SEC4">MATCHING NEWLINE CHARACTERS</a>
-<li><a name="TOC5" href="#SEC5">MATCHING A PATTERN</a>
-<li><a name="TOC6" href="#SEC6">ERROR MESSAGES</a>
-<li><a name="TOC7" href="#SEC7">MEMORY USAGE</a>
-<li><a name="TOC8" href="#SEC8">AUTHOR</a>
-<li><a name="TOC9" href="#SEC9">REVISION</a>
+<li><a name="TOC3" href="#SEC3">USING THE POSIX FUNCTIONS</a>
+<li><a name="TOC4" href="#SEC4">COMPILING A PATTERN</a>
+<li><a name="TOC5" href="#SEC5">MATCHING NEWLINE CHARACTERS</a>
+<li><a name="TOC6" href="#SEC6">MATCHING A PATTERN</a>
+<li><a name="TOC7" href="#SEC7">ERROR MESSAGES</a>
+<li><a name="TOC8" href="#SEC8">MEMORY USAGE</a>
+<li><a name="TOC9" href="#SEC9">AUTHOR</a>
+<li><a name="TOC10" href="#SEC10">REVISION</a>
 </ul>
 <br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>
 <P>
 <b>#include &#60;pcre2posix.h&#62;</b>
 </P>
 <P>
-<b>int regcomp(regex_t *<i>preg</i>, const char *<i>pattern</i>,</b>
-<b>     int <i>cflags</i>);</b>
-<br>
-<br>
 <b>int pcre2_regcomp(regex_t *<i>preg</i>, const char *<i>pattern</i>,</b>
 <b>     int <i>cflags</i>);</b>
 <br>
 <br>
-<b>int regexec(const regex_t *<i>preg</i>, const char *<i>string</i>,</b>
-<b>     size_t <i>nmatch</i>, regmatch_t <i>pmatch</i>[], int <i>eflags</i>);</b>
-<br>
-<br>
 <b>int pcre2_regexec(const regex_t *<i>preg</i>, const char *<i>string</i>,</b>
 <b>     size_t <i>nmatch</i>, regmatch_t <i>pmatch</i>[], int <i>eflags</i>);</b>
 <br>
 <br>
-<b>size_t regerror(int <i>errcode</i>, const regex_t *<i>preg</i>,</b>
-<b>     char *<i>errbuf</i>, size_t <i>errbuf_size</i>);</b>
-<br>
-<br>
 <b>size_t pcre2_regerror(int <i>errcode</i>, const regex_t *<i>preg</i>,</b>
 <b>     char *<i>errbuf</i>, size_t <i>errbuf_size</i>);</b>
 <br>
 <br>
-<b>void regfree(regex_t *<i>preg</i>);</b>
-<br>
-<br>
 <b>void pcre2_regfree(regex_t *<i>preg</i>);</b>
 </P>
 <br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br>
 <P>
 This set of functions provides a POSIX-style API for the PCRE2 regular
-expression 8-bit library. See the
+expression 8-bit library. There are no POSIX-style wrappers for PCRE2's 16-bit
+and 32-bit libraries. See the
 <a href="pcre2api.html"><b>pcre2api</b></a>
 documentation for a description of PCRE2's native API, which contains much
-additional functionality. There are no POSIX-style wrappers for PCRE2's 16-bit
-and 32-bit libraries.
+additional functionality. 
+</P>
+<P>
+The functions described here are wrapper functions that ultimately call the
+PCRE2 native API. Their prototypes are defined in the <b>pcre2posix.h</b> header
+file, and they all have unique names starting with <b>pcre2_</b>. However, the
+<b>pcre2posix.h</b> header also contains macro definitions that convert the 
+standard POSIX names such <b>regcomp()</b> into <b>pcre2_regcomp()</b> etc. This
+means that a program can use the usual POSIX names without running the risk of
+accidentally linking with POSIX functions from a different library.
+</P>
+<P>
+On Unix-like systems the PCRE2 POSIX library is called <b>libpcre2-posix</b>, so
+can be accessed by adding <b>-lpcre2-posix</b> to the command for linking an
+application. Because the POSIX functions call the native ones, it is also
+necessary to add <b>-lpcre2-8</b>.
 </P>
 <P>
-The functions described here are just wrapper functions that ultimately call
-the PCRE2 native API. Their prototypes are defined in the <b>pcre2posix.h</b>
-header file, and on Unix systems the library itself is called
-<b>libpcre2-posix.a</b>, so can be accessed by adding <b>-lpcre2-posix</b> to the
-command for linking an application that uses them. Because the POSIX functions
-call the native ones, it is also necessary to add <b>-lpcre2-8</b>.
+Although they are not defined as protypes in <b>pcre2posix.h</b>, the library 
+does contain functions with the POSIX names <b>regcomp()</b> etc. These simply
+pass their arguments to the PCRE2 functions. These functions are provided for
+backwards compatibility with earlier versions of PCRE2, so that existing
+programs do not have to be recompiled.
 </P>
 <P>
-When another POSIX regex library is also installed, there is the possibility of 
-linking an application with the wrong library. To help avoid this issue, the 
-PCRE2 POSIX library provides alternative names for the functions, all starting 
-with "pcre2_". If an application uses these names, possible ambiguity is 
-avoided. In the following description, however, the standard POSIX function
-names are used.
+Calling the header file <b>pcre2posix.h</b> avoids any conflict with other POSIX
+libraries. It can, of course, be renamed or aliased as <b>regex.h</b>, which is
+the "correct" name, if there is no clash. It provides two structure types,
+<i>regex_t</i> for compiled internal forms, and <i>regmatch_t</i> for returning
+captured substrings. It also defines some constants whose names start with
+"REG_"; these are used for setting options and identifying error codes.
 </P>
+<br><a name="SEC3" href="#TOC1">USING THE POSIX FUNCTIONS</a><br>
 <P>
 Those POSIX option bits that can reasonably be mapped to PCRE2 native options
 have been implemented. In addition, the option REG_EXTENDED is defined with the
@@ -103,17 +104,13 @@ POSIX definition; it is not fully POSIX-compatible, and in multi-unit encoding
 domains it is probably even less compatible.
 </P>
 <P>
-The header for these functions is supplied as <b>pcre2posix.h</b> to avoid any
-potential clash with other POSIX libraries. It can, of course, be renamed or
-aliased as <b>regex.h</b>, which is the "correct" name. It provides two
-structure types, <i>regex_t</i> for compiled internal forms, and
-<i>regmatch_t</i> for returning captured substrings. It also defines some
-constants whose names start with "REG_"; these are used for setting options and
-identifying error codes.
+The descriptions below use the actual names of the functions, but, as described
+above, the standard POSIX names (without the <b>pcre2_</b> prefix) may also be
+used.
 </P>
-<br><a name="SEC3" href="#TOC1">COMPILING A PATTERN</a><br>
+<br><a name="SEC4" href="#TOC1">COMPILING A PATTERN</a><br>
 <P>
-The function <b>regcomp()</b> is called to compile a pattern into an
+The function <b>pcre2_regcomp()</b> is called to compile a pattern into an
 internal form. By default, the pattern is a C string terminated by a binary
 zero (but see REG_PEND below). The <i>preg</i> argument is a pointer to a
 <b>regex_t</b> structure that is used as a base for storing information about
@@ -151,18 +148,18 @@ REG_UTF. Note that REG_NOSPEC is not part of the POSIX standard.
 <pre>
   REG_NOSUB
 </pre>
-When a pattern that is compiled with this flag is passed to <b>regexec()</b> for
-matching, the <i>nmatch</i> and <i>pmatch</i> arguments are ignored, and no
-captured strings are returned. Versions of the PCRE library prior to 10.22 used
-to set the PCRE2_NO_AUTO_CAPTURE compile option, but this no longer happens
-because it disables the use of backreferences.
+When a pattern that is compiled with this flag is passed to
+<b>pcre2_regexec()</b> for matching, the <i>nmatch</i> and <i>pmatch</i> arguments
+are ignored, and no captured strings are returned. Versions of the PCRE library
+prior to 10.22 used to set the PCRE2_NO_AUTO_CAPTURE compile option, but this
+no longer happens because it disables the use of backreferences.
 <pre>
   REG_PEND
 </pre>
 If this option is set, the <b>reg_endp</b> field in the <i>preg</i> structure
 (which has the type const char *) must be set to point to the character beyond
-the end of the pattern before calling <b>regcomp()</b>. The pattern itself may
-now contain binary zeros, which are treated as data characters. Without
+the end of the pattern before calling <b>pcre2_regcomp()</b>. The pattern itself
+may now contain binary zeros, which are treated as data characters. Without
 REG_PEND, a binary zero terminates the pattern and the <b>re_endp</b> field is
 ignored. This is a GNU extension to the POSIX standard and should be used with
 caution in software intended to be portable to other systems.
@@ -197,18 +194,19 @@ newlines are matched by the dot metacharacter (they are not) or by a negative
 class such as [^a] (they are).
 </P>
 <P>
-The yield of <b>regcomp()</b> is zero on success, and non-zero otherwise. The
-<i>preg</i> structure is filled in on success, and one other member of the
+The yield of <b>pcre2_regcomp()</b> is zero on success, and non-zero otherwise.
+The <i>preg</i> structure is filled in on success, and one other member of the
 structure (as well as <i>re_endp</i>) is public: <i>re_nsub</i> contains the
 number of capturing subpatterns in the regular expression. Various error codes
 are defined in the header file.
 </P>
 <P>
-NOTE: If the yield of <b>regcomp()</b> is non-zero, you must not attempt to
-use the contents of the <i>preg</i> structure. If, for example, you pass it to
-<b>regexec()</b>, the result is undefined and your program is likely to crash.
+NOTE: If the yield of <b>pcre2_regcomp()</b> is non-zero, you must not attempt
+to use the contents of the <i>preg</i> structure. If, for example, you pass it
+to <b>pcre2_regexec()</b>, the result is undefined and your program is likely to
+crash.
 </P>
-<br><a name="SEC4" href="#TOC1">MATCHING NEWLINE CHARACTERS</a><br>
+<br><a name="SEC5" href="#TOC1">MATCHING NEWLINE CHARACTERS</a><br>
 <P>
 This area is not simple, because POSIX and Perl take different views of things.
 It is not possible to get PCRE2 to obey POSIX semantics, but then PCRE2 was
@@ -242,16 +240,16 @@ is no way to stop newline from matching [^a].
 Default POSIX newline handling can be obtained by setting PCRE2_DOTALL and
 PCRE2_DOLLAR_ENDONLY when calling <b>pcre2_compile()</b> directly, but there is
 no way to make PCRE2 behave exactly as for the REG_NEWLINE action. When using
-the POSIX API, passing REG_NEWLINE to PCRE2's <b>regcomp()</b> function
+the POSIX API, passing REG_NEWLINE to PCRE2's <b>pcre2_regcomp()</b> function
 causes PCRE2_MULTILINE to be passed to <b>pcre2_compile()</b>, and REG_DOTALL
 passes PCRE2_DOTALL. There is no way to pass PCRE2_DOLLAR_ENDONLY.
 </P>
-<br><a name="SEC5" href="#TOC1">MATCHING A PATTERN</a><br>
+<br><a name="SEC6" href="#TOC1">MATCHING A PATTERN</a><br>
 <P>
-The function <b>regexec()</b> is called to match a compiled pattern <i>preg</i>
-against a given <i>string</i>, which is by default terminated by a zero byte
-(but see REG_STARTEND below), subject to the options in <i>eflags</i>. These can
-be:
+The function <b>pcre2_regexec()</b> is called to match a compiled pattern
+<i>preg</i> against a given <i>string</i>, which is by default terminated by a
+zero byte (but see REG_STARTEND below), subject to the options in <i>eflags</i>.
+These can be:
 <pre>
   REG_NOTBOL
 </pre>
@@ -295,7 +293,7 @@ are mutually exclusive; the error REG_INVARG is returned.
 <P>
 If the pattern was compiled with the REG_NOSUB flag, no data about any matched
 strings is returned. The <i>nmatch</i> and <i>pmatch</i> arguments of
-<b>regexec()</b> are ignored (except possibly as input for REG_STARTEND).
+<b>pcre2_regexec()</b> are ignored (except possibly as input for REG_STARTEND).
 </P>
 <P>
 The value of <i>nmatch</i> may be zero, and the value <i>pmatch</i> may be NULL
@@ -317,24 +315,25 @@ array have both structure members set to -1.
 A successful match yields a zero return; various error codes are defined in the
 header file, of which REG_NOMATCH is the "expected" failure code.
 </P>
-<br><a name="SEC6" href="#TOC1">ERROR MESSAGES</a><br>
+<br><a name="SEC7" href="#TOC1">ERROR MESSAGES</a><br>
 <P>
-The <b>regerror()</b> function maps a non-zero errorcode from either
-<b>regcomp()</b> or <b>regexec()</b> to a printable message. If <i>preg</i> is not
-NULL, the error should have arisen from the use of that structure. A message
-terminated by a binary zero is placed in <i>errbuf</i>. If the buffer is too
-short, only the first <i>errbuf_size</i> - 1 characters of the error message are
-used. The yield of the function is the size of buffer needed to hold the whole
-message, including the terminating zero. This value is greater than
-<i>errbuf_size</i> if the message was truncated.
+The <b>pcre2_regerror()</b> function maps a non-zero errorcode from either
+<b>pcre2_regcomp()</b> or <b>pcre2_regexec()</b> to a printable message. If
+<i>preg</i> is not NULL, the error should have arisen from the use of that
+structure. A message terminated by a binary zero is placed in <i>errbuf</i>. If
+the buffer is too short, only the first <i>errbuf_size</i> - 1 characters of the
+error message are used. The yield of the function is the size of buffer needed
+to hold the whole message, including the terminating zero. This value is
+greater than <i>errbuf_size</i> if the message was truncated.
 </P>
-<br><a name="SEC7" href="#TOC1">MEMORY USAGE</a><br>
+<br><a name="SEC8" href="#TOC1">MEMORY USAGE</a><br>
 <P>
 Compiling a regular expression causes memory to be allocated and associated
-with the <i>preg</i> structure. The function <b>regfree()</b> frees all such
-memory, after which <i>preg</i> may no longer be used as a compiled expression.
+with the <i>preg</i> structure. The function <b>pcre2_regfree()</b> frees all
+such memory, after which <i>preg</i> may no longer be used as a compiled
+expression.
 </P>
-<br><a name="SEC8" href="#TOC1">AUTHOR</a><br>
+<br><a name="SEC9" href="#TOC1">AUTHOR</a><br>
 <P>
 Philip Hazel
 <br>
@@ -343,11 +342,11 @@ University Computing Service
 Cambridge, England.
 <br>
 </P>
-<br><a name="SEC9" href="#TOC1">REVISION</a><br>
+<br><a name="SEC10" href="#TOC1">REVISION</a><br>
 <P>
-Last updated: 19 September 2018
+Last updated: 30 January 2019
 <br>
-Copyright &copy; 1997-2018 University of Cambridge.
+Copyright &copy; 1997-2019 University of Cambridge.
 <br>
 <p>
 Return to the <a href="index.html">PCRE2 index page</a>.