Provide alternative POSIX names.

ChangeLog

@@ -14,6 +14,10 @@ a greater than 1 fixed quantifier. This issue was found by Yunho Kim.
 
 3. Added support for callouts from pcre2_substitute().
 
+4. The POSIX functions are now all called pcre2_regcomp() etc., with wrappers
+that use the standard POSIX names. This should help avoid linking with the 
+wrong library in some environments.
+
 
 Version 10.32 10-September-2018
 -------------------------------

README

@@ -42,18 +42,18 @@ the 16-bit library, which processes strings of 16-bit values, and one for the
 32-bit library, which processes strings of 32-bit values. There are no C++
 wrappers.
 
-The distribution does contain a set of C wrapper functions for the 8-bit
+In addition, the distribution contains a set of C wrapper functions for the
-library that are based on the POSIX regular expression API (see the pcre2posix
+8-bit library that are based on the POSIX regular expression API (see the
-man page). These can be found in a library called libpcre2-posix. Note that
+pcre2posix man page). These are built into a library called libpcre2-posix.
-this just provides a POSIX calling interface to PCRE2; the regular expressions
+Note that this just provides a POSIX calling interface to PCRE2; the regular
-themselves still follow Perl syntax and semantics. The POSIX API is restricted,
+expressions themselves still follow Perl syntax and semantics. The POSIX API is
-and does not give full access to all of PCRE2's facilities.
+restricted, and does not give full access to all of PCRE2's facilities.
 
 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.
+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
@@ -61,12 +61,11 @@ 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.
 
-One way of avoiding this confusion is to compile PCRE2 with the addition of
+To help with this issue, the libpcre2-posix library provides alternative names
--Dregcomp=PCRE2regcomp (and similarly for the other POSIX functions) to the
+for the POSIX functions. These are the POSIX names, prefixed with "pcre2_", for 
-compiler flags (CFLAGS if you are using "configure" -- see below). This has the
+example, pcre2_regcomp(). If an application can be compiled to use the 
-effect of renaming the functions so that the names no longer clash. Of course,
+alternative names (for example by the use of -Dregcomp=pcre2_regcomp etc.) it 
-you have to do the same thing for your applications, or write them using the
+can be sure of linking with the PCRE2 functions.
-new names.
 
 
 Documentation for PCRE2
@@ -888,4 +887,4 @@ The distribution should contain the files listed below.
 Philip Hazel
 Email local part: ph10
 Email domain: cam.ac.uk
-Last updated: 17 June 2018
+Last updated: 19 September 2018

doc/pcre2posix.3

@@ -1,4 +1,4 @@
-.TH PCRE2POSIX 3 "15 June 2017" "PCRE2 10.30"
+.TH PCRE2POSIX 3 "19 September 2018" "PCRE2 10.33"
 .SH NAME
 PCRE2 - Perl-compatible regular expressions (revised API)
 .SH "SYNOPSIS"
@@ -10,13 +10,24 @@ PCRE2 - Perl-compatible regular expressions (revised API)
 .B int regcomp(regex_t *\fIpreg\fP, const char *\fIpattern\fP,
 .B "     int \fIcflags\fP);"
 .sp
+.B int pcre2_regcomp(regex_t *\fIpreg\fP, const char *\fIpattern\fP,
+.B "     int \fIcflags\fP);"
+.sp
 .B int regexec(const regex_t *\fIpreg\fP, const char *\fIstring\fP,
 .B "     size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[], int \fIeflags\fP);"
 .sp
+.B int pcre2_regexec(const regex_t *\fIpreg\fP, const char *\fIstring\fP,
+.B "     size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[], int \fIeflags\fP);"
+.sp
 .B "size_t regerror(int \fIerrcode\fP, const regex_t *\fIpreg\fP,"
 .B "     char *\fIerrbuf\fP, size_t \fIerrbuf_size\fP);"
 .sp
+.B "size_t pcre2_regerror(int \fIerrcode\fP, const regex_t *\fIpreg\fP,"
+.B "     char *\fIerrbuf\fP, size_t \fIerrbuf_size\fP);"
+.sp
 .B void regfree(regex_t *\fIpreg\fP);
+.sp
+.B void pcre2_regfree(regex_t *\fIpreg\fP);
 .fi
 .
 .SH DESCRIPTION
@@ -38,6 +49,13 @@ header file, and on Unix systems the library itself is called
 command for linking an application that uses them. Because the POSIX functions
 call the native ones, it is also necessary to add \fB-lpcre2-8\fP.
 .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.
+.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
 value zero. This has no effect, but since programs that are written to the
@@ -300,6 +318,6 @@ Cambridge, England.
 .rs
 .sp
 .nf
-Last updated: 15 June 2017
+Last updated: 19 September 2018
-Copyright (c) 1997-2017 University of Cambridge.
+Copyright (c) 1997-2018 University of Cambridge.
 .fi

src/pcre2posix.c

@@ -40,7 +40,10 @@ POSSIBILITY OF SUCH DAMAGE.
 
 
 /* This module is a wrapper that provides a POSIX API to the underlying PCRE2
-functions. */
+functions. The operative functions are called pcre2_regcomp(), etc., with
+wrappers that use the plain POSIX names. This makes it easier for an
+application to be sure it gets the PCRE2 versions in the presence of other
+POSIX regex libraries. */
 
 
 #ifdef HAVE_CONFIG_H
@@ -170,13 +173,44 @@ static const char *const pstring[] = {
 
 
 
+/*************************************************
+*      Wrappers with traditional POSIX names     *
+*************************************************/
+
+PCRE2POSIX_EXP_DEFN size_t PCRE2_CALL_CONVENTION
+regerror(int errcode, const regex_t *preg, char *errbuf, size_t errbuf_size)
+{
+return pcre2_regerror(errcode, preg, errbuf, errbuf_size);
+}
+
+PCRE2POSIX_EXP_DEFN void PCRE2_CALL_CONVENTION
+regfree(regex_t *preg)
+{
+pcre2_regfree(preg);
+}
+
+PCRE2POSIX_EXP_DEFN int PCRE2_CALL_CONVENTION
+regcomp(regex_t *preg, const char *pattern, int cflags)
+{
+return pcre2_regcomp(preg, pattern, cflags);
+}
+
+PCRE2POSIX_EXP_DEFN int PCRE2_CALL_CONVENTION
+regexec(const regex_t *preg, const char *string, size_t nmatch,
+  regmatch_t pmatch[], int eflags)
+{
+return pcre2_regexec(preg, string, nmatch, pmatch, eflags);
+}
+
+
 
 /*************************************************
 *          Translate error code to string        *
 *************************************************/
 
 PCRE2POSIX_EXP_DEFN size_t PCRE2_CALL_CONVENTION
-regerror(int errcode, const regex_t *preg, char *errbuf, size_t errbuf_size)
+pcre2_regerror(int errcode, const regex_t *preg, char *errbuf, 
+  size_t errbuf_size)
 {
 int used;
 const char *message;
@@ -199,13 +233,12 @@ return used + 1;
 
 
 
-
 /*************************************************
 *           Free store held by a regex           *
 *************************************************/
 
 PCRE2POSIX_EXP_DEFN void PCRE2_CALL_CONVENTION
-regfree(regex_t *preg)
+pcre2_regfree(regex_t *preg)
 {
 pcre2_match_data_free(preg->re_match_data);
 pcre2_code_free(preg->re_pcre2_code);
@@ -213,7 +246,6 @@ pcre2_code_free(preg->re_pcre2_code);
 
 
 
-
 /*************************************************
 *            Compile a regular expression        *
 *************************************************/
@@ -229,7 +261,7 @@ Returns:      0 on success
 */
 
 PCRE2POSIX_EXP_DEFN int PCRE2_CALL_CONVENTION
-regcomp(regex_t *preg, const char *pattern, int cflags)
+pcre2_regcomp(regex_t *preg, const char *pattern, int cflags)
 {
 PCRE2_SIZE erroffset;
 PCRE2_SIZE patlen;
@@ -296,7 +328,7 @@ for each match. If REG_NOSUB was specified at compile time, the nmatch and
 pmatch arguments are ignored, and the only result is yes/no/error. */
 
 PCRE2POSIX_EXP_DEFN int PCRE2_CALL_CONVENTION
-regexec(const regex_t *preg, const char *string, size_t nmatch,
+pcre2_regexec(const regex_t *preg, const char *string, size_t nmatch,
   regmatch_t pmatch[], int eflags)
 {
 int rc, so, eo;

src/pcre2posix.h

@@ -3,11 +3,13 @@
 *************************************************/
 
 /* PCRE2 is a library of functions to support regular expressions whose syntax
-and semantics are as close as possible to those of the Perl 5 language.
+and semantics are as close as possible to those of the Perl 5 language. This is 
+the public header file to be #included by applications that call PCRE2 via the 
+POSIX wrapper interface.
 
                        Written by Philip Hazel
      Original API code Copyright (c) 1997-2012 University of Cambridge
-         New API code Copyright (c) 2016 University of Cambridge
+          New API code Copyright (c) 2016-2018 University of Cambridge
 
 -----------------------------------------------------------------------------
 Redistribution and use in source and binary forms, with or without
@@ -136,12 +138,22 @@ file. */
 #  endif
 #endif
 
-/* The functions */
+/* The functions. The actual code is in functions with pcre2_xxx names for 
+uniqueness. Wrappers with the POSIX names are provided for those who can ensure 
+they get them from the PCRE2 library and not by accident from elsewhere. */
 
+PCRE2POSIX_EXP_DECL int pcre2_regcomp(regex_t *, const char *, int);
 PCRE2POSIX_EXP_DECL int regcomp(regex_t *, const char *, int);
+
+PCRE2POSIX_EXP_DECL int pcre2_regexec(const regex_t *, const char *, size_t,
+                     regmatch_t *, int);
 PCRE2POSIX_EXP_DECL int regexec(const regex_t *, const char *, size_t,
                      regmatch_t *, int);
+
+PCRE2POSIX_EXP_DECL size_t pcre2_regerror(int, const regex_t *, char *, size_t);
 PCRE2POSIX_EXP_DECL size_t regerror(int, const regex_t *, char *, size_t);
+
+PCRE2POSIX_EXP_DECL void pcre2_regfree(regex_t *);
 PCRE2POSIX_EXP_DECL void regfree(regex_t *);
 
 #ifdef __cplusplus