pcre.txt

PHP v6.0 For Linux 运行环境：Win9X/ WinME/ WinNT/ Win2K/ WinXP

       The DFA algorithm suffers from a number of disadvantages:

       1. It is substantially slower than  the  standard  algorithm.  This  is
       partly  because  it has to search for all possible matches, but is also
       because it is less susceptible to optimization.

       2. Capturing parentheses and back references are not supported.

       3. The "atomic group" feature of PCRE regular expressions is supported,
       but  does not provide the advantage that it does for the standard algo-
       rithm.

Last updated: 28 February 2005
Copyright (c) 1997-2005 University of Cambridge.
------------------------------------------------------------------------------


PCREAPI(3)                                                          PCREAPI(3)


NAME
       PCRE - Perl-compatible regular expressions


PCRE NATIVE API

       #include <pcre.h>

       pcre *pcre_compile(const char *pattern, int options,
            const char **errptr, int *erroffset,
            const unsigned char *tableptr);

       pcre *pcre_compile2(const char *pattern, int options,
            int *errorcodeptr,
            const char **errptr, int *erroffset,
            const unsigned char *tableptr);

       pcre_extra *pcre_study(const pcre *code, int options,
            const char **errptr);

       int pcre_exec(const pcre *code, const pcre_extra *extra,
            const char *subject, int length, int startoffset,
            int options, int *ovector, int ovecsize);

       int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,
            const char *subject, int length, int startoffset,
            int options, int *ovector, int ovecsize,
            int *workspace, int wscount);

       int pcre_copy_named_substring(const pcre *code,
            const char *subject, int *ovector,
            int stringcount, const char *stringname,
            char *buffer, int buffersize);

       int pcre_copy_substring(const char *subject, int *ovector,
            int stringcount, int stringnumber, char *buffer,
            int buffersize);

       int pcre_get_named_substring(const pcre *code,
            const char *subject, int *ovector,
            int stringcount, const char *stringname,
            const char **stringptr);

       int pcre_get_stringnumber(const pcre *code,
            const char *name);

       int pcre_get_substring(const char *subject, int *ovector,
            int stringcount, int stringnumber,
            const char **stringptr);

       int pcre_get_substring_list(const char *subject,
            int *ovector, int stringcount, const char ***listptr);

       void pcre_free_substring(const char *stringptr);

       void pcre_free_substring_list(const char **stringptr);

       const unsigned char *pcre_maketables(void);

       int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
            int what, void *where);

       int pcre_info(const pcre *code, int *optptr, int *firstcharptr);

       int pcre_refcount(pcre *code, int adjust);

       int pcre_config(int what, void *where);

       char *pcre_version(void);

       void *(*pcre_malloc)(size_t);

       void (*pcre_free)(void *);

       void *(*pcre_stack_malloc)(size_t);

       void (*pcre_stack_free)(void *);

       int (*pcre_callout)(pcre_callout_block *);


PCRE API OVERVIEW

       PCRE has its own native API, which is described in this document. There
       is also a set of wrapper functions that correspond to the POSIX regular
       expression  API.  These  are  described in the pcreposix documentation.
       Both of these APIs define a set of C function calls. A C++  wrapper  is
       distributed with PCRE. It is documented in the pcrecpp page.

       The  native  API  C  function prototypes are defined in the header file
       pcre.h, and on Unix systems the library itself is called  libpcre.   It
       can normally be accessed by adding -lpcre to the command for linking an
       application  that  uses  PCRE.  The  header  file  defines  the  macros
       PCRE_MAJOR  and  PCRE_MINOR to contain the major and minor release num-
       bers for the library.  Applications can use these  to  include  support
       for different releases of PCRE.

       The   functions   pcre_compile(),  pcre_compile2(),  pcre_study(),  and
       pcre_exec() are used for compiling and matching regular expressions  in
       a  Perl-compatible  manner. A sample program that demonstrates the sim-
       plest way of using them is provided in the file  called  pcredemo.c  in
       the  source distribution. The pcresample documentation describes how to
       run it.

       A second matching function, pcre_dfa_exec(), which is not Perl-compati-
       ble,  is  also provided. This uses a different algorithm for the match-
       ing. This allows it to find all possible matches (at a given  point  in
       the  subject),  not  just  one. However, this algorithm does not return
       captured substrings. A description of the two matching  algorithms  and
       their  advantages  and disadvantages is given in the pcrematching docu-
       mentation.

       In addition to the main compiling and  matching  functions,  there  are
       convenience functions for extracting captured substrings from a subject
       string that is matched by pcre_exec(). They are:

         pcre_copy_substring()
         pcre_copy_named_substring()
         pcre_get_substring()
         pcre_get_named_substring()
         pcre_get_substring_list()
         pcre_get_stringnumber()

       pcre_free_substring() and pcre_free_substring_list() are also provided,
       to free the memory used for extracted strings.

       The  function  pcre_maketables()  is  used  to build a set of character
       tables  in  the  current  locale   for   passing   to   pcre_compile(),
       pcre_exec(),  or  pcre_dfa_exec(). This is an optional facility that is
       provided for specialist use.  Most  commonly,  no  special  tables  are
       passed,  in  which case internal tables that are generated when PCRE is
       built are used.

       The function pcre_fullinfo() is used to find out  information  about  a
       compiled  pattern; pcre_info() is an obsolete version that returns only
       some of the available information, but is retained for  backwards  com-
       patibility.   The function pcre_version() returns a pointer to a string
       containing the version of PCRE and its date of release.

       The function pcre_refcount() maintains a  reference  count  in  a  data
       block  containing  a compiled pattern. This is provided for the benefit
       of object-oriented applications.

       The global variables pcre_malloc and pcre_free  initially  contain  the
       entry  points  of  the  standard malloc() and free() functions, respec-
       tively. PCRE calls the memory management functions via these variables,
       so  a  calling  program  can replace them if it wishes to intercept the
       calls. This should be done before calling any PCRE functions.

       The global variables pcre_stack_malloc  and  pcre_stack_free  are  also
       indirections  to  memory  management functions. These special functions
       are used only when PCRE is compiled to use  the  heap  for  remembering
       data, instead of recursive function calls, when running the pcre_exec()
       function. This is a non-standard way of building PCRE, for use in envi-
       ronments that have limited stacks. Because of the greater use of memory
       management, it runs more slowly.  Separate functions  are  provided  so
       that  special-purpose  external  code  can  be used for this case. When
       used, these functions are always called in a  stack-like  manner  (last
       obtained,  first freed), and always for memory blocks of the same size.

       The global variable pcre_callout initially contains NULL. It can be set
       by  the  caller  to  a "callout" function, which PCRE will then call at
       specified points during a matching operation. Details are given in  the
       pcrecallout documentation.


MULTITHREADING

       The  PCRE  functions  can be used in multi-threading applications, with
       the  proviso  that  the  memory  management  functions  pointed  to  by
       pcre_malloc, pcre_free, pcre_stack_malloc, and pcre_stack_free, and the
       callout function pointed to by pcre_callout, are shared by all threads.

       The  compiled form of a regular expression is not altered during match-
       ing, so the same compiled pattern can safely be used by several threads
       at once.


SAVING PRECOMPILED PATTERNS FOR LATER USE

       The compiled form of a regular expression can be saved and re-used at a
       later time, possibly by a different program, and even on a  host  other
       than  the  one  on  which  it  was  compiled.  Details are given in the
       pcreprecompile documentation.


CHECKING BUILD-TIME OPTIONS

       int pcre_config(int what, void *where);

       The function pcre_config() makes it possible for a PCRE client to  dis-
       cover which optional features have been compiled into the PCRE library.
       The pcrebuild documentation has more details about these optional  fea-
       tures.

       The  first  argument  for pcre_config() is an integer, specifying which
       information is required; the second argument is a pointer to a variable
       into  which  the  information  is  placed. The following information is
       available:

         PCRE_CONFIG_UTF8

       The output is an integer that is set to one if UTF-8 support is  avail-
       able; otherwise it is set to zero.

         PCRE_CONFIG_UNICODE_PROPERTIES

       The  output  is  an  integer  that is set to one if support for Unicode
       character properties is available; otherwise it is set to zero.

         PCRE_CONFIG_NEWLINE

       The output is an integer that is set to the value of the code  that  is
       used  for the newline character. It is either linefeed (10) or carriage
       return (13), and should normally be the  standard  character  for  your
       operating system.

         PCRE_CONFIG_LINK_SIZE

       The  output  is  an  integer that contains the number of bytes used for
       internal linkage in compiled regular expressions. The value is 2, 3, or
       4.  Larger  values  allow larger regular expressions to be compiled, at
       the expense of slower matching. The default value of  2  is  sufficient
       for  all  but  the  most massive patterns, since it allows the compiled
       pattern to be up to 64K in size.

         PCRE_CONFIG_POSIX_MALLOC_THRESHOLD

       The output is an integer that contains the threshold  above  which  the
       POSIX  interface  uses malloc() for output vectors. Further details are
       given in the pcreposix documentation.

         PCRE_CONFIG_MATCH_LIMIT

       The output is an integer that gives the default limit for the number of
       internal  matching  function  calls in a pcre_exec() execution. Further
       details are given with pcre_exec() below.

         PCRE_CONFIG_MATCH_LIMIT_RECURSION

       The output is an integer that gives the default limit for the depth  of
       recursion  when calling the internal matching function in a pcre_exec()
       execution. Further details are given with pcre_exec() below.

         PCRE_CONFIG_STACKRECURSE

       The output is an integer that is set to one if internal recursion  when
       running pcre_exec() is implemented by recursive function calls that use
       the stack to remember their state. This is the usual way that  PCRE  is
       compiled. The output is zero if PCRE was compiled to use blocks of data
       on the  heap  instead  of  recursive  function  calls.  In  this  case,
       pcre_stack_malloc  and  pcre_stack_free  are  called  to  manage memory
       blocks on the heap, thus avoiding the use of the stack.