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

Return an error code when pcre2_get_error_message() does not recognize an error 

code, and add a pcre2test facility for testing this.
This commit is contained in:
Philip.Hazel 2016-06-17 11:30:27 +00:00
parent 16acce6555
commit 0a29ecbe02
13 changed files with 689 additions and 441 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
ChangeLog
View File

@ -136,6 +136,13 @@ RunTest (see 4 above).
35. Fix potential negative index in pcre2test.
36. Calls to pcre2_get_error_message() with error numbers that are never
returned by PCRE2 functions were returning empty strings. Now the error code
PCRE2_ERROR_BADDATA is returned. A facility has been added to pcre2test to
show the texts for given error numbers (i.e. to call pcre2_get_error_message()
and display what it returns) and a few representative error codes are now
checked in RunTest.
Version 10.21 12-January-2016
-----------------------------

1
RunTest
View File

@ -499,6 +499,7 @@ for bmode in "$test8" "$test16" "$test32"; do
for opt in "" $jitopt; do
$sim $valgrind ${opt:+$vjs} ./pcre2test -q $test2stack $bmode $opt $testdata/testinput2 testtry
if [ $? = 0 ] ; then
$sim $valgrind ${opt:+$vjs} ./pcre2test -q $bmode $opt -error -63,-62,-2,-1,0,100,188,189 >>testtry
checkresult $? 2 "$opt"
else
echo " "

5
doc/html/pcre2_get_error_message.html
View File

@ -35,7 +35,10 @@ errors are negative numbers. The arguments are:
<i>bufflen</i> the length of the buffer (code units)
</pre>
The function returns the length of the message, excluding the trailing zero, or
a negative error code if the buffer is too small.
the negative error code PCRE2_ERROR_NOMEMORY if the buffer is too small. In
this case, the returned message is truncated (but still with a trailing zero).
If <i>errorcode</i> does not contain a recognized error code number, the
negative value PCRE2_ERROR_BADDATA is returned.
</P>
<P>
There is a complete description of the PCRE2 native API in the

123
doc/html/pcre2api.html
View File

@ -43,16 +43,17 @@ please consult the man page, in case the conversion went wrong.
<li><a name="TOC28" href="#SEC28">HOW PCRE2_MATCH() RETURNS A STRING AND CAPTURED SUBSTRINGS</a>
<li><a name="TOC29" href="#SEC29">OTHER INFORMATION ABOUT A MATCH</a>
<li><a name="TOC30" href="#SEC30">ERROR RETURNS FROM <b>pcre2_match()</b></a>
<li><a name="TOC31" href="#SEC31">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a>
<li><a name="TOC32" href="#SEC32">EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS</a>
<li><a name="TOC33" href="#SEC33">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a>
<li><a name="TOC34" href="#SEC34">CREATING A NEW STRING WITH SUBSTITUTIONS</a>
<li><a name="TOC35" href="#SEC35">DUPLICATE SUBPATTERN NAMES</a>
<li><a name="TOC36" href="#SEC36">FINDING ALL POSSIBLE MATCHES AT ONE POSITION</a>
<li><a name="TOC37" href="#SEC37">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a>
<li><a name="TOC38" href="#SEC38">SEE ALSO</a>
<li><a name="TOC39" href="#SEC39">AUTHOR</a>
<li><a name="TOC40" href="#SEC40">REVISION</a>
<li><a name="TOC31" href="#SEC31">OBTAINING A TEXTUAL ERROR MESSAGE</a>
<li><a name="TOC32" href="#SEC32">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a>
<li><a name="TOC33" href="#SEC33">EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS</a>
<li><a name="TOC34" href="#SEC34">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a>
<li><a name="TOC35" href="#SEC35">CREATING A NEW STRING WITH SUBSTITUTIONS</a>
<li><a name="TOC36" href="#SEC36">DUPLICATE SUBPATTERN NAMES</a>
<li><a name="TOC37" href="#SEC37">FINDING ALL POSSIBLE MATCHES AT ONE POSITION</a>
<li><a name="TOC38" href="#SEC38">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a>
<li><a name="TOC39" href="#SEC39">SEE ALSO</a>
<li><a name="TOC40" href="#SEC40">AUTHOR</a>
<li><a name="TOC41" href="#SEC41">REVISION</a>
</ul>
<P>
<b>#include &#60;pcre2.h&#62;</b>
@ -1063,7 +1064,7 @@ The <b>pcre2_compile()</b> function compiles a pattern into an internal form.
The pattern is defined by a pointer to a string of code units and a length. If
the pattern is zero-terminated, the length can be specified as
PCRE2_ZERO_TERMINATED. The function returns a pointer to a block of memory that
contains the compiled pattern and related data.
contains the compiled pattern and related data, or NULL if an error occurred.
</P>
<P>
If the compile context argument <i>ccontext</i> is NULL, memory for the compiled
@ -1085,8 +1086,9 @@ to acquire a private copy of shared compiled code.
<P>
NOTE: When one of the matching functions is called, pointers to the compiled
pattern and the subject string are set in the match data block so that they can
be referenced by the extraction functions. After running a match, you must not
free a compiled pattern (or a subject string) until after all operations on the
be referenced by the substring extraction functions. After running a match, you
must not free a compiled pattern (or a subject string) until after all
operations on the
<a href="#matchdatablock">match data block</a>
have taken place.
</P>
@ -1113,13 +1115,20 @@ newline setting) can be provided in a compile context (as described
</P>
<P>
If <i>errorcode</i> or <i>erroroffset</i> is NULL, <b>pcre2_compile()</b> returns
NULL immediately. Otherwise, if compilation of a pattern fails,
<b>pcre2_compile()</b> returns NULL, having set these variables to an error code
and an offset (number of code units) within the pattern, respectively. The
<b>pcre2_get_error_message()</b> function provides a textual message for each
error code. Compilation errors are positive numbers, but UTF formatting errors
are negative numbers. For an invalid UTF-8 or UTF-16 string, the offset is that
of the first code unit of the failing character.
NULL immediately. Otherwise, the variables to which these point are set to an
error code and an offset (number of code units) within the pattern,
respectively, when <b>pcre2_compile()</b> returns NULL because a compilation
error has occurred. The values are not defined when compilation is successful
and <b>pcre2_compile()</b> returns a non-NULL value.
</P>
<P>
The <b>pcre2_get_error_message()</b> function (see "Obtaining a textual error
message"
<a href="#geterrormessage">below)</a>
provides a textual message for each error code. Compilation errors have
positive error codes; UTF formatting error codes are negative. For an invalid
UTF-8 or UTF-16 string, the offset is that of the first code unit of the
failing character.
</P>
<P>
Some errors are not detected until the whole pattern has been scanned; in these
@ -1488,13 +1497,16 @@ page.
</P>
<br><a name="SEC19" href="#TOC1">COMPILATION ERROR CODES</a><br>
<P>
There are over 80 positive error codes that <b>pcre2_compile()</b> may return if
it finds an error in the pattern. There are also some negative error codes that
are used for invalid UTF strings. These are the same as given by
<b>pcre2_match()</b> and <b>pcre2_dfa_match()</b>, and are described in the
There are over 80 positive error codes that <b>pcre2_compile()</b> may return
(via <i>errorcode</i>) if it finds an error in the pattern. There are also some
negative error codes that are used for invalid UTF strings. These are the same
as given by <b>pcre2_match()</b> and <b>pcre2_dfa_match()</b>, and are described
in the
<a href="pcre2unicode.html"><b>pcre2unicode</b></a>
page. The <b>pcre2_get_error_message()</b> function can be called to obtain a
textual error message from any error code.
page. The <b>pcre2_get_error_message()</b> function (see "Obtaining a textual
error message"
<a href="#geterrormessage">below)</a>
can be called to obtain a textual error message from any error code.
<a name="jitcompiling"></a></P>
<br><a name="SEC20" href="#TOC1">JUST-IN-TIME (JIT) COMPILATION</a><br>
<P>
@ -2416,11 +2428,13 @@ page.
<br><a name="SEC30" href="#TOC1">ERROR RETURNS FROM <b>pcre2_match()</b></a><br>
<P>
If <b>pcre2_match()</b> fails, it returns a negative number. This can be
converted to a text string by calling <b>pcre2_get_error_message()</b>. Negative
error codes are also returned by other functions, and are documented with them.
The codes are given names in the header file. If UTF checking is in force and
an invalid UTF subject string is detected, one of a number of UTF-specific
negative error codes is returned. Details are given in the
converted to a text string by calling the <b>pcre2_get_error_message()</b>
function (see "Obtaining a textual error message"
<a href="#geterrormessage">below).</a>
Negative error codes are also returned by other functions, and are documented
with them. The codes are given names in the header file. If UTF checking is in
force and an invalid UTF subject string is detected, one of a number of
UTF-specific negative error codes is returned. Details are given in the
<a href="pcre2unicode.html"><b>pcre2unicode</b></a>
page. The following are the other errors that may be returned by
<b>pcre2_match()</b>:
@ -2521,8 +2535,29 @@ is attempted.
PCRE2_ERROR_RECURSIONLIMIT
</pre>
The internal recursion limit was reached.
<a name="geterrormessage"></a></P>
<br><a name="SEC31" href="#TOC1">OBTAINING A TEXTUAL ERROR MESSAGE</a><br>
<P>
<b>int pcre2_get_error_message(int <i>errorcode</i>, PCRE2_UCHAR *<i>buffer</i>,</b>
<b> PCRE2_SIZE <i>bufflen</i>);</b>
</P>
<P>
A text message for an error code from any PCRE2 function (compile, match, or
auxiliary) can be obtained by calling <b>pcre2_get_error_message()</b>. The code
is passed as the first argument, with the remaining two arguments specifying a
code unit buffer and its length, into which the text message is placed. Note
that the message is returned in code units of the appropriate width for the
library that is being used.
</P>
<P>
The returned message is terminated with a trailing zero, and the function
returns the number of code units used, excluding the trailing zero. If the
error number is unknown, the negative error code PCRE2_ERROR_BADDATA is
returned. If the buffer is too small, the message is truncated (but still with
a trailing zero), and the negative error code PCRE2_ERROR_NOMEMORY is returned.
None of the messages are very long; a buffer size of 120 code units is ample.
<a name="extractbynumber"></a></P>
<br><a name="SEC31" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br>
<br><a name="SEC32" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br>
<P>
<b>int pcre2_substring_length_bynumber(pcre2_match_data *<i>match_data</i>,</b>
<b> uint32_t <i>number</i>, PCRE2_SIZE *<i>length</i>);</b>
@ -2619,7 +2654,7 @@ The substring did not participate in the match. For example, if the pattern is
(abc)|(def) and the subject is "def", and the ovector contains at least two
capturing slots, substring number 1 is unset.
</P>
<br><a name="SEC32" href="#TOC1">EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS</a><br>
<br><a name="SEC33" href="#TOC1">EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS</a><br>
<P>
<b>int pcre2_substring_list_get(pcre2_match_data *<i>match_data</i>,</b>
<b>" PCRE2_UCHAR ***<i>listptr</i>, PCRE2_SIZE **<i>lengthsptr</i>);</b>
@ -2658,7 +2693,7 @@ can be distinguished from a genuine zero-length substring by inspecting the
appropriate offset in the ovector, which contain PCRE2_UNSET for unset
substrings, or by calling <b>pcre2_substring_length_bynumber()</b>.
<a name="extractbyname"></a></P>
<br><a name="SEC33" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a><br>
<br><a name="SEC34" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a><br>
<P>
<b>int pcre2_substring_number_from_name(const pcre2_code *<i>code</i>,</b>
<b> PCRE2_SPTR <i>name</i>);</b>
@ -2718,7 +2753,7 @@ names are not included in the compiled code. The matching process uses only
numbers. For this reason, the use of different names for subpatterns of the
same number causes an error at compile time.
</P>
<br><a name="SEC34" href="#TOC1">CREATING A NEW STRING WITH SUBSTITUTIONS</a><br>
<br><a name="SEC35" href="#TOC1">CREATING A NEW STRING WITH SUBSTITUTIONS</a><br>
<P>
<b>int pcre2_substitute(const pcre2_code *<i>code</i>, PCRE2_SPTR <i>subject</i>,</b>
<b> PCRE2_SIZE <i>length</i>, PCRE2_SIZE <i>startoffset</i>,</b>
@ -2921,9 +2956,11 @@ started, which can happen if \K is used in an assertion).
</P>
<P>
As for all PCRE2 errors, a text message that describes the error can be
obtained by calling <b>pcre2_get_error_message()</b>.
obtained by calling the <b>pcre2_get_error_message()</b> function (see
"Obtaining a textual error message"
<a href="#geterrormessage">above).</a>
</P>
<br><a name="SEC35" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br>
<br><a name="SEC36" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br>
<P>
<b>int pcre2_substring_nametable_scan(const pcre2_code *<i>code</i>,</b>
<b> PCRE2_SPTR <i>name</i>, PCRE2_SPTR *<i>first</i>, PCRE2_SPTR *<i>last</i>);</b>
@ -2968,7 +3005,7 @@ in the section entitled <i>Information about a pattern</i>. Given all the
relevant entries for the name, you can extract each of their numbers, and hence
the captured data.
</P>
<br><a name="SEC36" href="#TOC1">FINDING ALL POSSIBLE MATCHES AT ONE POSITION</a><br>
<br><a name="SEC37" href="#TOC1">FINDING ALL POSSIBLE MATCHES AT ONE POSITION</a><br>
<P>
The traditional matching function uses a similar algorithm to Perl, which stops
when it finds the first match at a given point in the subject. If you want to
@ -2986,7 +3023,7 @@ substring. Then return 1, which forces <b>pcre2_match()</b> to backtrack and try
other alternatives. Ultimately, when it runs out of matches,
<b>pcre2_match()</b> will yield PCRE2_ERROR_NOMATCH.
<a name="dfamatch"></a></P>
<br><a name="SEC37" href="#TOC1">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a><br>
<br><a name="SEC38" href="#TOC1">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a><br>
<P>
<b>int pcre2_dfa_match(const pcre2_code *<i>code</i>, PCRE2_SPTR <i>subject</i>,</b>
<b> PCRE2_SIZE <i>length</i>, PCRE2_SIZE <i>startoffset</i>,</b>
@ -3181,13 +3218,13 @@ some plausibility checks are made on the contents of the workspace, which
should contain data about the previous partial match. If any of these checks
fail, this error is given.
</P>
<br><a name="SEC38" href="#TOC1">SEE ALSO</a><br>
<br><a name="SEC39" href="#TOC1">SEE ALSO</a><br>
<P>
<b>pcre2build</b>(3), <b>pcre2callout</b>(3), <b>pcre2demo(3)</b>,
<b>pcre2matching</b>(3), <b>pcre2partial</b>(3), <b>pcre2posix</b>(3),
<b>pcre2sample</b>(3), <b>pcre2stack</b>(3), <b>pcre2unicode</b>(3).
</P>
<br><a name="SEC39" href="#TOC1">AUTHOR</a><br>
<br><a name="SEC40" href="#TOC1">AUTHOR</a><br>
<P>
Philip Hazel
<br>
@ -3196,9 +3233,9 @@ University Computing Service
Cambridge, England.
<br>
</P>
<br><a name="SEC40" href="#TOC1">REVISION</a><br>
<br><a name="SEC41" href="#TOC1">REVISION</a><br>
<P>
Last updated: 05 June 2016
Last updated: 17 June 2016
<br>
Copyright &copy; 1997-2016 University of Cambridge.
<br>

39
doc/html/pcre2test.html
View File

@ -98,7 +98,7 @@ further data is read.
</P>
<P>
For maximum portability, therefore, it is safest to avoid non-printing
characters in <b>pcre2test</b> input files. There is a facility for specifying
characters in <b>pcre2test</b> input files. There is a facility for specifying
some or all of a pattern's characters as hexadecimal pairs, thus making it
possible to include binary zeroes in a pattern for testing purposes. Subject
lines are processed for backslash escapes, which makes it possible to include
@ -179,6 +179,13 @@ using the <b>pcre2_dfa_match()</b> function instead of the default
<b>pcre2_match()</b>.
</P>
<P>
<b>-error</b> <i>number[,number,...]</i>
Call <b>pcre2_get_error_message()</b> for each of the error numbers in the
comma-separated list, display the resulting messages on the standard output,
then exit with zero exit code. The numbers may be positive or negative. This is
a convenience facility for PCRE2 maintainers.
</P>
<P>
<b>-help</b>
Output a brief summary these options and then exit.
</P>
@ -572,7 +579,7 @@ about the pattern:
null_context compile with a NULL context
parens_nest_limit=&#60;n&#62; set maximum parentheses depth
posix use the POSIX API
posix_nosub use the POSIX API with REG_NOSUB
posix_nosub use the POSIX API with REG_NOSUB
push push compiled pattern onto the stack
pushcopy push a copy onto the stack
stackguard=&#60;number&#62; test the stackguard feature
@ -662,22 +669,22 @@ default values).
Specifying pattern characters in hexadecimal
</b><br>
<P>
The <b>hex</b> modifier specifies that the characters of the pattern, except for
The <b>hex</b> modifier specifies that the characters of the pattern, except for
substrings enclosed in single or double quotes, are to be interpreted as pairs
of hexadecimal digits. This feature is provided as a way of creating patterns
that contain binary zeros and other non-printing characters. White space is
permitted between pairs of digits. For example, this pattern contains three
permitted between pairs of digits. For example, this pattern contains three
characters:
<pre>
/ab 32 59/hex
</pre>
Parts of such a pattern are taken literally if quoted. This pattern contains
Parts of such a pattern are taken literally if quoted. This pattern contains
nine characters, only two of which are specified in hexadecimal:
<pre>
/ab "literal" 32/hex
</pre>
Either single or double quotes may be used. There is no way of including
the delimiter within a substring.
the delimiter within a substring.
</P>
<P>
By default, <b>pcre2test</b> passes patterns as zero-terminated strings to
@ -935,8 +942,8 @@ line to contain a new pattern (or a command) instead of a subject line. This
facility is used when saving compiled patterns to a file, as described in the
section entitled "Saving and restoring compiled patterns"
<a href="#saverestore">below. If <b>pushcopy</b> is used instead of <b>push</b>, a copy of the compiled</a>
pattern is stacked, leaving the original as current, ready to match the
following input lines. This provides a way of testing the
pattern is stacked, leaving the original as current, ready to match the
following input lines. This provides a way of testing the
<b>pcre2_code_copy()</b> function.
The <b>push</b> and <b>pushcopy </b> modifiers are incompatible with compilation
modifiers such as <b>global</b> that act at match time. Any that are specified
@ -962,7 +969,7 @@ for a description of their effects.
anchored set PCRE2_ANCHORED
dfa_restart set PCRE2_DFA_RESTART
dfa_shortest set PCRE2_DFA_SHORTEST
no_jit set PCRE2_NO_JIT
no_jit set PCRE2_NO_JIT
no_utf_check set PCRE2_NO_UTF_CHECK
notbol set PCRE2_NOTBOL
notempty set PCRE2_NOTEMPTY
@ -1023,7 +1030,7 @@ pattern.
substitute_unset_empty use PCRE2_SUBSTITUTE_UNSET_EMPTY
zero_terminate pass the subject as zero-terminated
</pre>
The effects of these modifiers are described in the following sections. When
The effects of these modifiers are described in the following sections. When
matching via the POSIX wrapper API, the <b>aftertext</b>, <b>allaftertext</b>,
and <b>ovector</b> subject modifiers work as described below. All other
modifiers are either ignored, with a warning message, or cause an error.
@ -1537,8 +1544,8 @@ item to be tested. For example:
This output indicates that callout number 0 occurred for a match attempt
starting at the fourth character of the subject string, when the pointer was at
the seventh character, and when the next pattern item was \d. Just
one circumflex is output if the start and current positions are the same, or if
the current position precedes the start position, which can happen if the
one circumflex is output if the start and current positions are the same, or if
the current position precedes the start position, which can happen if the
callout is in a lookbehind assertion.
</P>
<P>
@ -1636,7 +1643,7 @@ the <b>pushcopy</b> modifier causes a copy of the compiled pattern to be
stacked, leaving the original available for immediate matching. By using
<b>push</b> and/or <b>pushcopy</b>, a number of patterns can be compiled and
retained. These modifiers are incompatible with <b>posix</b>, and control
modifiers that act at match time are ignored (with a message) for the stacked
modifiers that act at match time are ignored (with a message) for the stacked
patterns. The <b>jitverify</b> modifier applies only at compile time.
</P>
<P>
@ -1677,8 +1684,8 @@ If <b>jitverify</b> is used with #pop, it does not automatically imply
<b>jit</b>, which is different behaviour from when it is used on a pattern.
</P>
<P>
The #popcopy command is analagous to the <b>pushcopy</b> modifier in that it
makes current a copy of the topmost stack pattern, leaving the original still
The #popcopy command is analagous to the <b>pushcopy</b> modifier in that it
makes current a copy of the topmost stack pattern, leaving the original still
on the stack.
</P>
<br><a name="SEC19" href="#TOC1">SEE ALSO</a><br>
@ -1698,7 +1705,7 @@ Cambridge, England.
</P>
<br><a name="SEC21" href="#TOC1">REVISION</a><br>
<P>
Last updated: 05 June 2016
Last updated: 17 June 2016
<br>
Copyright &copy; 1997-2016 University of Cambridge.
<br>

669
doc/pcre2.txt
View File

File diff suppressed because it is too large Load Diff

7
doc/pcre2_get_error_message.3
View File

@ -1,4 +1,4 @@
.TH PCRE2_GET_ERROR_MESSAGE 3 "21 October 2014" "PCRE2 10.00"
.TH PCRE2_GET_ERROR_MESSAGE 3 "17 June 2016" "PCRE2 10.22"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.SH SYNOPSIS
@ -23,7 +23,10 @@ errors are negative numbers. The arguments are:
\fIbufflen\fP the length of the buffer (code units)
.sp
The function returns the length of the message, excluding the trailing zero, or
a negative error code if the buffer is too small.
the negative error code PCRE2_ERROR_NOMEMORY if the buffer is too small. In
this case, the returned message is truncated (but still with a trailing zero).
If \fIerrorcode\fP does not contain a recognized error code number, the
negative value PCRE2_ERROR_BADDATA is returned.
.P
There is a complete description of the PCRE2 native API in the
.\" HREF

98
doc/pcre2api.3
View File

@ -1,4 +1,4 @@
.TH PCRE2API 3 "05 June 2016" "PCRE2 10.22"
.TH PCRE2API 3 "17 June 2016" "PCRE2 10.22"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.sp
@ -1032,7 +1032,7 @@ The \fBpcre2_compile()\fP function compiles a pattern into an internal form.
The pattern is defined by a pointer to a string of code units and a length. If
the pattern is zero-terminated, the length can be specified as
PCRE2_ZERO_TERMINATED. The function returns a pointer to a block of memory that
contains the compiled pattern and related data.
contains the compiled pattern and related data, or NULL if an error occurred.
.P
If the compile context argument \fIccontext\fP is NULL, memory for the compiled
pattern is obtained by calling \fBmalloc()\fP. Otherwise, it is obtained from
@ -1054,8 +1054,9 @@ to acquire a private copy of shared compiled code.
.P
NOTE: When one of the matching functions is called, pointers to the compiled
pattern and the subject string are set in the match data block so that they can
be referenced by the extraction functions. After running a match, you must not
free a compiled pattern (or a subject string) until after all operations on the
be referenced by the substring extraction functions. After running a match, you
must not free a compiled pattern (or a subject string) until after all
operations on the
.\" HTML <a href="#matchdatablock">
.\" </a>
match data block
@ -1086,13 +1087,22 @@ above).
.\"
.P
If \fIerrorcode\fP or \fIerroroffset\fP is NULL, \fBpcre2_compile()\fP returns
NULL immediately. Otherwise, if compilation of a pattern fails,
\fBpcre2_compile()\fP returns NULL, having set these variables to an error code
and an offset (number of code units) within the pattern, respectively. The
\fBpcre2_get_error_message()\fP function provides a textual message for each
error code. Compilation errors are positive numbers, but UTF formatting errors
are negative numbers. For an invalid UTF-8 or UTF-16 string, the offset is that
of the first code unit of the failing character.
NULL immediately. Otherwise, the variables to which these point are set to an
error code and an offset (number of code units) within the pattern,
respectively, when \fBpcre2_compile()\fP returns NULL because a compilation
error has occurred. The values are not defined when compilation is successful
and \fBpcre2_compile()\fP returns a non-NULL value.
.P
The \fBpcre2_get_error_message()\fP function (see "Obtaining a textual error
message"
.\" HTML <a href="#geterrormessage">
.\" </a>
below)
.\"
provides a textual message for each error code. Compilation errors have
positive error codes; UTF formatting error codes are negative. For an invalid
UTF-8 or UTF-16 string, the offset is that of the first code unit of the
failing character.
.P
Some errors are not detected until the whole pattern has been scanned; in these
cases, the offset passed back is the length of the pattern. Note that the
@ -1479,15 +1489,21 @@ page.
.SH "COMPILATION ERROR CODES"
.rs
.sp
There are over 80 positive error codes that \fBpcre2_compile()\fP may return if
it finds an error in the pattern. There are also some negative error codes that
are used for invalid UTF strings. These are the same as given by
\fBpcre2_match()\fP and \fBpcre2_dfa_match()\fP, and are described in the
There are over 80 positive error codes that \fBpcre2_compile()\fP may return
(via \fIerrorcode\fP) if it finds an error in the pattern. There are also some
negative error codes that are used for invalid UTF strings. These are the same
as given by \fBpcre2_match()\fP and \fBpcre2_dfa_match()\fP, and are described
in the
.\" HREF
\fBpcre2unicode\fP
.\"
page. The \fBpcre2_get_error_message()\fP function can be called to obtain a
textual error message from any error code.
page. The \fBpcre2_get_error_message()\fP function (see "Obtaining a textual
error message"
.\" HTML <a href="#geterrormessage">
.\" </a>
below)
.\"
can be called to obtain a textual error message from any error code.
.
.
.\" HTML <a name="jitcompiling"></a>
@ -2454,11 +2470,16 @@ page.
.rs
.sp
If \fBpcre2_match()\fP fails, it returns a negative number. This can be
converted to a text string by calling \fBpcre2_get_error_message()\fP. Negative
error codes are also returned by other functions, and are documented with them.
The codes are given names in the header file. If UTF checking is in force and
an invalid UTF subject string is detected, one of a number of UTF-specific
negative error codes is returned. Details are given in the
converted to a text string by calling the \fBpcre2_get_error_message()\fP
function (see "Obtaining a textual error message"
.\" HTML <a href="#geterrormessage">
.\" </a>
below).
.\"
Negative error codes are also returned by other functions, and are documented
with them. The codes are given names in the header file. If UTF checking is in
force and an invalid UTF subject string is detected, one of a number of
UTF-specific negative error codes is returned. Details are given in the
.\" HREF
\fBpcre2unicode\fP
.\"
@ -2571,6 +2592,30 @@ is attempted.
The internal recursion limit was reached.
.
.
.\" HTML <a name="geterrormessage"></a>
.SH "OBTAINING A TEXTUAL ERROR MESSAGE"
.rs
.sp
.nf
.B int pcre2_get_error_message(int \fIerrorcode\fP, PCRE2_UCHAR *\fIbuffer\fP,
.B " PCRE2_SIZE \fIbufflen\fP);"
.fi
.P
A text message for an error code from any PCRE2 function (compile, match, or
auxiliary) can be obtained by calling \fBpcre2_get_error_message()\fP. The code
is passed as the first argument, with the remaining two arguments specifying a
code unit buffer and its length, into which the text message is placed. Note
that the message is returned in code units of the appropriate width for the
library that is being used.
.P
The returned message is terminated with a trailing zero, and the function
returns the number of code units used, excluding the trailing zero. If the
error number is unknown, the negative error code PCRE2_ERROR_BADDATA is
returned. If the buffer is too small, the message is truncated (but still with
a trailing zero), and the negative error code PCRE2_ERROR_NOMEMORY is returned.
None of the messages are very long; a buffer size of 120 code units is ample.
.
.
.\" HTML <a name="extractbynumber"></a>
.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"
.rs
@ -2948,7 +2993,12 @@ substitution), and PCRE2_BADSUBPATTERN (the pattern match ended before it
started, which can happen if \eK is used in an assertion).
.P
As for all PCRE2 errors, a text message that describes the error can be
obtained by calling \fBpcre2_get_error_message()\fP.
obtained by calling the \fBpcre2_get_error_message()\fP function (see
"Obtaining a textual error message"
.\" HTML <a href="#geterrormessage">
.\" </a>
above).
.\"
.
.
.SH "DUPLICATE SUBPATTERN NAMES"
@ -3242,6 +3292,6 @@ Cambridge, England.
.rs
.sp
.nf
Last updated: 05 June 2016
Last updated: 17 June 2016
Copyright (c) 1997-2016 University of Cambridge.
.fi

44
doc/pcre2test.1
View File

@ -1,4 +1,4 @@
.TH PCRE2TEST 1 "05 June 2016" "PCRE 10.22"
.TH PCRE2TEST 1 "17 June 2016" "PCRE 10.22"
.SH NAME
pcre2test - a program for testing Perl-compatible regular expressions.
.SH SYNOPSIS
@ -68,7 +68,7 @@ environments character 26 (hex 1A) causes an immediate end of file, and no
further data is read.
.P
For maximum portability, therefore, it is safest to avoid non-printing
characters in \fBpcre2test\fP input files. There is a facility for specifying
characters in \fBpcre2test\fP input files. There is a facility for specifying
some or all of a pattern's characters as hexadecimal pairs, thus making it
possible to include binary zeroes in a pattern for testing purposes. Subject
lines are processed for backslash escapes, which makes it possible to include
@ -143,6 +143,12 @@ Behave as if each subject line has the \fBdfa\fP modifier; matching is done
using the \fBpcre2_dfa_match()\fP function instead of the default
\fBpcre2_match()\fP.
.TP 10
\fB-error\fP \fInumber[,number,...]\fP
Call \fBpcre2_get_error_message()\fP for each of the error numbers in the
comma-separated list, display the resulting messages on the standard output,
then exit with zero exit code. The numbers may be positive or negative. This is
a convenience facility for PCRE2 maintainers.
.TP 10
\fB-help\fP
Output a brief summary these options and then exit.
.TP 10
@ -536,7 +542,7 @@ about the pattern:
null_context compile with a NULL context
parens_nest_limit=<n> set maximum parentheses depth
posix use the POSIX API
posix_nosub use the POSIX API with REG_NOSUB
posix_nosub use the POSIX API with REG_NOSUB
push push compiled pattern onto the stack
pushcopy push a copy onto the stack
stackguard=<number> test the stackguard feature
@ -621,22 +627,22 @@ default values).
.SS "Specifying pattern characters in hexadecimal"
.rs
.sp
The \fBhex\fP modifier specifies that the characters of the pattern, except for
The \fBhex\fP modifier specifies that the characters of the pattern, except for
substrings enclosed in single or double quotes, are to be interpreted as pairs
of hexadecimal digits. This feature is provided as a way of creating patterns
that contain binary zeros and other non-printing characters. White space is
permitted between pairs of digits. For example, this pattern contains three
permitted between pairs of digits. For example, this pattern contains three
characters:
.sp
/ab 32 59/hex
.sp
Parts of such a pattern are taken literally if quoted. This pattern contains
Parts of such a pattern are taken literally if quoted. This pattern contains
nine characters, only two of which are specified in hexadecimal:
.sp
/ab "literal" 32/hex
.sp
.sp
Either single or double quotes may be used. There is no way of including
the delimiter within a substring.
the delimiter within a substring.
.P
By default, \fBpcre2test\fP passes patterns as zero-terminated strings to
\fBpcre2_compile()\fP, giving the length as PCRE2_ZERO_TERMINATED. However, for
@ -897,9 +903,9 @@ facility is used when saving compiled patterns to a file, as described in the
section entitled "Saving and restoring compiled patterns"
.\" HTML <a href="#saverestore">
.\" </a>
below. If \fBpushcopy\fP is used instead of \fBpush\fP, a copy of the compiled
pattern is stacked, leaving the original as current, ready to match the
following input lines. This provides a way of testing the
below. If \fBpushcopy\fP is used instead of \fBpush\fP, a copy of the compiled
pattern is stacked, leaving the original as current, ready to match the
following input lines. This provides a way of testing the
\fBpcre2_code_copy()\fP function.
.\"
The \fBpush\fP and \fBpushcopy \fP modifiers are incompatible with compilation
@ -931,7 +937,7 @@ for a description of their effects.
anchored set PCRE2_ANCHORED
dfa_restart set PCRE2_DFA_RESTART
dfa_shortest set PCRE2_DFA_SHORTEST
no_jit set PCRE2_NO_JIT
no_jit set PCRE2_NO_JIT
no_utf_check set PCRE2_NO_UTF_CHECK
notbol set PCRE2_NOTBOL
notempty set PCRE2_NOTEMPTY
@ -991,7 +997,7 @@ pattern.
substitute_unset_empty use PCRE2_SUBSTITUTE_UNSET_EMPTY
zero_terminate pass the subject as zero-terminated
.sp
The effects of these modifiers are described in the following sections. When
The effects of these modifiers are described in the following sections. When
matching via the POSIX wrapper API, the \fBaftertext\fP, \fBallaftertext\fP,
and \fBovector\fP subject modifiers work as described below. All other
modifiers are either ignored, with a warning message, or cause an error.
@ -1499,8 +1505,8 @@ item to be tested. For example:
This output indicates that callout number 0 occurred for a match attempt
starting at the fourth character of the subject string, when the pointer was at
the seventh character, and when the next pattern item was \ed. Just
one circumflex is output if the start and current positions are the same, or if
the current position precedes the start position, which can happen if the
one circumflex is output if the start and current positions are the same, or if
the current position precedes the start position, which can happen if the
callout is in a lookbehind assertion.
.P
Callouts numbered 255 are assumed to be automatic callouts, inserted as a
@ -1602,7 +1608,7 @@ the \fBpushcopy\fP modifier causes a copy of the compiled pattern to be
stacked, leaving the original available for immediate matching. By using
\fBpush\fP and/or \fBpushcopy\fP, a number of patterns can be compiled and
retained. These modifiers are incompatible with \fBposix\fP, and control
modifiers that act at match time are ignored (with a message) for the stacked
modifiers that act at match time are ignored (with a message) for the stacked
patterns. The \fBjitverify\fP modifier applies only at compile time.
.P
The command
@ -1647,8 +1653,8 @@ reloads two patterns.
If \fBjitverify\fP is used with #pop, it does not automatically imply
\fBjit\fP, which is different behaviour from when it is used on a pattern.
.P
The #popcopy command is analagous to the \fBpushcopy\fP modifier in that it
makes current a copy of the topmost stack pattern, leaving the original still
The #popcopy command is analagous to the \fBpushcopy\fP modifier in that it
makes current a copy of the topmost stack pattern, leaving the original still
on the stack.
.
.
@ -1675,6 +1681,6 @@ Cambridge, England.
.rs
.sp
.nf
Last updated: 05 June 2016
Last updated: 17 June 2016
Copyright (c) 1997-2016 University of Cambridge.
.fi

9
doc/pcre2test.txt
View File

@ -138,6 +138,13 @@ COMMAND LINE OPTIONS
is done using the pcre2_dfa_match() function instead of the
default pcre2_match().
-error number[,number,...]
Call pcre2_get_error_message() for each of the error numbers
in the comma-separated list, display the resulting messages
on the standard output, then exit with zero exit code. The
numbers may be positive or negative. This is a convenience
facility for PCRE2 maintainers.
-help Output a brief summary these options and then exit.
-i Behave as if each pattern has the /info modifier; information
@ -1539,5 +1546,5 @@ AUTHOR
REVISION
Last updated: 05 June 2016
Last updated: 17 June 2016
Copyright (c) 1997-2016 University of Cambridge.

18
src/pcre2_error.c
View File

@ -252,7 +252,7 @@ static const unsigned char match_error_texts[] =
/* 60 */
"match with end before start is not supported\0"
"too many replacements (more than INT_MAX)\0"
"bad serialized data\0"
"bad serialized data\0"
;
@ -277,32 +277,32 @@ Returns: length of message if all is well
PCRE2_EXP_DEFN int PCRE2_CALL_CONVENTION
pcre2_get_error_message(int enumber, PCRE2_UCHAR *buffer, size_t size)
{
char xbuff[128];
const unsigned char *message;
size_t i;
int n;
if (size == 0) return PCRE2_ERROR_NOMEMORY;
if (enumber > COMPILE_ERROR_BASE) /* Compile error */
if (enumber >= COMPILE_ERROR_BASE) /* Compile error */
{
message = compile_error_texts;
n = enumber - COMPILE_ERROR_BASE;
}
else /* Match or UTF error */
else if (enumber < 0) /* Match or UTF error */
{
message = match_error_texts;
n = -enumber;
}
else /* Invalid error number */
{
message = (unsigned char *)"\0"; /* Empty message list */
n = 1;
}
for (; n > 0; n--)
{
while (*message++ != CHAR_NULL) {};
if (*message == CHAR_NULL)
{
sprintf(xbuff, "No text for error %d", enumber);
break;
}
if (*message == CHAR_NULL) return PCRE2_ERROR_BADDATA;
}
for (i = 0; *message != 0; i++)

102
src/pcre2test.c
View File

@ -3018,9 +3018,9 @@ for (;;)
dlen = strlen((char *)here);
here += dlen;
/* Check for end of line reached. Take care not to read data from before
/* Check for end of line reached. Take care not to read data from before
start (dlen will be zero for a file starting with a binary zero). */
if (here > start && here[-1] == '\n') return start;
/* If we have not read a newline when reading a file, we have either filled
@ -4774,7 +4774,7 @@ if ((pat_patctl.control & CTL_POSIX) != 0)
if (rc != 0)
{
size_t bsize, usize;
int psize;
int psize;
preg.re_pcre2_code = NULL; /* In case something was left in there */
preg.re_match_data = NULL;
@ -4784,9 +4784,9 @@ if ((pat_patctl.control & CTL_POSIX) != 0)
if (bsize + 8 < pbuffer8_size)
memcpy(pbuffer8 + bsize, "DEADBEEF", 8);
usize = regerror(rc, &preg, (char *)pbuffer8, bsize);
/* Inside regerror(), snprintf() is used. If the buffer is too small, some
versions of snprintf() put a zero byte at the end, but others do not.
/* Inside regerror(), snprintf() is used. If the buffer is too small, some
versions of snprintf() put a zero byte at the end, but others do not.
Therefore, we print a maximum of one less than the size of the buffer. */
psize = (int)bsize - 1;
@ -6885,6 +6885,7 @@ printf(" pcre2-32 32 bit library support enabled [0, 1]\n");
printf(" unicode Unicode and UTF support enabled [0, 1]\n");
printf(" -d set default pattern control 'debug'\n");
printf(" -dfa set default subject control 'dfa'\n");
printf(" -error <n,m,..> show messages for error numbers, then exit\n");
printf(" -help show usage information\n");
printf(" -i set default pattern control 'info'\n");
printf(" -jit set default pattern control 'jit'\n");
@ -7062,6 +7063,7 @@ BOOL showtotaltimes = FALSE;
BOOL skipping = FALSE;
char *arg_subject = NULL;
char *arg_pattern = NULL;
char *arg_error = NULL;
/* The offsets to the options and control bits fields of the pattern and data
control blocks must be the same so that common options and controls such as
@ -7273,6 +7275,12 @@ while (argc > 1 && argv[op][0] == '-' && argv[op][1] != 0)
/* The following options save their data for processing once we know what
the running mode is. */
else if (strcmp(arg, "-error") == 0)
{
arg_error = argv[op+1];
goto CHECK_VALUE_EXISTS;
}
else if (strcmp(arg, "-subject") == 0)
{
arg_subject = argv[op+1];
@ -7306,6 +7314,88 @@ while (argc > 1 && argv[op][0] == '-' && argv[op][1] != 0)
argc--;
}
/* If -error was present, get the error numbers, show the messages, and exit.
We wait to do this until we know which mode we are in. */
if (arg_error != NULL)
{
int len;
int errcode;
char *endptr;
/* Ensure the relevant non-8-bit buffer is available. */
#ifdef SUPPORT_PCRE2_16
if (test_mode == PCRE16_MODE)
{
pbuffer16_size = 256;
pbuffer16 = (uint16_t *)malloc(pbuffer16_size);
if (pbuffer16 == NULL)
{
fprintf(stderr, "pcre2test: malloc(%lu) failed for pbuffer16\n",
(unsigned long int)pbuffer16_size);
yield = 1;
goto EXIT;
}
}
#endif
#ifdef SUPPORT_PCRE2_32
if (test_mode == PCRE32_MODE)
{
pbuffer32_size = 256;
pbuffer32 = (uint32_t *)malloc(pbuffer32_size);
if (pbuffer32 == NULL)
{
fprintf(stderr, "pcre2test: malloc(%lu) failed for pbuffer32\n",
(unsigned long int)pbuffer32_size);
yield = 1;
goto EXIT;
}
}
#endif
/* Loop along a list of error numbers. */
for (;;)
{
errcode = strtol(arg_error, &endptr, 10);
if (*endptr != 0 && *endptr != CHAR_COMMA)
{
fprintf(stderr, "** '%s' is not a valid error number list\n", arg_error);
yield = 1;
goto EXIT;
}
printf("Error %d: ", errcode);
PCRE2_GET_ERROR_MESSAGE(len, errcode, pbuffer);
if (len < 0)
{
switch (len)
{
case PCRE2_ERROR_BADDATA:
printf("PCRE2_ERROR_BADDATA (unknown error number)");
break;
case PCRE2_ERROR_NOMEMORY:
printf("PCRE2_ERROR_NOMEMORY (buffer too small)");
break;
default:
printf("Unexpected return (%d) from pcre2_get_error_message()", len);
break;
}
}
else
{
PCHARSV(CASTVAR(void *, pbuffer), 0, len, FALSE, stdout);
}
printf("\n");
if (*endptr == 0) goto EXIT;
arg_error = endptr + 1;
}
/* Control never reaches here */
} /* End of -error handling */
/* Initialize things that cannot be done until we know which test mode we are
running in. When HEAP_MATCH_RECURSE is undefined, calling pcre2_set_recursion_
memory_management() is a no-op, but we call it in order to exercise it. Also

8
testdata/testoutput2 vendored
View File

@ -15187,3 +15187,11 @@ Failed: error 122 at offset 10: unmatched closing parenthesis
No match
# End of testinput2
Error -63: PCRE2_ERROR_BADDATA (unknown error number)
Error -62: bad serialized data
Error -2: partial match
Error -1: no match
Error 0: PCRE2_ERROR_BADDATA (unknown error number)
Error 100: no error
Error 188: pattern string is longer than the limit set by the application
Error 189: PCRE2_ERROR_BADDATA (unknown error number)