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);

       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_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);

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_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_SPTR *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(PCRE2_SIZE startsize,
	 PCRE2_SIZE 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)(PCRE2_SIZE, 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.

       Character strings are passed to and from	a PCRE2	library	as a  sequence
       of  unsigned  integers  in  code	 units of the appropriate width. 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  constant  pointers  to the equivalent UCHAR types, that is,
       they are	pointers to vectors of unsigned	code units.

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

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)

       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_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.

   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_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,	which-
       ever 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 starts out using a 20KiB vector on the sys-
       tem stack for recording backtracking points. The	more nested backtrack-
       ing  points  there  are (that is, the deeper the	search tree), the more
       memory is needed.  Heap memory is used only if the  initial  vector  is
       too small. If the heap limit is set to a	value less than	21 (in partic-
       ular, zero) no heap memory will be used.	In this	 case,	only  patterns
       that  do	not have a lot of nested backtracking can be successfully pro-
       cessed.

       Similarly, for pcre2_dfa_match(), a vector on the system	stack is  used
       when  processing	pattern	recursions, lookarounds, or atomic groups, and
       only if this is not big enough is heap memory used. In this case,  too,
       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 pro-
       cessed by pcre2_jit_compile(), the way in which matching	is executed is
       entirely	 different. However, there is still the	possibility of runaway
       matching	that goes on for a very	long  time,  and  so  the  match_limit
       value  is  also used in this case (but in a different way) to limit how
       long the	matching can continue.

       The default value for the limit can be set when PCRE2 is	built; the de-
       fault  default  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" de-
       pends 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 available; otherwise it is set	to zero.

	 PCRE2_CONFIG_JITTARGET

       The  where  argument  should point to a buffer that is at least 48 code
       units long.  (The  exact	 length	 required  can	be  found  by  calling
       pcre2_config()  with  where  set	 to NULL.) The buffer is filled	with a
       string that contains the	name of	the architecture  for  which  the  JIT
       compiler	 is  configured,  for  example "x86 32bit (little endian + 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.  The  function  returns  a
       pointer to a block of memory that contains the compiled pattern and re-
       lated 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 pa-
       rameters	(for example, the newline setting) can be provided in  a  com-
       pile 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. The values are not defined when compilation is suc-
       cessful and pcre2_compile() returns a non-NULL value.

       There are nearly	100 positive error codes that pcre2_compile() may  re-
       turn  if	it finds an error in the pattern. There	are also some negative
       error codes that	are used for invalid UTF strings when validity	check-
       ing  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.

       The value returned in erroroffset is an indication of where in the pat-
       tern  the  error	 occurred. It is not necessarily the furthest point in
       the pattern that	was read. For example, after the error "lookbehind as-
       sertion	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  off-
       set 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_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	equiv-
       alents,	are case-equivalent with U+212A	(Kelvin	sign) and U+017F (long
       S) respectively.	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 another case.

	 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 or inside a character class. However,
       white space is not allowed within sequences 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 follow-
       ing  quantifier	and  between a quantifier and a	following + that indi-
       cates possessiveness. PCRE2_EXTENDED 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.

	 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.   This  facility  is not supported for DFA matching. For de-
       tails, see the pcre2unicode documentation.

	 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 PCRE_UCP
       and PCRE_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 option is set, it disables "auto-possessification", 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. However, 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.

	 PCRE2_NO_DOTSTAR_ANCHOR

       If this 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  inside  an
       atomic group or a capture group that is the subject of a	backreference,
       or if the pattern contains (*PRUNE) or (*SKIP). When  the  optimization
       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.

	 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.

       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. 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	 callouts  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  optimiza-
       tions  are  in effect a pre-scan	of the subject that takes place	before
       the pattern is run.

       The PCRE2_NO_START_OPTIMIZE option disables the start-up	optimizations,
       possibly	 causing  performance  to  suffer,  but	ensuring 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.

       Setting PCRE2_NO_START_OPTIMIZE 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	 with  PCRE2_NO_START_OPTIMIZE
       set,  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 re-
       sult is "no match".

       As 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".  If	 NO_START_OPTIMIZE is set, 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.

	 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
       pcre_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 instead to	classify char-
       acters. More details are	given in  the  section	on  generic  character
       types  in  the pcre2pattern page. If you	set PCRE2_UCP, matching	one of
       the items it affects takes much longer.

       The second effect of PCRE2_UCP is to force the use of  Unicode  proper-
       ties  for  upper/lower casing operations	on characters with code	points
       greater than 127, even when PCRE2_UTF is	not set. This makes it	possi-
       ble, for	example, to process strings in the 16-bit UCS-2	code. This op-
       tion is available only if PCRE2 has been	compiled with Unicode  support
       (which is the default).

	 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 handles characters with code points greater than 127.

   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_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_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_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.

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(PCRE2_SIZE startsize,
	 PCRE2_SIZE 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), the Unicode
       properties of all characters can	be tested with \p and \P, or, alterna-
       tively,	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	opera-
       tions on	characters with	code points greater than 127  to  use  Unicode
       properties. These effects apply even when PCRE2_UTF is not set.

       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

       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  pro-
       cessed,	the first lookbehind moves back	by two characters, matches one
       character, then the nested lookbehind also moves	back  by  two  charac-
       ters. This puts the matching point three	characters earlier than	it was
       at the start.  PCRE2_INFO_MAXLOOKBEHIND is really only useful as	a  de-
       bugging	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
       reload  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 endi-
       anness, 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  begin  with pcre2_serialize_ are used for	converting to and from
       the serialized form. They are described in the pcre2serialize  documen-
       tation.	Note  that  PCRE2 serialization	does not convert compiled pat-
       terns 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 part	of the
       subject and any substrings that were captured. 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. One pair of offsets  is  re-
       quired  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 substrings. A minimum of at least	1 pair is  imposed  by
       pcre2_match_data_create(), so it	is always possible to return the over-
       all matched string.

       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. The sec-
       ond argument is again a pointer to a general context, but in this  case
       if NULL is passed, the memory is	obtained 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.

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.

       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 "Mississipi" the first call to pcre2_match()
       finds  the first	occurrence. If pcre2_match() is	called again with just
       the remainder of	the subject, namely "issipi", it does not  match,  be-
       cause  \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	occur-
       rence 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_ENDANCHORED, PCRE2_NOTBOL, PCRE2_NO-
       TEOL,	 PCRE2_NOTEMPTY,     PCRE2_NOTEMPTY_ATSTART,	 PCRE2_NO_JIT,
       PCRE2_NO_UTF_CHECK,  PCRE2_PARTIAL_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.	 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_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 for the second and third
       capture groupss (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

       If a pattern contains many nested backtracking points, heap  memory  is
       used  to	 remember them.	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 allocation 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_SPTR *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.  This
       can  be	given  as  PCRE2_ZERO_TERMINATED for a zero-terminated string.
       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 been used	for an
       external	call to	pcre2_match(). The data	in the match_data  block  (re-
       turn code, offset vector) is used for the first substitution instead of
       calling pcre2_match() from within pcre2_substitute().  This  allows  an
       application 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 buf-
       fer that	is needed. This	value is  passed  back	via  the  outlengthptr
       variable,  with	the  result  of	 the  function	still  being PCRE2_ER-
       ROR_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. The following forms are always recognized:

	 $$		     insert a dollar character
	 $<n> or ${<n>}	     insert the	contents of group <n>
	 $*MARK	or ${*MARK}  insert a control verb name

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

       $*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, two things change:

       Firstly,	 backslash in a	replacement string is interpreted as an	escape
       character. The usual forms such as \n or	\x{ddd}	can be used to specify
       particular  character codes, and	backslash followed by any non-alphanu-
       meric character quotes that character. Extended quoting	can  be	 coded
       using \Q...\E, exactly as in pattern strings.

       There  are  also	four escape sequences for forcing the case of inserted
       letters.	 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, respec-
       tively,	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 automatically reverts to no case forcing. Case forcing applies to
       all  inserted  characters, including those from capture groups and let-
       ters within \Q...\E quoted sequences. 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.

       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  second  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  before,  <n>	may be a group number or a name. The first form	speci-
       fies a default value. If	group <n> is set, its value  is	 inserted;  if
       not,  <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.

       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.

       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 the rest of the input is
       copied to the output and	the call to pcre2_substitute() exits,  return-
       ing the number of matches so far.

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.	This has different characteristics to the normal algo-
       rithm, and is not compatible with Perl. Some of the features  of	 PCRE2
       patterns	 are  not  supported.  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 sup-
       port, 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
       workspace  is needed for	patterns and subjects where there are a	lot of
       potential 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 pcre_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
       University Computing Service
       Cambridge, England.

REVISION

       Last updated: 04	November 2020
       Copyright (c) 1997-2020 University of Cambridge.

PCRE2 10.36		       04 November 2020			   PCRE2API(3)

NAME | PCRE2 NATIVE API BASIC FUNCTIONS | PCRE2 NATIVE API AUXILIARY MATCH FUNCTIONS | PCRE2 NATIVE API GENERAL CONTEXT FUNCTIONS | PCRE2 NATIVE API COMPILE CONTEXT FUNCTIONS | PCRE2 NATIVE API MATCH CONTEXT FUNCTIONS | PCRE2 NATIVE API STRING EXTRACTION FUNCTIONS | PCRE2 NATIVE API STRING SUBSTITUTION FUNCTION | PCRE2 NATIVE API JIT FUNCTIONS | PCRE2 NATIVE API SERIALIZATION FUNCTIONS | PCRE2 NATIVE API AUXILIARY FUNCTIONS | PCRE2 NATIVE API OBSOLETE FUNCTIONS | PCRE2 EXPERIMENTAL PATTERN CONVERSION FUNCTIONS | PCRE2 8-BIT, 16-BIT, AND 32-BIT LIBRARIES | PCRE2 API OVERVIEW | STRING LENGTHS AND OFFSETS | NEWLINES | MULTITHREADING | PCRE2 CONTEXTS | CHECKING BUILD-TIME OPTIONS | COMPILING A PATTERN | JUST-IN-TIME (JIT) COMPILATION | LOCALE SUPPORT | INFORMATION ABOUT A COMPILED PATTERN | INFORMATION ABOUT A PATTERN'S CALLOUTS | SERIALIZATION AND PRECOMPILING | THE MATCH DATA BLOCK | MATCHING A PATTERN: THE TRADITIONAL FUNCTION | NEWLINE HANDLING WHEN MATCHING | HOW PCRE2_MATCH() RETURNS A STRING AND CAPTURED SUBSTRINGS | OTHER INFORMATION ABOUT A MATCH | ERROR RETURNS FROM pcre2_match() | OBTAINING A TEXTUAL ERROR MESSAGE | EXTRACTING CAPTURED SUBSTRINGS BY NUMBER | EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS | EXTRACTING CAPTURED SUBSTRINGS BY NAME | CREATING A NEW STRING WITH SUBSTITUTIONS | DUPLICATE CAPTURE GROUP NAMES | FINDING ALL POSSIBLE MATCHES AT ONE POSITION | MATCHING A PATTERN: THE ALTERNATIVE FUNCTION | SEE ALSO | AUTHOR | REVISION

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

home | help