walkero
/
pcre2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

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

function names in the library.
This commit is contained in:
Philip.Hazel 2019-01-30 16:11:16 +00:00
parent 51fb3956ee
commit ae913fbee7
8 changed files with 332 additions and 320 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
ChangeLog
View File

@ -14,9 +14,12 @@ a greater than 1 fixed quantifier. This issue was found by Yunho Kim.
3. Added support for callouts from pcre2_substitute(). 3. Added support for callouts from pcre2_substitute().
4. The POSIX functions are now all called pcre2_regcomp() etc., with wrappers 4. The POSIX functions are now all called pcre2_regcomp() etc., with wrapper
that use the standard POSIX names. This should help avoid linking with the functions that use the standard POSIX names. However, in pcre2posix.h the POSIX
wrong library in some environments. names are defined as macros. This should help avoid linking with the wrong
library in some environments while still exporting the POSIX names for
pre-existing programs that use them. (The Debian alternative names are also
defined as macros, but not documented.)
5. Fix an xclass matching issue in JIT. 5. Fix an xclass matching issue in JIT.

17
README
View File

@ -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 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 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 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). renamed or pointed at by a link (or the program modified, of course). See the
pcre2posix documentation for more details.
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.
Documentation for PCRE2 Documentation for PCRE2
@ -897,4 +886,4 @@ The distribution should contain the files listed below.
Philip Hazel Philip Hazel
Email local part: ph10 Email local part: ph10
Email domain: cam.ac.uk Email domain: cam.ac.uk
Last updated: 15 November 2018 Last updated: 29 January 2019

17
doc/html/README.txt
View File

@ -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 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 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 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). renamed or pointed at by a link (or the program modified, of course). See the
pcre2posix documentation for more details.
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.
Documentation for PCRE2 Documentation for PCRE2
@ -897,4 +886,4 @@ The distribution should contain the files listed below.
Philip Hazel Philip Hazel
Email local part: ph10 Email local part: ph10
Email domain: cam.ac.uk Email domain: cam.ac.uk
Last updated: 15 November 2018 Last updated: 29 January 2019

163
doc/html/pcre2posix.html
View File

@ -15,74 +15,75 @@ please consult the man page, in case the conversion went wrong.
<ul> <ul>
<li><a name="TOC1" href="#SEC1">SYNOPSIS</a> <li><a name="TOC1" href="#SEC1">SYNOPSIS</a>
<li><a name="TOC2" href="#SEC2">DESCRIPTION</a> <li><a name="TOC2" href="#SEC2">DESCRIPTION</a>
<li><a name="TOC3" href="#SEC3">COMPILING A PATTERN</a> <li><a name="TOC3" href="#SEC3">USING THE POSIX FUNCTIONS</a>
<li><a name="TOC4" href="#SEC4">MATCHING NEWLINE CHARACTERS</a> <li><a name="TOC4" href="#SEC4">COMPILING A PATTERN</a>
<li><a name="TOC5" href="#SEC5">MATCHING A PATTERN</a> <li><a name="TOC5" href="#SEC5">MATCHING NEWLINE CHARACTERS</a>
<li><a name="TOC6" href="#SEC6">ERROR MESSAGES</a> <li><a name="TOC6" href="#SEC6">MATCHING A PATTERN</a>
<li><a name="TOC7" href="#SEC7">MEMORY USAGE</a> <li><a name="TOC7" href="#SEC7">ERROR MESSAGES</a>
<li><a name="TOC8" href="#SEC8">AUTHOR</a> <li><a name="TOC8" href="#SEC8">MEMORY USAGE</a>
<li><a name="TOC9" href="#SEC9">REVISION</a> <li><a name="TOC9" href="#SEC9">AUTHOR</a>
<li><a name="TOC10" href="#SEC10">REVISION</a>
</ul> </ul>
<br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br> <br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>
<P> <P>
<b>#include &#60;pcre2posix.h&#62;</b> <b>#include &#60;pcre2posix.h&#62;</b>
</P> </P>
<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 pcre2_regcomp(regex_t *<i>preg</i>, const char *<i>pattern</i>,</b>
<b> int <i>cflags</i>);</b> <b> int <i>cflags</i>);</b>
<br> <br>
<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>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> <b> size_t <i>nmatch</i>, regmatch_t <i>pmatch</i>[], int <i>eflags</i>);</b>
<br> <br>
<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>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> <b> char *<i>errbuf</i>, size_t <i>errbuf_size</i>);</b>
<br> <br>
<br> <br>
<b>void regfree(regex_t *<i>preg</i>);</b>
<br>
<br>
<b>void pcre2_regfree(regex_t *<i>preg</i>);</b> <b>void pcre2_regfree(regex_t *<i>preg</i>);</b>
</P> </P>
<br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br> <br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br>
<P> <P>
This set of functions provides a POSIX-style API for the PCRE2 regular 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> <a href="pcre2api.html"><b>pcre2api</b></a>
documentation for a description of PCRE2's native API, which contains much 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 additional functionality.
and 32-bit libraries.
</P> </P>
<P> <P>
The functions described here are just wrapper functions that ultimately call The functions described here are wrapper functions that ultimately call the
the PCRE2 native API. Their prototypes are defined in the <b>pcre2posix.h</b> PCRE2 native API. Their prototypes are defined in the <b>pcre2posix.h</b> header
header file, and on Unix systems the library itself is called file, and they all have unique names starting with <b>pcre2_</b>. However, the
<b>libpcre2-posix.a</b>, so can be accessed by adding <b>-lpcre2-posix</b> to the <b>pcre2posix.h</b> header also contains macro definitions that convert the
command for linking an application that uses them. Because the POSIX functions standard POSIX names such <b>regcomp()</b> into <b>pcre2_regcomp()</b> etc. This
call the native ones, it is also necessary to add <b>-lpcre2-8</b>. 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>
<P> <P>
When another POSIX regex library is also installed, there is the possibility of On Unix-like systems the PCRE2 POSIX library is called <b>libpcre2-posix</b>, so
linking an application with the wrong library. To help avoid this issue, the can be accessed by adding <b>-lpcre2-posix</b> to the command for linking an
PCRE2 POSIX library provides alternative names for the functions, all starting application. Because the POSIX functions call the native ones, it is also
with "pcre2_". If an application uses these names, possible ambiguity is necessary to add <b>-lpcre2-8</b>.
avoided. In the following description, however, the standard POSIX function
names are used.
</P> </P>
<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 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 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 value zero. This has no effect, but since programs that are written to 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. domains it is probably even less compatible.
</P> </P>
<P> <P>
The header for these functions is supplied as <b>pcre2posix.h</b> to avoid any The descriptions below use the actual names of the functions, but, as described
potential clash with other POSIX libraries. It can, of course, be renamed or above, the standard POSIX names (without the <b>pcre2_</b> prefix) may also be
aliased as <b>regex.h</b>, which is the "correct" name. It provides two used.
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> </P>
<br><a name="SEC3" href="#TOC1">COMPILING A PATTERN</a><br> <br><a name="SEC4" href="#TOC1">COMPILING A PATTERN</a><br>
<P> <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 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 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 <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> <pre>
REG_NOSUB REG_NOSUB
</pre> </pre>
When a pattern that is compiled with this flag is passed to <b>regexec()</b> for When a pattern that is compiled with this flag is passed to
matching, the <i>nmatch</i> and <i>pmatch</i> arguments are ignored, and no <b>pcre2_regexec()</b> for matching, the <i>nmatch</i> and <i>pmatch</i> arguments
captured strings are returned. Versions of the PCRE library prior to 10.22 used are ignored, and no captured strings are returned. Versions of the PCRE library
to set the PCRE2_NO_AUTO_CAPTURE compile option, but this no longer happens prior to 10.22 used to set the PCRE2_NO_AUTO_CAPTURE compile option, but this
because it disables the use of backreferences. no longer happens because it disables the use of backreferences.
<pre> <pre>
REG_PEND REG_PEND
</pre> </pre>
If this option is set, the <b>reg_endp</b> field in the <i>preg</i> structure 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 (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 the end of the pattern before calling <b>pcre2_regcomp()</b>. The pattern itself
now contain binary zeros, which are treated as data characters. Without 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 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 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. 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). class such as [^a] (they are).
</P> </P>
<P> <P>
The yield of <b>regcomp()</b> is zero on success, and non-zero otherwise. The The yield of <b>pcre2_regcomp()</b> is zero on success, and non-zero otherwise.
<i>preg</i> structure is filled in on success, and one other member of the 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 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 number of capturing subpatterns in the regular expression. Various error codes
are defined in the header file. are defined in the header file.
</P> </P>
<P> <P>
NOTE: If the yield of <b>regcomp()</b> is non-zero, you must not attempt to NOTE: If the yield of <b>pcre2_regcomp()</b> is non-zero, you must not attempt
use the contents of the <i>preg</i> structure. If, for example, you pass it to to use the contents of the <i>preg</i> structure. If, for example, you pass it
<b>regexec()</b>, the result is undefined and your program is likely to crash. to <b>pcre2_regexec()</b>, the result is undefined and your program is likely to
crash.
</P> </P>
<br><a name="SEC4" href="#TOC1">MATCHING NEWLINE CHARACTERS</a><br> <br><a name="SEC5" href="#TOC1">MATCHING NEWLINE CHARACTERS</a><br>
<P> <P>
This area is not simple, because POSIX and Perl take different views of things. 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 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 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 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 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 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. passes PCRE2_DOTALL. There is no way to pass PCRE2_DOLLAR_ENDONLY.
</P> </P>
<br><a name="SEC5" href="#TOC1">MATCHING A PATTERN</a><br> <br><a name="SEC6" href="#TOC1">MATCHING A PATTERN</a><br>
<P> <P>
The function <b>regexec()</b> is called to match a compiled pattern <i>preg</i> The function <b>pcre2_regexec()</b> is called to match a compiled pattern
against a given <i>string</i>, which is by default terminated by a zero byte <i>preg</i> against a given <i>string</i>, which is by default terminated by a
(but see REG_STARTEND below), subject to the options in <i>eflags</i>. These can zero byte (but see REG_STARTEND below), subject to the options in <i>eflags</i>.
be: These can be:
<pre> <pre>
REG_NOTBOL REG_NOTBOL
</pre> </pre>
@ -295,7 +293,7 @@ are mutually exclusive; the error REG_INVARG is returned.
<P> <P>
If the pattern was compiled with the REG_NOSUB flag, no data about any matched 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 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>
<P> <P>
The value of <i>nmatch</i> may be zero, and the value <i>pmatch</i> may be NULL 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 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. header file, of which REG_NOMATCH is the "expected" failure code.
</P> </P>
<br><a name="SEC6" href="#TOC1">ERROR MESSAGES</a><br> <br><a name="SEC7" href="#TOC1">ERROR MESSAGES</a><br>
<P> <P>
The <b>regerror()</b> function maps a non-zero errorcode from either The <b>pcre2_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 <b>pcre2_regcomp()</b> or <b>pcre2_regexec()</b> to a printable message. If
NULL, the error should have arisen from the use of that structure. A message <i>preg</i> is not NULL, the error should have arisen from the use of that
terminated by a binary zero is placed in <i>errbuf</i>. If the buffer is too structure. A message terminated by a binary zero is placed in <i>errbuf</i>. If
short, only the first <i>errbuf_size</i> - 1 characters of the error message are the buffer is too short, only the first <i>errbuf_size</i> - 1 characters of the
used. The yield of the function is the size of buffer needed to hold the whole error message are used. The yield of the function is the size of buffer needed
message, including the terminating zero. This value is greater than to hold the whole message, including the terminating zero. This value is
<i>errbuf_size</i> if the message was truncated. greater than <i>errbuf_size</i> if the message was truncated.
</P> </P>
<br><a name="SEC7" href="#TOC1">MEMORY USAGE</a><br> <br><a name="SEC8" href="#TOC1">MEMORY USAGE</a><br>
<P> <P>
Compiling a regular expression causes memory to be allocated and associated 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 with the <i>preg</i> structure. The function <b>pcre2_regfree()</b> frees all
memory, after which <i>preg</i> may no longer be used as a compiled expression. such memory, after which <i>preg</i> may no longer be used as a compiled
expression.
</P> </P>
<br><a name="SEC8" href="#TOC1">AUTHOR</a><br> <br><a name="SEC9" href="#TOC1">AUTHOR</a><br>
<P> <P>
Philip Hazel Philip Hazel
<br> <br>
@ -343,11 +342,11 @@ University Computing Service
Cambridge, England. Cambridge, England.
<br> <br>
</P> </P>
<br><a name="SEC9" href="#TOC1">REVISION</a><br> <br><a name="SEC10" href="#TOC1">REVISION</a><br>
<P> <P>
Last updated: 19 September 2018 Last updated: 30 January 2019
<br> <br>
Copyright &copy; 1997-2018 University of Cambridge. Copyright &copy; 1997-2019 University of Cambridge.
<br> <br>
<p> <p>
Return to the <a href="index.html">PCRE2 index page</a>. Return to the <a href="index.html">PCRE2 index page</a>.

257
doc/pcre2.txt
View File

@ -9587,175 +9587,179 @@ SYNOPSIS
#include <pcre2posix.h> #include <pcre2posix.h>
int regcomp(regex_t *preg, const char *pattern,
int cflags);
int pcre2_regcomp(regex_t *preg, const char *pattern, int pcre2_regcomp(regex_t *preg, const char *pattern,
int cflags); int cflags);
int regexec(const regex_t *preg, const char *string,
size_t nmatch, regmatch_t pmatch[], int eflags);
int pcre2_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 nmatch, regmatch_t pmatch[], int eflags);
size_t regerror(int errcode, const regex_t *preg,
char *errbuf, size_t errbuf_size);
size_t pcre2_regerror(int errcode, const regex_t *preg, size_t pcre2_regerror(int errcode, const regex_t *preg,
char *errbuf, size_t errbuf_size); char *errbuf, size_t errbuf_size);
void regfree(regex_t *preg);
void pcre2_regfree(regex_t *preg); void pcre2_regfree(regex_t *preg);
DESCRIPTION DESCRIPTION
This set of functions provides a POSIX-style API for the PCRE2 regular This set of functions provides a POSIX-style API for the PCRE2 regular
expression 8-bit library. See the pcre2api documentation for a descrip- expression 8-bit library. There are no POSIX-style wrappers for PCRE2's
tion of PCRE2's native API, which contains much additional functional- 16-bit and 32-bit libraries. See the pcre2api documentation for a
ity. There are no POSIX-style wrappers for PCRE2's 16-bit and 32-bit description of PCRE2's native API, which contains much additional func-
libraries. tionality.
The functions described here are just wrapper functions that ultimately The functions described here are wrapper functions that ultimately call
call the PCRE2 native API. Their prototypes are defined in the the PCRE2 native API. Their prototypes are defined in the pcre2posix.h
pcre2posix.h header file, and on Unix systems the library itself is header file, and they all have unique names starting with pcre2_. How-
called libpcre2-posix.a, so can be accessed by adding -lpcre2-posix to ever, the pcre2posix.h header also contains macro definitions that con-
the command for linking an application that uses them. Because the vert the standard POSIX names such regcomp() into pcre2_regcomp() etc.
POSIX functions call the native ones, it is also necessary to add This means that a program can use the usual POSIX names without running
-lpcre2-8. the risk of accidentally linking with POSIX functions from a different
library.
When another POSIX regex library is also installed, there is the possi- On Unix-like systems the PCRE2 POSIX library is called libpcre2-posix,
bility of linking an application with the wrong library. To help avoid so can be accessed by adding -lpcre2-posix to the command for linking
this issue, the PCRE2 POSIX library provides alternative names for the an application. Because the POSIX functions call the native ones, it is
functions, all starting with "pcre2_". If an application uses these also necessary to add -lpcre2-8.
names, possible ambiguity is avoided. In the following description,
however, the standard POSIX function names are used.
Those POSIX option bits that can reasonably be mapped to PCRE2 native Although they are not defined as protypes in pcre2posix.h, the library
options have been implemented. In addition, the option REG_EXTENDED is does contain functions with the POSIX names regcomp() etc. These simply
defined with the value zero. This has no effect, but since programs pass their arguments to the PCRE2 functions. These functions are pro-
that are written to the POSIX interface often use it, this makes it vided for backwards compatibility with earlier versions of PCRE2, so
easier to slot in PCRE2 as a replacement library. Other POSIX options 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
defined with the value zero. This has no effect, but since programs
that are written to the POSIX interface often use it, this makes it
easier to slot in PCRE2 as a replacement library. Other POSIX options
are not even defined. are not even defined.
There are also some options that are not defined by POSIX. These have There are also some options that are not defined by POSIX. These have
been added at the request of users who want to make use of certain been added at the request of users who want to make use of certain
PCRE2-specific features via the POSIX calling interface or to add BSD PCRE2-specific features via the POSIX calling interface or to add BSD
or GNU functionality. or GNU functionality.
When PCRE2 is called via these functions, it is only the API that is When PCRE2 is called via these functions, it is only the API that is
POSIX-like in style. The syntax and semantics of the regular expres- POSIX-like in style. The syntax and semantics of the regular expres-
sions themselves are still those of Perl, subject to the setting of sions themselves are still those of Perl, subject to the setting of
various PCRE2 options, as described below. "POSIX-like in style" means various PCRE2 options, as described below. "POSIX-like in style" means
that the API approximates to the POSIX definition; it is not fully that the API approximates to the POSIX definition; it is not fully
POSIX-compatible, and in multi-unit encoding domains it is probably POSIX-compatible, and in multi-unit encoding domains it is probably
even less compatible. even less compatible.
The header for these functions is supplied as pcre2posix.h to avoid any The descriptions below use the actual names of the functions, but, as
potential clash with other POSIX libraries. It can, of course, be described above, the standard POSIX names (without the pcre2_ prefix)
renamed or aliased as regex.h, which is the "correct" name. It provides may also be used.
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.
COMPILING A PATTERN COMPILING A PATTERN
The function regcomp() is called to compile a pattern into an internal The function pcre2_regcomp() is called to compile a pattern into an
form. By default, the pattern is a C string terminated by a binary zero internal form. By default, the pattern is a C string terminated by a
(but see REG_PEND below). The preg argument is a pointer to a regex_t binary zero (but see REG_PEND below). The preg argument is a pointer to
structure that is used as a base for storing information about the com- a regex_t structure that is used as a base for storing information
piled regular expression. (It is also used for input when REG_PEND is about the compiled regular expression. (It is also used for input when
set.) REG_PEND is set.)
The argument cflags is either zero, or contains one or more of the bits The argument cflags is either zero, or contains one or more of the bits
defined by the following macros: defined by the following macros:
REG_DOTALL REG_DOTALL
The PCRE2_DOTALL option is set when the regular expression is passed The PCRE2_DOTALL option is set when the regular expression is passed
for compilation to the native function. Note that REG_DOTALL is not for compilation to the native function. Note that REG_DOTALL is not
part of the POSIX standard. part of the POSIX standard.
REG_ICASE REG_ICASE
The PCRE2_CASELESS option is set when the regular expression is passed The PCRE2_CASELESS option is set when the regular expression is passed
for compilation to the native function. for compilation to the native function.
REG_NEWLINE REG_NEWLINE
The PCRE2_MULTILINE option is set when the regular expression is passed The PCRE2_MULTILINE option is set when the regular expression is passed
for compilation to the native function. Note that this does not mimic for compilation to the native function. Note that this does not mimic
the defined POSIX behaviour for REG_NEWLINE (see the following sec- the defined POSIX behaviour for REG_NEWLINE (see the following sec-
tion). tion).
REG_NOSPEC REG_NOSPEC
The PCRE2_LITERAL option is set when the regular expression is passed The PCRE2_LITERAL option is set when the regular expression is passed
for compilation to the native function. This disables all meta charac- for compilation to the native function. This disables all meta charac-
ters in the pattern, causing it to be treated as a literal string. The ters in the pattern, causing it to be treated as a literal string. The
only other options that are allowed with REG_NOSPEC are REG_ICASE, only other options that are allowed with REG_NOSPEC are REG_ICASE,
REG_NOSUB, REG_PEND, and REG_UTF. Note that REG_NOSPEC is not part of REG_NOSUB, REG_PEND, and REG_UTF. Note that REG_NOSPEC is not part of
the POSIX standard. the POSIX standard.
REG_NOSUB REG_NOSUB
When a pattern that is compiled with this flag is passed to regexec() When a pattern that is compiled with this flag is passed to
for matching, the nmatch and pmatch arguments are ignored, and no cap- pcre2_regexec() for matching, the nmatch and pmatch arguments are
tured strings are returned. Versions of the PCRE library prior to 10.22 ignored, and no captured strings are returned. Versions of the PCRE
used to set the PCRE2_NO_AUTO_CAPTURE compile option, but this no library prior to 10.22 used to set the PCRE2_NO_AUTO_CAPTURE compile
longer happens because it disables the use of backreferences. option, but this no longer happens because it disables the use of back-
references.
REG_PEND REG_PEND
If this option is set, the reg_endp field in the preg structure (which 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 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 the end of the pattern before calling pcre2_regcomp(). The pattern
now contain binary zeros, which are treated as data characters. Without itself may now contain binary zeros, which are treated as data charac-
REG_PEND, a binary zero terminates the pattern and the re_endp field is ters. Without REG_PEND, a binary zero terminates the pattern and the
ignored. This is a GNU extension to the POSIX standard and should be re_endp field is ignored. This is a GNU extension to the POSIX standard
used with caution in software intended to be portable to other systems. and should be used with caution in software intended to be portable to
other systems.
REG_UCP REG_UCP
The PCRE2_UCP option is set when the regular expression is passed for The PCRE2_UCP option is set when the regular expression is passed for
compilation to the native function. This causes PCRE2 to use Unicode compilation to the native function. This causes PCRE2 to use Unicode
properties when matchine \d, \w, etc., instead of just recognizing properties when matchine \d, \w, etc., instead of just recognizing
ASCII values. Note that REG_UCP is not part of the POSIX standard. ASCII values. Note that REG_UCP is not part of the POSIX standard.
REG_UNGREEDY REG_UNGREEDY
The PCRE2_UNGREEDY option is set when the regular expression is passed The PCRE2_UNGREEDY option is set when the regular expression is passed
for compilation to the native function. Note that REG_UNGREEDY is not for compilation to the native function. Note that REG_UNGREEDY is not
part of the POSIX standard. part of the POSIX standard.
REG_UTF REG_UTF
The PCRE2_UTF option is set when the regular expression is passed for The PCRE2_UTF option is set when the regular expression is passed for
compilation to the native function. This causes the pattern itself and compilation to the native function. This causes the pattern itself and
all data strings used for matching it to be treated as UTF-8 strings. all data strings used for matching it to be treated as UTF-8 strings.
Note that REG_UTF is not part of the POSIX standard. Note that REG_UTF is not part of the POSIX standard.
In the absence of these flags, no options are passed to the native In the absence of these flags, no options are passed to the native
function. This means the the regex is compiled with PCRE2 default function. This means the the regex is compiled with PCRE2 default
semantics. In particular, the way it handles newline characters in the semantics. In particular, the way it handles newline characters in the
subject string is the Perl way, not the POSIX way. Note that setting subject string is the Perl way, not the POSIX way. Note that setting
PCRE2_MULTILINE has only some of the effects specified for REG_NEWLINE. PCRE2_MULTILINE has only some of the effects specified for REG_NEWLINE.
It does not affect the way newlines are matched by the dot metacharac- 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). 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 The yield of pcre2_regcomp() is zero on success, and non-zero other-
preg structure is filled in on success, and one other member of the wise. The preg structure is filled in on success, and one other member
structure (as well as re_endp) is public: re_nsub contains the number of the structure (as well as re_endp) is public: re_nsub contains the
of capturing subpatterns in the regular expression. Various error codes number of capturing subpatterns in the regular expression. Various
are defined in the header file. error codes are defined in the header file.
NOTE: If the yield of regcomp() is non-zero, you must not attempt to NOTE: If the yield of pcre2_regcomp() is non-zero, you must not attempt
use the contents of the preg structure. If, for example, you pass it to to use the contents of the preg structure. If, for example, you pass it
regexec(), the result is undefined and your program is likely to crash. to pcre2_regexec(), the result is undefined and your program is likely
to crash.
MATCHING NEWLINE CHARACTERS MATCHING NEWLINE CHARACTERS
@ -9792,17 +9796,17 @@ MATCHING NEWLINE CHARACTERS
Default POSIX newline handling can be obtained by setting PCRE2_DOTALL Default POSIX newline handling can be obtained by setting PCRE2_DOTALL
and PCRE2_DOLLAR_ENDONLY when calling pcre2_compile() directly, but and PCRE2_DOLLAR_ENDONLY when calling pcre2_compile() directly, but
there is no way to make PCRE2 behave exactly as for the REG_NEWLINE 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- action. When using the POSIX API, passing REG_NEWLINE to PCRE2's
comp() function causes PCRE2_MULTILINE to be passed to pcre2_compile(), pcre2_regcomp() function causes PCRE2_MULTILINE to be passed to
and REG_DOTALL passes PCRE2_DOTALL. There is no way to pass PCRE2_DOL- pcre2_compile(), and REG_DOTALL passes PCRE2_DOTALL. There is no way to
LAR_ENDONLY. pass PCRE2_DOLLAR_ENDONLY.
MATCHING A PATTERN 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 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: can be:
REG_NOTBOL REG_NOTBOL
@ -9846,45 +9850,46 @@ MATCHING A PATTERN
If the pattern was compiled with the REG_NOSUB flag, no data about any If the pattern was compiled with the REG_NOSUB flag, no data about any
matched strings is returned. The nmatch and pmatch arguments of 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 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 (unless REG_STARTEND is set); in both these cases no data about any
matched strings is returned. matched strings is returned.
Otherwise, the portion of the string that was matched, and also any Otherwise, the portion of the string that was matched, and also any
captured substrings, are returned via the pmatch argument, which points captured substrings, are returned via the pmatch argument, which points
to an array of nmatch structures of type regmatch_t, containing the to an array of nmatch structures of type regmatch_t, containing the
members rm_so and rm_eo. These contain the byte offset to the first members rm_so and rm_eo. These contain the byte offset to the first
character of each substring and the offset to the first character after character of each substring and the offset to the first character after
the end of each substring, respectively. The 0th element of the vector the end of each substring, respectively. The 0th element of the vector
relates to the entire portion of string that was matched; subsequent relates to the entire portion of string that was matched; subsequent
elements relate to the capturing subpatterns of the regular expression. elements relate to the capturing subpatterns of the regular expression.
Unused entries in the array have both structure members set to -1. Unused entries in the array have both structure members set to -1.
A successful match yields a zero return; various error codes are A successful match yields a zero return; various error codes are
defined in the header file, of which REG_NOMATCH is the "expected" defined in the header file, of which REG_NOMATCH is the "expected"
failure code. failure code.
ERROR MESSAGES ERROR MESSAGES
The regerror() function maps a non-zero errorcode from either regcomp() The pcre2_regerror() function maps a non-zero errorcode from either
or regexec() to a printable message. If preg is not NULL, the error pcre2_regcomp() or pcre2_regexec() to a printable message. If preg is
should have arisen from the use of that structure. A message terminated not NULL, the error should have arisen from the use of that structure.
by a binary zero is placed in errbuf. If the buffer is too short, only A message terminated by a binary zero is placed in errbuf. If the buf-
the first errbuf_size - 1 characters of the error message are used. The fer is too short, only the first errbuf_size - 1 characters of the
yield of the function is the size of buffer needed to hold the whole error message are used. The yield of the function is the size of buffer
message, including the terminating zero. This value is greater than needed to hold the whole message, including the terminating zero. This
errbuf_size if the message was truncated. value is greater than errbuf_size if the message was truncated.
MEMORY USAGE MEMORY USAGE
Compiling a regular expression causes memory to be allocated and asso- Compiling a regular expression causes memory to be allocated and asso-
ciated with the preg structure. The function regfree() frees all such ciated with the preg structure. The function pcre2_regfree() frees all
memory, after which preg may no longer be used as a compiled expres- such memory, after which preg may no longer be used as a compiled
sion. expression.
AUTHOR AUTHOR
@ -9896,8 +9901,8 @@ AUTHOR
REVISION REVISION
Last updated: 19 September 2018 Last updated: 30 January 2019
Copyright (c) 1997-2018 University of Cambridge. Copyright (c) 1997-2019 University of Cambridge.
------------------------------------------------------------------------------ ------------------------------------------------------------------------------

133
doc/pcre2posix.3
View File

@ -1,4 +1,4 @@
.TH PCRE2POSIX 3 "19 September 2018" "PCRE2 10.33" .TH PCRE2POSIX 3 "30 January 2019" "PCRE2 10.33"
.SH NAME .SH NAME
PCRE2 - Perl-compatible regular expressions (revised API) PCRE2 - Perl-compatible regular expressions (revised API)
.SH "SYNOPSIS" .SH "SYNOPSIS"
@ -7,26 +7,15 @@ PCRE2 - Perl-compatible regular expressions (revised API)
.B #include <pcre2posix.h> .B #include <pcre2posix.h>
.PP .PP
.nf .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 pcre2_regcomp(regex_t *\fIpreg\fP, const char *\fIpattern\fP,
.B " int \fIcflags\fP);" .B " int \fIcflags\fP);"
.sp .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 int pcre2_regexec(const regex_t *\fIpreg\fP, const char *\fIstring\fP,
.B " size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[], int \fIeflags\fP);" .B " size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[], int \fIeflags\fP);"
.sp .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 "size_t pcre2_regerror(int \fIerrcode\fP, const regex_t *\fIpreg\fP,"
.B " char *\fIerrbuf\fP, size_t \fIerrbuf_size\fP);" .B " char *\fIerrbuf\fP, size_t \fIerrbuf_size\fP);"
.sp .sp
.B void regfree(regex_t *\fIpreg\fP);
.sp
.B void pcre2_regfree(regex_t *\fIpreg\fP); .B void pcre2_regfree(regex_t *\fIpreg\fP);
.fi .fi
. .
@ -34,28 +23,44 @@ PCRE2 - Perl-compatible regular expressions (revised API)
.rs .rs
.sp .sp
This set of functions provides a POSIX-style API for the PCRE2 regular 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 .\" HREF
\fBpcre2api\fP \fBpcre2api\fP
.\" .\"
documentation for a description of PCRE2's native API, which contains much 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 additional functionality.
and 32-bit libraries.
.P .P
The functions described here are just wrapper functions that ultimately call The functions described here are wrapper functions that ultimately call the
the PCRE2 native API. Their prototypes are defined in the \fBpcre2posix.h\fP PCRE2 native API. Their prototypes are defined in the \fBpcre2posix.h\fP header
header file, and on Unix systems the library itself is called file, and they all have unique names starting with \fBpcre2_\fP. However, the
\fBlibpcre2-posix.a\fP, so can be accessed by adding \fB-lpcre2-posix\fP to the \fBpcre2posix.h\fP header also contains macro definitions that convert the
command for linking an application that uses them. Because the POSIX functions standard POSIX names such \fBregcomp()\fP into \fBpcre2_regcomp()\fP etc. This
call the native ones, it is also necessary to add \fB-lpcre2-8\fP. 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
When another POSIX regex library is also installed, there is the possibility of On Unix-like systems the PCRE2 POSIX library is called \fBlibpcre2-posix\fP, so
linking an application with the wrong library. To help avoid this issue, the can be accessed by adding \fB-lpcre2-posix\fP to the command for linking an
PCRE2 POSIX library provides alternative names for the functions, all starting application. Because the POSIX functions call the native ones, it is also
with "pcre2_". If an application uses these names, possible ambiguity is necessary to add \fB-lpcre2-8\fP.
avoided. In the following description, however, the standard POSIX function
names are used.
.P .P
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 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 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 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 POSIX definition; it is not fully POSIX-compatible, and in multi-unit encoding
domains it is probably even less compatible. domains it is probably even less compatible.
.P .P
The header for these functions is supplied as \fBpcre2posix.h\fP to avoid any The descriptions below use the actual names of the functions, but, as described
potential clash with other POSIX libraries. It can, of course, be renamed or above, the standard POSIX names (without the \fBpcre2_\fP prefix) may also be
aliased as \fBregex.h\fP, which is the "correct" name. It provides two used.
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 "COMPILING A PATTERN" .SH "COMPILING A PATTERN"
.rs .rs
.sp .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 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 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 \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 .sp
REG_NOSUB REG_NOSUB
.sp .sp
When a pattern that is compiled with this flag is passed to \fBregexec()\fP for When a pattern that is compiled with this flag is passed to
matching, the \fInmatch\fP and \fIpmatch\fP arguments are ignored, and no \fBpcre2_regexec()\fP for matching, the \fInmatch\fP and \fIpmatch\fP arguments
captured strings are returned. Versions of the PCRE library prior to 10.22 used are ignored, and no captured strings are returned. Versions of the PCRE library
to set the PCRE2_NO_AUTO_CAPTURE compile option, but this no longer happens prior to 10.22 used to set the PCRE2_NO_AUTO_CAPTURE compile option, but this
because it disables the use of backreferences. no longer happens because it disables the use of backreferences.
.sp .sp
REG_PEND REG_PEND
.sp .sp
If this option is set, the \fBreg_endp\fP field in the \fIpreg\fP structure 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 (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 the end of the pattern before calling \fBpcre2_regcomp()\fP. The pattern itself
now contain binary zeros, which are treated as data characters. Without 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 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 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. 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 newlines are matched by the dot metacharacter (they are not) or by a negative
class such as [^a] (they are). class such as [^a] (they are).
.P .P
The yield of \fBregcomp()\fP is zero on success, and non-zero otherwise. The The yield of \fBpcre2_regcomp()\fP is zero on success, and non-zero otherwise.
\fIpreg\fP structure is filled in on success, and one other member of the 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 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 number of capturing subpatterns in the regular expression. Various error codes
are defined in the header file. are defined in the header file.
.P .P
NOTE: If the yield of \fBregcomp()\fP is non-zero, you must not attempt to NOTE: If the yield of \fBpcre2_regcomp()\fP is non-zero, you must not attempt
use the contents of the \fIpreg\fP structure. If, for example, you pass it to to use the contents of the \fIpreg\fP structure. If, for example, you pass it
\fBregexec()\fP, the result is undefined and your program is likely to crash. to \fBpcre2_regexec()\fP, the result is undefined and your program is likely to
crash.
. .
. .
.SH "MATCHING NEWLINE CHARACTERS" .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 Default POSIX newline handling can be obtained by setting PCRE2_DOTALL and
PCRE2_DOLLAR_ENDONLY when calling \fBpcre2_compile()\fP directly, but there is 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 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 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. 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" .SH "MATCHING A PATTERN"
.rs .rs
.sp .sp
The function \fBregexec()\fP is called to match a compiled pattern \fIpreg\fP The function \fBpcre2_regexec()\fP is called to match a compiled pattern
against a given \fIstring\fP, which is by default terminated by a zero byte \fIpreg\fP against a given \fIstring\fP, which is by default terminated by a
(but see REG_STARTEND below), subject to the options in \fIeflags\fP. These can zero byte (but see REG_STARTEND below), subject to the options in \fIeflags\fP.
be: These can be:
.sp .sp
REG_NOTBOL REG_NOTBOL
.sp .sp
@ -263,7 +265,7 @@ are mutually exclusive; the error REG_INVARG is returned.
.P .P
If the pattern was compiled with the REG_NOSUB flag, no data about any matched 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 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 .P
The value of \fInmatch\fP may be zero, and the value \fIpmatch\fP may be NULL 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 (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" .SH "ERROR MESSAGES"
.rs .rs
.sp .sp
The \fBregerror()\fP function maps a non-zero errorcode from either The \fBpcre2_regerror()\fP function maps a non-zero errorcode from either
\fBregcomp()\fP or \fBregexec()\fP to a printable message. If \fIpreg\fP is not \fBpcre2_regcomp()\fP or \fBpcre2_regexec()\fP to a printable message. If
NULL, the error should have arisen from the use of that structure. A message \fIpreg\fP is not NULL, the error should have arisen from the use of that
terminated by a binary zero is placed in \fIerrbuf\fP. If the buffer is too structure. A message terminated by a binary zero is placed in \fIerrbuf\fP. If
short, only the first \fIerrbuf_size\fP - 1 characters of the error message are the buffer is too short, only the first \fIerrbuf_size\fP - 1 characters of the
used. The yield of the function is the size of buffer needed to hold the whole error message are used. The yield of the function is the size of buffer needed
message, including the terminating zero. This value is greater than to hold the whole message, including the terminating zero. This value is
\fIerrbuf_size\fP if the message was truncated. greater than \fIerrbuf_size\fP if the message was truncated.
. .
. .
.SH MEMORY USAGE .SH MEMORY USAGE
.rs .rs
.sp .sp
Compiling a regular expression causes memory to be allocated and associated Compiling a regular expression causes memory to be allocated and associated
with the \fIpreg\fP structure. The function \fBregfree()\fP frees all such with the \fIpreg\fP structure. The function \fBpcre2_regfree()\fP frees all
memory, after which \fIpreg\fP may no longer be used as a compiled expression. such memory, after which \fIpreg\fP may no longer be used as a compiled
expression.
. .
. .
.SH AUTHOR .SH AUTHOR
@ -318,6 +321,6 @@ Cambridge, England.
.rs .rs
.sp .sp
.nf .nf
Last updated: 19 September 2018 Last updated: 30 January 2019
Copyright (c) 1997-2018 University of Cambridge. Copyright (c) 1997-2019 University of Cambridge.
.fi .fi

25
src/pcre2posix.c
View File

@ -7,7 +7,7 @@ and semantics are as close as possible to those of the Perl 5 language.
Written by Philip Hazel Written by Philip Hazel
Original API code Copyright (c) 1997-2012 University of Cambridge 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 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 /* This module is a wrapper that provides a POSIX API to the underlying PCRE2
functions. The operative functions are called pcre2_regcomp(), etc., with functions. The operative functions are called pcre2_regcomp(), etc., with
wrappers that use the plain POSIX names. This makes it easier for an wrappers that use the plain POSIX names. In addition, pcre2posix.h defines the
application to be sure it gets the PCRE2 versions in the presence of other POSIX names as macros for the pcre2_xxx functions, so any program that includes
POSIX regex libraries. */ 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 #ifdef HAVE_CONFIG_H
@ -177,24 +179,39 @@ static const char *const pstring[] = {
* Wrappers with traditional POSIX names * * 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 PCRE2POSIX_EXP_DEFN size_t PCRE2_CALL_CONVENTION
regerror(int errcode, const regex_t *preg, char *errbuf, size_t errbuf_size) regerror(int errcode, const regex_t *preg, char *errbuf, size_t errbuf_size)
{ {
return pcre2_regerror(errcode, preg, errbuf, 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 PCRE2POSIX_EXP_DEFN void PCRE2_CALL_CONVENTION
regfree(regex_t *preg) regfree(regex_t *preg)
{ {
pcre2_regfree(preg); pcre2_regfree(preg);
} }
#undef regcomp
PCRE2POSIX_EXP_DECL int regcomp(regex_t *, const char *, int);
PCRE2POSIX_EXP_DEFN int PCRE2_CALL_CONVENTION PCRE2POSIX_EXP_DEFN int PCRE2_CALL_CONVENTION
regcomp(regex_t *preg, const char *pattern, int cflags) regcomp(regex_t *preg, const char *pattern, int cflags)
{ {
return pcre2_regcomp(preg, pattern, 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 PCRE2POSIX_EXP_DEFN int PCRE2_CALL_CONVENTION
regexec(const regex_t *preg, const char *string, size_t nmatch, regexec(const regex_t *preg, const char *string, size_t nmatch,
regmatch_t pmatch[], int eflags) regmatch_t pmatch[], int eflags)

29
src/pcre2posix.h
View File

@ -9,7 +9,7 @@ POSIX wrapper interface.
Written by Philip Hazel Written by Philip Hazel
Original API code Copyright (c) 1997-2012 University of Cambridge 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 Redistribution and use in source and binary forms, with or without
@ -139,22 +139,29 @@ file. */
#endif #endif
/* The functions. The actual code is in functions with pcre2_xxx names for /* 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 uniqueness. POSIX names are provided as macros for API compatibility with POSIX
they get them from the PCRE2 library and not by accident from elsewhere. */ 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 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, PCRE2POSIX_EXP_DECL int pcre2_regexec(const regex_t *, const char *, size_t,
regmatch_t *, int); 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 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 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 #ifdef __cplusplus
} /* extern "C" */ } /* extern "C" */