Revision: 116
http://www.exim.org/viewvc/pcre2?view=rev&revision=116
Author: ph10
Date: 2014-10-16 17:49:23 +0100 (Thu, 16 Oct 2014)
Log Message:
-----------
Update pcre2_pattern_info to return a length if "where" is NULL.
Modified Paths:
--------------
code/trunk/doc/pcre2api.3
code/trunk/src/pcre2_pattern_info.c
Modified: code/trunk/doc/pcre2api.3
===================================================================
--- code/trunk/doc/pcre2api.3 2014-10-16 16:22:44 UTC (rev 115)
+++ code/trunk/doc/pcre2api.3 2014-10-16 16:49:23 UTC (rev 116)
@@ -1,4 +1,4 @@
-.TH PCRE2API 3 "14 October 2014" "PCRE2 10.00"
+.TH PCRE2API 3 "16 October 2014" "PCRE2 10.00"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.sp
@@ -757,13 +757,16 @@
.P
The first argument for \fBpcre2_config()\fP specifies which information is
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,
-\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
-The returned value from \fBpcre2_config()\fP is non-negative on success, or the
-negative error code PCRE2_ERROR_BADOPTION if the value in the first argument is
-not recognized. The following information is available:
+When requesting information, the returned value from \fBpcre2_config()\fP is
+non-negative on success, or the negative error code PCRE2_ERROR_BADOPTION if
+the value in the first argument is not recognized. The following information is
+available:
.sp
PCRE2_CONFIG_BSR
.sp
@@ -779,12 +782,13 @@
.sp
PCRE2_CONFIG_JITTARGET
.sp
-The \fIwhere\fP argument should point to a buffer that is at least 64 code
-units long. It is filled with a string that contains the name of the
-architecture for which the JIT compiler is configured, for example "x86 32bit
-(little endian + unaligned)". If JIT support is not available,
-PCRE2_ERROR_BADOPTION is returned, otherwise the length of the string, in code
-units, is returned.
+The \fIwhere\fP argument should point to a buffer that is at least 48 code
+units long. (The exact length needed can be found by calling
+\fBpcre2_config()\fP with \fBwhere\fP set to NULL.) The buffer is filled with a
+string that contains the name of the architecture for which the JIT compiler is
+configured, for example "x86 32bit (little endian + unaligned)". If JIT support
+is not available, PCRE2_ERROR_BADOPTION is returned, otherwise the length of
+the string, in code units, is returned.
.sp
PCRE2_CONFIG_LINKSIZE
.sp
@@ -847,10 +851,12 @@
PCRE2_CONFIG_UNICODE_VERSION
.sp
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
-with the text "Unicode not 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.
+units long. (The exact length needed can be found by calling
+\fBpcre2_config()\fP with \fBwhere\fP set to NULL.) If PCRE2 has been compiled
+without Unicode support, the buffer is filled with the text "Unicode not
+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
PCRE2_CONFIG_UNICODE
.sp
@@ -859,9 +865,11 @@
.sp
PCRE2_CONFIG_VERSION
.sp
-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
-length of the string (in code units) is returned.
+The \fIwhere\fP argument should point to a buffer that is at least 12 code
+units long. (The exact length needed can be found by calling
+\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"
@@ -1350,20 +1358,20 @@
The \fBpcre2_pattern_info()\fP function returns information about a compiled
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 is a pointer to a variable to receive the data. The yield of the
-function is zero for success, or one of the following negative numbers:
+argument is a pointer to a variable to receive the data. If the third argument
+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
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_BADOPTION the value of \fIwhat\fP was invalid
PCRE2_ERROR_UNSET the requested field is not set
.sp
The "magic number" is placed at the start of each compiled pattern as an simple
-check against passing an arbitrary memory pointer.
-Here is
-a typical call of \fBpcre2_pattern_info()\fP, to obtain the length of the compiled
-pattern:
+check against passing an arbitrary memory pointer. Here is a typical call of
+\fBpcre2_pattern_info()\fP, to obtain the length of the compiled pattern:
.sp
int rc;
size_t length;
@@ -2624,6 +2632,6 @@
.rs
.sp
.nf
-Last updated: 14 October 2014
+Last updated: 16 October 2014
Copyright (c) 1997-2014 University of Cambridge.
.fi
Modified: code/trunk/src/pcre2_pattern_info.c
===================================================================
--- code/trunk/src/pcre2_pattern_info.c 2014-10-16 16:22:44 UTC (rev 115)
+++ code/trunk/src/pcre2_pattern_info.c 2014-10-16 16:49:23 UTC (rev 116)
@@ -54,9 +54,11 @@
Arguments:
code points to compiled code
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
@@ -64,8 +66,45 @@
{
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,
return with PCRE2_ERROR_BADMAGIC. */
@@ -85,8 +124,7 @@
/* Check that this pattern was compiled in the correct bit mode */
-if ((re->flags & (PCRE2_CODE_UNIT_WIDTH/8)) == 0)
- return PCRE2_ERROR_BADMODE;
+if ((re->flags & (PCRE2_CODE_UNIT_WIDTH/8)) == 0) return PCRE2_ERROR_BADMODE;
switch(what)
{
@@ -157,7 +195,7 @@
case PCRE2_INFO_MATCHLIMIT:
*((uint32_t *)where) = re->limit_match;
- if (re->limit_match == UINT32_MAX) return PCRE2_ERROR_UNSET;
+ if (re->limit_match == UINT32_MAX) return PCRE2_ERROR_UNSET;
break;
case PCRE2_INFO_MAXLOOKBEHIND:
@@ -177,7 +215,7 @@
break;
case PCRE2_INFO_NAMETABLE:
- *((PCRE2_SPTR*)where) = (PCRE2_SPTR)((char *)re + sizeof(pcre2_real_code));
+ *((PCRE2_SPTR *)where) = (PCRE2_SPTR)((char *)re + sizeof(pcre2_real_code));
break;
case PCRE2_INFO_NEWLINE:
@@ -186,7 +224,7 @@
case PCRE2_INFO_RECURSIONLIMIT:
*((uint32_t *)where) = re->limit_recursion;
- if (re->limit_recursion == UINT32_MAX) return PCRE2_ERROR_UNSET;
+ if (re->limit_recursion == UINT32_MAX) return PCRE2_ERROR_UNSET;
break;
case PCRE2_INFO_SIZE:
