diff options
Diffstat (limited to 'srclib/pcre/doc/pcrebuild.3')
| -rw-r--r-- | srclib/pcre/doc/pcrebuild.3 | 174 |
1 files changed, 0 insertions, 174 deletions
diff --git a/srclib/pcre/doc/pcrebuild.3 b/srclib/pcre/doc/pcrebuild.3 deleted file mode 100644 index 8ac588281d..0000000000 --- a/srclib/pcre/doc/pcrebuild.3 +++ /dev/null @@ -1,174 +0,0 @@ -.TH PCRE 3 -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PCRE BUILD-TIME OPTIONS" -.rs -.sp -This document describes the optional features of PCRE that can be selected when -the library is compiled. They are all selected, or deselected, by providing -options to the \fBconfigure\fP script that is run before the \fBmake\fP -command. The complete list of options for \fBconfigure\fP (which includes the -standard ones such as the selection of the installation directory) can be -obtained by running -.sp - ./configure --help -.sp -The following sections describe certain options whose names begin with --enable -or --disable. These settings specify changes to the defaults for the -\fBconfigure\fP command. Because of the way that \fBconfigure\fP 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. -. -.SH "UTF-8 SUPPORT" -.rs -.sp -To build PCRE with support for UTF-8 character strings, add -.sp - --enable-utf8 -.sp -to the \fBconfigure\fP command. Of itself, this does not make PCRE treat -strings as UTF-8. As well as compiling PCRE with this option, you also have -have to set the PCRE_UTF8 option when you call the \fBpcre_compile()\fP -function. -. -.SH "UNICODE CHARACTER PROPERTY SUPPORT" -.rs -.sp -UTF-8 support allows PCRE to process character values greater than 255 in the -strings that it handles. On its own, however, it does not provide any -facilities for accessing the properties of such characters. If you want to be -able to use the pattern escapes \eP, \ep, and \eX, which refer to Unicode -character properties, you must add -.sp - --enable-unicode-properties -.sp -to the \fBconfigure\fP command. This implies UTF-8 support, even if you have -not explicitly requested it. -.P -Including Unicode property support adds around 90K of tables to the PCRE -library, approximately doubling its size. Only the general category properties -such as \fILu\fP and \fINd\fP are supported. Details are given in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation. -. -.SH "CODE VALUE OF NEWLINE" -.rs -.sp -By default, PCRE treats character 10 (linefeed) as the newline character. This -is the normal newline character on Unix-like systems. You can compile PCRE to -use character 13 (carriage return) instead by adding -.sp - --enable-newline-is-cr -.sp -to the \fBconfigure\fP command. For completeness there is also a ---enable-newline-is-lf option, which explicitly specifies linefeed as the -newline character. -. -.SH "BUILDING SHARED AND STATIC LIBRARIES" -.rs -.sp -The PCRE building process uses \fBlibtool\fP to build both shared and static -Unix libraries by default. You can suppress one of these by adding one of -.sp - --disable-shared - --disable-static -.sp -to the \fBconfigure\fP command, as required. -. -.SH "POSIX MALLOC USAGE" -.rs -.sp -When PCRE is called through the POSIX interface (see the -.\" HREF -\fBpcreposix\fP -.\" -documentation), additional working storage is required for holding the pointers -to capturing substrings, because PCRE requires three integers per substring, -whereas the POSIX interface provides only two. If the number of expected -substrings is small, the wrapper function uses space on the stack, because this -is faster than using \fBmalloc()\fP for each call. The default threshold above -which the stack is no longer used is 10; it can be changed by adding a setting -such as -.sp - --with-posix-malloc-threshold=20 -.sp -to the \fBconfigure\fP command. -. -.SH "LIMITING PCRE RESOURCE USAGE" -.rs -.sp -Internally, PCRE has a function called \fBmatch()\fP, which it calls repeatedly -(possibly recursively) when matching a pattern. By controlling the maximum -number of times this function may be called during a single matching operation, -a limit can be placed on the resources used by a single call to -\fBpcre_exec()\fP. The limit can be changed at run time, as described in the -.\" HREF -\fBpcreapi\fP -.\" -documentation. The default is 10 million, but this can be changed by adding a -setting such as -.sp - --with-match-limit=500000 -.sp -to the \fBconfigure\fP command. -. -.SH "HANDLING VERY LARGE PATTERNS" -.rs -.sp -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, two-byte values are used for these offsets, leading -to a maximum size for a compiled pattern of around 64K. This is sufficient to -handle all but the most gigantic patterns. Nevertheless, some people do want to -process enormous patterns, so it is possible to compile PCRE to use three-byte -or four-byte offsets by adding a setting such as -.sp - --with-link-size=3 -.sp -to the \fBconfigure\fP command. The value given must be 2, 3, or 4. Using -longer offsets slows down the operation of PCRE because it has to load -additional bytes when handling them. -.P -If you build PCRE with an increased link size, test 2 (and test 5 if you are -using UTF-8) will fail. Part of the output of these tests is a representation -of the compiled pattern, and this changes with the link size. -. -.SH "AVOIDING EXCESSIVE STACK USAGE" -.rs -.sp -PCRE implements backtracking while matching by making recursive calls to an -internal function called \fBmatch()\fP. In environments where the size of the -stack is limited, this can severely limit PCRE's operation. (The Unix -environment does not usually suffer from this problem.) An alternative approach -that uses memory from the heap to remember data, instead of using recursive -function calls, has been implemented to work round this problem. If you want to -build a version of PCRE that works this way, add -.sp - --disable-stack-for-recursion -.sp -to the \fBconfigure\fP command. With this configuration, PCRE will use the -\fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP variables to call memory -management functions. Separate functions are provided because the usage is very -predictable: the block sizes requested are always the same, and the blocks are -always freed in reverse order. A calling program might be able to implement -optimized functions that perform better than the standard \fBmalloc()\fP and -\fBfree()\fP functions. PCRE runs noticeably more slowly when built in this -way. -. -.SH "USING EBCDIC CODE" -.rs -.sp -PCRE assumes by default that it will run in an environment where the character -code is ASCII (or Unicode, which is a superset of ASCII). PCRE can, however, be -compiled to run in an EBCDIC environment by adding -.sp - --enable-ebcdic -.sp -to the \fBconfigure\fP command. -.P -.in 0 -Last updated: 09 September 2004 -.br -Copyright (c) 1997-2004 University of Cambridge. |