@@ -63,8 +64,27 @@ The following sections include descriptions of options --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.
-+By default, a library called libpcre is built, containing functions that +take string arguments contained in vectors of bytes, either as single-byte +characters, or interpreted as UTF-8 strings. You can also build a separate +library, called libpcre16, in which strings are contained in vectors of +16-bit data units and interpreted either as single-unit characters or UTF-16 +strings, by adding +
+ --enable-pcre16 ++to the configure command. If you do not want the 8-bit library, add +
+ --disable-pcre8 ++as well. At least one of the two libraries must be built. Note that the C++ and +POSIX wrappers are for the 8-bit library only, and that pcregrep is an +8-bit program. None of these are built if you select only the 16-bit library. + +
The PCRE building process uses libtool to build both shared and static Unix libraries by default. You can suppress one of these by adding one of
@@ -73,45 +93,56 @@ Unix libraries by default. You can suppress one of theto the configure command, as required. -
-By default, the configure script will search for a C++ compiler and C++ -header files. If it finds them, it automatically builds the C++ wrapper library -for PCRE. You can disable this by adding +By default, if the 8-bit library is being built, the configure script +will search for a C++ compiler and C++ header files. If it finds them, it +automatically builds the C++ wrapper library (which supports only 8-bit +strings). You can disable this by adding
--disable-cppto the configure command. -
-To build PCRE with support for UTF-8 Unicode character strings, add +To build PCRE with support for UTF Unicode character strings, add
- --enable-utf8 + --enable-utf-to the configure 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 pcre_compile() -or pcre_compile2() functions. +to the configure command. This setting applies to both libraries, adding +support for UTF-8 to the 8-bit library and support for UTF-16 to the 16-bit +library. There are no separate options for enabling UTF-8 and UTF-16 +independently because that would allow ridiculous settings such as requesting +UTF-16 support while building only the 8-bit library. It is not possible to +build one library with UTF support and the other without in the same +configuration. (For backwards compatibility, --enable-utf8 is a synonym of +--enable-utf.)
-If you set --enable-utf8 when compiling in an EBCDIC environment, PCRE expects +Of itself, this setting does not make PCRE treat strings as UTF-8 or UTF-16. As +well as compiling PCRE with this option, you also have have to set the +PCRE_UTF8 or PCRE_UTF16 option when you call one of the pattern compiling +functions. +
++If you set --enable-utf when compiling in an EBCDIC environment, PCRE expects its input to be either ASCII or UTF-8 (depending on the runtime option). It is not possible to support both EBCDIC and UTF-8 codes in the same version of the -library. Consequently, --enable-utf8 and --enable-ebcdic are mutually +library. Consequently, --enable-utf and --enable-ebcdic are mutually exclusive.
--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 +UTF support allows the libraries to process character codepoints up to 0x10ffff +in the strings that they handle. 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 \P, \p, and \X, which refer to Unicode character properties, you must add
--enable-unicode-properties-to the configure command. This implies UTF-8 support, even if you have +to the configure command. This implies UTF support, even if you have not explicitly requested it.
@@ -121,7 +152,7 @@ supported. Details are given in the pcrepattern documentation.
-Just-in-time compiler support is included in the build by specifying
@@ -138,7 +169,7 @@ pcregrep automatically makes use of it, unless you addto the "configure" command. -
By default, PCRE interprets the linefeed (LF) character as indicating the end of a line. This is the normal newline character on Unix-like systems. You can @@ -171,7 +202,7 @@ Whatever line ending convention is selected when PCRE overridden when the library functions are called. At build time it is conventional to use the standard for your operating system.
-By default, the sequence \R in a pattern matches any Unicode newline sequence, whatever has been selected as the line ending sequence. If you specify @@ -182,9 +213,9 @@ the default is changed so that \R matches only CR, LF, selected when PCRE is built can be overridden when the library functions are called.
--When PCRE is called through the POSIX interface (see the +When the 8-bit library is called through the POSIX interface (see the pcreposix documentation), additional working storage is required for holding the pointers to capturing substrings, because PCRE requires three integers per substring, @@ -198,23 +229,24 @@ such as to the configure command.
-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 truyl enormous patterns, so it is possible to compile PCRE to use +process truly enormous patterns, so it is possible to compile PCRE to use three-byte or four-byte offsets by adding a setting such as
--with-link-size=3-to the configure 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. +to the configure command. The value given must be 2, 3, or 4. For the +16-bit library, a value of 3 is rounded up to 4. Using longer offsets slows +down the operation of PCRE because it has to load additional data when handling +them. -
When matching with the pcre_exec() function, PCRE implements backtracking by making recursive calls to an internal function called match(). In @@ -245,7 +277,7 @@ perform better than malloc() and free(). slowly when built in this way. This option affects only the pcre_exec() function; it is not relevant for pcre_dfa_exec().
-Internally, PCRE has a function called match(), which it calls repeatedly (sometimes recursively) when matching a pattern with the pcre_exec() @@ -274,7 +306,7 @@ constraints. However, you can set a lower limit by add to the configure command. This value can also be overridden at run time.
-PCRE uses fixed tables for processing characters whose code values are less than 256. By default, PCRE is built with a set of tables that are distributed @@ -291,7 +323,7 @@ compiling, because dftables is run on the local create alternative tables when cross compiling, you will have to do so "by hand".)
-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). This is the case for @@ -303,9 +335,9 @@ EBCDIC environment by adding to the configure 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). The ---enable-ebcdic option is incompatible with --enable-utf8. +--enable-ebcdic option is incompatible with --enable-utf.
-By default, pcregrep reads all files as plain text. You can build it so that it recognizes files whose names end in .gz or .bz2, and reads @@ -318,7 +350,7 @@ to the configure command. These options natural relevant libraries are installed on your system. Configuration will fail if they are not.
-pcregrep 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 @@ -333,7 +365,7 @@ parameter value by adding, for example, to the configure command. The caller of \fPpcregrep\fP can, however, override this value by specifying a run-time option.
-If you add
@@ -364,11 +396,11 @@ automatically included, you may need to add somethingimmediately before the configure command. -
-pcreapi(3), pcre_config(3). +pcreapi(3), pcre16, pcre_config(3).
-
Philip Hazel
@@ -377,11 +409,11 @@ University Computing Service
Cambridge CB2 3QH, England.
-Last updated: 06 September 2011
+Last updated: 07 January 2012
-Copyright © 1997-2011 University of Cambridge.
+Copyright © 1997-2012 University of Cambridge.
Return to the PCRE index page.