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

Update HTML docs.

This commit is contained in:
Philip.Hazel 2016-02-26 18:32:07 +00:00
parent 96926349bc
commit be1ac011ec
6 changed files with 504 additions and 311 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/html/index.html
View File

@ -91,6 +91,9 @@ in the library.
<tr><td><a href="pcre2_callout_enumerate.html">pcre2_callout_enumerate</a></td> <tr><td><a href="pcre2_callout_enumerate.html">pcre2_callout_enumerate</a></td>
<td>&nbsp;&nbsp;Enumerate callouts in a compiled pattern</td></tr> <td>&nbsp;&nbsp;Enumerate callouts in a compiled pattern</td></tr>
<tr><td><a href="pcre2_code_copy.html">pcre2_code_copy</a></td>
<td>&nbsp;&nbsp;Copy a compiled pattern</td></tr>
<tr><td><a href="pcre2_code_free.html">pcre2_code_free</a></td> <tr><td><a href="pcre2_code_free.html">pcre2_code_free</a></td>
<td>&nbsp;&nbsp;Free a compiled pattern</td></tr> <td>&nbsp;&nbsp;Free a compiled pattern</td></tr>

42
doc/html/pcre2_code_copy.html Normal file
View File

@ -0,0 +1,42 @@
<html>
<head>
<title>pcre2_code_copy specification</title>
</head>
<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
<h1>pcre2_code_copy man page</h1>
<p>
Return to the <a href="index.html">PCRE2 index page</a>.
</p>
<p>
This page is part of the PCRE2 HTML documentation. It was generated
automatically from the original man page. If there is any nonsense in it,
please consult the man page, in case the conversion went wrong.
<br>
<br><b>
SYNOPSIS
</b><br>
<P>
<b>#include &#60;pcre2.h&#62;</b>
</P>
<P>
<b>pcre2_code *pcre2_code_copy(const pcre2_code *<i>code</i>);</b>
</P>
<br><b>
DESCRIPTION
</b><br>
<P>
This function makes a copy of the memory used for a compiled pattern, excluding
any memory used by the JIT compiler. Without a subsequent call to
<b>pcre2_jit_compile()</b>, the copy can be used only for non-JIT matching. The
yield of the function is NULL if <i>code</i> is NULL or if sufficient memory
cannot be obtained.
</P>
<P>
There is a complete description of the PCRE2 native API in the
<a href="pcre2api.html"><b>pcre2api</b></a>
page and a description of the POSIX API in the
<a href="pcre2posix.html"><b>pcre2posix</b></a>
page.
<p>
Return to the <a href="index.html">PCRE2 index page</a>.
</p>

111
doc/html/pcre2api.html
View File

@ -290,6 +290,9 @@ document for an overview of all the PCRE2 documentation.
</P> </P>
<br><a name="SEC10" href="#TOC1">PCRE2 NATIVE API AUXILIARY FUNCTIONS</a><br> <br><a name="SEC10" href="#TOC1">PCRE2 NATIVE API AUXILIARY FUNCTIONS</a><br>
<P> <P>
<b>pcre2_code *pcre2_code_copy(const pcre2_code *<i>code</i>);</b>
<br>
<br>
<b>int pcre2_get_error_message(int <i>errorcode</i>, PCRE2_UCHAR *<i>buffer</i>,</b> <b>int pcre2_get_error_message(int <i>errorcode</i>, PCRE2_UCHAR *<i>buffer</i>,</b>
<b> PCRE2_SIZE <i>bufflen</i>);</b> <b> PCRE2_SIZE <i>bufflen</i>);</b>
<br> <br>
@ -455,10 +458,19 @@ return a copy of the subject string with substitutions for parts that were
matched. matched.
</P> </P>
<P> <P>
Functions whose names begin with <b>pcre2_serialize_</b> are used for saving
compiled patterns on disc or elsewhere, and reloading them later.
</P>
<P>
Finally, there are functions for finding out information about a compiled Finally, there are functions for finding out information about a compiled
pattern (<b>pcre2_pattern_info()</b>) and about the configuration with which pattern (<b>pcre2_pattern_info()</b>) and about the configuration with which
PCRE2 was built (<b>pcre2_config()</b>). PCRE2 was built (<b>pcre2_config()</b>).
</P> </P>
<P>
Functions with names ending with <b>_free()</b> are used for freeing memory
blocks of various sorts. In all cases, if one of these functions is called with
a NULL argument, it does nothing.
</P>
<br><a name="SEC13" href="#TOC1">STRING LENGTHS AND OFFSETS</a><br> <br><a name="SEC13" href="#TOC1">STRING LENGTHS AND OFFSETS</a><br>
<P> <P>
The PCRE2 API uses string lengths and offsets into strings of code units in The PCRE2 API uses string lengths and offsets into strings of code units in
@ -516,20 +528,51 @@ time ensuring that multithreaded applications can use it.
There are several different blocks of data that are used to pass information There are several different blocks of data that are used to pass information
between the application and the PCRE2 libraries. between the application and the PCRE2 libraries.
</P> </P>
<br><b>
The compiled pattern
</b><br>
<P> <P>
(1) A pointer to the compiled form of a pattern is returned to the user when A pointer to the compiled form of a pattern is returned to the user when
<b>pcre2_compile()</b> is successful. The data in the compiled pattern is fixed, <b>pcre2_compile()</b> is successful. The data in the compiled pattern is fixed,
and does not change when the pattern is matched. Therefore, it is thread-safe, and does not change when the pattern is matched. Therefore, it is thread-safe,
that is, the same compiled pattern can be used by more than one thread that is, the same compiled pattern can be used by more than one thread
simultaneously. An application can compile all its patterns at the start, simultaneously. For example, an application can compile all its patterns at the
before forking off multiple threads that use them. However, if the just-in-time start, before forking off multiple threads that use them. However, if the
optimization feature is being used, it needs separate memory stack areas for just-in-time optimization feature is being used, it needs separate memory stack
each thread. See the areas for each thread. See the
<a href="pcre2jit.html"><b>pcre2jit</b></a> <a href="pcre2jit.html"><b>pcre2jit</b></a>
documentation for more details. documentation for more details.
</P> </P>
<P> <P>
(2) The next section below introduces the idea of "contexts" in which PCRE2 In a more complicated situation, where patterns are compiled only when they are
first needed, but are still shared between threads, pointers to compiled
patterns must be protected from simultaneous writing by multiple threads, at
least until a pattern has been compiled. The logic can be something like this:
<pre>
Get a read-only (shared) lock (mutex) for pointer
if (pointer == NULL)
{
Get a write (unique) lock for pointer
pointer = pcre2_compile(...
}
Release the lock
Use pointer in pcre2_match()
</pre>
Of course, testing for compilation errors should also be included in the code.
</P>
<P>
If JIT is being used, but the JIT compilation is not being done immediately,
(perhaps waiting to see if the pattern is used often enough) similar logic is
required. JIT compilation updates a pointer within the compiled code block, so
a thread must gain unique write access to the pointer before calling
<b>pcre2_jit_compile()</b>. Alternatively, <b>pcre2_code_copy()</b> can be used
to obtain a private copy of the compiled code.
</P>
<br><b>
Context blocks
</b><br>
<P>
The next main section below introduces the idea of "contexts" in which PCRE2
functions are called. A context is nothing more than a collection of parameters functions are called. A context is nothing more than a collection of parameters
that control the way PCRE2 operates. Grouping a number of parameters together that control the way PCRE2 operates. Grouping a number of parameters together
in a context is a convenient way of passing them to a PCRE2 function without in a context is a convenient way of passing them to a PCRE2 function without
@ -543,11 +586,14 @@ are never changed, the same context can be used by all the threads. However, if
any thread needs to change any value in a context, it must make its own any thread needs to change any value in a context, it must make its own
thread-specific copy. thread-specific copy.
</P> </P>
<br><b>
Match blocks
</b><br>
<P> <P>
(3) The matching functions need a block of memory for working space and for The matching functions need a block of memory for working space and for storing
storing the results of a match. This includes details of what was matched, as the results of a match. This includes details of what was matched, as well as
well as additional information such as the name of a (*MARK) setting. Each additional information such as the name of a (*MARK) setting. Each thread must
thread must provide its own version of this memory. provide its own copy of this memory.
</P> </P>
<br><a name="SEC16" href="#TOC1">PCRE2 CONTEXTS</a><br> <br><a name="SEC16" href="#TOC1">PCRE2 CONTEXTS</a><br>
<P> <P>
@ -1007,14 +1053,33 @@ zero.
<br> <br>
<br> <br>
<b>void pcre2_code_free(pcre2_code *<i>code</i>);</b> <b>void pcre2_code_free(pcre2_code *<i>code</i>);</b>
<br>
<br>
<b>pcre2_code *pcre2_code_copy(const pcre2_code *<i>code</i>);</b>
</P> </P>
<P> <P>
The <b>pcre2_compile()</b> function compiles a pattern into an internal form. 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 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 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 PCRE2_ZERO_TERMINATED. The function returns a pointer to a block of memory that
contains the compiled pattern and related data. The caller must free the memory contains the compiled pattern and related data.
by calling <b>pcre2_code_free()</b> when it is no longer needed. </P>
<P>
If the compile context argument <i>ccontext</i> is NULL, memory for the compiled
pattern is obtained by calling <b>malloc()</b>. Otherwise, it is obtained from
the same memory function that was used for the compile context. The caller must
free the memory by calling <b>pcre2_code_free()</b> when it is no longer needed.
</P>
<P>
The function <b>pcre2_code_copy()</b> makes a copy of the compiled code in new
memory, using the same memory allocator as was used for the original. However,
if the code has been processed by the JIT compiler (see
<a href="#jitcompiling">below),</a>
the JIT information cannot be copied (because it is position-dependent).
The new copy can initially be used only for non-JIT matching, though it can be
passed to <b>pcre2_jit_compile()</b> if required. The <b>pcre2_code_copy()</b>
function provides a way for individual threads in a multithreaded application
to acquire a private copy of shared compiled code.
</P> </P>
<P> <P>
NOTE: When one of the matching functions is called, pointers to the compiled NOTE: When one of the matching functions is called, pointers to the compiled
@ -1025,16 +1090,12 @@ free a compiled pattern (or a subject string) until after all operations on the
have taken place. have taken place.
</P> </P>
<P> <P>
If the compile context argument <i>ccontext</i> is NULL, memory for the compiled The <i>options</i> argument for <b>pcre2_compile()</b> contains various bit
pattern is obtained by calling <b>malloc()</b>. Otherwise, it is obtained from settings that affect the compilation. It should be zero if no options are
the same memory function that was used for the compile context. required. The available options are described below. Some of them (in
</P> particular, those that are compatible with Perl, but some others as well) can
<P> also be set and unset from within the pattern (see the detailed description in
The <i>options</i> argument contains various bit settings that affect the the
compilation. It should be zero if no options are required. The available
options are described below. Some of them (in particular, those that are
compatible with Perl, but some others as well) can also be set and unset from
within the pattern (see the detailed description in the
<a href="pcre2pattern.html"><b>pcre2pattern</b></a> <a href="pcre2pattern.html"><b>pcre2pattern</b></a>
documentation). documentation).
</P> </P>
@ -1433,7 +1494,7 @@ are used for invalid UTF strings. These are the same as given by
<a href="pcre2unicode.html"><b>pcre2unicode</b></a> <a href="pcre2unicode.html"><b>pcre2unicode</b></a>
page. The <b>pcre2_get_error_message()</b> function can be called to obtain a page. The <b>pcre2_get_error_message()</b> function can be called to obtain a
textual error message from any error code. textual error message from any error code.
</P> <a name="jitcompiling"></a></P>
<br><a name="SEC20" href="#TOC1">JUST-IN-TIME (JIT) COMPILATION</a><br> <br><a name="SEC20" href="#TOC1">JUST-IN-TIME (JIT) COMPILATION</a><br>
<P> <P>
<b>int pcre2_jit_compile(pcre2_code *<i>code</i>, uint32_t <i>options</i>);</b> <b>int pcre2_jit_compile(pcre2_code *<i>code</i>, uint32_t <i>options</i>);</b>
@ -3123,7 +3184,7 @@ Cambridge, England.
</P> </P>
<br><a name="SEC40" href="#TOC1">REVISION</a><br> <br><a name="SEC40" href="#TOC1">REVISION</a><br>
<P> <P>
Last updated: 31 January 2016 Last updated: 26 February 2016
<br> <br>
Copyright &copy; 1997-2016 University of Cambridge. Copyright &copy; 1997-2016 University of Cambridge.
<br> <br>

51
doc/html/pcre2test.html
View File

@ -353,9 +353,10 @@ test files that are also processed by <b>perltest.sh</b>. The <b>#perltest</b>
command helps detect tests that are accidentally put in the wrong file. command helps detect tests that are accidentally put in the wrong file.
<pre> <pre>
#pop [&#60;modifiers&#62;] #pop [&#60;modifiers&#62;]
#popcopy [&#60;modifiers&#62;]
</pre> </pre>
This command is used to manipulate the stack of compiled patterns, as described These commands are used to manipulate the stack of compiled patterns, as
in the section entitled "Saving and restoring compiled patterns" described in the section entitled "Saving and restoring compiled patterns"
<a href="#saverestore">below.</a> <a href="#saverestore">below.</a>
<pre> <pre>
#save &#60;filename&#62; #save &#60;filename&#62;
@ -573,6 +574,7 @@ about the pattern:
posix use the POSIX API 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 push push compiled pattern onto the stack
pushcopy push a copy onto the stack
stackguard=&#60;number&#62; test the stackguard feature stackguard=&#60;number&#62; test the stackguard feature
tables=[0|1|2] select internal tables tables=[0|1|2] select internal tables
</pre> </pre>
@ -932,12 +934,16 @@ pushed onto a stack of compiled patterns, and <b>pcre2test</b> expects the next
line to contain a new pattern (or a command) instead of a subject line. This 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 facility is used when saving compiled patterns to a file, as described in the
section entitled "Saving and restoring compiled patterns" section entitled "Saving and restoring compiled patterns"
<a href="#saverestore">below.</a> <a href="#saverestore">below. If <b>pushcopy</b> is used instead of <b>push</b>, a copy of the compiled</a>
The <b>push</b> modifier is incompatible with compilation modifiers such as pattern is stacked, leaving the original as current, ready to match the
<b>global</b> that act at match time. Any that are specified are ignored, with a following input lines. This provides a way of testing the
warning message, except for <b>replace</b>, which causes an error. Note that, <b>pcre2_code_copy()</b> function.
<b>jitverify</b>, which is allowed, does not carry through to any subsequent The <b>push</b> and <b>pushcopy </b> modifiers are incompatible with compilation
matching that uses this pattern. modifiers such as <b>global</b> that act at match time. Any that are specified
are ignored (for the stacked copy), with a warning message, except for
<b>replace</b>, which causes an error. Note that <b>jitverify</b>, which is
allowed, does not carry through to any subsequent matching that uses a stacked
pattern.
<a name="subjectmodifiers"></a></P> <a name="subjectmodifiers"></a></P>
<br><a name="SEC11" href="#TOC1">SUBJECT MODIFIERS</a><br> <br><a name="SEC11" href="#TOC1">SUBJECT MODIFIERS</a><br>
<P> <P>
@ -1530,7 +1536,9 @@ item to be tested. For example:
This output indicates that callout number 0 occurred for a match attempt 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 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 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. 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>
<P> <P>
Callouts numbered 255 are assumed to be automatic callouts, inserted as a Callouts numbered 255 are assumed to be automatic callouts, inserted as a
@ -1622,11 +1630,16 @@ can be used to test these functions.
<P> <P>
When a pattern with <b>push</b> modifier is successfully compiled, it is pushed When a pattern with <b>push</b> modifier is successfully compiled, it is pushed
onto a stack of compiled patterns, and <b>pcre2test</b> expects the next line to onto a stack of compiled patterns, and <b>pcre2test</b> expects the next line to
contain a new pattern (or command) instead of a subject line. By this means, a contain a new pattern (or command) instead of a subject line. By contrast,
number of patterns can be compiled and retained. The <b>push</b> modifier is the <b>pushcopy</b> modifier causes a copy of the compiled pattern to be
incompatible with <b>posix</b>, and control modifiers that act at match time are stacked, leaving the original available for immediate matching. By using
ignored (with a message). The <b>jitverify</b> modifier applies only at compile <b>push</b> and/or <b>pushcopy</b>, a number of patterns can be compiled and
time. The command 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
patterns. The <b>jitverify</b> modifier applies only at compile time.
</P>
<P>
The command
<pre> <pre>
#save &#60;filename&#62; #save &#60;filename&#62;
</pre> </pre>
@ -1643,7 +1656,8 @@ usual by an empty line or end of file. This command may be followed by a
modifier list containing only modifier list containing only
<a href="#controlmodifiers">control modifiers</a> <a href="#controlmodifiers">control modifiers</a>
that act after a pattern has been compiled. In particular, <b>hex</b>, that act after a pattern has been compiled. In particular, <b>hex</b>,
<b>posix</b>, <b>posix_nosub</b>, and <b>push</b> are not allowed, nor are any <b>posix</b>, <b>posix_nosub</b>, <b>push</b>, and <b>pushcopy</b> are not allowed,
nor are any
<a href="#optionmodifiers">option-setting modifiers.</a> <a href="#optionmodifiers">option-setting modifiers.</a>
The JIT modifiers are, however permitted. Here is an example that saves and The JIT modifiers are, however permitted. Here is an example that saves and
reloads two patterns. reloads two patterns.
@ -1661,6 +1675,11 @@ reloads two patterns.
If <b>jitverify</b> is used with #pop, it does not automatically imply 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. <b>jit</b>, which is different behaviour from when it is used on a pattern.
</P> </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
on the stack.
</P>
<br><a name="SEC19" href="#TOC1">SEE ALSO</a><br> <br><a name="SEC19" href="#TOC1">SEE ALSO</a><br>
<P> <P>
<b>pcre2</b>(3), <b>pcre2api</b>(3), <b>pcre2callout</b>(3), <b>pcre2</b>(3), <b>pcre2api</b>(3), <b>pcre2callout</b>(3),
@ -1678,7 +1697,7 @@ Cambridge, England.
</P> </P>
<br><a name="SEC21" href="#TOC1">REVISION</a><br> <br><a name="SEC21" href="#TOC1">REVISION</a><br>
<P> <P>
Last updated: 31 January 2016 Last updated: 06 February 2016
<br> <br>
Copyright &copy; 1997-2016 University of Cambridge. Copyright &copy; 1997-2016 University of Cambridge.
<br> <br>

105
doc/pcre2.txt
View File

@ -377,6 +377,8 @@ PCRE2 NATIVE API SERIALIZATION FUNCTIONS
PCRE2 NATIVE API AUXILIARY FUNCTIONS PCRE2 NATIVE API AUXILIARY FUNCTIONS
pcre2_code *pcre2_code_copy(const pcre2_code *code);
int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer, int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer,
PCRE2_SIZE bufflen); PCRE2_SIZE bufflen);
@ -523,10 +525,17 @@ PCRE2 API OVERVIEW
return a copy of the subject string with substitutions for parts that return a copy of the subject string with substitutions for parts that
were matched. were matched.
Functions whose names begin with pcre2_serialize_ are used for saving
compiled patterns on disc or elsewhere, and reloading them later.
Finally, there are functions for finding out information about a com- Finally, there are functions for finding out information about a com-
piled pattern (pcre2_pattern_info()) and about the configuration with piled pattern (pcre2_pattern_info()) and about the configuration with
which PCRE2 was built (pcre2_config()). which PCRE2 was built (pcre2_config()).
Functions with names ending with _free() are used for freeing memory
blocks of various sorts. In all cases, if one of these functions is
called with a NULL argument, it does nothing.
STRING LENGTHS AND OFFSETS STRING LENGTHS AND OFFSETS
@ -582,17 +591,47 @@ MULTITHREADING
There are several different blocks of data that are used to pass infor- There are several different blocks of data that are used to pass infor-
mation between the application and the PCRE2 libraries. mation between the application and the PCRE2 libraries.
(1) A pointer to the compiled form of a pattern is returned to the user The compiled pattern
A pointer to the compiled form of a pattern is returned to the user
when pcre2_compile() is successful. The data in the compiled pattern is when pcre2_compile() is successful. The data in the compiled pattern is
fixed, and does not change when the pattern is matched. Therefore, it fixed, and does not change when the pattern is matched. Therefore, it
is thread-safe, that is, the same compiled pattern can be used by more is thread-safe, that is, the same compiled pattern can be used by more
than one thread simultaneously. An application can compile all its pat- than one thread simultaneously. For example, an application can compile
terns at the start, before forking off multiple threads that use them. all its patterns at the start, before forking off multiple threads that
However, if the just-in-time optimization feature is being used, it use them. However, if the just-in-time optimization feature is being
needs separate memory stack areas for each thread. See the pcre2jit used, it needs separate memory stack areas for each thread. See the
documentation for more details. pcre2jit documentation for more details.
(2) The next section below introduces the idea of "contexts" in which In a more complicated situation, where patterns are compiled only when
they are first needed, but are still shared between threads, pointers
to compiled patterns must be protected from simultaneous writing by
multiple threads, at least until a pattern has been compiled. The logic
can be something like this:
Get a read-only (shared) lock (mutex) for pointer
if (pointer == NULL)
{
Get a write (unique) lock for pointer
pointer = pcre2_compile(...
}
Release the lock
Use pointer in pcre2_match()
Of course, testing for compilation errors should also be included in
the code.
If JIT is being used, but the JIT compilation is not being done immedi-
ately, (perhaps waiting to see if the pattern is used often enough)
similar logic is required. JIT compilation updates a pointer within the
compiled code block, so a thread must gain unique write access to the
pointer before calling pcre2_jit_compile(). Alternatively,
pcre2_code_copy() can be used to obtain a private copy of the compiled
code.
Context blocks
The next main section below introduces the idea of "contexts" in which
PCRE2 functions are called. A context is nothing more than a collection PCRE2 functions are called. A context is nothing more than a collection
of parameters that control the way PCRE2 operates. Grouping a number of of parameters that control the way PCRE2 operates. Grouping a number of
parameters together in a context is a convenient way of passing them to parameters together in a context is a convenient way of passing them to
@ -605,11 +644,12 @@ MULTITHREADING
threads. However, if any thread needs to change any value in a context, threads. However, if any thread needs to change any value in a context,
it must make its own thread-specific copy. it must make its own thread-specific copy.
(3) The matching functions need a block of memory for working space and Match blocks
for storing the results of a match. This includes details of what was
The matching functions need a block of memory for working space and for
storing the results of a match. This includes details of what was
matched, as well as additional information such as the name of a matched, as well as additional information such as the name of a
(*MARK) setting. Each thread must provide its own version of this mem- (*MARK) setting. Each thread must provide its own copy of this memory.
ory.
PCRE2 CONTEXTS PCRE2 CONTEXTS
@ -1060,13 +1100,29 @@ COMPILING A PATTERN
void pcre2_code_free(pcre2_code *code); void pcre2_code_free(pcre2_code *code);
pcre2_code *pcre2_code_copy(const pcre2_code *code);
The pcre2_compile() function compiles a pattern into an internal form. The pcre2_compile() function compiles a pattern into an internal form.
The pattern is defined by a pointer to a string of code units and a 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 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 as PCRE2_ZERO_TERMINATED. The function returns a pointer to a block of
memory that contains the compiled pattern and related data. The caller memory that contains the compiled pattern and related data.
must free the memory by calling pcre2_code_free() when it is no longer
needed. If the compile context argument ccontext is NULL, memory for the com-
piled pattern is obtained by calling malloc(). Otherwise, it is
obtained from the same memory function that was used for the compile
context. The caller must free the memory by calling pcre2_code_free()
when it is no longer needed.
The function pcre2_code_copy() makes a copy of the compiled code in new
memory, using the same memory allocator as was used for the original.
However, if the code has been processed by the JIT compiler (see
below), the JIT information cannot be copied (because it is position-
dependent). The new copy can initially be used only for non-JIT match-
ing, though it can be passed to pcre2_jit_compile() if required. The
pcre2_code_copy() function provides a way for individual threads in a
multithreaded application to acquire a private copy of shared compiled
code.
NOTE: When one of the matching functions is called, pointers to the 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 compiled pattern and the subject string are set in the match data block
@ -1075,17 +1131,12 @@ COMPILING A PATTERN
string) until after all operations on the match data block have taken string) until after all operations on the match data block have taken
place. place.
If the compile context argument ccontext is NULL, memory for the com- The options argument for pcre2_compile() contains various bit settings
piled pattern is obtained by calling malloc(). Otherwise, it is that affect the compilation. It should be zero if no options are
obtained from the same memory function that was used for the compile required. The available options are described below. Some of them (in
context. particular, those that are compatible with Perl, but some others as
well) can also be set and unset from within the pattern (see the
The options argument contains various bit settings that affect the com- detailed description in the pcre2pattern documentation).
pilation. It should be zero if no options are required. The available
options are described below. Some of them (in particular, those that
are compatible with Perl, but some others as well) can also be set and
unset from within the pattern (see the detailed description in the
pcre2pattern documentation).
For those options that can be different in different parts of the pat- For those options that can be different in different parts of the pat-
tern, the contents of the options argument specifies their settings at tern, the contents of the options argument specifies their settings at
@ -3058,7 +3109,7 @@ AUTHOR
REVISION REVISION
Last updated: 31 January 2016 Last updated: 26 February 2016
Copyright (c) 1997-2016 University of Cambridge. Copyright (c) 1997-2016 University of Cambridge.
------------------------------------------------------------------------------ ------------------------------------------------------------------------------

51
doc/pcre2test.txt
View File

@ -296,10 +296,11 @@ COMMAND LINES
wrong file. wrong file.
#pop [<modifiers>] #pop [<modifiers>]
#popcopy [<modifiers>]
This command is used to manipulate the stack of compiled patterns, as These commands are used to manipulate the stack of compiled patterns,
described in the section entitled "Saving and restoring compiled pat- as described in the section entitled "Saving and restoring compiled
terns" below. patterns" below.
#save <filename> #save <filename>
@ -518,6 +519,7 @@ PATTERN MODIFIERS
posix use the POSIX API 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 push push compiled pattern onto the stack
pushcopy push a copy onto the stack
stackguard=<number> test the stackguard feature stackguard=<number> test the stackguard feature
tables=[0|1|2] select internal tables tables=[0|1|2] select internal tables
@ -833,11 +835,15 @@ PATTERN MODIFIERS
next line to contain a new pattern (or a command) instead of a subject next 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 line. This facility is used when saving compiled patterns to a file, as
described in the section entitled "Saving and restoring compiled pat- described in the section entitled "Saving and restoring compiled pat-
terns" below. The push modifier is incompatible with compilation modi- terns" below. If pushcopy is used instead of push, a copy of the com-
fiers such as global that act at match time. Any that are specified are piled pattern is stacked, leaving the original as current, ready to
ignored, with a warning message, except for replace, which causes an match the following input lines. This provides a way of testing the
error. Note that, jitverify, which is allowed, does not carry through pcre2_code_copy() function. The push and pushcopy modifiers are
to any subsequent matching that uses this pattern. incompatible with compilation modifiers such as global that act at
match time. Any that are specified are ignored (for the stacked copy),
with a warning message, except for replace, which causes an error. Note
that jitverify, which is allowed, does not carry through to any subse-
quent matching that uses a stacked pattern.
SUBJECT MODIFIERS SUBJECT MODIFIERS
@ -1379,7 +1385,8 @@ CALLOUTS
attempt starting at the fourth character of the subject string, when attempt starting at the fourth character of the subject string, when
the pointer was at the seventh character, and when the next pattern 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 item was \d. Just one circumflex is output if the start and current
positions are the same. positions are the same, or if the current position precedes the start
position, which can happen if the callout is in a lookbehind assertion.
Callouts numbered 255 are assumed to be automatic callouts, inserted as Callouts numbered 255 are assumed to be automatic callouts, inserted as
a result of the /auto_callout pattern modifier. In this case, instead a result of the /auto_callout pattern modifier. In this case, instead
@ -1468,10 +1475,15 @@ SAVING AND RESTORING COMPILED PATTERNS
When a pattern with push modifier is successfully compiled, it is When a pattern with push modifier is successfully compiled, it is
pushed onto a stack of compiled patterns, and pcre2test expects the pushed onto a stack of compiled patterns, and pcre2test expects the
next line to contain a new pattern (or command) instead of a subject next line to contain a new pattern (or command) instead of a subject
line. By this means, a number of patterns can be compiled and retained. line. By contrast, the pushcopy modifier causes a copy of the compiled
The push modifier is incompatible with posix, and control modifiers pattern to be stacked, leaving the original available for immediate
that act at match time are ignored (with a message). The jitverify mod- matching. By using push and/or pushcopy, a number of patterns can be
ifier applies only at compile time. The command compiled and retained. These modifiers are incompatible with posix, and
control modifiers that act at match time are ignored (with a message)
for the stacked patterns. The jitverify modifier applies only at com-
pile time.
The command
#save <filename> #save <filename>
@ -1488,9 +1500,10 @@ SAVING AND RESTORING COMPILED PATTERNS
matched with the pattern, terminated as usual by an empty line or end matched with the pattern, terminated as usual by an empty line or end
of file. This command may be followed by a modifier list containing of file. This command may be followed by a modifier list containing
only control modifiers that act after a pattern has been compiled. In only control modifiers that act after a pattern has been compiled. In
particular, hex, posix, posix_nosub, and push are not allowed, nor are particular, hex, posix, posix_nosub, push, and pushcopy are not
any option-setting modifiers. The JIT modifiers are, however permit- allowed, nor are any option-setting modifiers. The JIT modifiers are,
ted. Here is an example that saves and reloads two patterns. however permitted. Here is an example that saves and reloads two pat-
terns.
/abc/push /abc/push
/xyz/push /xyz/push
@ -1505,6 +1518,10 @@ SAVING AND RESTORING COMPILED PATTERNS
If jitverify is used with #pop, it does not automatically imply jit, If jitverify is used with #pop, it does not automatically imply jit,
which is different behaviour from when it is used on a pattern. which is different behaviour from when it is used on a pattern.
The #popcopy command is analagous to the pushcopy modifier in that it
makes current a copy of the topmost stack pattern, leaving the original
still on the stack.
SEE ALSO SEE ALSO
@ -1521,5 +1538,5 @@ AUTHOR
REVISION REVISION
Last updated: 31 January 2016 Last updated: 06 February 2016
Copyright (c) 1997-2016 University of Cambridge. Copyright (c) 1997-2016 University of Cambridge.