977 lines
48 KiB
Diff
977 lines
48 KiB
Diff
From 29a7c30ba6edafe863c01725f3caa876c89398ca Mon Sep 17 00:00:00 2001
|
|
From: ph10 <ph10@6239d852-aaf2-0410-a92c-79f79f948069>
|
|
Date: Wed, 30 Jan 2019 16:11:16 +0000
|
|
Subject: [PATCH] Update POSIX wrapper to use macros in the .h file, but also
|
|
have the POSIX function names in the library.
|
|
MIME-Version: 1.0
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
git-svn-id: svn://vcs.exim.org/pcre2/code/trunk@1064 6239d852-aaf2-0410-a92c-79f79f948069
|
|
|
|
Petr Písař: Ported to 10.32.
|
|
|
|
Signed-off-by: Petr Písař <ppisar@redhat.com>
|
|
---
|
|
README | 17 +----
|
|
doc/html/README.txt | 18 +----
|
|
doc/html/pcre2posix.html | 152 +++++++++++++++++++++----------------
|
|
doc/pcre2.txt | 157 ++++++++++++++++++++++-----------------
|
|
doc/pcre2posix.3 | 133 +++++++++++++++++----------------
|
|
src/pcre2posix.c | 27 +++++--
|
|
src/pcre2posix.h | 29 +++++---
|
|
7 files changed, 291 insertions(+), 242 deletions(-)
|
|
|
|
diff --git a/README b/README
|
|
index ae8adf8..4c3a3bf 100644
|
|
--- a/README
|
|
+++ b/README
|
|
@@ -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
|
|
@@ -887,4 +876,4 @@ The distribution should contain the files listed below.
|
|
Philip Hazel
|
|
Email local part: ph10
|
|
Email domain: cam.ac.uk
|
|
-Last updated: 19 September 2018
|
|
+Last updated: 29 January 2019
|
|
diff --git a/doc/html/README.txt b/doc/html/README.txt
|
|
index 2eb621b..4cd57e6 100644
|
|
--- a/doc/html/README.txt
|
|
+++ b/doc/html/README.txt
|
|
@@ -53,20 +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.
|
|
-
|
|
-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.
|
|
-
|
|
-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.
|
|
+renamed or pointed at by a link (or the program modified, of course). See the
|
|
+pcre2posix documentation for more details.
|
|
|
|
|
|
Documentation for PCRE2
|
|
@@ -888,4 +876,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: 29 January 2019
|
|
diff --git a/doc/html/pcre2posix.html b/doc/html/pcre2posix.html
|
|
index 1da2460..b03948e 100644
|
|
--- a/doc/html/pcre2posix.html
|
|
+++ b/doc/html/pcre2posix.html
|
|
@@ -15,51 +15,75 @@ 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 <pcre2posix.h></b>
|
|
</P>
|
|
<P>
|
|
-<b>int regcomp(regex_t *<i>preg</i>, const char *<i>pattern</i>,</b>
|
|
+<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>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>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>
|
|
+<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 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>.
|
|
+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>
|
|
+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>
|
|
+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
|
|
value zero. This has no effect, but since programs that are written to the
|
|
@@ -80,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
|
|
@@ -128,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.
|
|
@@ -174,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
|
|
@@ -219,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>
|
|
@@ -272,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
|
|
@@ -294,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>
|
|
@@ -320,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: 15 June 2017
|
|
+Last updated: 30 January 2019
|
|
<br>
|
|
-Copyright © 1997-2017 University of Cambridge.
|
|
+Copyright © 1997-2019 University of Cambridge.
|
|
<br>
|
|
<p>
|
|
Return to the <a href="index.html">PCRE2 index page</a>.
|
|
diff --git a/doc/pcre2.txt b/doc/pcre2.txt
|
|
index 30ba2f9..b8d2d20 100644
|
|
--- a/doc/pcre2.txt
|
|
+++ b/doc/pcre2.txt
|
|
@@ -9362,33 +9362,56 @@ SYNOPSIS
|
|
|
|
#include <pcre2posix.h>
|
|
|
|
- int regcomp(regex_t *preg, const char *pattern,
|
|
+ int pcre2_regcomp(regex_t *preg, const char *pattern,
|
|
int cflags);
|
|
|
|
- int regexec(const regex_t *preg, const char *string,
|
|
+ int pcre2_regexec(const regex_t *preg, const char *string,
|
|
size_t nmatch, regmatch_t pmatch[], int eflags);
|
|
|
|
- size_t regerror(int errcode, const regex_t *preg,
|
|
+ size_t pcre2_regerror(int errcode, const regex_t *preg,
|
|
char *errbuf, size_t errbuf_size);
|
|
|
|
- void regfree(regex_t *preg);
|
|
+ void pcre2_regfree(regex_t *preg);
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
This set of functions provides a POSIX-style API for the PCRE2 regular
|
|
- expression 8-bit library. See the pcre2api documentation for a descrip-
|
|
- tion of PCRE2's native API, which contains much additional functional-
|
|
- ity. There are no POSIX-style wrappers for PCRE2's 16-bit and 32-bit
|
|
- libraries.
|
|
-
|
|
- The functions described here are just wrapper functions that ultimately
|
|
- call the PCRE2 native API. Their prototypes are defined in the
|
|
- pcre2posix.h header file, and on Unix systems the library itself is
|
|
- called libpcre2-posix.a, so can be accessed by adding -lpcre2-posix to
|
|
- the command for linking an application that uses them. Because the
|
|
- POSIX functions call the native ones, it is also necessary to add
|
|
- -lpcre2-8.
|
|
+ expression 8-bit library. There are no POSIX-style wrappers for PCRE2's
|
|
+ 16-bit and 32-bit libraries. See the pcre2api documentation for a
|
|
+ description of PCRE2's native API, which contains much additional func-
|
|
+ tionality.
|
|
+
|
|
+ The functions described here are wrapper functions that ultimately call
|
|
+ the PCRE2 native API. Their prototypes are defined in the pcre2posix.h
|
|
+ header file, and they all have unique names starting with pcre2_. How-
|
|
+ ever, the pcre2posix.h header also contains macro definitions that con-
|
|
+ vert the standard POSIX names such regcomp() into pcre2_regcomp() 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.
|
|
+
|
|
+ On Unix-like systems the PCRE2 POSIX library is called libpcre2-posix,
|
|
+ so can be accessed by adding -lpcre2-posix to the command for linking
|
|
+ an application. Because the POSIX functions call the native ones, it is
|
|
+ also necessary to add -lpcre2-8.
|
|
+
|
|
+ Although they are not defined as protypes in pcre2posix.h, the library
|
|
+ does contain functions with the POSIX names regcomp() etc. These simply
|
|
+ pass their arguments to the PCRE2 functions. These functions are pro-
|
|
+ vided for backwards compatibility with earlier versions of PCRE2, so
|
|
+ that existing programs do not have to be recompiled.
|
|
+
|
|
+ Calling the header file pcre2posix.h avoids any conflict with other
|
|
+ POSIX libraries. It can, of course, be renamed or aliased as regex.h,
|
|
+ which is the "correct" name, if there is no clash. It provides two
|
|
+ structure types, regex_t for compiled internal forms, and regmatch_t
|
|
+ for returning captured substrings. It also defines some constants whose
|
|
+ names start with "REG_"; these are used for setting options and identi-
|
|
+ fying error codes.
|
|
+
|
|
+
|
|
+USING THE POSIX FUNCTIONS
|
|
|
|
Those POSIX option bits that can reasonably be mapped to PCRE2 native
|
|
options have been implemented. In addition, the option REG_EXTENDED is
|
|
@@ -9410,23 +9433,19 @@ DESCRIPTION
|
|
POSIX-compatible, and in multi-unit encoding domains it is probably
|
|
even less compatible.
|
|
|
|
- The header for these functions is supplied as pcre2posix.h to avoid any
|
|
- potential clash with other POSIX libraries. It can, of course, be
|
|
- renamed or aliased as regex.h, which is the "correct" name. It provides
|
|
- two structure types, regex_t for compiled internal forms, and reg-
|
|
- match_t for returning captured substrings. It also defines some con-
|
|
- stants 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 pcre2_ prefix)
|
|
+ may also be used.
|
|
|
|
|
|
COMPILING A PATTERN
|
|
|
|
- The function regcomp() 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 preg argument is a pointer to a regex_t
|
|
- structure that is used as a base for storing information about the com-
|
|
- piled regular expression. (It is also used for input when REG_PEND is
|
|
- set.)
|
|
+ The function pcre2_regcomp() 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 preg argument is a pointer to
|
|
+ a regex_t structure that is used as a base for storing information
|
|
+ about the compiled regular expression. (It is also used for input when
|
|
+ REG_PEND is set.)
|
|
|
|
The argument cflags is either zero, or contains one or more of the bits
|
|
defined by the following macros:
|
|
@@ -9460,21 +9479,23 @@ COMPILING A PATTERN
|
|
|
|
REG_NOSUB
|
|
|
|
- When a pattern that is compiled with this flag is passed to regexec()
|
|
- for matching, the nmatch and pmatch arguments are ignored, and no cap-
|
|
- tured 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
|
|
+ pcre2_regexec() for matching, the nmatch and pmatch 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 back-
|
|
+ references.
|
|
|
|
REG_PEND
|
|
|
|
If this option is set, the reg_endp field in the preg structure (which
|
|
has the type const char *) must be set to point to the character beyond
|
|
- the end of the pattern before calling regcomp(). 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 re_endp 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.
|
|
+ the end of the pattern before calling pcre2_regcomp(). The pattern
|
|
+ itself may now contain binary zeros, which are treated as data charac-
|
|
+ ters. Without REG_PEND, a binary zero terminates the pattern and the
|
|
+ re_endp 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.
|
|
|
|
REG_UCP
|
|
|
|
@@ -9504,15 +9525,16 @@ COMPILING A PATTERN
|
|
It does not affect the way newlines are matched by the dot metacharac-
|
|
ter (they are not) or by a negative class such as [^a] (they are).
|
|
|
|
- The yield of regcomp() is zero on success, and non-zero otherwise. The
|
|
- preg structure is filled in on success, and one other member of the
|
|
- structure (as well as re_endp) is public: re_nsub contains the number
|
|
- of capturing subpatterns in the regular expression. Various error codes
|
|
- are defined in the header file.
|
|
+ The yield of pcre2_regcomp() is zero on success, and non-zero other-
|
|
+ wise. The preg structure is filled in on success, and one other member
|
|
+ of the structure (as well as re_endp) is public: re_nsub contains the
|
|
+ number of capturing subpatterns in the regular expression. Various
|
|
+ error codes are defined in the header file.
|
|
|
|
- NOTE: If the yield of regcomp() is non-zero, you must not attempt to
|
|
- use the contents of the preg structure. If, for example, you pass it to
|
|
- regexec(), the result is undefined and your program is likely to crash.
|
|
+ NOTE: If the yield of pcre2_regcomp() is non-zero, you must not attempt
|
|
+ to use the contents of the preg structure. If, for example, you pass it
|
|
+ to pcre2_regexec(), the result is undefined and your program is likely
|
|
+ to crash.
|
|
|
|
|
|
MATCHING NEWLINE CHARACTERS
|
|
@@ -9549,17 +9571,17 @@ MATCHING NEWLINE CHARACTERS
|
|
Default POSIX newline handling can be obtained by setting PCRE2_DOTALL
|
|
and PCRE2_DOLLAR_ENDONLY when calling pcre2_compile() 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 reg-
|
|
- comp() function causes PCRE2_MULTILINE to be passed to pcre2_compile(),
|
|
- and REG_DOTALL passes PCRE2_DOTALL. There is no way to pass PCRE2_DOL-
|
|
- LAR_ENDONLY.
|
|
+ action. When using the POSIX API, passing REG_NEWLINE to PCRE2's
|
|
+ pcre2_regcomp() function causes PCRE2_MULTILINE to be passed to
|
|
+ pcre2_compile(), and REG_DOTALL passes PCRE2_DOTALL. There is no way to
|
|
+ pass PCRE2_DOLLAR_ENDONLY.
|
|
|
|
|
|
MATCHING A PATTERN
|
|
|
|
- The function regexec() is called to match a compiled pattern preg
|
|
+ The function pcre2_regexec() is called to match a compiled pattern preg
|
|
against a given string, which is by default terminated by a zero byte
|
|
- (but see REG_STARTEND below), subject to the options in eflags. These
|
|
+ (but see REG_STARTEND below), subject to the options in eflags. These
|
|
can be:
|
|
|
|
REG_NOTBOL
|
|
@@ -9603,7 +9625,8 @@ MATCHING A PATTERN
|
|
|
|
If the pattern was compiled with the REG_NOSUB flag, no data about any
|
|
matched strings is returned. The nmatch and pmatch arguments of
|
|
- regexec() are ignored (except possibly as input for REG_STARTEND).
|
|
+ pcre2_regexec() are ignored (except possibly as input for REG_STAR-
|
|
+ TEND).
|
|
|
|
The value of nmatch may be zero, and the value pmatch may be NULL
|
|
(unless REG_STARTEND is set); in both these cases no data about any
|
|
@@ -9626,22 +9649,22 @@ MATCHING A PATTERN
|
|
|
|
ERROR MESSAGES
|
|
|
|
- The regerror() function maps a non-zero errorcode from either regcomp()
|
|
- or regexec() to a printable message. If preg is not NULL, the error
|
|
- should have arisen from the use of that structure. A message terminated
|
|
- by a binary zero is placed in errbuf. If the buffer is too short, only
|
|
- the first errbuf_size - 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
|
|
- errbuf_size if the message was truncated.
|
|
+ The pcre2_regerror() function maps a non-zero errorcode from either
|
|
+ pcre2_regcomp() or pcre2_regexec() to a printable message. If preg is
|
|
+ not NULL, the error should have arisen from the use of that structure.
|
|
+ A message terminated by a binary zero is placed in errbuf. If the buf-
|
|
+ fer is too short, only the first errbuf_size - 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 errbuf_size if the message was truncated.
|
|
|
|
|
|
MEMORY USAGE
|
|
|
|
Compiling a regular expression causes memory to be allocated and asso-
|
|
- ciated with the preg structure. The function regfree() frees all such
|
|
- memory, after which preg may no longer be used as a compiled expres-
|
|
- sion.
|
|
+ ciated with the preg structure. The function pcre2_regfree() frees all
|
|
+ such memory, after which preg may no longer be used as a compiled
|
|
+ expression.
|
|
|
|
|
|
AUTHOR
|
|
@@ -9653,8 +9676,8 @@ AUTHOR
|
|
|
|
REVISION
|
|
|
|
- Last updated: 15 June 2017
|
|
- Copyright (c) 1997-2017 University of Cambridge.
|
|
+ Last updated: 30 January 2019
|
|
+ Copyright (c) 1997-2019 University of Cambridge.
|
|
------------------------------------------------------------------------------
|
|
|
|
|
|
diff --git a/doc/pcre2posix.3 b/doc/pcre2posix.3
|
|
index a91ccbf..05eb605 100644
|
|
--- a/doc/pcre2posix.3
|
|
+++ b/doc/pcre2posix.3
|
|
@@ -1,4 +1,4 @@
|
|
-.TH PCRE2POSIX 3 "19 September 2018" "PCRE2 10.33"
|
|
+.TH PCRE2POSIX 3 "30 January 2019" "PCRE2 10.33"
|
|
.SH NAME
|
|
PCRE2 - Perl-compatible regular expressions (revised API)
|
|
.SH "SYNOPSIS"
|
|
@@ -7,26 +7,15 @@ PCRE2 - Perl-compatible regular expressions (revised API)
|
|
.B #include <pcre2posix.h>
|
|
.PP
|
|
.nf
|
|
-.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
|
|
.
|
|
@@ -34,28 +23,44 @@ PCRE2 - Perl-compatible regular expressions (revised API)
|
|
.rs
|
|
.sp
|
|
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
|
|
.\" HREF
|
|
\fBpcre2api\fP
|
|
.\"
|
|
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
|
|
+The functions described here are wrapper functions that ultimately call the
|
|
+PCRE2 native API. Their prototypes are defined in the \fBpcre2posix.h\fP header
|
|
+file, and they all have unique names starting with \fBpcre2_\fP. However, the
|
|
+\fBpcre2posix.h\fP header also contains macro definitions that convert the
|
|
+standard POSIX names such \fBregcomp()\fP into \fBpcre2_regcomp()\fP 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
|
|
-The functions described here are just wrapper functions that ultimately call
|
|
-the PCRE2 native API. Their prototypes are defined in the \fBpcre2posix.h\fP
|
|
-header file, and on Unix systems the library itself is called
|
|
-\fBlibpcre2-posix.a\fP, so can be accessed by adding \fB-lpcre2-posix\fP to the
|
|
-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.
|
|
+On Unix-like systems the PCRE2 POSIX library is called \fBlibpcre2-posix\fP, so
|
|
+can be accessed by adding \fB-lpcre2-posix\fP to the command for linking an
|
|
+application. 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.
|
|
+Although they are not defined as protypes in \fBpcre2posix.h\fP, the library
|
|
+does contain functions with the POSIX names \fBregcomp()\fP 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
|
|
+Calling the header file \fBpcre2posix.h\fP avoids any conflict with other POSIX
|
|
+libraries. It can, of course, be renamed or aliased as \fBregex.h\fP, which is
|
|
+the "correct" name, if there is no clash. It provides two structure types,
|
|
+\fIregex_t\fP for compiled internal forms, and \fIregmatch_t\fP for returning
|
|
+captured substrings. It also defines some constants whose names start with
|
|
+"REG_"; these are used for setting options and identifying error codes.
|
|
+.
|
|
+.
|
|
+.SH "USING THE POSIX FUNCTIONS"
|
|
+.rs
|
|
+.sp
|
|
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
|
|
@@ -73,19 +78,15 @@ described below. "POSIX-like in style" means that the API approximates to the
|
|
POSIX definition; it is not fully POSIX-compatible, and in multi-unit encoding
|
|
domains it is probably even less compatible.
|
|
.P
|
|
-The header for these functions is supplied as \fBpcre2posix.h\fP to avoid any
|
|
-potential clash with other POSIX libraries. It can, of course, be renamed or
|
|
-aliased as \fBregex.h\fP, which is the "correct" name. It provides two
|
|
-structure types, \fIregex_t\fP for compiled internal forms, and
|
|
-\fIregmatch_t\fP 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 \fBpcre2_\fP prefix) may also be
|
|
+used.
|
|
.
|
|
.
|
|
.SH "COMPILING A PATTERN"
|
|
.rs
|
|
.sp
|
|
-The function \fBregcomp()\fP is called to compile a pattern into an
|
|
+The function \fBpcre2_regcomp()\fP 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 \fIpreg\fP argument is a pointer to a
|
|
\fBregex_t\fP structure that is used as a base for storing information about
|
|
@@ -122,18 +123,18 @@ REG_UTF. Note that REG_NOSPEC is not part of the POSIX standard.
|
|
.sp
|
|
REG_NOSUB
|
|
.sp
|
|
-When a pattern that is compiled with this flag is passed to \fBregexec()\fP for
|
|
-matching, the \fInmatch\fP and \fIpmatch\fP 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
|
|
+\fBpcre2_regexec()\fP for matching, the \fInmatch\fP and \fIpmatch\fP 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.
|
|
.sp
|
|
REG_PEND
|
|
.sp
|
|
If this option is set, the \fBreg_endp\fP field in the \fIpreg\fP structure
|
|
(which has the type const char *) must be set to point to the character beyond
|
|
-the end of the pattern before calling \fBregcomp()\fP. The pattern itself may
|
|
-now contain binary zeros, which are treated as data characters. Without
|
|
+the end of the pattern before calling \fBpcre2_regcomp()\fP. 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 \fBre_endp\fP 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.
|
|
@@ -166,15 +167,16 @@ Perl way, not the POSIX way. Note that setting PCRE2_MULTILINE has only
|
|
newlines are matched by the dot metacharacter (they are not) or by a negative
|
|
class such as [^a] (they are).
|
|
.P
|
|
-The yield of \fBregcomp()\fP is zero on success, and non-zero otherwise. The
|
|
-\fIpreg\fP structure is filled in on success, and one other member of the
|
|
+The yield of \fBpcre2_regcomp()\fP is zero on success, and non-zero otherwise.
|
|
+The \fIpreg\fP structure is filled in on success, and one other member of the
|
|
structure (as well as \fIre_endp\fP) is public: \fIre_nsub\fP contains the
|
|
number of capturing subpatterns in the regular expression. Various error codes
|
|
are defined in the header file.
|
|
.P
|
|
-NOTE: If the yield of \fBregcomp()\fP is non-zero, you must not attempt to
|
|
-use the contents of the \fIpreg\fP structure. If, for example, you pass it to
|
|
-\fBregexec()\fP, the result is undefined and your program is likely to crash.
|
|
+NOTE: If the yield of \fBpcre2_regcomp()\fP is non-zero, you must not attempt
|
|
+to use the contents of the \fIpreg\fP structure. If, for example, you pass it
|
|
+to \fBpcre2_regexec()\fP, the result is undefined and your program is likely to
|
|
+crash.
|
|
.
|
|
.
|
|
.SH "MATCHING NEWLINE CHARACTERS"
|
|
@@ -211,7 +213,7 @@ 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 \fBpcre2_compile()\fP 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 \fBregcomp()\fP function
|
|
+the POSIX API, passing REG_NEWLINE to PCRE2's \fBpcre2_regcomp()\fP function
|
|
causes PCRE2_MULTILINE to be passed to \fBpcre2_compile()\fP, and REG_DOTALL
|
|
passes PCRE2_DOTALL. There is no way to pass PCRE2_DOLLAR_ENDONLY.
|
|
.
|
|
@@ -219,10 +221,10 @@ passes PCRE2_DOTALL. There is no way to pass PCRE2_DOLLAR_ENDONLY.
|
|
.SH "MATCHING A PATTERN"
|
|
.rs
|
|
.sp
|
|
-The function \fBregexec()\fP is called to match a compiled pattern \fIpreg\fP
|
|
-against a given \fIstring\fP, which is by default terminated by a zero byte
|
|
-(but see REG_STARTEND below), subject to the options in \fIeflags\fP. These can
|
|
-be:
|
|
+The function \fBpcre2_regexec()\fP is called to match a compiled pattern
|
|
+\fIpreg\fP against a given \fIstring\fP, which is by default terminated by a
|
|
+zero byte (but see REG_STARTEND below), subject to the options in \fIeflags\fP.
|
|
+These can be:
|
|
.sp
|
|
REG_NOTBOL
|
|
.sp
|
|
@@ -263,7 +265,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 \fInmatch\fP and \fIpmatch\fP arguments of
|
|
-\fBregexec()\fP are ignored (except possibly as input for REG_STARTEND).
|
|
+\fBpcre2_regexec()\fP are ignored (except possibly as input for REG_STARTEND).
|
|
.P
|
|
The value of \fInmatch\fP may be zero, and the value \fIpmatch\fP may be NULL
|
|
(unless REG_STARTEND is set); in both these cases no data about any matched
|
|
@@ -286,22 +288,23 @@ header file, of which REG_NOMATCH is the "expected" failure code.
|
|
.SH "ERROR MESSAGES"
|
|
.rs
|
|
.sp
|
|
-The \fBregerror()\fP function maps a non-zero errorcode from either
|
|
-\fBregcomp()\fP or \fBregexec()\fP to a printable message. If \fIpreg\fP is not
|
|
-NULL, the error should have arisen from the use of that structure. A message
|
|
-terminated by a binary zero is placed in \fIerrbuf\fP. If the buffer is too
|
|
-short, only the first \fIerrbuf_size\fP - 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
|
|
-\fIerrbuf_size\fP if the message was truncated.
|
|
+The \fBpcre2_regerror()\fP function maps a non-zero errorcode from either
|
|
+\fBpcre2_regcomp()\fP or \fBpcre2_regexec()\fP to a printable message. If
|
|
+\fIpreg\fP is not NULL, the error should have arisen from the use of that
|
|
+structure. A message terminated by a binary zero is placed in \fIerrbuf\fP. If
|
|
+the buffer is too short, only the first \fIerrbuf_size\fP - 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 \fIerrbuf_size\fP if the message was truncated.
|
|
.
|
|
.
|
|
.SH MEMORY USAGE
|
|
.rs
|
|
.sp
|
|
Compiling a regular expression causes memory to be allocated and associated
|
|
-with the \fIpreg\fP structure. The function \fBregfree()\fP frees all such
|
|
-memory, after which \fIpreg\fP may no longer be used as a compiled expression.
|
|
+with the \fIpreg\fP structure. The function \fBpcre2_regfree()\fP frees all
|
|
+such memory, after which \fIpreg\fP may no longer be used as a compiled
|
|
+expression.
|
|
.
|
|
.
|
|
.SH AUTHOR
|
|
@@ -318,6 +321,6 @@ Cambridge, England.
|
|
.rs
|
|
.sp
|
|
.nf
|
|
-Last updated: 19 September 2018
|
|
-Copyright (c) 1997-2018 University of Cambridge.
|
|
+Last updated: 30 January 2019
|
|
+Copyright (c) 1997-2019 University of Cambridge.
|
|
.fi
|
|
diff --git a/src/pcre2posix.c b/src/pcre2posix.c
|
|
index 3666100..34a8d80 100644
|
|
--- a/src/pcre2posix.c
|
|
+++ b/src/pcre2posix.c
|
|
@@ -7,7 +7,7 @@ and semantics are as close as possible to those of the Perl 5 language.
|
|
|
|
Written by Philip Hazel
|
|
Original API code Copyright (c) 1997-2012 University of Cambridge
|
|
- New API code Copyright (c) 2016-2018 University of Cambridge
|
|
+ New API code Copyright (c) 2016-2019 University of Cambridge
|
|
|
|
-----------------------------------------------------------------------------
|
|
Redistribution and use in source and binary forms, with or without
|
|
@@ -41,9 +41,11 @@ POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
/* This module is a wrapper that provides a POSIX API to the underlying PCRE2
|
|
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. */
|
|
+wrappers that use the plain POSIX names. In addition, pcre2posix.h defines the
|
|
+POSIX names as macros for the pcre2_xxx functions, so any program that includes
|
|
+it and uses the POSIX names will call the base functions directly. 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
|
|
@@ -177,24 +179,39 @@ static const char *const pstring[] = {
|
|
* Wrappers with traditional POSIX names *
|
|
*************************************************/
|
|
|
|
+/* Keep defining them to preseve the ABI for applications linked to the pcre2
|
|
+POSIX library before these names were changed into macros in pcre2posix.h.
|
|
+This also ensures that the POSIX names are callable from languages that do not
|
|
+include pcre2posix.h. It is vital to #undef the macro definitions from
|
|
+pcre2posix.h! */
|
|
+
|
|
+#undef regerror
|
|
+PCRE2POSIX_EXP_DECL size_t regerror(int, const regex_t *, char *, size_t);
|
|
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);
|
|
}
|
|
|
|
+#undef regfree
|
|
+PCRE2POSIX_EXP_DECL void regfree(regex_t *);
|
|
PCRE2POSIX_EXP_DEFN void PCRE2_CALL_CONVENTION
|
|
regfree(regex_t *preg)
|
|
{
|
|
pcre2_regfree(preg);
|
|
}
|
|
|
|
+#undef regcomp
|
|
+PCRE2POSIX_EXP_DECL int regcomp(regex_t *, const char *, int);
|
|
PCRE2POSIX_EXP_DEFN int PCRE2_CALL_CONVENTION
|
|
regcomp(regex_t *preg, const char *pattern, int cflags)
|
|
{
|
|
return pcre2_regcomp(preg, pattern, cflags);
|
|
}
|
|
|
|
+#undef regexec
|
|
+PCRE2POSIX_EXP_DECL int regexec(const regex_t *, const char *, size_t,
|
|
+ regmatch_t *, int);
|
|
PCRE2POSIX_EXP_DEFN int PCRE2_CALL_CONVENTION
|
|
regexec(const regex_t *preg, const char *string, size_t nmatch,
|
|
regmatch_t pmatch[], int eflags)
|
|
@@ -209,7 +226,7 @@ return pcre2_regexec(preg, string, nmatch, pmatch, eflags);
|
|
*************************************************/
|
|
|
|
PCRE2POSIX_EXP_DEFN size_t PCRE2_CALL_CONVENTION
|
|
-pcre2_regerror(int errcode, const regex_t *preg, char *errbuf,
|
|
+pcre2_regerror(int errcode, const regex_t *preg, char *errbuf,
|
|
size_t errbuf_size)
|
|
{
|
|
int used;
|
|
diff --git a/src/pcre2posix.h b/src/pcre2posix.h
|
|
index bfe347e..cb59d03 100644
|
|
--- a/src/pcre2posix.h
|
|
+++ b/src/pcre2posix.h
|
|
@@ -9,7 +9,7 @@ POSIX wrapper interface.
|
|
|
|
Written by Philip Hazel
|
|
Original API code Copyright (c) 1997-2012 University of Cambridge
|
|
- New API code Copyright (c) 2016-2018 University of Cambridge
|
|
+ New API code Copyright (c) 2016-2019 University of Cambridge
|
|
|
|
-----------------------------------------------------------------------------
|
|
Redistribution and use in source and binary forms, with or without
|
|
@@ -139,22 +139,29 @@ file. */
|
|
#endif
|
|
|
|
/* 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. */
|
|
+uniqueness. POSIX names are provided as macros for API compatibility with POSIX
|
|
+regex functions. It's done this way to ensure to they are always linked from
|
|
+the PCRE2 library and not by accident from elsewhere (regex_t differs in size
|
|
+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 *);
|
|
+
|
|
+#define regcomp pcre2_regcomp
|
|
+#define regexec pcre2_regexec
|
|
+#define regerror pcre2_regerror
|
|
+#define regfree pcre2_regfree
|
|
+
|
|
+/* Debian had a patch that used different names. These are now here to save
|
|
+them having to maintain their own patch, but are not documented by PCRE2. */
|
|
+
|
|
+#define PCRE2regcomp pcre2_regcomp
|
|
+#define PCRE2regexec pcre2_regexec
|
|
+#define PCRE2regerror pcre2_regerror
|
|
+#define PCRE2regfree pcre2_regfree
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
--
|
|
2.17.2
|
|
|