embedaddon/pcre/doc/html/pcre.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc / html / pcre.html
Revision 1.1.1.4 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Sun Jun 15 19:46:05 2014 UTC (10 years, 9 months ago) by misho
Branches: pcre, MAIN
CVS tags: v8_34, HEAD

pcre 8.34

1: <html> 2: <head> 3: <title>pcre specification</title> 4: </head> 5: <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6: <h1>pcre man page</h1> 7:  8: Return to the <a href="index.html">PCRE index page</a>. 9:  10:  11: This page is part of the PCRE HTML documentation. It was generated automatically 12: from the original man page. If there is any nonsense in it, please consult the 13: man page, in case the conversion went wrong. 14:   15: <ul> 16: <li><a name="TOC1" href="#SEC1">INTRODUCTION</a> 17: <li><a name="TOC2" href="#SEC2">SECURITY CONSIDERATIONS</a> 18: <li><a name="TOC3" href="#SEC3">USER DOCUMENTATION</a> 19: <li><a name="TOC4" href="#SEC4">AUTHOR</a> 20: <li><a name="TOC5" href="#SEC5">REVISION</a> 21: </ul> 22:  <a name="SEC1" href="#TOC1">INTRODUCTION</a>  23:  24: The PCRE library is a set of functions that implement regular expression 25: pattern matching using the same syntax and semantics as Perl, with just a few 26: differences. Some features that appeared in Python and PCRE before they 27: appeared in Perl are also available using the Python syntax, there is some 28: support for one or two .NET and Oniguruma syntax items, and there is an option 29: for requesting some minor changes that give better JavaScript compatibility. 30:  31:  32: Starting with release 8.30, it is possible to compile two separate PCRE 33: libraries: the original, which supports 8-bit character strings (including 34: UTF-8 strings), and a second library that supports 16-bit character strings 35: (including UTF-16 strings). The build process allows either one or both to be 36: built. The majority of the work to make this possible was done by Zoltan 37: Herczeg. 38:  39:  40: Starting with release 8.32 it is possible to compile a third separate PCRE 41: library that supports 32-bit character strings (including UTF-32 strings). The 42: build process allows any combination of the 8-, 16- and 32-bit libraries. The 43: work to make this possible was done by Christian Persch. 44:  45:  46: The three libraries contain identical sets of functions, except that the names 47: in the 16-bit library start with pcre16_ instead of pcre_, and the 48: names in the 32-bit library start with pcre32_ instead of pcre_. To 49: avoid over-complication and reduce the documentation maintenance load, most of 50: the documentation describes the 8-bit library, with the differences for the 51: 16-bit and 32-bit libraries described separately in the 52: <a href="pcre16.html">pcre16</a> 53: and 54: <a href="pcre32.html">pcre32</a> 55: pages. References to functions or structures of the form pcre[16|32]_xxx 56: should be read as meaning "pcre_xxx when using the 8-bit library, 57: pcre16_xxx when using the 16-bit library, or pcre32_xxx when using 58: the 32-bit library". 59:  60:  61: The current implementation of PCRE corresponds approximately with Perl 5.12, 62: including support for UTF-8/16/32 encoded strings and Unicode general category 63: properties. However, UTF-8/16/32 and Unicode support has to be explicitly 64: enabled; it is not the default. The Unicode tables correspond to Unicode 65: release 6.3.0. 66:  67:  68: In addition to the Perl-compatible matching function, PCRE contains an 69: alternative function that matches the same compiled patterns in a different 70: way. In certain circumstances, the alternative function has some advantages. 71: For a discussion of the two matching algorithms, see the 72: <a href="pcrematching.html">pcrematching</a> 73: page. 74:  75:  76: PCRE is written in C and released as a C library. A number of people have 77: written wrappers and interfaces of various kinds. In particular, Google Inc. 78: have provided a comprehensive C++ wrapper for the 8-bit library. This is now 79: included as part of the PCRE distribution. The 80: <a href="pcrecpp.html">pcrecpp</a> 81: page has details of this interface. Other people's contributions can be found 82: in the Contrib directory at the primary FTP site, which is: 83: <a href="ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre">ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre</a> 84:  85:  86: Details of exactly which Perl regular expression features are and are not 87: supported by PCRE are given in separate documents. See the 88: <a href="pcrepattern.html">pcrepattern</a> 89: and 90: <a href="pcrecompat.html">pcrecompat</a> 91: pages. There is a syntax summary in the 92: <a href="pcresyntax.html">pcresyntax</a> 93: page. 94:  95:  96: Some features of PCRE can be included, excluded, or changed when the library is 97: built. The 98: <a href="pcre_config.html">pcre_config()</a> 99: function makes it possible for a client to discover which features are 100: available. The features themselves are described in the 101: <a href="pcrebuild.html">pcrebuild</a> 102: page. Documentation about building PCRE for various operating systems can be 103: found in the 104: <a href="README.txt">README</a> 105: and 106: <a href="NON-AUTOTOOLS-BUILD.txt">NON-AUTOTOOLS_BUILD</a> 107: files in the source distribution. 108:  109:  110: The libraries contains a number of undocumented internal functions and data 111: tables that are used by more than one of the exported external functions, but 112: which are not intended for use by external callers. Their names all begin with 113: "_pcre_" or "_pcre16_" or "_pcre32_", which hopefully will not provoke any name 114: clashes. In some environments, it is possible to control which external symbols 115: are exported when a shared library is built, and in these cases the 116: undocumented symbols are not exported. 117:  118:  <a name="SEC2" href="#TOC1">SECURITY CONSIDERATIONS</a>  119:  120: If you are using PCRE in a non-UTF application that permits users to supply 121: arbitrary patterns for compilation, you should be aware of a feature that 122: allows users to turn on UTF support from within a pattern, provided that PCRE 123: was built with UTF support. For example, an 8-bit pattern that begins with 124: "(*UTF8)" or "(*UTF)" turns on UTF-8 mode, which interprets patterns and 125: subjects as strings of UTF-8 characters instead of individual 8-bit characters. 126: This causes both the pattern and any data against which it is matched to be 127: checked for UTF-8 validity. If the data string is very long, such a check might 128: use sufficiently many resources as to cause your application to lose 129: performance. 130:  131:  132: One way of guarding against this possibility is to use the 133: pcre_fullinfo() function to check the compiled pattern's options for UTF. 134: Alternatively, from release 8.33, you can set the PCRE_NEVER_UTF option at 135: compile time. This causes an compile time error if a pattern contains a 136: UTF-setting sequence. 137:  138:  139: If your application is one that supports UTF, be aware that validity checking 140: can take time. If the same data string is to be matched many times, you can use 141: the PCRE_NO_UTF[8|16|32]_CHECK option for the second and subsequent matches to 142: save redundant checks. 143:  144:  145: Another way that performance can be hit is by running a pattern that has a very 146: large search tree against a string that will never match. Nested unlimited 147: repeats in a pattern are a common example. PCRE provides some protection 148: against this: see the PCRE_EXTRA_MATCH_LIMIT feature in the 149: <a href="pcreapi.html">pcreapi</a> 150: page. 151:  152:  <a name="SEC3" href="#TOC1">USER DOCUMENTATION</a>  153:  154: The user documentation for PCRE comprises a number of different sections. In 155: the "man" format, each of these is a separate "man page". In the HTML format, 156: each is a separate page, linked from the index page. In the plain text format, 157: all the sections, except the pcredemo section, are concatenated, for ease 158: of searching. The sections are as follows: 159: <pre> 160: pcre this document 161: pcre-config show PCRE installation configuration information 162: pcre16 details of the 16-bit library 163: pcre32 details of the 32-bit library 164: pcreapi details of PCRE's native C API 165: pcrebuild building PCRE 166: pcrecallout details of the callout feature 167: pcrecompat discussion of Perl compatibility 168: pcrecpp details of the C++ wrapper for the 8-bit library 169: pcredemo a demonstration C program that uses PCRE 170: pcregrep description of the pcregrep command (8-bit only) 171: pcrejit discussion of the just-in-time optimization support 172: pcrelimits details of size and other limits 173: pcrematching discussion of the two matching algorithms 174: pcrepartial details of the partial matching facility 175: pcrepattern syntax and semantics of supported regular expressions 176: pcreperform discussion of performance issues 177: pcreposix the POSIX-compatible C API for the 8-bit library 178: pcreprecompile details of saving and re-using precompiled patterns 179: pcresample discussion of the pcredemo program 180: pcrestack discussion of stack usage 181: pcresyntax quick syntax reference 182: pcretest description of the pcretest testing command 183: pcreunicode discussion of Unicode and UTF-8/16/32 support 184: </pre> 185: In addition, in the "man" and HTML formats, there is a short page for each 186: C library function, listing its arguments and results. 187:  188:  <a name="SEC4" href="#TOC1">AUTHOR</a>  189:  190: Philip Hazel 191:   192: University Computing Service 193:   194: Cambridge CB2 3QH, England. 195:   196:  197:  198: Putting an actual email address here seems to have been a spam magnet, so I've 199: taken it away. If you want to email me, use my two initials, followed by the 200: two digits 10, at the domain cam.ac.uk. 201:  202:  <a name="SEC5" href="#TOC1">REVISION</a>  203:  204: Last updated: 13 May 2013 205:   206: Copyright © 1997-2013 University of Cambridge. 207:   208:  209: Return to the <a href="index.html">PCRE index page</a>. 210: 