From 992e1fad4497514f3d8ac5d929307256b374f7e2 Mon Sep 17 00:00:00 2001 From: "Philip.Hazel" Date: Wed, 19 Sep 2018 16:33:09 +0000 Subject: [PATCH] Provide alternative POSIX names. --- ChangeLog | 4 ++++ README | 27 +++++++++++++-------------- doc/pcre2posix.3 | 24 +++++++++++++++++++++--- src/pcre2posix.c | 46 +++++++++++++++++++++++++++++++++++++++------- src/pcre2posix.h | 18 +++++++++++++++--- 5 files changed, 92 insertions(+), 27 deletions(-) diff --git a/ChangeLog b/ChangeLog index 18e8e45..381a982 100644 --- a/ChangeLog +++ b/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 ------------------------------- diff --git a/README b/README index 2eb621b..ae8adf8 100644 --- a/README +++ b/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 -library that are based on the POSIX regular expression API (see the pcre2posix -man page). These can be found in a library called libpcre2-posix. Note that -this just provides a POSIX calling interface to PCRE2; the regular expressions -themselves still follow Perl syntax and semantics. The POSIX API is restricted, -and does not give full access to all of PCRE2's facilities. +In addition, the distribution contains a set of C wrapper functions for the +8-bit library that are based on the POSIX regular expression API (see the +pcre2posix man page). These are built into a library called libpcre2-posix. +Note that this just provides a POSIX calling interface to PCRE2; the regular +expressions themselves still follow Perl syntax and semantics. The POSIX API is +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 --Dregcomp=PCRE2regcomp (and similarly for the other POSIX functions) to the -compiler flags (CFLAGS if you are using "configure" -- see below). This has the -effect of renaming the functions so that the names no longer clash. Of course, -you have to do the same thing for your applications, or write them using the -new names. +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. 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 diff --git a/doc/pcre2posix.3 b/doc/pcre2posix.3 index 0d8b2c2..a91ccbf 100644 --- a/doc/pcre2posix.3 +++ b/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 -Copyright (c) 1997-2017 University of Cambridge. +Last updated: 19 September 2018 +Copyright (c) 1997-2018 University of Cambridge. .fi diff --git a/src/pcre2posix.c b/src/pcre2posix.c index 7b9f477..3666100 100644 --- a/src/pcre2posix.c +++ b/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; diff --git a/src/pcre2posix.h b/src/pcre2posix.h index 4ae1d3c..bfe347e 100644 --- a/src/pcre2posix.h +++ b/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