embedaddon/pcre/doc/pcreapi.3 - diff

Return to pcreapi.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc

Diff for /embedaddon/pcre/doc/pcreapi.3 between versions 1.1.1.4 and 1.1.1.5

version 1.1.1.4, 2013/07/22 08:25:56	version 1.1.1.5, 2014/06/15 19:46:05
Line 1	Line 1
.TH PCREAPI 3 "12 May 2013" "PCRE 8.33"	.TH PCREAPI 3 "12 November 2013" "PCRE 8.34"
.SH NAME	.SH NAME
PCRE - Perl-compatible regular expressions	PCRE - Perl-compatible regular expressions
.sp	.sp
Line 8 PCRE - Perl-compatible regular expressions	Line 8 PCRE - Perl-compatible regular expressions
.SH "PCRE NATIVE API BASIC FUNCTIONS"	.SH "PCRE NATIVE API BASIC FUNCTIONS"
.rs	.rs
.sp	.sp
.SM	.nf
.B pcre pcre_compile(const char \fIpattern\fP, int \fIoptions\fP,	.B pcre pcre_compile(const char \fIpattern\fP, int \fIoptions\fP,
.ti +5n	.B " const char *\fIerrptr\fP, int \fIerroffset\fP,"
.B const char *\fIerrptr\fP, int \fIerroffset\fP,	.B " const unsigned char *\fItableptr\fP);"
.ti +5n	.sp
.B const unsigned char *\fItableptr\fP);
.PP
.B pcre pcre_compile2(const char \fIpattern\fP, int \fIoptions\fP,	.B pcre pcre_compile2(const char \fIpattern\fP, int \fIoptions\fP,
.ti +5n	.B " int *\fIerrorcodeptr\fP,"
.B int *\fIerrorcodeptr\fP,	.B " const char *\fIerrptr\fP, int \fIerroffset\fP,"
.ti +5n	.B " const unsigned char *\fItableptr\fP);"
.B const char *\fIerrptr\fP, int \fIerroffset\fP,	.sp
.ti +5n
.B const unsigned char *\fItableptr\fP);
.PP
.B pcre_extra pcre_study(const pcre \fIcode\fP, int \fIoptions\fP,	.B pcre_extra pcre_study(const pcre \fIcode\fP, int \fIoptions\fP,
.ti +5n	.B " const char **\fIerrptr\fP);"
.B const char **\fIerrptr\fP);	.B void pcre_free_study(pcre_extra *\fIextra\fP);
.PP
.B void pcre_free_study(pcre_extra *\fIextra\fP);	.B void pcre_free_study(pcre_extra *\fIextra\fP);
.PP	.sp
.B int pcre_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"	.B int pcre_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"
.ti +5n	.B " const char *\fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,	.B " int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);"
.ti +5n	.sp
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);
.PP
.B int pcre_dfa_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"	.B int pcre_dfa_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"
.ti +5n	.B " const char *\fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,	.B " int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,"
.ti +5n	.B " int *\fIworkspace\fP, int \fIwscount\fP);"
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,	.fi
.ti +5n
.B int *\fIworkspace\fP, int \fIwscount\fP);
.	.
.	.
.SH "PCRE NATIVE API STRING EXTRACTION FUNCTIONS"	.SH "PCRE NATIVE API STRING EXTRACTION FUNCTIONS"
.rs	.rs
.sp	.sp
	.nf
.B int pcre_copy_named_substring(const pcre *\fIcode\fP,	.B int pcre_copy_named_substring(const pcre *\fIcode\fP,
.ti +5n	.B " const char \fIsubject\fP, int \fIovector\fP,"
.B const char \fIsubject\fP, int \fIovector\fP,	.B " int \fIstringcount\fP, const char *\fIstringname\fP,"
.ti +5n	.B " char *\fIbuffer\fP, int \fIbuffersize\fP);"
.B int \fIstringcount\fP, const char *\fIstringname\fP,	.sp
.ti +5n
.B char *\fIbuffer\fP, int \fIbuffersize\fP);
.PP
.B int pcre_copy_substring(const char \fIsubject\fP, int \fIovector\fP,	.B int pcre_copy_substring(const char \fIsubject\fP, int \fIovector\fP,
.ti +5n	.B " int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,"
.B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,	.B " int \fIbuffersize\fP);"
.ti +5n	.sp
.B int \fIbuffersize\fP);
.PP
.B int pcre_get_named_substring(const pcre *\fIcode\fP,	.B int pcre_get_named_substring(const pcre *\fIcode\fP,
.ti +5n	.B " const char \fIsubject\fP, int \fIovector\fP,"
.B const char \fIsubject\fP, int \fIovector\fP,	.B " int \fIstringcount\fP, const char *\fIstringname\fP,"
.ti +5n	.B " const char **\fIstringptr\fP);"
.B int \fIstringcount\fP, const char *\fIstringname\fP,	.sp
.ti +5n
.B const char **\fIstringptr\fP);
.PP
.B int pcre_get_stringnumber(const pcre *\fIcode\fP,	.B int pcre_get_stringnumber(const pcre *\fIcode\fP,
.ti +5n	.B " const char *\fIname\fP);"
.B const char *\fIname\fP);	.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,
.PP
.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,	.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,
.ti +5n	.B " const char \fIname\fP, char \fIfirst\fP, char *\fIlast\fP);"
.B const char \fIname\fP, char \fIfirst\fP, char *\fIlast\fP);	.B int pcre_get_substring(const char \fIsubject\fP, int \fIovector\fP,
.PP
.B int pcre_get_substring(const char \fIsubject\fP, int \fIovector\fP,	.B int pcre_get_substring(const char \fIsubject\fP, int \fIovector\fP,
.ti +5n	.B " int \fIstringcount\fP, int \fIstringnumber\fP,"
.B int \fIstringcount\fP, int \fIstringnumber\fP,	.B " const char **\fIstringptr\fP);"
.ti +5n	.sp
.B const char **\fIstringptr\fP);
.PP
.B int pcre_get_substring_list(const char *\fIsubject\fP,	.B int pcre_get_substring_list(const char *\fIsubject\fP,
.ti +5n	.B " int \fIovector\fP, int \fIstringcount\fP, const char **\fIlistptr\fP);"
.B int \fIovector\fP, int \fIstringcount\fP, "const char **\fIlistptr\fP);"	.B void pcre_free_substring(const char *\fIstringptr\fP);
.PP
.B void pcre_free_substring(const char *\fIstringptr\fP);	.B void pcre_free_substring(const char *\fIstringptr\fP);
.PP	.sp
.B void pcre_free_substring_list(const char **\fIstringptr\fP);	.B void pcre_free_substring_list(const char **\fIstringptr\fP);
	.fi
.	.
.	.
.SH "PCRE NATIVE API AUXILIARY FUNCTIONS"	.SH "PCRE NATIVE API AUXILIARY FUNCTIONS"
.rs	.rs
.sp	.sp
	.nf
.B int pcre_jit_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"	.B int pcre_jit_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"
.ti +5n	.B " const char *\fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,	.B " int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,"
.ti +5n	.B " pcre_jit_stack *\fIjstack\fP);"
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,	.sp
.ti +5n
.B pcre_jit_stack *\fIjstack\fP);
.PP
.B pcre_jit_stack *pcre_jit_stack_alloc(int \fIstartsize\fP, int \fImaxsize\fP);	.B pcre_jit_stack *pcre_jit_stack_alloc(int \fIstartsize\fP, int \fImaxsize\fP);
.PP	.sp
.B void pcre_jit_stack_free(pcre_jit_stack *\fIstack\fP);	.B void pcre_jit_stack_free(pcre_jit_stack *\fIstack\fP);
.PP	.sp
.B void pcre_assign_jit_stack(pcre_extra *\fIextra\fP,	.B void pcre_assign_jit_stack(pcre_extra *\fIextra\fP,
.ti +5n	.B " pcre_jit_callback \fIcallback\fP, void *\fIdata\fP);"
.B pcre_jit_callback \fIcallback\fP, void *\fIdata\fP);	.B const unsigned char *pcre_maketables(void);
.PP
.B const unsigned char *pcre_maketables(void);	.B const unsigned char *pcre_maketables(void);
.PP	.sp
.B int pcre_fullinfo(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"	.B int pcre_fullinfo(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"
.ti +5n	.B " int \fIwhat\fP, void *\fIwhere\fP);"
.B int \fIwhat\fP, void *\fIwhere\fP);	.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);
.PP
.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);	.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);
.PP	.sp
.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);	.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);
.PP	.sp
.B const char *pcre_version(void);	.B const char *pcre_version(void);
.PP	.sp
.B int pcre_pattern_to_host_byte_order(pcre *\fIcode\fP,	.B int pcre_pattern_to_host_byte_order(pcre *\fIcode\fP,
.ti +5n	.B " pcre_extra \fIextra\fP, const unsigned char \fItables\fP);"
.B pcre_extra \fIextra\fP, const unsigned char \fItables\fP);	.
.	.
.	.
.SH "PCRE NATIVE API INDIRECTED FUNCTIONS"	.SH "PCRE NATIVE API INDIRECTED FUNCTIONS"
.rs	.rs
.sp	.sp
	.nf
.B void (pcre_malloc)(size_t);	.B void (pcre_malloc)(size_t);
.PP	.sp
.B void (pcre_free)(void );	.B void (pcre_free)(void );
.PP	.sp
.B void (pcre_stack_malloc)(size_t);	.B void (pcre_stack_malloc)(size_t);
.PP	.sp
.B void (pcre_stack_free)(void );	.B void (pcre_stack_free)(void );
.PP	.sp
.B int (pcre_callout)(pcre_callout_block );	.B int (pcre_callout)(pcre_callout_block );
	.fi
.	.
.	.
.SH "PCRE 8-BIT, 16-BIT, AND 32-BIT LIBRARIES"	.SH "PCRE 8-BIT, 16-BIT, AND 32-BIT LIBRARIES"
Line 483 the	Line 460 the
.\"	.\"
documentation.	documentation.
.sp	.sp
	PCRE_CONFIG_PARENS_LIMIT
	.sp
	The output is a long integer that gives the maximum depth of nesting of
	parentheses (of any kind) in a pattern. This limit is imposed to cap the amount
	of system stack used when a pattern is compiled. It is specified when PCRE is
	built; the default is 250.
	.sp
PCRE_CONFIG_MATCH_LIMIT	PCRE_CONFIG_MATCH_LIMIT
.sp	.sp
The output is a long integer that gives the default limit for the number of	The output is a long integer that gives the default limit for the number of
Line 509 avoiding the use of the stack.	Line 493 avoiding the use of the stack.
.SH "COMPILING A PATTERN"	.SH "COMPILING A PATTERN"
.rs	.rs
.sp	.sp
	.nf
.B pcre pcre_compile(const char \fIpattern\fP, int \fIoptions\fP,	.B pcre pcre_compile(const char \fIpattern\fP, int \fIoptions\fP,
.ti +5n	.B " const char *\fIerrptr\fP, int \fIerroffset\fP,"
.B const char *\fIerrptr\fP, int \fIerroffset\fP,	.B " const unsigned char *\fItableptr\fP);"
.ti +5n
.B const unsigned char *\fItableptr\fP);
.sp	.sp
.B pcre pcre_compile2(const char \fIpattern\fP, int \fIoptions\fP,	.B pcre pcre_compile2(const char \fIpattern\fP, int \fIoptions\fP,
.ti +5n	.B " int *\fIerrorcodeptr\fP,"
.B int *\fIerrorcodeptr\fP,	.B " const char *\fIerrptr\fP, int \fIerroffset\fP,"
.ti +5n	.B " const unsigned char *\fItableptr\fP);"
.B const char *\fIerrptr\fP, int \fIerroffset\fP,	.fi
.ti +5n
.B const unsigned char *\fItableptr\fP);
.P	.P
Either of the functions \fBpcre_compile()\fP or \fBpcre_compile2()\fP can be	Either of the functions \fBpcre_compile()\fP or \fBpcre_compile2()\fP can be
called to compile a pattern into an internal form. The only difference between	called to compile a pattern into an internal form. The only difference between
Line 581 If the final argument, \fItableptr\fP, is NULL, PCRE u	Line 562 If the final argument, \fItableptr\fP, is NULL, PCRE u
character tables that are built when PCRE is compiled, using the default C	character tables that are built when PCRE is compiled, using the default C
locale. Otherwise, \fItableptr\fP must be an address that is the result of a	locale. Otherwise, \fItableptr\fP must be an address that is the result of a
call to \fBpcre_maketables()\fP. This value is stored with the compiled	call to \fBpcre_maketables()\fP. This value is stored with the compiled
pattern, and used again by \fBpcre_exec()\fP, unless another table pointer is	pattern, and used again by \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP when the
passed to it. For more discussion, see the section on locale support below.	pattern is matched. For more discussion, see the section on locale support
	below.
.P	.P
This code fragment shows a typical straightforward call to \fBpcre_compile()\fP:	This code fragment shows a typical straightforward call to \fBpcre_compile()\fP:
.sp	.sp
Line 670 documentation.	Line 652 documentation.
.sp	.sp
PCRE_EXTENDED	PCRE_EXTENDED
.sp	.sp
If this bit is set, white space data characters in the pattern are totally	If this bit is set, most white space characters in the pattern are totally
ignored except when escaped or inside a character class. White space does not	ignored except when escaped or inside a character class. However, white space
include the VT character (code 11). In addition, characters between an	is not allowed within sequences such as (?> that introduce various
unescaped # outside a character class and the next newline, inclusive, are also	parenthesized subpatterns, nor within a numerical quantifier such as {1,3}.
ignored. This is equivalent to Perl's /x option, and it can be changed within a	However, ignorable white space is permitted between an item and a following
pattern by a (?x) option setting.	quantifier and between a quantifier and a following + that indicates
	possessiveness.
.P	.P
	White space did not used to include the VT character (code 11), because Perl
	did not treat this character as white space. However, Perl changed at release
	5.18, so PCRE followed at release 8.34, and VT is now treated as white space.
	.P
	PCRE_EXTENDED also causes characters between an unescaped # outside a character
	class and the next newline, inclusive, to be ignored. PCRE_EXTENDED is
	equivalent to Perl's /x option, and it can be changed within a pattern by a
	(?x) option setting.
	.P
Which characters are interpreted as newlines is controlled by the options	Which characters are interpreted as newlines is controlled by the options
passed to \fBpcre_compile()\fP or by a special sequence at the start of the	passed to \fBpcre_compile()\fP or by a special sequence at the start of the
pattern, as described in the section entitled	pattern, as described in the section entitled
Line 821 were followed by ?: but named parentheses can still be	Line 813 were followed by ?: but named parentheses can still be
they acquire numbers in the usual way). There is no equivalent of this option	they acquire numbers in the usual way). There is no equivalent of this option
in Perl.	in Perl.
.sp	.sp
	PCRE_NO_AUTO_POSSESS
	.sp
	If this option is set, it disables "auto-possessification". This is an
	optimization that, for example, turns a+b into a++b in order to avoid
	backtracks into a+ that can never be successful. However, if callouts are in
	use, auto-possessification means that some of them are never taken. You can set
	this option if you want the matching functions to do a full unoptimized search
	and run all the callouts, but it is mainly provided for testing purposes.
	.sp
PCRE_NO_START_OPTIMIZE	PCRE_NO_START_OPTIMIZE
.sp	.sp
This is an option that acts at matching time; that is, it is really an option	This is an option that acts at matching time; that is, it is really an option
Line 886 page. If an invalid UTF-8 sequence is found, \fBpcre_c	Line 887 page. If an invalid UTF-8 sequence is found, \fBpcre_c
error. If you already know that your pattern is valid, and you want to skip	error. If you already know that your pattern is valid, and you want to skip
this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK option.	this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK option.
When it is set, the effect of passing an invalid UTF-8 string as a pattern is	When it is set, the effect of passing an invalid UTF-8 string as a pattern is
undefined. It may cause your program to crash. Note that this option can also	undefined. It may cause your program to crash or loop. Note that this option
be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress the	can also be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress
validity checking of subject strings only. If the same string is being matched	the validity checking of subject strings only. If the same string is being
many times, the option can be safely set for the second and subsequent	matched many times, the option can be safely set for the second and subsequent
matchings to improve performance.	matchings to improve performance.
.	.
.	.
Line 936 have fallen out of use. To avoid confusion, they have	Line 937 have fallen out of use. To avoid confusion, they have
31 POSIX collating elements are not supported	31 POSIX collating elements are not supported
32 this version of PCRE is compiled without UTF support	32 this version of PCRE is compiled without UTF support
33 [this code is not in use]	33 [this code is not in use]
34 character value in \ex{...} sequence is too large	34 character value in \ex{} or \eo{} is too large
35 invalid condition (?(0)	35 invalid condition (?(0)
36 \eC not allowed in lookbehind assertion	36 \eC not allowed in lookbehind assertion
37 PCRE does not support \eL, \el, \eN{name}, \eU, or \eu	37 PCRE does not support \eL, \el, \eN{name}, \eU, or \eu
Line 984 have fallen out of use. To avoid confusion, they have	Line 985 have fallen out of use. To avoid confusion, they have
75 name is too long in (MARK), (PRUNE), (SKIP), or (THEN)	75 name is too long in (MARK), (PRUNE), (SKIP), or (THEN)
76 character value in \eu.... sequence is too large	76 character value in \eu.... sequence is too large
77 invalid UTF-32 string (specifically UTF-32)	77 invalid UTF-32 string (specifically UTF-32)
	78 setting UTF is disabled by the application
	79 non-hex character in \ex{} (closing brace missing?)
	80 non-octal character in \eo{} (closing brace missing?)
	81 missing opening brace after \eo
	82 parentheses are too deeply nested
	83 invalid range in character class
.sp	.sp
The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may	The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may
be used if the limits were changed when PCRE was built.	be used if the limits were changed when PCRE was built.
Line 993 be used if the limits were changed when PCRE was built	Line 1000 be used if the limits were changed when PCRE was built
.SH "STUDYING A PATTERN"	.SH "STUDYING A PATTERN"
.rs	.rs
.sp	.sp
.B pcre_extra pcre_study(const pcre \fIcode\fP, int \fIoptions\fP	.nf
.ti +5n	.B pcre_extra pcre_study(const pcre \fIcode\fP, int \fIoptions\fP,
.B const char **\fIerrptr\fP);	.B " const char **\fIerrptr\fP);"
	.fi
.PP	.PP
If a compiled pattern is going to be used several times, it is worth spending	If a compiled pattern is going to be used several times, it is worth spending
more time analyzing it in order to speed up the time taken for matching. The	more time analyzing it in order to speed up the time taken for matching. The
Line 1117 below.	Line 1125 below.
.sp	.sp
PCRE handles caseless matching, and determines whether characters are letters,	PCRE handles caseless matching, and determines whether characters are letters,
digits, or whatever, by reference to a set of tables, indexed by character	digits, or whatever, by reference to a set of tables, indexed by character
value. When running in UTF-8 mode, this applies only to characters	code point. When running in UTF-8 mode, or in the 16- or 32-bit libraries, this
with codes less than 128. By default, higher-valued codes never match escapes	applies only to characters with code points less than 256. By default,
such as \ew or \ed, but they can be tested with \ep if PCRE is built with	higher-valued code points never match escapes such as \ew or \ed. However, if
Unicode character property support. Alternatively, the PCRE_UCP option can be	PCRE is built with Unicode property support, all characters can be tested with
set at compile time; this causes \ew and friends to use Unicode property	\ep and \eP, or, alternatively, the PCRE_UCP option can be set when a pattern
support instead of built-in tables. The use of locales with Unicode is	is compiled; this causes \ew and friends to use Unicode property support
discouraged. If you are handling characters with codes greater than 128, you	instead of the built-in tables.
should either use UTF-8 and Unicode, or use locales, but not try to mix the
two.
.P	.P
	The use of locales with Unicode is discouraged. If you are handling characters
	with code points greater than 128, you should either use Unicode support, or
	use locales, but not try to mix the two.
	.P
PCRE contains an internal set of tables that are used when the final argument	PCRE contains an internal set of tables that are used when the final argument
of \fBpcre_compile()\fP is NULL. These are sufficient for many applications.	of \fBpcre_compile()\fP is NULL. These are sufficient for many applications.
Normally, the internal tables recognize only ASCII characters. However, when	Normally, the internal tables recognize only ASCII characters. However, when
Line 1140 for this locale support is expected to die away.	Line 1150 for this locale support is expected to die away.
.P	.P
External tables are built by calling the \fBpcre_maketables()\fP function,	External tables are built by calling the \fBpcre_maketables()\fP function,
which has no arguments, in the relevant locale. The result can then be passed	which has no arguments, in the relevant locale. The result can then be passed
to \fBpcre_compile()\fP or \fBpcre_exec()\fP as often as necessary. For	to \fBpcre_compile()\fP as often as necessary. For example, to build and use
example, to build and use tables that are appropriate for the French locale	tables that are appropriate for the French locale (where accented characters
(where accented characters with values greater than 128 are treated as letters),	with values greater than 128 are treated as letters), the following code could
the following code could be used:	be used:
.sp	.sp
setlocale(LC_CTYPE, "fr_FR");	setlocale(LC_CTYPE, "fr_FR");
tables = pcre_maketables();	tables = pcre_maketables();
Line 1159 needed.	Line 1169 needed.
.P	.P
The pointer that is passed to \fBpcre_compile()\fP is saved with the compiled	The pointer that is passed to \fBpcre_compile()\fP is saved with the compiled
pattern, and the same tables are used via this pointer by \fBpcre_study()\fP	pattern, and the same tables are used via this pointer by \fBpcre_study()\fP
and normally also by \fBpcre_exec()\fP. Thus, by default, for any single	and also by \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP. Thus, for any single
pattern, compilation, studying and matching all happen in the same locale, but	pattern, compilation, studying and matching all happen in the same locale, but
different patterns can be compiled in different locales.	different patterns can be processed in different locales.
.P	.P
It is possible to pass a table pointer or NULL (indicating the use of the	It is possible to pass a table pointer or NULL (indicating the use of the
internal tables) to \fBpcre_exec()\fP. Although not intended for this purpose,	internal tables) to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP (see the
this facility could be used to match a pattern in a different locale from the	discussion below in the section on matching a pattern). This facility is
one in which it was compiled. Passing table pointers at run time is discussed	provided for use with pre-compiled patterns that have been saved and reloaded.
below in the section on matching a pattern.	Character tables are not saved with patterns, so if a non-standard table was
	used at compile time, it must be provided again when the reloaded pattern is
	matched. Attempting to use this facility to match a pattern in a different
	locale from the one in which it was compiled is likely to lead to anomalous
	(usually incorrect) results.
.	.
.	.
.\" HTML <a name="infoaboutpattern"></a>	.\" HTML <a name="infoaboutpattern"></a>
.SH "INFORMATION ABOUT A PATTERN"	.SH "INFORMATION ABOUT A PATTERN"
.rs	.rs
.sp	.sp
	.nf
.B int pcre_fullinfo(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"	.B int pcre_fullinfo(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"
.ti +5n	.B " int \fIwhat\fP, void *\fIwhere\fP);"
.B int \fIwhat\fP, void *\fIwhere\fP);	.PP
.PP	.PP
The \fBpcre_fullinfo()\fP function returns information about a compiled	The \fBpcre_fullinfo()\fP function returns information about a compiled
pattern. It replaces the \fBpcre_info()\fP function, which was removed from the	pattern. It replaces the \fBpcre_info()\fP function, which was removed from the
Line 1310 only if it follows something of variable length. For e	Line 1325 only if it follows something of variable length. For e
is -1.	is -1.
.P	.P
Since for the 32-bit library using the non-UTF-32 mode, this function is unable	Since for the 32-bit library using the non-UTF-32 mode, this function is unable
to return the full 32-bit range of the character, this value is deprecated;	to return the full 32-bit range of characters, this value is deprecated;
instead the PCRE_INFO_REQUIREDCHARFLAGS and PCRE_INFO_REQUIREDCHAR values should	instead the PCRE_INFO_REQUIREDCHARFLAGS and PCRE_INFO_REQUIREDCHAR values should
be used.	be used.
.sp	.sp
	PCRE_INFO_MATCH_EMPTY
	.sp
	Return 1 if the pattern can match an empty string, otherwise 0. The fourth
	argument should point to an \fBint\fP variable.
	.sp
PCRE_INFO_MATCHLIMIT	PCRE_INFO_MATCHLIMIT
.sp	.sp
If the pattern set a match limit by including an item of the form	If the pattern set a match limit by including an item of the form
Line 1369 most significant byte first. In the 16-bit library, th	Line 1389 most significant byte first. In the 16-bit library, th
contains the parenthesis number. The rest of the entry is the corresponding	contains the parenthesis number. The rest of the entry is the corresponding
name, zero terminated.	name, zero terminated.
.P	.P
The names are in alphabetical order. Duplicate names may appear if (?\| is used	The names are in alphabetical order. If (?\| is used to create multiple groups
to create multiple groups with the same number, as described in the	with the same number, as described in the
.\" HTML <a href="pcrepattern.html#dupsubpatternnumber">	.\" HTML <a href="pcrepattern.html#dupsubpatternnumber">
.\" </a>	.\" </a>
section on duplicate subpattern numbers	section on duplicate subpattern numbers
Line 1379 in the	Line 1399 in the
.\" HREF	.\" HREF
\fBpcrepattern\fP	\fBpcrepattern\fP
.\"	.\"
page. Duplicate names for subpatterns with different numbers are permitted only	page, the groups may be given the same name, but there is only one entry in the
if PCRE_DUPNAMES is set. In all cases of duplicate names, they appear in the	table. Different names for groups of the same number are not permitted.
table in the order in which they were found in the pattern. In the absence of	Duplicate names for subpatterns with different numbers are permitted,
(?\| this is the order of increasing number; when (?\| is used this is not	but only if PCRE_DUPNAMES is set. They appear in the table in the order in
necessarily the case because later subpatterns may have lower numbers.	which they were found in the pattern. In the absence of (?\| this is the order
	of increasing number; when (?\| is used this is not necessarily the case because
	later subpatterns may have lower numbers.
.P	.P
As a simple example of the name/number table, consider the following pattern	As a simple example of the name/number table, consider the following pattern
after compilation by the 8-bit library (assume PCRE_EXTENDED is set, so white	after compilation by the 8-bit library (assume PCRE_EXTENDED is set, so white
Line 1501 returned. For anchored patterns, 0 is returned.	Line 1523 returned. For anchored patterns, 0 is returned.
.sp	.sp
PCRE_INFO_FIRSTCHARACTER	PCRE_INFO_FIRSTCHARACTER
.sp	.sp
Return the fixed first character value, if PCRE_INFO_FIRSTCHARACTERFLAGS	Return the fixed first character value in the situation where
returned 1; otherwise returns 0. The fourth argument should point to an	PCRE_INFO_FIRSTCHARACTERFLAGS returns 1; otherwise return 0. The fourth
\fBuint_t\fP variable.	argument should point to an \fBuint_t\fP variable.
.P	.P
In the 8-bit library, the value is always less than 256. In the 16-bit library	In the 8-bit library, the value is always less than 256. In the 16-bit library
the value can be up to 0xffff. In the 32-bit library in UTF-32 mode the value	the value can be up to 0xffff. In the 32-bit library in UTF-32 mode the value
can be up to 0x10ffff, and up to 0xffffffff when not using UTF-32 mode.	can be up to 0x10ffff, and up to 0xffffffff when not using UTF-32 mode.
.P
If there is no fixed first value, and if either
.sp	.sp
(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
starts with "^", or
.sp
(b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set
(if it were set, the pattern would be anchored),
.sp
-1 is returned, indicating that the pattern matches only at the start of a
subject string or after any newline within the string. Otherwise -2 is
returned. For anchored patterns, -2 is returned.
.sp
PCRE_INFO_REQUIREDCHARFLAGS	PCRE_INFO_REQUIREDCHARFLAGS
.sp	.sp
Returns 1 if there is a rightmost literal data unit that must exist in any	Returns 1 if there is a rightmost literal data unit that must exist in any
Line 1567 is different. (This seems a highly unlikely scenario.)	Line 1577 is different. (This seems a highly unlikely scenario.)
.SH "MATCHING A PATTERN: THE TRADITIONAL FUNCTION"	.SH "MATCHING A PATTERN: THE TRADITIONAL FUNCTION"
.rs	.rs
.sp	.sp
	.nf
.B int pcre_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"	.B int pcre_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"
.ti +5n	.B " const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,	.B " int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);"
.ti +5n	.fi
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);
.P	.P
The function \fBpcre_exec()\fP is called to match a subject string against a	The function \fBpcre_exec()\fP is called to match a subject string against a
compiled pattern, which is passed in the \fIcode\fP argument. If the	compiled pattern, which is passed in the \fIcode\fP argument. If the
Line 1724 and is described in the	Line 1734 and is described in the
.\"	.\"
documentation.	documentation.
.P	.P
The \fItables\fP field is used to pass a character tables pointer to	The \fItables\fP field is provided for use with patterns that have been
\fBpcre_exec()\fP; this overrides the value that is stored with the compiled	pre-compiled using custom character tables, saved to disc or elsewhere, and
pattern. A non-NULL value is stored with the compiled pattern only if custom	then reloaded, because the tables that were used to compile a pattern are not
tables were supplied to \fBpcre_compile()\fP via its \fItableptr\fP argument.	saved with it. See the
If NULL is passed to \fBpcre_exec()\fP using this mechanism, it forces PCRE's
internal tables to be used. This facility is helpful when re-using patterns
that have been saved after compiling with an external set of tables, because
the external tables might be at a different address when \fBpcre_exec()\fP is
called. See the
.\" HREF	.\" HREF
\fBpcreprecompile\fP	\fBpcreprecompile\fP
.\"	.\"
documentation for a discussion of saving compiled patterns for later use.	documentation for a discussion of saving compiled patterns for later use. If
	NULL is passed using this mechanism, it forces PCRE's internal tables to be
	used.
.P	.P
	\fBWarning:\fP The tables that \fBpcre_exec()\fP uses must be the same as those
	that were used when the pattern was compiled. If this is not the case, the
	behaviour of \fBpcre_exec()\fP is undefined. Therefore, when a pattern is
	compiled and matched in the same process, this field should never be set. In
	this (the most common) case, the correct table pointer is automatically passed
	with the compiled pattern from \fBpcre_compile()\fP to \fBpcre_exec()\fP.
	.P
If PCRE_EXTRA_MARK is set in the \fIflags\fP field, the \fImark\fP field must	If PCRE_EXTRA_MARK is set in the \fIflags\fP field, the \fImark\fP field must
be set to point to a suitable variable. If the pattern contains any	be set to point to a suitable variable. If the pattern contains any
backtracking control verbs such as (*MARK:NAME), and the execution ends up with	backtracking control verbs such as (*MARK:NAME), and the execution ends up with
Line 1960 all the matches in a single subject string. However, y	Line 1974 all the matches in a single subject string. However, y
the value of \fIstartoffset\fP points to the start of a character (or the end	the value of \fIstartoffset\fP points to the start of a character (or the end
of the subject). When PCRE_NO_UTF8_CHECK is set, the effect of passing an	of the subject). When PCRE_NO_UTF8_CHECK is set, the effect of passing an
invalid string as a subject or an invalid value of \fIstartoffset\fP is	invalid string as a subject or an invalid value of \fIstartoffset\fP is
undefined. Your program may crash.	undefined. Your program may crash or loop.
.sp	.sp
PCRE_PARTIAL_HARD	PCRE_PARTIAL_HARD
PCRE_PARTIAL_SOFT	PCRE_PARTIAL_SOFT
Line 2423 no longer in use and is never returned.	Line 2437 no longer in use and is never returned.
.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"	.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"
.rs	.rs
.sp	.sp
	.nf
.B int pcre_copy_substring(const char \fIsubject\fP, int \fIovector\fP,	.B int pcre_copy_substring(const char \fIsubject\fP, int \fIovector\fP,
.ti +5n	.B " int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,"
.B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,	.B " int \fIbuffersize\fP);"
.ti +5n	.sp
.B int \fIbuffersize\fP);
.PP
.B int pcre_get_substring(const char \fIsubject\fP, int \fIovector\fP,	.B int pcre_get_substring(const char \fIsubject\fP, int \fIovector\fP,
.ti +5n	.B " int \fIstringcount\fP, int \fIstringnumber\fP,"
.B int \fIstringcount\fP, int \fIstringnumber\fP,	.B " const char **\fIstringptr\fP);"
.ti +5n	.sp
.B const char **\fIstringptr\fP);
.PP
.B int pcre_get_substring_list(const char *\fIsubject\fP,	.B int pcre_get_substring_list(const char *\fIsubject\fP,
.ti +5n	.B " int \fIovector\fP, int \fIstringcount\fP, const char **\fIlistptr\fP);"
.B int \fIovector\fP, int \fIstringcount\fP, "const char **\fIlistptr\fP);"	.PP
.PP	.PP
Captured substrings can be accessed directly by using the offsets returned by	Captured substrings can be accessed directly by using the offsets returned by
\fBpcre_exec()\fP in \fIovector\fP. For convenience, the functions	\fBpcre_exec()\fP in \fIovector\fP. For convenience, the functions
Line 2516 provided.	Line 2527 provided.
.SH "EXTRACTING CAPTURED SUBSTRINGS BY NAME"	.SH "EXTRACTING CAPTURED SUBSTRINGS BY NAME"
.rs	.rs
.sp	.sp
	.nf
.B int pcre_get_stringnumber(const pcre *\fIcode\fP,	.B int pcre_get_stringnumber(const pcre *\fIcode\fP,
.ti +5n	.B " const char *\fIname\fP);"
.B const char *\fIname\fP);	.B int pcre_copy_named_substring(const pcre *\fIcode\fP,
.PP
.B int pcre_copy_named_substring(const pcre *\fIcode\fP,	.B int pcre_copy_named_substring(const pcre *\fIcode\fP,
.ti +5n	.B " const char \fIsubject\fP, int \fIovector\fP,"
.B const char \fIsubject\fP, int \fIovector\fP,	.B " int \fIstringcount\fP, const char *\fIstringname\fP,"
.ti +5n	.B " char *\fIbuffer\fP, int \fIbuffersize\fP);"
.B int \fIstringcount\fP, const char *\fIstringname\fP,	.sp
.ti +5n
.B char *\fIbuffer\fP, int \fIbuffersize\fP);
.PP
.B int pcre_get_named_substring(const pcre *\fIcode\fP,	.B int pcre_get_named_substring(const pcre *\fIcode\fP,
.ti +5n	.B " const char \fIsubject\fP, int \fIovector\fP,"
.B const char \fIsubject\fP, int \fIovector\fP,	.B " int \fIstringcount\fP, const char *\fIstringname\fP,"
.ti +5n	.B " const char **\fIstringptr\fP);"
.B int \fIstringcount\fP, const char *\fIstringname\fP,	.fi
.ti +5n
.B const char **\fIstringptr\fP);
.PP	.PP
To extract a substring by name, you first have to find associated number.	To extract a substring by name, you first have to find associated number.
For example, for this pattern	For example, for this pattern
Line 2586 same number causes an error at compile time.	Line 2592 same number causes an error at compile time.
.SH "DUPLICATE SUBPATTERN NAMES"	.SH "DUPLICATE SUBPATTERN NAMES"
.rs	.rs
.sp	.sp
	.nf
.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,	.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,
.ti +5n	.B " const char \fIname\fP, char \fIfirst\fP, char *\fIlast\fP);"
.B const char \fIname\fP, char \fIfirst\fP, char *\fIlast\fP);	.PP
.PP	.PP
When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns	When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns
are not required to be unique. (Duplicate names are always allowed for	are not required to be unique. (Duplicate names are always allowed for
Line 2677 the value returned is the size of each block that is o	Line 2684 the value returned is the size of each block that is o
.SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION"	.SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION"
.rs	.rs
.sp	.sp
	.nf
.B int pcre_dfa_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"	.B int pcre_dfa_exec(const pcre \fIcode\fP, "const pcre_extra \fIextra\fP,"
.ti +5n	.B " const char *\fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,	.B " int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,"
.ti +5n	.B " int *\fIworkspace\fP, int \fIwscount\fP);"
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,	.fi
.ti +5n
.B int *\fIworkspace\fP, int \fIwscount\fP);
.P	.P
The function \fBpcre_dfa_exec()\fP is called to match a subject string against	The function \fBpcre_dfa_exec()\fP is called to match a subject string against
a compiled pattern, using a matching algorithm that scans the subject string	a compiled pattern, using a matching algorithm that scans the subject string
Line 2810 matching string is given first. If there were too many	Line 2816 matching string is given first. If there were too many
\fIovector\fP, the yield of the function is zero, and the vector is filled with	\fIovector\fP, the yield of the function is zero, and the vector is filled with
the longest matches. Unlike \fBpcre_exec()\fP, \fBpcre_dfa_exec()\fP can use	the longest matches. Unlike \fBpcre_exec()\fP, \fBpcre_dfa_exec()\fP can use
the entire \fIovector\fP for returning matched strings.	the entire \fIovector\fP for returning matched strings.
	.P
	NOTE: PCRE's "auto-possessification" optimization usually applies to character
	repeats at the end of a pattern (as well as internally). For example, the
	pattern "a\ed+" is compiled as if it were "a\ed++" because there is no point
	even considering the possibility of backtracking into the repeated digits. For
	DFA matching, this means that only one possible match is found. If you really
	do want multiple matches in such cases, either use an ungreedy repeat
	("a\ed+?") or set the PCRE_NO_AUTO_POSSESS option when compiling.
.	.
.	.
.SS "Error returns from \fBpcre_dfa_exec()\fP"	.SS "Error returns from \fBpcre_dfa_exec()\fP"
Line 2886 Cambridge CB2 3QH, England.	Line 2900 Cambridge CB2 3QH, England.
.rs	.rs
.sp	.sp
.nf	.nf
Last updated: 12 May 2013	Last updated: 12 November 2013
Copyright (c) 1997-2013 University of Cambridge.	Copyright (c) 1997-2013 University of Cambridge.
.fi	.fi

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>

Removed from v.1.1.1.4
changed lines
	Added in v.1.1.1.5