From be1ac011ec498d8c4374e8e422009eb56267024e Mon Sep 17 00:00:00 2001 From: "Philip.Hazel" Date: Fri, 26 Feb 2016 18:32:07 +0000 Subject: [PATCH] Update HTML docs. --- doc/html/index.html | 3 + doc/html/pcre2_code_copy.html | 42 +++ doc/html/pcre2api.html | 115 ++++++-- doc/html/pcre2test.html | 51 ++-- doc/pcre2.txt | 503 +++++++++++++++++++--------------- doc/pcre2test.txt | 101 ++++--- 6 files changed, 504 insertions(+), 311 deletions(-) create mode 100644 doc/html/pcre2_code_copy.html diff --git a/doc/html/index.html b/doc/html/index.html index f459657..703c298 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -91,6 +91,9 @@ in the library. pcre2_callout_enumerate   Enumerate callouts in a compiled pattern +pcre2_code_copy +   Copy a compiled pattern + pcre2_code_free   Free a compiled pattern diff --git a/doc/html/pcre2_code_copy.html b/doc/html/pcre2_code_copy.html new file mode 100644 index 0000000..5b68282 --- /dev/null +++ b/doc/html/pcre2_code_copy.html @@ -0,0 +1,42 @@ + + +pcre2_code_copy specification + + +

pcre2_code_copy man page

+

+Return to the PCRE2 index page. +

+

+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. +
+
+SYNOPSIS +
+

+#include <pcre2.h> +

+

+pcre2_code *pcre2_code_copy(const pcre2_code *code); +

+
+DESCRIPTION +
+

+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 +pcre2_jit_compile(), the copy can be used only for non-JIT matching. The +yield of the function is NULL if code is NULL or if sufficient memory +cannot be obtained. +

+

+There is a complete description of the PCRE2 native API in the +pcre2api +page and a description of the POSIX API in the +pcre2posix +page. +

+Return to the PCRE2 index page. +

diff --git a/doc/html/pcre2api.html b/doc/html/pcre2api.html index d6c1b19..a037d4b 100644 --- a/doc/html/pcre2api.html +++ b/doc/html/pcre2api.html @@ -290,6 +290,9 @@ document for an overview of all the PCRE2 documentation.


PCRE2 NATIVE API AUXILIARY FUNCTIONS

+pcre2_code *pcre2_code_copy(const pcre2_code *code); +
+
int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer, PCRE2_SIZE bufflen);
@@ -455,10 +458,19 @@ return a copy of the subject string with substitutions for parts that 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 compiled pattern (pcre2_pattern_info()) and about the configuration with 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

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 between the application and the PCRE2 libraries.

+
+The compiled pattern +

-(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 pcre2_compile() is successful. The data in the compiled pattern is 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 than one thread -simultaneously. An application can compile all its patterns at the start, -before forking off multiple threads that use them. However, if the just-in-time -optimization feature is being used, it needs separate memory stack areas for -each thread. See the +simultaneously. For example, an application can compile all its patterns at the +start, before forking off multiple threads that use them. However, if the +just-in-time optimization feature is being used, it needs separate memory stack +areas for each thread. See the pcre2jit documentation for more details.

-(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: +

+  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 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 +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 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 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 thread-specific copy.

+
+Match blocks +

-(3) 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 (*MARK) setting. Each -thread must provide its own version of this memory. +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 (*MARK) setting. Each thread must +provide its own copy of this memory.


PCRE2 CONTEXTS

@@ -1007,14 +1053,33 @@ zero.

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 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 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 -by calling pcre2_code_free() when it is no longer needed. +contains the compiled pattern and related data. +

+

+If the compile context argument ccontext is NULL, memory for the compiled +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 matching, 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 compiled @@ -1025,16 +1090,12 @@ free a compiled pattern (or a subject string) until after all operations on the have taken place.

-If the compile context argument ccontext is NULL, memory for the compiled -pattern is obtained by calling malloc(). Otherwise, it is obtained from -the same memory function that was used for the compile context. -

-

-The options argument contains various bit settings that affect 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 +The options argument for pcre2_compile() contains various bit +settings that affect 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 pcre2pattern documentation).

@@ -1282,8 +1343,8 @@ If this option is set, it disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by ? behaves as if it were followed by ?: but named parentheses can still be used for capturing (and they acquire numbers in the usual way). There is no equivalent of this option -in Perl. Note that, if this option is set, references to capturing groups (back -references or recursion/subroutine calls) may only refer to named groups, +in Perl. Note that, if this option is set, references to capturing groups (back +references or recursion/subroutine calls) may only refer to named groups, though the reference can be by name or by number. 
   PCRE2_NO_AUTO_POSSESS
@@ -1433,7 +1494,7 @@ are used for invalid UTF strings. These are the same as given by
 pcre2unicode
 page. The pcre2_get_error_message() function can be called to obtain a
 textual error message from any error code.
-

+

 
JUST-IN-TIME (JIT) COMPILATION

 

 int pcre2_jit_compile(pcre2_code *code, uint32_t options);
@@ -3123,7 +3184,7 @@ Cambridge, England.
 

 
REVISION

 

-Last updated: 31 January 2016
+Last updated: 26 February 2016
 

 Copyright © 1997-2016 University of Cambridge.
 

diff --git a/doc/html/pcre2test.html b/doc/html/pcre2test.html
index 0157962..d0cc2ec 100644
--- a/doc/html/pcre2test.html
+++ b/doc/html/pcre2test.html
@@ -353,9 +353,10 @@ test files that are also processed by perltest.sh. The #perltest
 command helps detect tests that are accidentally put in the wrong file.
 
   #pop [<modifiers>]
+  #popcopy [<modifiers>]
 

-This command is used to manipulate the stack of compiled patterns, as described
-in the section entitled "Saving and restoring compiled patterns"
+These commands are used to manipulate the stack of compiled patterns, as
+described in the section entitled "Saving and restoring compiled patterns"
 below.
 
   #save <filename>
@@ -573,6 +574,7 @@ about the pattern:
       posix                     use the POSIX API
       posix_nosub               use the POSIX API with REG_NOSUB 
       push                      push compiled pattern onto the stack
+      pushcopy                  push a copy onto the stack
       stackguard=<number>       test the stackguard feature
       tables=[0|1|2]            select internal tables
 

@@ -932,12 +934,16 @@ pushed onto a stack of compiled patterns, and pcre2test expects the 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 described in the
 section entitled "Saving and restoring compiled patterns"
-below.
-The push modifier is incompatible with compilation modifiers such as
-global that act at match time. Any that are specified are ignored, with a
-warning message, except for replace, which causes an error. Note that,
-jitverify, which is allowed, does not carry through to any subsequent
-matching that uses this pattern.
+below. If pushcopy is used instead of push, a copy of the compiled
+pattern is stacked, leaving the original as current, ready to match the 
+following input lines. This provides a way of testing the 
+pcre2_code_copy() function.
+The push and pushcopy  modifiers are 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 subsequent matching that uses a stacked
+pattern.
 

 
SUBJECT MODIFIERS

 

@@ -1530,7 +1536,9 @@ item to be tested. For example:
 This output indicates that callout number 0 occurred for a match attempt
 starting at the fourth character of the subject string, when the pointer was at
 the seventh character, and when the next pattern item was \d. Just
-one circumflex is output if the start and current positions are the same.
+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.
 

 

 Callouts numbered 255 are assumed to be automatic callouts, inserted as a
@@ -1622,11 +1630,16 @@ can be used to test these functions.
 

 When a pattern with push modifier is successfully compiled, it is pushed
 onto a stack of compiled patterns, and pcre2test expects the 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. The push modifier is
-incompatible with posix, and control modifiers that act at match time are
-ignored (with a message). The jitverify modifier applies only at compile
-time. The command
+contain a new pattern (or command) instead of a subject line. By contrast,
+the pushcopy modifier causes a copy of the compiled pattern to be
+stacked, leaving the original available for immediate matching. By using
+push and/or pushcopy, a number of patterns can be 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 compile time.
+

+

+The command
 
   #save <filename>
 

@@ -1643,7 +1656,8 @@ usual by an empty line or end of file. This command may be followed by a
 modifier list containing only
 control modifiers
 that act after a pattern has been compiled. In particular, hex,
-posix, posix_nosub, and push are not allowed, nor are any
+posix, posix_nosub, push, and pushcopy are not allowed,
+nor are any
 option-setting modifiers.
 The JIT modifiers are, however permitted. Here is an example that saves and
 reloads two patterns.
@@ -1661,6 +1675,11 @@ reloads two patterns.
 If jitverify is used with #pop, it does not automatically imply
 jit, 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

 

 pcre2(3), pcre2api(3), pcre2callout(3),
@@ -1678,7 +1697,7 @@ Cambridge, England.
 

 
REVISION

 

-Last updated: 31 January 2016
+Last updated: 06 February 2016
 

 Copyright © 1997-2016 University of Cambridge.
 

diff --git a/doc/pcre2.txt b/doc/pcre2.txt
index 6b53509..f67f7ac 100644
--- a/doc/pcre2.txt
+++ b/doc/pcre2.txt
@@ -377,6 +377,8 @@ PCRE2 NATIVE API SERIALIZATION 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,
          PCRE2_SIZE bufflen);
 
@@ -523,76 +525,113 @@ PCRE2 API OVERVIEW
        return a copy of the subject string with substitutions for  parts  that
        were matched.
 
-       Finally,  there  are functions for finding out information about a com-
-       piled pattern (pcre2_pattern_info()) and about the  configuration  with
+       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-
+       piled  pattern  (pcre2_pattern_info()) and about the configuration with
        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
 
-       The  PCRE2  API  uses  string  lengths and offsets into strings of code
-       units in several places. These values are always  of  type  PCRE2_SIZE,
-       which  is an unsigned integer type, currently always defined as size_t.
-       The largest  value  that  can  be  stored  in  such  a  type  (that  is
-       ~(PCRE2_SIZE)0)  is reserved as a special indicator for zero-terminated
-       strings and unset offsets.  Therefore, the longest string that  can  be
+       The PCRE2 API uses string lengths and  offsets  into  strings  of  code
+       units  in  several  places. These values are always of type PCRE2_SIZE,
+       which is an unsigned integer type, currently always defined as  size_t.
+       The  largest  value  that  can  be  stored  in  such  a  type  (that is
+       ~(PCRE2_SIZE)0) is reserved as a special indicator for  zero-terminated
+       strings  and  unset offsets.  Therefore, the longest string that can be
        handled is one less than this maximum.
 
 
 NEWLINES
 
        PCRE2 supports five different conventions for indicating line breaks in
-       strings: a single CR (carriage return) character, a  single  LF  (line-
+       strings:  a  single  CR (carriage return) character, a single LF (line-
        feed) character, the two-character sequence CRLF, any of the three pre-
-       ceding, or any Unicode newline sequence. The Unicode newline  sequences
-       are  the  three just mentioned, plus the single characters VT (vertical
+       ceding,  or any Unicode newline sequence. The Unicode newline sequences
+       are the three just mentioned, plus the single characters  VT  (vertical
        tab, U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line
        separator, U+2028), and PS (paragraph separator, U+2029).
 
-       Each  of  the first three conventions is used by at least one operating
+       Each of the first three conventions is used by at least  one  operating
        system as its standard newline sequence. When PCRE2 is built, a default
-       can  be  specified.  The default default is LF, which is the Unix stan-
-       dard. However, the newline convention can be changed by an  application
+       can be specified.  The default default is LF, which is the  Unix  stan-
+       dard.  However, the newline convention can be changed by an application
        when calling pcre2_compile(), or it can be specified by special text at
        the start of the pattern itself; this overrides any other settings. See
        the pcre2pattern page for details of the special character sequences.
 
-       In  the  PCRE2  documentation  the  word "newline" is used to mean "the
+       In the PCRE2 documentation the word "newline"  is  used  to  mean  "the
        character or pair of characters that indicate a line break". The choice
-       of  newline convention affects the handling of the dot, circumflex, and
+       of newline convention affects the handling of the dot, circumflex,  and
        dollar metacharacters, the handling of #-comments in /x mode, and, when
-       CRLF  is a recognized line ending sequence, the match position advance-
+       CRLF is a recognized line ending sequence, the match position  advance-
        ment for a non-anchored pattern. There is more detail about this in the
        section on pcre2_match() options below.
 
-       The  choice of newline convention does not affect the interpretation of
+       The choice of newline convention does not affect the interpretation  of
        the \n or \r escape sequences, nor does it affect what \R matches; this
        has its own separate convention.
 
 
 MULTITHREADING
 
-       In  a multithreaded application it is important to keep thread-specific
-       data separate from data that can be shared between threads.  The  PCRE2
-       library  code  itself  is  thread-safe: it contains no static or global
-       variables. The API is designed to be  fairly  simple  for  non-threaded
-       applications  while at the same time ensuring that multithreaded appli-
+       In a multithreaded application it is important to keep  thread-specific
+       data  separate  from data that can be shared between threads. The PCRE2
+       library code itself is thread-safe: it contains  no  static  or  global
+       variables.  The  API  is  designed to be fairly simple for non-threaded
+       applications while at the same time ensuring that multithreaded  appli-
        cations can use it.
 
        There are several different blocks of data that are used to pass infor-
        mation between the application and the PCRE2 libraries.
 
-       (1) 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
-       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
-       than one thread simultaneously. An application can compile all its pat-
-       terns at the start, before forking off multiple threads that use  them.
-       However,  if  the  just-in-time  optimization feature is being used, it
-       needs separate memory stack areas for each  thread.  See  the  pcre2jit
-       documentation for more details.
+   The compiled pattern
 
-       (2)  The  next section below introduces the idea of "contexts" in which
+       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
+       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
+       than one thread simultaneously. For example, an application can compile
+       all its patterns at the start, before forking off multiple threads that
+       use them. However, if the just-in-time optimization  feature  is  being
+       used,  it  needs  separate  memory stack areas for each thread. See the
+       pcre2jit documentation for more details.
+
+       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
        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
@@ -605,44 +644,45 @@ MULTITHREADING
        threads. However, if any thread needs to change any value in a context,
        it must make its own thread-specific copy.
 
-       (3) 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
+   Match blocks
+
+       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
-       (*MARK)  setting. Each thread must provide its own version of this mem-
-       ory.
+       (*MARK) setting. Each thread must provide its own copy of this memory.
 
 
 PCRE2 CONTEXTS
 
-       Some PCRE2 functions have a lot of parameters, many of which  are  used
-       only  by  specialist  applications,  for example, those that use custom
-       memory management or non-standard character tables.  To  keep  function
-       argument  lists  at a reasonable size, and at the same time to keep the
-       API extensible, "uncommon" parameters are passed to  certain  functions
-       in  a  context instead of directly. A context is just a block of memory
-       that holds the parameter values.  Applications  that  do  not  need  to
-       adjust  any  of  the  context  parameters  can pass NULL when a context
+       Some  PCRE2  functions have a lot of parameters, many of which are used
+       only by specialist applications, for example,  those  that  use  custom
+       memory  management  or  non-standard character tables. To keep function
+       argument lists at a reasonable size, and at the same time to  keep  the
+       API  extensible,  "uncommon" parameters are passed to certain functions
+       in a context instead of directly. A context is just a block  of  memory
+       that  holds  the  parameter  values.   Applications that do not need to
+       adjust any of the context parameters  can  pass  NULL  when  a  context
        pointer is required.
 
-       There are three different types of context: a general context  that  is
-       relevant  for  several  PCRE2 operations, a compile-time context, and a
+       There  are  three different types of context: a general context that is
+       relevant for several PCRE2 operations, a compile-time  context,  and  a
        match-time context.
 
    The general context
 
-       At present, this context just  contains  pointers  to  (and  data  for)
-       external  memory  management  functions  that  are  called from several
+       At  present,  this  context  just  contains  pointers to (and data for)
+       external memory management  functions  that  are  called  from  several
        places in the PCRE2 library. The context is named `general' rather than
-       specifically  `memory'  because in future other fields may be added. If
-       you do not want to supply your own custom memory management  functions,
-       you  do not need to bother with a general context. A general context is
+       specifically `memory' because in future other fields may be  added.  If
+       you  do not want to supply your own custom memory management functions,
+       you do not need to bother with a general context. A general context  is
        created by:
 
        pcre2_general_context *pcre2_general_context_create(
          void *(*private_malloc)(PCRE2_SIZE, void *),
          void (*private_free)(void *, void *), void *memory_data);
 
-       The two function pointers specify custom memory  management  functions,
+       The  two  function pointers specify custom memory management functions,
        whose prototypes are:
 
          void *private_malloc(PCRE2_SIZE, void *);
@@ -650,16 +690,16 @@ PCRE2 CONTEXTS
 
        Whenever code in PCRE2 calls these functions, the final argument is the
        value of memory_data. Either of the first two arguments of the creation
-       function  may be NULL, in which case the system memory management func-
-       tions malloc() and free() are used. (This is not currently  useful,  as
-       there  are  no  other  fields in a general context, but in future there
-       might be.)  The private_malloc() function  is  used  (if  supplied)  to
-       obtain  memory  for storing the context, and all three values are saved
+       function may be NULL, in which case the system memory management  func-
+       tions  malloc()  and free() are used. (This is not currently useful, as
+       there are no other fields in a general context,  but  in  future  there
+       might  be.)   The  private_malloc()  function  is used (if supplied) to
+       obtain memory for storing the context, and all three values  are  saved
        as part of the context.
 
-       Whenever PCRE2 creates a data block of any kind, the block  contains  a
-       pointer  to the free() function that matches the malloc() function that
-       was used. When the time comes to  free  the  block,  this  function  is
+       Whenever  PCRE2  creates a data block of any kind, the block contains a
+       pointer to the free() function that matches the malloc() function  that
+       was  used.  When  the  time  comes  to free the block, this function is
        called.
 
        A general context can be copied by calling:
@@ -674,7 +714,7 @@ PCRE2 CONTEXTS
 
    The compile context
 
-       A  compile context is required if you want to change the default values
+       A compile context is required if you want to change the default  values
        of any of the following compile-time parameters:
 
          What \R matches (Unicode newlines or CR, LF, CRLF only)
@@ -684,11 +724,11 @@ PCRE2 CONTEXTS
          The maximum length of the pattern string
          An external function for stack checking
 
-       A compile context is also required if you are using custom memory  man-
-       agement.   If  none of these apply, just pass NULL as the context argu-
+       A  compile context is also required if you are using custom memory man-
+       agement.  If none of these apply, just pass NULL as the  context  argu-
        ment of pcre2_compile().
 
-       A compile context is created, copied, and freed by the following  func-
+       A  compile context is created, copied, and freed by the following func-
        tions:
 
        pcre2_compile_context *pcre2_compile_context_create(
@@ -699,33 +739,33 @@ PCRE2 CONTEXTS
 
        void pcre2_compile_context_free(pcre2_compile_context *ccontext);
 
-       A  compile  context  is created with default values for its parameters.
+       A compile context is created with default values  for  its  parameters.
        These can be changed by calling the following functions, which return 0
        on success, or PCRE2_ERROR_BADDATA if invalid data is detected.
 
        int pcre2_set_bsr(pcre2_compile_context *ccontext,
          uint32_t value);
 
-       The  value  must  be PCRE2_BSR_ANYCRLF, to specify that \R matches only
-       CR, LF, or CRLF, or PCRE2_BSR_UNICODE, to specify that \R  matches  any
+       The value must be PCRE2_BSR_ANYCRLF, to specify that  \R  matches  only
+       CR,  LF,  or CRLF, or PCRE2_BSR_UNICODE, to specify that \R matches any
        Unicode line ending sequence. The value is used by the JIT compiler and
-       by  the  two  interpreted   matching   functions,   pcre2_match()   and
+       by   the   two   interpreted   matching  functions,  pcre2_match()  and
        pcre2_dfa_match().
 
        int pcre2_set_character_tables(pcre2_compile_context *ccontext,
          const unsigned char *tables);
 
-       The  value  must  be  the result of a call to pcre2_maketables(), whose
+       The value must be the result of a  call  to  pcre2_maketables(),  whose
        only argument is a general context. This function builds a set of char-
        acter tables in the current locale.
 
        int pcre2_set_max_pattern_length(pcre2_compile_context *ccontext,
          PCRE2_SIZE value);
 
-       This  sets a maximum length, in code units, for the pattern string that
-       is to be compiled. If the pattern is longer,  an  error  is  generated.
-       This  facility  is  provided  so that applications that accept patterns
-       from external sources can limit their size. The default is the  largest
+       This sets a maximum length, in code units, for the pattern string  that
+       is  to  be  compiled.  If the pattern is longer, an error is generated.
+       This facility is provided so that  applications  that  accept  patterns
+       from  external sources can limit their size. The default is the largest
        number that a PCRE2_SIZE variable can hold, which is effectively unlim-
        ited.
 
@@ -733,38 +773,38 @@ PCRE2 CONTEXTS
          uint32_t value);
 
        This specifies which characters or character sequences are to be recog-
-       nized  as newlines. The value must be one of PCRE2_NEWLINE_CR (carriage
+       nized as newlines. The value must be one of PCRE2_NEWLINE_CR  (carriage
        return only), PCRE2_NEWLINE_LF (linefeed only), PCRE2_NEWLINE_CRLF (the
-       two-character  sequence  CR followed by LF), PCRE2_NEWLINE_ANYCRLF (any
+       two-character sequence CR followed by LF),  PCRE2_NEWLINE_ANYCRLF  (any
        of the above), or PCRE2_NEWLINE_ANY (any Unicode newline sequence).
 
        When a pattern is compiled with the PCRE2_EXTENDED option, the value of
-       this  parameter  affects  the recognition of white space and the end of
+       this parameter affects the recognition of white space and  the  end  of
        internal comments starting with #. The value is saved with the compiled
-       pattern  for  subsequent  use by the JIT compiler and by the two inter-
+       pattern for subsequent use by the JIT compiler and by  the  two  inter-
        preted matching functions, pcre2_match() and pcre2_dfa_match().
 
        int pcre2_set_parens_nest_limit(pcre2_compile_context *ccontext,
          uint32_t value);
 
        This parameter ajusts the limit, set when PCRE2 is built (default 250),
-       on  the  depth  of  parenthesis  nesting in a pattern. This limit stops
+       on the depth of parenthesis nesting in  a  pattern.  This  limit  stops
        rogue patterns using up too much system stack when being compiled.
 
        int pcre2_set_compile_recursion_guard(pcre2_compile_context *ccontext,
          int (*guard_function)(uint32_t, void *), void *user_data);
 
-       There is at least one application that runs PCRE2 in threads with  very
-       limited  system  stack,  where running out of stack is to be avoided at
-       all costs. The parenthesis limit above cannot take account of how  much
-       stack  is  actually  available.  For  a finer control, you can supply a
-       function that is called whenever pcre2_compile() starts  to  compile  a
-       parenthesized  part  of  a  pattern. This function can check the actual
+       There  is at least one application that runs PCRE2 in threads with very
+       limited system stack, where running out of stack is to  be  avoided  at
+       all  costs. The parenthesis limit above cannot take account of how much
+       stack is actually available. For a finer  control,  you  can  supply  a
+       function  that  is  called whenever pcre2_compile() starts to compile a
+       parenthesized part of a pattern. This function  can  check  the  actual
        stack size (or anything else that it wants to, of course).
 
-       The first argument to the callout function gives the current  depth  of
-       nesting,  and  the second is user data that is set up by the last argu-
-       ment  of  pcre2_set_compile_recursion_guard().  The  callout   function
+       The  first  argument to the callout function gives the current depth of
+       nesting, and the second is user data that is set up by the  last  argu-
+       ment   of  pcre2_set_compile_recursion_guard().  The  callout  function
        should return zero if all is well, or non-zero to force an error.
 
    The match context
@@ -778,10 +818,10 @@ PCRE2 CONTEXTS
          The limit for calling match() recursively
 
        A match context is also required if you are using custom memory manage-
-       ment.   If  none of these apply, just pass NULL as the context argument
+       ment.  If none of these apply, just pass NULL as the  context  argument
        of pcre2_match(), pcre2_dfa_match(), or pcre2_jit_match().
 
-       A match context is created, copied, and freed by  the  following  func-
+       A  match  context  is created, copied, and freed by the following func-
        tions:
 
        pcre2_match_context *pcre2_match_context_create(
@@ -792,7 +832,7 @@ PCRE2 CONTEXTS
 
        void pcre2_match_context_free(pcre2_match_context *mcontext);
 
-       A  match  context  is  created  with default values for its parameters.
+       A match context is created with  default  values  for  its  parameters.
        These can be changed by calling the following functions, which return 0
        on success, or PCRE2_ERROR_BADDATA if invalid data is detected.
 
@@ -800,96 +840,96 @@ PCRE2 CONTEXTS
          int (*callout_function)(pcre2_callout_block *, void *),
          void *callout_data);
 
-       This  sets  up a "callout" function, which PCRE2 will call at specified
+       This sets up a "callout" function, which PCRE2 will call  at  specified
        points during a matching operation. Details are given in the pcre2call-
        out documentation.
 
        int pcre2_set_offset_limit(pcre2_match_context *mcontext,
          PCRE2_SIZE value);
 
-       The  offset_limit  parameter  limits  how  far an unanchored search can
-       advance in the subject string. The default value  is  PCRE2_UNSET.  The
-       pcre2_match()      and      pcre2_dfa_match()      functions     return
-       PCRE2_ERROR_NOMATCH if a match with a starting point before or  at  the
+       The offset_limit parameter limits how  far  an  unanchored  search  can
+       advance  in  the  subject string. The default value is PCRE2_UNSET. The
+       pcre2_match()     and      pcre2_dfa_match()      functions      return
+       PCRE2_ERROR_NOMATCH  if  a match with a starting point before or at the
        given offset is not found. For example, if the pattern /abc/ is matched
-       against "123abc" with an offset  limit  less  than  3,  the  result  is
-       PCRE2_ERROR_NO_MATCH.   A  match  can never be found if the startoffset
+       against  "123abc"  with  an  offset  limit  less  than 3, the result is
+       PCRE2_ERROR_NO_MATCH.  A match can never be found  if  the  startoffset
        argument of pcre2_match() or pcre2_dfa_match() is greater than the off-
        set limit.
 
-       When  using  this  facility,  you  must set PCRE2_USE_OFFSET_LIMIT when
-       calling pcre2_compile() so that when JIT is in use, different code  can
-       be  compiled. If a match is started with a non-default match limit when
+       When using this facility,  you  must  set  PCRE2_USE_OFFSET_LIMIT  when
+       calling  pcre2_compile() so that when JIT is in use, different code can
+       be compiled. If a match is started with a non-default match limit  when
        PCRE2_USE_OFFSET_LIMIT is not set, an error is generated.
 
-       The offset limit facility can be used to track progress when  searching
-       large  subject  strings.  See  also  the  PCRE2_FIRSTLINE option, which
+       The  offset limit facility can be used to track progress when searching
+       large subject strings.  See  also  the  PCRE2_FIRSTLINE  option,  which
        requires a match to start within the first line of the subject. If this
-       is  set  with an offset limit, a match must occur in the first line and
-       also within the offset limit.  In other words,  whichever  limit  comes
+       is set with an offset limit, a match must occur in the first  line  and
+       also  within  the  offset limit.  In other words, whichever limit comes
        first is used.
 
        int pcre2_set_match_limit(pcre2_match_context *mcontext,
          uint32_t value);
 
-       The  match_limit  parameter  provides  a means of preventing PCRE2 from
+       The match_limit parameter provides a means  of  preventing  PCRE2  from
        using up too many resources when processing patterns that are not going
-       to  match, but which have a very large number of possibilities in their
-       search trees. The classic example is a pattern that uses nested  unlim-
+       to match, but which have a very large number of possibilities in  their
+       search  trees. The classic example is a pattern that uses nested unlim-
        ited repeats.
 
-       Internally,  pcre2_match()  uses  a  function  called match(), which it
-       calls repeatedly (sometimes recursively). The limit set by  match_limit
-       is  imposed  on  the  number  of times this function is called during a
+       Internally, pcre2_match() uses a  function  called  match(),  which  it
+       calls  repeatedly (sometimes recursively). The limit set by match_limit
+       is imposed on the number of times this  function  is  called  during  a
        match, which has the effect of limiting the amount of backtracking that
-       can  take place. For patterns that are not anchored, the count restarts
-       from zero for each position in the subject string. This  limit  is  not
+       can take place. For patterns that are not anchored, the count  restarts
+       from  zero  for  each position in the subject string. This limit is not
        relevant to pcre2_dfa_match(), which ignores it.
 
-       When  pcre2_match() is called with a pattern that was successfully pro-
+       When pcre2_match() is called with a pattern that was successfully  pro-
        cessed by pcre2_jit_compile(), the way in which matching is executed is
-       entirely  different. However, there is still the possibility of runaway
-       matching that goes on for a very long  time,  and  so  the  match_limit
-       value  is  also used in this case (but in a different way) to limit how
+       entirely different. However, there is still the possibility of  runaway
+       matching  that  goes  on  for  a very long time, and so the match_limit
+       value is also used in this case (but in a different way) to  limit  how
        long the matching can continue.
 
-       The default value for the limit can be set when  PCRE2  is  built;  the
-       default  default  is 10 million, which handles all but the most extreme
-       cases.   If   the   limit   is    exceeded,    pcre2_match()    returns
-       PCRE2_ERROR_MATCHLIMIT.  A  value  for the match limit may also be sup-
+       The  default  value  for  the limit can be set when PCRE2 is built; the
+       default default is 10 million, which handles all but the  most  extreme
+       cases.    If    the    limit   is   exceeded,   pcre2_match()   returns
+       PCRE2_ERROR_MATCHLIMIT. A value for the match limit may  also  be  sup-
        plied by an item at the start of a pattern of the form
 
          (*LIMIT_MATCH=ddd)
 
-       where ddd is a decimal number.  However,  such  a  setting  is  ignored
-       unless  ddd  is  less than the limit set by the caller of pcre2_match()
+       where  ddd  is  a  decimal  number.  However, such a setting is ignored
+       unless ddd is less than the limit set by the  caller  of  pcre2_match()
        or, if no such limit is set, less than the default.
 
        int pcre2_set_recursion_limit(pcre2_match_context *mcontext,
          uint32_t value);
 
        The recursion_limit parameter is similar to match_limit, but instead of
-       limiting  the  total  number of times that match() is called, it limits
-       the depth of recursion. The recursion depth is a  smaller  number  than
-       the  total number of calls, because not all calls to match() are recur-
+       limiting the total number of times that match() is  called,  it  limits
+       the  depth  of  recursion. The recursion depth is a smaller number than
+       the total number of calls, because not all calls to match() are  recur-
        sive.  This limit is of use only if it is set smaller than match_limit.
 
        Limiting the recursion depth limits the amount of system stack that can
-       be  used,  or,  when  PCRE2 has been compiled to use memory on the heap
-       instead of the stack, the amount of heap memory that can be used.  This
-       limit  is not relevant, and is ignored, when matching is done using JIT
+       be used, or, when PCRE2 has been compiled to use  memory  on  the  heap
+       instead  of the stack, the amount of heap memory that can be used. This
+       limit is not relevant, and is ignored, when matching is done using  JIT
        compiled code or by the pcre2_dfa_match() function.
 
-       The default value for recursion_limit can be set when PCRE2  is  built;
-       the  default  default is the same value as the default for match_limit.
-       If the limit is exceeded, pcre2_match() returns  PCRE2_ERROR_RECURSION-
-       LIMIT.  A value for the recursion limit may also be supplied by an item
+       The  default  value for recursion_limit can be set when PCRE2 is built;
+       the default default is the same value as the default  for  match_limit.
+       If  the limit is exceeded, pcre2_match() returns PCRE2_ERROR_RECURSION-
+       LIMIT. A value for the recursion limit may also be supplied by an  item
        at the start of a pattern of the form
 
          (*LIMIT_RECURSION=ddd)
 
-       where ddd is a decimal number.  However,  such  a  setting  is  ignored
-       unless  ddd  is  less than the limit set by the caller of pcre2_match()
+       where  ddd  is  a  decimal  number.  However, such a setting is ignored
+       unless ddd is less than the limit set by the  caller  of  pcre2_match()
        or, if no such limit is set, less than the default.
 
        int pcre2_set_recursion_memory_management(
@@ -898,21 +938,21 @@ PCRE2 CONTEXTS
          void (*private_free)(void *, void *), void *memory_data);
 
        This function sets up two additional custom memory management functions
-       for  use  by  pcre2_match()  when PCRE2 is compiled to use the heap for
+       for use by pcre2_match() when PCRE2 is compiled to  use  the  heap  for
        remembering backtracking data, instead of recursive function calls that
-       use  the  system stack. There is a discussion about PCRE2's stack usage
-       in the pcre2stack documentation. See the pcre2build  documentation  for
+       use the system stack. There is a discussion about PCRE2's  stack  usage
+       in  the  pcre2stack documentation. See the pcre2build documentation for
        details of how to build PCRE2.
 
-       Using  the  heap for recursion is a non-standard way of building PCRE2,
-       for use in environments  that  have  limited  stacks.  Because  of  the
+       Using the heap for recursion is a non-standard way of  building  PCRE2,
+       for  use  in  environments  that  have  limited  stacks. Because of the
        greater use of memory management, pcre2_match() runs more slowly. Func-
-       tions that are different to the general  custom  memory  functions  are
-       provided  so  that  special-purpose  external code can be used for this
-       case, because the memory blocks are all the same size. The  blocks  are
+       tions  that  are  different  to the general custom memory functions are
+       provided so that special-purpose external code can  be  used  for  this
+       case,  because  the memory blocks are all the same size. The blocks are
        retained by pcre2_match() until it is about to exit so that they can be
-       re-used when possible during the match. In the absence of  these  func-
-       tions,  the normal custom memory management functions are used, if sup-
+       re-used  when  possible during the match. In the absence of these func-
+       tions, the normal custom memory management functions are used, if  sup-
        plied, otherwise the system functions.
 
 
@@ -920,75 +960,75 @@ CHECKING BUILD-TIME OPTIONS
 
        int pcre2_config(uint32_t what, void *where);
 
-       The function pcre2_config() makes it possible for  a  PCRE2  client  to
-       discover  which  optional  features  have  been compiled into the PCRE2
-       library. The pcre2build documentation  has  more  details  about  these
+       The  function  pcre2_config()  makes  it possible for a PCRE2 client to
+       discover which optional features have  been  compiled  into  the  PCRE2
+       library.  The  pcre2build  documentation  has  more details about these
        optional features.
 
-       The  first  argument  for pcre2_config() 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
-       amount of memory that is needed  for  the  requested  information.  For
-       calls  that  return  numerical  values,  the  value  is  in bytes; when
-       requesting these values, where should point  to  appropriately  aligned
-       memory.  For calls that return strings, the required length is given in
+       The first argument for pcre2_config() 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
+       amount  of  memory  that  is  needed for the requested information. For
+       calls that return  numerical  values,  the  value  is  in  bytes;  when
+       requesting  these  values,  where should point to appropriately aligned
+       memory. For calls that return strings, the required length is given  in
        code units, not counting the terminating zero.
 
-       When requesting information, the returned value from pcre2_config()  is
-       non-negative  on success, or the negative error code PCRE2_ERROR_BADOP-
-       TION if the value in the first argument is not recognized. The  follow-
+       When  requesting information, the returned value from pcre2_config() is
+       non-negative on success, or the negative error code  PCRE2_ERROR_BADOP-
+       TION  if the value in the first argument is not recognized. The follow-
        ing information is available:
 
          PCRE2_CONFIG_BSR
 
-       The  output  is a uint32_t integer whose value indicates what character
-       sequences the \R  escape  sequence  matches  by  default.  A  value  of
+       The output is a uint32_t integer whose value indicates  what  character
+       sequences  the  \R  escape  sequence  matches  by  default.  A value of
        PCRE2_BSR_UNICODE  means  that  \R  matches  any  Unicode  line  ending
-       sequence; a value of PCRE2_BSR_ANYCRLF means that \R matches  only  CR,
+       sequence;  a  value of PCRE2_BSR_ANYCRLF means that \R matches only CR,
        LF, or CRLF. The default can be overridden when a pattern is compiled.
 
          PCRE2_CONFIG_JIT
 
-       The  output  is  a  uint32_t  integer that is set to one if support for
+       The output is a uint32_t integer that is set  to  one  if  support  for
        just-in-time compiling is available; otherwise it is set to zero.
 
          PCRE2_CONFIG_JITTARGET
 
-       The where argument should point to a buffer that is at  least  48  code
-       units  long.  (The  exact  length  required  can  be  found  by calling
-       pcre2_config() with where 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 number of code units used is returned. This  is
+       The  where  argument  should point to a buffer that is at least 48 code
+       units long.  (The  exact  length  required  can  be  found  by  calling
+       pcre2_config()  with  where  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 number of code units used is returned. This is
        the length of the string, plus one unit for the terminating zero.
 
          PCRE2_CONFIG_LINKSIZE
 
        The output is a uint32_t integer that contains the number of bytes used
-       for internal linkage in compiled regular  expressions.  When  PCRE2  is
-       configured,  the value can be set to 2, 3, or 4, with the default being
-       2. This is the value that is returned by pcre2_config(). However,  when
-       the  16-bit  library  is compiled, a value of 3 is rounded up to 4, and
-       when the 32-bit library is compiled, internal  linkages  always  use  4
+       for  internal  linkage  in  compiled regular expressions. When PCRE2 is
+       configured, the value can be set to 2, 3, or 4, with the default  being
+       2.  This is the value that is returned by pcre2_config(). However, when
+       the 16-bit library is compiled, a value of 3 is rounded up  to  4,  and
+       when  the  32-bit  library  is compiled, internal linkages always use 4
        bytes, so the configured value is not relevant.
 
        The default value of 2 for the 8-bit and 16-bit libraries is sufficient
-       for all but the most massive patterns, since it allows the size of  the
+       for  all but the most massive patterns, since it allows the size of the
        compiled pattern to be up to 64K code units. Larger values allow larger
-       regular expressions to be compiled by those two libraries, but  at  the
+       regular  expressions  to be compiled by those two libraries, but at the
        expense of slower matching.
 
          PCRE2_CONFIG_MATCHLIMIT
 
-       The  output  is a uint32_t integer that gives the default limit for the
-       number of internal matching function calls in  a  pcre2_match()  execu-
+       The output is a uint32_t integer that gives the default limit  for  the
+       number  of  internal  matching function calls in a pcre2_match() execu-
        tion. Further details are given with pcre2_match() below.
 
          PCRE2_CONFIG_NEWLINE
 
-       The  output  is  a  uint32_t  integer whose value specifies the default
-       character sequence that is recognized as meaning "newline". The  values
+       The output is a uint32_t integer  whose  value  specifies  the  default
+       character  sequence that is recognized as meaning "newline". The values
        are:
 
          PCRE2_NEWLINE_CR       Carriage return (CR)
@@ -997,56 +1037,56 @@ CHECKING BUILD-TIME OPTIONS
          PCRE2_NEWLINE_ANY      Any Unicode line ending
          PCRE2_NEWLINE_ANYCRLF  Any of CR, LF, or CRLF
 
-       The  default  should  normally  correspond to the standard sequence for
+       The default should normally correspond to  the  standard  sequence  for
        your operating system.
 
          PCRE2_CONFIG_PARENSLIMIT
 
-       The output is a uint32_t integer that gives the maximum depth of  nest-
+       The  output is a uint32_t integer that gives the maximum depth of nest-
        ing 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 PCRE2 is built; the default is 250. This limit does not
-       take into account the stack that may already be  used  by  the  calling
-       application.  For  finer  control  over  compilation  stack  usage, see
+       cap  the  amount of system stack used when a pattern is compiled. It is
+       specified when PCRE2 is built; the default is 250. This limit does  not
+       take  into  account  the  stack that may already be used by the calling
+       application. For  finer  control  over  compilation  stack  usage,  see
        pcre2_set_compile_recursion_guard().
 
          PCRE2_CONFIG_RECURSIONLIMIT
 
-       The output is a uint32_t integer that gives the default limit  for  the
-       depth  of  recursion  when  calling the internal matching function in a
-       pcre2_match() execution. Further details are given  with  pcre2_match()
+       The  output  is a uint32_t integer that gives the default limit for the
+       depth of recursion when calling the internal  matching  function  in  a
+       pcre2_match()  execution.  Further details are given with pcre2_match()
        below.
 
          PCRE2_CONFIG_STACKRECURSE
 
-       The  output is a uint32_t integer that is set to one if internal recur-
-       sion when running pcre2_match() is implemented  by  recursive  function
-       calls  that  use  the system stack to remember their state. This is the
-       usual way that PCRE2 is compiled. The output is zero if PCRE2 was  com-
-       piled  to  use blocks of data on the heap instead of recursive function
+       The output is a uint32_t integer that is set to one if internal  recur-
+       sion  when  running  pcre2_match() is implemented by recursive function
+       calls that use the system stack to remember their state.  This  is  the
+       usual  way that PCRE2 is compiled. The output is zero if PCRE2 was com-
+       piled to use blocks of data on the heap instead of  recursive  function
        calls.
 
          PCRE2_CONFIG_UNICODE_VERSION
 
-       The where argument should point to a buffer that is at  least  24  code
-       units  long.  (The  exact  length  required  can  be  found  by calling
-       pcre2_config() with where 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,
-       "8.0.0")  is  inserted. The number of code units used is returned. This
+       The  where  argument  should point to a buffer that is at least 24 code
+       units long.  (The  exact  length  required  can  be  found  by  calling
+       pcre2_config()  with  where  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,
+       "8.0.0") is inserted. The number of code units used is  returned.  This
        is the length of the string plus one unit for the terminating zero.
 
          PCRE2_CONFIG_UNICODE
 
-       The output is a uint32_t integer that is set to one if Unicode  support
-       is  available; otherwise it is set to zero. Unicode support implies UTF
+       The  output is a uint32_t integer that is set to one if Unicode support
+       is available; otherwise it is set to zero. Unicode support implies  UTF
        support.
 
          PCRE2_CONFIG_VERSION
 
-       The where argument should point to a buffer that is at  least  12  code
-       units  long.  (The  exact  length  required  can  be  found  by calling
-       pcre2_config() with where set to NULL.) The buffer is filled  with  the
+       The  where  argument  should point to a buffer that is at least 12 code
+       units long.  (The  exact  length  required  can  be  found  by  calling
+       pcre2_config()  with  where set to NULL.) The buffer is filled with the
        PCRE2 version string, zero-terminated. The number of code units used is
        returned. This is the length of the string plus one unit for the termi-
        nating zero.
@@ -1060,32 +1100,43 @@ COMPILING A PATTERN
 
        void pcre2_code_free(pcre2_code *code);
 
-       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
-       length,  If the pattern is zero-terminated, the length can be specified
-       as PCRE2_ZERO_TERMINATED. The function returns a pointer to a block  of
-       memory  that contains the compiled pattern and related data. The caller
-       must free the memory by calling pcre2_code_free() when it is no  longer
-       needed.
+       pcre2_code *pcre2_code_copy(const pcre2_code *code);
 
-       NOTE:  When  one  of  the matching functions is called, pointers to the
-       compiled pattern and the subject string are set in the match data block
-       so  that they can be referenced by the extraction functions. After run-
-       ning a match, you must not  free  a  compiled  pattern  (or  a  subject
-       string)  until  after all operations on the match data block have taken
-       place.
+       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
+       length. If the pattern is zero-terminated, the length can be  specified
+       as  PCRE2_ZERO_TERMINATED. The function returns a pointer to a block of
+       memory that contains the compiled pattern and related data.
 
        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.
+       context.  The  caller must free the memory by calling pcre2_code_free()
+       when it is no longer needed.
 
-       The options argument contains various bit settings that affect the com-
-       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).
+       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
+       compiled pattern and the subject string are set in the match data block
+       so that they can be referenced by the extraction functions. After  run-
+       ning  a  match,  you  must  not  free  a compiled pattern (or a subject
+       string) until after all operations on the match data block  have  taken
+       place.
+
+       The  options argument for pcre2_compile() contains various bit settings
+       that affect 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 pcre2pattern documentation).
 
        For those options that can be different in different parts of the  pat-
        tern,  the contents of the options argument specifies their settings at
@@ -3058,7 +3109,7 @@ AUTHOR
 
 REVISION
 
-       Last updated: 31 January 2016
+       Last updated: 26 February 2016
        Copyright (c) 1997-2016 University of Cambridge.
 ------------------------------------------------------------------------------
  
diff --git a/doc/pcre2test.txt b/doc/pcre2test.txt
index 0446452..5bc9f32 100644
--- a/doc/pcre2test.txt
+++ b/doc/pcre2test.txt
@@ -296,10 +296,11 @@ COMMAND LINES
        wrong file.
 
          #pop []
+         #popcopy []
 
-       This  command  is used to manipulate the stack of compiled patterns, as
-       described in the section entitled "Saving and restoring  compiled  pat-
-       terns" below.
+       These  commands  are used to manipulate the stack of compiled patterns,
+       as described in the section entitled  "Saving  and  restoring  compiled
+       patterns" below.
 
          #save 
 
@@ -518,6 +519,7 @@ PATTERN MODIFIERS
              posix                     use the POSIX API
              posix_nosub               use the POSIX API with REG_NOSUB
              push                      push compiled pattern onto the stack
+             pushcopy                  push a copy onto the stack
              stackguard=       test the stackguard feature
              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
        line. This facility is used when saving compiled patterns to a file, as
        described  in  the section entitled "Saving and restoring compiled pat-
-       terns" below.  The push modifier is incompatible with compilation modi-
-       fiers such as global that act at match time. Any that are specified are
-       ignored, with a warning message, except for replace,  which  causes  an
-       error.  Note  that, jitverify, which is allowed, does not carry through
-       to any subsequent matching that uses this pattern.
+       terns" below. If pushcopy is used instead of push, a copy of  the  com-
+       piled  pattern  is  stacked,  leaving the original as current, ready to
+       match the following input lines. This provides a  way  of  testing  the
+       pcre2_code_copy()  function.   The  push  and  pushcopy   modifiers are
+       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
@@ -1379,10 +1385,11 @@ CALLOUTS
        attempt starting at the fourth character of the  subject  string,  when
        the  pointer  was  at  the seventh character, and when the next pattern
        item was \d. Just one circumflex is output if  the  start  and  current
-       positions are the same.
+       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
-       a result of the /auto_callout pattern modifier. In this  case,  instead
+       a  result  of the /auto_callout pattern modifier. In this case, instead
        of showing the callout number, the offset in the pattern, preceded by a
        plus, is output. For example:
 
@@ -1396,7 +1403,7 @@ CALLOUTS
           0: E*
 
        If a pattern contains (*MARK) items, an additional line is output when-
-       ever  a  change  of  latest mark is passed to the callout function. For
+       ever a change of latest mark is passed to  the  callout  function.  For
        example:
 
            re> /a(*MARK:X)bc/auto_callout
@@ -1410,17 +1417,17 @@ CALLOUTS
          +12 ^  ^
           0: abc
 
-       The mark changes between matching "a" and "b", but stays the  same  for
-       the  rest  of  the match, so nothing more is output. If, as a result of
-       backtracking, the mark reverts to being unset, the  text  ""  is
+       The  mark  changes between matching "a" and "b", but stays the same for
+       the rest of the match, so nothing more is output. If, as  a  result  of
+       backtracking,  the  mark  reverts to being unset, the text "" is
        output.
 
    Callouts with string arguments
 
        The output for a callout with a string argument is similar, except that
-       instead of outputting a callout number before the position  indicators,
-       the  callout  string  and  its  offset in the pattern string are output
-       before the reflection of the subject string, and the subject string  is
+       instead  of outputting a callout number before the position indicators,
+       the callout string and its offset in  the  pattern  string  are  output
+       before  the reflection of the subject string, and the subject string is
        reflected for each callout. For example:
 
            re> /^ab(?C'first')cd(?C"second")ef/
@@ -1437,41 +1444,46 @@ CALLOUTS
 NON-PRINTING CHARACTERS
 
        When pcre2test is outputting text in the compiled version of a pattern,
-       bytes other than 32-126 are always treated as  non-printing  characters
+       bytes  other  than 32-126 are always treated as non-printing characters
        and are therefore shown as hex escapes.
 
-       When  pcre2test  is outputting text that is a matched part of a subject
-       string, it behaves in the same way, unless a different locale has  been
-       set  for  the  pattern  (using the /locale modifier). In this case, the
-       isprint() function is used to  distinguish  printing  and  non-printing
+       When pcre2test is outputting text that is a matched part of  a  subject
+       string,  it behaves in the same way, unless a different locale has been
+       set for the pattern (using the /locale modifier).  In  this  case,  the
+       isprint()  function  is  used  to distinguish printing and non-printing
        characters.
 
 
 SAVING AND RESTORING COMPILED PATTERNS
 
-       It  is  possible  to  save  compiled patterns on disc or elsewhere, and
+       It is possible to save compiled patterns  on  disc  or  elsewhere,  and
        reload them later, subject to a number of restrictions. JIT data cannot
-       be  saved.  The host on which the patterns are reloaded must be running
+       be saved. The host on which the patterns are reloaded must  be  running
        the same version of PCRE2, with the same code unit width, and must also
-       have  the  same  endianness,  pointer width and PCRE2_SIZE type. Before
-       compiled patterns can be saved they must be serialized, that  is,  con-
-       verted  to a stream of bytes. A single byte stream may contain any num-
-       ber of compiled patterns, but they must  all  use  the  same  character
+       have the same endianness, pointer width  and  PCRE2_SIZE  type.  Before
+       compiled  patterns  can be saved they must be serialized, that is, con-
+       verted to a stream of bytes. A single byte stream may contain any  num-
+       ber  of  compiled  patterns,  but  they must all use the same character
        tables. A single copy of the tables is included in the byte stream (its
        size is 1088 bytes).
 
-       The functions whose names begin  with  pcre2_serialize_  are  used  for
-       serializing  and de-serializing. They are described in the pcre2serial-
+       The  functions  whose  names  begin  with pcre2_serialize_ are used for
+       serializing and de-serializing. They are described in the  pcre2serial-
        ize  documentation.  In  this  section  we  describe  the  features  of
        pcre2test that can be used to test these functions.
 
-       When  a  pattern  with  push  modifier  is successfully compiled, it is
-       pushed onto a stack of compiled patterns,  and  pcre2test  expects  the
-       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.
-       The  push  modifier  is  incompatible with posix, and control modifiers
-       that act at match time are ignored (with a message). The jitverify mod-
-       ifier applies only at compile time. The command
+       When a pattern with push  modifier  is  successfully  compiled,  it  is
+       pushed  onto  a  stack  of compiled patterns, and pcre2test expects the
+       next line to contain a new pattern (or command) instead  of  a  subject
+       line.  By contrast, the pushcopy modifier causes a copy of the compiled
+       pattern to be stacked, leaving the  original  available  for  immediate
+       matching.  By  using  push and/or pushcopy, a number of patterns can be
+       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 
 
@@ -1488,9 +1500,10 @@ SAVING AND RESTORING COMPILED PATTERNS
        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
        only  control  modifiers that act after a pattern has been compiled. In
-       particular, hex, posix, posix_nosub, and push are not allowed, nor  are
-       any  option-setting  modifiers.  The JIT modifiers are, however permit-
-       ted. Here is an example that saves and reloads two patterns.
+       particular,  hex,  posix,  posix_nosub,  push,  and  pushcopy  are  not
+       allowed,  nor are any option-setting modifiers.  The JIT modifiers are,
+       however permitted. Here is an example that saves and reloads  two  pat-
+       terns.
 
          /abc/push
          /xyz/push
@@ -1502,9 +1515,13 @@ SAVING AND RESTORING COMPILED PATTERNS
          #pop jit,bincode
          abc
 
-       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.
 
+       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
 
@@ -1521,5 +1538,5 @@ AUTHOR
 
 REVISION
 
-       Last updated: 31 January 2016
+       Last updated: 06 February 2016
        Copyright (c) 1997-2016 University of Cambridge.