1PCRE2API(3)                Library Functions Manual                PCRE2API(3)
2
3
4

NAME

6       PCRE2 - Perl-compatible regular expressions (revised API)
7
8       #include <pcre2.h>
9
10       PCRE2  is  a  new API for PCRE, starting at release 10.0. This document
11       contains a description of all its native functions. See the pcre2 docu‐
12       ment for an overview of all the PCRE2 documentation.
13

PCRE2 NATIVE API BASIC FUNCTIONS

15
16       pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE length,
17         uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset,
18         pcre2_compile_context *ccontext);
19
20       void pcre2_code_free(pcre2_code *code);
21
22       pcre2_match_data *pcre2_match_data_create(uint32_t ovecsize,
23         pcre2_general_context *gcontext);
24
25       pcre2_match_data *pcre2_match_data_create_from_pattern(
26         const pcre2_code *code, pcre2_general_context *gcontext);
27
28       int pcre2_match(const pcre2_code *code, PCRE2_SPTR subject,
29         PCRE2_SIZE length, PCRE2_SIZE startoffset,
30         uint32_t options, pcre2_match_data *match_data,
31         pcre2_match_context *mcontext);
32
33       int pcre2_dfa_match(const pcre2_code *code, PCRE2_SPTR subject,
34         PCRE2_SIZE length, PCRE2_SIZE startoffset,
35         uint32_t options, pcre2_match_data *match_data,
36         pcre2_match_context *mcontext,
37         int *workspace, PCRE2_SIZE wscount);
38
39       void pcre2_match_data_free(pcre2_match_data *match_data);
40

PCRE2 NATIVE API AUXILIARY MATCH FUNCTIONS

42
43       PCRE2_SPTR pcre2_get_mark(pcre2_match_data *match_data);
44
45       uint32_t pcre2_get_ovector_count(pcre2_match_data *match_data);
46
47       PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *match_data);
48
49       PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data);
50

PCRE2 NATIVE API GENERAL CONTEXT FUNCTIONS

52
53       pcre2_general_context *pcre2_general_context_create(
54         void *(*private_malloc)(PCRE2_SIZE, void *),
55         void (*private_free)(void *, void *), void *memory_data);
56
57       pcre2_general_context *pcre2_general_context_copy(
58         pcre2_general_context *gcontext);
59
60       void pcre2_general_context_free(pcre2_general_context *gcontext);
61

PCRE2 NATIVE API COMPILE CONTEXT FUNCTIONS

63
64       pcre2_compile_context *pcre2_compile_context_create(
65         pcre2_general_context *gcontext);
66
67       pcre2_compile_context *pcre2_compile_context_copy(
68         pcre2_compile_context *ccontext);
69
70       void pcre2_compile_context_free(pcre2_compile_context *ccontext);
71
72       int pcre2_set_bsr(pcre2_compile_context *ccontext,
73         uint32_t value);
74
75       int pcre2_set_character_tables(pcre2_compile_context *ccontext,
76         const uint8_t *tables);
77
78       int pcre2_set_compile_extra_options(pcre2_compile_context *ccontext,
79         uint32_t extra_options);
80
81       int pcre2_set_max_pattern_length(pcre2_compile_context *ccontext,
82         PCRE2_SIZE value);
83
84       int pcre2_set_newline(pcre2_compile_context *ccontext,
85         uint32_t value);
86
87       int pcre2_set_parens_nest_limit(pcre2_compile_context *ccontext,
88         uint32_t value);
89
90       int pcre2_set_compile_recursion_guard(pcre2_compile_context *ccontext,
91         int (*guard_function)(uint32_t, void *), void *user_data);
92

PCRE2 NATIVE API MATCH CONTEXT FUNCTIONS

94
95       pcre2_match_context *pcre2_match_context_create(
96         pcre2_general_context *gcontext);
97
98       pcre2_match_context *pcre2_match_context_copy(
99         pcre2_match_context *mcontext);
100
101       void pcre2_match_context_free(pcre2_match_context *mcontext);
102
103       int pcre2_set_callout(pcre2_match_context *mcontext,
104         int (*callout_function)(pcre2_callout_block *, void *),
105         void *callout_data);
106
107       int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
108         int (*callout_function)(pcre2_substitute_callout_block *, void *),
109         void *callout_data);
110
111       int pcre2_set_offset_limit(pcre2_match_context *mcontext,
112         PCRE2_SIZE value);
113
114       int pcre2_set_heap_limit(pcre2_match_context *mcontext,
115         uint32_t value);
116
117       int pcre2_set_match_limit(pcre2_match_context *mcontext,
118         uint32_t value);
119
120       int pcre2_set_depth_limit(pcre2_match_context *mcontext,
121         uint32_t value);
122

PCRE2 NATIVE API STRING EXTRACTION FUNCTIONS

124
125       int pcre2_substring_copy_byname(pcre2_match_data *match_data,
126         PCRE2_SPTR name, PCRE2_UCHAR *buffer, PCRE2_SIZE *bufflen);
127
128       int pcre2_substring_copy_bynumber(pcre2_match_data *match_data,
129         uint32_t number, PCRE2_UCHAR *buffer,
130         PCRE2_SIZE *bufflen);
131
132       void pcre2_substring_free(PCRE2_UCHAR *buffer);
133
134       int pcre2_substring_get_byname(pcre2_match_data *match_data,
135         PCRE2_SPTR name, PCRE2_UCHAR **bufferptr, PCRE2_SIZE *bufflen);
136
137       int pcre2_substring_get_bynumber(pcre2_match_data *match_data,
138         uint32_t number, PCRE2_UCHAR **bufferptr,
139         PCRE2_SIZE *bufflen);
140
141       int pcre2_substring_length_byname(pcre2_match_data *match_data,
142         PCRE2_SPTR name, PCRE2_SIZE *length);
143
144       int pcre2_substring_length_bynumber(pcre2_match_data *match_data,
145         uint32_t number, PCRE2_SIZE *length);
146
147       int pcre2_substring_nametable_scan(const pcre2_code *code,
148         PCRE2_SPTR name, PCRE2_SPTR *first, PCRE2_SPTR *last);
149
150       int pcre2_substring_number_from_name(const pcre2_code *code,
151         PCRE2_SPTR name);
152
153       void pcre2_substring_list_free(PCRE2_SPTR *list);
154
155       int pcre2_substring_list_get(pcre2_match_data *match_data,
156         PCRE2_UCHAR ***listptr, PCRE2_SIZE **lengthsptr);
157

PCRE2 NATIVE API STRING SUBSTITUTION FUNCTION

159
160       int pcre2_substitute(const pcre2_code *code, PCRE2_SPTR subject,
161         PCRE2_SIZE length, PCRE2_SIZE startoffset,
162         uint32_t options, pcre2_match_data *match_data,
163         pcre2_match_context *mcontext, PCRE2_SPTR replacementz,
164         PCRE2_SIZE rlength, PCRE2_UCHAR *outputbuffer,
165         PCRE2_SIZE *outlengthptr);
166

PCRE2 NATIVE API JIT FUNCTIONS

168
169       int pcre2_jit_compile(pcre2_code *code, uint32_t options);
170
171       int pcre2_jit_match(const pcre2_code *code, PCRE2_SPTR subject,
172         PCRE2_SIZE length, PCRE2_SIZE startoffset,
173         uint32_t options, pcre2_match_data *match_data,
174         pcre2_match_context *mcontext);
175
176       void pcre2_jit_free_unused_memory(pcre2_general_context *gcontext);
177
178       pcre2_jit_stack *pcre2_jit_stack_create(PCRE2_SIZE startsize,
179         PCRE2_SIZE maxsize, pcre2_general_context *gcontext);
180
181       void pcre2_jit_stack_assign(pcre2_match_context *mcontext,
182         pcre2_jit_callback callback_function, void *callback_data);
183
184       void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack);
185

PCRE2 NATIVE API SERIALIZATION FUNCTIONS

187
188       int32_t pcre2_serialize_decode(pcre2_code **codes,
189         int32_t number_of_codes, const uint8_t *bytes,
190         pcre2_general_context *gcontext);
191
192       int32_t pcre2_serialize_encode(const pcre2_code **codes,
193         int32_t number_of_codes, uint8_t **serialized_bytes,
194         PCRE2_SIZE *serialized_size, pcre2_general_context *gcontext);
195
196       void pcre2_serialize_free(uint8_t *bytes);
197
198       int32_t pcre2_serialize_get_number_of_codes(const uint8_t *bytes);
199

PCRE2 NATIVE API AUXILIARY FUNCTIONS

201
202       pcre2_code *pcre2_code_copy(const pcre2_code *code);
203
204       pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *code);
205
206       int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer,
207         PCRE2_SIZE bufflen);
208
209       const uint8_t *pcre2_maketables(pcre2_general_context *gcontext);
210
211       void pcre2_maketables_free(pcre2_general_context *gcontext,
212         const uint8_t *tables);
213
214       int pcre2_pattern_info(const pcre2_code *code, uint32_t what,
215         void *where);
216
217       int pcre2_callout_enumerate(const pcre2_code *code,
218         int (*callback)(pcre2_callout_enumerate_block *, void *),
219         void *user_data);
220
221       int pcre2_config(uint32_t what, void *where);
222

PCRE2 NATIVE API OBSOLETE FUNCTIONS

224
225       int pcre2_set_recursion_limit(pcre2_match_context *mcontext,
226         uint32_t value);
227
228       int pcre2_set_recursion_memory_management(
229         pcre2_match_context *mcontext,
230         void *(*private_malloc)(PCRE2_SIZE, void *),
231         void (*private_free)(void *, void *), void *memory_data);
232
233       These  functions became obsolete at release 10.30 and are retained only
234       for backward compatibility. They should not be used in  new  code.  The
235       first  is  replaced by pcre2_set_depth_limit(); the second is no longer
236       needed and has no effect (it always returns zero).
237

PCRE2 EXPERIMENTAL PATTERN CONVERSION FUNCTIONS

239
240       pcre2_convert_context *pcre2_convert_context_create(
241         pcre2_general_context *gcontext);
242
243       pcre2_convert_context *pcre2_convert_context_copy(
244         pcre2_convert_context *cvcontext);
245
246       void pcre2_convert_context_free(pcre2_convert_context *cvcontext);
247
248       int pcre2_set_glob_escape(pcre2_convert_context *cvcontext,
249         uint32_t escape_char);
250
251       int pcre2_set_glob_separator(pcre2_convert_context *cvcontext,
252         uint32_t separator_char);
253
254       int pcre2_pattern_convert(PCRE2_SPTR pattern, PCRE2_SIZE length,
255         uint32_t options, PCRE2_UCHAR **buffer,
256         PCRE2_SIZE *blength, pcre2_convert_context *cvcontext);
257
258       void pcre2_converted_pattern_free(PCRE2_UCHAR *converted_pattern);
259
260       These functions provide a way of  converting  non-PCRE2  patterns  into
261       patterns that can be processed by pcre2_compile(). This facility is ex‐
262       perimental and may be changed in future releases. At  present,  "globs"
263       and  POSIX  basic  and  extended patterns can be converted. Details are
264       given in the pcre2convert documentation.
265

PCRE2 8-BIT, 16-BIT, AND 32-BIT LIBRARIES

267
268       There are three PCRE2 libraries, supporting 8-bit, 16-bit,  and  32-bit
269       code  units,  respectively.  However,  there  is  just one header file,
270       pcre2.h.  This contains the function prototypes and  other  definitions
271       for all three libraries. One, two, or all three can be installed simul‐
272       taneously. On Unix-like systems the libraries  are  called  libpcre2-8,
273       libpcre2-16, and libpcre2-32, and they can also co-exist with the orig‐
274       inal PCRE libraries.
275
276       Character strings are passed to and from a PCRE2 library as a  sequence
277       of  unsigned  integers  in  code  units of the appropriate width. Every
278       PCRE2 function comes in three different forms, one  for  each  library,
279       for example:
280
281         pcre2_compile_8()
282         pcre2_compile_16()
283         pcre2_compile_32()
284
285       There are also three different sets of data types:
286
287         PCRE2_UCHAR8, PCRE2_UCHAR16, PCRE2_UCHAR32
288         PCRE2_SPTR8,  PCRE2_SPTR16,  PCRE2_SPTR32
289
290       The  UCHAR  types define unsigned code units of the appropriate widths.
291       For example, PCRE2_UCHAR16 is usually defined as `uint16_t'.  The  SPTR
292       types  are  constant  pointers  to the equivalent UCHAR types, that is,
293       they are pointers to vectors of unsigned code units.
294
295       Many applications use only one code unit width. For their  convenience,
296       macros are defined whose names are the generic forms such as pcre2_com‐
297       pile() and  PCRE2_SPTR.  These  macros  use  the  value  of  the  macro
298       PCRE2_CODE_UNIT_WIDTH  to generate the appropriate width-specific func‐
299       tion and macro names.  PCRE2_CODE_UNIT_WIDTH is not defined by default.
300       An  application  must  define  it  to  be 8, 16, or 32 before including
301       pcre2.h in order to make use of the generic names.
302
303       Applications that use more than one code unit width can be linked  with
304       more  than  one PCRE2 library, but must define PCRE2_CODE_UNIT_WIDTH to
305       be 0 before including pcre2.h, and then use the  real  function  names.
306       Any  code  that  is to be included in an environment where the value of
307       PCRE2_CODE_UNIT_WIDTH is unknown should  also  use  the  real  function
308       names. (Unfortunately, it is not possible in C code to save and restore
309       the value of a macro.)
310
311       If PCRE2_CODE_UNIT_WIDTH is not defined  before  including  pcre2.h,  a
312       compiler error occurs.
313
314       When  using  multiple  libraries  in an application, you must take care
315       when processing any particular pattern to use  only  functions  from  a
316       single  library.   For example, if you want to run a match using a pat‐
317       tern that was compiled with pcre2_compile_16(), you  must  do  so  with
318       pcre2_match_16(), not pcre2_match_8() or pcre2_match_32().
319
320       In  the  function summaries above, and in the rest of this document and
321       other PCRE2 documents, functions and data  types  are  described  using
322       their generic names, without the _8, _16, or _32 suffix.
323

PCRE2 API OVERVIEW

325
326       PCRE2  has  its  own  native  API, which is described in this document.
327       There are also some wrapper functions for the 8-bit library that corre‐
328       spond  to the POSIX regular expression API, but they do not give access
329       to all the functionality of PCRE2. They are described in the pcre2posix
330       documentation. Both these APIs define a set of C function calls.
331
332       The  native  API  C data types, function prototypes, option values, and
333       error codes are defined in the header file pcre2.h, which also contains
334       definitions of PCRE2_MAJOR and PCRE2_MINOR, the major and minor release
335       numbers for the library. Applications can use these to include  support
336       for different releases of PCRE2.
337
338       In a Windows environment, if you want to statically link an application
339       program against a non-dll PCRE2 library, you must  define  PCRE2_STATIC
340       before including pcre2.h.
341
342       The  functions pcre2_compile() and pcre2_match() are used for compiling
343       and matching regular expressions in a Perl-compatible manner. A  sample
344       program that demonstrates the simplest way of using them is provided in
345       the file called pcre2demo.c in the PCRE2 source distribution. A listing
346       of  this  program  is  given  in  the  pcre2demo documentation, and the
347       pcre2sample documentation describes how to compile and run it.
348
349       The compiling and matching functions recognize various options that are
350       passed as bits in an options argument. There are also some more compli‐
351       cated parameters such as custom memory  management  functions  and  re‐
352       source  limits  that  are  passed  in "contexts" (which are just memory
353       blocks, described below). Simple applications do not need to  make  use
354       of contexts.
355
356       Just-in-time  (JIT)  compiler  support  is an optional feature of PCRE2
357       that can be built in  appropriate  hardware  environments.  It  greatly
358       speeds  up  the matching performance of many patterns. Programs can re‐
359       quest that it be used if available by calling pcre2_jit_compile() after
360       a  pattern has been successfully compiled by pcre2_compile(). This does
361       nothing if JIT support is not available.
362
363       More complicated programs might need to  make  use  of  the  specialist
364       functions    pcre2_jit_stack_create(),    pcre2_jit_stack_free(),   and
365       pcre2_jit_stack_assign() in order to control the JIT code's memory  us‐
366       age.
367
368       JIT matching is automatically used by pcre2_match() if it is available,
369       unless the PCRE2_NO_JIT option is set. There is also a direct interface
370       for  JIT  matching,  which gives improved performance at the expense of
371       less sanity checking. The JIT-specific functions are discussed  in  the
372       pcre2jit documentation.
373
374       A  second  matching function, pcre2_dfa_match(), which is not Perl-com‐
375       patible, is also provided. This uses  a  different  algorithm  for  the
376       matching.  The  alternative  algorithm finds all possible matches (at a
377       given point in the subject), and scans the subject  just  once  (unless
378       there  are lookaround assertions). However, this algorithm does not re‐
379       turn captured substrings. A description of the two matching  algorithms
380       and  their  advantages  and disadvantages is given in the pcre2matching
381       documentation. There is no JIT support for pcre2_dfa_match().
382
383       In addition to the main compiling and  matching  functions,  there  are
384       convenience functions for extracting captured substrings from a subject
385       string that has been matched by pcre2_match(). They are:
386
387         pcre2_substring_copy_byname()
388         pcre2_substring_copy_bynumber()
389         pcre2_substring_get_byname()
390         pcre2_substring_get_bynumber()
391         pcre2_substring_list_get()
392         pcre2_substring_length_byname()
393         pcre2_substring_length_bynumber()
394         pcre2_substring_nametable_scan()
395         pcre2_substring_number_from_name()
396
397       pcre2_substring_free() and pcre2_substring_list_free()  are  also  pro‐
398       vided,  to  free  memory used for extracted strings. If either of these
399       functions is called with a NULL argument, the function returns  immedi‐
400       ately without doing anything.
401
402       The  function  pcre2_substitute()  can be called to match a pattern and
403       return a copy of the subject string with substitutions for  parts  that
404       were matched.
405
406       Functions  whose  names begin with pcre2_serialize_ are used for saving
407       compiled patterns on disc or elsewhere, and reloading them later.
408
409       Finally, there are functions for finding out information about  a  com‐
410       piled  pattern  (pcre2_pattern_info()) and about the configuration with
411       which PCRE2 was built (pcre2_config()).
412
413       Functions with names ending with _free() are used  for  freeing  memory
414       blocks  of  various  sorts.  In all cases, if one of these functions is
415       called with a NULL argument, it does nothing.
416

STRING LENGTHS AND OFFSETS

418
419       The PCRE2 API uses string lengths and  offsets  into  strings  of  code
420       units  in  several  places. These values are always of type PCRE2_SIZE,
421       which is an unsigned integer type, currently always defined as  size_t.
422       The  largest  value  that  can  be  stored  in  such  a  type  (that is
423       ~(PCRE2_SIZE)0) is reserved as a special indicator for  zero-terminated
424       strings  and  unset offsets.  Therefore, the longest string that can be
425       handled is one less than this maximum.
426

NEWLINES

428
429       PCRE2 supports five different conventions for indicating line breaks in
430       strings:  a  single  CR (carriage return) character, a single LF (line‐
431       feed) character, the two-character sequence CRLF, any of the three pre‐
432       ceding,  or any Unicode newline sequence. The Unicode newline sequences
433       are the three just mentioned, plus the single characters  VT  (vertical
434       tab, U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line
435       separator, U+2028), and PS (paragraph separator, U+2029).
436
437       Each of the first three conventions is used by at least  one  operating
438       system as its standard newline sequence. When PCRE2 is built, a default
439       can be specified.  If it is not, the default is set to LF, which is the
440       Unix standard. However, the newline convention can be changed by an ap‐
441       plication when calling pcre2_compile(), or it can be specified by  spe‐
442       cial  text at the start of the pattern itself; this overrides any other
443       settings. See the pcre2pattern page for details of the special  charac‐
444       ter sequences.
445
446       In  the  PCRE2  documentation  the  word "newline" is used to mean "the
447       character or pair of characters that indicate a line break". The choice
448       of  newline convention affects the handling of the dot, circumflex, and
449       dollar metacharacters, the handling of #-comments in /x mode, and, when
450       CRLF  is a recognized line ending sequence, the match position advance‐
451       ment for a non-anchored pattern. There is more detail about this in the
452       section on pcre2_match() options below.
453
454       The  choice of newline convention does not affect the interpretation of
455       the \n or \r escape sequences, nor does it affect what \R matches; this
456       has its own separate convention.
457

MULTITHREADING

459
460       In  a multithreaded application it is important to keep thread-specific
461       data separate from data that can be shared between threads.  The  PCRE2
462       library  code  itself  is  thread-safe: it contains no static or global
463       variables. The API is designed to be fairly simple for non-threaded ap‐
464       plications  while at the same time ensuring that multithreaded applica‐
465       tions can use it.
466
467       There are several different blocks of data that are used to pass infor‐
468       mation between the application and the PCRE2 libraries.
469
470   The compiled pattern
471
472       A  pointer  to  the  compiled form of a pattern is returned to the user
473       when pcre2_compile() is successful. The data in the compiled pattern is
474       fixed,  and  does not change when the pattern is matched. Therefore, it
475       is thread-safe, that is, the same compiled pattern can be used by  more
476       than one thread simultaneously. For example, an application can compile
477       all its patterns at the start, before forking off multiple threads that
478       use  them.  However,  if the just-in-time (JIT) optimization feature is
479       being used, it needs separate memory stack areas for each  thread.  See
480       the pcre2jit documentation for more details.
481
482       In  a more complicated situation, where patterns are compiled only when
483       they are first needed, but are still shared between  threads,  pointers
484       to  compiled  patterns  must  be protected from simultaneous writing by
485       multiple threads. This is somewhat tricky to do correctly. If you  know
486       that  writing  to  a pointer is atomic in your environment, you can use
487       logic like this:
488
489         Get a read-only (shared) lock (mutex) for pointer
490         if (pointer == NULL)
491           {
492           Get a write (unique) lock for pointer
493           if (pointer == NULL) pointer = pcre2_compile(...
494           }
495         Release the lock
496         Use pointer in pcre2_match()
497
498       Of course, testing for compilation errors should also  be  included  in
499       the code.
500
501       The  reason  for checking the pointer a second time is as follows: Sev‐
502       eral threads may have acquired the shared lock and tested  the  pointer
503       for being NULL, but only one of them will be given the write lock, with
504       the rest kept waiting. The winning thread will compile the pattern  and
505       store  the  result.  After this thread releases the write lock, another
506       thread will get it, and if it does not retest pointer for  being  NULL,
507       will recompile the pattern and overwrite the pointer, creating a memory
508       leak and possibly causing other issues.
509
510       In an environment where writing to a pointer may  not  be  atomic,  the
511       above  logic  is not sufficient. The thread that is doing the compiling
512       may be descheduled after writing only part of the pointer, which  could
513       cause  other  threads  to use an invalid value. Instead of checking the
514       pointer itself, a separate "pointer is valid" flag (that can be updated
515       atomically) must be used:
516
517         Get a read-only (shared) lock (mutex) for pointer
518         if (!pointer_is_valid)
519           {
520           Get a write (unique) lock for pointer
521           if (!pointer_is_valid)
522             {
523             pointer = pcre2_compile(...
524             pointer_is_valid = TRUE
525             }
526           }
527         Release the lock
528         Use pointer in pcre2_match()
529
530       If JIT is being used, but the JIT compilation is not being done immedi‐
531       ately (perhaps waiting to see if the pattern  is  used  often  enough),
532       similar  logic  is required. JIT compilation updates a value within the
533       compiled code block, so a thread must gain unique write access  to  the
534       pointer     before    calling    pcre2_jit_compile().    Alternatively,
535       pcre2_code_copy() or pcre2_code_copy_with_tables() can be used  to  ob‐
536       tain  a  private  copy of the compiled code before calling the JIT com‐
537       piler.
538
539   Context blocks
540
541       The next main section below introduces the idea of "contexts" in  which
542       PCRE2 functions are called. A context is nothing more than a collection
543       of parameters that control the way PCRE2 operates. Grouping a number of
544       parameters together in a context is a convenient way of passing them to
545       a PCRE2 function without using lots of arguments. The  parameters  that
546       are  stored  in  contexts  are in some sense "advanced features" of the
547       API. Many straightforward applications will not need to use contexts.
548
549       In a multithreaded application, if the parameters in a context are val‐
550       ues  that  are  never  changed, the same context can be used by all the
551       threads. However, if any thread needs to change any value in a context,
552       it must make its own thread-specific copy.
553
554   Match blocks
555
556       The  matching  functions need a block of memory for storing the results
557       of a match. This includes details of what was matched, as well as addi‐
558       tional  information  such as the name of a (*MARK) setting. Each thread
559       must provide its own copy of this memory.
560

PCRE2 CONTEXTS

562
563       Some PCRE2 functions have a lot of parameters, many of which  are  used
564       only  by  specialist  applications,  for example, those that use custom
565       memory management or non-standard character tables.  To  keep  function
566       argument  lists  at a reasonable size, and at the same time to keep the
567       API extensible, "uncommon" parameters are passed to  certain  functions
568       in  a  context instead of directly. A context is just a block of memory
569       that holds the parameter values.  Applications that do not need to  ad‐
570       just any of the context parameters can pass NULL when a context pointer
571       is required.
572
573       There are three different types of context: a general context  that  is
574       relevant  for  several  PCRE2 operations, a compile-time context, and a
575       match-time context.
576
577   The general context
578
579       At present, this context just contains pointers to (and data  for)  ex‐
580       ternal  memory management functions that are called from several places
581       in the PCRE2 library.  The  context  is  named  `general'  rather  than
582       specifically  `memory'  because in future other fields may be added. If
583       you do not want to supply your own custom memory management  functions,
584       you  do not need to bother with a general context. A general context is
585       created by:
586
587       pcre2_general_context *pcre2_general_context_create(
588         void *(*private_malloc)(PCRE2_SIZE, void *),
589         void (*private_free)(void *, void *), void *memory_data);
590
591       The two function pointers specify custom memory  management  functions,
592       whose prototypes are:
593
594         void *private_malloc(PCRE2_SIZE, void *);
595         void  private_free(void *, void *);
596
597       Whenever code in PCRE2 calls these functions, the final argument is the
598       value of memory_data. Either of the first two arguments of the creation
599       function  may be NULL, in which case the system memory management func‐
600       tions malloc() and free() are used. (This is not currently  useful,  as
601       there  are  no  other  fields in a general context, but in future there
602       might be.)  The private_malloc() function is used (if supplied) to  ob‐
603       tain  memory for storing the context, and all three values are saved as
604       part of the context.
605
606       Whenever PCRE2 creates a data block of any kind, the block  contains  a
607       pointer  to the free() function that matches the malloc() function that
608       was used. When the time comes to  free  the  block,  this  function  is
609       called.
610
611       A general context can be copied by calling:
612
613       pcre2_general_context *pcre2_general_context_copy(
614         pcre2_general_context *gcontext);
615
616       The memory used for a general context should be freed by calling:
617
618       void pcre2_general_context_free(pcre2_general_context *gcontext);
619
620       If  this  function  is  passed  a NULL argument, it returns immediately
621       without doing anything.
622
623   The compile context
624
625       A compile context is required if you want to provide an external  func‐
626       tion  for  stack  checking  during compilation or to change the default
627       values of any of the following compile-time parameters:
628
629         What \R matches (Unicode newlines or CR, LF, CRLF only)
630         PCRE2's character tables
631         The newline character sequence
632         The compile time nested parentheses limit
633         The maximum length of the pattern string
634         The extra options bits (none set by default)
635
636       A compile context is also required if you are using custom memory  man‐
637       agement.   If  none of these apply, just pass NULL as the context argu‐
638       ment of pcre2_compile().
639
640       A compile context is created, copied, and freed by the following  func‐
641       tions:
642
643       pcre2_compile_context *pcre2_compile_context_create(
644         pcre2_general_context *gcontext);
645
646       pcre2_compile_context *pcre2_compile_context_copy(
647         pcre2_compile_context *ccontext);
648
649       void pcre2_compile_context_free(pcre2_compile_context *ccontext);
650
651       A  compile  context  is created with default values for its parameters.
652       These can be changed by calling the following functions, which return 0
653       on success, or PCRE2_ERROR_BADDATA if invalid data is detected.
654
655       int pcre2_set_bsr(pcre2_compile_context *ccontext,
656         uint32_t value);
657
658       The  value  must  be PCRE2_BSR_ANYCRLF, to specify that \R matches only
659       CR, LF, or CRLF, or PCRE2_BSR_UNICODE, to specify that \R  matches  any
660       Unicode line ending sequence. The value is used by the JIT compiler and
661       by  the  two  interpreted   matching   functions,   pcre2_match()   and
662       pcre2_dfa_match().
663
664       int pcre2_set_character_tables(pcre2_compile_context *ccontext,
665         const uint8_t *tables);
666
667       The  value  must  be  the result of a call to pcre2_maketables(), whose
668       only argument is a general context. This function builds a set of char‐
669       acter tables in the current locale.
670
671       int pcre2_set_compile_extra_options(pcre2_compile_context *ccontext,
672         uint32_t extra_options);
673
674       As  PCRE2  has developed, almost all the 32 option bits that are avail‐
675       able in the options argument of pcre2_compile() have been used  up.  To
676       avoid  running  out, the compile context contains a set of extra option
677       bits which are used for some newer, assumed rarer, options. This  func‐
678       tion  sets  those bits. It always sets all the bits (either on or off).
679       It does not modify any existing setting. The available options are  de‐
680       fined in the section entitled "Extra compile options" below.
681
682       int pcre2_set_max_pattern_length(pcre2_compile_context *ccontext,
683         PCRE2_SIZE value);
684
685       This  sets a maximum length, in code units, for any pattern string that
686       is compiled with this context. If the pattern is longer,  an  error  is
687       generated.   This facility is provided so that applications that accept
688       patterns from external sources can limit their size. The default is the
689       largest  number  that  a  PCRE2_SIZE variable can hold, which is effec‐
690       tively unlimited.
691
692       int pcre2_set_newline(pcre2_compile_context *ccontext,
693         uint32_t value);
694
695       This specifies which characters or character sequences are to be recog‐
696       nized  as newlines. The value must be one of PCRE2_NEWLINE_CR (carriage
697       return only), PCRE2_NEWLINE_LF (linefeed only), PCRE2_NEWLINE_CRLF (the
698       two-character  sequence  CR followed by LF), PCRE2_NEWLINE_ANYCRLF (any
699       of the above), PCRE2_NEWLINE_ANY (any  Unicode  newline  sequence),  or
700       PCRE2_NEWLINE_NUL (the NUL character, that is a binary zero).
701
702       A pattern can override the value set in the compile context by starting
703       with a sequence such as (*CRLF). See the pcre2pattern page for details.
704
705       When a  pattern  is  compiled  with  the  PCRE2_EXTENDED  or  PCRE2_EX‐
706       TENDED_MORE  option,  the newline convention affects the recognition of
707       the end of internal comments starting with #. The value is  saved  with
708       the  compiled pattern for subsequent use by the JIT compiler and by the
709       two    interpreted    matching     functions,     pcre2_match()     and
710       pcre2_dfa_match().
711
712       int pcre2_set_parens_nest_limit(pcre2_compile_context *ccontext,
713         uint32_t value);
714
715       This  parameter  adjusts  the  limit,  set when PCRE2 is built (default
716       250), on the depth of parenthesis nesting  in  a  pattern.  This  limit
717       stops  rogue  patterns  using  up too much system stack when being com‐
718       piled. The limit applies to parentheses of all kinds, not just  captur‐
719       ing parentheses.
720
721       int pcre2_set_compile_recursion_guard(pcre2_compile_context *ccontext,
722         int (*guard_function)(uint32_t, void *), void *user_data);
723
724       There  is at least one application that runs PCRE2 in threads with very
725       limited system stack, where running out of stack is to  be  avoided  at
726       all  costs. The parenthesis limit above cannot take account of how much
727       stack is actually available during compilation. For  a  finer  control,
728       you  can  supply  a  function  that  is called whenever pcre2_compile()
729       starts to compile a parenthesized part of a pattern. This function  can
730       check  the  actual  stack  size  (or anything else that it wants to, of
731       course).
732
733       The first argument to the callout function gives the current  depth  of
734       nesting,  and  the second is user data that is set up by the last argu‐
735       ment  of  pcre2_set_compile_recursion_guard().  The  callout   function
736       should return zero if all is well, or non-zero to force an error.
737
738   The match context
739
740       A match context is required if you want to:
741
742         Set up a callout function
743         Set an offset limit for matching an unanchored pattern
744         Change the limit on the amount of heap used when matching
745         Change the backtracking match limit
746         Change the backtracking depth limit
747         Set custom memory management specifically for the match
748
749       If  none  of  these  apply,  just  pass NULL as the context argument of
750       pcre2_match(), pcre2_dfa_match(), or pcre2_jit_match().
751
752       A match context is created, copied, and freed by  the  following  func‐
753       tions:
754
755       pcre2_match_context *pcre2_match_context_create(
756         pcre2_general_context *gcontext);
757
758       pcre2_match_context *pcre2_match_context_copy(
759         pcre2_match_context *mcontext);
760
761       void pcre2_match_context_free(pcre2_match_context *mcontext);
762
763       A  match  context  is  created  with default values for its parameters.
764       These can be changed by calling the following functions, which return 0
765       on success, or PCRE2_ERROR_BADDATA if invalid data is detected.
766
767       int pcre2_set_callout(pcre2_match_context *mcontext,
768         int (*callout_function)(pcre2_callout_block *, void *),
769         void *callout_data);
770
771       This  sets  up a callout function for PCRE2 to call at specified points
772       during a matching operation. Details are given in the pcre2callout doc‐
773       umentation.
774
775       int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
776         int (*callout_function)(pcre2_substitute_callout_block *, void *),
777         void *callout_data);
778
779       This  sets up a callout function for PCRE2 to call after each substitu‐
780       tion made by pcre2_substitute(). Details are given in the section enti‐
781       tled "Creating a new string with substitutions" below.
782
783       int pcre2_set_offset_limit(pcre2_match_context *mcontext,
784         PCRE2_SIZE value);
785
786       The  offset_limit parameter limits how far an unanchored search can ad‐
787       vance in the subject string. The  default  value  is  PCRE2_UNSET.  The
788       pcre2_match()  and  pcre2_dfa_match()  functions return PCRE2_ERROR_NO‐
789       MATCH if a match with a starting point before or at the given offset is
790       not found. The pcre2_substitute() function makes no more substitutions.
791
792       For  example,  if the pattern /abc/ is matched against "123abc" with an
793       offset limit less than 3, the result is  PCRE2_ERROR_NOMATCH.  A  match
794       can  never  be  found  if  the  startoffset  argument of pcre2_match(),
795       pcre2_dfa_match(), or pcre2_substitute() is  greater  than  the  offset
796       limit set in the match context.
797
798       When  using  this facility, you must set the PCRE2_USE_OFFSET_LIMIT op‐
799       tion when calling pcre2_compile() so that when JIT is in use, different
800       code  can  be  compiled. If a match is started with a non-default match
801       limit when PCRE2_USE_OFFSET_LIMIT is not set, an error is generated.
802
803       The offset limit facility can be used to track progress when  searching
804       large  subject  strings or to limit the extent of global substitutions.
805       See also the PCRE2_FIRSTLINE option, which requires a  match  to  start
806       before  or  at  the first newline that follows the start of matching in
807       the subject. If this is set with an offset limit, a match must occur in
808       the first line and also within the offset limit. In other words, which‐
809       ever limit comes first is used.
810
811       int pcre2_set_heap_limit(pcre2_match_context *mcontext,
812         uint32_t value);
813
814       The heap_limit parameter specifies, in units of kibibytes (1024 bytes),
815       the  maximum  amount  of heap memory that pcre2_match() may use to hold
816       backtracking information when running an interpretive match. This limit
817       also applies to pcre2_dfa_match(), which may use the heap when process‐
818       ing patterns with a lot of nested pattern recursion or  lookarounds  or
819       atomic groups. This limit does not apply to matching with the JIT opti‐
820       mization, which has  its  own  memory  control  arrangements  (see  the
821       pcre2jit  documentation for more details). If the limit is reached, the
822       negative error code  PCRE2_ERROR_HEAPLIMIT  is  returned.  The  default
823       limit  can be set when PCRE2 is built; if it is not, the default is set
824       very large and is essentially unlimited.
825
826       A value for the heap limit may also be supplied by an item at the start
827       of a pattern of the form
828
829         (*LIMIT_HEAP=ddd)
830
831       where  ddd  is a decimal number. However, such a setting is ignored un‐
832       less ddd is less than the limit set by the caller of pcre2_match()  or,
833       if no such limit is set, less than the default.
834
835       The  pcre2_match() function always needs some heap memory, so setting a
836       value of zero guarantees a "heap limit exceeded" error. Details of  how
837       pcre2_match()  uses  the  heap are given in the pcre2perform documenta‐
838       tion.
839
840       For pcre2_dfa_match(), a vector on the system stack is used  when  pro‐
841       cessing  pattern recursions, lookarounds, or atomic groups, and only if
842       this is not big enough is heap memory used. In  this  case,  setting  a
843       value of zero disables the use of the heap.
844
845       int pcre2_set_match_limit(pcre2_match_context *mcontext,
846         uint32_t value);
847
848       The match_limit parameter provides a means of preventing PCRE2 from us‐
849       ing up too many computing resources when processing patterns  that  are
850       not going to match, but which have a very large number of possibilities
851       in their search trees. The classic  example  is  a  pattern  that  uses
852       nested unlimited repeats.
853
854       There  is an internal counter in pcre2_match() that is incremented each
855       time round its main matching loop. If  this  value  reaches  the  match
856       limit, pcre2_match() returns the negative value PCRE2_ERROR_MATCHLIMIT.
857       This has the effect of limiting the amount  of  backtracking  that  can
858       take place. For patterns that are not anchored, the count restarts from
859       zero for each position in the subject string. This limit  also  applies
860       to pcre2_dfa_match(), though the counting is done in a different way.
861
862       When  pcre2_match() is called with a pattern that was successfully pro‐
863       cessed by pcre2_jit_compile(), the way in which matching is executed is
864       entirely  different. However, there is still the possibility of runaway
865       matching that goes on for a very long  time,  and  so  the  match_limit
866       value  is  also used in this case (but in a different way) to limit how
867       long the matching can continue.
868
869       The default value for the limit can be set when PCRE2 is built; the de‐
870       fault  default  is  10  million, which handles all but the most extreme
871       cases. A value for the match limit may also be supplied by an  item  at
872       the start of a pattern of the form
873
874         (*LIMIT_MATCH=ddd)
875
876       where  ddd  is a decimal number. However, such a setting is ignored un‐
877       less ddd is less than the limit set by the caller of  pcre2_match()  or
878       pcre2_dfa_match() or, if no such limit is set, less than the default.
879
880       int pcre2_set_depth_limit(pcre2_match_context *mcontext,
881         uint32_t value);
882
883       This   parameter   limits   the   depth   of   nested  backtracking  in
884       pcre2_match().  Each time a nested backtracking point is passed, a  new
885       memory  frame  is used to remember the state of matching at that point.
886       Thus, this parameter indirectly limits the amount  of  memory  that  is
887       used in a match. However, because the size of each memory frame depends
888       on the number of capturing parentheses, the actual memory limit  varies
889       from  pattern to pattern. This limit was more useful in versions before
890       10.30, where function recursion was used for backtracking.
891
892       The depth limit is not relevant, and is ignored, when matching is  done
893       using JIT compiled code. However, it is supported by pcre2_dfa_match(),
894       which uses it to limit the depth of nested internal recursive  function
895       calls  that implement atomic groups, lookaround assertions, and pattern
896       recursions. This limits, indirectly, the amount of system stack that is
897       used.  It  was  more useful in versions before 10.32, when stack memory
898       was used for local workspace vectors for recursive function calls. From
899       version  10.32,  only local variables are allocated on the stack and as
900       each call uses only a few hundred bytes, even a small stack can support
901       quite a lot of recursion.
902
903       If  the depth of internal recursive function calls is great enough, lo‐
904       cal workspace vectors are allocated on the heap from version 10.32  on‐
905       wards,  so  the  depth  limit also indirectly limits the amount of heap
906       memory that is used. A recursive pattern such as /(.(?2))((?1)|)/, when
907       matched  to a very long string using pcre2_dfa_match(), can use a great
908       deal of memory. However, it is probably better to limit heap usage  di‐
909       rectly by calling pcre2_set_heap_limit().
910
911       The  default  value for the depth limit can be set when PCRE2 is built;
912       if it is not, the default is set to the same value as the  default  for
913       the   match   limit.   If  the  limit  is  exceeded,  pcre2_match()  or
914       pcre2_dfa_match() returns PCRE2_ERROR_DEPTHLIMIT. A value for the depth
915       limit  may also be supplied by an item at the start of a pattern of the
916       form
917
918         (*LIMIT_DEPTH=ddd)
919
920       where ddd is a decimal number. However, such a setting is  ignored  un‐
921       less  ddd  is less than the limit set by the caller of pcre2_match() or
922       pcre2_dfa_match() or, if no such limit is set, less than the default.
923

CHECKING BUILD-TIME OPTIONS

925
926       int pcre2_config(uint32_t what, void *where);
927
928       The function pcre2_config() makes it possible for  a  PCRE2  client  to
929       find  the  value  of  certain  configuration parameters and to discover
930       which optional features have been compiled into the PCRE2 library.  The
931       pcre2build documentation has more details about these features.
932
933       The  first  argument  for pcre2_config() specifies which information is
934       required. The second argument is a pointer to memory into which the in‐
935       formation is placed. If NULL is passed, the function returns the amount
936       of memory that is needed for the requested information. For calls  that
937       return  numerical  values, the value is in bytes; when requesting these
938       values, where should point to appropriately aligned memory.  For  calls
939       that  return  strings,  the required length is given in code units, not
940       counting the terminating zero.
941
942       When requesting information, the returned value from pcre2_config()  is
943       non-negative  on success, or the negative error code PCRE2_ERROR_BADOP‐
944       TION if the value in the first argument is not recognized. The  follow‐
945       ing information is available:
946
947         PCRE2_CONFIG_BSR
948
949       The  output  is a uint32_t integer whose value indicates what character
950       sequences the \R  escape  sequence  matches  by  default.  A  value  of
951       PCRE2_BSR_UNICODE  means  that  \R  matches any Unicode line ending se‐
952       quence; a value of PCRE2_BSR_ANYCRLF means that \R matches only CR, LF,
953       or CRLF. The default can be overridden when a pattern is compiled.
954
955         PCRE2_CONFIG_COMPILED_WIDTHS
956
957       The  output  is a uint32_t integer whose lower bits indicate which code
958       unit widths were selected when PCRE2 was  built.  The  1-bit  indicates
959       8-bit  support, and the 2-bit and 4-bit indicate 16-bit and 32-bit sup‐
960       port, respectively.
961
962         PCRE2_CONFIG_DEPTHLIMIT
963
964       The output is a uint32_t integer that gives the default limit  for  the
965       depth  of  nested  backtracking in pcre2_match() or the depth of nested
966       recursions, lookarounds, and atomic groups in  pcre2_dfa_match().  Fur‐
967       ther details are given with pcre2_set_depth_limit() above.
968
969         PCRE2_CONFIG_HEAPLIMIT
970
971       The  output is a uint32_t integer that gives, in kibibytes, the default
972       limit  for  the  amount  of  heap  memory  used  by  pcre2_match()   or
973       pcre2_dfa_match().      Further      details     are     given     with
974       pcre2_set_heap_limit() above.
975
976         PCRE2_CONFIG_JIT
977
978       The output is a uint32_t integer that is set  to  one  if  support  for
979       just-in-time compiling is available; otherwise it is set to zero.
980
981         PCRE2_CONFIG_JITTARGET
982
983       The  where  argument  should point to a buffer that is at least 48 code
984       units long.  (The  exact  length  required  can  be  found  by  calling
985       pcre2_config()  with  where  set  to NULL.) The buffer is filled with a
986       string that contains the name of the architecture  for  which  the  JIT
987       compiler  is  configured,  for  example "x86 32bit (little endian + un‐
988       aligned)". If JIT support is not  available,  PCRE2_ERROR_BADOPTION  is
989       returned,  otherwise the number of code units used is returned. This is
990       the length of the string, plus one unit for the terminating zero.
991
992         PCRE2_CONFIG_LINKSIZE
993
994       The output is a uint32_t integer that contains the number of bytes used
995       for  internal  linkage  in  compiled regular expressions. When PCRE2 is
996       configured, the value can be set to 2, 3, or 4, with the default  being
997       2.  This is the value that is returned by pcre2_config(). However, when
998       the 16-bit library is compiled, a value of 3 is rounded up  to  4,  and
999       when  the  32-bit  library  is compiled, internal linkages always use 4
1000       bytes, so the configured value is not relevant.
1001
1002       The default value of 2 for the 8-bit and 16-bit libraries is sufficient
1003       for  all but the most massive patterns, since it allows the size of the
1004       compiled pattern to be up to 65535  code  units.  Larger  values  allow
1005       larger  regular  expressions to be compiled by those two libraries, but
1006       at the expense of slower matching.
1007
1008         PCRE2_CONFIG_MATCHLIMIT
1009
1010       The output is a uint32_t integer that gives the default match limit for
1011       pcre2_match().  Further  details are given with pcre2_set_match_limit()
1012       above.
1013
1014         PCRE2_CONFIG_NEWLINE
1015
1016       The output is a uint32_t integer  whose  value  specifies  the  default
1017       character  sequence that is recognized as meaning "newline". The values
1018       are:
1019
1020         PCRE2_NEWLINE_CR       Carriage return (CR)
1021         PCRE2_NEWLINE_LF       Linefeed (LF)
1022         PCRE2_NEWLINE_CRLF     Carriage return, linefeed (CRLF)
1023         PCRE2_NEWLINE_ANY      Any Unicode line ending
1024         PCRE2_NEWLINE_ANYCRLF  Any of CR, LF, or CRLF
1025         PCRE2_NEWLINE_NUL      The NUL character (binary zero)
1026
1027       The default should normally correspond to  the  standard  sequence  for
1028       your operating system.
1029
1030         PCRE2_CONFIG_NEVER_BACKSLASH_C
1031
1032       The  output  is  a uint32_t integer that is set to one if the use of \C
1033       was permanently disabled when PCRE2 was built; otherwise it is  set  to
1034       zero.
1035
1036         PCRE2_CONFIG_PARENSLIMIT
1037
1038       The  output is a uint32_t integer that gives the maximum depth of nest‐
1039       ing of parentheses (of any kind) in a pattern. This limit is imposed to
1040       cap  the  amount of system stack used when a pattern is compiled. It is
1041       specified when PCRE2 is built; the default is 250. This limit does  not
1042       take into account the stack that may already be used by the calling ap‐
1043       plication.  For  finer  control  over  compilation  stack  usage,   see
1044       pcre2_set_compile_recursion_guard().
1045
1046         PCRE2_CONFIG_STACKRECURSE
1047
1048       This parameter is obsolete and should not be used in new code. The out‐
1049       put is a uint32_t integer that is always set to zero.
1050
1051         PCRE2_CONFIG_TABLES_LENGTH
1052
1053       The output is a uint32_t integer that gives the length of PCRE2's char‐
1054       acter  processing  tables in bytes. For details of these tables see the
1055       section on locale support below.
1056
1057         PCRE2_CONFIG_UNICODE_VERSION
1058
1059       The where argument should point to a buffer that is at  least  24  code
1060       units  long.  (The  exact  length  required  can  be  found  by calling
1061       pcre2_config() with where set to NULL.)  If  PCRE2  has  been  compiled
1062       without  Unicode  support,  the buffer is filled with the text "Unicode
1063       not supported". Otherwise, the Unicode  version  string  (for  example,
1064       "8.0.0")  is  inserted. The number of code units used is returned. This
1065       is the length of the string plus one unit for the terminating zero.
1066
1067         PCRE2_CONFIG_UNICODE
1068
1069       The output is a uint32_t integer that is set to one if Unicode  support
1070       is  available; otherwise it is set to zero. Unicode support implies UTF
1071       support.
1072
1073         PCRE2_CONFIG_VERSION
1074
1075       The where argument should point to a buffer that is at  least  24  code
1076       units  long.  (The  exact  length  required  can  be  found  by calling
1077       pcre2_config() with where set to NULL.) The buffer is filled  with  the
1078       PCRE2 version string, zero-terminated. The number of code units used is
1079       returned. This is the length of the string plus one unit for the termi‐
1080       nating zero.
1081

COMPILING A PATTERN

1083
1084       pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE length,
1085         uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset,
1086         pcre2_compile_context *ccontext);
1087
1088       void pcre2_code_free(pcre2_code *code);
1089
1090       pcre2_code *pcre2_code_copy(const pcre2_code *code);
1091
1092       pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *code);
1093
1094       The  pcre2_compile() function compiles a pattern into an internal form.
1095       The pattern is defined by a pointer to a string of  code  units  and  a
1096       length  (in  code units). If the pattern is zero-terminated, the length
1097       can be specified  as  PCRE2_ZERO_TERMINATED.  The  function  returns  a
1098       pointer to a block of memory that contains the compiled pattern and re‐
1099       lated data, or NULL if an error occurred.
1100
1101       If the compile context argument ccontext is NULL, memory for  the  com‐
1102       piled  pattern  is  obtained  by calling malloc(). Otherwise, it is ob‐
1103       tained from the same memory function that was used for the compile con‐
1104       text. The caller must free the memory by calling pcre2_code_free() when
1105       it is no longer needed.  If pcre2_code_free() is called with a NULL ar‐
1106       gument, it returns immediately, without doing anything.
1107
1108       The function pcre2_code_copy() makes a copy of the compiled code in new
1109       memory, using the same memory allocator as was used for  the  original.
1110       However,  if  the  code has been processed by the JIT compiler (see be‐
1111       low), the JIT information cannot be copied (because it is  position-de‐
1112       pendent).   The  new copy can initially be used only for non-JIT match‐
1113       ing, though it can be passed to  pcre2_jit_compile()  if  required.  If
1114       pcre2_code_copy() is called with a NULL argument, it returns NULL.
1115
1116       The pcre2_code_copy() function provides a way for individual threads in
1117       a multithreaded application to acquire a private copy  of  shared  com‐
1118       piled  code.   However, it does not make a copy of the character tables
1119       used by the compiled pattern; the new pattern code points to  the  same
1120       tables  as  the original code.  (See "Locale Support" below for details
1121       of these character tables.) In many applications the  same  tables  are
1122       used  throughout, so this behaviour is appropriate. Nevertheless, there
1123       are occasions when a copy of a compiled pattern and the relevant tables
1124       are  needed.  The pcre2_code_copy_with_tables() provides this facility.
1125       Copies of both the code and the tables are  made,  with  the  new  code
1126       pointing  to the new tables. The memory for the new tables is automati‐
1127       cally freed when pcre2_code_free() is called for the new  copy  of  the
1128       compiled  code.  If pcre2_code_copy_with_tables() is called with a NULL
1129       argument, it returns NULL.
1130
1131       NOTE: When one of the matching functions is  called,  pointers  to  the
1132       compiled pattern and the subject string are set in the match data block
1133       so that they can be referenced by the  substring  extraction  functions
1134       after  a  successful match.  After running a match, you must not free a
1135       compiled pattern or a subject string until after all operations on  the
1136       match  data  block have taken place, unless, in the case of the subject
1137       string, you have used the PCRE2_COPY_MATCHED_SUBJECT option,  which  is
1138       described  in  the section entitled "Option bits for pcre2_match()" be‐
1139       low.
1140
1141       The options argument for pcre2_compile() contains various bit  settings
1142       that  affect the compilation. It should be zero if none of them are re‐
1143       quired. The available options are described below.  Some  of  them  (in
1144       particular,  those  that  are  compatible with Perl, but some others as
1145       well) can also be set and unset from within the pattern  (see  the  de‐
1146       tailed description in the pcre2pattern documentation).
1147
1148       For  those options that can be different in different parts of the pat‐
1149       tern, the contents of the options argument specifies their settings  at
1150       the  start  of  compilation. The PCRE2_ANCHORED, PCRE2_ENDANCHORED, and
1151       PCRE2_NO_UTF_CHECK options can be set at the time of matching  as  well
1152       as at compile time.
1153
1154       Some  additional  options and less frequently required compile-time pa‐
1155       rameters (for example, the newline setting) can be provided in  a  com‐
1156       pile context (as described above).
1157
1158       If errorcode or erroroffset is NULL, pcre2_compile() returns NULL imme‐
1159       diately. Otherwise, the variables to which these point are  set  to  an
1160       error code and an offset (number of code units) within the pattern, re‐
1161       spectively, when pcre2_compile() returns NULL because a compilation er‐
1162       ror has occurred.
1163
1164       There  are nearly 100 positive error codes that pcre2_compile() may re‐
1165       turn if it finds an error in the pattern. There are also some  negative
1166       error  codes that are used for invalid UTF strings when validity check‐
1167       ing is in force. These are the  same  as  given  by  pcre2_match()  and
1168       pcre2_dfa_match(), and are described in the pcre2unicode documentation.
1169       There is no separate documentation for the positive  error  codes,  be‐
1170       cause  the  textual  error  messages  that  are obtained by calling the
1171       pcre2_get_error_message() function (see "Obtaining a textual error mes‐
1172       sage"  below)  should  be  self-explanatory.  Macro names starting with
1173       PCRE2_ERROR_ are defined for both positive and negative error codes  in
1174       pcre2.h.  When  compilation  is  successful errorcode is set to a value
1175       that returns the message "no error" if passed  to  pcre2_get_error_mes‐
1176       sage().
1177
1178       The value returned in erroroffset is an indication of where in the pat‐
1179       tern an error occurred. When there is no error,  zero  is  returned.  A
1180       non-zero  value  is  not  necessarily the furthest point in the pattern
1181       that was read. For example, after the error  "lookbehind  assertion  is
1182       not  fixed length", the error offset points to the start of the failing
1183       assertion. For an invalid UTF-8 or UTF-16 string, the offset is that of
1184       the first code unit of the failing character.
1185
1186       Some  errors are not detected until the whole pattern has been scanned;
1187       in these cases, the offset passed back is the length  of  the  pattern.
1188       Note  that  the  offset is in code units, not characters, even in a UTF
1189       mode. It may sometimes point into the middle of a UTF-8 or UTF-16 char‐
1190       acter.
1191
1192       This  code  fragment shows a typical straightforward call to pcre2_com‐
1193       pile():
1194
1195         pcre2_code *re;
1196         PCRE2_SIZE erroffset;
1197         int errorcode;
1198         re = pcre2_compile(
1199           "^A.*Z",                /* the pattern */
1200           PCRE2_ZERO_TERMINATED,  /* the pattern is zero-terminated */
1201           0,                      /* default options */
1202           &errorcode,             /* for error code */
1203           &erroffset,             /* for error offset */
1204           NULL);                  /* no compile context */
1205
1206
1207   Main compile options
1208
1209       The following names for option bits are defined in the  pcre2.h  header
1210       file:
1211
1212         PCRE2_ANCHORED
1213
1214       If this bit is set, the pattern is forced to be "anchored", that is, it
1215       is constrained to match only at the first matching point in the  string
1216       that  is being searched (the "subject string"). This effect can also be
1217       achieved by appropriate constructs in the pattern itself, which is  the
1218       only way to do it in Perl.
1219
1220         PCRE2_ALLOW_EMPTY_CLASS
1221
1222       By  default, for compatibility with Perl, a closing square bracket that
1223       immediately follows an opening one is treated as a data  character  for
1224       the  class.  When  PCRE2_ALLOW_EMPTY_CLASS  is  set,  it terminates the
1225       class, which therefore contains no characters and so can never match.
1226
1227         PCRE2_ALT_BSUX
1228
1229       This option request alternative handling  of  three  escape  sequences,
1230       which  makes  PCRE2's  behaviour more like ECMAscript (aka JavaScript).
1231       When it is set:
1232
1233       (1) \U matches an upper case "U" character; by default \U causes a com‐
1234       pile time error (Perl uses \U to upper case subsequent characters).
1235
1236       (2) \u matches a lower case "u" character unless it is followed by four
1237       hexadecimal digits, in which case the hexadecimal  number  defines  the
1238       code  point  to match. By default, \u causes a compile time error (Perl
1239       uses it to upper case the following character).
1240
1241       (3) \x matches a lower case "x" character unless it is followed by  two
1242       hexadecimal  digits,  in  which case the hexadecimal number defines the
1243       code point to match. By default, as in Perl, a  hexadecimal  number  is
1244       always expected after \x, but it may have zero, one, or two digits (so,
1245       for example, \xz matches a binary zero character followed by z).
1246
1247       ECMAscript 6 added additional functionality to \u. This can be accessed
1248       using  the  PCRE2_EXTRA_ALT_BSUX  extra  option (see "Extra compile op‐
1249       tions" below).  Note that this alternative escape handling applies only
1250       to  patterns.  Neither  of  these options affects the processing of re‐
1251       placement strings passed to pcre2_substitute().
1252
1253         PCRE2_ALT_CIRCUMFLEX
1254
1255       In  multiline  mode  (when  PCRE2_MULTILINE  is  set),  the  circumflex
1256       metacharacter  matches at the start of the subject (unless PCRE2_NOTBOL
1257       is set), and also after any internal  newline.  However,  it  does  not
1258       match after a newline at the end of the subject, for compatibility with
1259       Perl. If you want a multiline circumflex also to match after  a  termi‐
1260       nating newline, you must set PCRE2_ALT_CIRCUMFLEX.
1261
1262         PCRE2_ALT_VERBNAMES
1263
1264       By  default, for compatibility with Perl, the name in any verb sequence
1265       such as (*MARK:NAME) is any sequence of characters that  does  not  in‐
1266       clude  a closing parenthesis. The name is not processed in any way, and
1267       it is not possible to include a closing parenthesis in the  name.  How‐
1268       ever,  if  the PCRE2_ALT_VERBNAMES option is set, normal backslash pro‐
1269       cessing is applied to verb names and only an unescaped  closing  paren‐
1270       thesis  terminates the name. A closing parenthesis can be included in a
1271       name either as \) or between  \Q  and  \E.  If  the  PCRE2_EXTENDED  or
1272       PCRE2_EXTENDED_MORE  option  is set with PCRE2_ALT_VERBNAMES, unescaped
1273       whitespace in verb names is skipped and #-comments are recognized,  ex‐
1274       actly as in the rest of the pattern.
1275
1276         PCRE2_AUTO_CALLOUT
1277
1278       If  this  bit  is  set,  pcre2_compile()  automatically inserts callout
1279       items, all with number 255, before each pattern  item,  except  immedi‐
1280       ately  before  or after an explicit callout in the pattern. For discus‐
1281       sion of the callout facility, see the pcre2callout documentation.
1282
1283         PCRE2_CASELESS
1284
1285       If this bit is set, letters in the pattern match both upper  and  lower
1286       case  letters in the subject. It is equivalent to Perl's /i option, and
1287       it can be changed within a pattern by a (?i) option setting. If  either
1288       PCRE2_UTF  or  PCRE2_UCP  is  set,  Unicode properties are used for all
1289       characters with more than one other case, and for all characters  whose
1290       code  points  are  greater  than  U+007F. Note that there are two ASCII
1291       characters, K and S, that, in addition to their lower case ASCII equiv‐
1292       alents,  are case-equivalent with U+212A (Kelvin sign) and U+017F (long
1293       S) respectively. For lower valued characters with only one other  case,
1294       a  lookup table is used for speed. When neither PCRE2_UTF nor PCRE2_UCP
1295       is set, a lookup table is used for all code points less than  256,  and
1296       higher  code  points  (available  only  in  16-bit  or 32-bit mode) are
1297       treated as not having another case.
1298
1299         PCRE2_DOLLAR_ENDONLY
1300
1301       If this bit is set, a dollar metacharacter in the pattern matches  only
1302       at  the  end  of the subject string. Without this option, a dollar also
1303       matches immediately before a newline at the end of the string (but  not
1304       before  any other newlines). The PCRE2_DOLLAR_ENDONLY option is ignored
1305       if PCRE2_MULTILINE is set. There is no equivalent  to  this  option  in
1306       Perl, and no way to set it within a pattern.
1307
1308         PCRE2_DOTALL
1309
1310       If  this  bit  is  set,  a dot metacharacter in the pattern matches any
1311       character, including one that indicates a  newline.  However,  it  only
1312       ever matches one character, even if newlines are coded as CRLF. Without
1313       this option, a dot does not match when the current position in the sub‐
1314       ject  is  at  a newline. This option is equivalent to Perl's /s option,
1315       and it can be changed within a pattern by a (?s) option setting. A neg‐
1316       ative  class such as [^a] always matches newline characters, and the \N
1317       escape sequence always matches a non-newline character, independent  of
1318       the setting of PCRE2_DOTALL.
1319
1320         PCRE2_DUPNAMES
1321
1322       If  this  bit is set, names used to identify capture groups need not be
1323       unique.  This can be helpful for certain types of pattern  when  it  is
1324       known  that  only  one instance of the named group can ever be matched.
1325       There are more details of named capture  groups  below;  see  also  the
1326       pcre2pattern documentation.
1327
1328         PCRE2_ENDANCHORED
1329
1330       If  this  bit is set, the end of any pattern match must be right at the
1331       end of the string being searched (the "subject string"). If the pattern
1332       match succeeds by reaching (*ACCEPT), but does not reach the end of the
1333       subject, the match fails at the current starting point. For  unanchored
1334       patterns,  a  new  match is then tried at the next starting point. How‐
1335       ever, if the match succeeds by reaching the end of the pattern, but not
1336       the  end  of  the subject, backtracking occurs and an alternative match
1337       may be found. Consider these two patterns:
1338
1339         .(*ACCEPT)|..
1340         .|..
1341
1342       If matched against "abc" with PCRE2_ENDANCHORED set, the first  matches
1343       "c"  whereas  the  second matches "bc". The effect of PCRE2_ENDANCHORED
1344       can also be achieved by appropriate constructs in the  pattern  itself,
1345       which is the only way to do it in Perl.
1346
1347       For DFA matching with pcre2_dfa_match(), PCRE2_ENDANCHORED applies only
1348       to the first (that is, the  longest)  matched  string.  Other  parallel
1349       matches,  which are necessarily substrings of the first one, must obvi‐
1350       ously end before the end of the subject.
1351
1352         PCRE2_EXTENDED
1353
1354       If this bit is set, most white space characters in the pattern are  to‐
1355       tally ignored except when escaped or inside a character class. However,
1356       white space is not allowed within sequences such as (?> that  introduce
1357       various  parenthesized groups, nor within numerical quantifiers such as
1358       {1,3}. Ignorable white space is permitted between an item and a follow‐
1359       ing  quantifier  and  between a quantifier and a following + that indi‐
1360       cates possessiveness. PCRE2_EXTENDED is equivalent to Perl's /x option,
1361       and it can be changed within a pattern by a (?x) option setting.
1362
1363       When  PCRE2  is compiled without Unicode support, PCRE2_EXTENDED recog‐
1364       nizes as white space only those characters with code points  less  than
1365       256 that are flagged as white space in its low-character table. The ta‐
1366       ble is normally created by pcre2_maketables(), which uses the isspace()
1367       function  to identify space characters. In most ASCII environments, the
1368       relevant characters are those with code  points  0x0009  (tab),  0x000A
1369       (linefeed),  0x000B (vertical tab), 0x000C (formfeed), 0x000D (carriage
1370       return), and 0x0020 (space).
1371
1372       When PCRE2 is compiled with Unicode support, in addition to these char‐
1373       acters,  five  more Unicode "Pattern White Space" characters are recog‐
1374       nized by PCRE2_EXTENDED. These are U+0085 (next line), U+200E (left-to-
1375       right  mark), U+200F (right-to-left mark), U+2028 (line separator), and
1376       U+2029 (paragraph separator). This set of characters  is  the  same  as
1377       recognized  by  Perl's /x option. Note that the horizontal and vertical
1378       space characters that are matched by the \h and \v escapes in  patterns
1379       are a much bigger set.
1380
1381       As  well as ignoring most white space, PCRE2_EXTENDED also causes char‐
1382       acters between an unescaped # outside a character class  and  the  next
1383       newline,  inclusive,  to be ignored, which makes it possible to include
1384       comments inside complicated patterns. Note that the end of this type of
1385       comment  is a literal newline sequence in the pattern; escape sequences
1386       that happen to represent a newline do not count.
1387
1388       Which characters are interpreted as newlines can be specified by a set‐
1389       ting  in  the compile context that is passed to pcre2_compile() or by a
1390       special sequence at the start of the pattern, as described in the  sec‐
1391       tion  entitled "Newline conventions" in the pcre2pattern documentation.
1392       A default is defined when PCRE2 is built.
1393
1394         PCRE2_EXTENDED_MORE
1395
1396       This option has the effect of PCRE2_EXTENDED,  but,  in  addition,  un‐
1397       escaped  space and horizontal tab characters are ignored inside a char‐
1398       acter class. Note: only these two characters are ignored, not the  full
1399       set  of pattern white space characters that are ignored outside a char‐
1400       acter class. PCRE2_EXTENDED_MORE is equivalent to  Perl's  /xx  option,
1401       and it can be changed within a pattern by a (?xx) option setting.
1402
1403         PCRE2_FIRSTLINE
1404
1405       If this option is set, the start of an unanchored pattern match must be
1406       before or at the first newline in  the  subject  string  following  the
1407       start  of  matching, though the matched text may continue over the new‐
1408       line. If startoffset is non-zero, the limiting newline is not necessar‐
1409       ily  the  first  newline  in  the  subject. For example, if the subject
1410       string is "abc\nxyz" (where \n represents a single-character newline) a
1411       pattern  match for "yz" succeeds with PCRE2_FIRSTLINE if startoffset is
1412       greater than 3. See also PCRE2_USE_OFFSET_LIMIT, which provides a  more
1413       general  limiting  facility.  If  PCRE2_FIRSTLINE is set with an offset
1414       limit, a match must occur in the first line and also within the  offset
1415       limit. In other words, whichever limit comes first is used.
1416
1417         PCRE2_LITERAL
1418
1419       If this option is set, all meta-characters in the pattern are disabled,
1420       and it is treated as a literal string. Matching literal strings with  a
1421       regular expression engine is not the most efficient way of doing it. If
1422       you are doing a lot of literal matching and  are  worried  about  effi‐
1423       ciency, you should consider using other approaches. The only other main
1424       options  that  are  allowed  with  PCRE2_LITERAL  are:  PCRE2_ANCHORED,
1425       PCRE2_ENDANCHORED, PCRE2_AUTO_CALLOUT, PCRE2_CASELESS, PCRE2_FIRSTLINE,
1426       PCRE2_MATCH_INVALID_UTF,  PCRE2_NO_START_OPTIMIZE,  PCRE2_NO_UTF_CHECK,
1427       PCRE2_UTF,  and  PCRE2_USE_OFFSET_LIMIT.  The  extra  options PCRE2_EX‐
1428       TRA_MATCH_LINE and PCRE2_EXTRA_MATCH_WORD are also supported. Any other
1429       options cause an error.
1430
1431         PCRE2_MATCH_INVALID_UTF
1432
1433       This  option  forces PCRE2_UTF (see below) and also enables support for
1434       matching by pcre2_match() in subject strings that contain  invalid  UTF
1435       sequences.   This  facility  is not supported for DFA matching. For de‐
1436       tails, see the pcre2unicode documentation.
1437
1438         PCRE2_MATCH_UNSET_BACKREF
1439
1440       If this option is set,  a  backreference  to  an  unset  capture  group
1441       matches  an  empty  string (by default this causes the current matching
1442       alternative to fail).  A pattern such as (\1)(a) succeeds when this op‐
1443       tion  is  set  (assuming it can find an "a" in the subject), whereas it
1444       fails by default, for Perl compatibility.  Setting  this  option  makes
1445       PCRE2 behave more like ECMAscript (aka JavaScript).
1446
1447         PCRE2_MULTILINE
1448
1449       By  default,  for  the purposes of matching "start of line" and "end of
1450       line", PCRE2 treats the subject string as consisting of a  single  line
1451       of  characters,  even  if  it actually contains newlines. The "start of
1452       line" metacharacter (^) matches only at the start of  the  string,  and
1453       the  "end  of  line"  metacharacter  ($) matches only at the end of the
1454       string, or before a terminating newline (except  when  PCRE2_DOLLAR_EN‐
1455       DONLY is set). Note, however, that unless PCRE2_DOTALL is set, the "any
1456       character" metacharacter (.) does not match at a newline.  This  behav‐
1457       iour (for ^, $, and dot) is the same as Perl.
1458
1459       When  PCRE2_MULTILINE  it is set, the "start of line" and "end of line"
1460       constructs match immediately following or immediately  before  internal
1461       newlines  in  the  subject string, respectively, as well as at the very
1462       start and end. This is equivalent to Perl's /m option, and  it  can  be
1463       changed within a pattern by a (?m) option setting. Note that the "start
1464       of line" metacharacter does not match after a newline at the end of the
1465       subject,  for compatibility with Perl.  However, you can change this by
1466       setting the PCRE2_ALT_CIRCUMFLEX option. If there are no newlines in  a
1467       subject  string,  or  no  occurrences  of  ^ or $ in a pattern, setting
1468       PCRE2_MULTILINE has no effect.
1469
1470         PCRE2_NEVER_BACKSLASH_C
1471
1472       This option locks out the use of \C in the pattern that is  being  com‐
1473       piled.   This  escape  can  cause  unpredictable  behaviour in UTF-8 or
1474       UTF-16 modes, because it may leave the current matching  point  in  the
1475       middle of a multi-code-unit character. This option may be useful in ap‐
1476       plications that process patterns from external sources. Note that there
1477       is also a build-time option that permanently locks out the use of \C.
1478
1479         PCRE2_NEVER_UCP
1480
1481       This  option  locks  out the use of Unicode properties for handling \B,
1482       \b, \D, \d, \S, \s, \W, \w, and some of the POSIX character classes, as
1483       described  for  the  PCRE2_UCP option below. In particular, it prevents
1484       the creator of the pattern from enabling this facility by starting  the
1485       pattern  with  (*UCP).  This  option may be useful in applications that
1486       process patterns from external sources. The option combination PCRE_UCP
1487       and PCRE_NEVER_UCP causes an error.
1488
1489         PCRE2_NEVER_UTF
1490
1491       This  option  locks out interpretation of the pattern as UTF-8, UTF-16,
1492       or UTF-32, depending on which library is in use. In particular, it pre‐
1493       vents  the  creator of the pattern from switching to UTF interpretation
1494       by starting the pattern with (*UTF). This option may be useful  in  ap‐
1495       plications that process patterns from external sources. The combination
1496       of PCRE2_UTF and PCRE2_NEVER_UTF causes an error.
1497
1498         PCRE2_NO_AUTO_CAPTURE
1499
1500       If this option is set, it disables the use of numbered capturing paren‐
1501       theses  in the pattern. Any opening parenthesis that is not followed by
1502       ? behaves as if it were followed by ?: but named parentheses can  still
1503       be used for capturing (and they acquire numbers in the usual way). This
1504       is the same as Perl's /n option.  Note that, when this option  is  set,
1505       references  to  capture  groups (backreferences or recursion/subroutine
1506       calls) may only refer to named groups, though the reference can  be  by
1507       name or by number.
1508
1509         PCRE2_NO_AUTO_POSSESS
1510
1511       If this option is set, it disables "auto-possessification", which is an
1512       optimization that, for example, turns a+b into a++b in order  to  avoid
1513       backtracks  into  a+ that can never be successful. However, if callouts
1514       are in use, auto-possessification means that some  callouts  are  never
1515       taken. You can set this option if you want the matching functions to do
1516       a full unoptimized search and run all the callouts, but  it  is  mainly
1517       provided for testing purposes.
1518
1519         PCRE2_NO_DOTSTAR_ANCHOR
1520
1521       If this option is set, it disables an optimization that is applied when
1522       .* is the first significant item in a top-level branch  of  a  pattern,
1523       and  all  the  other branches also start with .* or with \A or \G or ^.
1524       The optimization is automatically disabled for .* if it  is  inside  an
1525       atomic group or a capture group that is the subject of a backreference,
1526       or if the pattern contains (*PRUNE) or (*SKIP). When  the  optimization
1527       is   not   disabled,  such  a  pattern  is  automatically  anchored  if
1528       PCRE2_DOTALL is set for all the .* items and PCRE2_MULTILINE is not set
1529       for  any  ^ items. Otherwise, the fact that any match must start either
1530       at the start of the subject or following a newline is remembered.  Like
1531       other optimizations, this can cause callouts to be skipped.
1532
1533         PCRE2_NO_START_OPTIMIZE
1534
1535       This  is  an  option whose main effect is at matching time. It does not
1536       change what pcre2_compile() generates, but it does affect the output of
1537       the JIT compiler.
1538
1539       There  are  a  number of optimizations that may occur at the start of a
1540       match, in order to speed up the process. For example, if  it  is  known
1541       that  an  unanchored  match must start with a specific code unit value,
1542       the matching code searches the subject for that value, and fails  imme‐
1543       diately  if it cannot find it, without actually running the main match‐
1544       ing function. This means that a special item such as (*COMMIT)  at  the
1545       start  of  a  pattern is not considered until after a suitable starting
1546       point for the match has been found.  Also,  when  callouts  or  (*MARK)
1547       items  are  in use, these "start-up" optimizations can cause them to be
1548       skipped if the pattern is never actually used. The  start-up  optimiza‐
1549       tions  are  in effect a pre-scan of the subject that takes place before
1550       the pattern is run.
1551
1552       The PCRE2_NO_START_OPTIMIZE option disables the start-up optimizations,
1553       possibly  causing  performance  to  suffer,  but ensuring that in cases
1554       where the result is "no match", the callouts do occur, and  that  items
1555       such as (*COMMIT) and (*MARK) are considered at every possible starting
1556       position in the subject string.
1557
1558       Setting PCRE2_NO_START_OPTIMIZE may change the outcome  of  a  matching
1559       operation.  Consider the pattern
1560
1561         (*COMMIT)ABC
1562
1563       When  this  is compiled, PCRE2 records the fact that a match must start
1564       with the character "A". Suppose the subject  string  is  "DEFABC".  The
1565       start-up  optimization  scans along the subject, finds "A" and runs the
1566       first match attempt from there. The (*COMMIT) item means that the  pat‐
1567       tern  must  match the current starting position, which in this case, it
1568       does. However, if the same match is  run  with  PCRE2_NO_START_OPTIMIZE
1569       set,  the  initial  scan  along the subject string does not happen. The
1570       first match attempt is run starting  from  "D"  and  when  this  fails,
1571       (*COMMIT)  prevents any further matches being tried, so the overall re‐
1572       sult is "no match".
1573
1574       As another start-up optimization makes use of a minimum  length  for  a
1575       matching subject, which is recorded when possible. Consider the pattern
1576
1577         (*MARK:1)B(*MARK:2)(X|Y)
1578
1579       The  minimum  length  for  a match is two characters. If the subject is
1580       "XXBB", the "starting character" optimization skips "XX", then tries to
1581       match  "BB", which is long enough. In the process, (*MARK:2) is encoun‐
1582       tered and remembered. When the match attempt fails,  the  next  "B"  is
1583       found,  but  there is only one character left, so there are no more at‐
1584       tempts, and "no match" is returned with the "last  mark  seen"  set  to
1585       "2".  If  NO_START_OPTIMIZE is set, however, matches are tried at every
1586       possible starting position, including at the end of the subject,  where
1587       (*MARK:1)  is encountered, but there is no "B", so the "last mark seen"
1588       that is returned is "1". In this case, the optimizations do not  affect
1589       the overall match result, which is still "no match", but they do affect
1590       the auxiliary information that is returned.
1591
1592         PCRE2_NO_UTF_CHECK
1593
1594       When PCRE2_UTF is set, the validity of the pattern as a UTF  string  is
1595       automatically  checked.  There  are  discussions  about the validity of
1596       UTF-8 strings, UTF-16 strings, and UTF-32 strings in  the  pcre2unicode
1597       document.  If an invalid UTF sequence is found, pcre2_compile() returns
1598       a negative error code.
1599
1600       If you know that your pattern is a valid UTF string, and  you  want  to
1601       skip   this   check   for   performance   reasons,   you  can  set  the
1602       PCRE2_NO_UTF_CHECK option. When it is set, the effect of passing an in‐
1603       valid  UTF  string as a pattern is undefined. It may cause your program
1604       to crash or loop.
1605
1606       Note  that  this  option  can  also  be  passed  to  pcre2_match()  and
1607       pcre2_dfa_match(),  to  suppress  UTF  validity checking of the subject
1608       string.
1609
1610       Note also that setting PCRE2_NO_UTF_CHECK at compile time does not dis‐
1611       able  the error that is given if an escape sequence for an invalid Uni‐
1612       code code point is encountered in the pattern. In particular,  the  so-
1613       called  "surrogate"  code points (0xd800 to 0xdfff) are invalid. If you
1614       want to allow escape  sequences  such  as  \x{d800}  you  can  set  the
1615       PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES  extra  option, as described in the
1616       section entitled "Extra compile options" below.  However, this is  pos‐
1617       sible only in UTF-8 and UTF-32 modes, because these values are not rep‐
1618       resentable in UTF-16.
1619
1620         PCRE2_UCP
1621
1622       This option has two effects. Firstly, it change the way PCRE2 processes
1623       \B,  \b,  \D,  \d,  \S,  \s,  \W,  \w,  and some of the POSIX character
1624       classes. By default, only  ASCII  characters  are  recognized,  but  if
1625       PCRE2_UCP is set, Unicode properties are used instead to classify char‐
1626       acters. More details are given in  the  section  on  generic  character
1627       types  in  the pcre2pattern page. If you set PCRE2_UCP, matching one of
1628       the items it affects takes much longer.
1629
1630       The second effect of PCRE2_UCP is to force the use of  Unicode  proper‐
1631       ties  for  upper/lower casing operations on characters with code points
1632       greater than 127, even when PCRE2_UTF is not set. This makes it  possi‐
1633       ble, for example, to process strings in the 16-bit UCS-2 code. This op‐
1634       tion is available only if PCRE2 has been compiled with Unicode  support
1635       (which is the default).
1636
1637         PCRE2_UNGREEDY
1638
1639       This  option  inverts  the "greediness" of the quantifiers so that they
1640       are not greedy by default, but become greedy if followed by "?". It  is
1641       not  compatible  with Perl. It can also be set by a (?U) option setting
1642       within the pattern.
1643
1644         PCRE2_USE_OFFSET_LIMIT
1645
1646       This option must be set for pcre2_compile() if pcre2_set_offset_limit()
1647       is  going  to be used to set a non-default offset limit in a match con‐
1648       text for matches that use this pattern. An error  is  generated  if  an
1649       offset  limit is set without this option. For more details, see the de‐
1650       scription of pcre2_set_offset_limit() in  the  section  that  describes
1651       match contexts. See also the PCRE2_FIRSTLINE option above.
1652
1653         PCRE2_UTF
1654
1655       This  option  causes  PCRE2  to regard both the pattern and the subject
1656       strings that are subsequently processed as strings  of  UTF  characters
1657       instead  of  single-code-unit  strings.  It  is available when PCRE2 is
1658       built to include Unicode support (which is  the  default).  If  Unicode
1659       support is not available, the use of this option provokes an error. De‐
1660       tails of how PCRE2_UTF changes the behaviour of PCRE2 are given in  the
1661       pcre2unicode  page.  In  particular,  note  that  it  changes  the  way
1662       PCRE2_CASELESS handles characters with code points greater than 127.
1663
1664   Extra compile options
1665
1666       The option bits that can be set in a compile  context  by  calling  the
1667       pcre2_set_compile_extra_options() function are as follows:
1668
1669         PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK
1670
1671       Since release 10.38 PCRE2 has forbidden the use of \K within lookaround
1672       assertions, following Perl's lead. This option is provided to re-enable
1673       the previous behaviour (act in positive lookarounds, ignore in negative
1674       ones) in case anybody is relying on it.
1675
1676         PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES
1677
1678       This option applies when compiling a pattern in UTF-8 or  UTF-32  mode.
1679       It  is  forbidden in UTF-16 mode, and ignored in non-UTF modes. Unicode
1680       "surrogate" code points in the range 0xd800 to 0xdfff are used in pairs
1681       in  UTF-16  to  encode  code points with values in the range 0x10000 to
1682       0x10ffff. The surrogates cannot therefore  be  represented  in  UTF-16.
1683       They can be represented in UTF-8 and UTF-32, but are defined as invalid
1684       code points, and cause errors if  encountered  in  a  UTF-8  or  UTF-32
1685       string that is being checked for validity by PCRE2.
1686
1687       These  values also cause errors if encountered in escape sequences such
1688       as \x{d912} within a pattern. However, it seems that some applications,
1689       when using PCRE2 to check for unwanted characters in UTF-8 strings, ex‐
1690       plicitly  test  for  the  surrogates  using   escape   sequences.   The
1691       PCRE2_NO_UTF_CHECK  option  does not disable the error that occurs, be‐
1692       cause it applies only to the testing of input strings for UTF validity.
1693
1694       If the extra option PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES is set,  surro‐
1695       gate  code  point values in UTF-8 and UTF-32 patterns no longer provoke
1696       errors and are incorporated in the compiled pattern. However, they  can
1697       only  match  subject characters if the matching function is called with
1698       PCRE2_NO_UTF_CHECK set.
1699
1700         PCRE2_EXTRA_ALT_BSUX
1701
1702       The original option PCRE2_ALT_BSUX causes PCRE2 to process \U, \u,  and
1703       \x  in  the way that ECMAscript (aka JavaScript) does. Additional func‐
1704       tionality was defined by ECMAscript 6; setting PCRE2_EXTRA_ALT_BSUX has
1705       the  effect  of PCRE2_ALT_BSUX, but in addition it recognizes \u{hhh..}
1706       as a hexadecimal character code, where hhh.. is any number of hexadeci‐
1707       mal digits.
1708
1709         PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL
1710
1711       This  is a dangerous option. Use with care. By default, an unrecognized
1712       escape such as \j or a malformed one such as \x{2z} causes  a  compile-
1713       time error when detected by pcre2_compile(). Perl is somewhat inconsis‐
1714       tent in handling such items: for example, \j is treated  as  a  literal
1715       "j",  and non-hexadecimal digits in \x{} are just ignored, though warn‐
1716       ings are given in both cases if Perl's warning switch is enabled.  How‐
1717       ever,  a  malformed  octal  number  after \o{ always causes an error in
1718       Perl.
1719
1720       If the PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL  extra  option  is  passed  to
1721       pcre2_compile(),  all  unrecognized  or  malformed escape sequences are
1722       treated as single-character escapes. For example, \j is a  literal  "j"
1723       and  \x{2z}  is treated as the literal string "x{2z}". Setting this op‐
1724       tion means that typos in patterns may go undetected and have unexpected
1725       results.  Also  note  that a sequence such as [\N{] is interpreted as a
1726       malformed attempt at [\N{...}] and so is treated as [N{]  whereas  [\N]
1727       gives an error because an unqualified \N is a valid escape sequence but
1728       is not supported in a character class. To reiterate: this is a  danger‐
1729       ous option. Use with great care.
1730
1731         PCRE2_EXTRA_ESCAPED_CR_IS_LF
1732
1733       There  are  some  legacy applications where the escape sequence \r in a
1734       pattern is expected to match a newline. If this option is set, \r in  a
1735       pattern  is  converted to \n so that it matches a LF (linefeed) instead
1736       of a CR (carriage return) character. The option does not affect a  lit‐
1737       eral  CR in the pattern, nor does it affect CR specified as an explicit
1738       code point such as \x{0D}.
1739
1740         PCRE2_EXTRA_MATCH_LINE
1741
1742       This option is provided for use by  the  -x  option  of  pcre2grep.  It
1743       causes  the  pattern  only to match complete lines. This is achieved by
1744       automatically inserting the code for "^(?:" at the start  of  the  com‐
1745       piled  pattern  and ")$" at the end. Thus, when PCRE2_MULTILINE is set,
1746       the matched line may be in the middle of the subject string.  This  op‐
1747       tion can be used with PCRE2_LITERAL.
1748
1749         PCRE2_EXTRA_MATCH_WORD
1750
1751       This  option  is  provided  for  use  by the -w option of pcre2grep. It
1752       causes the pattern only to match strings that have a word  boundary  at
1753       the  start and the end. This is achieved by automatically inserting the
1754       code for "\b(?:" at the start of the compiled pattern and ")\b" at  the
1755       end.  The option may be used with PCRE2_LITERAL. However, it is ignored
1756       if PCRE2_EXTRA_MATCH_LINE is also set.
1757

JUST-IN-TIME (JIT) COMPILATION

1759
1760       int pcre2_jit_compile(pcre2_code *code, uint32_t options);
1761
1762       int pcre2_jit_match(const pcre2_code *code, PCRE2_SPTR subject,
1763         PCRE2_SIZE length, PCRE2_SIZE startoffset,
1764         uint32_t options, pcre2_match_data *match_data,
1765         pcre2_match_context *mcontext);
1766
1767       void pcre2_jit_free_unused_memory(pcre2_general_context *gcontext);
1768
1769       pcre2_jit_stack *pcre2_jit_stack_create(PCRE2_SIZE startsize,
1770         PCRE2_SIZE maxsize, pcre2_general_context *gcontext);
1771
1772       void pcre2_jit_stack_assign(pcre2_match_context *mcontext,
1773         pcre2_jit_callback callback_function, void *callback_data);
1774
1775       void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack);
1776
1777       These functions provide support for  JIT  compilation,  which,  if  the
1778       just-in-time  compiler  is available, further processes a compiled pat‐
1779       tern into machine code that executes much faster than the pcre2_match()
1780       interpretive  matching function. Full details are given in the pcre2jit
1781       documentation.
1782
1783       JIT compilation is a heavyweight optimization. It can  take  some  time
1784       for  patterns  to  be analyzed, and for one-off matches and simple pat‐
1785       terns the benefit of faster execution might be offset by a much  slower
1786       compilation  time.  Most (but not all) patterns can be optimized by the
1787       JIT compiler.
1788

LOCALE SUPPORT

1790
1791       const uint8_t *pcre2_maketables(pcre2_general_context *gcontext);
1792
1793       void pcre2_maketables_free(pcre2_general_context *gcontext,
1794         const uint8_t *tables);
1795
1796       PCRE2 handles caseless matching, and determines whether characters  are
1797       letters,  digits, or whatever, by reference to a set of tables, indexed
1798       by character code point. However, this applies only to characters whose
1799       code  points  are  less than 256. By default, higher-valued code points
1800       never match escapes such as \w or \d.
1801
1802       When PCRE2 is built with Unicode support (the default), certain Unicode
1803       character  properties  can be tested with \p and \P, or, alternatively,
1804       the PCRE2_UCP option can be set when a pattern is compiled; this causes
1805       \w  and friends to use Unicode property support instead of the built-in
1806       tables.  PCRE2_UCP also causes upper/lower casing operations on charac‐
1807       ters with code points greater than 127 to use Unicode properties. These
1808       effects apply even when PCRE2_UTF is not set.
1809
1810       The use of locales with Unicode is discouraged.  If  you  are  handling
1811       characters  with  code  points  greater than 127, you should either use
1812       Unicode support, or use locales, but not try to mix the two.
1813
1814       PCRE2 contains a built-in set of character tables that are used by  de‐
1815       fault.   These  are sufficient for many applications. Normally, the in‐
1816       ternal tables recognize only ASCII characters. However, when  PCRE2  is
1817       built, it is possible to cause the internal tables to be rebuilt in the
1818       default "C" locale of the local system, which may cause them to be dif‐
1819       ferent.
1820
1821       The  built-in tables can be overridden by tables supplied by the appli‐
1822       cation that calls PCRE2. These may be created  in  a  different  locale
1823       from  the  default.  As more and more applications change to using Uni‐
1824       code, the need for this locale support is expected to die away.
1825
1826       External tables are built by calling the  pcre2_maketables()  function,
1827       in the relevant locale. The only argument to this function is a general
1828       context, which can be used to pass a custom memory  allocator.  If  the
1829       argument is NULL, the system malloc() is used. The result can be passed
1830       to pcre2_compile() as often as necessary, by creating a compile context
1831       and  calling  pcre2_set_character_tables()  to  set  the tables pointer
1832       therein.
1833
1834       For example, to build and use  tables  that  are  appropriate  for  the
1835       French  locale  (where accented characters with values greater than 127
1836       are treated as letters), the following code could be used:
1837
1838         setlocale(LC_CTYPE, "fr_FR");
1839         tables = pcre2_maketables(NULL);
1840         ccontext = pcre2_compile_context_create(NULL);
1841         pcre2_set_character_tables(ccontext, tables);
1842         re = pcre2_compile(..., ccontext);
1843
1844       The locale name "fr_FR" is used on Linux and other  Unix-like  systems;
1845       if you are using Windows, the name for the French locale is "french".
1846
1847       The pointer that is passed (via the compile context) to pcre2_compile()
1848       is saved with the compiled pattern, and the same tables are used by the
1849       matching  functions.  Thus,  for  any  single  pattern, compilation and
1850       matching both happen in the same locale, but different patterns can  be
1851       processed in different locales.
1852
1853       It  is the caller's responsibility to ensure that the memory containing
1854       the tables remains available while they are still in use. When they are
1855       no  longer  needed, you can discard them using pcre2_maketables_free(),
1856       which should pass as its first parameter the same global  context  that
1857       was used to create the tables.
1858
1859   Saving locale tables
1860
1861       The  tables  described above are just a sequence of binary bytes, which
1862       makes them independent of hardware characteristics such  as  endianness
1863       or  whether  the processor is 32-bit or 64-bit. A copy of the result of
1864       pcre2_maketables() can therefore be saved in a file  or  elsewhere  and
1865       re-used  later, even in a different program or on another computer. The
1866       size of the tables (number  of  bytes)  must  be  obtained  by  calling
1867       pcre2_config()   with  the  PCRE2_CONFIG_TABLES_LENGTH  option  because
1868       pcre2_maketables()  does  not  return  this  value.   Note   that   the
1869       pcre2_dftables program, which is part of the PCRE2 build system, can be
1870       used stand-alone to create a file that contains a set of binary tables.
1871       See the pcre2build documentation for details.
1872

INFORMATION ABOUT A COMPILED PATTERN

1874
1875       int pcre2_pattern_info(const pcre2 *code, uint32_t what, void *where);
1876
1877       The  pcre2_pattern_info()  function returns general information about a
1878       compiled pattern. For information about callouts, see the next section.
1879       The  first  argument  for pcre2_pattern_info() is a pointer to the com‐
1880       piled pattern. The second argument specifies which piece of information
1881       is  required,  and the third argument is a pointer to a variable to re‐
1882       ceive the data. If the third argument is NULL, the  first  argument  is
1883       ignored,  and  the  function  returns the size in bytes of the variable
1884       that is required for the information requested. Otherwise, the yield of
1885       the function is zero for success, or one of the following negative num‐
1886       bers:
1887
1888         PCRE2_ERROR_NULL           the argument code was NULL
1889         PCRE2_ERROR_BADMAGIC       the "magic number" was not found
1890         PCRE2_ERROR_BADOPTION      the value of what was invalid
1891         PCRE2_ERROR_UNSET          the requested field is not set
1892
1893       The "magic number" is placed at the start of each compiled pattern as a
1894       simple  check  against  passing  an arbitrary memory pointer. Here is a
1895       typical call of pcre2_pattern_info(), to obtain the length of the  com‐
1896       piled pattern:
1897
1898         int rc;
1899         size_t length;
1900         rc = pcre2_pattern_info(
1901           re,               /* result of pcre2_compile() */
1902           PCRE2_INFO_SIZE,  /* what is required */
1903           &length);         /* where to put the data */
1904
1905       The possible values for the second argument are defined in pcre2.h, and
1906       are as follows:
1907
1908         PCRE2_INFO_ALLOPTIONS
1909         PCRE2_INFO_ARGOPTIONS
1910         PCRE2_INFO_EXTRAOPTIONS
1911
1912       Return copies of the pattern's options. The third argument should point
1913       to  a  uint32_t variable. PCRE2_INFO_ARGOPTIONS returns exactly the op‐
1914       tions that were passed to  pcre2_compile(),  whereas  PCRE2_INFO_ALLOP‐
1915       TIONS  returns  the compile options as modified by any top-level (*XXX)
1916       option settings such as (*UTF) at the  start  of  the  pattern  itself.
1917       PCRE2_INFO_EXTRAOPTIONS  returns the extra options that were set in the
1918       compile context by calling the pcre2_set_compile_extra_options()  func‐
1919       tion.
1920
1921       For  example, if the pattern /(*UTF)abc/ is compiled with the PCRE2_EX‐
1922       TENDED option, the result for PCRE2_INFO_ALLOPTIONS  is  PCRE2_EXTENDED
1923       and  PCRE2_UTF.   Option settings such as (?i) that can change within a
1924       pattern do not affect the result of PCRE2_INFO_ALLOPTIONS, even if they
1925       appear  right  at the start of the pattern. (This was different in some
1926       earlier releases.)
1927
1928       A pattern compiled without PCRE2_ANCHORED is automatically anchored  by
1929       PCRE2 if the first significant item in every top-level branch is one of
1930       the following:
1931
1932         ^     unless PCRE2_MULTILINE is set
1933         \A    always
1934         \G    always
1935         .*    sometimes - see below
1936
1937       When .* is the first significant item, anchoring is possible only  when
1938       all the following are true:
1939
1940         .* is not in an atomic group
1941         .* is not in a capture group that is the subject
1942              of a backreference
1943         PCRE2_DOTALL is in force for .*
1944         Neither (*PRUNE) nor (*SKIP) appears in the pattern
1945         PCRE2_NO_DOTSTAR_ANCHOR is not set
1946
1947       For  patterns  that are auto-anchored, the PCRE2_ANCHORED bit is set in
1948       the options returned for PCRE2_INFO_ALLOPTIONS.
1949
1950         PCRE2_INFO_BACKREFMAX
1951
1952       Return the number of the highest  backreference  in  the  pattern.  The
1953       third  argument  should  point  to  a  uint32_t variable. Named capture
1954       groups acquire numbers as well as names, and these  count  towards  the
1955       highest  backreference.  Backreferences  such as \4 or \g{12} match the
1956       captured characters of the given group, but in addition, the check that
1957       a capture group is set in a conditional group such as (?(3)a|b) is also
1958       a backreference.  Zero is returned if there are no backreferences.
1959
1960         PCRE2_INFO_BSR
1961
1962       The output is a uint32_t integer whose value indicates  what  character
1963       sequences  the \R escape sequence matches. A value of PCRE2_BSR_UNICODE
1964       means that \R matches any Unicode line  ending  sequence;  a  value  of
1965       PCRE2_BSR_ANYCRLF means that \R matches only CR, LF, or CRLF.
1966
1967         PCRE2_INFO_CAPTURECOUNT
1968
1969       Return  the  highest  capture  group number in the pattern. In patterns
1970       where (?| is not used, this is also the total number of capture groups.
1971       The third argument should point to a uint32_t variable.
1972
1973         PCRE2_INFO_DEPTHLIMIT
1974
1975       If  the  pattern set a backtracking depth limit by including an item of
1976       the form (*LIMIT_DEPTH=nnnn) at the start, the value is  returned.  The
1977       third argument should point to a uint32_t integer. If no such value has
1978       been set, the call to pcre2_pattern_info() returns the error  PCRE2_ER‐
1979       ROR_UNSET. Note that this limit will only be used during matching if it
1980       is less than the limit set or defaulted by  the  caller  of  the  match
1981       function.
1982
1983         PCRE2_INFO_FIRSTBITMAP
1984
1985       In  the absence of a single first code unit for a non-anchored pattern,
1986       pcre2_compile() may construct a 256-bit table that defines a fixed  set
1987       of  values for the first code unit in any match. For example, a pattern
1988       that starts with [abc] results in a table with  three  bits  set.  When
1989       code  unit  values greater than 255 are supported, the flag bit for 255
1990       means "any code unit of value 255 or above". If such a table  was  con‐
1991       structed,  a pointer to it is returned. Otherwise NULL is returned. The
1992       third argument should point to a const uint8_t * variable.
1993
1994         PCRE2_INFO_FIRSTCODETYPE
1995
1996       Return information about the first code unit of any matched string, for
1997       a  non-anchored  pattern. The third argument should point to a uint32_t
1998       variable. If there is a fixed first value, for example, the letter  "c"
1999       from  a  pattern such as (cat|cow|coyote), 1 is returned, and the value
2000       can be retrieved using PCRE2_INFO_FIRSTCODEUNIT. If there is  no  fixed
2001       first  value,  but it is known that a match can occur only at the start
2002       of the subject or following a newline in the subject,  2  is  returned.
2003       Otherwise, and for anchored patterns, 0 is returned.
2004
2005         PCRE2_INFO_FIRSTCODEUNIT
2006
2007       Return  the  value  of  the first code unit of any matched string for a
2008       pattern where PCRE2_INFO_FIRSTCODETYPE returns 1; otherwise  return  0.
2009       The  third  argument  should point to a uint32_t variable. In the 8-bit
2010       library, the value is always less than 256. In the 16-bit  library  the
2011       value  can  be  up  to 0xffff. In the 32-bit library in UTF-32 mode the
2012       value can be up to 0x10ffff, and up to 0xffffffff when not using UTF-32
2013       mode.
2014
2015         PCRE2_INFO_FRAMESIZE
2016
2017       Return the size (in bytes) of the data frames that are used to remember
2018       backtracking positions when the pattern is processed  by  pcre2_match()
2019       without  the  use  of  JIT. The third argument should point to a size_t
2020       variable. The frame size depends on the number of capturing parentheses
2021       in the pattern. Each additional capture group adds two PCRE2_SIZE vari‐
2022       ables.
2023
2024         PCRE2_INFO_HASBACKSLASHC
2025
2026       Return 1 if the pattern contains any instances of \C, otherwise 0.  The
2027       third argument should point to a uint32_t variable.
2028
2029         PCRE2_INFO_HASCRORLF
2030
2031       Return  1  if  the  pattern  contains any explicit matches for CR or LF
2032       characters, otherwise 0. The third argument should point to a  uint32_t
2033       variable.  An explicit match is either a literal CR or LF character, or
2034       \r or \n or one of the  equivalent  hexadecimal  or  octal  escape  se‐
2035       quences.
2036
2037         PCRE2_INFO_HEAPLIMIT
2038
2039       If the pattern set a heap memory limit by including an item of the form
2040       (*LIMIT_HEAP=nnnn) at the start, the value is returned. The third argu‐
2041       ment should point to a uint32_t integer. If no such value has been set,
2042       the call to pcre2_pattern_info() returns the  error  PCRE2_ERROR_UNSET.
2043       Note  that  this  limit will only be used during matching if it is less
2044       than the limit set or defaulted by the caller of the match function.
2045
2046         PCRE2_INFO_JCHANGED
2047
2048       Return 1 if the (?J) or (?-J) option setting is used  in  the  pattern,
2049       otherwise  0.  The  third argument should point to a uint32_t variable.
2050       (?J) and (?-J) set and unset the local PCRE2_DUPNAMES  option,  respec‐
2051       tively.
2052
2053         PCRE2_INFO_JITSIZE
2054
2055       If  the  compiled  pattern was successfully processed by pcre2_jit_com‐
2056       pile(), return the size of the  JIT  compiled  code,  otherwise  return
2057       zero. The third argument should point to a size_t variable.
2058
2059         PCRE2_INFO_LASTCODETYPE
2060
2061       Returns  1 if there is a rightmost literal code unit that must exist in
2062       any matched string, other than at its start. The third argument  should
2063       point to a uint32_t variable. If there is no such value, 0 is returned.
2064       When 1 is returned, the code unit value itself can be  retrieved  using
2065       PCRE2_INFO_LASTCODEUNIT. For anchored patterns, a last literal value is
2066       recorded only if it follows something of variable length. For  example,
2067       for  the pattern /^a\d+z\d+/ the returned value is 1 (with "z" returned
2068       from PCRE2_INFO_LASTCODEUNIT), but for /^a\dz\d/ the returned value  is
2069       0.
2070
2071         PCRE2_INFO_LASTCODEUNIT
2072
2073       Return  the value of the rightmost literal code unit that must exist in
2074       any matched string, other than  at  its  start,  for  a  pattern  where
2075       PCRE2_INFO_LASTCODETYPE returns 1. Otherwise, return 0. The third argu‐
2076       ment should point to a uint32_t variable.
2077
2078         PCRE2_INFO_MATCHEMPTY
2079
2080       Return 1 if the pattern might match an empty string, otherwise  0.  The
2081       third argument should point to a uint32_t variable. When a pattern con‐
2082       tains recursive subroutine calls it is not always possible to determine
2083       whether or not it can match an empty string. PCRE2 takes a cautious ap‐
2084       proach and returns 1 in such cases.
2085
2086         PCRE2_INFO_MATCHLIMIT
2087
2088       If the pattern set a match limit by  including  an  item  of  the  form
2089       (*LIMIT_MATCH=nnnn)  at the start, the value is returned. The third ar‐
2090       gument should point to a uint32_t integer. If no such  value  has  been
2091       set, the call to pcre2_pattern_info() returns the error PCRE2_ERROR_UN‐
2092       SET. Note that this limit will only be used during matching  if  it  is
2093       less  than  the limit set or defaulted by the caller of the match func‐
2094       tion.
2095
2096         PCRE2_INFO_MAXLOOKBEHIND
2097
2098       A lookbehind assertion moves back a certain number of  characters  (not
2099       code  units)  when  it starts to process each of its branches. This re‐
2100       quest returns the largest of these backward moves. The  third  argument
2101       should point to a uint32_t integer. The simple assertions \b and \B re‐
2102       quire a one-character lookbehind and cause PCRE2_INFO_MAXLOOKBEHIND  to
2103       return  1  in  the absence of anything longer. \A also registers a one-
2104       character lookbehind, though it does not actually inspect the  previous
2105       character.
2106
2107       Note that this information is useful for multi-segment matching only if
2108       the pattern contains no nested lookbehinds. For  example,  the  pattern
2109       (?<=a(?<=ba)c)  returns  a maximum lookbehind of 2, but when it is pro‐
2110       cessed, the first lookbehind moves back by two characters, matches  one
2111       character,  then  the  nested lookbehind also moves back by two charac‐
2112       ters. This puts the matching point three characters earlier than it was
2113       at  the start.  PCRE2_INFO_MAXLOOKBEHIND is really only useful as a de‐
2114       bugging tool. See the pcre2partial documentation for  a  discussion  of
2115       multi-segment matching.
2116
2117         PCRE2_INFO_MINLENGTH
2118
2119       If  a  minimum  length  for  matching subject strings was computed, its
2120       value is returned. Otherwise the returned value is 0. This value is not
2121       computed  when PCRE2_NO_START_OPTIMIZE is set. The value is a number of
2122       characters, which in UTF mode may be different from the number of  code
2123       units.  The  third  argument  should  point to a uint32_t variable. The
2124       value is a lower bound to the length of any matching string. There  may
2125       not  be  any  strings  of that length that do actually match, but every
2126       string that does match is at least that long.
2127
2128         PCRE2_INFO_NAMECOUNT
2129         PCRE2_INFO_NAMEENTRYSIZE
2130         PCRE2_INFO_NAMETABLE
2131
2132       PCRE2 supports the use of named as well as numbered capturing parenthe‐
2133       ses.  The names are just an additional way of identifying the parenthe‐
2134       ses, which still acquire numbers. Several convenience functions such as
2135       pcre2_substring_get_byname()  are provided for extracting captured sub‐
2136       strings by name. It is also possible to extract the data  directly,  by
2137       first  converting  the  name to a number in order to access the correct
2138       pointers in the output vector (described with pcre2_match() below).  To
2139       do the conversion, you need to use the name-to-number map, which is de‐
2140       scribed by these three values.
2141
2142       The map consists of a number of  fixed-size  entries.  PCRE2_INFO_NAME‐
2143       COUNT  gives  the number of entries, and PCRE2_INFO_NAMEENTRYSIZE gives
2144       the size of each entry in code units; both of these return  a  uint32_t
2145       value. The entry size depends on the length of the longest name.
2146
2147       PCRE2_INFO_NAMETABLE returns a pointer to the first entry of the table.
2148       This is a PCRE2_SPTR pointer to a block of code units. In the 8-bit li‐
2149       brary,  the first two bytes of each entry are the number of the captur‐
2150       ing parenthesis, most significant byte first. In  the  16-bit  library,
2151       the  pointer  points  to 16-bit code units, the first of which contains
2152       the parenthesis number. In the 32-bit library, the  pointer  points  to
2153       32-bit  code units, the first of which contains the parenthesis number.
2154       The rest of the entry is the corresponding name, zero terminated.
2155
2156       The names are in alphabetical order. If (?| is used to create  multiple
2157       capture groups with the same number, as described in the section on du‐
2158       plicate group numbers in the pcre2pattern page, the groups may be given
2159       the  same  name,  but  there  is only one entry in the table. Different
2160       names for groups of the same number are not permitted.
2161
2162       Duplicate names for capture groups with different numbers  are  permit‐
2163       ted, but only if PCRE2_DUPNAMES is set. They appear in the table in the
2164       order in which they were found in the pattern. In the  absence  of  (?|
2165       this  is  the  order of increasing number; when (?| is used this is not
2166       necessarily the case because later capture groups may have  lower  num‐
2167       bers.
2168
2169       As  a  simple  example of the name/number table, consider the following
2170       pattern after compilation by the 8-bit library  (assume  PCRE2_EXTENDED
2171       is set, so white space - including newlines - is ignored):
2172
2173         (?<date> (?<year>(\d\d)?\d\d) -
2174         (?<month>\d\d) - (?<day>\d\d) )
2175
2176       There are four named capture groups, so the table has four entries, and
2177       each entry in the table is eight bytes long. The table is  as  follows,
2178       with non-printing bytes shows in hexadecimal, and undefined bytes shown
2179       as ??:
2180
2181         00 01 d  a  t  e  00 ??
2182         00 05 d  a  y  00 ?? ??
2183         00 04 m  o  n  t  h  00
2184         00 02 y  e  a  r  00 ??
2185
2186       When writing code to extract data from named capture groups  using  the
2187       name-to-number  map,  remember that the length of the entries is likely
2188       to be different for each compiled pattern.
2189
2190         PCRE2_INFO_NEWLINE
2191
2192       The output is one of the following uint32_t values:
2193
2194         PCRE2_NEWLINE_CR       Carriage return (CR)
2195         PCRE2_NEWLINE_LF       Linefeed (LF)
2196         PCRE2_NEWLINE_CRLF     Carriage return, linefeed (CRLF)
2197         PCRE2_NEWLINE_ANY      Any Unicode line ending
2198         PCRE2_NEWLINE_ANYCRLF  Any of CR, LF, or CRLF
2199         PCRE2_NEWLINE_NUL      The NUL character (binary zero)
2200
2201       This identifies the character sequence that will be recognized as mean‐
2202       ing "newline" while matching.
2203
2204         PCRE2_INFO_SIZE
2205
2206       Return  the  size  of  the compiled pattern in bytes (for all three li‐
2207       braries). The third argument should point to a  size_t  variable.  This
2208       value  includes  the  size  of the general data block that precedes the
2209       code units of the compiled pattern itself. The value that is used  when
2210       pcre2_compile()  is  getting memory in which to place the compiled pat‐
2211       tern may be slightly larger than the value returned by this option, be‐
2212       cause  there  are  cases where the code that calculates the size has to
2213       over-estimate. Processing a pattern with the JIT compiler does not  al‐
2214       ter the value returned by this option.
2215

INFORMATION ABOUT A PATTERN'S CALLOUTS

2217
2218       int pcre2_callout_enumerate(const pcre2_code *code,
2219         int (*callback)(pcre2_callout_enumerate_block *, void *),
2220         void *user_data);
2221
2222       A script language that supports the use of string arguments in callouts
2223       might like to scan all the callouts in a  pattern  before  running  the
2224       match. This can be done by calling pcre2_callout_enumerate(). The first
2225       argument is a pointer to a compiled pattern, the  second  points  to  a
2226       callback  function,  and the third is arbitrary user data. The callback
2227       function is called for every callout in the pattern  in  the  order  in
2228       which they appear. Its first argument is a pointer to a callout enumer‐
2229       ation block, and its second argument is the user_data  value  that  was
2230       passed  to  pcre2_callout_enumerate(). The contents of the callout enu‐
2231       meration block are described in the pcre2callout  documentation,  which
2232       also gives further details about callouts.
2233

SERIALIZATION AND PRECOMPILING

2235
2236       It  is  possible  to  save  compiled patterns on disc or elsewhere, and
2237       reload them later, subject to a number of  restrictions.  The  host  on
2238       which  the  patterns  are  reloaded must be running the same version of
2239       PCRE2, with the same code unit width, and must also have the same endi‐
2240       anness,  pointer  width,  and PCRE2_SIZE type. Before compiled patterns
2241       can be saved, they must be converted to a "serialized" form,  which  in
2242       the  case of PCRE2 is really just a bytecode dump.  The functions whose
2243       names begin with pcre2_serialize_ are used for converting to  and  from
2244       the  serialized form. They are described in the pcre2serialize documen‐
2245       tation. Note that PCRE2 serialization does not  convert  compiled  pat‐
2246       terns to an abstract format like Java or .NET serialization.
2247

THE MATCH DATA BLOCK

2249
2250       pcre2_match_data *pcre2_match_data_create(uint32_t ovecsize,
2251         pcre2_general_context *gcontext);
2252
2253       pcre2_match_data *pcre2_match_data_create_from_pattern(
2254         const pcre2_code *code, pcre2_general_context *gcontext);
2255
2256       void pcre2_match_data_free(pcre2_match_data *match_data);
2257
2258       Information  about  a  successful  or unsuccessful match is placed in a
2259       match data block, which is an opaque  structure  that  is  accessed  by
2260       function  calls.  In particular, the match data block contains a vector
2261       of offsets into the subject string that define the matched parts of the
2262       subject. This is known as the ovector.
2263
2264       Before  calling  pcre2_match(), pcre2_dfa_match(), or pcre2_jit_match()
2265       you must create a match data block by calling one of the creation func‐
2266       tions  above.  For pcre2_match_data_create(), the first argument is the
2267       number of pairs of offsets in the ovector.
2268
2269       When using pcre2_match(), one pair of offsets is required  to  identify
2270       the  string that matched the whole pattern, with an additional pair for
2271       each captured substring. For example, a value of 4 creates enough space
2272       to  record  the matched portion of the subject plus three captured sub‐
2273       strings.
2274
2275       When using pcre2_dfa_match() there may be multiple  matched  substrings
2276       of  different  lengths  at  the  same point in the subject. The ovector
2277       should be made large enough to hold as many as are expected.
2278
2279       A minimum of at least 1 pair is imposed  by  pcre2_match_data_create(),
2280       so  it  is  always possible to return the overall matched string in the
2281       case  of  pcre2_match()  or  the  longest  match   in   the   case   of
2282       pcre2_dfa_match().  The  maximum  number  of pairs is 65535; if the the
2283       first argument of pcre2_match_data_create() is greater than this, 65535
2284       is used.
2285
2286       The second argument of pcre2_match_data_create() is a pointer to a gen‐
2287       eral context, which can specify custom memory management for  obtaining
2288       the memory for the match data block. If you are not using custom memory
2289       management, pass NULL, which causes malloc() to be used.
2290
2291       For pcre2_match_data_create_from_pattern(), the  first  argument  is  a
2292       pointer to a compiled pattern. The ovector is created to be exactly the
2293       right size to hold all the substrings  a  pattern  might  capture  when
2294       matched using pcre2_match(). You should not use this call when matching
2295       with pcre2_dfa_match(). The second argument is again  a  pointer  to  a
2296       general  context, but in this case if NULL is passed, the memory is ob‐
2297       tained using the same allocator that was used for the compiled  pattern
2298       (custom or default).
2299
2300       A  match  data block can be used many times, with the same or different
2301       compiled patterns. You can extract information from a match data  block
2302       after  a  match  operation  has  finished, using functions that are de‐
2303       scribed in the sections on matched strings and other match data below.
2304
2305       When a call of pcre2_match() fails, valid  data  is  available  in  the
2306       match  block  only  when  the  error  is PCRE2_ERROR_NOMATCH, PCRE2_ER‐
2307       ROR_PARTIAL, or one of the error codes for an invalid UTF  string.  Ex‐
2308       actly what is available depends on the error, and is detailed below.
2309
2310       When  one of the matching functions is called, pointers to the compiled
2311       pattern and the subject string are set in the match data block so  that
2312       they  can  be referenced by the extraction functions after a successful
2313       match. After running a match, you must not free a compiled pattern or a
2314       subject  string until after all operations on the match data block (for
2315       that match) have taken place,  unless,  in  the  case  of  the  subject
2316       string,  you  have used the PCRE2_COPY_MATCHED_SUBJECT option, which is
2317       described in the section entitled "Option bits for  pcre2_match()"  be‐
2318       low.
2319
2320       When  a match data block itself is no longer needed, it should be freed
2321       by calling pcre2_match_data_free(). If this function is called  with  a
2322       NULL argument, it returns immediately, without doing anything.
2323

MATCHING A PATTERN: THE TRADITIONAL FUNCTION

2325
2326       int pcre2_match(const pcre2_code *code, PCRE2_SPTR subject,
2327         PCRE2_SIZE length, PCRE2_SIZE startoffset,
2328         uint32_t options, pcre2_match_data *match_data,
2329         pcre2_match_context *mcontext);
2330
2331       The  function pcre2_match() is called to match a subject string against
2332       a compiled pattern, which is passed in the code argument. You can  call
2333       pcre2_match() with the same code argument as many times as you like, in
2334       order to find multiple matches in the subject string or to  match  dif‐
2335       ferent subject strings with the same pattern.
2336
2337       This  function is the main matching facility of the library, and it op‐
2338       erates in a Perl-like manner. For specialist use there is also  an  al‐
2339       ternative  matching  function,  which is described below in the section
2340       about the pcre2_dfa_match() function.
2341
2342       Here is an example of a simple call to pcre2_match():
2343
2344         pcre2_match_data *md = pcre2_match_data_create(4, NULL);
2345         int rc = pcre2_match(
2346           re,             /* result of pcre2_compile() */
2347           "some string",  /* the subject string */
2348           11,             /* the length of the subject string */
2349           0,              /* start at offset 0 in the subject */
2350           0,              /* default options */
2351           md,             /* the match data block */
2352           NULL);          /* a match context; NULL means use defaults */
2353
2354       If the subject string is zero-terminated, the length can  be  given  as
2355       PCRE2_ZERO_TERMINATED. A match context must be provided if certain less
2356       common matching parameters are to be changed. For details, see the sec‐
2357       tion on the match context above.
2358
2359   The string to be matched by pcre2_match()
2360
2361       The  subject string is passed to pcre2_match() as a pointer in subject,
2362       a length in length, and a starting offset in  startoffset.  The  length
2363       and  offset  are  in  code units, not characters.  That is, they are in
2364       bytes for the 8-bit library, 16-bit code units for the 16-bit  library,
2365       and  32-bit  code units for the 32-bit library, whether or not UTF pro‐
2366       cessing is enabled. As a special case, if subject is NULL and length is
2367       zero,  the  subject is assumed to be an empty string. If length is non-
2368       zero, an error occurs if subject is NULL.
2369
2370       If startoffset is greater than the length of the subject, pcre2_match()
2371       returns  PCRE2_ERROR_BADOFFSET.  When  the starting offset is zero, the
2372       search for a match starts at the beginning of the subject, and this  is
2373       by far the most common case. In UTF-8 or UTF-16 mode, the starting off‐
2374       set must point to the start of a character, or to the end of  the  sub‐
2375       ject  (in  UTF-32 mode, one code unit equals one character, so all off‐
2376       sets are valid). Like the pattern string, the subject may  contain  bi‐
2377       nary zeros.
2378
2379       A  non-zero  starting offset is useful when searching for another match
2380       in the same subject by calling pcre2_match()  again  after  a  previous
2381       success.   Setting  startoffset  differs  from passing over a shortened
2382       string and setting PCRE2_NOTBOL in the case of a  pattern  that  begins
2383       with any kind of lookbehind. For example, consider the pattern
2384
2385         \Biss\B
2386
2387       which  finds  occurrences  of "iss" in the middle of words. (\B matches
2388       only if the current position in the subject is not  a  word  boundary.)
2389       When   applied   to   the   string  "Mississippi"  the  first  call  to
2390       pcre2_match() finds the first occurrence. If  pcre2_match()  is  called
2391       again with just the remainder of the subject, namely "issippi", it does
2392       not match, because \B is always false at  the  start  of  the  subject,
2393       which  is  deemed  to  be a word boundary. However, if pcre2_match() is
2394       passed the entire string again, but with startoffset set to 4, it finds
2395       the  second  occurrence  of "iss" because it is able to look behind the
2396       starting point to discover that it is preceded by a letter.
2397
2398       Finding all the matches in a subject is tricky  when  the  pattern  can
2399       match an empty string. It is possible to emulate Perl's /g behaviour by
2400       first  trying  the  match  again  at  the   same   offset,   with   the
2401       PCRE2_NOTEMPTY_ATSTART  and  PCRE2_ANCHORED  options,  and then if that
2402       fails, advancing the starting  offset  and  trying  an  ordinary  match
2403       again.  There  is  some  code  that  demonstrates how to do this in the
2404       pcre2demo sample program. In the most general case, you have  to  check
2405       to  see  if the newline convention recognizes CRLF as a newline, and if
2406       so, and the current character is CR followed by LF, advance the  start‐
2407       ing offset by two characters instead of one.
2408
2409       If a non-zero starting offset is passed when the pattern is anchored, a
2410       single attempt to match at the given offset is made. This can only suc‐
2411       ceed  if  the  pattern does not require the match to be at the start of
2412       the subject. In other words, the anchoring must be the result  of  set‐
2413       ting  the PCRE2_ANCHORED option or the use of .* with PCRE2_DOTALL, not
2414       by starting the pattern with ^ or \A.
2415
2416   Option bits for pcre2_match()
2417
2418       The unused bits of the options argument for pcre2_match() must be zero.
2419       The    only    bits    that    may    be    set   are   PCRE2_ANCHORED,
2420       PCRE2_COPY_MATCHED_SUBJECT, PCRE2_ENDANCHORED, PCRE2_NOTBOL,  PCRE2_NO‐
2421       TEOL,     PCRE2_NOTEMPTY,     PCRE2_NOTEMPTY_ATSTART,     PCRE2_NO_JIT,
2422       PCRE2_NO_UTF_CHECK, PCRE2_PARTIAL_HARD, and  PCRE2_PARTIAL_SOFT.  Their
2423       action is described below.
2424
2425       Setting  PCRE2_ANCHORED  or PCRE2_ENDANCHORED at match time is not sup‐
2426       ported by the just-in-time (JIT) compiler. If it is set,  JIT  matching
2427       is  disabled  and  the interpretive code in pcre2_match() is run. Apart
2428       from PCRE2_NO_JIT (obviously), the remaining options are supported  for
2429       JIT matching.
2430
2431         PCRE2_ANCHORED
2432
2433       The PCRE2_ANCHORED option limits pcre2_match() to matching at the first
2434       matching position. If a pattern was compiled  with  PCRE2_ANCHORED,  or
2435       turned  out to be anchored by virtue of its contents, it cannot be made
2436       unachored at matching time. Note that setting the option at match  time
2437       disables JIT matching.
2438
2439         PCRE2_COPY_MATCHED_SUBJECT
2440
2441       By  default,  a  pointer to the subject is remembered in the match data
2442       block so that, after a successful match, it can be  referenced  by  the
2443       substring  extraction  functions.  This means that the subject's memory
2444       must not be freed until all such operations are complete. For some  ap‐
2445       plications  where the lifetime of the subject string is not guaranteed,
2446       it may be necessary to make a copy of the subject  string,  but  it  is
2447       wasteful  to do this unless the match is successful. After a successful
2448       match, if PCRE2_COPY_MATCHED_SUBJECT is set, the subject is copied  and
2449       the  new  pointer  is remembered in the match data block instead of the
2450       original subject pointer. The memory allocator that was  used  for  the
2451       match  block  itself  is  used.  The  copy  is automatically freed when
2452       pcre2_match_data_free() is called to free the match data block.  It  is
2453       also automatically freed if the match data block is re-used for another
2454       match operation.
2455
2456         PCRE2_ENDANCHORED
2457
2458       If the PCRE2_ENDANCHORED option is set, any string  that  pcre2_match()
2459       matches  must be right at the end of the subject string. Note that set‐
2460       ting the option at match time disables JIT matching.
2461
2462         PCRE2_NOTBOL
2463
2464       This option specifies that first character of the subject string is not
2465       the  beginning  of  a  line, so the circumflex metacharacter should not
2466       match before it. Setting this without  having  set  PCRE2_MULTILINE  at
2467       compile time causes circumflex never to match. This option affects only
2468       the behaviour of the circumflex metacharacter. It does not affect \A.
2469
2470         PCRE2_NOTEOL
2471
2472       This option specifies that the end of the subject string is not the end
2473       of  a line, so the dollar metacharacter should not match it nor (except
2474       in multiline mode) a newline immediately before it. Setting this  with‐
2475       out  having  set PCRE2_MULTILINE at compile time causes dollar never to
2476       match. This option affects only the behaviour of the dollar metacharac‐
2477       ter. It does not affect \Z or \z.
2478
2479         PCRE2_NOTEMPTY
2480
2481       An empty string is not considered to be a valid match if this option is
2482       set. If there are alternatives in the pattern, they are tried.  If  all
2483       the  alternatives  match  the empty string, the entire match fails. For
2484       example, if the pattern
2485
2486         a?b?
2487
2488       is applied to a string not beginning with "a" or  "b",  it  matches  an
2489       empty string at the start of the subject. With PCRE2_NOTEMPTY set, this
2490       match is not valid, so pcre2_match() searches further into  the  string
2491       for occurrences of "a" or "b".
2492
2493         PCRE2_NOTEMPTY_ATSTART
2494
2495       This  is  like PCRE2_NOTEMPTY, except that it locks out an empty string
2496       match only at the first matching position, that is, at the start of the
2497       subject  plus  the  starting offset. An empty string match later in the
2498       subject is permitted.  If the pattern is anchored, such a match can oc‐
2499       cur only if the pattern contains \K.
2500
2501         PCRE2_NO_JIT
2502
2503       By   default,   if   a  pattern  has  been  successfully  processed  by
2504       pcre2_jit_compile(), JIT is automatically used  when  pcre2_match()  is
2505       called  with  options  that JIT supports. Setting PCRE2_NO_JIT disables
2506       the use of JIT; it forces matching to be done by the interpreter.
2507
2508         PCRE2_NO_UTF_CHECK
2509
2510       When PCRE2_UTF is set at compile time, the validity of the subject as a
2511       UTF   string   is   checked  unless  PCRE2_NO_UTF_CHECK  is  passed  to
2512       pcre2_match() or PCRE2_MATCH_INVALID_UTF was passed to pcre2_compile().
2513       The latter special case is discussed in detail in the pcre2unicode doc‐
2514       umentation.
2515
2516       In the default case, if a non-zero starting offset is given, the  check
2517       is  applied  only  to  that part of the subject that could be inspected
2518       during matching, and there is a check that the starting  offset  points
2519       to  the first code unit of a character or to the end of the subject. If
2520       there are no lookbehind assertions in the pattern, the check starts  at
2521       the starting offset.  Otherwise, it starts at the length of the longest
2522       lookbehind before the starting offset, or at the start of  the  subject
2523       if  there are not that many characters before the starting offset. Note
2524       that the sequences \b and \B are one-character lookbehinds.
2525
2526       The check is carried out before any other processing takes place, and a
2527       negative  error  code is returned if the check fails. There are several
2528       UTF error codes for each code unit width,  corresponding  to  different
2529       problems  with  the code unit sequence. There are discussions about the
2530       validity of UTF-8 strings, UTF-16 strings, and UTF-32  strings  in  the
2531       pcre2unicode documentation.
2532
2533       If you know that your subject is valid, and you want to skip this check
2534       for performance reasons, you can set the PCRE2_NO_UTF_CHECK option when
2535       calling  pcre2_match().  You  might  want to do this for the second and
2536       subsequent calls to pcre2_match() if you are making repeated  calls  to
2537       find multiple matches in the same subject string.
2538
2539       Warning:  Unless  PCRE2_MATCH_INVALID_UTF was set at compile time, when
2540       PCRE2_NO_UTF_CHECK is set at match time the effect of  passing  an  in‐
2541       valid string as a subject, or an invalid value of startoffset, is unde‐
2542       fined.  Your program may crash or loop indefinitely or give  wrong  re‐
2543       sults.
2544
2545         PCRE2_PARTIAL_HARD
2546         PCRE2_PARTIAL_SOFT
2547
2548       These options turn on the partial matching feature. A partial match oc‐
2549       curs if the end of the subject  string  is  reached  successfully,  but
2550       there are not enough subject characters to complete the match. In addi‐
2551       tion, either at least one character must have  been  inspected  or  the
2552       pattern  must  contain  a  lookbehind,  or the pattern must be one that
2553       could match an empty string.
2554
2555       If this situation arises when PCRE2_PARTIAL_SOFT  (but  not  PCRE2_PAR‐
2556       TIAL_HARD) is set, matching continues by testing any remaining alterna‐
2557       tives. Only if no complete match can be  found  is  PCRE2_ERROR_PARTIAL
2558       returned  instead  of  PCRE2_ERROR_NOMATCH.  In other words, PCRE2_PAR‐
2559       TIAL_SOFT specifies that the caller is prepared  to  handle  a  partial
2560       match, but only if no complete match can be found.
2561
2562       If  PCRE2_PARTIAL_HARD is set, it overrides PCRE2_PARTIAL_SOFT. In this
2563       case, if a partial match is found,  pcre2_match()  immediately  returns
2564       PCRE2_ERROR_PARTIAL,  without  considering  any  other alternatives. In
2565       other words, when PCRE2_PARTIAL_HARD is set, a partial match is consid‐
2566       ered to be more important that an alternative complete match.
2567
2568       There is a more detailed discussion of partial and multi-segment match‐
2569       ing, with examples, in the pcre2partial documentation.
2570

NEWLINE HANDLING WHEN MATCHING

2572
2573       When PCRE2 is built, a default newline convention is set; this is  usu‐
2574       ally  the standard convention for the operating system. The default can
2575       be overridden in a compile context by calling  pcre2_set_newline().  It
2576       can  also be overridden by starting a pattern string with, for example,
2577       (*CRLF), as described in the section  on  newline  conventions  in  the
2578       pcre2pattern  page. During matching, the newline choice affects the be‐
2579       haviour of the dot, circumflex, and dollar metacharacters. It may  also
2580       alter  the  way  the  match starting position is advanced after a match
2581       failure for an unanchored pattern.
2582
2583       When PCRE2_NEWLINE_CRLF, PCRE2_NEWLINE_ANYCRLF, or PCRE2_NEWLINE_ANY is
2584       set  as  the  newline convention, and a match attempt for an unanchored
2585       pattern fails when the current starting position is at a CRLF sequence,
2586       and  the  pattern contains no explicit matches for CR or LF characters,
2587       the match position is advanced by two characters  instead  of  one,  in
2588       other words, to after the CRLF.
2589
2590       The above rule is a compromise that makes the most common cases work as
2591       expected. For example, if the pattern is .+A (and the PCRE2_DOTALL  op‐
2592       tion  is  not set), it does not match the string "\r\nA" because, after
2593       failing at the start, it skips both the CR and the LF before  retrying.
2594       However,  the  pattern  [\r\n]A does match that string, because it con‐
2595       tains an explicit CR or LF reference, and so advances only by one char‐
2596       acter after the first failure.
2597
2598       An explicit match for CR of LF is either a literal appearance of one of
2599       those characters in the pattern, or one of the \r or \n  or  equivalent
2600       octal or hexadecimal escape sequences. Implicit matches such as [^X] do
2601       not count, nor does \s, even though it includes CR and LF in the  char‐
2602       acters that it matches.
2603
2604       Notwithstanding  the above, anomalous effects may still occur when CRLF
2605       is a valid newline sequence and explicit \r or \n escapes appear in the
2606       pattern.
2607

HOW PCRE2_MATCH() RETURNS A STRING AND CAPTURED SUBSTRINGS

2609
2610       uint32_t pcre2_get_ovector_count(pcre2_match_data *match_data);
2611
2612       PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *match_data);
2613
2614       In  general, a pattern matches a certain portion of the subject, and in
2615       addition, further substrings from the subject  may  be  picked  out  by
2616       parenthesized  parts  of  the  pattern.  Following the usage in Jeffrey
2617       Friedl's book, this is called "capturing"  in  what  follows,  and  the
2618       phrase  "capture  group" (Perl terminology) is used for a fragment of a
2619       pattern that picks out a substring. PCRE2 supports several other  kinds
2620       of parenthesized group that do not cause substrings to be captured. The
2621       pcre2_pattern_info() function can be used to find out how many  capture
2622       groups there are in a compiled pattern.
2623
2624       You  can  use  auxiliary functions for accessing captured substrings by
2625       number or by name, as described in sections below.
2626
2627       Alternatively, you can make direct use of the vector of PCRE2_SIZE val‐
2628       ues,  called  the  ovector,  which  contains  the  offsets  of captured
2629       strings.  It  is  part  of  the  match  data   block.    The   function
2630       pcre2_get_ovector_pointer()  returns  the  address  of the ovector, and
2631       pcre2_get_ovector_count() returns the number of pairs of values it con‐
2632       tains.
2633
2634       Within the ovector, the first in each pair of values is set to the off‐
2635       set of the first code unit of a substring, and the second is set to the
2636       offset  of the first code unit after the end of a substring. These val‐
2637       ues are always code unit offsets, not character offsets. That is,  they
2638       are byte offsets in the 8-bit library, 16-bit offsets in the 16-bit li‐
2639       brary, and 32-bit offsets in the 32-bit library.
2640
2641       After a partial match  (error  return  PCRE2_ERROR_PARTIAL),  only  the
2642       first  pair  of  offsets  (that is, ovector[0] and ovector[1]) are set.
2643       They identify the part of the subject that was partially  matched.  See
2644       the pcre2partial documentation for details of partial matching.
2645
2646       After  a  fully  successful match, the first pair of offsets identifies
2647       the portion of the subject string that was matched by the  entire  pat‐
2648       tern.  The  next  pair is used for the first captured substring, and so
2649       on. The value returned by pcre2_match() is one more  than  the  highest
2650       numbered  pair  that  has been set. For example, if two substrings have
2651       been captured, the returned value is 3. If there are no  captured  sub‐
2652       strings, the return value from a successful match is 1, indicating that
2653       just the first pair of offsets has been set.
2654
2655       If a pattern uses the \K escape sequence within a  positive  assertion,
2656       the reported start of a successful match can be greater than the end of
2657       the match.  For example, if the pattern  (?=ab\K)  is  matched  against
2658       "ab", the start and end offset values for the match are 2 and 0.
2659
2660       If  a  capture group is matched repeatedly within a single match opera‐
2661       tion, it is the last portion of the subject that it matched that is re‐
2662       turned.
2663
2664       If the ovector is too small to hold all the captured substring offsets,
2665       as much as possible is filled in, and the function returns a  value  of
2666       zero.  If captured substrings are not of interest, pcre2_match() may be
2667       called with a match data block whose ovector is of minimum length (that
2668       is, one pair).
2669
2670       It  is  possible for capture group number n+1 to match some part of the
2671       subject when group n has not been used at  all.  For  example,  if  the
2672       string "abc" is matched against the pattern (a|(z))(bc) the return from
2673       the function is 4, and groups 1 and 3 are matched, but 2 is  not.  When
2674       this  happens,  both values in the offset pairs corresponding to unused
2675       groups are set to PCRE2_UNSET.
2676
2677       Offset values that correspond to unused groups at the end  of  the  ex‐
2678       pression  are also set to PCRE2_UNSET. For example, if the string "abc"
2679       is matched against the pattern (abc)(x(yz)?)? groups 2 and  3  are  not
2680       matched.  The  return  from the function is 2, because the highest used
2681       capture group number is 1. The offsets for for  the  second  and  third
2682       capture  groupss  (assuming  the vector is large enough, of course) are
2683       set to PCRE2_UNSET.
2684
2685       Elements in the ovector that do not correspond to capturing parentheses
2686       in the pattern are never changed. That is, if a pattern contains n cap‐
2687       turing parentheses, no more than ovector[0] to ovector[2n+1] are set by
2688       pcre2_match().  The  other  elements retain whatever values they previ‐
2689       ously had. After a failed match attempt, the contents  of  the  ovector
2690       are unchanged.
2691

OTHER INFORMATION ABOUT A MATCH

2693
2694       PCRE2_SPTR pcre2_get_mark(pcre2_match_data *match_data);
2695
2696       PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data);
2697
2698       As  well as the offsets in the ovector, other information about a match
2699       is retained in the match data block and can be retrieved by  the  above
2700       functions  in  appropriate  circumstances.  If they are called at other
2701       times, the result is undefined.
2702
2703       After a successful match, a partial match (PCRE2_ERROR_PARTIAL),  or  a
2704       failure  to  match (PCRE2_ERROR_NOMATCH), a mark name may be available.
2705       The function pcre2_get_mark() can be called to access this name,  which
2706       can  be  specified  in  the  pattern by any of the backtracking control
2707       verbs, not just (*MARK). The same function applies to all the verbs. It
2708       returns a pointer to the zero-terminated name, which is within the com‐
2709       piled pattern. If no name is available, NULL is returned. The length of
2710       the  name  (excluding  the terminating zero) is stored in the code unit
2711       that precedes the name. You should use this length instead  of  relying
2712       on the terminating zero if the name might contain a binary zero.
2713
2714       After  a  successful  match, the name that is returned is the last mark
2715       name encountered on the matching path through the pattern. Instances of
2716       backtracking  verbs  without  names do not count. Thus, for example, if
2717       the matching path contains (*MARK:A)(*PRUNE), the name "A" is returned.
2718       After a "no match" or a partial match, the last encountered name is re‐
2719       turned. For example, consider this pattern:
2720
2721         ^(*MARK:A)((*MARK:B)a|b)c
2722
2723       When it matches "bc", the returned name is A. The B mark is  "seen"  in
2724       the  first  branch of the group, but it is not on the matching path. On
2725       the other hand, when this pattern fails to  match  "bx",  the  returned
2726       name is B.
2727
2728       Warning:  By  default, certain start-of-match optimizations are used to
2729       give a fast "no match" result in some situations. For example,  if  the
2730       anchoring  is removed from the pattern above, there is an initial check
2731       for the presence of "c" in the subject before running the matching  en‐
2732       gine. This check fails for "bx", causing a match failure without seeing
2733       any marks. You can disable the start-of-match optimizations by  setting
2734       the  PCRE2_NO_START_OPTIMIZE  option for pcre2_compile() or by starting
2735       the pattern with (*NO_START_OPT).
2736
2737       After a successful match, a partial match, or one of  the  invalid  UTF
2738       errors  (for example, PCRE2_ERROR_UTF8_ERR5), pcre2_get_startchar() can
2739       be called. After a successful or partial match it returns the code unit
2740       offset  of  the character at which the match started. For a non-partial
2741       match, this can be different to the value of ovector[0] if the  pattern
2742       contains  the  \K escape sequence. After a partial match, however, this
2743       value is always the same as ovector[0] because \K does not  affect  the
2744       result of a partial match.
2745
2746       After  a UTF check failure, pcre2_get_startchar() can be used to obtain
2747       the code unit offset of the invalid UTF character. Details are given in
2748       the pcre2unicode page.
2749

ERROR RETURNS FROM pcre2_match()

2751
2752       If  pcre2_match() fails, it returns a negative number. This can be con‐
2753       verted to a text string by calling the pcre2_get_error_message()  func‐
2754       tion  (see  "Obtaining a textual error message" below).  Negative error
2755       codes are also returned by other functions,  and  are  documented  with
2756       them.  The codes are given names in the header file. If UTF checking is
2757       in force and an invalid UTF subject string is detected, one of a number
2758       of  UTF-specific negative error codes is returned. Details are given in
2759       the pcre2unicode page. The following are the other errors that  may  be
2760       returned by pcre2_match():
2761
2762         PCRE2_ERROR_NOMATCH
2763
2764       The subject string did not match the pattern.
2765
2766         PCRE2_ERROR_PARTIAL
2767
2768       The  subject  string did not match, but it did match partially. See the
2769       pcre2partial documentation for details of partial matching.
2770
2771         PCRE2_ERROR_BADMAGIC
2772
2773       PCRE2 stores a 4-byte "magic number" at the start of the compiled code,
2774       to  catch  the case when it is passed a junk pointer. This is the error
2775       that is returned when the magic number is not present.
2776
2777         PCRE2_ERROR_BADMODE
2778
2779       This error is given when a compiled pattern is passed to a function  in
2780       a  library  of a different code unit width, for example, a pattern com‐
2781       piled by the 8-bit library is passed to  a  16-bit  or  32-bit  library
2782       function.
2783
2784         PCRE2_ERROR_BADOFFSET
2785
2786       The value of startoffset was greater than the length of the subject.
2787
2788         PCRE2_ERROR_BADOPTION
2789
2790       An unrecognized bit was set in the options argument.
2791
2792         PCRE2_ERROR_BADUTFOFFSET
2793
2794       The UTF code unit sequence that was passed as a subject was checked and
2795       found to be valid (the PCRE2_NO_UTF_CHECK option was not set), but  the
2796       value  of startoffset did not point to the beginning of a UTF character
2797       or the end of the subject.
2798
2799         PCRE2_ERROR_CALLOUT
2800
2801       This error is never generated by pcre2_match() itself. It  is  provided
2802       for  use  by  callout  functions  that  want  to cause pcre2_match() or
2803       pcre2_callout_enumerate() to return a distinctive error code.  See  the
2804       pcre2callout documentation for details.
2805
2806         PCRE2_ERROR_DEPTHLIMIT
2807
2808       The nested backtracking depth limit was reached.
2809
2810         PCRE2_ERROR_HEAPLIMIT
2811
2812       The heap limit was reached.
2813
2814         PCRE2_ERROR_INTERNAL
2815
2816       An  unexpected  internal error has occurred. This error could be caused
2817       by a bug in PCRE2 or by overwriting of the compiled pattern.
2818
2819         PCRE2_ERROR_JIT_STACKLIMIT
2820
2821       This error is returned when a pattern that was successfully studied us‐
2822       ing JIT is being matched, but the memory available for the just-in-time
2823       processing stack is not large enough. See  the  pcre2jit  documentation
2824       for more details.
2825
2826         PCRE2_ERROR_MATCHLIMIT
2827
2828       The backtracking match limit was reached.
2829
2830         PCRE2_ERROR_NOMEMORY
2831
2832       Heap  memory  is  used  to  remember backgracking points. This error is
2833       given when the memory allocation function (default  or  custom)  fails.
2834       Note  that  a  different  error, PCRE2_ERROR_HEAPLIMIT, is given if the
2835       amount of memory needed exceeds the heap limit. PCRE2_ERROR_NOMEMORY is
2836       also  returned  if PCRE2_COPY_MATCHED_SUBJECT is set and memory alloca‐
2837       tion fails.
2838
2839         PCRE2_ERROR_NULL
2840
2841       Either the code, subject, or match_data argument was passed as NULL.
2842
2843         PCRE2_ERROR_RECURSELOOP
2844
2845       This error is returned when  pcre2_match()  detects  a  recursion  loop
2846       within  the  pattern. Specifically, it means that either the whole pat‐
2847       tern or a capture group has been called recursively for the second time
2848       at  the  same position in the subject string. Some simple patterns that
2849       might do this are detected and faulted at compile time, but  more  com‐
2850       plicated  cases,  in particular mutual recursions between two different
2851       groups, cannot be detected until matching is attempted.
2852

OBTAINING A TEXTUAL ERROR MESSAGE

2854
2855       int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer,
2856         PCRE2_SIZE bufflen);
2857
2858       A text message for an error code  from  any  PCRE2  function  (compile,
2859       match,  or  auxiliary)  can be obtained by calling pcre2_get_error_mes‐
2860       sage(). The code is passed as the first argument,  with  the  remaining
2861       two  arguments  specifying  a  code  unit buffer and its length in code
2862       units, into which the text message is placed. The message  is  returned
2863       in  code  units  of the appropriate width for the library that is being
2864       used.
2865
2866       The returned message is terminated with a trailing zero, and the  func‐
2867       tion  returns  the  number  of  code units used, excluding the trailing
2868       zero. If the error number is unknown, the negative error code PCRE2_ER‐
2869       ROR_BADDATA  is  returned.  If  the buffer is too small, the message is
2870       truncated (but still with a trailing zero), and the negative error code
2871       PCRE2_ERROR_NOMEMORY  is returned.  None of the messages are very long;
2872       a buffer size of 120 code units is ample.
2873

EXTRACTING CAPTURED SUBSTRINGS BY NUMBER

2875
2876       int pcre2_substring_length_bynumber(pcre2_match_data *match_data,
2877         uint32_t number, PCRE2_SIZE *length);
2878
2879       int pcre2_substring_copy_bynumber(pcre2_match_data *match_data,
2880         uint32_t number, PCRE2_UCHAR *buffer,
2881         PCRE2_SIZE *bufflen);
2882
2883       int pcre2_substring_get_bynumber(pcre2_match_data *match_data,
2884         uint32_t number, PCRE2_UCHAR **bufferptr,
2885         PCRE2_SIZE *bufflen);
2886
2887       void pcre2_substring_free(PCRE2_UCHAR *buffer);
2888
2889       Captured substrings can be accessed directly by using  the  ovector  as
2890       described above.  For convenience, auxiliary functions are provided for
2891       extracting  captured  substrings  as  new,  separate,   zero-terminated
2892       strings. A substring that contains a binary zero is correctly extracted
2893       and has a further zero added on the end, but  the  result  is  not,  of
2894       course, a C string.
2895
2896       The functions in this section identify substrings by number. The number
2897       zero refers to the entire matched substring, with higher numbers refer‐
2898       ring  to  substrings  captured by parenthesized groups. After a partial
2899       match, only substring zero is available.  An  attempt  to  extract  any
2900       other  substring  gives the error PCRE2_ERROR_PARTIAL. The next section
2901       describes similar functions for extracting captured substrings by name.
2902
2903       If a pattern uses the \K escape sequence within a  positive  assertion,
2904       the reported start of a successful match can be greater than the end of
2905       the match.  For example, if the pattern  (?=ab\K)  is  matched  against
2906       "ab",  the  start  and  end offset values for the match are 2 and 0. In
2907       this situation, calling these functions with a  zero  substring  number
2908       extracts a zero-length empty string.
2909
2910       You  can  find the length in code units of a captured substring without
2911       extracting it by calling pcre2_substring_length_bynumber().  The  first
2912       argument  is a pointer to the match data block, the second is the group
2913       number, and the third is a pointer to a variable into which the  length
2914       is  placed.  If  you just want to know whether or not the substring has
2915       been captured, you can pass the third argument as NULL.
2916
2917       The pcre2_substring_copy_bynumber() function  copies  a  captured  sub‐
2918       string  into  a supplied buffer, whereas pcre2_substring_get_bynumber()
2919       copies it into new memory, obtained using the  same  memory  allocation
2920       function  that  was  used for the match data block. The first two argu‐
2921       ments of these functions are a pointer to the match data  block  and  a
2922       capture group number.
2923
2924       The final arguments of pcre2_substring_copy_bynumber() are a pointer to
2925       the buffer and a pointer to a variable that contains its length in code
2926       units.  This is updated to contain the actual number of code units used
2927       for the extracted substring, excluding the terminating zero.
2928
2929       For pcre2_substring_get_bynumber() the third and fourth arguments point
2930       to  variables that are updated with a pointer to the new memory and the
2931       number of code units that comprise the substring, again  excluding  the
2932       terminating  zero.  When  the substring is no longer needed, the memory
2933       should be freed by calling pcre2_substring_free().
2934
2935       The return value from all these functions is zero  for  success,  or  a
2936       negative  error  code.  If  the pattern match failed, the match failure
2937       code is returned.  If a substring number greater than zero is used  af‐
2938       ter  a  partial  match, PCRE2_ERROR_PARTIAL is returned. Other possible
2939       error codes are:
2940
2941         PCRE2_ERROR_NOMEMORY
2942
2943       The buffer was too small for  pcre2_substring_copy_bynumber(),  or  the
2944       attempt to get memory failed for pcre2_substring_get_bynumber().
2945
2946         PCRE2_ERROR_NOSUBSTRING
2947
2948       There  is  no  substring  with that number in the pattern, that is, the
2949       number is greater than the number of capturing parentheses.
2950
2951         PCRE2_ERROR_UNAVAILABLE
2952
2953       The substring number, though not greater than the number of captures in
2954       the pattern, is greater than the number of slots in the ovector, so the
2955       substring could not be captured.
2956
2957         PCRE2_ERROR_UNSET
2958
2959       The substring did not participate in the match.  For  example,  if  the
2960       pattern  is  (abc)|(def) and the subject is "def", and the ovector con‐
2961       tains at least two capturing slots, substring number 1 is unset.
2962

EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS

2964
2965       int pcre2_substring_list_get(pcre2_match_data *match_data,
2966         PCRE2_UCHAR ***listptr, PCRE2_SIZE **lengthsptr);
2967
2968       void pcre2_substring_list_free(PCRE2_SPTR *list);
2969
2970       The pcre2_substring_list_get() function  extracts  all  available  sub‐
2971       strings  and  builds  a  list of pointers to them. It also (optionally)
2972       builds a second list that contains their lengths (in code  units),  ex‐
2973       cluding  a  terminating zero that is added to each of them. All this is
2974       done in a single block of memory that is obtained using the same memory
2975       allocation function that was used to get the match data block.
2976
2977       This  function  must be called only after a successful match. If called
2978       after a partial match, the error code PCRE2_ERROR_PARTIAL is returned.
2979
2980       The address of the memory block is returned via listptr, which is  also
2981       the start of the list of string pointers. The end of the list is marked
2982       by a NULL pointer. The address of the list of lengths is  returned  via
2983       lengthsptr.  If your strings do not contain binary zeros and you do not
2984       therefore need the lengths, you may supply NULL as the lengthsptr argu‐
2985       ment  to  disable  the  creation of a list of lengths. The yield of the
2986       function is zero if all went well, or PCRE2_ERROR_NOMEMORY if the  mem‐
2987       ory  block could not be obtained. When the list is no longer needed, it
2988       should be freed by calling pcre2_substring_list_free().
2989
2990       If this function encounters a substring that is unset, which can happen
2991       when  capture  group  number  n+1 matches some part of the subject, but
2992       group n has not been used at all, it returns an empty string. This  can
2993       be distinguished from a genuine zero-length substring by inspecting the
2994       appropriate offset in the ovector, which contain PCRE2_UNSET for  unset
2995       substrings, or by calling pcre2_substring_length_bynumber().
2996

EXTRACTING CAPTURED SUBSTRINGS BY NAME

2998
2999       int pcre2_substring_number_from_name(const pcre2_code *code,
3000         PCRE2_SPTR name);
3001
3002       int pcre2_substring_length_byname(pcre2_match_data *match_data,
3003         PCRE2_SPTR name, PCRE2_SIZE *length);
3004
3005       int pcre2_substring_copy_byname(pcre2_match_data *match_data,
3006         PCRE2_SPTR name, PCRE2_UCHAR *buffer, PCRE2_SIZE *bufflen);
3007
3008       int pcre2_substring_get_byname(pcre2_match_data *match_data,
3009         PCRE2_SPTR name, PCRE2_UCHAR **bufferptr, PCRE2_SIZE *bufflen);
3010
3011       void pcre2_substring_free(PCRE2_UCHAR *buffer);
3012
3013       To  extract a substring by name, you first have to find associated num‐
3014       ber.  For example, for this pattern:
3015
3016         (a+)b(?<xxx>\d+)...
3017
3018       the number of the capture group called "xxx" is 2. If the name is known
3019       to be unique (PCRE2_DUPNAMES was not set), you can find the number from
3020       the name by calling pcre2_substring_number_from_name(). The first argu‐
3021       ment  is the compiled pattern, and the second is the name. The yield of
3022       the function is the group number, PCRE2_ERROR_NOSUBSTRING if  there  is
3023       no  group  with that name, or PCRE2_ERROR_NOUNIQUESUBSTRING if there is
3024       more than one group with that name.  Given the number, you can  extract
3025       the  substring  directly from the ovector, or use one of the "bynumber"
3026       functions described above.
3027
3028       For convenience, there are also "byname" functions that  correspond  to
3029       the "bynumber" functions, the only difference being that the second ar‐
3030       gument is a name instead of a number.  If  PCRE2_DUPNAMES  is  set  and
3031       there are duplicate names, these functions scan all the groups with the
3032       given name, and return the captured  substring  from  the  first  named
3033       group that is set.
3034
3035       If  there are no groups with the given name, PCRE2_ERROR_NOSUBSTRING is
3036       returned. If all groups with the name have  numbers  that  are  greater
3037       than the number of slots in the ovector, PCRE2_ERROR_UNAVAILABLE is re‐
3038       turned. If there is at least one group with a slot in the ovector,  but
3039       no group is found to be set, PCRE2_ERROR_UNSET is returned.
3040
3041       Warning: If the pattern uses the (?| feature to set up multiple capture
3042       groups with the same number, as described in the section  on  duplicate
3043       group numbers in the pcre2pattern page, you cannot use names to distin‐
3044       guish the different capture groups, because names are not  included  in
3045       the  compiled  code.  The  matching process uses only numbers. For this
3046       reason, the use of different names for  groups  with  the  same  number
3047       causes an error at compile time.
3048

CREATING A NEW STRING WITH SUBSTITUTIONS

3050
3051       int pcre2_substitute(const pcre2_code *code, PCRE2_SPTR subject,
3052         PCRE2_SIZE length, PCRE2_SIZE startoffset,
3053         uint32_t options, pcre2_match_data *match_data,
3054         pcre2_match_context *mcontext, PCRE2_SPTR replacement,
3055         PCRE2_SIZE rlength, PCRE2_UCHAR *outputbuffer,
3056         PCRE2_SIZE *outlengthptr);
3057
3058       This  function  optionally calls pcre2_match() and then makes a copy of
3059       the subject string in outputbuffer, replacing parts that  were  matched
3060       with the replacement string, whose length is supplied in rlength, which
3061       can be given as PCRE2_ZERO_TERMINATED for a zero-terminated string.  As
3062       a  special  case,  if  replacement is NULL and rlength is zero, the re‐
3063       placement is assumed to be an empty string. If rlength is non-zero,  an
3064       error occurs if replacement is NULL.
3065
3066       There is an option (see PCRE2_SUBSTITUTE_REPLACEMENT_ONLY below) to re‐
3067       turn just the replacement string(s). The default action is  to  perform
3068       just  one  replacement  if  the pattern matches, but there is an option
3069       that requests multiple replacements  (see  PCRE2_SUBSTITUTE_GLOBAL  be‐
3070       low).
3071
3072       If  successful,  pcre2_substitute() returns the number of substitutions
3073       that were carried out. This may be zero if no match was found,  and  is
3074       never  greater  than one unless PCRE2_SUBSTITUTE_GLOBAL is set. A nega‐
3075       tive value is returned if an error is detected.
3076
3077       Matches in which a \K item in a lookahead in  the  pattern  causes  the
3078       match  to  end  before it starts are not supported, and give rise to an
3079       error return. For global replacements, matches in which \K in a lookbe‐
3080       hind  causes the match to start earlier than the point that was reached
3081       in the previous iteration are also not supported.
3082
3083       The first seven arguments of pcre2_substitute() are  the  same  as  for
3084       pcre2_match(), except that the partial matching options are not permit‐
3085       ted, and match_data may be passed as NULL, in which case a  match  data
3086       block  is obtained and freed within this function, using memory manage‐
3087       ment functions from the match context, if provided, or else those  that
3088       were used to allocate memory for the compiled code.
3089
3090       If  match_data is not NULL and PCRE2_SUBSTITUTE_MATCHED is not set, the
3091       provided block is used for all calls to pcre2_match(), and its contents
3092       afterwards  are  the result of the final call. For global changes, this
3093       will always be a no-match error. The contents of the ovector within the
3094       match data block may or may not have been changed.
3095
3096       As  well as the usual options for pcre2_match(), a number of additional
3097       options can be set in the options argument of pcre2_substitute().   One
3098       such  option is PCRE2_SUBSTITUTE_MATCHED. When this is set, an external
3099       match_data block must be provided, and it must have already  been  used
3100       for an external call to pcre2_match() with the same pattern and subject
3101       arguments. The data in the match_data block (return code,  offset  vec‐
3102       tor)  is  then  used  for  the  first  substitution  instead of calling
3103       pcre2_match() from within pcre2_substitute(). This allows  an  applica‐
3104       tion to check for a match before choosing to substitute, without having
3105       to repeat the match.
3106
3107       The contents of the  externally  supplied  match  data  block  are  not
3108       changed   when   PCRE2_SUBSTITUTE_MATCHED   is  set.  If  PCRE2_SUBSTI‐
3109       TUTE_GLOBAL is also set, pcre2_match() is called after the  first  sub‐
3110       stitution  to  check for further matches, but this is done using an in‐
3111       ternally obtained match data block, thus always  leaving  the  external
3112       block unchanged.
3113
3114       The  code  argument is not used for matching before the first substitu‐
3115       tion when PCRE2_SUBSTITUTE_MATCHED is set, but  it  must  be  provided,
3116       even  when  PCRE2_SUBSTITUTE_GLOBAL is not set, because it contains in‐
3117       formation such as the UTF setting and the number of capturing parenthe‐
3118       ses in the pattern.
3119
3120       The  default  action  of  pcre2_substitute() is to return a copy of the
3121       subject string with matched substrings replaced. However, if PCRE2_SUB‐
3122       STITUTE_REPLACEMENT_ONLY  is  set,  only the replacement substrings are
3123       returned. In the global case, multiple replacements are concatenated in
3124       the  output  buffer.  Substitution  callouts (see below) can be used to
3125       separate them if necessary.
3126
3127       The outlengthptr argument of pcre2_substitute() must point to  a  vari‐
3128       able  that contains the length, in code units, of the output buffer. If
3129       the function is successful, the value is updated to contain the  length
3130       in  code  units  of the new string, excluding the trailing zero that is
3131       automatically added.
3132
3133       If the function is not successful, the value set via  outlengthptr  de‐
3134       pends  on  the  type  of  error.  For  syntax errors in the replacement
3135       string, the value is the offset in the replacement string where the er‐
3136       ror  was  detected.  For  other errors, the value is PCRE2_UNSET by de‐
3137       fault. This includes the case of the output buffer being too small, un‐
3138       less PCRE2_SUBSTITUTE_OVERFLOW_LENGTH is set.
3139
3140       PCRE2_SUBSTITUTE_OVERFLOW_LENGTH  changes  what happens when the output
3141       buffer is too small. The default action is to return PCRE2_ERROR_NOMEM‐
3142       ORY  immediately.  If  this  option is set, however, pcre2_substitute()
3143       continues to go through the motions of matching and substituting (with‐
3144       out,  of course, writing anything) in order to compute the size of buf‐
3145       fer that is needed. This value is  passed  back  via  the  outlengthptr
3146       variable,  with  the  result  of  the  function  still  being PCRE2_ER‐
3147       ROR_NOMEMORY.
3148
3149       Passing a buffer size of zero is a permitted way  of  finding  out  how
3150       much  memory  is needed for given substitution. However, this does mean
3151       that the entire operation is carried out twice. Depending on the appli‐
3152       cation,  it  may  be more efficient to allocate a large buffer and free
3153       the  excess  afterwards,  instead   of   using   PCRE2_SUBSTITUTE_OVER‐
3154       FLOW_LENGTH.
3155
3156       The  replacement  string,  which  is interpreted as a UTF string in UTF
3157       mode, is checked for UTF validity unless PCRE2_NO_UTF_CHECK is set.  An
3158       invalid UTF replacement string causes an immediate return with the rel‐
3159       evant UTF error code.
3160
3161       If PCRE2_SUBSTITUTE_LITERAL is set, the replacement string is  not  in‐
3162       terpreted in any way. By default, however, a dollar character is an es‐
3163       cape character that can specify the insertion of characters  from  cap‐
3164       ture  groups  and names from (*MARK) or other control verbs in the pat‐
3165       tern. The following forms are always recognized:
3166
3167         $$                  insert a dollar character
3168         $<n> or ${<n>}      insert the contents of group <n>
3169         $*MARK or ${*MARK}  insert a control verb name
3170
3171       Either a group number or a group name  can  be  given  for  <n>.  Curly
3172       brackets  are  required only if the following character would be inter‐
3173       preted as part of the number or name. The number may be zero to include
3174       the  entire  matched  string.   For  example,  if  the pattern a(b)c is
3175       matched with "=abc=" and the replacement string "+$1$0$1+", the  result
3176       is "=+babcb+=".
3177
3178       $*MARK  inserts the name from the last encountered backtracking control
3179       verb on the matching path that has a name. (*MARK) must always  include
3180       a  name,  but  the  other  verbs  need not. For example, in the case of
3181       (*MARK:A)(*PRUNE) the name inserted is "A", but for (*MARK:A)(*PRUNE:B)
3182       the  relevant  name is "B". This facility can be used to perform simple
3183       simultaneous substitutions, as this pcre2test example shows:
3184
3185         /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK}
3186             apple lemon
3187          2: pear orange
3188
3189       PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject
3190       string,  replacing every matching substring. If this option is not set,
3191       only the first matching substring is replaced. The search  for  matches
3192       takes  place in the original subject string (that is, previous replace‐
3193       ments do not affect it).  Iteration is  implemented  by  advancing  the
3194       startoffset  value  for  each search, which is always passed the entire
3195       subject string. If an offset limit is set in the match context, search‐
3196       ing stops when that limit is reached.
3197
3198       You  can  restrict  the effect of a global substitution to a portion of
3199       the subject string by setting either or both of startoffset and an off‐
3200       set limit. Here is a pcre2test example:
3201
3202         /B/g,replace=!,use_offset_limit
3203         ABC ABC ABC ABC\=offset=3,offset_limit=12
3204          2: ABC A!C A!C ABC
3205
3206       When  continuing  with  global substitutions after matching a substring
3207       with zero length, an attempt to find a non-empty match at the same off‐
3208       set is performed.  If this is not successful, the offset is advanced by
3209       one character except when CRLF is a valid newline sequence and the next
3210       two  characters are CR, LF. In this case, the offset is advanced by two
3211       characters.
3212
3213       PCRE2_SUBSTITUTE_UNKNOWN_UNSET causes references to capture groups that
3214       do not appear in the pattern to be treated as unset groups. This option
3215       should be used with care, because it means that a typo in a group  name
3216       or number no longer causes the PCRE2_ERROR_NOSUBSTRING error.
3217
3218       PCRE2_SUBSTITUTE_UNSET_EMPTY causes unset capture groups (including un‐
3219       known groups when PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set) to be  treated
3220       as  empty  strings  when inserted as described above. If this option is
3221       not set, an attempt to insert an unset group causes the PCRE2_ERROR_UN‐
3222       SET  error.  This  option  does not influence the extended substitution
3223       syntax described below.
3224
3225       PCRE2_SUBSTITUTE_EXTENDED causes extra processing to be applied to  the
3226       replacement  string.  Without this option, only the dollar character is
3227       special, and only the group insertion forms  listed  above  are  valid.
3228       When PCRE2_SUBSTITUTE_EXTENDED is set, two things change:
3229
3230       Firstly,  backslash in a replacement string is interpreted as an escape
3231       character. The usual forms such as \n or \x{ddd} can be used to specify
3232       particular  character codes, and backslash followed by any non-alphanu‐
3233       meric character quotes that character. Extended quoting  can  be  coded
3234       using \Q...\E, exactly as in pattern strings.
3235
3236       There  are  also four escape sequences for forcing the case of inserted
3237       letters.  The insertion mechanism has three states:  no  case  forcing,
3238       force upper case, and force lower case. The escape sequences change the
3239       current state: \U and \L change to upper or lower case forcing, respec‐
3240       tively,  and  \E (when not terminating a \Q quoted sequence) reverts to
3241       no case forcing. The sequences \u and \l force the next  character  (if
3242       it  is  a  letter)  to  upper or lower case, respectively, and then the
3243       state automatically reverts to no case forcing. Case forcing applies to
3244       all  inserted  characters, including those from capture groups and let‐
3245       ters within \Q...\E quoted sequences. If either PCRE2_UTF or  PCRE2_UCP
3246       was  set when the pattern was compiled, Unicode properties are used for
3247       case forcing characters whose code points are greater than 127.
3248
3249       Note that case forcing sequences such as \U...\E do not nest. For exam‐
3250       ple,  the  result of processing "\Uaa\LBB\Ecc\E" is "AAbbcc"; the final
3251       \E has no effect. Note  also  that  the  PCRE2_ALT_BSUX  and  PCRE2_EX‐
3252       TRA_ALT_BSUX options do not apply to replacement strings.
3253
3254       The  second  effect of setting PCRE2_SUBSTITUTE_EXTENDED is to add more
3255       flexibility to capture group substitution. The  syntax  is  similar  to
3256       that used by Bash:
3257
3258         ${<n>:-<string>}
3259         ${<n>:+<string1>:<string2>}
3260
3261       As  before,  <n> may be a group number or a name. The first form speci‐
3262       fies a default value. If group <n> is set, its value  is  inserted;  if
3263       not,  <string>  is  expanded  and  the result inserted. The second form
3264       specifies strings that are expanded and inserted when group <n> is  set
3265       or  unset,  respectively. The first form is just a convenient shorthand
3266       for
3267
3268         ${<n>:+${<n>}:<string>}
3269
3270       Backslash can be used to escape colons and closing  curly  brackets  in
3271       the  replacement  strings.  A change of the case forcing state within a
3272       replacement string remains  in  force  afterwards,  as  shown  in  this
3273       pcre2test example:
3274
3275         /(some)?(body)/substitute_extended,replace=${1:+\U:\L}HeLLo
3276             body
3277          1: hello
3278             somebody
3279          1: HELLO
3280
3281       The  PCRE2_SUBSTITUTE_UNSET_EMPTY option does not affect these extended
3282       substitutions. However, PCRE2_SUBSTITUTE_UNKNOWN_UNSET does  cause  un‐
3283       known groups in the extended syntax forms to be treated as unset.
3284
3285       If  PCRE2_SUBSTITUTE_LITERAL  is  set,  PCRE2_SUBSTITUTE_UNKNOWN_UNSET,
3286       PCRE2_SUBSTITUTE_UNSET_EMPTY, and PCRE2_SUBSTITUTE_EXTENDED are irrele‐
3287       vant and are ignored.
3288
3289   Substitution errors
3290
3291       In  the  event of an error, pcre2_substitute() returns a negative error
3292       code. Except for PCRE2_ERROR_NOMATCH (which is never returned),  errors
3293       from pcre2_match() are passed straight back.
3294
3295       PCRE2_ERROR_NOSUBSTRING is returned for a non-existent substring inser‐
3296       tion, unless PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set.
3297
3298       PCRE2_ERROR_UNSET is returned for an unset substring insertion (includ‐
3299       ing  an  unknown  substring when PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set)
3300       when the simple (non-extended) syntax is used and  PCRE2_SUBSTITUTE_UN‐
3301       SET_EMPTY is not set.
3302
3303       PCRE2_ERROR_NOMEMORY  is  returned  if  the  output  buffer  is not big
3304       enough. If the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option is set, the size
3305       of  buffer  that is needed is returned via outlengthptr. Note that this
3306       does not happen by default.
3307
3308       PCRE2_ERROR_NULL is returned if PCRE2_SUBSTITUTE_MATCHED is set but the
3309       match_data  argument is NULL or if the subject or replacement arguments
3310       are NULL. For backward compatibility reasons an exception is  made  for
3311       the replacement argument if the rlength argument is also 0.
3312
3313       PCRE2_ERROR_BADREPLACEMENT  is  used for miscellaneous syntax errors in
3314       the replacement string, with more  particular  errors  being  PCRE2_ER‐
3315       ROR_BADREPESCAPE (invalid escape sequence), PCRE2_ERROR_REPMISSINGBRACE
3316       (closing curly bracket not found), PCRE2_ERROR_BADSUBSTITUTION  (syntax
3317       error  in  extended group substitution), and PCRE2_ERROR_BADSUBSPATTERN
3318       (the pattern match ended before it started or the match started earlier
3319       than  the  current  position  in the subject, which can happen if \K is
3320       used in an assertion).
3321
3322       As for all PCRE2 errors, a text message that describes the error can be
3323       obtained  by  calling  the pcre2_get_error_message() function (see "Ob‐
3324       taining a textual error message" above).
3325
3326   Substitution callouts
3327
3328       int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
3329         int (*callout_function)(pcre2_substitute_callout_block *, void *),
3330         void *callout_data);
3331
3332       The pcre2_set_substitution_callout() function can be used to specify  a
3333       callout  function for pcre2_substitute(). This information is passed in
3334       a match context. The callout function is called after each substitution
3335       has been processed, but it can cause the replacement not to happen. The
3336       callout function is not called for simulated substitutions that  happen
3337       as a result of the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option.
3338
3339       The first argument of the callout function is a pointer to a substitute
3340       callout block structure, which contains the following fields, not  nec‐
3341       essarily in this order:
3342
3343         uint32_t    version;
3344         uint32_t    subscount;
3345         PCRE2_SPTR  input;
3346         PCRE2_SPTR  output;
3347         PCRE2_SIZE *ovector;
3348         uint32_t    oveccount;
3349         PCRE2_SIZE  output_offsets[2];
3350
3351       The  version field contains the version number of the block format. The
3352       current version is 0. The version number will  increase  in  future  if
3353       more  fields are added, but the intention is never to remove any of the
3354       existing fields.
3355
3356       The subscount field is the number of the current match. It is 1 for the
3357       first callout, 2 for the second, and so on. The input and output point‐
3358       ers are copies of the values passed to pcre2_substitute().
3359
3360       The ovector field points to the ovector, which contains the  result  of
3361       the most recent match. The oveccount field contains the number of pairs
3362       that are set in the ovector, and is always greater than zero.
3363
3364       The output_offsets vector contains the offsets of  the  replacement  in
3365       the  output  string. This has already been processed for dollar and (if
3366       requested) backslash substitutions as described above.
3367
3368       The second argument of the callout function  is  the  value  passed  as
3369       callout_data  when  the  function was registered. The value returned by
3370       the callout function is interpreted as follows:
3371
3372       If the value is zero, the replacement is accepted, and,  if  PCRE2_SUB‐
3373       STITUTE_GLOBAL  is set, processing continues with a search for the next
3374       match. If the value is not zero, the current  replacement  is  not  ac‐
3375       cepted.  If  the  value is greater than zero, processing continues when
3376       PCRE2_SUBSTITUTE_GLOBAL is set. Otherwise (the value is less than  zero
3377       or  PCRE2_SUBSTITUTE_GLOBAL  is  not set), the the rest of the input is
3378       copied to the output and the call to pcre2_substitute() exits,  return‐
3379       ing the number of matches so far.
3380

DUPLICATE CAPTURE GROUP NAMES

3382
3383       int pcre2_substring_nametable_scan(const pcre2_code *code,
3384         PCRE2_SPTR name, PCRE2_SPTR *first, PCRE2_SPTR *last);
3385
3386       When  a  pattern  is compiled with the PCRE2_DUPNAMES option, names for
3387       capture groups are not required to be unique. Duplicate names  are  al‐
3388       ways  allowed for groups with the same number, created by using the (?|
3389       feature. Indeed, if such groups are named, they are required to use the
3390       same names.
3391
3392       Normally,  patterns  that  use duplicate names are such that in any one
3393       match, only one of each set of identically-named  groups  participates.
3394       An example is shown in the pcre2pattern documentation.
3395
3396       When   duplicates   are   present,   pcre2_substring_copy_byname()  and
3397       pcre2_substring_get_byname() return the first  substring  corresponding
3398       to  the given name that is set. Only if none are set is PCRE2_ERROR_UN‐
3399       SET is returned. The  pcre2_substring_number_from_name()  function  re‐
3400       turns  the error PCRE2_ERROR_NOUNIQUESUBSTRING when there are duplicate
3401       names.
3402
3403       If you want to get full details of all captured substrings for a  given
3404       name,  you  must use the pcre2_substring_nametable_scan() function. The
3405       first argument is the compiled pattern, and the second is the name.  If
3406       the  third  and fourth arguments are NULL, the function returns a group
3407       number for a unique name, or PCRE2_ERROR_NOUNIQUESUBSTRING otherwise.
3408
3409       When the third and fourth arguments are not NULL, they must be pointers
3410       to  variables  that are updated by the function. After it has run, they
3411       point to the first and last entries in the name-to-number table for the
3412       given  name,  and the function returns the length of each entry in code
3413       units. In both cases, PCRE2_ERROR_NOSUBSTRING is returned if there  are
3414       no entries for the given name.
3415
3416       The format of the name table is described above in the section entitled
3417       Information about a pattern. Given all the  relevant  entries  for  the
3418       name,  you  can  extract  each of their numbers, and hence the captured
3419       data.
3420

FINDING ALL POSSIBLE MATCHES AT ONE POSITION

3422
3423       The traditional matching function uses a  similar  algorithm  to  Perl,
3424       which  stops when it finds the first match at a given point in the sub‐
3425       ject. If you want to find all possible matches, or the longest possible
3426       match  at  a  given  position,  consider using the alternative matching
3427       function (see below) instead. If you cannot use the  alternative  func‐
3428       tion, you can kludge it up by making use of the callout facility, which
3429       is described in the pcre2callout documentation.
3430
3431       What you have to do is to insert a callout right at the end of the pat‐
3432       tern.   When your callout function is called, extract and save the cur‐
3433       rent matched substring. Then return 1, which  forces  pcre2_match()  to
3434       backtrack  and  try other alternatives. Ultimately, when it runs out of
3435       matches, pcre2_match() will yield PCRE2_ERROR_NOMATCH.
3436

MATCHING A PATTERN: THE ALTERNATIVE FUNCTION

3438
3439       int pcre2_dfa_match(const pcre2_code *code, PCRE2_SPTR subject,
3440         PCRE2_SIZE length, PCRE2_SIZE startoffset,
3441         uint32_t options, pcre2_match_data *match_data,
3442         pcre2_match_context *mcontext,
3443         int *workspace, PCRE2_SIZE wscount);
3444
3445       The function pcre2_dfa_match() is called  to  match  a  subject  string
3446       against  a  compiled pattern, using a matching algorithm that scans the
3447       subject string just once (not counting lookaround assertions), and does
3448       not  backtrack (except when processing lookaround assertions). This has
3449       different characteristics to the normal algorithm, and is not  compati‐
3450       ble  with  Perl.  Some  of  the features of PCRE2 patterns are not sup‐
3451       ported. Nevertheless, there are times when this kind of matching can be
3452       useful.  For a discussion of the two matching algorithms, and a list of
3453       features that pcre2_dfa_match() does not support, see the pcre2matching
3454       documentation.
3455
3456       The  arguments  for  the pcre2_dfa_match() function are the same as for
3457       pcre2_match(), plus two extras. The ovector within the match data block
3458       is used in a different way, and this is described below. The other com‐
3459       mon arguments are used in the same way as for pcre2_match(),  so  their
3460       description is not repeated here.
3461
3462       The  two  additional  arguments provide workspace for the function. The
3463       workspace vector should contain at least 20 elements. It  is  used  for
3464       keeping  track  of  multiple  paths  through  the  pattern  tree.  More
3465       workspace is needed for patterns and subjects where there are a lot  of
3466       potential matches.
3467
3468       Here is an example of a simple call to pcre2_dfa_match():
3469
3470         int wspace[20];
3471         pcre2_match_data *md = pcre2_match_data_create(4, NULL);
3472         int rc = pcre2_dfa_match(
3473           re,             /* result of pcre2_compile() */
3474           "some string",  /* the subject string */
3475           11,             /* the length of the subject string */
3476           0,              /* start at offset 0 in the subject */
3477           0,              /* default options */
3478           md,             /* the match data block */
3479           NULL,           /* a match context; NULL means use defaults */
3480           wspace,         /* working space vector */
3481           20);            /* number of elements (NOT size in bytes) */
3482
3483   Option bits for pcre2_dfa_match()
3484
3485       The  unused  bits of the options argument for pcre2_dfa_match() must be
3486       zero.  The  only   bits   that   may   be   set   are   PCRE2_ANCHORED,
3487       PCRE2_COPY_MATCHED_SUBJECT,  PCRE2_ENDANCHORED, PCRE2_NOTBOL, PCRE2_NO‐
3488       TEOL,   PCRE2_NOTEMPTY,   PCRE2_NOTEMPTY_ATSTART,   PCRE2_NO_UTF_CHECK,
3489       PCRE2_PARTIAL_HARD,    PCRE2_PARTIAL_SOFT,    PCRE2_DFA_SHORTEST,   and
3490       PCRE2_DFA_RESTART. All but the last four of these are exactly the  same
3491       as for pcre2_match(), so their description is not repeated here.
3492
3493         PCRE2_PARTIAL_HARD
3494         PCRE2_PARTIAL_SOFT
3495
3496       These  have  the  same general effect as they do for pcre2_match(), but
3497       the details are slightly different. When PCRE2_PARTIAL_HARD is set  for
3498       pcre2_dfa_match(),  it  returns  PCRE2_ERROR_PARTIAL  if the end of the
3499       subject is reached and there is still at least one matching possibility
3500       that requires additional characters. This happens even if some complete
3501       matches have already been found. When PCRE2_PARTIAL_SOFT  is  set,  the
3502       return  code  PCRE2_ERROR_NOMATCH is converted into PCRE2_ERROR_PARTIAL
3503       if the end of the subject is  reached,  there  have  been  no  complete
3504       matches, but there is still at least one matching possibility. The por‐
3505       tion of the string that was inspected when the  longest  partial  match
3506       was found is set as the first matching string in both cases. There is a
3507       more detailed discussion of partial and  multi-segment  matching,  with
3508       examples, in the pcre2partial documentation.
3509
3510         PCRE2_DFA_SHORTEST
3511
3512       Setting  the PCRE2_DFA_SHORTEST option causes the matching algorithm to
3513       stop as soon as it has found one match. Because of the way the alterna‐
3514       tive  algorithm  works, this is necessarily the shortest possible match
3515       at the first possible matching point in the subject string.
3516
3517         PCRE2_DFA_RESTART
3518
3519       When pcre2_dfa_match() returns a partial match, it is possible to  call
3520       it again, with additional subject characters, and have it continue with
3521       the same match. The PCRE2_DFA_RESTART option requests this action; when
3522       it  is  set,  the workspace and wscount options must reference the same
3523       vector as before because data about the match so far is  left  in  them
3524       after a partial match. There is more discussion of this facility in the
3525       pcre2partial documentation.
3526
3527   Successful returns from pcre2_dfa_match()
3528
3529       When pcre2_dfa_match() succeeds, it may have matched more than one sub‐
3530       string in the subject. Note, however, that all the matches from one run
3531       of the function start at the same point in  the  subject.  The  shorter
3532       matches  are all initial substrings of the longer matches. For example,
3533       if the pattern
3534
3535         <.*>
3536
3537       is matched against the string
3538
3539         This is <something> <something else> <something further> no more
3540
3541       the three matched strings are
3542
3543         <something> <something else> <something further>
3544         <something> <something else>
3545         <something>
3546
3547       On success, the yield of the function is a number  greater  than  zero,
3548       which  is  the  number  of  matched substrings. The offsets of the sub‐
3549       strings are returned in the ovector, and can be extracted by number  in
3550       the  same way as for pcre2_match(), but the numbers bear no relation to
3551       any capture groups that may exist in the pattern, because DFA  matching
3552       does not support capturing.
3553
3554       Calls  to the convenience functions that extract substrings by name re‐
3555       turn the error PCRE2_ERROR_DFA_UFUNC (unsupported function) if used af‐
3556       ter  a  DFA match. The convenience functions that extract substrings by
3557       number never return PCRE2_ERROR_NOSUBSTRING.
3558
3559       The matched strings are stored in  the  ovector  in  reverse  order  of
3560       length;  that  is,  the longest matching string is first. If there were
3561       too many matches to fit into the ovector, the yield of the function  is
3562       zero, and the vector is filled with the longest matches.
3563
3564       NOTE:  PCRE2's  "auto-possessification" optimization usually applies to
3565       character repeats at the end of a pattern (as well as internally).  For
3566       example,  the pattern "a\d+" is compiled as if it were "a\d++". For DFA
3567       matching, this means that only one possible match is found. If you  re‐
3568       ally do want multiple matches in such cases, either use an ungreedy re‐
3569       peat such as "a\d+?" or set the PCRE2_NO_AUTO_POSSESS option when  com‐
3570       piling.
3571
3572   Error returns from pcre2_dfa_match()
3573
3574       The pcre2_dfa_match() function returns a negative number when it fails.
3575       Many of the errors are the same  as  for  pcre2_match(),  as  described
3576       above.  There are in addition the following errors that are specific to
3577       pcre2_dfa_match():
3578
3579         PCRE2_ERROR_DFA_UITEM
3580
3581       This return is given if pcre2_dfa_match() encounters  an  item  in  the
3582       pattern  that it does not support, for instance, the use of \C in a UTF
3583       mode or a backreference.
3584
3585         PCRE2_ERROR_DFA_UCOND
3586
3587       This return is given if pcre2_dfa_match() encounters a  condition  item
3588       that uses a backreference for the condition, or a test for recursion in
3589       a specific capture group. These are not supported.
3590
3591         PCRE2_ERROR_DFA_UINVALID_UTF
3592
3593       This return is given if pcre2_dfa_match() is called for a pattern  that
3594       was  compiled  with  PCRE2_MATCH_INVALID_UTF. This is not supported for
3595       DFA matching.
3596
3597         PCRE2_ERROR_DFA_WSSIZE
3598
3599       This return is given if pcre2_dfa_match() runs  out  of  space  in  the
3600       workspace vector.
3601
3602         PCRE2_ERROR_DFA_RECURSE
3603
3604       When a recursion or subroutine call is processed, the matching function
3605       calls itself recursively, using private  memory  for  the  ovector  and
3606       workspace.   This  error  is given if the internal ovector is not large
3607       enough. This should be extremely rare, as a  vector  of  size  1000  is
3608       used.
3609
3610         PCRE2_ERROR_DFA_BADRESTART
3611
3612       When  pcre2_dfa_match()  is  called  with the PCRE2_DFA_RESTART option,
3613       some plausibility checks are made on the  contents  of  the  workspace,
3614       which  should  contain data about the previous partial match. If any of
3615       these checks fail, this error is given.
3616

SEE ALSO

3618
3619       pcre2build(3),   pcre2callout(3),    pcre2demo(3),    pcre2matching(3),
3620       pcre2partial(3), pcre2posix(3), pcre2sample(3), pcre2unicode(3).
3621

AUTHOR

3623
3624       Philip Hazel
3625       Retired from University Computing Service
3626       Cambridge, England.
3627

REVISION

3629
3630       Last updated: 27 July 2022
3631       Copyright (c) 1997-2022 University of Cambridge.
3632
3633
3634
3635PCRE2 10.41                      27 July 2022                      PCRE2API(3)
Impressum