1<html> 2<head> 3<title>pcre2build specification</title> 4</head> 5<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6<h1>pcre2build man page</h1> 7<p> 8Return to the <a href="index.html">PCRE2 index page</a>. 9</p> 10<p> 11This page is part of the PCRE2 HTML documentation. It was generated 12automatically from the original man page. If there is any nonsense in it, 13please consult the man page, in case the conversion went wrong. 14<br> 15<ul> 16<li><a name="TOC1" href="#SEC1">BUILDING PCRE2</a> 17<li><a name="TOC2" href="#SEC2">PCRE2 BUILD-TIME OPTIONS</a> 18<li><a name="TOC3" href="#SEC3">BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES</a> 19<li><a name="TOC4" href="#SEC4">BUILDING SHARED AND STATIC LIBRARIES</a> 20<li><a name="TOC5" href="#SEC5">UNICODE AND UTF SUPPORT</a> 21<li><a name="TOC6" href="#SEC6">DISABLING THE USE OF \C</a> 22<li><a name="TOC7" href="#SEC7">JUST-IN-TIME COMPILER SUPPORT</a> 23<li><a name="TOC8" href="#SEC8">NEWLINE RECOGNITION</a> 24<li><a name="TOC9" href="#SEC9">WHAT \R MATCHES</a> 25<li><a name="TOC10" href="#SEC10">HANDLING VERY LARGE PATTERNS</a> 26<li><a name="TOC11" href="#SEC11">LIMITING PCRE2 RESOURCE USAGE</a> 27<li><a name="TOC12" href="#SEC12">LIMITING VARIABLE-LENGTH LOOKBEHIND ASSERTIONS</a> 28<li><a name="TOC13" href="#SEC13">CREATING CHARACTER TABLES AT BUILD TIME</a> 29<li><a name="TOC14" href="#SEC14">USING EBCDIC CODE</a> 30<li><a name="TOC15" href="#SEC15">PCRE2GREP SUPPORT FOR EXTERNAL SCRIPTS</a> 31<li><a name="TOC16" href="#SEC16">PCRE2GREP OPTIONS FOR COMPRESSED FILE SUPPORT</a> 32<li><a name="TOC17" href="#SEC17">PCRE2GREP BUFFER SIZE</a> 33<li><a name="TOC18" href="#SEC18">PCRE2TEST OPTION FOR LIBREADLINE SUPPORT</a> 34<li><a name="TOC19" href="#SEC19">INCLUDING DEBUGGING CODE</a> 35<li><a name="TOC20" href="#SEC20">DEBUGGING WITH VALGRIND SUPPORT</a> 36<li><a name="TOC21" href="#SEC21">CODE COVERAGE REPORTING</a> 37<li><a name="TOC22" href="#SEC22">DISABLING THE Z AND T FORMATTING MODIFIERS</a> 38<li><a name="TOC23" href="#SEC23">SUPPORT FOR FUZZERS</a> 39<li><a name="TOC24" href="#SEC24">OBSOLETE OPTION</a> 40<li><a name="TOC25" href="#SEC25">SEE ALSO</a> 41<li><a name="TOC26" href="#SEC26">AUTHOR</a> 42<li><a name="TOC27" href="#SEC27">REVISION</a> 43</ul> 44<br><a name="SEC1" href="#TOC1">BUILDING PCRE2</a><br> 45<P> 46PCRE2 is distributed with a <b>configure</b> script that can be used to build 47the library in Unix-like environments using the applications known as 48Autotools. Also in the distribution are files to support building using 49<b>CMake</b> instead of <b>configure</b>. The text file 50<a href="README.txt"><b>README</b></a> 51contains general information about building with Autotools (some of which is 52repeated below), and also has some comments about building on various operating 53systems. The files in the <b>vms</b> directory support building under OpenVMS. 54There is a lot more information about building PCRE2 without using 55Autotools (including information about using <b>CMake</b> and building "by 56hand") in the text file called 57<a href="NON-AUTOTOOLS-BUILD.txt"><b>NON-AUTOTOOLS-BUILD</b>.</a> 58You should consult this file as well as the 59<a href="README.txt"><b>README</b></a> 60file if you are building in a non-Unix-like environment. 61</P> 62<br><a name="SEC2" href="#TOC1">PCRE2 BUILD-TIME OPTIONS</a><br> 63<P> 64The rest of this document describes the optional features of PCRE2 that can be 65selected when the library is compiled. It assumes use of the <b>configure</b> 66script, where the optional features are selected or deselected by providing 67options to <b>configure</b> before running the <b>make</b> command. However, the 68same options can be selected in both Unix-like and non-Unix-like environments 69if you are using <b>CMake</b> instead of <b>configure</b> to build PCRE2. 70</P> 71<P> 72If you are not using Autotools or <b>CMake</b>, option selection can be done by 73editing the <b>config.h</b> file, or by passing parameter settings to the 74compiler, as described in 75<a href="NON-AUTOTOOLS-BUILD.txt"><b>NON-AUTOTOOLS-BUILD</b>.</a> 76</P> 77<P> 78The complete list of options for <b>configure</b> (which includes the standard 79ones such as the selection of the installation directory) can be obtained by 80running 81<pre> 82 ./configure --help 83</pre> 84The following sections include descriptions of "on/off" options whose names 85begin with --enable or --disable. Because of the way that <b>configure</b> 86works, --enable and --disable always come in pairs, so the complementary option 87always exists as well, but as it specifies the default, it is not described. 88Options that specify values have names that start with --with. At the end of a 89<b>configure</b> run, a summary of the configuration is output. 90</P> 91<br><a name="SEC3" href="#TOC1">BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES</a><br> 92<P> 93By default, a library called <b>libpcre2-8</b> is built, containing functions 94that take string arguments contained in arrays of bytes, interpreted either as 95single-byte characters, or UTF-8 strings. You can also build two other 96libraries, called <b>libpcre2-16</b> and <b>libpcre2-32</b>, which process 97strings that are contained in arrays of 16-bit and 32-bit code units, 98respectively. These can be interpreted either as single-unit characters or 99UTF-16/UTF-32 strings. To build these additional libraries, add one or both of 100the following to the <b>configure</b> command: 101<pre> 102 --enable-pcre2-16 103 --enable-pcre2-32 104</pre> 105If you do not want the 8-bit library, add 106<pre> 107 --disable-pcre2-8 108</pre> 109as well. At least one of the three libraries must be built. Note that the POSIX 110wrapper is for the 8-bit library only, and that <b>pcre2grep</b> is an 8-bit 111program. Neither of these are built if you select only the 16-bit or 32-bit 112libraries. 113</P> 114<br><a name="SEC4" href="#TOC1">BUILDING SHARED AND STATIC LIBRARIES</a><br> 115<P> 116The Autotools PCRE2 building process uses <b>libtool</b> to build both shared 117and static libraries by default. You can suppress an unwanted library by adding 118one of 119<pre> 120 --disable-shared 121 --disable-static 122</pre> 123to the <b>configure</b> command. Setting --disable-shared ensures that PCRE2 124libraries are built as static libraries. The binaries that are then created as 125part of the build process (for example, <b>pcre2test</b> and <b>pcre2grep</b>) 126are linked statically with one or more PCRE2 libraries, but may also be 127dynamically linked with other libraries such as <b>libc</b>. If you want these 128binaries to be fully statically linked, you can set LDFLAGS like this: 129<br> 130<br> 131LDFLAGS=--static ./configure --disable-shared 132<br> 133<br> 134Note the two hyphens in --static. Of course, this works only if static versions 135of all the relevant libraries are available for linking. 136</P> 137<br><a name="SEC5" href="#TOC1">UNICODE AND UTF SUPPORT</a><br> 138<P> 139By default, PCRE2 is built with support for Unicode and UTF character strings. 140To build it without Unicode support, add 141<pre> 142 --disable-unicode 143</pre> 144to the <b>configure</b> command. This setting applies to all three libraries. It 145is not possible to build one library with Unicode support and another without 146in the same configuration. 147</P> 148<P> 149Of itself, Unicode support does not make PCRE2 treat strings as UTF-8, UTF-16 150or UTF-32. To do that, applications that use the library can set the PCRE2_UTF 151option when they call <b>pcre2_compile()</b> to compile a pattern. 152Alternatively, patterns may be started with (*UTF) unless the application has 153locked this out by setting PCRE2_NEVER_UTF. 154</P> 155<P> 156UTF support allows the libraries to process character code points up to 1570x10ffff in the strings that they handle. Unicode support also gives access to 158the Unicode properties of characters, using pattern escapes such as \P, \p, 159and \X. Only the general category properties such as <i>Lu</i> and <i>Nd</i>, 160script names, and some bi-directional properties are supported. Details are 161given in the 162<a href="pcre2pattern.html"><b>pcre2pattern</b></a> 163documentation. 164</P> 165<P> 166Pattern escapes such as \d and \w do not by default make use of Unicode 167properties. The application can request that they do by setting the PCRE2_UCP 168option. Unless the application has set PCRE2_NEVER_UCP, a pattern may also 169request this by starting with (*UCP). 170</P> 171<br><a name="SEC6" href="#TOC1">DISABLING THE USE OF \C</a><br> 172<P> 173The \C escape sequence, which matches a single code unit, even in a UTF mode, 174can cause unpredictable behaviour because it may leave the current matching 175point in the middle of a multi-code-unit character. The application can lock it 176out by setting the PCRE2_NEVER_BACKSLASH_C option when calling 177<b>pcre2_compile()</b>. There is also a build-time option 178<pre> 179 --enable-never-backslash-C 180</pre> 181(note the upper case C) which locks out the use of \C entirely. 182</P> 183<br><a name="SEC7" href="#TOC1">JUST-IN-TIME COMPILER SUPPORT</a><br> 184<P> 185Just-in-time (JIT) compiler support is included in the build by specifying 186<pre> 187 --enable-jit 188</pre> 189This support is available only for certain hardware architectures. If this 190option is set for an unsupported architecture, a building error occurs. 191If in doubt, use 192<pre> 193 --enable-jit=auto 194</pre> 195which enables JIT only if the current hardware is supported. You can check 196if JIT is enabled in the configuration summary that is output at the end of a 197<b>configure</b> run. If you are enabling JIT under SELinux you may also want to 198add 199<pre> 200 --enable-jit-sealloc 201</pre> 202which enables the use of an execmem allocator in JIT that is compatible with 203SELinux. This has no effect if JIT is not enabled. See the 204<a href="pcre2jit.html"><b>pcre2jit</b></a> 205documentation for a discussion of JIT usage. When JIT support is enabled, 206<b>pcre2grep</b> automatically makes use of it, unless you add 207<pre> 208 --disable-pcre2grep-jit 209</pre> 210to the <b>configure</b> command. 211</P> 212<br><a name="SEC8" href="#TOC1">NEWLINE RECOGNITION</a><br> 213<P> 214By default, PCRE2 interprets the linefeed (LF) character as indicating the end 215of a line. This is the normal newline character on Unix-like systems. You can 216compile PCRE2 to use carriage return (CR) instead, by adding 217<pre> 218 --enable-newline-is-cr 219</pre> 220to the <b>configure</b> command. There is also an --enable-newline-is-lf option, 221which explicitly specifies linefeed as the newline character. 222</P> 223<P> 224Alternatively, you can specify that line endings are to be indicated by the 225two-character sequence CRLF (CR immediately followed by LF). If you want this, 226add 227<pre> 228 --enable-newline-is-crlf 229</pre> 230to the <b>configure</b> command. There is a fourth option, specified by 231<pre> 232 --enable-newline-is-anycrlf 233</pre> 234which causes PCRE2 to recognize any of the three sequences CR, LF, or CRLF as 235indicating a line ending. A fifth option, specified by 236<pre> 237 --enable-newline-is-any 238</pre> 239causes PCRE2 to recognize any Unicode newline sequence. The Unicode newline 240sequences are the three just mentioned, plus the single characters VT (vertical 241tab, U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line 242separator, U+2028), and PS (paragraph separator, U+2029). The final option is 243<pre> 244 --enable-newline-is-nul 245</pre> 246which causes NUL (binary zero) to be set as the default line-ending character. 247</P> 248<P> 249Whatever default line ending convention is selected when PCRE2 is built can be 250overridden by applications that use the library. At build time it is 251recommended to use the standard for your operating system. 252</P> 253<br><a name="SEC9" href="#TOC1">WHAT \R MATCHES</a><br> 254<P> 255By default, the sequence \R in a pattern matches any Unicode newline sequence, 256independently of what has been selected as the line ending sequence. If you 257specify 258<pre> 259 --enable-bsr-anycrlf 260</pre> 261the default is changed so that \R matches only CR, LF, or CRLF. Whatever is 262selected when PCRE2 is built can be overridden by applications that use the 263library. 264</P> 265<br><a name="SEC10" href="#TOC1">HANDLING VERY LARGE PATTERNS</a><br> 266<P> 267Within a compiled pattern, offset values are used to point from one part to 268another (for example, from an opening parenthesis to an alternation 269metacharacter). By default, in the 8-bit and 16-bit libraries, two-byte values 270are used for these offsets, leading to a maximum size for a compiled pattern of 271around 64 thousand code units. This is sufficient to handle all but the most 272gigantic patterns. Nevertheless, some people do want to process truly enormous 273patterns, so it is possible to compile PCRE2 to use three-byte or four-byte 274offsets by adding a setting such as 275<pre> 276 --with-link-size=3 277</pre> 278to the <b>configure</b> command. The value given must be 2, 3, or 4. For the 27916-bit library, a value of 3 is rounded up to 4. In these libraries, using 280longer offsets slows down the operation of PCRE2 because it has to load 281additional data when handling them. For the 32-bit library the value is always 2824 and cannot be overridden; the value of --with-link-size is ignored. 283</P> 284<br><a name="SEC11" href="#TOC1">LIMITING PCRE2 RESOURCE USAGE</a><br> 285<P> 286The <b>pcre2_match()</b> function increments a counter each time it goes round 287its main loop. Putting a limit on this counter controls the amount of computing 288resource used by a single call to <b>pcre2_match()</b>. The limit can be changed 289at run time, as described in the 290<a href="pcre2api.html"><b>pcre2api</b></a> 291documentation. The default is 10 million, but this can be changed by adding a 292setting such as 293<pre> 294 --with-match-limit=500000 295</pre> 296to the <b>configure</b> command. This setting also applies to the 297<b>pcre2_dfa_match()</b> matching function, and to JIT matching (though the 298counting is done differently). 299</P> 300<P> 301The <b>pcre2_match()</b> function uses heap memory to record backtracking 302points. The more nested backtracking points there are (that is, the deeper the 303search tree), the more memory is needed. There is an upper limit, specified in 304kibibytes (units of 1024 bytes). This limit can be changed at run time, as 305described in the 306<a href="pcre2api.html"><b>pcre2api</b></a> 307documentation. The default limit (in effect unlimited) is 20 million. You can 308change this by a setting such as 309<pre> 310 --with-heap-limit=500 311</pre> 312which limits the amount of heap to 500 KiB. This limit applies only to 313interpretive matching in <b>pcre2_match()</b> and <b>pcre2_dfa_match()</b>, which 314may also use the heap for internal workspace when processing complicated 315patterns. This limit does not apply when JIT (which has its own memory 316arrangements) is used. 317</P> 318<P> 319You can also explicitly limit the depth of nested backtracking in the 320<b>pcre2_match()</b> interpreter. This limit defaults to the value that is set 321for --with-match-limit. You can set a lower default limit by adding, for 322example, 323<pre> 324 --with-match-limit-depth=10000 325</pre> 326to the <b>configure</b> command. This value can be overridden at run time. This 327depth limit indirectly limits the amount of heap memory that is used, but 328because the size of each backtracking "frame" depends on the number of 329capturing parentheses in a pattern, the amount of heap that is used before the 330limit is reached varies from pattern to pattern. This limit was more useful in 331versions before 10.30, where function recursion was used for backtracking. 332</P> 333<P> 334As well as applying to <b>pcre2_match()</b>, the depth limit also controls 335the depth of recursive function calls in <b>pcre2_dfa_match()</b>. These are 336used for lookaround assertions, atomic groups, and recursion within patterns. 337The limit does not apply to JIT matching. 338</P> 339<br><a name="SEC12" href="#TOC1">LIMITING VARIABLE-LENGTH LOOKBEHIND ASSERTIONS</a><br> 340<P> 341Lookbehind assertions in which one or more branches can match a variable number 342of characters are supported only if there is a maximum matching length for each 343top-level branch. There is a limit to this maximum that defaults to 255 344characters. You can alter this default by a setting such as 345<pre> 346 --with-max-varlookbehind=100 347</pre> 348The limit can be changed at runtime by calling 349<b>pcre2_set_max_varlookbehind()</b>. Lookbehind assertions in which every 350branch matches a fixed number of characters (not necessarily all the same) are 351not constrained by this limit. 352<a name="createtables"></a></P> 353<br><a name="SEC13" href="#TOC1">CREATING CHARACTER TABLES AT BUILD TIME</a><br> 354<P> 355PCRE2 uses fixed tables for processing characters whose code points are less 356than 256. By default, PCRE2 is built with a set of tables that are distributed 357in the file <i>src/pcre2_chartables.c.dist</i>. These tables are for ASCII codes 358only. If you add 359<pre> 360 --enable-rebuild-chartables 361</pre> 362to the <b>configure</b> command, the distributed tables are no longer used. 363Instead, a program called <b>pcre2_dftables</b> is compiled and run. This 364outputs the source for new set of tables, created in the default locale of your 365C run-time system. This method of replacing the tables does not work if you are 366cross compiling, because <b>pcre2_dftables</b> needs to be run on the local 367host and therefore not compiled with the cross compiler. 368</P> 369<P> 370If you need to create alternative tables when cross compiling, you will have to 371do so "by hand". There may also be other reasons for creating tables manually. 372To cause <b>pcre2_dftables</b> to be built on the local host, run a normal 373compiling command, and then run the program with the output file as its 374argument, for example: 375<pre> 376 cc src/pcre2_dftables.c -o pcre2_dftables 377 ./pcre2_dftables src/pcre2_chartables.c 378</pre> 379This builds the tables in the default locale of the local host. If you want to 380specify a locale, you must use the -L option: 381<pre> 382 LC_ALL=fr_FR ./pcre2_dftables -L src/pcre2_chartables.c 383</pre> 384You can also specify -b (with or without -L). This causes the tables to be 385written in binary instead of as source code. A set of binary tables can be 386loaded into memory by an application and passed to <b>pcre2_compile()</b> in the 387same way as tables created by calling <b>pcre2_maketables()</b>. The tables are 388just a string of bytes, independent of hardware characteristics such as 389endianness. This means they can be bundled with an application that runs in 390different environments, to ensure consistent behaviour. 391</P> 392<br><a name="SEC14" href="#TOC1">USING EBCDIC CODE</a><br> 393<P> 394PCRE2 assumes by default that it will run in an environment where the character 395code is ASCII or Unicode, which is a superset of ASCII. This is the case for 396most computer operating systems. PCRE2 can, however, be compiled to run in an 3978-bit EBCDIC environment by adding 398<pre> 399 --enable-ebcdic --disable-unicode 400</pre> 401to the <b>configure</b> command. This setting implies 402--enable-rebuild-chartables. You should only use it if you know that you are in 403an EBCDIC environment (for example, an IBM mainframe operating system). 404</P> 405<P> 406It is not possible to support both EBCDIC and UTF-8 codes in the same version 407of the library. Consequently, --enable-unicode and --enable-ebcdic are mutually 408exclusive. 409</P> 410<P> 411The EBCDIC character that corresponds to an ASCII LF is assumed to have the 412value 0x15 by default. However, in some EBCDIC environments, 0x25 is used. In 413such an environment you should use 414<pre> 415 --enable-ebcdic-nl25 416</pre> 417as well as, or instead of, --enable-ebcdic. The EBCDIC character for CR has the 418same value as in ASCII, namely, 0x0d. Whichever of 0x15 and 0x25 is <i>not</i> 419chosen as LF is made to correspond to the Unicode NEL character (which, in 420Unicode, is 0x85). 421</P> 422<P> 423The options that select newline behaviour, such as --enable-newline-is-cr, 424and equivalent run-time options, refer to these character values in an EBCDIC 425environment. 426</P> 427<br><a name="SEC15" href="#TOC1">PCRE2GREP SUPPORT FOR EXTERNAL SCRIPTS</a><br> 428<P> 429By default <b>pcre2grep</b> supports the use of callouts with string arguments 430within the patterns it is matching. There are two kinds: one that generates 431output using local code, and another that calls an external program or script. 432If --disable-pcre2grep-callout-fork is added to the <b>configure</b> command, 433only the first kind of callout is supported; if --disable-pcre2grep-callout is 434used, all callouts are completely ignored. For more details of <b>pcre2grep</b> 435callouts, see the 436<a href="pcre2grep.html"><b>pcre2grep</b></a> 437documentation. 438</P> 439<br><a name="SEC16" href="#TOC1">PCRE2GREP OPTIONS FOR COMPRESSED FILE SUPPORT</a><br> 440<P> 441By default, <b>pcre2grep</b> reads all files as plain text. You can build it so 442that it recognizes files whose names end in <b>.gz</b> or <b>.bz2</b>, and reads 443them with <b>libz</b> or <b>libbz2</b>, respectively, by adding one or both of 444<pre> 445 --enable-pcre2grep-libz 446 --enable-pcre2grep-libbz2 447</pre> 448to the <b>configure</b> command. These options naturally require that the 449relevant libraries are installed on your system. Configuration will fail if 450they are not. 451</P> 452<br><a name="SEC17" href="#TOC1">PCRE2GREP BUFFER SIZE</a><br> 453<P> 454<b>pcre2grep</b> uses an internal buffer to hold a "window" on the file it is 455scanning, in order to be able to output "before" and "after" lines when it 456finds a match. The default starting size of the buffer is 20KiB. The buffer 457itself is three times this size, but because of the way it is used for holding 458"before" lines, the longest line that is guaranteed to be processable is the 459notional buffer size. If a longer line is encountered, <b>pcre2grep</b> 460automatically expands the buffer, up to a specified maximum size, whose default 461is 1MiB or the starting size, whichever is the larger. You can change the 462default parameter values by adding, for example, 463<pre> 464 --with-pcre2grep-bufsize=51200 465 --with-pcre2grep-max-bufsize=2097152 466</pre> 467to the <b>configure</b> command. The caller of <b>pcre2grep</b> can override 468these values by using --buffer-size and --max-buffer-size on the command line. 469</P> 470<br><a name="SEC18" href="#TOC1">PCRE2TEST OPTION FOR LIBREADLINE SUPPORT</a><br> 471<P> 472If you add one of 473<pre> 474 --enable-pcre2test-libreadline 475 --enable-pcre2test-libedit 476</pre> 477to the <b>configure</b> command, <b>pcre2test</b> is linked with the 478<b>libreadline</b> or<b>libedit</b> library, respectively, and when its input is 479from a terminal, it reads it using the <b>readline()</b> function. This provides 480line-editing and history facilities. Note that <b>libreadline</b> is 481GPL-licensed, so if you distribute a binary of <b>pcre2test</b> linked in this 482way, there may be licensing issues. These can be avoided by linking instead 483with <b>libedit</b>, which has a BSD licence. 484</P> 485<P> 486Setting --enable-pcre2test-libreadline causes the <b>-lreadline</b> option to be 487added to the <b>pcre2test</b> build. In many operating environments with a 488system-installed readline library this is sufficient. However, in some 489environments (e.g. if an unmodified distribution version of readline is in 490use), some extra configuration may be necessary. The INSTALL file for 491<b>libreadline</b> says this: 492<pre> 493 "Readline uses the termcap functions, but does not link with 494 the termcap or curses library itself, allowing applications 495 which link with readline the to choose an appropriate library." 496</pre> 497If your environment has not been set up so that an appropriate library is 498automatically included, you may need to add something like 499<pre> 500 LIBS="-ncurses" 501</pre> 502immediately before the <b>configure</b> command. 503</P> 504<br><a name="SEC19" href="#TOC1">INCLUDING DEBUGGING CODE</a><br> 505<P> 506If you add 507<pre> 508 --enable-debug 509</pre> 510to the <b>configure</b> command, additional debugging code is included in the 511build. This feature is intended for use by the PCRE2 maintainers. 512</P> 513<br><a name="SEC20" href="#TOC1">DEBUGGING WITH VALGRIND SUPPORT</a><br> 514<P> 515If you add 516<pre> 517 --enable-valgrind 518</pre> 519to the <b>configure</b> command, PCRE2 will use valgrind annotations to mark 520certain memory regions as unaddressable. This allows it to detect invalid 521memory accesses, and is mostly useful for debugging PCRE2 itself. 522</P> 523<br><a name="SEC21" href="#TOC1">CODE COVERAGE REPORTING</a><br> 524<P> 525If your C compiler is gcc, you can build a version of PCRE2 that can generate a 526code coverage report for its test suite. To enable this, you must install 527<b>lcov</b> version 1.6 or above. Then specify 528<pre> 529 --enable-coverage 530</pre> 531to the <b>configure</b> command and build PCRE2 in the usual way. 532</P> 533<P> 534Note that using <b>ccache</b> (a caching C compiler) is incompatible with code 535coverage reporting. If you have configured <b>ccache</b> to run automatically 536on your system, you must set the environment variable 537<pre> 538 CCACHE_DISABLE=1 539</pre> 540before running <b>make</b> to build PCRE2, so that <b>ccache</b> is not used. 541</P> 542<P> 543When --enable-coverage is used, the following addition targets are added to the 544<i>Makefile</i>: 545<pre> 546 make coverage 547</pre> 548This creates a fresh coverage report for the PCRE2 test suite. It is equivalent 549to running "make coverage-reset", "make coverage-baseline", "make check", and 550then "make coverage-report". 551<pre> 552 make coverage-reset 553</pre> 554This zeroes the coverage counters, but does nothing else. 555<pre> 556 make coverage-baseline 557</pre> 558This captures baseline coverage information. 559<pre> 560 make coverage-report 561</pre> 562This creates the coverage report. 563<pre> 564 make coverage-clean-report 565</pre> 566This removes the generated coverage report without cleaning the coverage data 567itself. 568<pre> 569 make coverage-clean-data 570</pre> 571This removes the captured coverage data without removing the coverage files 572created at compile time (*.gcno). 573<pre> 574 make coverage-clean 575</pre> 576This cleans all coverage data including the generated coverage report. For more 577information about code coverage, see the <b>gcov</b> and <b>lcov</b> 578documentation. 579</P> 580<br><a name="SEC22" href="#TOC1">DISABLING THE Z AND T FORMATTING MODIFIERS</a><br> 581<P> 582The C99 standard defines formatting modifiers z and t for size_t and 583ptrdiff_t values, respectively. By default, PCRE2 uses these modifiers in 584environments other than old versions of Microsoft Visual Studio when 585__STDC_VERSION__ is defined and has a value greater than or equal to 199901L 586(indicating support for C99). 587However, there is at least one environment that claims to be C99 but does not 588support these modifiers. If 589<pre> 590 --disable-percent-zt 591</pre> 592is specified, no use is made of the z or t modifiers. Instead of %td or %zu, 593a suitable format is used depending in the size of long for the platform. 594</P> 595<br><a name="SEC23" href="#TOC1">SUPPORT FOR FUZZERS</a><br> 596<P> 597There is a special option for use by people who want to run fuzzing tests on 598PCRE2: 599<pre> 600 --enable-fuzz-support 601</pre> 602At present this applies only to the 8-bit library. If set, it causes an extra 603library called libpcre2-fuzzsupport.a to be built, but not installed. This 604contains a single function called LLVMFuzzerTestOneInput() whose arguments are 605a pointer to a string and the length of the string. When called, this function 606tries to compile the string as a pattern, and if that succeeds, to match it. 607This is done both with no options and with some random options bits that are 608generated from the string. 609</P> 610<P> 611Setting --enable-fuzz-support also causes a binary called <b>pcre2fuzzcheck</b> 612to be created. This is normally run under valgrind or used when PCRE2 is 613compiled with address sanitizing enabled. It calls the fuzzing function and 614outputs information about what it is doing. The input strings are specified by 615arguments: if an argument starts with "=" the rest of it is a literal input 616string. Otherwise, it is assumed to be a file name, and the contents of the 617file are the test string. 618</P> 619<br><a name="SEC24" href="#TOC1">OBSOLETE OPTION</a><br> 620<P> 621In versions of PCRE2 prior to 10.30, there were two ways of handling 622backtracking in the <b>pcre2_match()</b> function. The default was to use the 623system stack, but if 624<pre> 625 --disable-stack-for-recursion 626</pre> 627was set, memory on the heap was used. From release 10.30 onwards this has 628changed (the stack is no longer used) and this option now does nothing except 629give a warning. 630</P> 631<br><a name="SEC25" href="#TOC1">SEE ALSO</a><br> 632<P> 633<b>pcre2api</b>(3), <b>pcre2-config</b>(3). 634</P> 635<br><a name="SEC26" href="#TOC1">AUTHOR</a><br> 636<P> 637Philip Hazel 638<br> 639Retired from University Computing Service 640<br> 641Cambridge, England. 642<br> 643</P> 644<br><a name="SEC27" href="#TOC1">REVISION</a><br> 645<P> 646Last updated: 15 April 2024 647<br> 648Copyright © 1997-2024 University of Cambridge. 649<br> 650<p> 651Return to the <a href="index.html">PCRE2 index page</a>. 652</p> 653