Update pcre2_pattern_info to return a length if "where" is NULL.

This commit is contained in:
Philip.Hazel 2014-10-16 16:49:23 +00:00
parent 54b96723cd
commit 2f27ca131d
2 changed files with 81 additions and 35 deletions

View File

@ -1,4 +1,4 @@
.TH PCRE2API 3 "14 October 2014" "PCRE2 10.00" .TH PCRE2API 3 "16 October 2014" "PCRE2 10.00"
.SH NAME .SH NAME
PCRE2 - Perl-compatible regular expressions (revised API) PCRE2 - Perl-compatible regular expressions (revised API)
.sp .sp
@ -757,13 +757,16 @@ documentation has more details about these optional features.
.P .P
The first argument for \fBpcre2_config()\fP specifies which information is The first argument for \fBpcre2_config()\fP specifies which information is
required. The second argument is a pointer to memory into which the information required. The second argument is a pointer to memory into which the information
is placed. If NULL is passed, the function returns the number of bytes that are is placed. If NULL is passed, the function returns the amount of memory that is
needed for the requested information. For calls that return numerical values, needed for the requested information. For calls that return numerical values,
\fIwhere\fP should point to appropriately aligned memory. the value is in bytes; when requesting these values, \fIwhere\fP should point
to appropriately aligned memory. For calls that return strings, the required
length is given in code units, not counting the terminating zero.
.P .P
The returned value from \fBpcre2_config()\fP is non-negative on success, or the When requesting information, the returned value from \fBpcre2_config()\fP is
negative error code PCRE2_ERROR_BADOPTION if the value in the first argument is non-negative on success, or the negative error code PCRE2_ERROR_BADOPTION if
not recognized. The following information is available: the value in the first argument is not recognized. The following information is
available:
.sp .sp
PCRE2_CONFIG_BSR PCRE2_CONFIG_BSR
.sp .sp
@ -779,12 +782,13 @@ compiling is available; otherwise it is set to zero.
.sp .sp
PCRE2_CONFIG_JITTARGET PCRE2_CONFIG_JITTARGET
.sp .sp
The \fIwhere\fP argument should point to a buffer that is at least 64 code The \fIwhere\fP argument should point to a buffer that is at least 48 code
units long. It is filled with a string that contains the name of the units long. (The exact length needed can be found by calling
architecture for which the JIT compiler is configured, for example "x86 32bit \fBpcre2_config()\fP with \fBwhere\fP set to NULL.) The buffer is filled with a
(little endian + unaligned)". If JIT support is not available, string that contains the name of the architecture for which the JIT compiler is
PCRE2_ERROR_BADOPTION is returned, otherwise the length of the string, in code configured, for example "x86 32bit (little endian + unaligned)". If JIT support
units, is returned. is not available, PCRE2_ERROR_BADOPTION is returned, otherwise the length of
the string, in code units, is returned.
.sp .sp
PCRE2_CONFIG_LINKSIZE PCRE2_CONFIG_LINKSIZE
.sp .sp
@ -847,10 +851,12 @@ heap instead of recursive function calls.
PCRE2_CONFIG_UNICODE_VERSION PCRE2_CONFIG_UNICODE_VERSION
.sp .sp
The \fIwhere\fP argument should point to a buffer that is at least 24 code The \fIwhere\fP argument should point to a buffer that is at least 24 code
units long. If PCRE2 has been compiled without Unicode support, this is filled units long. (The exact length needed can be found by calling
with the text "Unicode not supported". Otherwise, the Unicode version string \fBpcre2_config()\fP with \fBwhere\fP set to NULL.) If PCRE2 has been compiled
(for example, "7.0.0") is inserted. The string is zero-terminated. The function without Unicode support, the buffer is filled with the text "Unicode not
returns the length of the string in code units. supported". Otherwise, the Unicode version string (for example, "7.0.0") is
inserted. The string is zero-terminated. The function returns the length of the
string in code units.
.sp .sp
PCRE2_CONFIG_UNICODE PCRE2_CONFIG_UNICODE
.sp .sp
@ -860,8 +866,10 @@ otherwise it is set to zero. Unicode support implies UTF support.
PCRE2_CONFIG_VERSION PCRE2_CONFIG_VERSION
.sp .sp
The \fIwhere\fP argument should point to a buffer that is at least 12 code The \fIwhere\fP argument should point to a buffer that is at least 12 code
units long. It is filled with the PCRE2 version string, zero-terminated. The units long. (The exact length needed can be found by calling
length of the string (in code units) is returned. \fBpcre2_config()\fP with \fBwhere\fP set to NULL.) The buffer is filled with
the PCRE2 version string, zero-terminated. The length of the string (in code
units) is returned.
. .
. .
.SH "COMPILING A PATTERN" .SH "COMPILING A PATTERN"
@ -1350,20 +1358,20 @@ can be processed in different locales.
The \fBpcre2_pattern_info()\fP function returns information about a compiled The \fBpcre2_pattern_info()\fP function returns information about a compiled
pattern. The first argument is a pointer to the compiled pattern. The second pattern. The first argument is a pointer to the compiled pattern. The second
argument specifies which piece of information is required, and the third argument specifies which piece of information is required, and the third
argument is a pointer to a variable to receive the data. The yield of the argument is a pointer to a variable to receive the data. If the third argument
function is zero for success, or one of the following negative numbers: is NULL, the first argument is ignored, and the function returns the size in
bytes of the variable that is required for the information requested.
Otherwise, The yield of the function is zero for success, or one of the
following negative numbers:
.sp .sp
PCRE2_ERROR_NULL the argument \fIcode\fP was NULL PCRE2_ERROR_NULL the argument \fIcode\fP was NULL
the argument \fIwhere\fP was NULL
PCRE2_ERROR_BADMAGIC the "magic number" was not found PCRE2_ERROR_BADMAGIC the "magic number" was not found
PCRE2_ERROR_BADOPTION the value of \fIwhat\fP was invalid PCRE2_ERROR_BADOPTION the value of \fIwhat\fP was invalid
PCRE2_ERROR_UNSET the requested field is not set PCRE2_ERROR_UNSET the requested field is not set
.sp .sp
The "magic number" is placed at the start of each compiled pattern as an simple The "magic number" is placed at the start of each compiled pattern as an simple
check against passing an arbitrary memory pointer. check against passing an arbitrary memory pointer. Here is a typical call of
Here is \fBpcre2_pattern_info()\fP, to obtain the length of the compiled pattern:
a typical call of \fBpcre2_pattern_info()\fP, to obtain the length of the compiled
pattern:
.sp .sp
int rc; int rc;
size_t length; size_t length;
@ -2624,6 +2632,6 @@ Cambridge CB2 3QH, England.
.rs .rs
.sp .sp
.nf .nf
Last updated: 14 October 2014 Last updated: 16 October 2014
Copyright (c) 1997-2014 University of Cambridge. Copyright (c) 1997-2014 University of Cambridge.
.fi .fi

View File

@ -54,9 +54,11 @@ POSSIBILITY OF SUCH DAMAGE.
Arguments: Arguments:
code points to compiled code code points to compiled code
what what information is required what what information is required
where where to put the information where where to put the information; if NULL, return length
Returns: 0 if data returned, negative on error or unset value Returns: 0 when data returned
> 0 when length requested
< 0 on error or unset value
*/ */
PCRE2_EXP_DEFN int PCRE2_CALL_CONVENTION PCRE2_EXP_DEFN int PCRE2_CALL_CONVENTION
@ -64,7 +66,44 @@ pcre2_pattern_info(const pcre2_code *code, uint32_t what, void *where)
{ {
const pcre2_real_code *re = (pcre2_real_code *)code; const pcre2_real_code *re = (pcre2_real_code *)code;
if (re == NULL || where == NULL) return PCRE2_ERROR_NULL; if (where == NULL) /* Requests field length */
{
switch(what)
{
case PCRE2_INFO_ALLOPTIONS:
case PCRE2_INFO_ARGOPTIONS:
case PCRE2_INFO_BACKREFMAX:
case PCRE2_INFO_BSR:
case PCRE2_INFO_CAPTURECOUNT:
case PCRE2_INFO_FIRSTCODETYPE:
case PCRE2_INFO_FIRSTCODEUNIT:
case PCRE2_INFO_HASCRORLF:
case PCRE2_INFO_JCHANGED:
case PCRE2_INFO_LASTCODETYPE:
case PCRE2_INFO_LASTCODEUNIT:
case PCRE2_INFO_MATCHEMPTY:
case PCRE2_INFO_MATCHLIMIT:
case PCRE2_INFO_MAXLOOKBEHIND:
case PCRE2_INFO_MINLENGTH:
case PCRE2_INFO_NAMEENTRYSIZE:
case PCRE2_INFO_NAMECOUNT:
case PCRE2_INFO_NEWLINE:
case PCRE2_INFO_RECURSIONLIMIT:
return sizeof(uint32_t);
case PCRE2_INFO_FIRSTBITMAP:
return sizeof(const uint8_t *);
case PCRE2_INFO_JITSIZE:
case PCRE2_INFO_SIZE:
return sizeof(size_t);
case PCRE2_INFO_NAMETABLE:
return sizeof(PCRE2_SPTR);
}
}
if (re == NULL) return PCRE2_ERROR_NULL;
/* Check that the first field in the block is the magic number. If it is not, /* Check that the first field in the block is the magic number. If it is not,
return with PCRE2_ERROR_BADMAGIC. */ return with PCRE2_ERROR_BADMAGIC. */
@ -85,8 +124,7 @@ with different endianness. */
/* Check that this pattern was compiled in the correct bit mode */ /* Check that this pattern was compiled in the correct bit mode */
if ((re->flags & (PCRE2_CODE_UNIT_WIDTH/8)) == 0) if ((re->flags & (PCRE2_CODE_UNIT_WIDTH/8)) == 0) return PCRE2_ERROR_BADMODE;
return PCRE2_ERROR_BADMODE;
switch(what) switch(what)
{ {