Remove references to 'pcrs-suppport' in the show-status template
[privoxy.git] / pcre / doc / pcreposix.txt
1 NAME
2      pcreposix - POSIX API for  Perl-compatible  regular  expres-
3      sions.
4
5
6
7 SYNOPSIS
8      #include <pcreposix.h>
9
10      int regcomp(regex_t *preg, const char *pattern,
11           int cflags);
12
13      int regexec(regex_t *preg, const char *string,
14           size_t nmatch, regmatch_t pmatch[], int eflags);
15
16      size_t regerror(int errcode, const regex_t *preg,
17           char *errbuf, size_t errbuf_size);
18
19      void regfree(regex_t *preg);
20
21
22
23 DESCRIPTION
24      This set of functions provides a POSIX-style API to the PCRE
25      regular expression package. See the pcre documentation for a
26      description of the native  API,  which  contains  additional
27      functionality.
28
29      The functions described here are just wrapper functions that
30      ultimately call the native API. Their prototypes are defined
31      in the pcreposix.h header file,  and  on  Unix  systems  the
32      library  itself is called pcreposix.a, so can be accessed by
33      adding -lpcreposix to the command for linking an application
34      which uses them. Because the POSIX functions call the native
35      ones, it is also necessary to add -lpcre.
36
37      I have implemented only those option bits that can  be  rea-
38      sonably  mapped  to  PCRE  native  options. In addition, the
39      options REG_EXTENDED and  REG_NOSUB  are  defined  with  the
40      value zero. They have no effect, but since programs that are
41      written to the POSIX interface often use them, this makes it
42      easier to slot in PCRE as a replacement library. Other POSIX
43      options are not even defined.
44
45      When PCRE is called via these functions, it is only the  API
46      that is POSIX-like in style. The syntax and semantics of the
47      regular expressions themselves are still those of Perl, sub-
48      ject  to  the  setting of various PCRE options, as described
49      below.
50
51      The header for these functions is supplied as pcreposix.h to
52      avoid  any  potential  clash  with other POSIX libraries. It
53      can, of course, be renamed or aliased as regex.h,  which  is
54      the "correct" name. It provides two structure types, regex_t
55      for compiled internal forms, and  regmatch_t  for  returning
56      captured  substrings.  It  also defines some constants whose
57      names start with "REG_"; these are used for setting  options
58      and identifying error codes.
59
60
61
62 COMPILING A PATTERN
63      The function regcomp() is called to compile a  pattern  into
64      an  internal form. The pattern is a C string terminated by a
65      binary zero, and is passed in the argument pattern. The preg
66      argument  is  a pointer to a regex_t structure which is used
67      as a base for storing information about the compiled expres-
68      sion.
69
70      The argument cflags is either zero, or contains one or  more
71      of the bits defined by the following macros:
72
73        REG_ICASE
74
75      The PCRE_CASELESS option  is  set  when  the  expression  is
76      passed for compilation to the native function.
77
78        REG_NEWLINE
79
80      The PCRE_MULTILINE option is  set  when  the  expression  is
81      passed for compilation to the native function.
82
83      In the absence of these flags, no options are passed to  the
84      native  function.  This means the the regex is compiled with
85      PCRE default semantics. In particular, the  way  it  handles
86      newline  characters  in  the subject string is the Perl way,
87      not the POSIX way. Note that setting PCRE_MULTILINE has only
88      some  of  the effects specified for REG_NEWLINE. It does not
89      affect the way newlines are matched by . (they aren't) or  a
90      negative class such as [^a] (they are).
91
92      The yield of regcomp() is zero on success, and non-zero oth-
93      erwise.  The preg structure is filled in on success, and one
94      member of the structure is publicized: re_nsub contains  the
95      number  of  capturing subpatterns in the regular expression.
96      Various error codes are defined in the header file.
97
98
99
100 MATCHING A PATTERN
101      The function regexec() is called  to  match  a  pre-compiled
102      pattern  preg against a given string, which is terminated by
103      a zero byte, subject to the options in eflags. These can be:
104
105        REG_NOTBOL
106
107      The PCRE_NOTBOL option is set when  calling  the  underlying
108      PCRE matching function.
109
110        REG_NOTEOL
111
112      The PCRE_NOTEOL option is set when  calling  the  underlying
113      PCRE matching function.
114
115      The portion of the string that was  matched,  and  also  any
116      captured  substrings,  are returned via the pmatch argument,
117      which points to  an  array  of  nmatch  structures  of  type
118      regmatch_t,  containing  the  members rm_so and rm_eo. These
119      contain the offset to the first character of each  substring
120      and  the offset to the first character after the end of each
121      substring, respectively.  The  0th  element  of  the  vector
122      relates  to  the  entire portion of string that was matched;
123      subsequent elements relate to the capturing  subpatterns  of
124      the  regular  expression.  Unused  entries in the array have
125      both structure members set to -1.
126
127      A successful match yields a zero return; various error codes
128      are  defined in the header file, of which REG_NOMATCH is the
129      "expected" failure code.
130
131
132
133 ERROR MESSAGES
134      The regerror()  function  maps  a  non-zero  errorcode  from
135      either regcomp or regexec to a printable message. If preg is
136      not NULL, the error should have arisen from the use of  that
137      structure.  A  message terminated by a binary zero is placed
138      in errbuf. The length of the message, including the zero, is
139      limited  to  errbuf_size.  The  yield of the function is the
140      size of buffer needed to hold the whole message.
141
142
143
144 STORAGE
145      Compiling a regular expression causes memory to be allocated
146      and  associated  with  the preg structure. The function reg-
147      free() frees all such memory, after which preg may no longer
148      be used as a compiled expression.
149
150
151
152 AUTHOR
153      Philip Hazel <ph10@cam.ac.uk>
154      University Computing Service,
155      New Museums Site,
156      Cambridge CB2 3QG, England.
157      Phone: +44 1223 334714
158
159      Copyright (c) 1997-2000 University of Cambridge.