685 lines
26 KiB
HTML
685 lines
26 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of PCRE2BUILD</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>PCRE2BUILD</H1>
|
|
Section: C Library Functions (3)<BR>Updated: 03 March 2019<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
PCRE2 - Perl-compatible regular expressions (revised API)
|
|
<A NAME="lbAC"> </A>
|
|
<H2>BUILDING PCRE2</H2>
|
|
|
|
|
|
<P>
|
|
PCRE2 is distributed with a <B>configure</B> script that can be used to build
|
|
the library in Unix-like environments using the applications known as
|
|
Autotools. Also in the distribution are files to support building using
|
|
<B>CMake</B> instead of <B>configure</B>. The text file
|
|
|
|
|
|
<B>README</B>
|
|
|
|
contains general information about building with Autotools (some of which is
|
|
repeated below), and also has some comments about building on various operating
|
|
systems. There is a lot more information about building PCRE2 without using
|
|
Autotools (including information about using <B>CMake</B> and building "by
|
|
hand") in the text file called
|
|
|
|
|
|
<B>NON-AUTOTOOLS-BUILD</B>.
|
|
|
|
You should consult this file as well as the
|
|
|
|
|
|
<B>README</B>
|
|
|
|
file if you are building in a non-Unix-like environment.
|
|
<A NAME="lbAD"> </A>
|
|
<H2>PCRE2 BUILD-TIME OPTIONS</H2>
|
|
|
|
|
|
<P>
|
|
The rest of this document describes the optional features of PCRE2 that can be
|
|
selected when the library is compiled. It assumes use of the <B>configure</B>
|
|
script, where the optional features are selected or deselected by providing
|
|
options to <B>configure</B> before running the <B>make</B> command. However, the
|
|
same options can be selected in both Unix-like and non-Unix-like environments
|
|
if you are using <B>CMake</B> instead of <B>configure</B> to build PCRE2.
|
|
<P>
|
|
|
|
If you are not using Autotools or <B>CMake</B>, option selection can be done by
|
|
editing the <B>config.h</B> file, or by passing parameter settings to the
|
|
compiler, as described in
|
|
|
|
|
|
<B>NON-AUTOTOOLS-BUILD</B>.
|
|
|
|
<P>
|
|
|
|
The complete list of options for <B>configure</B> (which includes the standard
|
|
ones such as the selection of the installation directory) can be obtained by
|
|
running
|
|
<P>
|
|
<BR> ./configure --help
|
|
<P>
|
|
The following sections include descriptions of "on/off" options whose names
|
|
begin with --enable or --disable. Because of the way that <B>configure</B>
|
|
works, --enable and --disable always come in pairs, so the complementary option
|
|
always exists as well, but as it specifies the default, it is not described.
|
|
Options that specify values have names that start with --with. At the end of a
|
|
<B>configure</B> run, a summary of the configuration is output.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES</H2>
|
|
|
|
|
|
<P>
|
|
By default, a library called <B>libpcre2-8</B> is built, containing functions
|
|
that take string arguments contained in arrays of bytes, interpreted either as
|
|
single-byte characters, or UTF-8 strings. You can also build two other
|
|
libraries, called <B>libpcre2-16</B> and <B>libpcre2-32</B>, which process
|
|
strings that are contained in arrays of 16-bit and 32-bit code units,
|
|
respectively. These can be interpreted either as single-unit characters or
|
|
UTF-16/UTF-32 strings. To build these additional libraries, add one or both of
|
|
the following to the <B>configure</B> command:
|
|
<P>
|
|
<BR> --enable-pcre2-16
|
|
<BR> --enable-pcre2-32
|
|
<P>
|
|
If you do not want the 8-bit library, add
|
|
<P>
|
|
<BR> --disable-pcre2-8
|
|
<P>
|
|
as well. At least one of the three libraries must be built. Note that the POSIX
|
|
wrapper is for the 8-bit library only, and that <B>pcre2grep</B> is an 8-bit
|
|
program. Neither of these are built if you select only the 16-bit or 32-bit
|
|
libraries.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>BUILDING SHARED AND STATIC LIBRARIES</H2>
|
|
|
|
|
|
<P>
|
|
The Autotools PCRE2 building process uses <B>libtool</B> to build both shared
|
|
and static libraries by default. You can suppress an unwanted library by adding
|
|
one of
|
|
<P>
|
|
<BR> --disable-shared
|
|
<BR> --disable-static
|
|
<P>
|
|
to the <B>configure</B> command.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>UNICODE AND UTF SUPPORT</H2>
|
|
|
|
|
|
<P>
|
|
By default, PCRE2 is built with support for Unicode and UTF character strings.
|
|
To build it without Unicode support, add
|
|
<P>
|
|
<BR> --disable-unicode
|
|
<P>
|
|
to the <B>configure</B> command. This setting applies to all three libraries. It
|
|
is not possible to build one library with Unicode support, and another without,
|
|
in the same configuration.
|
|
<P>
|
|
|
|
Of itself, Unicode support does not make PCRE2 treat strings as UTF-8, UTF-16
|
|
or UTF-32. To do that, applications that use the library can set the PCRE2_UTF
|
|
option when they call <B>pcre2_compile()</B> to compile a pattern.
|
|
Alternatively, patterns may be started with (*UTF) unless the application has
|
|
locked this out by setting PCRE2_NEVER_UTF.
|
|
<P>
|
|
|
|
UTF support allows the libraries to process character code points up to
|
|
0x10ffff in the strings that they handle. Unicode support also gives access to
|
|
the Unicode properties of characters, using pattern escapes such as \P, \p,
|
|
and \X. Only the general category properties such as <I>Lu</I> and <I>Nd</I> are
|
|
supported. Details are given in the
|
|
|
|
<B>pcre2pattern</B>
|
|
|
|
documentation.
|
|
<P>
|
|
|
|
Pattern escapes such as \d and \w do not by default make use of Unicode
|
|
properties. The application can request that they do by setting the PCRE2_UCP
|
|
option. Unless the application has set PCRE2_NEVER_UCP, a pattern may also
|
|
request this by starting with (*UCP).
|
|
<A NAME="lbAH"> </A>
|
|
<H2>DISABLING THE USE OF \C</H2>
|
|
|
|
|
|
<P>
|
|
The \C escape sequence, which matches a single code unit, even in a UTF mode,
|
|
can cause unpredictable behaviour because it may leave the current matching
|
|
point in the middle of a multi-code-unit character. The application can lock it
|
|
out by setting the PCRE2_NEVER_BACKSLASH_C option when calling
|
|
<B>pcre2_compile()</B>. There is also a build-time option
|
|
<P>
|
|
<BR> --enable-never-backslash-C
|
|
<P>
|
|
(note the upper case C) which locks out the use of \C entirely.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>JUST-IN-TIME COMPILER SUPPORT</H2>
|
|
|
|
|
|
<P>
|
|
Just-in-time (JIT) compiler support is included in the build by specifying
|
|
<P>
|
|
<BR> --enable-jit
|
|
<P>
|
|
This support is available only for certain hardware architectures. If this
|
|
option is set for an unsupported architecture, a building error occurs.
|
|
If in doubt, use
|
|
<P>
|
|
<BR> --enable-jit=auto
|
|
<P>
|
|
which enables JIT only if the current hardware is supported. You can check
|
|
if JIT is enabled in the configuration summary that is output at the end of a
|
|
<B>configure</B> run. If you are enabling JIT under SELinux you may also want to
|
|
add
|
|
<P>
|
|
<BR> --enable-jit-sealloc
|
|
<P>
|
|
which enables the use of an execmem allocator in JIT that is compatible with
|
|
SELinux. This has no effect if JIT is not enabled. See the
|
|
|
|
<B>pcre2jit</B>
|
|
|
|
documentation for a discussion of JIT usage. When JIT support is enabled,
|
|
pcre2grep automatically makes use of it, unless you add
|
|
<P>
|
|
<BR> --disable-pcre2grep-jit
|
|
<P>
|
|
to the "configure" command.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>NEWLINE RECOGNITION</H2>
|
|
|
|
|
|
<P>
|
|
By default, PCRE2 interprets the linefeed (LF) character as indicating the end
|
|
of a line. This is the normal newline character on Unix-like systems. You can
|
|
compile PCRE2 to use carriage return (CR) instead, by adding
|
|
<P>
|
|
<BR> --enable-newline-is-cr
|
|
<P>
|
|
to the <B>configure</B> command. There is also an --enable-newline-is-lf option,
|
|
which explicitly specifies linefeed as the newline character.
|
|
<P>
|
|
|
|
Alternatively, you can specify that line endings are to be indicated by the
|
|
two-character sequence CRLF (CR immediately followed by LF). If you want this,
|
|
add
|
|
<P>
|
|
<BR> --enable-newline-is-crlf
|
|
<P>
|
|
to the <B>configure</B> command. There is a fourth option, specified by
|
|
<P>
|
|
<BR> --enable-newline-is-anycrlf
|
|
<P>
|
|
which causes PCRE2 to recognize any of the three sequences CR, LF, or CRLF as
|
|
indicating a line ending. A fifth option, specified by
|
|
<P>
|
|
<BR> --enable-newline-is-any
|
|
<P>
|
|
causes PCRE2 to recognize 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). The final option is
|
|
<P>
|
|
<BR> --enable-newline-is-nul
|
|
<P>
|
|
which causes NUL (binary zero) to be set as the default line-ending character.
|
|
<P>
|
|
|
|
Whatever default line ending convention is selected when PCRE2 is built can be
|
|
overridden by applications that use the library. At build time it is
|
|
recommended to use the standard for your operating system.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>WHAT \R MATCHES</H2>
|
|
|
|
|
|
<P>
|
|
By default, the sequence \R in a pattern matches any Unicode newline sequence,
|
|
independently of what has been selected as the line ending sequence. If you
|
|
specify
|
|
<P>
|
|
<BR> --enable-bsr-anycrlf
|
|
<P>
|
|
the default is changed so that \R matches only CR, LF, or CRLF. Whatever is
|
|
selected when PCRE2 is built can be overridden by applications that use the
|
|
library.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>HANDLING VERY LARGE PATTERNS</H2>
|
|
|
|
|
|
<P>
|
|
Within a compiled pattern, offset values are used to point from one part to
|
|
another (for example, from an opening parenthesis to an alternation
|
|
metacharacter). By default, in the 8-bit and 16-bit libraries, two-byte values
|
|
are used for these offsets, leading to a maximum size for a compiled pattern of
|
|
around 64 thousand code units. This is sufficient to handle all but the most
|
|
gigantic patterns. Nevertheless, some people do want to process truly enormous
|
|
patterns, so it is possible to compile PCRE2 to use three-byte or four-byte
|
|
offsets by adding a setting such as
|
|
<P>
|
|
<BR> --with-link-size=3
|
|
<P>
|
|
to the <B>configure</B> command. The value given must be 2, 3, or 4. For the
|
|
16-bit library, a value of 3 is rounded up to 4. In these libraries, using
|
|
longer offsets slows down the operation of PCRE2 because it has to load
|
|
additional data when handling them. For the 32-bit library the value is always
|
|
4 and cannot be overridden; the value of --with-link-size is ignored.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>LIMITING PCRE2 RESOURCE USAGE</H2>
|
|
|
|
|
|
<P>
|
|
The <B>pcre2_match()</B> function increments a counter each time it goes round
|
|
its main loop. Putting a limit on this counter controls the amount of computing
|
|
resource used by a single call to <B>pcre2_match()</B>. The limit can be changed
|
|
at run time, as described in the
|
|
|
|
<B>pcre2api</B>
|
|
|
|
documentation. The default is 10 million, but this can be changed by adding a
|
|
setting such as
|
|
<P>
|
|
<BR> --with-match-limit=500000
|
|
<P>
|
|
to the <B>configure</B> command. This setting also applies to the
|
|
<B>pcre2_dfa_match()</B> matching function, and to JIT matching (though the
|
|
counting is done differently).
|
|
<P>
|
|
|
|
The <B>pcre2_match()</B> function starts out using a 20KiB vector on the system
|
|
stack to record backtracking points. The more nested backtracking points there
|
|
are (that is, the deeper the search tree), the more memory is needed. If the
|
|
initial vector is not large enough, heap memory is used, up to a certain limit,
|
|
which is specified in kibibytes (units of 1024 bytes). The limit can be changed
|
|
at run time, as described in the
|
|
|
|
<B>pcre2api</B>
|
|
|
|
documentation. The default limit (in effect unlimited) is 20 million. You can
|
|
change this by a setting such as
|
|
<P>
|
|
<BR> --with-heap-limit=500
|
|
<P>
|
|
which limits the amount of heap to 500 KiB. This limit applies only to
|
|
interpretive matching in <B>pcre2_match()</B> and <B>pcre2_dfa_match()</B>, which
|
|
may also use the heap for internal workspace when processing complicated
|
|
patterns. This limit does not apply when JIT (which has its own memory
|
|
arrangements) is used.
|
|
<P>
|
|
|
|
You can also explicitly limit the depth of nested backtracking in the
|
|
<B>pcre2_match()</B> interpreter. This limit defaults to the value that is set
|
|
for --with-match-limit. You can set a lower default limit by adding, for
|
|
example,
|
|
<P>
|
|
<BR> --with-match-limit_depth=10000
|
|
<P>
|
|
to the <B>configure</B> command. This value can be overridden at run time. This
|
|
depth limit indirectly limits the amount of heap memory that is used, but
|
|
because the size of each backtracking "frame" depends on the number of
|
|
capturing parentheses in a pattern, the amount of heap that is used before the
|
|
limit is reached varies from pattern to pattern. This limit was more useful in
|
|
versions before 10.30, where function recursion was used for backtracking.
|
|
<P>
|
|
|
|
As well as applying to <B>pcre2_match()</B>, the depth limit also controls
|
|
the depth of recursive function calls in <B>pcre2_dfa_match()</B>. These are
|
|
used for lookaround assertions, atomic groups, and recursion within patterns.
|
|
The limit does not apply to JIT matching.
|
|
<A NAME="lbAN"> </A>
|
|
<H2>CREATING CHARACTER TABLES AT BUILD TIME</H2>
|
|
|
|
|
|
<P>
|
|
PCRE2 uses fixed tables for processing characters whose code points are less
|
|
than 256. By default, PCRE2 is built with a set of tables that are distributed
|
|
in the file <I>src/pcre2_chartables.c.dist</I>. These tables are for ASCII codes
|
|
only. If you add
|
|
<P>
|
|
<BR> --enable-rebuild-chartables
|
|
<P>
|
|
to the <B>configure</B> command, the distributed tables are no longer used.
|
|
Instead, a program called <B>dftables</B> is compiled and run. This outputs the
|
|
source for new set of tables, created in the default locale of your C run-time
|
|
system. This method of replacing the tables does not work if you are cross
|
|
compiling, because <B>dftables</B> is run on the local host. If you need to
|
|
create alternative tables when cross compiling, you will have to do so "by
|
|
hand".
|
|
<A NAME="lbAO"> </A>
|
|
<H2>USING EBCDIC CODE</H2>
|
|
|
|
|
|
<P>
|
|
PCRE2 assumes by default that it will run in an environment where the character
|
|
code is ASCII or Unicode, which is a superset of ASCII. This is the case for
|
|
most computer operating systems. PCRE2 can, however, be compiled to run in an
|
|
8-bit EBCDIC environment by adding
|
|
<P>
|
|
<BR> --enable-ebcdic --disable-unicode
|
|
<P>
|
|
to the <B>configure</B> command. This setting implies
|
|
--enable-rebuild-chartables. You should only use it if you know that you are in
|
|
an EBCDIC environment (for example, an IBM mainframe operating system).
|
|
<P>
|
|
|
|
It is not possible to support both EBCDIC and UTF-8 codes in the same version
|
|
of the library. Consequently, --enable-unicode and --enable-ebcdic are mutually
|
|
exclusive.
|
|
<P>
|
|
|
|
The EBCDIC character that corresponds to an ASCII LF is assumed to have the
|
|
value 0x15 by default. However, in some EBCDIC environments, 0x25 is used. In
|
|
such an environment you should use
|
|
<P>
|
|
<BR> --enable-ebcdic-nl25
|
|
<P>
|
|
as well as, or instead of, --enable-ebcdic. The EBCDIC character for CR has the
|
|
same value as in ASCII, namely, 0x0d. Whichever of 0x15 and 0x25 is <I>not</I>
|
|
chosen as LF is made to correspond to the Unicode NEL character (which, in
|
|
Unicode, is 0x85).
|
|
<P>
|
|
|
|
The options that select newline behaviour, such as --enable-newline-is-cr,
|
|
and equivalent run-time options, refer to these character values in an EBCDIC
|
|
environment.
|
|
<A NAME="lbAP"> </A>
|
|
<H2>PCRE2GREP SUPPORT FOR EXTERNAL SCRIPTS</H2>
|
|
|
|
|
|
<P>
|
|
By default <B>pcre2grep</B> supports the use of callouts with string arguments
|
|
within the patterns it is matching. There are two kinds: one that generates
|
|
output using local code, and another that calls an external program or script.
|
|
If --disable-pcre2grep-callout-fork is added to the <B>configure</B> command,
|
|
only the first kind of callout is supported; if --disable-pcre2grep-callout is
|
|
used, all callouts are completely ignored. For more details of <B>pcre2grep</B>
|
|
callouts, see the
|
|
|
|
<B>pcre2grep</B>
|
|
|
|
documentation.
|
|
<A NAME="lbAQ"> </A>
|
|
<H2>PCRE2GREP OPTIONS FOR COMPRESSED FILE SUPPORT</H2>
|
|
|
|
|
|
<P>
|
|
By default, <B>pcre2grep</B> reads all files as plain text. You can build it so
|
|
that it recognizes files whose names end in <B>.gz</B> or <B>.bz2</B>, and reads
|
|
them with <B>libz</B> or <B>libbz2</B>, respectively, by adding one or both of
|
|
<P>
|
|
<BR> --enable-pcre2grep-libz
|
|
<BR> --enable-pcre2grep-libbz2
|
|
<P>
|
|
to the <B>configure</B> command. These options naturally require that the
|
|
relevant libraries are installed on your system. Configuration will fail if
|
|
they are not.
|
|
<A NAME="lbAR"> </A>
|
|
<H2>PCRE2GREP BUFFER SIZE</H2>
|
|
|
|
|
|
<P>
|
|
<B>pcre2grep</B> uses an internal buffer to hold a "window" on the file it is
|
|
scanning, in order to be able to output "before" and "after" lines when it
|
|
finds a match. The default starting size of the buffer is 20KiB. The buffer
|
|
itself is three times this size, but because of the way it is used for holding
|
|
"before" lines, the longest line that is guaranteed to be processable is the
|
|
notional buffer size. If a longer line is encountered, <B>pcre2grep</B>
|
|
automatically expands the buffer, up to a specified maximum size, whose default
|
|
is 1MiB or the starting size, whichever is the larger. You can change the
|
|
default parameter values by adding, for example,
|
|
<P>
|
|
<BR> --with-pcre2grep-bufsize=51200
|
|
<BR> --with-pcre2grep-max-bufsize=2097152
|
|
<P>
|
|
to the <B>configure</B> command. The caller of pcre2grep can override
|
|
these values by using --buffer-size and --max-buffer-size on the command line.
|
|
<A NAME="lbAS"> </A>
|
|
<H2>PCRE2TEST OPTION FOR LIBREADLINE SUPPORT</H2>
|
|
|
|
|
|
<P>
|
|
If you add one of
|
|
<P>
|
|
<BR> --enable-pcre2test-libreadline
|
|
<BR> --enable-pcre2test-libedit
|
|
<P>
|
|
to the <B>configure</B> command, <B>pcre2test</B> is linked with the
|
|
<B>libreadline</B> or<B>libedit</B> library, respectively, and when its input is
|
|
from a terminal, it reads it using the <B>readline()</B> function. This provides
|
|
line-editing and history facilities. Note that <B>libreadline</B> is
|
|
GPL-licensed, so if you distribute a binary of <B>pcre2test</B> linked in this
|
|
way, there may be licensing issues. These can be avoided by linking instead
|
|
with <B>libedit</B>, which has a BSD licence.
|
|
<P>
|
|
|
|
Setting --enable-pcre2test-libreadline causes the <B>-lreadline</B> option to be
|
|
added to the <B>pcre2test</B> build. In many operating environments with a
|
|
sytem-installed readline library this is sufficient. However, in some
|
|
environments (e.g. if an unmodified distribution version of readline is in
|
|
use), some extra configuration may be necessary. The INSTALL file for
|
|
<B>libreadline</B> says this:
|
|
<P>
|
|
<BR> "Readline uses the termcap functions, but does not link with
|
|
<BR> the termcap or curses library itself, allowing applications
|
|
<BR> which link with readline the to choose an appropriate library."
|
|
<P>
|
|
If your environment has not been set up so that an appropriate library is
|
|
automatically included, you may need to add something like
|
|
<P>
|
|
<BR> LIBS="-ncurses"
|
|
<P>
|
|
immediately before the <B>configure</B> command.
|
|
<A NAME="lbAT"> </A>
|
|
<H2>INCLUDING DEBUGGING CODE</H2>
|
|
|
|
|
|
<P>
|
|
If you add
|
|
<P>
|
|
<BR> --enable-debug
|
|
<P>
|
|
to the <B>configure</B> command, additional debugging code is included in the
|
|
build. This feature is intended for use by the PCRE2 maintainers.
|
|
<A NAME="lbAU"> </A>
|
|
<H2>DEBUGGING WITH VALGRIND SUPPORT</H2>
|
|
|
|
|
|
<P>
|
|
If you add
|
|
<P>
|
|
<BR> --enable-valgrind
|
|
<P>
|
|
to the <B>configure</B> command, PCRE2 will use valgrind annotations to mark
|
|
certain memory regions as unaddressable. This allows it to detect invalid
|
|
memory accesses, and is mostly useful for debugging PCRE2 itself.
|
|
<A NAME="lbAV"> </A>
|
|
<H2>CODE COVERAGE REPORTING</H2>
|
|
|
|
|
|
<P>
|
|
If your C compiler is gcc, you can build a version of PCRE2 that can generate a
|
|
code coverage report for its test suite. To enable this, you must install
|
|
<B>lcov</B> version 1.6 or above. Then specify
|
|
<P>
|
|
<BR> --enable-coverage
|
|
<P>
|
|
to the <B>configure</B> command and build PCRE2 in the usual way.
|
|
<P>
|
|
|
|
Note that using <B>ccache</B> (a caching C compiler) is incompatible with code
|
|
coverage reporting. If you have configured <B>ccache</B> to run automatically
|
|
on your system, you must set the environment variable
|
|
<P>
|
|
<BR> CCACHE_DISABLE=1
|
|
<P>
|
|
before running <B>make</B> to build PCRE2, so that <B>ccache</B> is not used.
|
|
<P>
|
|
|
|
When --enable-coverage is used, the following addition targets are added to the
|
|
<I>Makefile</I>:
|
|
<P>
|
|
<BR> make coverage
|
|
<P>
|
|
This creates a fresh coverage report for the PCRE2 test suite. It is equivalent
|
|
to running "make coverage-reset", "make coverage-baseline", "make check", and
|
|
then "make coverage-report".
|
|
<P>
|
|
<BR> make coverage-reset
|
|
<P>
|
|
This zeroes the coverage counters, but does nothing else.
|
|
<P>
|
|
<BR> make coverage-baseline
|
|
<P>
|
|
This captures baseline coverage information.
|
|
<P>
|
|
<BR> make coverage-report
|
|
<P>
|
|
This creates the coverage report.
|
|
<P>
|
|
<BR> make coverage-clean-report
|
|
<P>
|
|
This removes the generated coverage report without cleaning the coverage data
|
|
itself.
|
|
<P>
|
|
<BR> make coverage-clean-data
|
|
<P>
|
|
This removes the captured coverage data without removing the coverage files
|
|
created at compile time (*.gcno).
|
|
<P>
|
|
<BR> make coverage-clean
|
|
<P>
|
|
This cleans all coverage data including the generated coverage report. For more
|
|
information about code coverage, see the <B>gcov</B> and <B>lcov</B>
|
|
documentation.
|
|
<A NAME="lbAW"> </A>
|
|
<H2>DISABLING THE Z AND T FORMATTING MODIFIERS</H2>
|
|
|
|
|
|
<P>
|
|
The C99 standard defines formatting modifiers z and t for size_t and
|
|
ptrdiff_t values, respectively. By default, PCRE2 uses these modifiers in
|
|
environments other than Microsoft Visual Studio when __STDC_VERSION__ is
|
|
defined and has a value greater than or equal to 199901L (indicating C99).
|
|
However, there is at least one environment that claims to be C99 but does not
|
|
support these modifiers. If
|
|
<P>
|
|
<BR> --disable-percent-zt
|
|
<P>
|
|
is specified, no use is made of the z or t modifiers. Instead or %td or %zu,
|
|
%lu is used, with a cast for size_t values.
|
|
<A NAME="lbAX"> </A>
|
|
<H2>SUPPORT FOR FUZZERS</H2>
|
|
|
|
|
|
<P>
|
|
There is a special option for use by people who want to run fuzzing tests on
|
|
PCRE2:
|
|
<P>
|
|
<BR> --enable-fuzz-support
|
|
<P>
|
|
At present this applies only to the 8-bit library. If set, it causes an extra
|
|
library called libpcre2-fuzzsupport.a to be built, but not installed. This
|
|
contains a single function called LLVMFuzzerTestOneInput() whose arguments are
|
|
a pointer to a string and the length of the string. When called, this function
|
|
tries to compile the string as a pattern, and if that succeeds, to match it.
|
|
This is done both with no options and with some random options bits that are
|
|
generated from the string.
|
|
<P>
|
|
|
|
Setting --enable-fuzz-support also causes a binary called <B>pcre2fuzzcheck</B>
|
|
to be created. This is normally run under valgrind or used when PCRE2 is
|
|
compiled with address sanitizing enabled. It calls the fuzzing function and
|
|
outputs information about what it is doing. The input strings are specified by
|
|
arguments: if an argument starts with "=" the rest of it is a literal input
|
|
string. Otherwise, it is assumed to be a file name, and the contents of the
|
|
file are the test string.
|
|
<A NAME="lbAY"> </A>
|
|
<H2>OBSOLETE OPTION</H2>
|
|
|
|
|
|
<P>
|
|
In versions of PCRE2 prior to 10.30, there were two ways of handling
|
|
backtracking in the <B>pcre2_match()</B> function. The default was to use the
|
|
system stack, but if
|
|
<P>
|
|
<BR> --disable-stack-for-recursion
|
|
<P>
|
|
was set, memory on the heap was used. From release 10.30 onwards this has
|
|
changed (the stack is no longer used) and this option now does nothing except
|
|
give a warning.
|
|
<A NAME="lbAZ"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
<P>
|
|
<B><A HREF="/cgi-bin/man/man2html?3+pcre2api">pcre2api</A></B>(3), <B><A HREF="/cgi-bin/man/man2html?3+pcre2-config">pcre2-config</A></B>(3).
|
|
<A NAME="lbBA"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
<P>
|
|
<PRE>
|
|
Philip Hazel
|
|
University Computing Service
|
|
Cambridge, England.
|
|
</PRE>
|
|
|
|
<A NAME="lbBB"> </A>
|
|
<H2>REVISION</H2>
|
|
|
|
|
|
<P>
|
|
<PRE>
|
|
Last updated: 03 March 2019
|
|
Copyright (c) 1997-2019 University of Cambridge.
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">BUILDING PCRE2</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">PCRE2 BUILD-TIME OPTIONS</A><DD>
|
|
<DT id="4"><A HREF="#lbAE">BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES</A><DD>
|
|
<DT id="5"><A HREF="#lbAF">BUILDING SHARED AND STATIC LIBRARIES</A><DD>
|
|
<DT id="6"><A HREF="#lbAG">UNICODE AND UTF SUPPORT</A><DD>
|
|
<DT id="7"><A HREF="#lbAH">DISABLING THE USE OF \C</A><DD>
|
|
<DT id="8"><A HREF="#lbAI">JUST-IN-TIME COMPILER SUPPORT</A><DD>
|
|
<DT id="9"><A HREF="#lbAJ">NEWLINE RECOGNITION</A><DD>
|
|
<DT id="10"><A HREF="#lbAK">WHAT \R MATCHES</A><DD>
|
|
<DT id="11"><A HREF="#lbAL">HANDLING VERY LARGE PATTERNS</A><DD>
|
|
<DT id="12"><A HREF="#lbAM">LIMITING PCRE2 RESOURCE USAGE</A><DD>
|
|
<DT id="13"><A HREF="#lbAN">CREATING CHARACTER TABLES AT BUILD TIME</A><DD>
|
|
<DT id="14"><A HREF="#lbAO">USING EBCDIC CODE</A><DD>
|
|
<DT id="15"><A HREF="#lbAP">PCRE2GREP SUPPORT FOR EXTERNAL SCRIPTS</A><DD>
|
|
<DT id="16"><A HREF="#lbAQ">PCRE2GREP OPTIONS FOR COMPRESSED FILE SUPPORT</A><DD>
|
|
<DT id="17"><A HREF="#lbAR">PCRE2GREP BUFFER SIZE</A><DD>
|
|
<DT id="18"><A HREF="#lbAS">PCRE2TEST OPTION FOR LIBREADLINE SUPPORT</A><DD>
|
|
<DT id="19"><A HREF="#lbAT">INCLUDING DEBUGGING CODE</A><DD>
|
|
<DT id="20"><A HREF="#lbAU">DEBUGGING WITH VALGRIND SUPPORT</A><DD>
|
|
<DT id="21"><A HREF="#lbAV">CODE COVERAGE REPORTING</A><DD>
|
|
<DT id="22"><A HREF="#lbAW">DISABLING THE Z AND T FORMATTING MODIFIERS</A><DD>
|
|
<DT id="23"><A HREF="#lbAX">SUPPORT FOR FUZZERS</A><DD>
|
|
<DT id="24"><A HREF="#lbAY">OBSOLETE OPTION</A><DD>
|
|
<DT id="25"><A HREF="#lbAZ">SEE ALSO</A><DD>
|
|
<DT id="26"><A HREF="#lbBA">AUTHOR</A><DD>
|
|
<DT id="27"><A HREF="#lbBB">REVISION</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:49 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|