Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PCRE2API(3)		   Library Functions Manual		   PCRE2API(3)

NAME
       PCRE2 - Perl-compatible regular expressions (revised API)

       #include	<pcre2.h>

       PCRE2  is  a  new API for PCRE, starting	at release 10.0. This document
       contains	a description of all its native	functions. See the pcre2 docu-
       ment for	an overview of all the PCRE2 documentation.

PCRE2 NATIVE API BASIC FUNCTIONS

       pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE	length,
	 uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset,
	 pcre2_compile_context *ccontext);

       void pcre2_code_free(pcre2_code *code);

       pcre2_match_data	*pcre2_match_data_create(uint32_t ovecsize,
	 pcre2_general_context *gcontext);

       pcre2_match_data	*pcre2_match_data_create_from_pattern(
	 const pcre2_code *code, pcre2_general_context *gcontext);

       int pcre2_match(const pcre2_code	*code, PCRE2_SPTR subject,
	 PCRE2_SIZE length, PCRE2_SIZE startoffset,
	 uint32_t options, pcre2_match_data *match_data,
	 pcre2_match_context *mcontext);

       int pcre2_dfa_match(const pcre2_code *code, PCRE2_SPTR subject,
	 PCRE2_SIZE length, PCRE2_SIZE startoffset,
	 uint32_t options, pcre2_match_data *match_data,
	 pcre2_match_context *mcontext,
	 int *workspace, PCRE2_SIZE wscount);

       void pcre2_match_data_free(pcre2_match_data *match_data);

PCRE2 NATIVE API AUXILIARY MATCH FUNCTIONS

       PCRE2_SPTR pcre2_get_mark(pcre2_match_data *match_data);

       PCRE2_SIZE pcre2_get_match_data_size(pcre2_match_data *match_data);

       PCRE2_SIZE pcre2_get_match_data_heapframes_size(
	 pcre2_match_data *match_data);

       uint32_t	pcre2_get_ovector_count(pcre2_match_data *match_data);

       PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *match_data);

       PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data);

PCRE2 NATIVE API GENERAL CONTEXT FUNCTIONS

       pcre2_general_context *pcre2_general_context_create(
	 void *(*private_malloc)(PCRE2_SIZE, void *),
	 void (*private_free)(void *, void *), void *memory_data);

       pcre2_general_context *pcre2_general_context_copy(
	 pcre2_general_context *gcontext);

       void pcre2_general_context_free(pcre2_general_context *gcontext);

PCRE2 NATIVE API COMPILE CONTEXT FUNCTIONS

       pcre2_compile_context *pcre2_compile_context_create(
	 pcre2_general_context *gcontext);

       pcre2_compile_context *pcre2_compile_context_copy(
	 pcre2_compile_context *ccontext);

       void pcre2_compile_context_free(pcre2_compile_context *ccontext);

       int pcre2_set_bsr(pcre2_compile_context *ccontext,
	 uint32_t value);

       int pcre2_set_character_tables(pcre2_compile_context *ccontext,
	 const uint8_t *tables);

       int pcre2_set_compile_extra_options(pcre2_compile_context *ccontext,
	 uint32_t extra_options);

       int pcre2_set_max_pattern_length(pcre2_compile_context *ccontext,
	 PCRE2_SIZE value);

       int pcre2_set_max_pattern_compiled_length(
	 pcre2_compile_context *ccontext, PCRE2_SIZE value);

       int pcre2_set_max_varlookbehind(pcre2_compile_contest *ccontext,
	 uint32_t value);

       int pcre2_set_newline(pcre2_compile_context *ccontext,
	 uint32_t value);

       int pcre2_set_parens_nest_limit(pcre2_compile_context *ccontext,
	 uint32_t value);

       int pcre2_set_compile_recursion_guard(pcre2_compile_context *ccontext,
	 int (*guard_function)(uint32_t, void *), void *user_data);

       int pcre2_set_optimize(pcre2_compile_context *ccontext,
	 uint32_t directive);

PCRE2 NATIVE API MATCH CONTEXT FUNCTIONS

       pcre2_match_context *pcre2_match_context_create(
	 pcre2_general_context *gcontext);

       pcre2_match_context *pcre2_match_context_copy(
	 pcre2_match_context *mcontext);

       void pcre2_match_context_free(pcre2_match_context *mcontext);

       int pcre2_set_callout(pcre2_match_context *mcontext,
	 int (*callout_function)(pcre2_callout_block *,	void *),
	 void *callout_data);

       int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
	 int (*callout_function)(pcre2_substitute_callout_block	*, void	*),
	 void *callout_data);

       int pcre2_set_substitute_case_callout(pcre2_match_context *mcontext,
	 PCRE2_SIZE (*callout_function)(PCRE2_SPTR, PCRE2_SIZE,
					PCRE2_UCHAR *, PCRE2_SIZE,
					int, void *),
	 void *callout_data);

       int pcre2_set_offset_limit(pcre2_match_context *mcontext,
	 PCRE2_SIZE value);

       int pcre2_set_heap_limit(pcre2_match_context *mcontext,
	 uint32_t value);

       int pcre2_set_match_limit(pcre2_match_context *mcontext,
	 uint32_t value);

       int pcre2_set_depth_limit(pcre2_match_context *mcontext,
	 uint32_t value);

PCRE2 NATIVE API STRING	EXTRACTION FUNCTIONS

       int pcre2_substring_copy_byname(pcre2_match_data	*match_data,
	 PCRE2_SPTR name, PCRE2_UCHAR *buffer, PCRE2_SIZE *bufflen);

       int pcre2_substring_copy_bynumber(pcre2_match_data *match_data,
	 uint32_t number, PCRE2_UCHAR *buffer,
	 PCRE2_SIZE *bufflen);

       void pcre2_substring_free(PCRE2_UCHAR *buffer);

       int pcre2_substring_get_byname(pcre2_match_data *match_data,
	 PCRE2_SPTR name, PCRE2_UCHAR **bufferptr, PCRE2_SIZE *bufflen);

       int pcre2_substring_get_bynumber(pcre2_match_data *match_data,
	 uint32_t number, PCRE2_UCHAR **bufferptr,
	 PCRE2_SIZE *bufflen);

       int pcre2_substring_length_byname(pcre2_match_data *match_data,
	 PCRE2_SPTR name, PCRE2_SIZE *length);

       int pcre2_substring_length_bynumber(pcre2_match_data *match_data,
	 uint32_t number, PCRE2_SIZE *length);

       int pcre2_substring_nametable_scan(const	pcre2_code *code,
	 PCRE2_SPTR name, PCRE2_SPTR *first, PCRE2_SPTR	*last);

       int pcre2_substring_number_from_name(const pcre2_code *code,
	 PCRE2_SPTR name);

       void pcre2_substring_list_free(PCRE2_UCHAR **list);

       int pcre2_substring_list_get(pcre2_match_data *match_data,
	 PCRE2_UCHAR ***listptr, PCRE2_SIZE **lengthsptr);

PCRE2 NATIVE API STRING	SUBSTITUTION FUNCTION

       int pcre2_substitute(const pcre2_code *code, PCRE2_SPTR subject,
	 PCRE2_SIZE length, PCRE2_SIZE startoffset,
	 uint32_t options, pcre2_match_data *match_data,
	 pcre2_match_context *mcontext,	PCRE2_SPTR replacementz,
	 PCRE2_SIZE rlength, PCRE2_UCHAR *outputbuffer,
	 PCRE2_SIZE *outlengthptr);

PCRE2 NATIVE API JIT FUNCTIONS

       int pcre2_jit_compile(pcre2_code	*code, uint32_t	options);

       int pcre2_jit_match(const pcre2_code *code, PCRE2_SPTR subject,
	 PCRE2_SIZE length, PCRE2_SIZE startoffset,
	 uint32_t options, pcre2_match_data *match_data,
	 pcre2_match_context *mcontext);

       void pcre2_jit_free_unused_memory(pcre2_general_context *gcontext);

       pcre2_jit_stack *pcre2_jit_stack_create(size_t startsize,
	 size_t	maxsize, pcre2_general_context *gcontext);

       void pcre2_jit_stack_assign(pcre2_match_context *mcontext,
	 pcre2_jit_callback callback_function, void *callback_data);

       void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack);

PCRE2 NATIVE API SERIALIZATION FUNCTIONS

       int32_t pcre2_serialize_decode(pcre2_code **codes,
	 int32_t number_of_codes, const	uint8_t	*bytes,
	 pcre2_general_context *gcontext);

       int32_t pcre2_serialize_encode(const pcre2_code **codes,
	 int32_t number_of_codes, uint8_t **serialized_bytes,
	 PCRE2_SIZE *serialized_size, pcre2_general_context *gcontext);

       void pcre2_serialize_free(uint8_t *bytes);

       int32_t pcre2_serialize_get_number_of_codes(const uint8_t *bytes);

PCRE2 NATIVE API AUXILIARY FUNCTIONS

       pcre2_code *pcre2_code_copy(const pcre2_code *code);

       pcre2_code *pcre2_code_copy_with_tables(const pcre2_code	*code);

       int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer,
	 PCRE2_SIZE bufflen);

       const uint8_t *pcre2_maketables(pcre2_general_context *gcontext);

       void pcre2_maketables_free(pcre2_general_context	*gcontext,
	 const uint8_t *tables);

       int pcre2_pattern_info(const pcre2_code *code, uint32_t what,
	 void *where);

       int pcre2_callout_enumerate(const pcre2_code *code,
	 int (*callback)(pcre2_callout_enumerate_block *, void *),
	 void *user_data);

       int pcre2_config(uint32_t what, void *where);

PCRE2 NATIVE API OBSOLETE FUNCTIONS

       int pcre2_set_recursion_limit(pcre2_match_context *mcontext,
	 uint32_t value);

       int pcre2_set_recursion_memory_management(
	 pcre2_match_context *mcontext,
	 void *(*private_malloc)(size_t, void *),
	 void (*private_free)(void *, void *), void *memory_data);

       These functions became obsolete at release 10.30	and are	retained  only
       for  backward  compatibility.  They should not be used in new code. The
       first is	replaced by pcre2_set_depth_limit(); the second	is  no	longer
       needed and has no effect	(it always returns zero).

PCRE2 EXPERIMENTAL PATTERN CONVERSION FUNCTIONS

       pcre2_convert_context *pcre2_convert_context_create(
	 pcre2_general_context *gcontext);

       pcre2_convert_context *pcre2_convert_context_copy(
	 pcre2_convert_context *cvcontext);

       void pcre2_convert_context_free(pcre2_convert_context *cvcontext);

       int pcre2_set_glob_escape(pcre2_convert_context *cvcontext,
	 uint32_t escape_char);

       int pcre2_set_glob_separator(pcre2_convert_context *cvcontext,
	 uint32_t separator_char);

       int pcre2_pattern_convert(PCRE2_SPTR pattern, PCRE2_SIZE	length,
	 uint32_t options, PCRE2_UCHAR **buffer,
	 PCRE2_SIZE *blength, pcre2_convert_context *cvcontext);

       void pcre2_converted_pattern_free(PCRE2_UCHAR *converted_pattern);

       These  functions	 provide  a  way of converting non-PCRE2 patterns into
       patterns	that can be processed by pcre2_compile(). This facility	is ex-
       perimental and may be changed in	future releases. At  present,  "globs"
       and  POSIX  basic  and  extended	patterns can be	converted. Details are
       given in	the pcre2convert documentation.

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

       There are three PCRE2 libraries,	supporting 8-bit, 16-bit,  and	32-bit
       code  units,  respectively.  However,  there  is	 just one header file,
       pcre2.h.	 This contains the function prototypes and  other  definitions
       for all three libraries.	One, two, or all three can be installed	simul-
       taneously.  On  Unix-like  systems the libraries	are called libpcre2-8,
       libpcre2-16, and	libpcre2-32, and they can also co-exist	with the orig-
       inal PCRE libraries.  Every PCRE2 function  comes  in  three  different
       forms, one for each library, for	example:

	 pcre2_compile_8()
	 pcre2_compile_16()
	 pcre2_compile_32()

       There are also three different sets of data types:

	 PCRE2_UCHAR8, PCRE2_UCHAR16, PCRE2_UCHAR32
	 PCRE2_SPTR8,  PCRE2_SPTR16,  PCRE2_SPTR32

       The  UCHAR  types define	unsigned code units of the appropriate widths.
       For example, PCRE2_UCHAR16 is usually defined as	`uint16_t'.  The  SPTR
       types are pointers to constants of the equivalent UCHAR types, that is,
       they are	pointers to vectors of unsigned	code units.

       Character  strings  are	passed	to a PCRE2 library as sequences	of un-
       signed integers in code units of	the appropriate	width. The length of a
       string may be given as a	number of code units, or  the  string  may  be
       specified as zero-terminated.

       Many  applications use only one code unit width.	For their convenience,
       macros are defined whose	names are the generic forms such as pcre2_com-
       pile() and  PCRE2_SPTR.	These  macros  use  the	 value	of  the	 macro
       PCRE2_CODE_UNIT_WIDTH  to generate the appropriate width-specific func-
       tion and	macro names.  PCRE2_CODE_UNIT_WIDTH is not defined by default.
       An application must define it to	be  8,	16,  or	 32  before  including
       pcre2.h in order	to make	use of the generic names.

       Applications  that use more than	one code unit width can	be linked with
       more than one PCRE2 library, but	must define  PCRE2_CODE_UNIT_WIDTH  to
       be  0  before  including	pcre2.h, and then use the real function	names.
       Any code	that is	to be included in an environment where	the  value  of
       PCRE2_CODE_UNIT_WIDTH  is  unknown  should  also	 use the real function
       names. (Unfortunately, it is not	possible in C code to save and restore
       the value of a macro.)

       If PCRE2_CODE_UNIT_WIDTH	is not defined	before	including  pcre2.h,  a
       compiler	error occurs.

       When  using  multiple  libraries	 in an application, you	must take care
       when processing any particular pattern to use  only  functions  from  a
       single  library.	  For example, if you want to run a match using	a pat-
       tern that was compiled with pcre2_compile_16(), you  must  do  so  with
       pcre2_match_16(), not pcre2_match_8() or	pcre2_match_32().

       In  the	function summaries above, and in the rest of this document and
       other PCRE2 documents, functions	and data  types	 are  described	 using
       their generic names, without the	_8, _16, or _32	suffix.

PCRE2 API OVERVIEW

       PCRE2  has  its	own  native  API, which	is described in	this document.
       There are also some wrapper functions for the 8-bit library that	corre-
       spond to	the POSIX regular expression API, but they do not give	access
       to  all	the  functionality of PCRE2 and	they are not thread-safe. They
       are described in	the pcre2posix documentation. Both these APIs define a
       set of C	function calls.

       The native API C	data types, function prototypes,  option  values,  and
       error codes are defined in the header file pcre2.h, which also contains
       definitions of PCRE2_MAJOR and PCRE2_MINOR, the major and minor release
       numbers	for the	library. Applications can use these to include support
       for different releases of PCRE2.

       In a Windows environment, if you	want to	statically link	an application
       program against a non-dll PCRE2 library,	you must  define  PCRE2_STATIC
       before including	pcre2.h.

       The  functions pcre2_compile() and pcre2_match()	are used for compiling
       and matching regular expressions	in a Perl-compatible manner. A	sample
       program that demonstrates the simplest way of using them	is provided in
       the file	called pcre2demo.c in the PCRE2	source distribution. A listing
       of  this	 program  is  given  in	 the  pcre2demo	documentation, and the
       pcre2sample documentation describes how to compile and run it.

       The compiling and matching functions recognize various options that are
       passed as bits in an options argument. There are	also some more compli-
       cated parameters	such as	custom memory  management  functions  and  re-
       source  limits  that  are  passed  in "contexts"	(which are just	memory
       blocks, described below). Simple	applications do	not need to  make  use
       of contexts.

       Just-in-time  (JIT)  compiler  support  is an optional feature of PCRE2
       that can	be built in  appropriate  hardware  environments.  It  greatly
       speeds  up  the matching	performance of many patterns. Programs can re-
       quest that it be	used if	available by calling pcre2_jit_compile() after
       a pattern has been successfully compiled	by pcre2_compile(). This  does
       nothing if JIT support is not available.

       More  complicated  programs  might  need	 to make use of	the specialist
       functions   pcre2_jit_stack_create(),	pcre2_jit_stack_free(),	   and
       pcre2_jit_stack_assign()	 in order to control the JIT code's memory us-
       age.

       JIT matching is automatically used by pcre2_match() if it is available,
       unless the PCRE2_NO_JIT option is set. There is also a direct interface
       for JIT matching, which gives improved performance at  the  expense  of
       less  sanity  checking. The JIT-specific	functions are discussed	in the
       pcre2jit	documentation.

       A second	matching function, pcre2_dfa_match(), which is	not  Perl-com-
       patible,	 is  also  provided.  This  uses a different algorithm for the
       matching. The alternative algorithm finds all possible  matches	(at  a
       given  point  in	 the subject), and scans the subject just once (unless
       there are lookaround assertions). However, this algorithm does not  re-
       turn  captured substrings. A description	of the two matching algorithms
       and their advantages and	disadvantages is given	in  the	 pcre2matching
       documentation. There is no JIT support for pcre2_dfa_match().

       In  addition  to	 the  main compiling and matching functions, there are
       convenience functions for extracting captured substrings	from a subject
       string that has been matched by pcre2_match(). They are:

	 pcre2_substring_copy_byname()
	 pcre2_substring_copy_bynumber()
	 pcre2_substring_get_byname()
	 pcre2_substring_get_bynumber()
	 pcre2_substring_list_get()
	 pcre2_substring_length_byname()
	 pcre2_substring_length_bynumber()
	 pcre2_substring_nametable_scan()
	 pcre2_substring_number_from_name()

       pcre2_substring_free() and pcre2_substring_list_free()  are  also  pro-
       vided,  to  free	 memory	used for extracted strings. If either of these
       functions is called with	a NULL argument, the function returns  immedi-
       ately without doing anything.

       The  function  pcre2_substitute()  can be called	to match a pattern and
       return a	copy of	the subject string with	substitutions for  parts  that
       were matched.

       Functions  whose	 names begin with pcre2_serialize_ are used for	saving
       compiled	patterns on disc or elsewhere, and reloading them later.

       Finally,	there are functions for	finding	out information	about  a  com-
       piled  pattern  (pcre2_pattern_info()) and about	the configuration with
       which PCRE2 was built (pcre2_config()).

       Functions with names ending with	_free()	are used  for  freeing	memory
       blocks  of  various  sorts.  In all cases, if one of these functions is
       called with a NULL argument, it does nothing.

STRING LENGTHS AND OFFSETS

       The PCRE2 API uses string lengths and  offsets  into  strings  of  code
       units  in  several  places. These values	are always of type PCRE2_SIZE,
       which is	an unsigned integer type, currently always defined as  size_t.
       The  largest  value  that  can  be  stored  in  such  a	type  (that is
       ~(PCRE2_SIZE)0) is reserved as a	special	indicator for  zero-terminated
       strings	and  unset offsets.  Therefore,	the longest string that	can be
       handled is one less than	this maximum. Note that	string lengths are al-
       ways given in code units. Only in the 8-bit library is  such  a	length
       the same	as the number of bytes in the string.

NEWLINES

       PCRE2 supports five different conventions for indicating	line breaks in
       strings:	 a  single  CR (carriage return) character, a single LF	(line-
       feed) character,	the two-character sequence CRLF, any of	the three pre-
       ceding, or any Unicode newline sequence.	The Unicode newline  sequences
       are  the	 three just mentioned, plus the	single characters VT (vertical
       tab, U+000B), FF	(form feed, U+000C), NEL (next line, U+0085), LS (line
       separator, U+2028), and PS (paragraph separator,	U+2029).

       Each of the first three conventions is used by at least	one  operating
       system as its standard newline sequence.	When PCRE2 is built, a default
       can be specified.  If it	is not,	the default is set to LF, which	is the
       Unix standard. However, the newline convention can be changed by	an ap-
       plication  when calling pcre2_compile(),	or it can be specified by spe-
       cial text at the	start of the pattern itself; this overrides any	 other
       settings.  See the pcre2pattern page for	details	of the special charac-
       ter sequences.

       In the PCRE2 documentation the word "newline"  is  used	to  mean  "the
       character or pair of characters that indicate a line break". The	choice
       of  newline convention affects the handling of the dot, circumflex, and
       dollar metacharacters, the handling of #-comments in /x mode, and, when
       CRLF is a recognized line ending	sequence, the match position  advance-
       ment for	a non-anchored pattern.	There is more detail about this	in the
       section on pcre2_match()	options	below.

       The  choice of newline convention does not affect the interpretation of
       the \n or \r escape sequences, nor does it affect what \R matches; this
       has its own separate convention.

MULTITHREADING

       In a multithreaded application it is important to keep  thread-specific
       data  separate  from data that can be shared between threads. The PCRE2
       library code itself is thread-safe: it contains	no  static  or	global
       variables. The API is designed to be fairly simple for non-threaded ap-
       plications  while at the	same time ensuring that	multithreaded applica-
       tions can use it.

       There are several different blocks of data that are used	to pass	infor-
       mation between the application and the PCRE2 libraries.

   The compiled	pattern

       A pointer to the	compiled form of a pattern is  returned	 to  the  user
       when pcre2_compile() is successful. The data in the compiled pattern is
       fixed,  and  does not change when the pattern is	matched. Therefore, it
       is thread-safe, that is,	the same compiled pattern can be used by  more
       than one	thread simultaneously. For example, an application can compile
       all its patterns	at the start, before forking off multiple threads that
       use  them.  However,  if	the just-in-time (JIT) optimization feature is
       being used, it needs separate memory stack areas	for each  thread.  See
       the pcre2jit documentation for more details.

       In  a more complicated situation, where patterns	are compiled only when
       they are	first needed, but are still shared between  threads,  pointers
       to  compiled  patterns  must  be	protected from simultaneous writing by
       multiple	threads. This is somewhat tricky to do correctly. If you  know
       that  writing  to  a pointer is atomic in your environment, you can use
       logic like this:

	 Get a read-only (shared) lock (mutex) for pointer
	 if (pointer ==	NULL)
	   {
	   Get a write (unique)	lock for pointer
	   if (pointer == NULL)	pointer	= pcre2_compile(...
	   }
	 Release the lock
	 Use pointer in	pcre2_match()

       Of course, testing for compilation errors should	also  be  included  in
       the code.

       The  reason  for	checking the pointer a second time is as follows: Sev-
       eral threads may	have acquired the shared lock and tested  the  pointer
       for being NULL, but only	one of them will be given the write lock, with
       the  rest kept waiting. The winning thread will compile the pattern and
       store the result.  After	this thread releases the write	lock,  another
       thread  will  get it, and if it does not	retest pointer for being NULL,
       will recompile the pattern and overwrite	the pointer, creating a	memory
       leak and	possibly causing other issues.

       In an environment where writing to a pointer may	 not  be  atomic,  the
       above  logic  is	not sufficient.	The thread that	is doing the compiling
       may be descheduled after	writing	only part of the pointer, which	 could
       cause  other  threads  to use an	invalid	value. Instead of checking the
       pointer itself, a separate "pointer is valid" flag (that	can be updated
       atomically) must	be used:

	 Get a read-only (shared) lock (mutex) for pointer
	 if (!pointer_is_valid)
	   {
	   Get a write (unique)	lock for pointer
	   if (!pointer_is_valid)
	     {
	     pointer = pcre2_compile(...
	     pointer_is_valid =	TRUE
	     }
	   }
	 Release the lock
	 Use pointer in	pcre2_match()

       If JIT is being used, but the JIT compilation is	not being done immedi-
       ately (perhaps waiting to see if	the pattern  is	 used  often  enough),
       similar	logic  is required. JIT	compilation updates a value within the
       compiled	code block, so a thread	must gain unique write access  to  the
       pointer	   before    calling	pcre2_jit_compile().	Alternatively,
       pcre2_code_copy() or pcre2_code_copy_with_tables() can be used  to  ob-
       tain  a	private	 copy of the compiled code before calling the JIT com-
       piler.

   Context blocks

       The next	main section below introduces the idea of "contexts" in	 which
       PCRE2 functions are called. A context is	nothing	more than a collection
       of parameters that control the way PCRE2	operates. Grouping a number of
       parameters together in a	context	is a convenient	way of passing them to
       a  PCRE2	 function without using	lots of	arguments. The parameters that
       are stored in contexts are in some sense	 "advanced  features"  of  the
       API. Many straightforward applications will not need to use contexts.

       In a multithreaded application, if the parameters in a context are val-
       ues  that  are  never  changed, the same	context	can be used by all the
       threads.	However, if any	thread needs to	change any value in a context,
       it must make its	own thread-specific copy.

   Match blocks

       The matching functions need a block of memory for storing  the  results
       of a match. This	includes details of what was matched, as well as addi-
       tional  information  such as the	name of	a (*MARK) setting. Each	thread
       must provide its	own copy of this memory.

PCRE2 CONTEXTS

       Some PCRE2 functions have a lot of parameters, many of which  are  used
       only  by	 specialist  applications,  for	example, those that use	custom
       memory management or non-standard character tables.  To	keep  function
       argument	 lists	at a reasonable	size, and at the same time to keep the
       API extensible, "uncommon" parameters are passed	to  certain  functions
       in  a  context instead of directly. A context is	just a block of	memory
       that holds the parameter	values.	 Applications that do not need to  ad-
       just any	of the context parameters can pass NULL	when a context pointer
       is required.

       There  are  three different types of context: a general context that is
       relevant	for several PCRE2 operations, a	compile-time  context,	and  a
       match-time context.

   The general context

       At  present,  this context just contains	pointers to (and data for) ex-
       ternal memory management	functions that are called from several	places
       in  the	PCRE2  library.	 The  context  is  named `general' rather than
       specifically `memory' because in	future other fields may	be  added.  If
       you  do not want	to supply your own custom memory management functions,
       you do not need to bother with a	general	context. A general context  is
       created by:

       pcre2_general_context *pcre2_general_context_create(
	 void *(*private_malloc)(PCRE2_SIZE, void *),
	 void (*private_free)(void *, void *), void *memory_data);

       The  two	 function pointers specify custom memory management functions,
       whose prototypes	are:

	 void *private_malloc(PCRE2_SIZE, void *);
	 void  private_free(void *, void *);

       Whenever	code in	PCRE2 calls these functions, the final argument	is the
       value of	memory_data. Either of the first two arguments of the creation
       function	may be NULL, in	which case the system memory management	 func-
       tions  malloc()	and free() are used. (This is not currently useful, as
       there are no other fields in a general context,	but  in	 future	 there
       might  be.)  The	private_malloc() function is used (if supplied)	to ob-
       tain memory for storing the context, and	all three values are saved  as
       part of the context.

       Whenever	 PCRE2	creates	a data block of	any kind, the block contains a
       pointer to the free() function that matches the malloc()	function  that
       was  used.  When	 the  time  comes  to free the block, this function is
       called.

       A general context can be	copied by calling:

       pcre2_general_context *pcre2_general_context_copy(
	 pcre2_general_context *gcontext);

       The memory used for a general context should be freed by	calling:

       void pcre2_general_context_free(pcre2_general_context *gcontext);

       If this function	is passed a  NULL  argument,  it  returns  immediately
       without doing anything.

   The compile context

       A  compile context is required if you want to provide an	external func-
       tion for	stack checking during compilation or  to  change  the  default
       values of any of	the following compile-time parameters:

	 What \R matches (Unicode newlines or CR, LF, CRLF only)
	 PCRE2's character tables
	 The newline character sequence
	 The compile time nested parentheses limit
	 The maximum length of the pattern string
	 The extra options bits	(none set by default)
	 Which performance optimizations the compiler should apply

       A  compile context is also required if you are using custom memory man-
       agement.	 If none of these apply, just pass NULL	as the	context	 argu-
       ment of pcre2_compile().

       A  compile context is created, copied, and freed	by the following func-
       tions:

       pcre2_compile_context *pcre2_compile_context_create(
	 pcre2_general_context *gcontext);

       pcre2_compile_context *pcre2_compile_context_copy(
	 pcre2_compile_context *ccontext);

       void pcre2_compile_context_free(pcre2_compile_context *ccontext);

       A compile context is created with default values	 for  its  parameters.
       These can be changed by calling the following functions,	which return 0
       on success, or PCRE2_ERROR_BADDATA if invalid data is detected.

       int pcre2_set_bsr(pcre2_compile_context *ccontext,
	 uint32_t value);

       The  value  must	 be PCRE2_BSR_ANYCRLF, to specify that \R matches only
       CR, LF, or CRLF,	or PCRE2_BSR_UNICODE, to specify that \R  matches  any
       Unicode line ending sequence. The value is used by the JIT compiler and
       by   the	  two	interpreted   matching	functions,  pcre2_match()  and
       pcre2_dfa_match().

       int pcre2_set_character_tables(pcre2_compile_context *ccontext,
	 const uint8_t *tables);

       The value must be the result of a  call	to  pcre2_maketables(),	 whose
       only argument is	a general context. This	function builds	a set of char-
       acter tables in the current locale.

       int pcre2_set_compile_extra_options(pcre2_compile_context *ccontext,
	 uint32_t extra_options);

       As  PCRE2  has developed, almost	all the	32 option bits that are	avail-
       able in the options argument of pcre2_compile() have been used  up.  To
       avoid  running  out, the	compile	context	contains a set of extra	option
       bits which are used for some newer, assumed rarer, options. This	 func-
       tion  sets  those bits. It always sets all the bits (either on or off).
       It does not modify any existing setting.	The available options are  de-
       fined in	the section entitled "Extra compile options" below.

       int pcre2_set_max_pattern_length(pcre2_compile_context *ccontext,
	 PCRE2_SIZE value);

       This  sets a maximum length, in code units, for any pattern string that
       is compiled with	this context. If the pattern is	longer,	 an  error  is
       generated.   This facility is provided so that applications that	accept
       patterns	from external sources can limit	their size. The	default	is the
       largest number that a PCRE2_SIZE	variable can  hold,  which  is	effec-
       tively unlimited.

       int pcre2_set_max_pattern_compiled_length(
	 pcre2_compile_context *ccontext, PCRE2_SIZE value);

       This  sets  a maximum size, in bytes, for the memory needed to hold the
       compiled	version	of a pattern that is compiled with  this  context.  If
       the  pattern needs more memory, an error	is generated. This facility is
       provided	so  that  applications	that  accept  patterns	from  external
       sources	can  limit  the	 amount	of memory they use. The	default	is the
       largest number that a PCRE2_SIZE	variable can  hold,  which  is	effec-
       tively unlimited.

       int pcre2_set_max_varlookbehind(pcre2_compile_contest *ccontext,
	 uint32_t value);

       This  sets  a  maximum length for the number of characters matched by a
       variable-length lookbehind assertion. The default is set	when PCRE2  is
       built,  with  the ultimate default being	255, the same as Perl. Lookbe-
       hind assertions without a bounding length are not supported.

       int pcre2_set_newline(pcre2_compile_context *ccontext,
	 uint32_t value);

       This specifies which characters or character sequences are to be	recog-
       nized as	newlines. The value must be one	of PCRE2_NEWLINE_CR  (carriage
       return only), PCRE2_NEWLINE_LF (linefeed	only), PCRE2_NEWLINE_CRLF (the
       two-character  sequence	CR followed by LF), PCRE2_NEWLINE_ANYCRLF (any
       of the above), PCRE2_NEWLINE_ANY	(any  Unicode  newline	sequence),  or
       PCRE2_NEWLINE_NUL (the NUL character, that is a binary zero).

       A pattern can override the value	set in the compile context by starting
       with a sequence such as (*CRLF).	See the	pcre2pattern page for details.

       When  a	pattern	 is  compiled  with  the  PCRE2_EXTENDED  or PCRE2_EX-
       TENDED_MORE option, the newline convention affects the  recognition  of
       the  end	 of internal comments starting with #. The value is saved with
       the compiled pattern for	subsequent use by the JIT compiler and by  the
       two     interpreted     matching	    functions,	  pcre2_match()	   and
       pcre2_dfa_match().

       int pcre2_set_parens_nest_limit(pcre2_compile_context *ccontext,
	 uint32_t value);

       This parameter adjusts the limit, set  when  PCRE2  is  built  (default
       250),  on  the  depth  of  parenthesis nesting in a pattern. This limit
       stops rogue patterns using up too much system  stack  when  being  com-
       piled.  The limit applies to parentheses	of all kinds, not just captur-
       ing parentheses.

       int pcre2_set_compile_recursion_guard(pcre2_compile_context *ccontext,
	 int (*guard_function)(uint32_t, void *), void *user_data);

       There is	at least one application that runs PCRE2 in threads with  very
       limited	system	stack,	where running out of stack is to be avoided at
       all costs. The parenthesis limit	above cannot take account of how  much
       stack  is  actually  available during compilation. For a	finer control,
       you can supply a	 function  that	 is  called  whenever  pcre2_compile()
       starts  to compile a parenthesized part of a pattern. This function can
       check the actual	stack size (or anything	else  that  it	wants  to,  of
       course).

       The  first  argument to the callout function gives the current depth of
       nesting,	and the	second is user data that is set	up by the  last	 argu-
       ment   of  pcre2_set_compile_recursion_guard().	The  callout  function
       should return zero if all is well, or non-zero to force an error.

       int pcre2_set_optimize(pcre2_compile_context *ccontext,
	 uint32_t directive);

       PCRE2 can apply various performance optimizations  during  compilation,
       in  order to make matching faster. For example, the compiler might con-
       vert  some  regex  constructs  into  an	equivalent   construct	 which
       pcre2_match()  can  execute faster. By default, all available optimiza-
       tions are enabled. However, in rare cases, one might  wish  to  disable
       specific	optimizations. For example, if it is known that	some optimiza-
       tions  cannot benefit a certain regex, it might be desirable to disable
       them, in	order to speed up compilation.

       The permitted values of directive are as	follows:

	 PCRE2_OPTIMIZATION_FULL

       Enable all optional performance	optimizations.	This  is  the  default
       value.

	 PCRE2_OPTIMIZATION_NONE

       Disable all optional performance	optimizations.

	 PCRE2_AUTO_POSSESS
	 PCRE2_AUTO_POSSESS_OFF

       Enable/disable  "auto-possessification" of variable quantifiers such as
       * and +.	 This optimization, for	example, turns a+b into	a++b in	 order
       to  avoid  backtracks into a+ that can never be successful. However, if
       callouts	are in use, auto-possessification means	that some callouts are
       never taken. You	can disable this optimization if you want the matching
       functions to do a full, unoptimized search and run all the callouts.

	 PCRE2_DOTSTAR_ANCHOR
	 PCRE2_DOTSTAR_ANCHOR_OFF

       Enable/disable an optimization that is applied when  .*	is  the	 first
       significant  item in a top-level	branch of a pattern, and all the other
       branches	also start with	.* or with \A or \G or ^. Such	a  pattern  is
       automatically  anchored if PCRE2_DOTALL is set for all the .* items and
       PCRE2_MULTILINE is not set for any ^ items. Otherwise,  the  fact  that
       any  match must start either at the start of the	subject	or following a
       newline is remembered. Like other optimizations,	this can  cause	 call-
       outs to be skipped.

       Dotstar	anchor	optimization is	automatically disabled for .* if it is
       inside an atomic	group or a capture group that  is  the	subject	 of  a
       backreference, or if the	pattern	contains (*PRUNE) or (*SKIP).

	 PCRE2_START_OPTIMIZE
	 PCRE2_START_OPTIMIZE_OFF

       Enable/disable optimizations which cause	matching functions to scan the
       subject string for specific code	unit values before attempting a	match.
       For  example, if	it is known that an unanchored match must start	with a
       specific	value, the matching code searches the subject for that	value,
       and  fails  immediately	if it cannot find it, without actually running
       the main	matching function. This	means that  a  special	item  such  as
       (*COMMIT)  at  the  start  of a pattern is not considered until after a
       suitable	starting point for the match has been found.  Also, when call-
       outs or (*MARK) items are in use, these	"start-up"  optimizations  can
       cause  them  to	be  skipped if the pattern is never actually used. The
       start-up	optimizations are in effect a pre-scan	of  the	 subject  that
       takes place before the pattern is run.

       Disabling start-up optimizations	ensures	that in	cases where the	result
       is  "no match", the callouts do occur, and that items such as (*COMMIT)
       and (*MARK) are considered at every possible starting position  in  the
       subject string.

       Disabling  start-up  optimizations may change the outcome of a matching
       operation.  Consider the	pattern

	 (*COMMIT)ABC

       When this is compiled, PCRE2 records the	fact that a match  must	 start
       with  the  character  "A".  Suppose the subject string is "DEFABC". The
       start-up	optimization scans along the subject, finds "A"	and  runs  the
       first  match attempt from there.	The (*COMMIT) item means that the pat-
       tern must match the current starting position, which in this  case,  it
       does. However, if the same match	is run without start-up	optimizations,
       the  initial  scan  along the subject string does not happen. The first
       match attempt is	run starting from "D" and when this  fails,  (*COMMIT)
       prevents	 any further matches being tried, so the overall result	is "no
       match".

       Another start-up	optimization makes use	of  a  minimum	length	for  a
       matching	subject, which is recorded when	possible. Consider the pattern

	 (*MARK:1)B(*MARK:2)(X|Y)

       The  minimum  length  for  a match is two characters. If	the subject is
       "XXBB", the "starting character"	optimization skips "XX", then tries to
       match "BB", which is long enough. In the	process, (*MARK:2) is  encoun-
       tered  and  remembered.	When  the match	attempt	fails, the next	"B" is
       found, but there	is only	one character left, so there are no  more  at-
       tempts,	and  "no  match"  is returned with the "last mark seen"	set to
       "2". Without start-up optimizations,  however,  matches	are  tried  at
       every  possible starting	position, including at the end of the subject,
       where (*MARK:1) is encountered, but there is no "B", so the "last  mark
       seen"  that  is returned	is "1".	In this	case, the optimizations	do not
       affect the overall match	result,	which is still "no match", but they do
       affect the auxiliary information	that is	returned.

   The match context

       A match context is required if you want to:

	 Set up	a callout function
	 Set an	offset limit for matching an unanchored	pattern
	 Change	the limit on the amount	of heap	used when matching
	 Change	the backtracking match limit
	 Change	the backtracking depth limit
	 Set custom memory management specifically for the match

       If none of these	apply, just pass  NULL	as  the	 context  argument  of
       pcre2_match(), pcre2_dfa_match(), or pcre2_jit_match().

       A  match	 context  is created, copied, and freed	by the following func-
       tions:

       pcre2_match_context *pcre2_match_context_create(
	 pcre2_general_context *gcontext);

       pcre2_match_context *pcre2_match_context_copy(
	 pcre2_match_context *mcontext);

       void pcre2_match_context_free(pcre2_match_context *mcontext);

       A match context is created with	default	 values	 for  its  parameters.
       These can be changed by calling the following functions,	which return 0
       on success, or PCRE2_ERROR_BADDATA if invalid data is detected.

       int pcre2_set_callout(pcre2_match_context *mcontext,
	 int (*callout_function)(pcre2_callout_block *,	void *),
	 void *callout_data);

       This  sets  up a	callout	function for PCRE2 to call at specified	points
       during a	matching operation. Details are	given in the pcre2callout doc-
       umentation.

       int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
	 int (*callout_function)(pcre2_substitute_callout_block	*, void	*),
	 void *callout_data);

       This sets up a callout function for PCRE2 to call after each  substitu-
       tion made by pcre2_substitute().	Details	are given in the section enti-
       tled "Creating a	new string with	substitutions" below.

       int pcre2_set_substitute_case_callout(pcre2_match_context *mcontext,
	 PCRE2_SIZE (*callout_function)(PCRE2_SPTR, PCRE2_SIZE,
					PCRE2_UCHAR *, PCRE2_SIZE,
					int, void *),
	 void *callout_data);

       This  sets up a callout function	for PCRE2 to call when performing case
       transformations inside pcre2_substitute(). Details  are	given  in  the
       section entitled	"Creating a new	string with substitutions" below.

       int pcre2_set_offset_limit(pcre2_match_context *mcontext,
	 PCRE2_SIZE value);

       The  offset_limit parameter limits how far an unanchored	search can ad-
       vance in	the subject string. The	 default  value	 is  PCRE2_UNSET.  The
       pcre2_match()  and  pcre2_dfa_match()  functions	return PCRE2_ERROR_NO-
       MATCH if	a match	with a starting	point before or	at the given offset is
       not found. The pcre2_substitute() function makes	no more	substitutions.

       For example, if the pattern /abc/ is matched against "123abc"  with  an
       offset  limit  less  than 3, the	result is PCRE2_ERROR_NOMATCH. A match
       can never be  found  if	the  startoffset  argument  of	pcre2_match(),
       pcre2_dfa_match(),  or  pcre2_substitute()  is  greater than the	offset
       limit set in the	match context.

       When using this facility, you must set the  PCRE2_USE_OFFSET_LIMIT  op-
       tion when calling pcre2_compile() so that when JIT is in	use, different
       code  can  be  compiled.	If a match is started with a non-default match
       limit when PCRE2_USE_OFFSET_LIMIT is not	set, an	error is generated.

       The offset limit	facility can be	used to	track progress when  searching
       large  subject  strings or to limit the extent of global	substitutions.
       See also	the PCRE2_FIRSTLINE option, which requires a  match  to	 start
       before  or  at  the first newline that follows the start	of matching in
       the subject. If this is set with	an offset limit, a match must occur in
       the first line and also	within	the  offset  limit.  In	 other	words,
       whichever limit comes first is used.

       int pcre2_set_heap_limit(pcre2_match_context *mcontext,
	 uint32_t value);

       The heap_limit parameter	specifies, in units of kibibytes (1024 bytes),
       the  maximum  amount  of	heap memory that pcre2_match() may use to hold
       backtracking information	when running an	interpretive match. This limit
       also applies to pcre2_dfa_match(), which	may use	the heap when process-
       ing patterns with a lot of nested pattern recursion or  lookarounds  or
       atomic groups. This limit does not apply	to matching with the JIT opti-
       mization,  which	 has  its  own	memory	control	 arrangements (see the
       pcre2jit	documentation for more details). If the	limit is reached,  the
       negative	 error	code  PCRE2_ERROR_HEAPLIMIT  is	 returned. The default
       limit can be set	when PCRE2 is built; if	it is not, the default is  set
       very large and is essentially unlimited.

       A value for the heap limit may also be supplied by an item at the start
       of a pattern of the form

	 (*LIMIT_HEAP=ddd)

       where  ddd  is a	decimal	number.	However, such a	setting	is ignored un-
       less ddd	is less	than the limit set by the caller of pcre2_match()  or,
       if no such limit	is set,	less than the default.

       The  pcre2_match() function always needs	some heap memory, so setting a
       value of	zero guarantees	a "heap	limit exceeded"	error. Details of  how
       pcre2_match()  uses  the	 heap are given	in the pcre2perform documenta-
       tion.

       For pcre2_dfa_match(), a	vector on the system stack is used  when  pro-
       cessing	pattern	recursions, lookarounds, or atomic groups, and only if
       this is not big enough is heap memory used. In  this  case,  setting  a
       value of	zero disables the use of the heap.

       int pcre2_set_match_limit(pcre2_match_context *mcontext,
	 uint32_t value);

       The match_limit parameter provides a means of preventing	PCRE2 from us-
       ing  up	too many computing resources when processing patterns that are
       not going to match, but which have a very large number of possibilities
       in their	search trees. The classic  example  is	a  pattern  that  uses
       nested unlimited	repeats.

       There  is an internal counter in	pcre2_match() that is incremented each
       time round its main matching loop. If  this  value  reaches  the	 match
       limit, pcre2_match() returns the	negative value PCRE2_ERROR_MATCHLIMIT.
       This  has  the  effect  of limiting the amount of backtracking that can
       take place. For patterns	that are not anchored, the count restarts from
       zero for	each position in the subject string. This limit	 also  applies
       to pcre2_dfa_match(), though the	counting is done in a different	way.

       When  pcre2_match()  is	called	with  a	 pattern that was successfully
       processed by pcre2_jit_compile(), the way in which matching is executed
       is entirely different. However, there is	still the possibility of  run-
       away matching that goes on for a	very long time,	and so the match_limit
       value  is  also used in this case (but in a different way) to limit how
       long the	matching can continue.

       The default value for the limit can be set when PCRE2 is	built; the de-
       fault is	10 million, which handles all but the most  extreme  cases.  A
       value  for the match limit may also be supplied by an item at the start
       of a pattern of the form

	 (*LIMIT_MATCH=ddd)

       where ddd is a decimal number. However, such a setting is  ignored  un-
       less  ddd  is less than the limit set by	the caller of pcre2_match() or
       pcre2_dfa_match() or, if	no such	limit is set, less than	the default.

       int pcre2_set_depth_limit(pcre2_match_context *mcontext,
	 uint32_t value);

       This  parameter	limits	 the   depth   of   nested   backtracking   in
       pcre2_match().	Each time a nested backtracking	point is passed, a new
       memory frame is used to remember	the state of matching at  that	point.
       Thus,  this  parameter  indirectly  limits the amount of	memory that is
       used in a match.	However, because the size of each memory frame depends
       on the number of	capturing parentheses, the actual memory limit	varies
       from  pattern to	pattern. This limit was	more useful in versions	before
       10.30, where function recursion was used	for backtracking.

       The depth limit is not relevant,	and is ignored,	when matching is  done
       using JIT compiled code.	However, it is supported by pcre2_dfa_match(),
       which  uses it to limit the depth of nested internal recursive function
       calls that implement atomic groups, lookaround assertions, and  pattern
       recursions. This	limits,	indirectly, the	amount of system stack that is
       used.  It  was  more useful in versions before 10.32, when stack	memory
       was used	for local workspace vectors for	recursive function calls. From
       version 10.32, only local variables are allocated on the	stack  and  as
       each call uses only a few hundred bytes,	even a small stack can support
       quite a lot of recursion.

       If  the depth of	internal recursive function calls is great enough, lo-
       cal workspace vectors are allocated on the heap from version 10.32  on-
       wards,  so  the	depth  limit also indirectly limits the	amount of heap
       memory that is used. A recursive	pattern	such as	/(.(?2))((?1)|)/, when
       matched to a very long string using pcre2_dfa_match(), can use a	 great
       deal  of	memory.	However, it is probably	better to limit	heap usage di-
       rectly by calling pcre2_set_heap_limit().

       The default value for the depth limit can be set	when PCRE2  is	built;
       if  it  is not, the default is set to the same value as the default for
       the  match  limit.   If	the  limit  is	exceeded,   pcre2_match()   or
       pcre2_dfa_match() returns PCRE2_ERROR_DEPTHLIMIT. A value for the depth
       limit  may also be supplied by an item at the start of a	pattern	of the
       form

	 (*LIMIT_DEPTH=ddd)

       where ddd is a decimal number. However, such a setting is  ignored  un-
       less  ddd  is less than the limit set by	the caller of pcre2_match() or
       pcre2_dfa_match() or, if	no such	limit is set, less than	the default.

CHECKING BUILD-TIME OPTIONS

       int pcre2_config(uint32_t what, void *where);

       The function pcre2_config() makes it possible for  a  PCRE2  client  to
       find  the  value	 of  certain  configuration parameters and to discover
       which optional features have been compiled into the PCRE2 library.  The
       pcre2build documentation	has more details about these features.

       The  first  argument  for pcre2_config()	specifies which	information is
       required. The second argument is	a pointer to memory into which the in-
       formation is placed. If NULL is passed, the function returns the	amount
       of memory that is needed	for the	requested information. For calls  that
       return  numerical  values, the value is in bytes; when requesting these
       values, where should point to appropriately aligned memory.  For	 calls
       that  return  strings,  the required length is given in code units, not
       counting	the terminating	zero.

       When requesting information, the	returned value from pcre2_config()  is
       non-negative  on	success, or the	negative error code PCRE2_ERROR_BADOP-
       TION if the value in the	first argument is not recognized. The  follow-
       ing information is available:

	 PCRE2_CONFIG_BSR

       The  output  is a uint32_t integer whose	value indicates	what character
       sequences the \R	 escape	 sequence  matches  by	default.  A  value  of
       PCRE2_BSR_UNICODE  means	 that  \R  matches any Unicode line ending se-
       quence; a value of PCRE2_BSR_ANYCRLF means that \R matches only CR, LF,
       or CRLF.	The default can	be overridden when a pattern is	compiled.

	 PCRE2_CONFIG_COMPILED_WIDTHS

       The output is a uint32_t	integer	whose lower bits indicate  which  code
       unit  widths  were  selected  when PCRE2	was built. The 1-bit indicates
       8-bit support, and the 2-bit and	4-bit indicate 16-bit and 32-bit  sup-
       port, respectively.

	 PCRE2_CONFIG_DEPTHLIMIT

       The  output  is a uint32_t integer that gives the default limit for the
       depth of	nested backtracking in pcre2_match() or	the  depth  of	nested
       recursions,  lookarounds,  and atomic groups in pcre2_dfa_match(). Fur-
       ther details are	given with pcre2_set_depth_limit() above.

	 PCRE2_CONFIG_HEAPLIMIT

       The output is a uint32_t	integer	that gives, in kibibytes, the  default
       limit   for  the	 amount	 of  heap  memory  used	 by  pcre2_match()  or
       pcre2_dfa_match().     Further	  details     are      given	  with
       pcre2_set_heap_limit() above.

	 PCRE2_CONFIG_JIT

       The  output  is	a  uint32_t  integer that is set to one	if support for
       just-in-time compiling is included in the library; otherwise it is  set
       to zero.	Note that having the support in	the library does not guarantee
       that  JIT will be used for any given match, and neither does it guaran-
       tee that	JIT will actually be able to function, because it may  not  be
       able  to	 allocate  executable  memory in some environments. There is a
       special call to pcre2_jit_compile() that	can be used to check this. See
       the pcre2jit documentation for more details.

	 PCRE2_CONFIG_JITTARGET

       The where argument should point to a buffer that	is at  least  48  code
       units  long.  (The  exact  length  required  can	 be  found  by calling
       pcre2_config() with where set to	NULL.) The buffer  is  filled  with  a
       string  that  contains  the  name of the	architecture for which the JIT
       compiler	is configured, for example "x86	32bit  (little	endian	+  un-
       aligned)".  If  JIT  support is not available, PCRE2_ERROR_BADOPTION is
       returned, otherwise the number of code units used is returned. This  is
       the length of the string, plus one unit for the terminating zero.

	 PCRE2_CONFIG_LINKSIZE

       The output is a uint32_t	integer	that contains the number of bytes used
       for  internal  linkage  in  compiled regular expressions. When PCRE2 is
       configured, the value can be set	to 2, 3, or 4, with the	default	 being
       2.  This	is the value that is returned by pcre2_config(). However, when
       the 16-bit library is compiled, a value of 3 is rounded up  to  4,  and
       when  the  32-bit  library  is compiled,	internal linkages always use 4
       bytes, so the configured	value is not relevant.

       The default value of 2 for the 8-bit and	16-bit libraries is sufficient
       for all but the most massive patterns, since it allows the size of  the
       compiled	 pattern  to  be  up  to 65535 code units. Larger values allow
       larger regular expressions to be	compiled by those two  libraries,  but
       at the expense of slower	matching.

	 PCRE2_CONFIG_MATCHLIMIT

       The output is a uint32_t	integer	that gives the default match limit for
       pcre2_match().  Further	details	are given with pcre2_set_match_limit()
       above.

	 PCRE2_CONFIG_NEWLINE

       The output is a uint32_t	integer	 whose	value  specifies  the  default
       character  sequence that	is recognized as meaning "newline". The	values
       are:

	 PCRE2_NEWLINE_CR	Carriage return	(CR)
	 PCRE2_NEWLINE_LF	Linefeed (LF)
	 PCRE2_NEWLINE_CRLF	Carriage return, linefeed (CRLF)
	 PCRE2_NEWLINE_ANY	Any Unicode line ending
	 PCRE2_NEWLINE_ANYCRLF	Any of CR, LF, or CRLF
	 PCRE2_NEWLINE_NUL	The NUL	character (binary zero)

       The default should normally correspond to  the  standard	 sequence  for
       your operating system.

	 PCRE2_CONFIG_NEVER_BACKSLASH_C

       The  output  is	a uint32_t integer that	is set to one if the use of \C
       was permanently disabled	when PCRE2 was built; otherwise	it is  set  to
       zero.

	 PCRE2_CONFIG_PARENSLIMIT

       The  output is a	uint32_t integer that gives the	maximum	depth of nest-
       ing of parentheses (of any kind)	in a pattern. This limit is imposed to
       cap the amount of system	stack used when	a pattern is compiled.	It  is
       specified  when PCRE2 is	built; the default is 250. This	limit does not
       take into account the stack that	may already be used by the calling ap-
       plication.  For	finer  control	over  compilation  stack  usage,   see
       pcre2_set_compile_recursion_guard().

	 PCRE2_CONFIG_STACKRECURSE

       This parameter is obsolete and should not be used in new	code. The out-
       put is a	uint32_t integer that is always	set to zero.

	 PCRE2_CONFIG_TABLES_LENGTH

       The output is a uint32_t	integer	that gives the length of PCRE2's char-
       acter  processing  tables in bytes. For details of these	tables see the
       section on locale support below.

	 PCRE2_CONFIG_UNICODE_VERSION

       The where argument should point to a buffer that	is at  least  24  code
       units  long.  (The  exact  length  required  can	 be  found  by calling
       pcre2_config() with where set to	NULL.)	If  PCRE2  has	been  compiled
       without	Unicode	 support,  the buffer is filled	with the text "Unicode
       not supported". Otherwise, the Unicode  version	string	(for  example,
       "8.0.0")	 is  inserted. The number of code units	used is	returned. This
       is the length of	the string plus	one unit for the terminating zero.

	 PCRE2_CONFIG_UNICODE

       The output is a uint32_t	integer	that is	set to one if Unicode  support
       is  available; otherwise	it is set to zero. Unicode support implies UTF
       support.

	 PCRE2_CONFIG_VERSION

       The where argument should point to a buffer that	is at  least  24  code
       units  long.  (The  exact  length  required  can	 be  found  by calling
       pcre2_config() with where set to	NULL.) The buffer is filled  with  the
       PCRE2 version string, zero-terminated. The number of code units used is
       returned. This is the length of the string plus one unit	for the	termi-
       nating zero.

COMPILING A PATTERN

       pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE	length,
	 uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset,
	 pcre2_compile_context *ccontext);

       void pcre2_code_free(pcre2_code *code);

       pcre2_code *pcre2_code_copy(const pcre2_code *code);

       pcre2_code *pcre2_code_copy_with_tables(const pcre2_code	*code);

       The  pcre2_compile() function compiles a	pattern	into an	internal form.
       The pattern is defined by a pointer to a	string of  code	 units	and  a
       length in code units. If	the pattern is zero-terminated,	the length can
       be  specified  as  PCRE2_ZERO_TERMINATED. A NULL	pattern	pointer	with a
       length of zero is treated as an empty  string  (NULL  with  a  non-zero
       length  causes  an  error  return). The function	returns	a pointer to a
       block of	memory that contains the compiled pattern and related data, or
       NULL if an error	occurred.

       If the compile context argument ccontext	is NULL, memory	for  the  com-
       piled  pattern  is  obtained  by	calling	malloc(). Otherwise, it	is ob-
       tained from the same memory function that was used for the compile con-
       text. The caller	must free the memory by	calling	pcre2_code_free() when
       it is no	longer needed.	If pcre2_code_free() is	called with a NULL ar-
       gument, it returns immediately, without doing anything.

       The function pcre2_code_copy() makes a copy of the compiled code	in new
       memory, using the same memory allocator as was used for	the  original.
       However,	 if  the  code has been	processed by the JIT compiler (see be-
       low), the JIT information cannot	be copied (because it is  position-de-
       pendent).   The	new copy can initially be used only for	non-JIT	match-
       ing, though it can be passed to	pcre2_jit_compile()  if	 required.  If
       pcre2_code_copy() is called with	a NULL argument, it returns NULL.

       The pcre2_code_copy() function provides a way for individual threads in
       a  multithreaded	 application  to acquire a private copy	of shared com-
       piled code.  However, it	does not make a	copy of	the  character	tables
       used  by	 the compiled pattern; the new pattern code points to the same
       tables as the original code.  (See "Locale Support" below  for  details
       of  these  character  tables.) In many applications the same tables are
       used throughout,	so this	behaviour is appropriate. Nevertheless,	 there
       are occasions when a copy of a compiled pattern and the relevant	tables
       are  needed.  The pcre2_code_copy_with_tables() provides	this facility.
       Copies of both the code and the tables are  made,  with	the  new  code
       pointing	 to the	new tables. The	memory for the new tables is automati-
       cally freed when	pcre2_code_free() is called for	the new	 copy  of  the
       compiled	 code.	If pcre2_code_copy_with_tables() is called with	a NULL
       argument, it returns NULL.

       NOTE: When one of the matching functions	is  called,  pointers  to  the
       compiled	pattern	and the	subject	string are set in the match data block
       so  that	 they  can be referenced by the	substring extraction functions
       after a successful match.  After	running	a match, you must not  free  a
       compiled	 pattern or a subject string until after all operations	on the
       match data block	have taken place, unless, in the case of  the  subject
       string,	you  have used the PCRE2_COPY_MATCHED_SUBJECT option, which is
       described in the	section	entitled "Option bits for  pcre2_match()"  be-
       low.

       The  options argument for pcre2_compile() contains various bit settings
       that affect the compilation. It should be zero if none of them are  re-
       quired.	The  available	options	 are described below. Some of them (in
       particular, those that are compatible with Perl,	 but  some  others  as
       well)  can  also	 be set	and unset from within the pattern (see the de-
       tailed description in the pcre2pattern documentation).

       For those options that can be different in different parts of the  pat-
       tern,  the contents of the options argument specifies their settings at
       the start of compilation. The  PCRE2_ANCHORED,  PCRE2_ENDANCHORED,  and
       PCRE2_NO_UTF_CHECK  options  can	be set at the time of matching as well
       as at compile time.

       Some additional options and less	frequently required compile-time para-
       meters (for example, the	newline	setting) can be	provided in a  compile
       context (as described above).

       If errorcode or erroroffset is NULL, pcre2_compile() returns NULL imme-
       diately.	 Otherwise,  the  variables to which these point are set to an
       error code and an offset	(number	of code	units) within the pattern, re-
       spectively, when	pcre2_compile()	returns	NULL because a compilation er-
       ror has occurred.

       There are over 100 positive error codes that pcre2_compile() may	return
       if it finds an error in the pattern. There are also some	negative error
       codes that are used for invalid UTF strings when	validity  checking  is
       in   force.   These   are  the  same  as	 given	by  pcre2_match()  and
       pcre2_dfa_match(), and are described in the pcre2unicode	documentation.
       There is	no separate documentation for the positive  error  codes,  be-
       cause  the  textual  error  messages  that  are obtained	by calling the
       pcre2_get_error_message() function (see "Obtaining a textual error mes-
       sage" below) should be  self-explanatory.  Macro	 names	starting  with
       PCRE2_ERROR_  are defined for both positive and negative	error codes in
       pcre2.h.	When compilation is successful errorcode is  set  to  a	 value
       that  returns  the message "no error" if	passed to pcre2_get_error_mes-
       sage().

       The value returned in erroroffset is an indication of where in the pat-
       tern an error occurred. When there is no	error,	zero  is  returned.  A
       non-zero	 value	is  not	 necessarily the furthest point	in the pattern
       that was	read. For example, after the error  "lookbehind	 assertion  is
       not  fixed length", the error offset points to the start	of the failing
       assertion. For an invalid UTF-8 or UTF-16 string, the offset is that of
       the first code unit of the failing character.

       Some errors are not detected until the whole pattern has	been  scanned;
       in  these  cases,  the offset passed back is the	length of the pattern.
       Note that the offset is in code units, not characters, even  in	a  UTF
       mode. It	may sometimes point into the middle of a UTF-8 or UTF-16 char-
       acter.

       This  code  fragment shows a typical straightforward call to pcre2_com-
       pile():

	 pcre2_code *re;
	 PCRE2_SIZE erroffset;
	 int errorcode;
	 re = pcre2_compile(
	   "^A.*Z",		   /* the pattern */
	   PCRE2_ZERO_TERMINATED,  /* the pattern is zero-terminated */
	   0,			   /* default options */
	   &errorcode,		   /* for error	code */
	   &erroffset,		   /* for error	offset */
	   NULL);		   /* no compile context */

   Main	compile	options

       The following names for option bits are defined in the  pcre2.h	header
       file:

	 PCRE2_ANCHORED

       If this bit is set, the pattern is forced to be "anchored", that	is, it
       is  constrained to match	only at	the first matching point in the	string
       that is being searched (the "subject string"). This effect can also  be
       achieved	 by appropriate	constructs in the pattern itself, which	is the
       only way	to do it in Perl.

	 PCRE2_ALLOW_EMPTY_CLASS

       By default, for compatibility with Perl,	a closing square bracket  that
       immediately  follows  an	opening	one is treated as a data character for
       the class. When	PCRE2_ALLOW_EMPTY_CLASS	 is  set,  it  terminates  the
       class, which therefore contains no characters and so can	never match.

	 PCRE2_ALT_BSUX

       This  option  request  alternative  handling of three escape sequences,
       which makes PCRE2's behaviour more like	ECMAscript  (aka  JavaScript).
       When it is set:

       (1) \U matches an upper case "U"	character; by default \U causes	a com-
       pile time error (Perl uses \U to	upper case subsequent characters).

       (2) \u matches a	lower case "u" character unless	it is followed by four
       hexadecimal  digits,  in	 which case the	hexadecimal number defines the
       code point to match. By default,	\u causes a compile time  error	 (Perl
       uses it to upper	case the following character).

       (3)  \x matches a lower case "x"	character unless it is followed	by two
       hexadecimal digits, in which case the hexadecimal  number  defines  the
       code  point  to	match. By default, as in Perl, a hexadecimal number is
       always expected after \x, but it	may have zero, one, or two digits (so,
       for example, \xz	matches	a binary zero character	followed by z).

       ECMAscript 6 added additional functionality to \u. This can be accessed
       using the PCRE2_EXTRA_ALT_BSUX extra option  (see  "Extra  compile  op-
       tions" below).  Note that this alternative escape handling applies only
       to  patterns.  Neither  of  these options affects the processing	of re-
       placement strings passed	to pcre2_substitute().

	 PCRE2_ALT_CIRCUMFLEX

       In  multiline  mode  (when  PCRE2_MULTILINE  is	set),  the  circumflex
       metacharacter  matches at the start of the subject (unless PCRE2_NOTBOL
       is set),	and also after any internal  newline.  However,	 it  does  not
       match after a newline at	the end	of the subject,	for compatibility with
       Perl.  If  you want a multiline circumflex also to match	after a	termi-
       nating newline, you must	set PCRE2_ALT_CIRCUMFLEX.

	 PCRE2_ALT_EXTENDED_CLASS

       Alters the parsing of character classes to follow the  extended	syntax
       described by Unicode UTS#18. The	PCRE2_ALT_EXTENDED_CLASS option	has no
       impact  on the behaviour	of the Perl-specific "(?[...])"	syntax for ex-
       tended classes, but instead enables the alternative syntax of  extended
       class  behaviour	 inside	 ordinary  "[...]"  character classes. See the
       pcre2pattern documentation for details of the  character	 classes  sup-
       ported.

	 PCRE2_ALT_VERBNAMES

       By  default, for	compatibility with Perl, the name in any verb sequence
       such as (*MARK:NAME) is any sequence of characters that	does  not  in-
       clude  a	closing	parenthesis. The name is not processed in any way, and
       it is not possible to include a closing parenthesis in the  name.  How-
       ever,  if  the PCRE2_ALT_VERBNAMES option is set, normal	backslash pro-
       cessing is applied to verb names	and only an unescaped  closing	paren-
       thesis  terminates the name. A closing parenthesis can be included in a
       name either as \) or between  \Q	 and  \E.  If  the  PCRE2_EXTENDED  or
       PCRE2_EXTENDED_MORE  option  is set with	PCRE2_ALT_VERBNAMES, unescaped
       whitespace in verb names	is skipped and #-comments are recognized,  ex-
       actly as	in the rest of the pattern.

	 PCRE2_AUTO_CALLOUT

       If  this	 bit  is  set,	pcre2_compile()	 automatically inserts callout
       items, all with number 255, before each pattern	item,  except  immedi-
       ately  before  or after an explicit callout in the pattern. For discus-
       sion of the callout facility, see the pcre2callout documentation.

	 PCRE2_CASELESS

       If this bit is set, letters in the pattern match	both upper  and	 lower
       case  letters in	the subject. It	is equivalent to Perl's	/i option, and
       it can be changed within	a pattern by a (?i) option setting. If	either
       PCRE2_UTF  or  PCRE2_UCP	 is  set,  Unicode properties are used for all
       characters with more than one other case, and for all characters	 whose
       code points are greater than U+007F.

       Note that there are two ASCII characters, K and S, that,	in addition to
       their  lower  case  ASCII  equivalents, are case-equivalent with	U+212A
       (Kelvin sign) and U+017F	(long S) respectively. If you do not want this
       case equivalence, you can  suppress  it	by  setting  PCRE2_EXTRA_CASE-
       LESS_RESTRICT.

       One  language family, Turkish and Azeri,	has its	own case-insensitivity
       rules, which can	be  selected  by  setting  PCRE2_EXTRA_TURKISH_CASING.
       This  alters  the behaviour of the 'i', 'I', U+0130 (capital I with dot
       above), and U+0131 (small dotless i) characters.

       For lower valued	characters with	only one other case, a lookup table is
       used for	speed. When neither PCRE2_UTF nor PCRE2_UCP is set,  a	lookup
       table is	used for all code points less than 256,	and higher code	points
       (available only in 16-bit or 32-bit mode) are treated as	not having an-
       other case.

       From release 10.45 PCRE2_CASELESS also affects what some	of the letter-
       related	Unicode	 property escapes (\p and \P) match. The properties Lu
       (upper case letter), Ll (lower case letter), and	Lt (title case letter)
       are all treated as LC (cased letter) when PCRE2_CASELESS	is set.

	 PCRE2_DOLLAR_ENDONLY

       If this bit is set, a dollar metacharacter in the pattern matches  only
       at  the	end  of	the subject string. Without this option, a dollar also
       matches immediately before a newline at the end of the string (but  not
       before  any other newlines). The	PCRE2_DOLLAR_ENDONLY option is ignored
       if PCRE2_MULTILINE is set. There	is no equivalent  to  this  option  in
       Perl, and no way	to set it within a pattern.

	 PCRE2_DOTALL

       If  this	 bit  is  set,	a dot metacharacter in the pattern matches any
       character, including one	that indicates a  newline.  However,  it  only
       ever matches one	character, even	if newlines are	coded as CRLF. Without
       this option, a dot does not match when the current position in the sub-
       ject  is	 at  a newline.	This option is equivalent to Perl's /s option,
       and it can be changed within a pattern by a (?s)	option setting.	A neg-
       ative class such	as [^a]	always matches newline characters, and the  \N
       escape  sequence	always matches a non-newline character,	independent of
       the setting of PCRE2_DOTALL.

	 PCRE2_DUPNAMES

       If this bit is set, names used to identify capture groups need  not  be
       unique.	 This  can  be helpful for certain types of pattern when it is
       known that only one instance of the named group can  ever  be  matched.
       There  are  more	 details  of  named capture groups below; see also the
       pcre2pattern documentation.

	 PCRE2_ENDANCHORED

       If this bit is set, the end of any pattern match	must be	right  at  the
       end of the string being searched	(the "subject string").	If the pattern
       match succeeds by reaching (*ACCEPT), but does not reach	the end	of the
       subject,	 the match fails at the	current	starting point.	For unanchored
       patterns, a new match is	then tried at the next	starting  point.  How-
       ever, if	the match succeeds by reaching the end of the pattern, but not
       the  end	 of  the subject, backtracking occurs and an alternative match
       may be found. Consider these two	patterns:

	 .(*ACCEPT)|..
	 .|..

       If matched against "abc"	with PCRE2_ENDANCHORED set, the	first  matches
       "c"  whereas  the  second matches "bc". The effect of PCRE2_ENDANCHORED
       can also	be achieved by appropriate constructs in the  pattern  itself,
       which is	the only way to	do it in Perl.

       For DFA matching	with pcre2_dfa_match(),	PCRE2_ENDANCHORED applies only
       to  the	first  (that  is,  the longest)	matched	string.	Other parallel
       matches,	which are necessarily substrings of the	first one, must	 obvi-
       ously end before	the end	of the subject.

	 PCRE2_EXTENDED

       If  this	bit is set, most white space characters	in the pattern are to-
       tally ignored except when escaped, inside a character class, or	inside
       a  \Q...\E  sequence.  However,	white  space is	not allowed within se-
       quences such as (?> that	introduce various  parenthesized  groups,  nor
       within  numerical  quantifiers  such as {1,3}. Ignorable	white space is
       permitted between an item and a	following  quantifier  and  between  a
       quantifier  and	a following + that indicates possessiveness. PCRE2_EX-
       TENDED is equivalent to Perl's /x option, and it	can be changed	within
       a pattern by a (?x) option setting.

       When  PCRE2  is compiled	without	Unicode	support, PCRE2_EXTENDED	recog-
       nizes as	white space only those characters with code points  less  than
       256 that	are flagged as white space in its low-character	table. The ta-
       ble is normally created by pcre2_maketables(), which uses the isspace()
       function	 to identify space characters. In most ASCII environments, the
       relevant	characters are those with code	points	0x0009	(tab),	0x000A
       (linefeed),  0x000B (vertical tab), 0x000C (formfeed), 0x000D (carriage
       return),	and 0x0020 (space).

       When PCRE2 is compiled with Unicode support, in addition	to these char-
       acters, five more Unicode "Pattern White	Space" characters  are	recog-
       nized by	PCRE2_EXTENDED.	These are U+0085 (next line), U+200E (left-to-
       right  mark), U+200F (right-to-left mark), U+2028 (line separator), and
       U+2029 (paragraph separator). This set of characters  is	 the  same  as
       recognized  by  Perl's /x option. Note that the horizontal and vertical
       space characters	that are matched by the	\h and \v escapes in  patterns
       are a much bigger set.

       As  well	as ignoring most white space, PCRE2_EXTENDED also causes char-
       acters between an unescaped # outside a character class	and  the  next
       newline,	 inclusive,  to	be ignored, which makes	it possible to include
       comments	inside complicated patterns. Note that the end of this type of
       comment is a literal newline sequence in	the pattern; escape  sequences
       that happen to represent	a newline do not count.

       Which characters	are interpreted	as newlines can	be specified by	a set-
       ting  in	 the compile context that is passed to pcre2_compile() or by a
       special sequence	at the start of	the pattern, as	described in the  sec-
       tion  entitled "Newline conventions" in the pcre2pattern	documentation.
       A default is defined when PCRE2 is built.

	 PCRE2_EXTENDED_MORE

       This option has the effect of PCRE2_EXTENDED,  but,  in	addition,  un-
       escaped	space and horizontal tab characters are	ignored	inside a char-
       acter class. Note: only these two characters are	ignored, not the  full
       set  of pattern white space characters that are ignored outside a char-
       acter class. PCRE2_EXTENDED_MORE	is equivalent to  Perl's  /xx  option,
       and it can be changed within a pattern by a (?xx) option	setting.

	 PCRE2_FIRSTLINE

       If this option is set, the start	of an unanchored pattern match must be
       before  or  at  the  first  newline in the subject string following the
       start of	matching, though the matched text may continue over  the  new-
       line. If	startoffset is non-zero, the limiting newline is not necessar-
       ily  the	 first	newline	 in  the  subject. For example,	if the subject
       string is "abc\nxyz" (where \n represents a single-character newline) a
       pattern match for "yz" succeeds with PCRE2_FIRSTLINE if startoffset  is
       greater	than 3.	See also PCRE2_USE_OFFSET_LIMIT, which provides	a more
       general limiting	facility. If PCRE2_FIRSTLINE is	 set  with  an	offset
       limit,  a match must occur in the first line and	also within the	offset
       limit. In other words, whichever	limit comes first is used. This	option
       has no effect for anchored patterns.

	 PCRE2_LITERAL

       If this option is set, all meta-characters in the pattern are disabled,
       and it is treated as a literal string. Matching literal strings with  a
       regular expression engine is not	the most efficient way of doing	it. If
       you  are	 doing	a  lot of literal matching and are worried about effi-
       ciency, you should consider using other approaches. The only other main
       options	that  are  allowed  with  PCRE2_LITERAL	 are:  PCRE2_ANCHORED,
       PCRE2_ENDANCHORED, PCRE2_AUTO_CALLOUT, PCRE2_CASELESS, PCRE2_FIRSTLINE,
       PCRE2_MATCH_INVALID_UTF,	 PCRE2_NO_START_OPTIMIZE,  PCRE2_NO_UTF_CHECK,
       PCRE2_UTF, and  PCRE2_USE_OFFSET_LIMIT.	The  extra  options  PCRE2_EX-
       TRA_MATCH_LINE and PCRE2_EXTRA_MATCH_WORD are also supported. Any other
       options cause an	error.

	 PCRE2_MATCH_INVALID_UTF

       This  option  forces PCRE2_UTF (see below) and also enables support for
       matching	by pcre2_match() in subject strings that contain  invalid  UTF
       sequences.   Note,  however, that the 16-bit and	32-bit PCRE2 libraries
       process strings as sequences of uint16_t	or uint32_t code points.  They
       cannot find valid UTF sequences within an arbitrary string of bytes un-
       less  such  sequences  are  suitably aligned. This facility is not sup-
       ported for DFA matching.	For details, see the  pcre2unicode  documenta-
       tion.

	 PCRE2_MATCH_UNSET_BACKREF

       If  this	 option	 is  set,  a  backreference  to	an unset capture group
       matches an empty	string (by default this	causes	the  current  matching
       alternative to fail).  A	pattern	such as	(\1)(a)	succeeds when this op-
       tion  is	 set  (assuming	it can find an "a" in the subject), whereas it
       fails by	default, for Perl compatibility.  Setting  this	 option	 makes
       PCRE2 behave more like ECMAscript (aka JavaScript).

	 PCRE2_MULTILINE

       By  default,  for  the purposes of matching "start of line" and "end of
       line", PCRE2 treats the subject string as consisting of a  single  line
       of  characters,	even  if  it actually contains newlines. The "start of
       line" metacharacter (^) matches only at the start of  the  string,  and
       the  "end  of  line"  metacharacter  ($)	matches	only at	the end	of the
       string, or before a terminating newline (except	when  PCRE2_DOLLAR_EN-
       DONLY is	set). Note, however, that unless PCRE2_DOTALL is set, the "any
       character"  metacharacter  (.) does not match at	a newline. This	behav-
       iour (for ^, $, and dot)	is the same as Perl.

       When PCRE2_MULTILINE it is set, the "start of line" and "end  of	 line"
       constructs  match  immediately following	or immediately before internal
       newlines	in the subject string, respectively, as	well as	 at  the  very
       start  and  end.	 This is equivalent to Perl's /m option, and it	can be
       changed within a	pattern	by a (?m) option setting. Note that the	"start
       of line"	metacharacter does not match after a newline at	the end	of the
       subject,	for compatibility with Perl.  However, you can change this  by
       setting	the PCRE2_ALT_CIRCUMFLEX option. If there are no newlines in a
       subject string, or no occurrences of ^  or  $  in  a  pattern,  setting
       PCRE2_MULTILINE has no effect.

	 PCRE2_NEVER_BACKSLASH_C

       This  option  locks out the use of \C in	the pattern that is being com-
       piled.  This escape can	cause  unpredictable  behaviour	 in  UTF-8  or
       UTF-16  modes,  because	it may leave the current matching point	in the
       middle of a multi-code-unit character. This option may be useful	in ap-
       plications that process patterns	from external sources. Note that there
       is also a build-time option that	permanently locks out the use of \C.

	 PCRE2_NEVER_UCP

       This option locks out the use of	Unicode	properties  for	 handling  \B,
       \b, \D, \d, \S, \s, \W, \w, and some of the POSIX character classes, as
       described  for  the  PCRE2_UCP option below. In particular, it prevents
       the creator of the pattern from enabling	this facility by starting  the
       pattern	with  (*UCP).  This  option may	be useful in applications that
       process	patterns  from	external  sources.  The	  option   combination
       PCRE2_UCP and PCRE2_NEVER_UCP causes an error.

	 PCRE2_NEVER_UTF

       This  option  locks out interpretation of the pattern as	UTF-8, UTF-16,
       or UTF-32, depending on which library is	in use.	In particular, it pre-
       vents the creator of the	pattern	from switching to  UTF	interpretation
       by  starting  the pattern with (*UTF). This option may be useful	in ap-
       plications that process patterns	from external sources. The combination
       of PCRE2_UTF and	PCRE2_NEVER_UTF	causes an error.

	 PCRE2_NO_AUTO_CAPTURE

       If this option is set, it disables the use of numbered capturing	paren-
       theses in the pattern. Any opening parenthesis that is not followed  by
       ?  behaves as if	it were	followed by ?: but named parentheses can still
       be used for capturing (and they acquire numbers in the usual way). This
       is the same as Perl's /n	option.	 Note that, when this option  is  set,
       references  to  capture	groups (backreferences or recursion/subroutine
       calls) may only refer to	named groups, though the reference can	be  by
       name or by number.

	 PCRE2_NO_AUTO_POSSESS

       If  this	 (deprecated)  option  is set, it disables "auto-possessifica-
       tion", which is an optimization that, for example, turns	a+b into  a++b
       in order	to avoid backtracks into a+ that can never be successful. How-
       ever,  if  callouts  are	 in use, auto-possessification means that some
       callouts	are never taken. You can set  this  option  if	you  want  the
       matching	 functions  to	do  a  full unoptimized	search and run all the
       callouts, but it	is mainly provided for testing purposes.

       If  a  compile  context	is  available,	it  is	recommended   to   use
       pcre2_set_optimize()  with  the directive PCRE2_AUTO_POSSESS_OFF	rather
       than   the   compile   option	PCRE2_NO_AUTO_POSSESS.	  Note	  that
       PCRE2_NO_AUTO_POSSESS  takes  precedence	 over the pcre2_set_optimize()
       optimization directives PCRE2_AUTO_POSSESS and PCRE2_AUTO_POSSESS_OFF.

	 PCRE2_NO_DOTSTAR_ANCHOR

       If this (deprecated) option is set, it disables an optimization that is
       applied when .* is the first significant	item in	a top-level branch  of
       a  pattern, and all the other branches also start with .* or with \A or
       \G or ^.	The optimization is automatically disabled for .* if it	is in-
       side an atomic group or a capture group that is the subject of a	 back-
       reference, or if	the pattern contains (*PRUNE) or (*SKIP). When the op-
       timization is not disabled, such	a pattern is automatically anchored if
       PCRE2_DOTALL is set for all the .* items	and PCRE2_MULTILINE is not set
       for  any	 ^ items. Otherwise, the fact that any match must start	either
       at the start of the subject or following	a newline is remembered.  Like
       other optimizations, this can cause callouts to be skipped.  (If	a com-
       pile  context  is  available,  it is recommended	to use pcre2_set_opti-
       mize() with the directive PCRE2_DOTSTAR_ANCHOR_OFF instead.)

	 PCRE2_NO_START_OPTIMIZE

       This is an option whose main effect is at matching time.	 It  does  not
       change what pcre2_compile() generates, but it does affect the output of
       the  JIT	 compiler.  Setting  this  option  is  equivalent  to  calling
       pcre2_set_optimize()   with   the   directive	parameter    set    to
       PCRE2_START_OPTIMIZE_OFF.

       There  are  a  number of	optimizations that may occur at	the start of a
       match, in order to speed	up the process.	For example, if	 it  is	 known
       that  an	 unanchored  match must	start with a specific code unit	value,
       the matching code searches the subject for that value, and fails	 imme-
       diately	if it cannot find it, without actually running the main	match-
       ing function. The start-up optimizations	are in effect  a  pre-scan  of
       the subject that	takes place before the pattern is run.

       Disabling  the  start-up	optimizations may cause	performance to suffer.
       However,	this may be desirable for patterns which contain  callouts  or
       items  such  as	(*COMMIT)  and	(*MARK).  See the above	description of
       PCRE2_START_OPTIMIZE_OFF	for further details.

	 PCRE2_NO_UTF_CHECK

       When PCRE2_UTF is set, the validity of the pattern as a UTF  string  is
       automatically  checked.	There  are  discussions	 about the validity of
       UTF-8 strings, UTF-16 strings, and UTF-32 strings in  the  pcre2unicode
       document.  If an	invalid	UTF sequence is	found, pcre2_compile() returns
       a negative error	code.

       If you know that	your pattern is	a valid	UTF string, and	 you  want  to
       skip   this   check   for   performance	 reasons,   you	 can  set  the
       PCRE2_NO_UTF_CHECK option. When it is set, the effect of	passing	an in-
       valid UTF string	as a pattern is	undefined. It may cause	 your  program
       to crash	or loop.

       Note  that  this	 option	 can  also  be	passed	to  pcre2_match()  and
       pcre2_dfa_match(), to suppress UTF validity  checking  of  the  subject
       string.

       Note also that setting PCRE2_NO_UTF_CHECK at compile time does not dis-
       able  the error that is given if	an escape sequence for an invalid Uni-
       code code point is encountered in the pattern. In particular,  the  so-
       called  "surrogate"  code points	(0xd800	to 0xdfff) are invalid.	If you
       want to allow escape  sequences	such  as  \x{d800}  you	 can  set  the
       PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES  extra  option, as described	in the
       section entitled	"Extra compile options"	below.	However, this is  pos-
       sible only in UTF-8 and UTF-32 modes, because these values are not rep-
       resentable in UTF-16.

	 PCRE2_UCP

       This option has two effects. Firstly, it	change the way PCRE2 processes
       \B,  \b,	 \D,  \d,  \S,	\s,  \W,  \w,  and some	of the POSIX character
       classes.	By default, only  ASCII	 characters  are  recognized,  but  if
       PCRE2_UCP  is  set, Unicode properties are used to classify characters.
       There are some PCRE2_EXTRA options (see below) that add	finer  control
       to  this	 behaviour.  More  details are given in	the section on generic
       character types in the pcre2pattern page.

       The second effect of PCRE2_UCP is to force the use of  Unicode  proper-
       ties for	upper/lower casing operations, even when PCRE2_UTF is not set.
       This  makes  it	possible  to process strings in	the 16-bit UCS-2 code.
       This option is available	only if	PCRE2 has been compiled	 with  Unicode
       support (which is the default).

       The PCRE2_EXTRA_CASELESS_RESTRICT option	(see above) restricts caseless
       matching	 such  that  ASCII  characters match only ASCII	characters and
       non-ASCII characters match only	non-ASCII  characters.	The  PCRE2_EX-
       TRA_TURKISH_CASING  option  (see	 above)	alters the matching of the 'i'
       characters to follow their behaviour in Turkish	and  Azeri  languages.
       For  further  details  on  PCRE2_EXTRA_CASELESS_RESTRICT	 and PCRE2_EX-
       TRA_TURKISH_CASING, see the pcre2unicode	page.

	 PCRE2_UNGREEDY

       This option inverts the "greediness" of the quantifiers	so  that  they
       are  not	greedy by default, but become greedy if	followed by "?". It is
       not compatible with Perl. It can	also be	set by a (?U)  option  setting
       within the pattern.

	 PCRE2_USE_OFFSET_LIMIT

       This option must	be set for pcre2_compile() if pcre2_set_offset_limit()
       is  going  to be	used to	set a non-default offset limit in a match con-
       text for	matches	that use this pattern. An error	 is  generated	if  an
       offset  limit is	set without this option. For more details, see the de-
       scription of pcre2_set_offset_limit() in	 the  section  that  describes
       match contexts. See also	the PCRE2_FIRSTLINE option above.

	 PCRE2_UTF

       This  option  causes  PCRE2  to regard both the pattern and the subject
       strings that are	subsequently processed as strings  of  UTF  characters
       instead	of  single-code-unit  strings.	It  is available when PCRE2 is
       built to	include	Unicode	support	(which is  the	default).  If  Unicode
       support is not available, the use of this option	provokes an error. De-
       tails  of how PCRE2_UTF changes the behaviour of	PCRE2 are given	in the
       pcre2unicode  page.  In	particular,  note  that	 it  changes  the  way
       PCRE2_CASELESS works.

   Extra compile options

       The  option  bits  that	can be set in a	compile	context	by calling the
       pcre2_set_compile_extra_options() function are as follows:

	 PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK

       Since release 10.38 PCRE2 has forbidden the use of \K within lookaround
       assertions, following Perl's lead. This option is provided to re-enable
       the previous behaviour (act in positive lookarounds, ignore in negative
       ones) in	case anybody is	relying	on it.

	 PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES

       This option applies when	compiling a pattern in UTF-8 or	 UTF-32	 mode.
       It  is  forbidden in UTF-16 mode, and ignored in	non-UTF	modes. Unicode
       "surrogate" code	points in the range 0xd800 to 0xdfff are used in pairs
       in UTF-16 to encode code	points with values in  the  range  0x10000  to
       0x10ffff.  The  surrogates  cannot  therefore be	represented in UTF-16.
       They can	be represented in UTF-8	and UTF-32, but	are defined as invalid
       code points, and	cause errors if	 encountered  in  a  UTF-8  or	UTF-32
       string that is being checked for	validity by PCRE2.

       These  values also cause	errors if encountered in escape	sequences such
       as \x{d912} within a pattern. However, it seems that some applications,
       when using PCRE2	to check for unwanted characters in UTF-8 strings, ex-
       plicitly	 test  for  the	 surrogates  using   escape   sequences.   The
       PCRE2_NO_UTF_CHECK  option  does	not disable the	error that occurs, be-
       cause it	applies	only to	the testing of input strings for UTF validity.

       If the extra option PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES is set,	surro-
       gate  code  point values	in UTF-8 and UTF-32 patterns no	longer provoke
       errors and are incorporated in the compiled pattern. However, they  can
       only  match  subject characters if the matching function	is called with
       PCRE2_NO_UTF_CHECK set.

	 PCRE2_EXTRA_ALT_BSUX

       The original option PCRE2_ALT_BSUX causes PCRE2 to process \U, \u,  and
       \x  in  the way that ECMAscript (aka JavaScript)	does. Additional func-
       tionality was defined by	ECMAscript 6; setting PCRE2_EXTRA_ALT_BSUX has
       the effect of PCRE2_ALT_BSUX, but in addition it	 recognizes  \u{hhh..}
       as a hexadecimal	character code,	where hhh.. is any number of hexadeci-
       mal digits.

	 PCRE2_EXTRA_ASCII_BSD

       This  option  forces \d to match	only ASCII digits, even	when PCRE2_UCP
       is set.	It can be changed within a pattern by means of the  (?aD)  op-
       tion setting.

	 PCRE2_EXTRA_ASCII_BSS

       This  option  forces \s to match	only ASCII space characters, even when
       PCRE2_UCP is set. It can	be changed within a pattern by	means  of  the
       (?aS) option setting.

	 PCRE2_EXTRA_ASCII_BSW

       This  option  forces  \w	to match only ASCII word characters, even when
       PCRE2_UCP is set. It can	be changed within a pattern by	means  of  the
       (?aW) option setting.

	 PCRE2_EXTRA_ASCII_DIGIT

       This option forces the POSIX character classes [:digit:]	and [:xdigit:]
       to  match  only	ASCII  digits,	even  when PCRE2_UCP is	set. It	can be
       changed within a	pattern	by means of the	(?aT) option setting.

	 PCRE2_EXTRA_ASCII_POSIX

       This option forces all the POSIX	character classes, including [:digit:]
       and [:xdigit:], to match	only ASCII characters, even when PCRE2_UCP  is
       set.  It	 can  be changed within	a pattern by means of the (?aP)	option
       setting,	but note that this also	sets PCRE2_EXTRA_ASCII_DIGIT in	 order
       to ensure that (?-aP) unsets all	ASCII restrictions for POSIX classes.

	 PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL

       This  is	a dangerous option. Use	with care. By default, an unrecognized
       escape such as \j or a malformed	one such as \x{2z} causes  a  compile-
       time error when detected	by pcre2_compile(). Perl is somewhat inconsis-
       tent  in	 handling  such	items: for example, \j is treated as a literal
       "j", and	non-hexadecimal	digits in \x{} are just	ignored, though	 warn-
       ings  are given in both cases if	Perl's warning switch is enabled. How-
       ever, a malformed octal number after \o{	 always	 causes	 an  error  in
       Perl.

       If  the	PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL  extra  option  is passed to
       pcre2_compile(),	all unrecognized or  malformed	escape	sequences  are
       treated	as  single-character escapes. For example, \j is a literal "j"
       and \x{2z} is treated as	the literal string "x{2z}". Setting  this  op-
       tion means that typos in	patterns may go	undetected and have unexpected
       results.	 Also  note  that a sequence such as [\N{] is interpreted as a
       malformed attempt at [\N{...}] and so is	treated	as [N{]	 whereas  [\N]
       gives an	error because an unqualified \N	is a valid escape sequence but
       is  not supported in a character	class. To reiterate: this is a danger-
       ous option. Use with great care.

	 PCRE2_EXTRA_CASELESS_RESTRICT

       When either PCRE2_UCP or	PCRE2_UTF is set,  caseless  matching  follows
       Unicode rules, which allow for more than	two cases per character. There
       are two case-equivalent character sets that contain both	ASCII and non-
       ASCII characters. The ASCII letter S is case-equivalent to U+017f (long
       S)  and	the ASCII letter K is case-equivalent to U+212a	(Kelvin	sign).
       This option disables recognition	of case-equivalences  that  cross  the
       ASCII/non-ASCII boundary. In a caseless match, both characters must ei-
       ther  be	ASCII or non-ASCII. The	option can be changed within a pattern
       by the (*CASELESS_RESTRICT) or (?r) option settings.

	 PCRE2_EXTRA_ESCAPED_CR_IS_LF

       There are some legacy applications where	the escape sequence  \r	 in  a
       pattern	is expected to match a newline.	If this	option is set, \r in a
       pattern is converted to \n so that it matches a LF  (linefeed)  instead
       of  a CR	(carriage return) character. The option	does not affect	a lit-
       eral CR in the pattern, nor does	it affect CR specified as an  explicit
       code point such as \x{0D}.

	 PCRE2_EXTRA_MATCH_LINE

       This  option  is	 provided  for	use  by	the -x option of pcre2grep. It
       causes the pattern only to match	complete lines.	This  is  achieved  by
       automatically  inserting	 the  code for "^(?:" at the start of the com-
       piled pattern and ")$" at the end. Thus,	when PCRE2_MULTILINE  is  set,
       the  matched  line may be in the	middle of the subject string. This op-
       tion can	be used	with PCRE2_LITERAL.

	 PCRE2_EXTRA_MATCH_WORD

       This option is provided for use by  the	-w  option  of	pcre2grep.  It
       causes  the  pattern only to match strings that have a word boundary at
       the start and the end. This is achieved by automatically	inserting  the
       code  for "\b(?:" at the	start of the compiled pattern and ")\b"	at the
       end. The	option may be used with	PCRE2_LITERAL. However,	it is  ignored
       if PCRE2_EXTRA_MATCH_LINE is also set.

	 PCRE2_EXTRA_NO_BS0

       If this option is set (note that	its final character is the digit 0) it
       locks  out  the	use  of	the sequence \0	unless at least	one more octal
       digit follows.

	 PCRE2_EXTRA_PYTHON_OCTAL

       If this option is set, PCRE2 follows Python's  rules  for  interpreting
       octal  escape  sequences. The rules for handling	sequences such as \14,
       which could be an octal number or a back	reference are  different.  De-
       tails are given in the pcre2pattern documentation.

	 PCRE2_EXTRA_NEVER_CALLOUT

       If this option is set, PCRE2 treats callouts in the pattern as a	syntax
       error, returning	PCRE2_ERROR_CALLOUT_CALLER_DISABLED. This is useful if
       the   application  knows	 that  a  callout  will	 not  be  provided  to
       pcre2_match(), so that callouts in the pattern  are  not	 silently  ig-
       nored.

	 PCRE2_EXTRA_TURKISH_CASING

       This  option  alters  case-equivalence of the 'i' letters to follow the
       alphabet	used by	Turkish	and Azeri languages. The option	can be changed
       within a	pattern	by the (*TURKISH_CASING) start-of-pattern setting. Ei-
       ther the	UTF or UCP options must	be set.	In the 8-bit library, UTF must
       be set. This option cannot be  combined	with  PCRE2_EXTRA_CASELESS_RE-
       STRICT.

JUST-IN-TIME (JIT) COMPILATION

       int pcre2_jit_compile(pcre2_code	*code, uint32_t	options);

       int pcre2_jit_match(const pcre2_code *code, PCRE2_SPTR subject,
	 PCRE2_SIZE length, PCRE2_SIZE startoffset,
	 uint32_t options, pcre2_match_data *match_data,
	 pcre2_match_context *mcontext);

       void pcre2_jit_free_unused_memory(pcre2_general_context *gcontext);

       pcre2_jit_stack *pcre2_jit_stack_create(size_t startsize,
	 size_t	maxsize, pcre2_general_context *gcontext);

       void pcre2_jit_stack_assign(pcre2_match_context *mcontext,
	 pcre2_jit_callback callback_function, void *callback_data);

       void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack);

       These  functions	 provide  support  for	JIT compilation, which,	if the
       just-in-time compiler is	available, further processes a	compiled  pat-
       tern into machine code that executes much faster	than the pcre2_match()
       interpretive  matching function.	Full details are given in the pcre2jit
       documentation.

       JIT compilation is a heavyweight	optimization. It can  take  some  time
       for  patterns  to  be analyzed, and for one-off matches and simple pat-
       terns the benefit of faster execution might be offset by	a much	slower
       compilation  time.  Most	(but not all) patterns can be optimized	by the
       JIT compiler.

LOCALE SUPPORT

       const uint8_t *pcre2_maketables(pcre2_general_context *gcontext);

       void pcre2_maketables_free(pcre2_general_context	*gcontext,
	 const uint8_t *tables);

       PCRE2 handles caseless matching,	and determines whether characters  are
       letters,	 digits, or whatever, by reference to a	set of tables, indexed
       by character code point.	However, this applies only to characters whose
       code points are less than 256. By default,  higher-valued  code	points
       never match escapes such	as \w or \d.

       When PCRE2 is built with	Unicode	support	(the default), certain Unicode
       character  properties  can be tested with \p and	\P, or,	alternatively,
       the PCRE2_UCP option can	be set when a pattern is compiled; this	causes
       \w and friends to use Unicode property support instead of the  built-in
       tables.	PCRE2_UCP also causes upper/lower casing operations on charac-
       ters with code points greater than 127 to use Unicode properties. These
       effects	apply even when	PCRE2_UTF is not set. There are, however, some
       PCRE2_EXTRA options (see	above) that can	be used	to modify or  suppress
       them.

       The  use	 of  locales  with Unicode is discouraged. If you are handling
       characters with code points greater than	127,  you  should  either  use
       Unicode support,	or use locales,	but not	try to mix the two.

       PCRE2  contains a built-in set of character tables that are used	by de-
       fault.  These are sufficient for	many applications. Normally,  the  in-
       ternal  tables  recognize only ASCII characters.	However, when PCRE2 is
       built, it is possible to	cause the internal tables to be	rebuilt	in the
       default "C" locale of the local system, which may cause them to be dif-
       ferent.

       The built-in tables can be overridden by	tables supplied	by the	appli-
       cation  that  calls  PCRE2.  These may be created in a different	locale
       from the	default.  As more and more applications	change to  using  Uni-
       code, the need for this locale support is expected to die away.

       External	 tables	 are built by calling the pcre2_maketables() function,
       in the relevant locale. The only	argument to this function is a general
       context,	which can be used to pass a custom memory  allocator.  If  the
       argument	is NULL, the system malloc() is	used. The result can be	passed
       to pcre2_compile() as often as necessary, by creating a compile context
       and  calling  pcre2_set_character_tables()  to  set  the	tables pointer
       therein.

       For example, to build and use  tables  that  are	 appropriate  for  the
       French  locale  (where accented characters with values greater than 127
       are treated as letters),	the following code could be used:

	 setlocale(LC_CTYPE, "fr_FR");
	 tables	= pcre2_maketables(NULL);
	 ccontext = pcre2_compile_context_create(NULL);
	 pcre2_set_character_tables(ccontext, tables);
	 re = pcre2_compile(..., ccontext);

       The locale name "fr_FR" is used on Linux	and other  Unix-like  systems;
       if you are using	Windows, the name for the French locale	is "french".

       The pointer that	is passed (via the compile context) to pcre2_compile()
       is saved	with the compiled pattern, and the same	tables are used	by the
       matching	 functions.  Thus,  for	 any  single  pattern, compilation and
       matching	both happen in the same	locale,	but different patterns can  be
       processed in different locales.

       It  is the caller's responsibility to ensure that the memory containing
       the tables remains available while they are still in use. When they are
       no longer needed, you can discard them  using  pcre2_maketables_free(),
       which  should  pass as its first	parameter the same global context that
       was used	to create the tables.

   Saving locale tables

       The tables described above are just a sequence of binary	 bytes,	 which
       makes  them  independent	of hardware characteristics such as endianness
       or whether the processor	is 32-bit or 64-bit. A copy of the  result  of
       pcre2_maketables()  can	therefore  be saved in a file or elsewhere and
       re-used later, even in a	different program or on	another	computer.  The
       size  of	 the  tables  (number  of  bytes)  must	be obtained by calling
       pcre2_config()  with  the  PCRE2_CONFIG_TABLES_LENGTH  option   because
       pcre2_maketables()   does   not	 return	 this  value.  Note  that  the
       pcre2_dftables program, which is	part of	the PCRE2 build	system,	can be
       used stand-alone	to create a file that contains a set of	binary tables.
       See the pcre2build documentation	for details.

INFORMATION ABOUT A COMPILED PATTERN

       int pcre2_pattern_info(const pcre2 *code, uint32_t what,	void *where);

       The pcre2_pattern_info()	function returns general information  about  a
       compiled	pattern. For information about callouts, see the next section.
       The  first  argument  for pcre2_pattern_info() is a pointer to the com-
       piled pattern. The second argument specifies which piece	of information
       is required, and	the third argument is a	pointer	to a variable  to  re-
       ceive  the  data.  If the third argument	is NULL, the first argument is
       ignored,	and the	function returns the size in  bytes  of	 the  variable
       that is required	for the	information requested. Otherwise, the yield of
       the function is zero for	success, or one	of the following negative num-
       bers:

	 PCRE2_ERROR_NULL	    the	argument code was NULL
	 PCRE2_ERROR_BADMAGIC	    the	"magic number" was not found
	 PCRE2_ERROR_BADOPTION	    the	value of what was invalid
	 PCRE2_ERROR_UNSET	    the	requested field	is not set

       The "magic number" is placed at the start of each compiled pattern as a
       simple  check  against  passing	an arbitrary memory pointer. Here is a
       typical call of pcre2_pattern_info(), to	obtain the length of the  com-
       piled pattern:

	 int rc;
	 size_t	length;
	 rc = pcre2_pattern_info(
	   re,		     /*	result of pcre2_compile() */
	   PCRE2_INFO_SIZE,  /*	what is	required */
	   &length);	     /*	where to put the data */

       The possible values for the second argument are defined in pcre2.h, and
       are as follows:

	 PCRE2_INFO_ALLOPTIONS
	 PCRE2_INFO_ARGOPTIONS
	 PCRE2_INFO_EXTRAOPTIONS

       Return copies of	the pattern's options. The third argument should point
       to  a  uint32_t variable. PCRE2_INFO_ARGOPTIONS returns exactly the op-
       tions that were passed to  pcre2_compile(),  whereas  PCRE2_INFO_ALLOP-
       TIONS  returns  the compile options as modified by any top-level	(*XXX)
       option settings such as (*UTF) at the  start  of	 the  pattern  itself.
       PCRE2_INFO_EXTRAOPTIONS	returns	the extra options that were set	in the
       compile context by calling the pcre2_set_compile_extra_options()	 func-
       tion.

       For  example, if	the pattern /(*UTF)abc/	is compiled with the PCRE2_EX-
       TENDED option, the result for PCRE2_INFO_ALLOPTIONS  is	PCRE2_EXTENDED
       and  PCRE2_UTF.	 Option	settings such as (?i) that can change within a
       pattern do not affect the result	of PCRE2_INFO_ALLOPTIONS, even if they
       appear right at the start of the	pattern. (This was different  in  some
       earlier releases.)

       A  pattern compiled without PCRE2_ANCHORED is automatically anchored by
       PCRE2 if	the first significant item in every top-level branch is	one of
       the following:

	 ^     unless PCRE2_MULTILINE is set
	 \A    always
	 \G    always
	 .*    sometimes - see below

       When .* is the first significant	item, anchoring	is possible only  when
       all the following are true:

	 .* is not in an atomic	group
	 .* is not in a	capture	group that is the subject
	      of a backreference
	 PCRE2_DOTALL is in force for .*
	 Neither (*PRUNE) nor (*SKIP) appears in the pattern
	 PCRE2_NO_DOTSTAR_ANCHOR is not	set
	 Dotstar anchoring has not been	disabled with PCRE2_DOTSTAR_ANCHOR_OFF

       For  patterns  that are auto-anchored, the PCRE2_ANCHORED bit is	set in
       the options returned for	PCRE2_INFO_ALLOPTIONS.

	 PCRE2_INFO_BACKREFMAX

       Return the number of the	highest	 backreference	in  the	 pattern.  The
       third  argument	should	point  to  a  uint32_t variable. Named capture
       groups acquire numbers as well as names,	and these  count  towards  the
       highest	backreference.	Backreferences	such as	\4 or \g{12} match the
       captured	characters of the given	group, but in addition,	the check that
       a capture group is set in a conditional group such as (?(3)a|b) is also
       a backreference.	 Zero is returned if there are no backreferences.

	 PCRE2_INFO_BSR

       The output is a uint32_t	integer	whose value indicates  what  character
       sequences  the \R escape	sequence matches. A value of PCRE2_BSR_UNICODE
       means that \R matches any Unicode line  ending  sequence;  a  value  of
       PCRE2_BSR_ANYCRLF means that \R matches only CR,	LF, or CRLF.

	 PCRE2_INFO_CAPTURECOUNT

       Return  the  highest  capture  group number in the pattern. In patterns
       where (?| is not	used, this is also the total number of capture groups.
       The third argument should point to a uint32_t variable.

	 PCRE2_INFO_DEPTHLIMIT

       If the pattern set a backtracking depth limit by	including an  item  of
       the  form  (*LIMIT_DEPTH=nnnn) at the start, the	value is returned. The
       third argument should point to a	uint32_t integer. If no	such value has
       been set, the call to pcre2_pattern_info() returns the error  PCRE2_ER-
       ROR_UNSET. Note that this limit will only be used during	matching if it
       is  less	 than  the  limit  set or defaulted by the caller of the match
       function.

	 PCRE2_INFO_FIRSTBITMAP

       In the absence of a single first	code unit for a	non-anchored  pattern,
       pcre2_compile()	may construct a	256-bit	table that defines a fixed set
       of values for the first code unit in any	match. For example, a  pattern
       that  starts  with  [abc]  results in a table with three	bits set. When
       code unit values	greater	than 255 are supported,	the flag bit  for  255
       means  "any  code unit of value 255 or above". If such a	table was con-
       structed, a pointer to it is returned. Otherwise	NULL is	returned.  The
       third argument should point to a	const uint8_t *	variable.

	 PCRE2_INFO_FIRSTCODETYPE

       Return information about	the first code unit of any matched string, for
       a  non-anchored	pattern. The third argument should point to a uint32_t
       variable. If there is a fixed first value, for example, the letter  "c"
       from  a	pattern	such as	(cat|cow|coyote), 1 is returned, and the value
       can be retrieved	using PCRE2_INFO_FIRSTCODEUNIT.	If there is  no	 fixed
       first  value,  but it is	known that a match can occur only at the start
       of the subject or following a newline in	the subject,  2	 is  returned.
       Otherwise, and for anchored patterns, 0 is returned.

	 PCRE2_INFO_FIRSTCODEUNIT

       Return  the  value  of  the first code unit of any matched string for a
       pattern where PCRE2_INFO_FIRSTCODETYPE returns 1; otherwise  return  0.
       The  third  argument  should point to a uint32_t	variable. In the 8-bit
       library,	the value is always less than 256. In the 16-bit  library  the
       value  can  be  up  to 0xffff. In the 32-bit library in UTF-32 mode the
       value can be up to 0x10ffff, and	up to 0xffffffff when not using	UTF-32
       mode.

	 PCRE2_INFO_FRAMESIZE

       Return the size (in bytes) of the data frames that are used to remember
       backtracking positions when the pattern is processed  by	 pcre2_match()
       without	the  use  of  JIT. The third argument should point to a	size_t
       variable. The frame size	depends	on the number of capturing parentheses
       in the pattern. Each additional capture group adds two PCRE2_SIZE vari-
       ables.

	 PCRE2_INFO_HASBACKSLASHC

       Return 1	if the pattern contains	any instances of \C, otherwise 0.  The
       third argument should point to a	uint32_t variable.

	 PCRE2_INFO_HASCRORLF

       Return  1  if  the  pattern  contains any explicit matches for CR or LF
       characters, otherwise 0.	The third argument should point	to a  uint32_t
       variable.  An explicit match is either a	literal	CR or LF character, or
       \r or \n	or one of the  equivalent  hexadecimal	or  octal  escape  se-
       quences.

	 PCRE2_INFO_HEAPLIMIT

       If the pattern set a heap memory	limit by including an item of the form
       (*LIMIT_HEAP=nnnn) at the start,	the value is returned. The third argu-
       ment should point to a uint32_t integer.	If no such value has been set,
       the  call  to pcre2_pattern_info() returns the error PCRE2_ERROR_UNSET.
       Note that this limit will only be used during matching if  it  is  less
       than the	limit set or defaulted by the caller of	the match function.

	 PCRE2_INFO_JCHANGED

       Return  1  if  the (?J) or (?-J)	option setting is used in the pattern,
       otherwise 0. The	third argument should point to	a  uint32_t  variable.
       (?J)  and  (?-J)	set and	unset the local	PCRE2_DUPNAMES option, respec-
       tively.

	 PCRE2_INFO_JITSIZE

       If the compiled pattern was successfully	 processed  by	pcre2_jit_com-
       pile(),	return	the  size  of  the JIT compiled	code, otherwise	return
       zero. The third argument	should point to	a size_t variable.

	 PCRE2_INFO_LASTCODETYPE

       Returns 1 if there is a rightmost literal code unit that	must exist  in
       any  matched string, other than at its start. The third argument	should
       point to	a uint32_t variable. If	there is no such value,	0 is returned.
       When 1 is returned, the code unit value itself can be  retrieved	 using
       PCRE2_INFO_LASTCODEUNIT.	For anchored patterns, a last literal value is
       recorded	 only if it follows something of variable length. For example,
       for the pattern /^a\d+z\d+/ the returned	value is 1 (with "z"  returned
       from  PCRE2_INFO_LASTCODEUNIT), but for /^a\dz\d/ the returned value is
       0.

	 PCRE2_INFO_LASTCODEUNIT

       Return the value	of the rightmost literal code unit that	must exist  in
       any  matched  string,  other  than  at  its  start, for a pattern where
       PCRE2_INFO_LASTCODETYPE returns 1. Otherwise, return 0. The third argu-
       ment should point to a uint32_t variable.

	 PCRE2_INFO_MATCHEMPTY

       Return 1	if the pattern might match an empty string, otherwise  0.  The
       third argument should point to a	uint32_t variable. When	a pattern con-
       tains recursive subroutine calls	it is not always possible to determine
       whether or not it can match an empty string. PCRE2 takes	a cautious ap-
       proach and returns 1 in such cases.

	 PCRE2_INFO_MATCHLIMIT

       If  the	pattern	 set  a	 match	limit by including an item of the form
       (*LIMIT_MATCH=nnnn) at the start, the value is returned.	The third  ar-
       gument  should  point  to a uint32_t integer. If	no such	value has been
       set, the	call to	pcre2_pattern_info() returns the error PCRE2_ERROR_UN-
       SET. Note that this limit will only be used during matching  if	it  is
       less  than  the limit set or defaulted by the caller of the match func-
       tion.

	 PCRE2_INFO_MAXLOOKBEHIND

       A lookbehind assertion moves back a certain number of  characters  (not
       code  units)  when  it starts to	process	each of	its branches. This re-
       quest returns the largest of these backward moves. The  third  argument
       should point to a uint32_t integer. The simple assertions \b and	\B re-
       quire  a	one-character lookbehind and cause PCRE2_INFO_MAXLOOKBEHIND to
       return 1	in the absence of anything longer. \A also  registers  a  one-
       character  lookbehind, though it	does not actually inspect the previous
       character.

       Note that this information is useful for	multi-segment matching only if
       the pattern contains no nested lookbehinds. For	example,  the  pattern
       (?<=a(?<=ba)c)  returns	a  maximum  lookbehind	of  2,	but when it is
       processed, the first lookbehind moves back by two  characters,  matches
       one  character, then the	nested lookbehind also moves back by two char-
       acters. This puts the matching point three characters earlier  than  it
       was  at the start.  PCRE2_INFO_MAXLOOKBEHIND is really only useful as a
       debugging tool. See the pcre2partial documentation for a	discussion  of
       multi-segment matching.

	 PCRE2_INFO_MINLENGTH

       If  a  minimum  length  for  matching subject strings was computed, its
       value is	returned. Otherwise the	returned value is 0. This value	is not
       computed	when PCRE2_NO_START_OPTIMIZE is	set. The value is a number  of
       characters,  which in UTF mode may be different from the	number of code
       units. The third	argument should	point  to  a  uint32_t	variable.  The
       value  is a lower bound to the length of	any matching string. There may
       not be any strings of that length that do  actually  match,  but	 every
       string that does	match is at least that long.

	 PCRE2_INFO_NAMECOUNT
	 PCRE2_INFO_NAMEENTRYSIZE
	 PCRE2_INFO_NAMETABLE

       PCRE2 supports the use of named as well as numbered capturing parenthe-
       ses.  The names are just	an additional way of identifying the parenthe-
       ses, which still	acquire	numbers. Several convenience functions such as
       pcre2_substring_get_byname() are	provided for extracting	captured  sub-
       strings	by  name. It is	also possible to extract the data directly, by
       first converting	the name to a number in	order to  access  the  correct
       pointers	 in the	output vector (described with pcre2_match() below). To
       do the conversion, you need to use the name-to-number map, which	is de-
       scribed by these	three values.

       The map consists	of a number of	fixed-size  entries.  PCRE2_INFO_NAME-
       COUNT  gives  the number	of entries, and	PCRE2_INFO_NAMEENTRYSIZE gives
       the size	of each	entry in code units; both of these return  a  uint32_t
       value. The entry	size depends on	the length of the longest name.

       PCRE2_INFO_NAMETABLE returns a pointer to the first entry of the	table.
       This is a PCRE2_SPTR pointer to a block of code units. In the 8-bit li-
       brary,  the first two bytes of each entry are the number	of the captur-
       ing parenthesis,	most significant byte first. In	 the  16-bit  library,
       the  pointer  points  to	16-bit code units, the first of	which contains
       the parenthesis number. In the 32-bit library, the  pointer  points  to
       32-bit  code units, the first of	which contains the parenthesis number.
       The rest	of the entry is	the corresponding name,	zero terminated.

       The names are in	alphabetical order. If (?| is used to create  multiple
       capture groups with the same number, as described in the	section	on du-
       plicate group numbers in	the pcre2pattern page, the groups may be given
       the  same  name,	 but  there  is	only one entry in the table. Different
       names for groups	of the same number are not permitted.

       Duplicate names for capture groups with different numbers  are  permit-
       ted, but	only if	PCRE2_DUPNAMES is set. They appear in the table	in the
       order  in  which	 they were found in the	pattern. In the	absence	of (?|
       this is the order of increasing number; when (?|	is used	 this  is  not
       necessarily  the	 case because later capture groups may have lower num-
       bers.

       As a simple example of the name/number table,  consider	the  following
       pattern	after  compilation by the 8-bit	library	(assume	PCRE2_EXTENDED
       is set, so white	space -	including newlines - is	ignored):

	 (?<date> (?<year>(\d\d)?\d\d) -
	 (?<month>\d\d)	- (?<day>\d\d) )

       There are four named capture groups, so the table has four entries, and
       each entry in the table is eight	bytes long. The	table is  as  follows,
       with non-printing bytes shows in	hexadecimal, and undefined bytes shown
       as ??:

	 00 01 d  a  t	e  00 ??
	 00 05 d  a  y	00 ?? ??
	 00 04 m  o  n	t  h  00
	 00 02 y  e  a	r  00 ??

       When  writing  code to extract data from	named capture groups using the
       name-to-number map, remember that the length of the entries  is	likely
       to be different for each	compiled pattern.

	 PCRE2_INFO_NEWLINE

       The output is one of the	following uint32_t values:

	 PCRE2_NEWLINE_CR	Carriage return	(CR)
	 PCRE2_NEWLINE_LF	Linefeed (LF)
	 PCRE2_NEWLINE_CRLF	Carriage return, linefeed (CRLF)
	 PCRE2_NEWLINE_ANY	Any Unicode line ending
	 PCRE2_NEWLINE_ANYCRLF	Any of CR, LF, or CRLF
	 PCRE2_NEWLINE_NUL	The NUL	character (binary zero)

       This identifies the character sequence that will	be recognized as mean-
       ing "newline" while matching.

	 PCRE2_INFO_SIZE

       Return  the  size  of  the compiled pattern in bytes (for all three li-
       braries). The third argument should point to a  size_t  variable.  This
       value  includes	the  size  of the general data block that precedes the
       code units of the compiled pattern itself. The value that is used  when
       pcre2_compile()	is  getting memory in which to place the compiled pat-
       tern may	be slightly larger than	the value returned by this option, be-
       cause there are cases where the code that calculates the	 size  has  to
       over-estimate.  Processing a pattern with the JIT compiler does not al-
       ter the value returned by this option.

INFORMATION ABOUT A PATTERN'S CALLOUTS

       int pcre2_callout_enumerate(const pcre2_code *code,
	 int (*callback)(pcre2_callout_enumerate_block *, void *),
	 void *user_data);

       A script	language that supports the use of string arguments in callouts
       might like to scan all the callouts in a	 pattern  before  running  the
       match. This can be done by calling pcre2_callout_enumerate(). The first
       argument	 is  a	pointer	 to a compiled pattern,	the second points to a
       callback	function, and the third	is arbitrary user data.	 The  callback
       function	 is  called  for  every	callout	in the pattern in the order in
       which they appear. Its first argument is	a pointer to a callout enumer-
       ation block, and	its second argument is the user_data  value  that  was
       passed  to  pcre2_callout_enumerate(). The contents of the callout enu-
       meration	block are described in the pcre2callout	 documentation,	 which
       also gives further details about	callouts.

SERIALIZATION AND PRECOMPILING

       It  is possible to save compiled	patterns on disc or elsewhere, and re-
       load them later,	subject	to a number of restrictions. The host on which
       the patterns are	reloaded must be running the same  version  of	PCRE2,
       with  the same code unit	width, and must	also have the same endianness,
       pointer width, and PCRE2_SIZE type. Before  compiled  patterns  can  be
       saved, they must	be converted to	a "serialized" form, which in the case
       of PCRE2	is really just a bytecode dump.	 The functions whose names be-
       gin with	pcre2_serialize_ are used for converting to and	from the seri-
       alized  form.  They  are	described in the pcre2serialize	documentation.
       Note that PCRE2 serialization does not convert compiled patterns	to  an
       abstract	format like Java or .NET serialization.

THE MATCH DATA BLOCK

       pcre2_match_data	*pcre2_match_data_create(uint32_t ovecsize,
	 pcre2_general_context *gcontext);

       pcre2_match_data	*pcre2_match_data_create_from_pattern(
	 const pcre2_code *code, pcre2_general_context *gcontext);

       void pcre2_match_data_free(pcre2_match_data *match_data);

       Information  about  a  successful  or unsuccessful match	is placed in a
       match data block, which is an opaque  structure	that  is  accessed  by
       function	 calls.	 In particular,	the match data block contains a	vector
       of offsets into the subject string that define the matched parts	of the
       subject.	This is	known as the ovector.

       Before calling pcre2_match(), pcre2_dfa_match(),	 or  pcre2_jit_match()
       you must	create a match data block by calling one of the	creation func-
       tions  above.  For pcre2_match_data_create(), the first argument	is the
       number of pairs of offsets in the ovector.

       When using pcre2_match(), one pair of offsets is	required  to  identify
       the  string that	matched	the whole pattern, with	an additional pair for
       each captured substring.	For example, a value of	4 creates enough space
       to record the matched portion of	the subject plus three	captured  sub-
       strings.

       When  using  pcre2_dfa_match() there may	be multiple matched substrings
       of different lengths at the same	point  in  the	subject.  The  ovector
       should be made large enough to hold as many as are expected.

       A  minimum  of at least 1 pair is imposed by pcre2_match_data_create(),
       so it is	always possible	to return the overall matched  string  in  the
       case   of   pcre2_match()   or	the  longest  match  in	 the  case  of
       pcre2_dfa_match(). The maximum number of	pairs is 65535;	if  the	 first
       argument	 of  pcre2_match_data_create()	is greater than	this, 65535 is
       used.

       The second argument of pcre2_match_data_create()	is a pointer to	a gen-
       eral context, which can specify custom memory management	for  obtaining
       the memory for the match	data block. If you are not using custom	memory
       management, pass	NULL, which causes malloc() to be used.

       For  pcre2_match_data_create_from_pattern(),  the  first	 argument is a
       pointer to a compiled pattern. The ovector is created to	be exactly the
       right size to hold all the substrings  a	 pattern  might	 capture  when
       matched using pcre2_match(). You	should not use this call when matching
       with  pcre2_dfa_match().	 The  second  argument is again	a pointer to a
       general context,	but in this case if NULL is passed, the	memory is  ob-
       tained  using the same allocator	that was used for the compiled pattern
       (custom or default).

       A match data block can be used many times, with the same	 or  different
       compiled	 patterns. You can extract information from a match data block
       after a match operation has finished,  using  functions	that  are  de-
       scribed in the sections on matched strings and other match data below.

       When  a	call  of  pcre2_match()	 fails,	valid data is available	in the
       match block only	 when  the  error  is  PCRE2_ERROR_NOMATCH,  PCRE2_ER-
       ROR_PARTIAL,  or	 one of	the error codes	for an invalid UTF string. Ex-
       actly what is available depends on the error, and is detailed below.

       When one	of the matching	functions is called, pointers to the  compiled
       pattern	and the	subject	string are set in the match data block so that
       they can	be referenced by the extraction	functions after	 a  successful
       match. After running a match, you must not free a compiled pattern or a
       subject	string until after all operations on the match data block (for
       that match) have	taken place,  unless,  in  the	case  of  the  subject
       string,	you  have used the PCRE2_COPY_MATCHED_SUBJECT option, which is
       described in the	section	entitled "Option bits for  pcre2_match()"  be-
       low.

       When  a match data block	itself is no longer needed, it should be freed
       by calling pcre2_match_data_free(). If this function is called  with  a
       NULL argument, it returns immediately, without doing anything.

MEMORY USE FOR MATCH DATA BLOCKS

       PCRE2_SIZE pcre2_get_match_data_size(pcre2_match_data *match_data);

       PCRE2_SIZE pcre2_get_match_data_heapframes_size(
	 pcre2_match_data *match_data);

       The  size of a match data block depends on the size of the ovector that
       it contains. The	function pcre2_get_match_data_size() returns the size,
       in bytes, of the	block that is its argument.

       When pcre2_match() runs interpretively (that is,	without	using JIT), it
       makes use of a vector of	data frames for	remembering backtracking posi-
       tions.  The size	of each	individual frame depends on the	number of cap-
       turing parentheses in the  pattern  and	can  be	 obtained  by  calling
       pcre2_pattern_info() with the PCRE2_INFO_FRAMESIZE option (see the sec-
       tion entitled "Information about	a compiled pattern" above).

       Heap  memory is used for	the frames vector; if the initial memory block
       turns out to be too small during	 matching,  it	is  automatically  ex-
       panded.	When  pcre2_match()  returns, the memory is not	freed, but re-
       mains attached to the match data	 block,	 for  use  by  any  subsequent
       matches	that  use  the	same block. It is automatically	freed when the
       match data block	itself is freed.

       You can find the	current	size of	the frames vector that	a  match  data
       block  owns  by	calling	 pcre2_get_match_data_heapframes_size(). For a
       newly created match data	block the size will be	zero.  Some  types  of
       match may require a lot of frames and thus a large vector; applications
       that run	in environments	where memory is	constrained can	check this and
       free the	match data block if the	heap frames vector has become too big.

MATCHING A PATTERN: THE	TRADITIONAL FUNCTION

       int pcre2_match(const pcre2_code	*code, PCRE2_SPTR subject,
	 PCRE2_SIZE length, PCRE2_SIZE startoffset,
	 uint32_t options, pcre2_match_data *match_data,
	 pcre2_match_context *mcontext);

       The  function pcre2_match() is called to	match a	subject	string against
       a compiled pattern, which is passed in the code argument. You can  call
       pcre2_match() with the same code	argument as many times as you like, in
       order  to  find multiple	matches	in the subject string or to match dif-
       ferent subject strings with the same pattern.

       This function is	the main matching facility of the library, and it  op-
       erates  in  a Perl-like manner. For specialist use there	is also	an al-
       ternative matching function, which is described below  in  the  section
       about the pcre2_dfa_match() function.

       Here is an example of a simple call to pcre2_match():

	 pcre2_match_data *md =	pcre2_match_data_create(4, NULL);
	 int rc	= pcre2_match(
	   re,		   /* result of	pcre2_compile()	*/
	   "some string",  /* the subject string */
	   11,		   /* the length of the	subject	string */
	   0,		   /* start at offset 0	in the subject */
	   0,		   /* default options */
	   md,		   /* the match	data block */
	   NULL);	   /* a	match context; NULL means use defaults */

       If  the	subject	 string	is zero-terminated, the	length can be given as
       PCRE2_ZERO_TERMINATED. A	match context must be provided if certain less
       common matching parameters are to be changed. For details, see the sec-
       tion on the match context above.

   The string to be matched by pcre2_match()

       The subject string is passed to pcre2_match() as	a pointer in  subject,
       a  length  in  length, and a starting offset in startoffset. The	length
       and offset are in code units, not characters.  That  is,	 they  are  in
       bytes  for the 8-bit library, 16-bit code units for the 16-bit library,
       and 32-bit code units for the 32-bit library, whether or	not  UTF  pro-
       cessing is enabled. As a	special	case, if subject is NULL and length is
       zero,  the  subject is assumed to be an empty string. If	length is non-
       zero, an	error occurs if	subject	is NULL.

       If startoffset is greater than the length of the	subject, pcre2_match()
       returns PCRE2_ERROR_BADOFFSET. When the starting	offset	is  zero,  the
       search  for a match starts at the beginning of the subject, and this is
       by far the most common case. In UTF-8 or	UTF-16 mode, the starting off-
       set must	point to the start of a	character, or to the end of  the  sub-
       ject  (in  UTF-32 mode, one code	unit equals one	character, so all off-
       sets are	valid).	Like the pattern string, the subject may  contain  bi-
       nary zeros.

       A  non-zero  starting offset is useful when searching for another match
       in the same subject by calling pcre2_match()  again  after  a  previous
       success.	  Setting  startoffset	differs	 from passing over a shortened
       string and setting PCRE2_NOTBOL in the case of a	 pattern  that	begins
       with any	kind of	lookbehind. For	example, consider the pattern

	 \Biss\B

       which  finds  occurrences  of "iss" in the middle of words. (\B matches
       only if the current position in the subject is not  a  word  boundary.)
       When   applied	to   the   string  "Mississippi"  the  first  call  to
       pcre2_match() finds the first occurrence. If  pcre2_match()  is	called
       again with just the remainder of	the subject, namely "issippi", it does
       not  match,  because  \B	 is  always false at the start of the subject,
       which is	deemed to be a word boundary.  However,	 if  pcre2_match()  is
       passed the entire string	again, but with	startoffset set	to 4, it finds
       the  second  occurrence	of "iss" because it is able to look behind the
       starting	point to discover that it is preceded by a letter.

       Finding all the matches in a subject is tricky  when  the  pattern  can
       match an	empty string. It is possible to	emulate	Perl's /g behaviour by
       first   trying	the   match   again  at	 the  same  offset,  with  the
       PCRE2_NOTEMPTY_ATSTART and PCRE2_ANCHORED options,  and	then  if  that
       fails,  advancing  the  starting	 offset	 and  trying an	ordinary match
       again. There is some code that demonstrates  how	 to  do	 this  in  the
       pcre2demo  sample  program. In the most general case, you have to check
       to see if the newline convention	recognizes CRLF	as a newline,  and  if
       so,  and	the current character is CR followed by	LF, advance the	start-
       ing offset by two characters instead of one.

       If a non-zero starting offset is	passed when the	pattern	is anchored, a
       single attempt to match at the given offset is made. This can only suc-
       ceed if the pattern does	not require the	match to be at	the  start  of
       the  subject.  In other words, the anchoring must be the	result of set-
       ting the	PCRE2_ANCHORED option or the use of .* with PCRE2_DOTALL,  not
       by starting the pattern with ^ or \A.

   Option bits for pcre2_match()

       The unused bits of the options argument for pcre2_match() must be zero.
       The    only    bits    that    may    be	   set	 are   PCRE2_ANCHORED,
       PCRE2_COPY_MATCHED_SUBJECT, PCRE2_DISABLE_RECURSELOOP_CHECK,  PCRE2_EN-
       DANCHORED,	PCRE2_NOTBOL,	    PCRE2_NOTEOL,      PCRE2_NOTEMPTY,
       PCRE2_NOTEMPTY_ATSTART,	PCRE2_NO_JIT,  PCRE2_NO_UTF_CHECK,  PCRE2_PAR-
       TIAL_HARD, and PCRE2_PARTIAL_SOFT.  Their action	is described below.

       Setting	PCRE2_ANCHORED	or PCRE2_ENDANCHORED at	match time is not sup-
       ported by the just-in-time (JIT)	compiler. If it	is set,	 JIT  matching
       is  disabled  and  the  interpretive  code  in  pcre2_match()  is  run.
       PCRE2_DISABLE_RECURSELOOP_CHECK is  ignored  by	JIT,  but  apart  from
       PCRE2_NO_JIT  (obviously),  the remaining options are supported for JIT
       matching.

	 PCRE2_ANCHORED

       The PCRE2_ANCHORED option limits	pcre2_match() to matching at the first
       matching	position. If a pattern was compiled  with  PCRE2_ANCHORED,  or
       turned  out to be anchored by virtue of its contents, it	cannot be made
       unachored at matching time. Note	that setting the option	at match  time
       disables	JIT matching.

	 PCRE2_COPY_MATCHED_SUBJECT

       By  default,  a	pointer	to the subject is remembered in	the match data
       block so	that, after a successful match,	it can be  referenced  by  the
       substring  extraction  functions.  This means that the subject's	memory
       must not	be freed until all such	operations are complete. For some  ap-
       plications  where the lifetime of the subject string is not guaranteed,
       it may be necessary to make a copy of the subject  string,  but	it  is
       wasteful	 to do this unless the match is	successful. After a successful
       match, if PCRE2_COPY_MATCHED_SUBJECT is set, the	subject	is copied  and
       the  new	 pointer  is remembered	in the match data block	instead	of the
       original	subject	pointer. The memory allocator that was	used  for  the
       match  block  itself  is	 used.	The  copy  is automatically freed when
       pcre2_match_data_free() is called to free the match data	block.	It  is
       also automatically freed	if the match data block	is re-used for another
       match operation.

	 PCRE2_DISABLE_RECURSELOOP_CHECK

       This  option  is	relevant only to pcre2_match() for interpretive	match-
       ing.   It  is  ignored  when  JIT  is  used,  and  is   forbidden   for
       pcre2_dfa_match().

       The use of recursion in patterns	can lead to infinite loops. In the in-
       terpretive  matcher  these  would  be eventually	caught by the match or
       heap limits, but	this could take	a long time and/or use a lot of	memory
       if the limits are large.	There is therefore a check  at	the  start  of
       each  recursion.	  If  the  same	 group is still	active from a previous
       call, and the current subject pointer is	the same  as  it  was  at  the
       start  of  that group, and the furthest inspected character of the sub-
       ject has	not changed, an	error is generated.

       There are rare cases of matches that would complete,  but  nevertheless
       trigger	this  error.  This  option  disables the check.	It is provided
       mainly for testing when comparing JIT and interpretive behaviour.

	 PCRE2_ENDANCHORED

       If the PCRE2_ENDANCHORED	option is set, any string  that	 pcre2_match()
       matches	must be	right at the end of the	subject	string.	Note that set-
       ting the	option at match	time disables JIT matching.

	 PCRE2_NOTBOL

       This option specifies that first	character of the subject string	is not
       the beginning of	a line,	so the	circumflex  metacharacter  should  not
       match  before  it.  Setting  this without having	set PCRE2_MULTILINE at
       compile time causes circumflex never to match. This option affects only
       the behaviour of	the circumflex metacharacter. It does not affect \A.

	 PCRE2_NOTEOL

       This option specifies that the end of the subject string	is not the end
       of a line, so the dollar	metacharacter should not match it nor  (except
       in  multiline mode) a newline immediately before	it. Setting this with-
       out having set PCRE2_MULTILINE at compile time causes dollar  never  to
       match. This option affects only the behaviour of	the dollar metacharac-
       ter. It does not	affect \Z or \z.

	 PCRE2_NOTEMPTY

       An empty	string is not considered to be a valid match if	this option is
       set.  If	 there are alternatives	in the pattern,	they are tried.	If all
       the alternatives	match the empty	string,	the entire  match  fails.  For
       example,	if the pattern

	 a?b?

       is  applied  to	a  string not beginning	with "a" or "b", it matches an
       empty string at the start of the	subject. With PCRE2_NOTEMPTY set, this
       match is	not valid, so pcre2_match() searches further into  the	string
       for occurrences of "a" or "b".

	 PCRE2_NOTEMPTY_ATSTART

       This  is	 like PCRE2_NOTEMPTY, except that it locks out an empty	string
       match only at the first matching	position, that is, at the start	of the
       subject plus the	starting offset. An empty string match	later  in  the
       subject is permitted.  If the pattern is	anchored, such a match can oc-
       cur only	if the pattern contains	\K.

	 PCRE2_NO_JIT

       By   default,   if   a  pattern	has  been  successfully	 processed  by
       pcre2_jit_compile(), JIT	is automatically used  when  pcre2_match()  is
       called  with  options  that JIT supports. Setting PCRE2_NO_JIT disables
       the use of JIT; it forces matching to be	done by	the interpreter.

	 PCRE2_NO_UTF_CHECK

       When PCRE2_UTF is set at	compile	time, the validity of the subject as a
       UTF  string  is	checked	 unless	 PCRE2_NO_UTF_CHECK   is   passed   to
       pcre2_match() or	PCRE2_MATCH_INVALID_UTF	was passed to pcre2_compile().
       The latter special case is discussed in detail in the pcre2unicode doc-
       umentation.

       In  the default case, if	a non-zero starting offset is given, the check
       is applied only to that part of the subject  that  could	 be  inspected
       during  matching,  and there is a check that the	starting offset	points
       to the first code unit of a character or	to the end of the subject.  If
       there  are no lookbehind	assertions in the pattern, the check starts at
       the starting offset.  Otherwise,	it starts at the length	of the longest
       lookbehind before the starting offset, or at the	start of  the  subject
       if  there are not that many characters before the starting offset. Note
       that the	sequences \b and \B are	one-character lookbehinds.

       The check is carried out	before any other processing takes place, and a
       negative	error code is returned if the check fails. There  are  several
       UTF  error  codes  for each code	unit width, corresponding to different
       problems	with the code unit sequence. There are discussions  about  the
       validity	 of  UTF-8  strings, UTF-16 strings, and UTF-32	strings	in the
       pcre2unicode documentation.

       If you know that	your subject is	valid, and you want to skip this check
       for performance reasons,	you can	set the	PCRE2_NO_UTF_CHECK option when
       calling pcre2_match(). You might	want to	do this	 for  the  second  and
       subsequent  calls  to pcre2_match() if you are making repeated calls to
       find multiple matches in	the same subject string.

       Warning:	Unless PCRE2_MATCH_INVALID_UTF was set at compile  time,  when
       PCRE2_NO_UTF_CHECK  is  set  at match time the effect of	passing	an in-
       valid string as a subject, or an	invalid	value of startoffset, is unde-
       fined.  Your program may	crash or loop indefinitely or give  wrong  re-
       sults.

	 PCRE2_PARTIAL_HARD
	 PCRE2_PARTIAL_SOFT

       These options turn on the partial matching feature. A partial match oc-
       curs  if	 the  end  of  the subject string is reached successfully, but
       there are not enough subject characters to complete the match. In addi-
       tion, either at least one character must	have  been  inspected  or  the
       pattern	must  contain  a  lookbehind,  or the pattern must be one that
       could match an empty string.

       If this situation arises	when PCRE2_PARTIAL_SOFT	 (but  not  PCRE2_PAR-
       TIAL_HARD) is set, matching continues by	testing	any remaining alterna-
       tives.  Only  if	 no complete match can be found	is PCRE2_ERROR_PARTIAL
       returned	instead	of PCRE2_ERROR_NOMATCH.	 In  other  words,  PCRE2_PAR-
       TIAL_SOFT  specifies  that  the	caller is prepared to handle a partial
       match, but only if no complete match can	be found.

       If PCRE2_PARTIAL_HARD is	set, it	overrides PCRE2_PARTIAL_SOFT. In  this
       case,  if  a  partial match is found, pcre2_match() immediately returns
       PCRE2_ERROR_PARTIAL, without considering	 any  other  alternatives.  In
       other words, when PCRE2_PARTIAL_HARD is set, a partial match is consid-
       ered to be more important that an alternative complete match.

       There is	a more detailed	discussion of partial and multi-segment	match-
       ing, with examples, in the pcre2partial documentation.

NEWLINE	HANDLING WHEN MATCHING

       When  PCRE2 is built, a default newline convention is set; this is usu-
       ally the	standard convention for	the operating system. The default  can
       be  overridden  in a compile context by calling pcre2_set_newline(). It
       can also	be overridden by starting a pattern string with, for  example,
       (*CRLF),	 as  described	in  the	 section on newline conventions	in the
       pcre2pattern page. During matching, the newline choice affects the  be-
       haviour	of the dot, circumflex,	and dollar metacharacters. It may also
       alter the way the match starting	position is  advanced  after  a	 match
       failure for an unanchored pattern.

       When PCRE2_NEWLINE_CRLF,	PCRE2_NEWLINE_ANYCRLF, or PCRE2_NEWLINE_ANY is
       set  as	the  newline convention, and a match attempt for an unanchored
       pattern fails when the current starting position	is at a	CRLF sequence,
       and the pattern contains	no explicit matches for	CR or  LF  characters,
       the  match  position  is	 advanced by two characters instead of one, in
       other words, to after the CRLF.

       The above rule is a compromise that makes the most common cases work as
       expected. For example, if the pattern is	.+A (and the PCRE2_DOTALL  op-
       tion  is	 not set), it does not match the string	"\r\nA"	because, after
       failing at the start, it	skips both the CR and the LF before  retrying.
       However,	 the  pattern  [\r\n]A does match that string, because it con-
       tains an	explicit CR or LF reference, and so advances only by one char-
       acter after the first failure.

       An explicit match for CR	of LF is either	a literal appearance of	one of
       those characters	in the pattern,	or one of the \r or \n	or  equivalent
       octal or	hexadecimal escape sequences. Implicit matches such as [^X] do
       not  count, nor does \s,	even though it includes	CR and LF in the char-
       acters that it matches.

       Notwithstanding the above, anomalous effects may	still occur when  CRLF
       is a valid newline sequence and explicit	\r or \n escapes appear	in the
       pattern.

HOW PCRE2_MATCH() RETURNS A STRING AND CAPTURED	SUBSTRINGS

       uint32_t	pcre2_get_ovector_count(pcre2_match_data *match_data);

       PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *match_data);

       In  general, a pattern matches a	certain	portion	of the subject,	and in
       addition, further substrings from the subject  may  be  picked  out  by
       parenthesized  parts  of	 the  pattern.	Following the usage in Jeffrey
       Friedl's	book, this is called "capturing"  in  what  follows,  and  the
       phrase  "capture	 group"	(Perl terminology) is used for a fragment of a
       pattern that picks out a	substring. PCRE2 supports several other	 kinds
       of parenthesized	group that do not cause	substrings to be captured. The
       pcre2_pattern_info()  function can be used to find out how many capture
       groups there are	in a compiled pattern.

       You can use auxiliary functions for accessing  captured	substrings  by
       number or by name, as described in sections below.

       Alternatively, you can make direct use of the vector of PCRE2_SIZE val-
       ues,  called  the  ovector,  which  contains  the  offsets  of captured
       strings.	 It  is	 part  of  the	match  data   block.	The   function
       pcre2_get_ovector_pointer()  returns  the  address  of the ovector, and
       pcre2_get_ovector_count() returns the number of pairs of	values it con-
       tains.

       Within the ovector, the first in	each pair of values is set to the off-
       set of the first	code unit of a substring, and the second is set	to the
       offset of the first code	unit after the end of a	substring. These  val-
       ues  are	always code unit offsets, not character	offsets. That is, they
       are byte	offsets	in the 8-bit library, 16-bit offsets in	the 16-bit li-
       brary, and 32-bit offsets in the	32-bit library.

       After a partial match  (error  return  PCRE2_ERROR_PARTIAL),  only  the
       first  pair  of	offsets	 (that is, ovector[0] and ovector[1]) are set.
       They identify the part of the subject that was partially	 matched.  See
       the pcre2partial	documentation for details of partial matching.

       After  a	 fully	successful match, the first pair of offsets identifies
       the portion of the subject string that was matched by the  entire  pat-
       tern.  The  next	 pair is used for the first captured substring,	and so
       on. The value returned by pcre2_match() is one more  than  the  highest
       numbered	 pair  that  has been set. For example,	if two substrings have
       been captured, the returned value is 3. If there	are no	captured  sub-
       strings,	the return value from a	successful match is 1, indicating that
       just the	first pair of offsets has been set.

       If  a  pattern uses the \K escape sequence within a positive assertion,
       the reported start of a successful match	can be greater than the	end of
       the match.  For example,	if the pattern	(?=ab\K)  is  matched  against
       "ab", the start and end offset values for the match are 2 and 0.

       If  a  capture group is matched repeatedly within a single match	opera-
       tion, it	is the last portion of the subject that	it matched that	is re-
       turned.

       If the ovector is too small to hold all the captured substring offsets,
       as much as possible is filled in, and the function returns a  value  of
       zero.  If captured substrings are not of	interest, pcre2_match()	may be
       called with a match data	block whose ovector is of minimum length (that
       is, one pair).

       It is possible for capture group	number n+1 to match some part  of  the
       subject	when  group  n	has  not been used at all. For example,	if the
       string "abc" is matched against the pattern (a|(z))(bc) the return from
       the function is 4, and groups 1 and 3 are matched, but 2	is  not.  When
       this  happens,  both values in the offset pairs corresponding to	unused
       groups are set to PCRE2_UNSET.

       Offset values that correspond to	unused groups at the end  of  the  ex-
       pression	 are also set to PCRE2_UNSET. For example, if the string "abc"
       is matched against the pattern (abc)(x(yz)?)? groups 2 and  3  are  not
       matched.	 The  return  from the function	is 2, because the highest used
       capture group number is 1. The offsets for the second and third capture
       groups (assuming	the vector is large enough,  of	 course)  are  set  to
       PCRE2_UNSET.

       Elements	in the ovector that do not correspond to capturing parentheses
       in the pattern are never	changed. That is, if a pattern contains	n cap-
       turing parentheses, no more than	ovector[0] to ovector[2n+1] are	set by
       pcre2_match().  The  other  elements retain whatever values they	previ-
       ously had. After	a failed match attempt,	the contents  of  the  ovector
       are unchanged.

OTHER INFORMATION ABOUT	A MATCH

       PCRE2_SPTR pcre2_get_mark(pcre2_match_data *match_data);

       PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data);

       As  well	as the offsets in the ovector, other information about a match
       is retained in the match	data block and can be retrieved	by  the	 above
       functions  in  appropriate  circumstances.  If they are called at other
       times, the result is undefined.

       After a successful match, a partial match (PCRE2_ERROR_PARTIAL),	 or  a
       failure	to  match (PCRE2_ERROR_NOMATCH), a mark	name may be available.
       The function pcre2_get_mark() can be called to access this name,	 which
       can  be	specified  in  the  pattern by any of the backtracking control
       verbs, not just (*MARK).	The same function applies to all the verbs. It
       returns a pointer to the	zero-terminated	name, which is within the com-
       piled pattern. If no name is available, NULL is returned. The length of
       the name	(excluding the terminating zero) is stored in  the  code  unit
       that  precedes  the name. You should use	this length instead of relying
       on the terminating zero if the name might contain a binary zero.

       After a successful match, the name that is returned is  the  last  mark
       name encountered	on the matching	path through the pattern. Instances of
       backtracking  verbs  without  names do not count. Thus, for example, if
       the matching path contains (*MARK:A)(*PRUNE), the name "A" is returned.
       After a "no match" or a partial match, the last encountered name	is re-
       turned. For example, consider this pattern:

	 ^(*MARK:A)((*MARK:B)a|b)c

       When it matches "bc", the returned name is A. The B mark	is  "seen"  in
       the  first  branch of the group,	but it is not on the matching path. On
       the other hand, when this pattern fails to  match  "bx",	 the  returned
       name is B.

       Warning:	 By  default, certain start-of-match optimizations are used to
       give a fast "no match" result in	some situations. For example,  if  the
       anchoring  is removed from the pattern above, there is an initial check
       for the presence	of "c" in the subject before running the matching  en-
       gine. This check	fails for "bx",	causing	a match	failure	without	seeing
       any  marks. You can disable the start-of-match optimizations by setting
       the PCRE2_NO_START_OPTIMIZE option for pcre2_compile() or  by  starting
       the pattern with	(*NO_START_OPT).

       After  a	 successful  match, a partial match, or	one of the invalid UTF
       errors (for example, PCRE2_ERROR_UTF8_ERR5), pcre2_get_startchar()  can
       be called. After	a successful or	partial	match it returns the code unit
       offset  of  the character at which the match started. For a non-partial
       match, this can be different to the value of ovector[0] if the  pattern
       contains	 the  \K escape	sequence. After	a partial match, however, this
       value is	always the same	as ovector[0] because \K does not  affect  the
       result of a partial match.

       After  a	UTF check failure, pcre2_get_startchar() can be	used to	obtain
       the code	unit offset of the invalid UTF character. Details are given in
       the pcre2unicode	page.

ERROR RETURNS FROM pcre2_match()

       If pcre2_match()	fails, it returns a negative number. This can be  con-
       verted  to a text string	by calling the pcre2_get_error_message() func-
       tion (see "Obtaining a textual error message" below).   Negative	 error
       codes  are  also	 returned  by other functions, and are documented with
       them. The codes are given names in the header file. If UTF checking  is
       in force	and an invalid UTF subject string is detected, one of a	number
       of  UTF-specific	negative error codes is	returned. Details are given in
       the pcre2unicode	page. The following are	the other errors that  may  be
       returned	by pcre2_match():

	 PCRE2_ERROR_NOMATCH

       The subject string did not match	the pattern.

	 PCRE2_ERROR_PARTIAL

       The  subject  string did	not match, but it did match partially. See the
       pcre2partial documentation for details of partial matching.

	 PCRE2_ERROR_BADMAGIC

       PCRE2 stores a 4-byte "magic number" at the start of the	compiled code,
       to catch	the case when it is passed a junk pointer. This	is  the	 error
       that is returned	when the magic number is not present.

	 PCRE2_ERROR_BADMODE

       This  error is given when a compiled pattern is passed to a function in
       a library of a different	code unit width, for example, a	 pattern  com-
       piled  by  the  8-bit  library  is passed to a 16-bit or	32-bit library
       function.

	 PCRE2_ERROR_BADOFFSET

       The value of startoffset	was greater than the length of the subject.

	 PCRE2_ERROR_BADOPTION

       An unrecognized bit was set in the options argument.

	 PCRE2_ERROR_BADUTFOFFSET

       The UTF code unit sequence that was passed as a subject was checked and
       found to	be valid (the PCRE2_NO_UTF_CHECK option	was not	set), but  the
       value  of startoffset did not point to the beginning of a UTF character
       or the end of the subject.

	 PCRE2_ERROR_CALLOUT

       This error is never generated by	pcre2_match() itself. It  is  provided
       for  use	 by  callout  functions	 that  want  to	cause pcre2_match() or
       pcre2_callout_enumerate() to return a distinctive error code.  See  the
       pcre2callout documentation for details.

	 PCRE2_ERROR_DEPTHLIMIT

       The nested backtracking depth limit was reached.

	 PCRE2_ERROR_HEAPLIMIT

       The heap	limit was reached.

	 PCRE2_ERROR_INTERNAL

       An  unexpected  internal	error has occurred. This error could be	caused
       by a bug	in PCRE2 or by overwriting of the compiled pattern.

	 PCRE2_ERROR_JIT_STACKLIMIT

       This error is returned when a pattern that was successfully studied us-
       ing JIT is being	matched, but the memory	available for the just-in-time
       processing stack	is not large enough. See  the  pcre2jit	 documentation
       for more	details.

	 PCRE2_ERROR_MATCHLIMIT

       The backtracking	match limit was	reached.

	 PCRE2_ERROR_NOMEMORY

       Heap  memory  is	 used  to  remember backtracking points. This error is
       given when the memory allocation	function (default  or  custom)	fails.
       Note  that  a  different	 error,	PCRE2_ERROR_HEAPLIMIT, is given	if the
       amount of memory	needed exceeds the heap	limit. PCRE2_ERROR_NOMEMORY is
       also returned if	PCRE2_COPY_MATCHED_SUBJECT is set and  memory  alloca-
       tion fails.

	 PCRE2_ERROR_NULL

       Either the code,	subject, or match_data argument	was passed as NULL.

	 PCRE2_ERROR_RECURSELOOP

       This  error  is	returned  when	pcre2_match() detects a	recursion loop
       within the pattern. Specifically, it means that either the  whole  pat-
       tern or a capture group has been	called recursively for the second time
       at  the	same position in the subject string. Some simple patterns that
       might do	this are detected and faulted at compile time, but  more  com-
       plicated	 cases,	 in particular mutual recursions between two different
       groups, cannot be detected until	matching is attempted.

OBTAINING A TEXTUAL ERROR MESSAGE

       int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer,
	 PCRE2_SIZE bufflen);

       A text message for an error code	 from  any  PCRE2  function  (compile,
       match,  or  auxiliary)  can be obtained by calling pcre2_get_error_mes-
       sage(). The code	is passed as the first argument,  with	the  remaining
       two  arguments  specifying  a  code  unit buffer	and its	length in code
       units, into which the text message is placed. The message  is  returned
       in  code	 units	of the appropriate width for the library that is being
       used.

       The returned message is terminated with a trailing zero,	and the	 func-
       tion  returns  the  number  of  code units used,	excluding the trailing
       zero. If	the error number is unknown, the negative error	code PCRE2_ER-
       ROR_BADDATA is returned.	If the buffer is too  small,  the  message  is
       truncated (but still with a trailing zero), and the negative error code
       PCRE2_ERROR_NOMEMORY  is	returned.  None	of the messages	are very long;
       a buffer	size of	120 code units is ample.

EXTRACTING CAPTURED SUBSTRINGS BY NUMBER

       int pcre2_substring_length_bynumber(pcre2_match_data *match_data,
	 uint32_t number, PCRE2_SIZE *length);

       int pcre2_substring_copy_bynumber(pcre2_match_data *match_data,
	 uint32_t number, PCRE2_UCHAR *buffer,
	 PCRE2_SIZE *bufflen);

       int pcre2_substring_get_bynumber(pcre2_match_data *match_data,
	 uint32_t number, PCRE2_UCHAR **bufferptr,
	 PCRE2_SIZE *bufflen);

       void pcre2_substring_free(PCRE2_UCHAR *buffer);

       Captured	substrings can be accessed directly by using  the  ovector  as
       described above.	 For convenience, auxiliary functions are provided for
       extracting   captured  substrings  as  new,  separate,  zero-terminated
       strings.	A substring that contains a binary zero	is correctly extracted
       and has a further zero added on the end,	but  the  result  is  not,  of
       course, a C string.

       The functions in	this section identify substrings by number. The	number
       zero refers to the entire matched substring, with higher	numbers	refer-
       ring  to	 substrings  captured by parenthesized groups. After a partial
       match, only substring zero is available.	 An  attempt  to  extract  any
       other  substring	 gives the error PCRE2_ERROR_PARTIAL. The next section
       describes similar functions for extracting captured substrings by name.

       If a pattern uses the \K	escape sequence	within a  positive  assertion,
       the reported start of a successful match	can be greater than the	end of
       the  match.   For  example,  if the pattern (?=ab\K) is matched against
       "ab", the start and end offset values for the match are	2  and	0.  In
       this  situation,	 calling  these	functions with a zero substring	number
       extracts	a zero-length empty string.

       You can find the	length in code units of	a captured  substring  without
       extracting  it  by calling pcre2_substring_length_bynumber(). The first
       argument	is a pointer to	the match data block, the second is the	 group
       number,	and the	third is a pointer to a	variable into which the	length
       is placed. If you just want to know whether or not  the	substring  has
       been captured, you can pass the third argument as NULL.

       The  pcre2_substring_copy_bynumber()  function  copies  a captured sub-
       string into a supplied buffer,  whereas	pcre2_substring_get_bynumber()
       copies  it  into	 new memory, obtained using the	same memory allocation
       function	that was used for the match data block.	The  first  two	 argu-
       ments  of  these	 functions are a pointer to the	match data block and a
       capture group number.

       The final arguments of pcre2_substring_copy_bynumber() are a pointer to
       the buffer and a	pointer	to a variable that contains its	length in code
       units.  This is updated to contain the actual number of code units used
       for the extracted substring, excluding the terminating zero.

       For pcre2_substring_get_bynumber() the third and	fourth arguments point
       to variables that are updated with a pointer to the new memory and  the
       number  of  code	units that comprise the	substring, again excluding the
       terminating zero. When the substring is no longer  needed,  the	memory
       should be freed by calling pcre2_substring_free().

       The  return  value  from	 all these functions is	zero for success, or a
       negative	error code. If the pattern match  failed,  the	match  failure
       code  is	returned.  If a	substring number greater than zero is used af-
       ter a partial match, PCRE2_ERROR_PARTIAL	is  returned.  Other  possible
       error codes are:

	 PCRE2_ERROR_NOMEMORY

       The  buffer  was	 too small for pcre2_substring_copy_bynumber(),	or the
       attempt to get memory failed for	pcre2_substring_get_bynumber().

	 PCRE2_ERROR_NOSUBSTRING

       There is	no substring with that number in the  pattern,	that  is,  the
       number is greater than the number of capturing parentheses.

	 PCRE2_ERROR_UNAVAILABLE

       The substring number, though not	greater	than the number	of captures in
       the pattern, is greater than the	number of slots	in the ovector,	so the
       substring could not be captured.

	 PCRE2_ERROR_UNSET

       The  substring  did  not	 participate in	the match. For example,	if the
       pattern is (abc)|(def) and the subject is "def",	and the	 ovector  con-
       tains at	least two capturing slots, substring number 1 is unset.

EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS

       int pcre2_substring_list_get(pcre2_match_data *match_data,
	 PCRE2_UCHAR ***listptr, PCRE2_SIZE **lengthsptr);

       void pcre2_substring_list_free(PCRE2_UCHAR **list);

       The  pcre2_substring_list_get()	function  extracts  all	available sub-
       strings and builds a list of pointers to	 them.	It  also  (optionally)
       builds  a  second list that contains their lengths (in code units), ex-
       cluding a terminating zero that is added	to each	of them. All  this  is
       done in a single	block of memory	that is	obtained using the same	memory
       allocation function that	was used to get	the match data block.

       This  function  must be called only after a successful match. If	called
       after a partial match, the error	code PCRE2_ERROR_PARTIAL is returned.

       The address of the memory block is returned via listptr,	which is  also
       the start of the	list of	string pointers. The end of the	list is	marked
       by  a  NULL pointer. The	address	of the list of lengths is returned via
       lengthsptr. If your strings do not contain binary zeros and you do  not
       therefore need the lengths, you may supply NULL as the lengthsptr argu-
       ment  to	 disable  the  creation	of a list of lengths. The yield	of the
       function	is zero	if all went well, or PCRE2_ERROR_NOMEMORY if the  mem-
       ory  block could	not be obtained. When the list is no longer needed, it
       should be freed by calling pcre2_substring_list_free().

       If this function	encounters a substring that is unset, which can	happen
       when capture group number n+1 matches some part	of  the	 subject,  but
       group  n	has not	been used at all, it returns an	empty string. This can
       be distinguished	from a genuine zero-length substring by	inspecting the
       appropriate offset in the ovector, which	contain	PCRE2_UNSET for	 unset
       substrings, or by calling pcre2_substring_length_bynumber().

EXTRACTING CAPTURED SUBSTRINGS BY NAME

       int pcre2_substring_number_from_name(const pcre2_code *code,
	 PCRE2_SPTR name);

       int pcre2_substring_length_byname(pcre2_match_data *match_data,
	 PCRE2_SPTR name, PCRE2_SIZE *length);

       int pcre2_substring_copy_byname(pcre2_match_data	*match_data,
	 PCRE2_SPTR name, PCRE2_UCHAR *buffer, PCRE2_SIZE *bufflen);

       int pcre2_substring_get_byname(pcre2_match_data *match_data,
	 PCRE2_SPTR name, PCRE2_UCHAR **bufferptr, PCRE2_SIZE *bufflen);

       void pcre2_substring_free(PCRE2_UCHAR *buffer);

       To  extract a substring by name,	you first have to find associated num-
       ber.  For example, for this pattern:

	 (a+)b(?<xxx>\d+)...

       the number of the capture group called "xxx" is 2. If the name is known
       to be unique (PCRE2_DUPNAMES was	not set), you can find the number from
       the name	by calling pcre2_substring_number_from_name(). The first argu-
       ment is the compiled pattern, and the second is the name. The yield  of
       the  function  is the group number, PCRE2_ERROR_NOSUBSTRING if there is
       no group	with that name,	or PCRE2_ERROR_NOUNIQUESUBSTRING if  there  is
       more  than one group with that name.  Given the number, you can extract
       the substring directly from the ovector,	or use one of  the  "bynumber"
       functions described above.

       For  convenience,  there	are also "byname" functions that correspond to
       the "bynumber" functions, the only difference being that	the second ar-
       gument is a name	instead	of a number.  If  PCRE2_DUPNAMES  is  set  and
       there are duplicate names, these	functions scan all the groups with the
       given  name,  and  return  the  captured	substring from the first named
       group that is set.

       If there	are no groups with the given name, PCRE2_ERROR_NOSUBSTRING  is
       returned.  If  all  groups  with	the name have numbers that are greater
       than the	number of slots	in the ovector,	PCRE2_ERROR_UNAVAILABLE	is re-
       turned. If there	is at least one	group with a slot in the ovector,  but
       no group	is found to be set, PCRE2_ERROR_UNSET is returned.

       Warning:	If the pattern uses the	(?| feature to set up multiple capture
       groups  with  the same number, as described in the section on duplicate
       group numbers in	the pcre2pattern page, you cannot use names to distin-
       guish the different capture groups, because names are not  included  in
       the  compiled  code.  The  matching process uses	only numbers. For this
       reason, the use of different names for  groups  with  the  same	number
       causes an error at compile time.

CREATING A NEW STRING WITH SUBSTITUTIONS

       int pcre2_substitute(const pcre2_code *code, PCRE2_SPTR subject,
	 PCRE2_SIZE length, PCRE2_SIZE startoffset,
	 uint32_t options, pcre2_match_data *match_data,
	 pcre2_match_context *mcontext,	PCRE2_SPTR replacement,
	 PCRE2_SIZE rlength, PCRE2_UCHAR *outputbuffer,
	 PCRE2_SIZE *outlengthptr);

       This  function  optionally calls	pcre2_match() and then makes a copy of
       the subject string in outputbuffer, replacing parts that	 were  matched
       with the	replacement string, whose length is supplied in	rlength, which
       can  be given as	PCRE2_ZERO_TERMINATED for a zero-terminated string. As
       a special case, if replacement is NULL and rlength  is  zero,  the  re-
       placement  is assumed to	be an empty string. If rlength is non-zero, an
       error occurs if replacement is NULL.

       There is	an option (see PCRE2_SUBSTITUTE_REPLACEMENT_ONLY below)	to re-
       turn just the replacement string(s). The	default	action is  to  perform
       just  one  replacement  if  the pattern matches,	but there is an	option
       that requests multiple replacements  (see  PCRE2_SUBSTITUTE_GLOBAL  be-
       low).

       If  successful,	pcre2_substitute() returns the number of substitutions
       that were carried out. This may be zero if no match was found,  and  is
       never  greater  than one	unless PCRE2_SUBSTITUTE_GLOBAL is set. A nega-
       tive value is returned if an error is detected.

       Matches in which	a \K item in a lookahead in  the  pattern  causes  the
       match  to  end  before it starts	are not	supported, and give rise to an
       error return. For global	replacements, matches in which \K in a lookbe-
       hind causes the match to	start earlier than the point that was  reached
       in the previous iteration are also not supported.

       The  first  seven  arguments  of	pcre2_substitute() are the same	as for
       pcre2_match(), except that the partial matching options are not permit-
       ted, and	match_data may be passed as NULL, in which case	a  match  data
       block  is obtained and freed within this	function, using	memory manage-
       ment functions from the match context, if provided, or else those  that
       were used to allocate memory for	the compiled code.

       If  match_data is not NULL and PCRE2_SUBSTITUTE_MATCHED is not set, the
       provided	block is used for all calls to pcre2_match(), and its contents
       afterwards are the result of the	final call. For	global	changes,  this
       will always be a	no-match error.	The contents of	the ovector within the
       match data block	may or may not have been changed.

       As  well	as the usual options for pcre2_match(),	a number of additional
       options can be set in the options argument of pcre2_substitute().   One
       such  option is PCRE2_SUBSTITUTE_MATCHED. When this is set, an external
       match_data block	must be	provided, and it must have already  been  used
       for an external call to pcre2_match() with the same pattern and subject
       arguments.  The	data in	the match_data block (return code, offset vec-
       tor) is then  used  for	the  first  substitution  instead  of  calling
       pcre2_match()  from  within pcre2_substitute(). This allows an applica-
       tion to check for a match before	choosing to substitute,	without	having
       to repeat the match.

       The contents of the  externally	supplied  match	 data  block  are  not
       changed	 when	PCRE2_SUBSTITUTE_MATCHED   is  set.  If	 PCRE2_SUBSTI-
       TUTE_GLOBAL is also set,	pcre2_match() is called	after the  first  sub-
       stitution  to  check for	further	matches, but this is done using	an in-
       ternally	obtained match data block, thus	always	leaving	 the  external
       block unchanged.

       The  code  argument is not used for matching before the first substitu-
       tion when PCRE2_SUBSTITUTE_MATCHED is set, but  it  must	 be  provided,
       even  when  PCRE2_SUBSTITUTE_GLOBAL is not set, because it contains in-
       formation such as the UTF setting and the number	of capturing parenthe-
       ses in the pattern.

       The default action of pcre2_substitute()	is to return  a	 copy  of  the
       subject string with matched substrings replaced.	However, if PCRE2_SUB-
       STITUTE_REPLACEMENT_ONLY	 is  set,  only	the replacement	substrings are
       returned. In the	global case, multiple replacements are concatenated in
       the output buffer. Substitution callouts	(see below)  can  be  used  to
       separate	them if	necessary.

       The  outlengthptr  argument of pcre2_substitute() must point to a vari-
       able that contains the length, in code units, of	the output buffer.  If
       the  function is	successful, the	value is updated to contain the	length
       in code units of	the new	string,	excluding the trailing	zero  that  is
       automatically added.

       If  the	function is not	successful, the	value set via outlengthptr de-
       pends on	the type of  error.  For  syntax  errors  in  the  replacement
       string, the value is the	offset in the replacement string where the er-
       ror  was	 detected.  For	 other errors, the value is PCRE2_UNSET	by de-
       fault. This includes the	case of	the output buffer being	too small, un-
       less PCRE2_SUBSTITUTE_OVERFLOW_LENGTH is	set.

       PCRE2_SUBSTITUTE_OVERFLOW_LENGTH	changes	what happens when  the	output
       buffer is too small. The	default	action is to return PCRE2_ERROR_NOMEM-
       ORY  immediately.  If  this  option is set, however, pcre2_substitute()
       continues to go through the motions of matching and substituting	(with-
       out, of course, writing anything) in  order  to	compute	 the  size  of
       buffer  that is needed, which will include the extra space for the ter-
       minating	NUL. This value	is passed back via the outlengthptr  variable,
       with the	result of the function still being PCRE2_ERROR_NOMEMORY.

       Passing	a  buffer  size	 of zero is a permitted	way of finding out how
       much memory is needed for given substitution. However, this  does  mean
       that the	entire operation is carried out	twice. Depending on the	appli-
       cation,	it  may	 be more efficient to allocate a large buffer and free
       the  excess  afterwards,	 instead   of	using	PCRE2_SUBSTITUTE_OVER-
       FLOW_LENGTH.

       The  replacement	 string,  which	 is interpreted	as a UTF string	in UTF
       mode, is	checked	for UTF	validity unless	PCRE2_NO_UTF_CHECK is set.  An
       invalid UTF replacement string causes an	immediate return with the rel-
       evant UTF error code.

       If  PCRE2_SUBSTITUTE_LITERAL  is	set, the replacement string is not in-
       terpreted in any	way. By	default, however, a dollar character is	an es-
       cape character that can specify the insertion of	characters  from  cap-
       ture  groups  and names from (*MARK) or other control verbs in the pat-
       tern. Dollar is the only	escape character (backslash is treated as lit-
       eral). The following forms are recognized:

	 $$		     insert a dollar character
	 $n or ${n}	     insert the	contents of group n
	 $0 or $&	     insert the	entire matched substring
	 $`		     insert the	substring that precedes	the match
	 $'		     insert the	substring that follows the match
	 $_		     insert the	entire input string
	 $*MARK	or ${*MARK}  insert a control verb name

       Either a	group number or	a group	name can be given for n,  for  example
       $2  or $NAME. Curly brackets are	required only if the following charac-
       ter would be interpreted	as part	of the number or name. The number  may
       be  zero	to include the entire matched string. For example, if the pat-
       tern  a(b)c  is	matched	 with  "=abc="	and  the  replacement	string
       "+$1$0$1+", the result is "=+babcb+=".

       The  JavaScript	form $<name>, where the	angle brackets are part	of the
       syntax, is also recognized for group names, but not for	group  numbers
       or *MARK.

       $*MARK  inserts the name	from the last encountered backtracking control
       verb on the matching path that has a name. (*MARK) must always  include
       a  name,	 but  the  other  verbs	 need not. For example,	in the case of
       (*MARK:A)(*PRUNE) the name inserted is "A", but for (*MARK:A)(*PRUNE:B)
       the relevant name is "B". This facility can be used to  perform	simple
       simultaneous substitutions, as this pcre2test example shows:

	 /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK}
	     apple lemon
	  2: pear orange

       PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject
       string,	replacing every	matching substring. If this option is not set,
       only the	first matching substring is replaced. The search  for  matches
       takes  place in the original subject string (that is, previous replace-
       ments do	not affect it).	 Iteration is  implemented  by	advancing  the
       startoffset  value  for	each search, which is always passed the	entire
       subject string. If an offset limit is set in the	match context, search-
       ing stops when that limit is reached.

       You can restrict	the effect of a	global substitution to	a  portion  of
       the subject string by setting either or both of startoffset and an off-
       set limit. Here is a pcre2test example:

	 /B/g,replace=!,use_offset_limit
	 ABC ABC ABC ABC\=offset=3,offset_limit=12
	  2: ABC A!C A!C ABC

       When  continuing	 with  global substitutions after matching a substring
       with zero length, an attempt to find a non-empty	match at the same off-
       set is performed.  If this is not successful, the offset	is advanced by
       one character except when CRLF is a valid newline sequence and the next
       two characters are CR, LF. In this case,	the offset is advanced by  two
       characters.

       PCRE2_SUBSTITUTE_UNKNOWN_UNSET causes references	to capture groups that
       do not appear in	the pattern to be treated as unset groups. This	option
       should  be used with care, because it means that	a typo in a group name
       or number no longer causes the PCRE2_ERROR_NOSUBSTRING error.

       PCRE2_SUBSTITUTE_UNSET_EMPTY causes unset capture groups	(including un-
       known groups when PCRE2_SUBSTITUTE_UNKNOWN_UNSET	is set)	to be  treated
       as  empty  strings  when	inserted as described above. If	this option is
       not set,	an attempt to insert an	unset group causes the PCRE2_ERROR_UN-
       SET error. This option does not	influence  the	extended  substitution
       syntax described	below.

       PCRE2_SUBSTITUTE_EXTENDED  causes extra processing to be	applied	to the
       replacement string. Without this	option,	only the dollar	 character  is
       special,	 and  only  the	 group insertion forms listed above are	valid.
       When PCRE2_SUBSTITUTE_EXTENDED is set, several things change:

       Firstly,	backslash in a replacement string is interpreted as an	escape
       character.  The usual forms such	as \x{ddd} can be used to specify par-
       ticular character codes,	and backslash followed by any non-alphanumeric
       character quotes	that character.	Extended quoting can  be  coded	 using
       \Q...\E,	 exactly  as in	pattern	strings. The escapes \b	and \v are in-
       terpreted as the	characters backspace and vertical tab, respectively.

       The interpretation of backslash followed	by one or more digits  is  the
       same  as	 in a pattern, which in	Perl has some ambiguities. Details are
       given in	the pcre2pattern page.

       The Python form \g<n>, where the	angle brackets are part	of the	syntax
       and  n  is either a group name or number, is recognized as an altertive
       way of inserting	the contents of	a group, for example \g<3>.

       There are also four escape sequences for	forcing	the case  of  inserted
       letters.	  Case	forcing	 applies to all	inserted characters, including
       those from capture groups and letters within \Q...\E quoted  sequences.
       The  insertion mechanism	has three states: no case forcing, force upper
       case, and force lower case. The escape  sequences  change  the  current
       state:  \U  and \L change to upper or lower case	forcing, respectively,
       and \E (when not	terminating a \Q quoted	sequence) reverts to  no  case
       forcing.	 The  sequences	\u and \l force	the next character (if it is a
       letter) to upper	or lower case, respectively, and then the state	 auto-
       matically reverts to no case forcing.

       However,	 if \u is immediately followed by \L or	\l is immediately fol-
       lowed by	\U, the	next character's case is forced	by  the	 first	escape
       sequence, and subsequent	characters by the second. This provides	a "ti-
       tle  casing"  facility that can be applied to group captures. For exam-
       ple, if group 1 has captured "heLLo", the replacement  string  "\u\L$1"
       becomes "Hello".

       If either PCRE2_UTF or PCRE2_UCP	was set	when the pattern was compiled,
       Unicode	properties  are	 used  for  case forcing characters whose code
       points are greater than 127. However, only simple case folding, as  de-
       termined	 by  the Unicode file CaseFolding.txt is supported. PCRE2 does
       not support language-specific special casing rules such as  using  dif-
       ferent  lower case Greek	sigmas in the middle and ends of words (as de-
       fined in	the Unicode file SpecialCasing.txt).

       Note that case forcing sequences	such as	\U...\E	do not nest. For exam-
       ple, the	result of processing "\Uaa\LBB\Ecc\E" is "AAbbcc";  the	 final
       \E  has	no  effect.  Note  also	 that the PCRE2_ALT_BSUX and PCRE2_EX-
       TRA_ALT_BSUX options do not apply to replacement	strings.

       The final effect	of setting PCRE2_SUBSTITUTE_EXTENDED is	 to  add  more
       flexibility  to	capture	 group	substitution. The syntax is similar to
       that used by Bash:

	 ${n:-string}
	 ${n:+string1:string2}

       As in the simple	case, n	may be a group number or  a  name.  The	 first
       form  specifies	a  default  value. If group n is set, its value	is in-
       serted; if not, the string is expanded and  the	result	inserted.  The
       second form specifies strings that are expanded and inserted when group
       n  is  set  or unset, respectively. The first form is just a convenient
       shorthand for

	 ${n:+${n}:string}

       Backslash can be	used to	escape colons and closing  curly  brackets  in
       the  replacement	 strings.  A change of the case	forcing	state within a
       replacement string remains  in  force  afterwards,  as  shown  in  this
       pcre2test example:

	 /(some)?(body)/substitute_extended,replace=${1:+\U:\L}HeLLo
	     body
	  1: hello
	     somebody
	  1: HELLO

       The  PCRE2_SUBSTITUTE_UNSET_EMPTY option	does not affect	these extended
       substitutions. However, PCRE2_SUBSTITUTE_UNKNOWN_UNSET does  cause  un-
       known groups in the extended syntax forms to be treated as unset.

       If  PCRE2_SUBSTITUTE_LITERAL  is	 set,  PCRE2_SUBSTITUTE_UNKNOWN_UNSET,
       PCRE2_SUBSTITUTE_UNSET_EMPTY, and PCRE2_SUBSTITUTE_EXTENDED are irrele-
       vant and	are ignored.

   Substitution	errors

       In the event of an error, pcre2_substitute() returns a  negative	 error
       code.  Except for PCRE2_ERROR_NOMATCH (which is never returned),	errors
       from pcre2_match() are passed straight back.

       PCRE2_ERROR_NOSUBSTRING is returned for a non-existent substring	inser-
       tion, unless PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set.

       PCRE2_ERROR_UNSET is returned for an unset substring insertion (includ-
       ing an unknown substring	when  PCRE2_SUBSTITUTE_UNKNOWN_UNSET  is  set)
       when  the simple	(non-extended) syntax is used and PCRE2_SUBSTITUTE_UN-
       SET_EMPTY is not	set.

       PCRE2_ERROR_NOMEMORY is returned	 if  the  output  buffer  is  not  big
       enough. If the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option is set, the size
       of  buffer  that	is needed is returned via outlengthptr.	Note that this
       does not	happen by default.

       PCRE2_ERROR_NULL	is returned if PCRE2_SUBSTITUTE_MATCHED	is set but the
       match_data argument is NULL or if the subject or	replacement  arguments
       are  NULL.  For backward	compatibility reasons an exception is made for
       the replacement argument	if the rlength argument	is also	0.

       PCRE2_ERROR_BADREPLACEMENT is used for miscellaneous syntax  errors  in
       the  replacement	 string,  with	more particular	errors being PCRE2_ER-
       ROR_BADREPESCAPE	(invalid escape	sequence), PCRE2_ERROR_REPMISSINGBRACE
       (closing	curly bracket not found), PCRE2_ERROR_BADSUBSTITUTION  (syntax
       error  in  extended group substitution),	and PCRE2_ERROR_BADSUBSPATTERN
       (the pattern match ended	before it started or the match started earlier
       than the	current	position in the	subject, which can  happen  if	\K  is
       used in an assertion).

       As for all PCRE2	errors,	a text message that describes the error	can be
       obtained	 by  calling  the pcre2_get_error_message() function (see "Ob-
       taining a textual error message"	above).

   Substitution	callouts

       int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
	 int (*callout_function)(pcre2_substitute_callout_block	*, void	*),
	 void *callout_data);

       The pcre2_set_substitution_callout() function can be used to specify  a
       callout	function for pcre2_substitute(). This information is passed in
       a match context.	The callout function is	called after each substitution
       has been	processed, but it can cause the	replacement not	to happen.

       The callout function is not called  for	simulated  substitutions  that
       happen  as  a result of the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option. In
       this mode, when substitution processing exceeds the buffer  space  pro-
       vided  by  the caller, processing continues by counting code units. The
       simulation is unable to populate	the callout block, and so the  simula-
       tion is pessimistic about the required buffer size. Whichever is	larger
       of  accepted or rejected	substitution is	reported as the	required size.
       Therefore, the returned buffer length may be an overestimate (without a
       substitution callout, it	is normally an exact measurement).

       The first argument of the callout function is a pointer to a substitute
       callout block structure,	which contains the following fields, not  nec-
       essarily	in this	order:

	 uint32_t    version;
	 uint32_t    subscount;
	 PCRE2_SPTR  input;
	 PCRE2_SPTR  output;
	 PCRE2_SIZE *ovector;
	 uint32_t    oveccount;
	 PCRE2_SIZE  output_offsets[2];

       The  version field contains the version number of the block format. The
       current version is 0. The version number	will  increase	in  future  if
       more  fields are	added, but the intention is never to remove any	of the
       existing	fields.

       The subscount field is the number of the	current	match. It is 1 for the
       first callout, 2	for the	second,	and so on. The input and output	point-
       ers are copies of the values passed to pcre2_substitute().

       The ovector field points	to the ovector,	which contains the  result  of
       the most	recent match. The oveccount field contains the number of pairs
       that are	set in the ovector, and	is always greater than zero.

       The  output_offsets  vector  contains the offsets of the	replacement in
       the output string. This has already been	processed for dollar  and  (if
       requested) backslash substitutions as described above.

       The  second  argument  of  the  callout function	is the value passed as
       callout_data when the function was registered. The  value  returned  by
       the callout function is interpreted as follows:

       If  the	value is zero, the replacement is accepted, and, if PCRE2_SUB-
       STITUTE_GLOBAL is set, processing continues with	a search for the  next
       match.  If  the	value  is not zero, the	current	replacement is not ac-
       cepted. If the value is greater than zero,  processing  continues  when
       PCRE2_SUBSTITUTE_GLOBAL	is set.	Otherwise (the value is	less than zero
       or PCRE2_SUBSTITUTE_GLOBAL is not set), the rest	of the input is	copied
       to the output and the call to pcre2_substitute()	exits,	returning  the
       number of matches so far.

   Substitution	case callouts

       int pcre2_set_substitute_case_callout(pcre2_match_context *mcontext,
	 PCRE2_SIZE (*callout_function)(PCRE2_SPTR, PCRE2_SIZE,
					PCRE2_UCHAR *, PCRE2_SIZE,
					int, void *),
	 void *callout_data);

       The pcre2_set_substitution_case_callout() function can be used to spec-
       ify  a  callout	function for pcre2_substitute()	to use when performing
       case transformations. This does not affect any case  insensitivity  be-
       haviour	when performing	a match, but only the user-visible transforma-
       tions performed when processing a substitution such as:

	   pcre2_substitute(..., "\\U$1", ...)

       The default case	transformations	applied	by PCRE2 are  reasonably  com-
       plete,  and,  in	 UTF  or UCP mode, perform the simple locale-invariant
       case transformations as specified by Unicode. This is suitable for  the
       internal	 (invisible)  case-equivalence	procedures used	during pattern
       matching, but an	application may	wish to	use more sophisticated locale-
       aware processing	for the	user-visible substitution transformations.

       One example implementation of the callout_function using	 the  ICU  li-
       brary would be:

	   PCRE2_SIZE
	   icu_case_callout(
	     PCRE2_SPTR	input, PCRE2_SIZE input_len,
	     PCRE2_UCHAR *output, PCRE2_SIZE output_cap,
	     int to_case, void *data_ptr)
	   {
	     UErrorCode	err = U_ZERO_ERROR;
	     int32_t r = to_case == PCRE2_SUBSTITUTE_CASE_LOWER
	       ? u_strToLower(output, output_cap, input, input_len, NULL, &err)
	       : to_case == PCRE2_SUBSTITUTE_CASE_UPPER
	       ? u_strToUpper(output, output_cap, input, input_len, NULL, &err)
	       : u_strToTitle(output, output_cap, input, input_len, &first_char_only,
			      NULL, &err);
	     if	(U_FAILURE(err)) return	(~(PCRE2_SIZE)0);
	     return r;
	   }

       The  first  and	second	arguments of the case callout function are the
       Unicode string to transform.

       The third and fourth arguments are the output buffer and	its capacity.

       The  fifth  is  one  of	the   constants	  PCRE2_SUBSTITUTE_CASE_LOWER,
       PCRE2_SUBSTITUTE_CASE_UPPER,    or   PCRE2_SUBSTITUTE_CASE_TITLE_FIRST.
       PCRE2_SUBSTITUTE_CASE_LOWER and PCRE2_SUBSTITUTE_CASE_UPPER are	passed
       to  the	callout	 to indicate that the case of the entire callout input
       should be case-transformed. PCRE2_SUBSTITUTE_CASE_TITLE_FIRST is	passed
       to indicate that	only the first character or  glyph  should  be	trans-
       formed  to  Unicode  titlecase  and the rest to Unicode lowercase (note
       that titlecasing	sometimes uses Unicode properties  to  titlecase  each
       word  in	a string; but PCRE2 is requesting that only the	single leading
       character is to be titlecased).

       The sixth argument is the callout_data  supplied	 to  pcre2_set_substi-
       tute_case_callout().

       The resulting string in the destination buffer may be larger or smaller
       than  the input,	if the casing rules merge or split characters. The re-
       turn value is the length	required for the output	string.	If a buffer of
       sufficient size was provided to the callout, then the  result  must  be
       written to the buffer and the number of code units returned. If the re-
       sult  does  not	fit in the provided buffer, then the required capacity
       must be returned	and PCRE2 will not make	 use  of  the  output  buffer.
       PCRE2  provides	input and output buffers which overlap,	so the callout
       must support this by suitable internal buffering.

       Alternatively, if the callout wishes to indicate	an error, then it  may
       return  (~(PCRE2_SIZE)0).  In this case pcre2_substitute() will immedi-
       ately fail with error PCRE2_ERROR_REPLACECASE.

       When  a	case  callout  is  combined  with  the	PCRE2_SUBSTITUTE_OVER-
       FLOW_LENGTH  option,  there are situations when pcre2_substitute() will
       return an underestimate of  the	required  buffer  size.	 If  you  call
       pcre2_substitute()  once	with PCRE2_SUBSTITUTE_OVERFLOW_LENGTH, and the
       input buffer is too small for the replacement string to be constructed,
       then instead of calling the case	callout, pcre2_substitute() will  make
       an  estimate  of	the required buffer size.  The second call should also
       pass PCRE2_SUBSTITUTE_OVERFLOW_LENGTH, because that second call is  not
       guaranteed  to succeed either, if the case callout requires more	buffer
       space than expected. The	caller must make repeated attempts in a	loop.

DUPLICATE CAPTURE GROUP	NAMES

       int pcre2_substring_nametable_scan(const	pcre2_code *code,
	 PCRE2_SPTR name, PCRE2_SPTR *first, PCRE2_SPTR	*last);

       When a pattern is compiled with the PCRE2_DUPNAMES  option,  names  for
       capture	groups	are not	required to be unique. Duplicate names are al-
       ways allowed for	groups with the	same number, created by	using the  (?|
       feature.	Indeed,	if such	groups are named, they are required to use the
       same names.

       Normally,  patterns  that  use duplicate	names are such that in any one
       match, only one of each set of identically-named	 groups	 participates.
       An example is shown in the pcre2pattern documentation.

       When   duplicates   are	 present,   pcre2_substring_copy_byname()  and
       pcre2_substring_get_byname() return the first  substring	 corresponding
       to  the given name that is set. Only if none are	set is PCRE2_ERROR_UN-
       SET is returned.	The  pcre2_substring_number_from_name()	 function  re-
       turns  the error	PCRE2_ERROR_NOUNIQUESUBSTRING when there are duplicate
       names.

       If you want to get full details of all captured substrings for a	 given
       name,  you  must	use the	pcre2_substring_nametable_scan() function. The
       first argument is the compiled pattern, and the second is the name.  If
       the  third  and fourth arguments	are NULL, the function returns a group
       number for a unique name, or PCRE2_ERROR_NOUNIQUESUBSTRING otherwise.

       When the	third and fourth arguments are not NULL, they must be pointers
       to variables that are updated by	the function. After it has  run,  they
       point to	the first and last entries in the name-to-number table for the
       given  name,  and the function returns the length of each entry in code
       units. In both cases, PCRE2_ERROR_NOSUBSTRING is	returned if there  are
       no entries for the given	name.

       The format of the name table is described above in the section entitled
       Information  about  a  pattern.	Given all the relevant entries for the
       name, you can extract each of their numbers,  and  hence	 the  captured
       data.

FINDING	ALL POSSIBLE MATCHES AT	ONE POSITION

       The  traditional	 matching  function  uses a similar algorithm to Perl,
       which stops when	it finds the first match at a given point in the  sub-
       ject. If	you want to find all possible matches, or the longest possible
       match  at  a  given  position,  consider	using the alternative matching
       function	(see below) instead. If	you cannot use the  alternative	 func-
       tion, you can kludge it up by making use	of the callout facility, which
       is described in the pcre2callout	documentation.

       What you	have to	do is to insert	a callout right	at the end of the pat-
       tern.   When your callout function is called, extract and save the cur-
       rent matched substring. Then return 1, which  forces  pcre2_match()  to
       backtrack  and  try other alternatives. Ultimately, when	it runs	out of
       matches,	pcre2_match() will yield PCRE2_ERROR_NOMATCH.

MATCHING A PATTERN: THE	ALTERNATIVE FUNCTION

       int pcre2_dfa_match(const pcre2_code *code, PCRE2_SPTR subject,
	 PCRE2_SIZE length, PCRE2_SIZE startoffset,
	 uint32_t options, pcre2_match_data *match_data,
	 pcre2_match_context *mcontext,
	 int *workspace, PCRE2_SIZE wscount);

       The function pcre2_dfa_match() is called	 to  match  a  subject	string
       against	a  compiled pattern, using a matching algorithm	that scans the
       subject string just once	(not counting lookaround assertions), and does
       not backtrack (except when processing lookaround	assertions). This  has
       different  characteristics to the normal	algorithm, and is not compati-
       ble with	Perl. Some of the features of  PCRE2  patterns	are  not  sup-
       ported. Nevertheless, there are times when this kind of matching	can be
       useful.	For a discussion of the	two matching algorithms, and a list of
       features	that pcre2_dfa_match() does not	support, see the pcre2matching
       documentation.

       The arguments for the pcre2_dfa_match() function	are the	 same  as  for
       pcre2_match(), plus two extras. The ovector within the match data block
       is used in a different way, and this is described below.	The other com-
       mon  arguments  are used	in the same way	as for pcre2_match(), so their
       description is not repeated here.

       The two additional arguments provide workspace for  the	function.  The
       workspace  vector  should  contain at least 20 elements.	It is used for
       keeping track of	multiple paths through the pattern  tree.  More	 work-
       space  is needed	for patterns and subjects where	there are a lot	of po-
       tential matches.

       Here is an example of a simple call to pcre2_dfa_match():

	 int wspace[20];
	 pcre2_match_data *md =	pcre2_match_data_create(4, NULL);
	 int rc	= pcre2_dfa_match(
	   re,		   /* result of	pcre2_compile()	*/
	   "some string",  /* the subject string */
	   11,		   /* the length of the	subject	string */
	   0,		   /* start at offset 0	in the subject */
	   0,		   /* default options */
	   md,		   /* the match	data block */
	   NULL,	   /* a	match context; NULL means use defaults */
	   wspace,	   /* working space vector */
	   20);		   /* number of	elements (NOT size in bytes) */

   Option bits for pcre2_dfa_match()

       The unused bits of the options argument for pcre2_dfa_match()  must  be
       zero.   The   only   bits   that	  may	be   set  are  PCRE2_ANCHORED,
       PCRE2_COPY_MATCHED_SUBJECT, PCRE2_ENDANCHORED, PCRE2_NOTBOL,  PCRE2_NO-
       TEOL,   PCRE2_NOTEMPTY,	 PCRE2_NOTEMPTY_ATSTART,   PCRE2_NO_UTF_CHECK,
       PCRE2_PARTIAL_HARD,   PCRE2_PARTIAL_SOFT,    PCRE2_DFA_SHORTEST,	   and
       PCRE2_DFA_RESTART.  All but the last four of these are exactly the same
       as for pcre2_match(), so	their description is not repeated here.

	 PCRE2_PARTIAL_HARD
	 PCRE2_PARTIAL_SOFT

       These have the same general effect as they do  for  pcre2_match(),  but
       the  details are	slightly different. When PCRE2_PARTIAL_HARD is set for
       pcre2_dfa_match(), it returns PCRE2_ERROR_PARTIAL if  the  end  of  the
       subject is reached and there is still at	least one matching possibility
       that requires additional	characters. This happens even if some complete
       matches	have  already  been found. When	PCRE2_PARTIAL_SOFT is set, the
       return code PCRE2_ERROR_NOMATCH is converted  into  PCRE2_ERROR_PARTIAL
       if  the	end  of	 the  subject  is reached, there have been no complete
       matches,	but there is still at least one	matching possibility. The por-
       tion of the string that was inspected when the  longest	partial	 match
       was found is set	as the first matching string in	both cases. There is a
       more  detailed  discussion  of partial and multi-segment	matching, with
       examples, in the	pcre2partial documentation.

	 PCRE2_DFA_SHORTEST

       Setting the PCRE2_DFA_SHORTEST option causes the	matching algorithm  to
       stop as soon as it has found one	match. Because of the way the alterna-
       tive  algorithm	works, this is necessarily the shortest	possible match
       at the first possible matching point in the subject string.

	 PCRE2_DFA_RESTART

       When pcre2_dfa_match() returns a	partial	match, it is possible to  call
       it again, with additional subject characters, and have it continue with
       the same	match. The PCRE2_DFA_RESTART option requests this action; when
       it  is  set,  the workspace and wscount options must reference the same
       vector as before	because	data about the match so	far is	left  in  them
       after a partial match. There is more discussion of this facility	in the
       pcre2partial documentation.

   Successful returns from pcre2_dfa_match()

       When pcre2_dfa_match() succeeds,	it may have matched more than one sub-
       string in the subject. Note, however, that all the matches from one run
       of  the	function  start	 at the	same point in the subject. The shorter
       matches are all initial substrings of the longer	matches. For  example,
       if the pattern

	 <.*>

       is matched against the string

	 This is <something> <something	else> <something further> no more

       the three matched strings are

	 <something> <something	else> <something further>
	 <something> <something	else>
	 <something>

       On  success,  the  yield	of the function	is a number greater than zero,
       which is	the number of matched substrings.  The	offsets	 of  the  sub-
       strings	are returned in	the ovector, and can be	extracted by number in
       the same	way as for pcre2_match(), but the numbers bear no relation  to
       any  capture groups that	may exist in the pattern, because DFA matching
       does not	support	capturing.

       Calls to	the convenience	functions that extract substrings by name  re-
       turn the	error PCRE2_ERROR_DFA_UFUNC (unsupported function) if used af-
       ter  a  DFA match. The convenience functions that extract substrings by
       number never return PCRE2_ERROR_NOSUBSTRING.

       The matched strings are stored in  the  ovector	in  reverse  order  of
       length;	that  is,  the longest matching	string is first. If there were
       too many	matches	to fit into the	ovector, the yield of the function  is
       zero, and the vector is filled with the longest matches.

       NOTE:  PCRE2's  "auto-possessification" optimization usually applies to
       character repeats at the	end of a pattern (as well as internally).  For
       example,	 the pattern "a\d+" is compiled	as if it were "a\d++". For DFA
       matching, this means that only one possible match is found. If you  re-
       ally do want multiple matches in	such cases, either use an ungreedy re-
       peat  such as "a\d+?" or	set the	PCRE2_NO_AUTO_POSSESS option when com-
       piling.

   Error returns from pcre2_dfa_match()

       The pcre2_dfa_match() function returns a	negative number	when it	fails.
       Many of the errors are the same	as  for	 pcre2_match(),	 as  described
       above.  There are in addition the following errors that are specific to
       pcre2_dfa_match():

	 PCRE2_ERROR_DFA_UITEM

       This  return  is	 given	if pcre2_dfa_match() encounters	an item	in the
       pattern that it does not	support, for instance, the use of \C in	a  UTF
       mode or a backreference.

	 PCRE2_ERROR_DFA_UCOND

       This  return  is	given if pcre2_dfa_match() encounters a	condition item
       that uses a backreference for the condition, or a test for recursion in
       a specific capture group. These are not supported.

	 PCRE2_ERROR_DFA_UINVALID_UTF

       This return is given if pcre2_dfa_match() is called for a pattern  that
       was  compiled  with  PCRE2_MATCH_INVALID_UTF. This is not supported for
       DFA matching.

	 PCRE2_ERROR_DFA_WSSIZE

       This return is given if pcre2_dfa_match() runs  out  of	space  in  the
       workspace vector.

	 PCRE2_ERROR_DFA_RECURSE

       When a recursion	or subroutine call is processed, the matching function
       calls  itself  recursively,  using  private  memory for the ovector and
       workspace.  This	error is given if the internal ovector	is  not	 large
       enough.	This  should  be  extremely  rare, as a	vector of size 1000 is
       used.

	 PCRE2_ERROR_DFA_BADRESTART

       When pcre2_dfa_match() is called	 with  the  PCRE2_DFA_RESTART  option,
       some  plausibility  checks  are	made on	the contents of	the workspace,
       which should contain data about the previous partial match. If  any  of
       these checks fail, this error is	given.

SEE ALSO

       pcre2build(3),	 pcre2callout(3),    pcre2demo(3),   pcre2matching(3),
       pcre2partial(3),	pcre2posix(3), pcre2sample(3), pcre2unicode(3).

AUTHOR

       Philip Hazel
       Retired from University Computing Service
       Cambridge, England.

REVISION

       Last updated: 26	December 2024
       Copyright (c) 1997-2024 University of Cambridge.

PCRE2 10.45		       26 December 2024			   PCRE2API(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pcre2api&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help