src/external/pcre2-10.32/doc/pcre2posix.3

   1 .TH PCRE2POSIX 3 "15 June 2017" "PCRE2 10.30"
   2 .SH NAME
   3 PCRE2 - Perl-compatible regular expressions (revised API)
   4 .SH "SYNOPSIS"
   5 .rs
   6 .sp
   7 .B #include <pcre2posix.h>
   8 .PP
   9 .nf
  10 .B int regcomp(regex_t *\fIpreg\fP, const char *\fIpattern\fP,
  11 .B "     int \fIcflags\fP);"
  12 .sp
  13 .B int regexec(const regex_t *\fIpreg\fP, const char *\fIstring\fP,
  14 .B "     size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[], int \fIeflags\fP);"
  15 .sp
  16 .B "size_t regerror(int \fIerrcode\fP, const regex_t *\fIpreg\fP,"
  17 .B "     char *\fIerrbuf\fP, size_t \fIerrbuf_size\fP);"
  18 .sp
  19 .B void regfree(regex_t *\fIpreg\fP);
  20 .fi
  21 .
  22 .SH DESCRIPTION
  23 .rs
  24 .sp
  25 This set of functions provides a POSIX-style API for the PCRE2 regular
  26 expression 8-bit library. See the
  27 .\" HREF
  28 \fBpcre2api\fP
  29 .\"
  30 documentation for a description of PCRE2's native API, which contains much
  31 additional functionality. There are no POSIX-style wrappers for PCRE2's 16-bit
  32 and 32-bit libraries.
  33 .P
  34 The functions described here are just wrapper functions that ultimately call
  35 the PCRE2 native API. Their prototypes are defined in the \fBpcre2posix.h\fP
  36 header file, and on Unix systems the library itself is called
  37 \fBlibpcre2-posix.a\fP, so can be accessed by adding \fB-lpcre2-posix\fP to the
  38 command for linking an application that uses them. Because the POSIX functions
  39 call the native ones, it is also necessary to add \fB-lpcre2-8\fP.
  40 .P
  41 Those POSIX option bits that can reasonably be mapped to PCRE2 native options
  42 have been implemented. In addition, the option REG_EXTENDED is defined with the
  43 value zero. This has no effect, but since programs that are written to the
  44 POSIX interface often use it, this makes it easier to slot in PCRE2 as a
  45 replacement library. Other POSIX options are not even defined.
  46 .P
  47 There are also some options that are not defined by POSIX. These have been
  48 added at the request of users who want to make use of certain PCRE2-specific
  49 features via the POSIX calling interface or to add BSD or GNU functionality.
  50 .P
  51 When PCRE2 is called via these functions, it is only the API that is POSIX-like
  52 in style. The syntax and semantics of the regular expressions themselves are
  53 still those of Perl, subject to the setting of various PCRE2 options, as
  54 described below. "POSIX-like in style" means that the API approximates to the
  55 POSIX definition; it is not fully POSIX-compatible, and in multi-unit encoding
  56 domains it is probably even less compatible.
  57 .P
  58 The header for these functions is supplied as \fBpcre2posix.h\fP to avoid any
  59 potential clash with other POSIX libraries. It can, of course, be renamed or
  60 aliased as \fBregex.h\fP, which is the "correct" name. It provides two
  61 structure types, \fIregex_t\fP for compiled internal forms, and
  62 \fIregmatch_t\fP for returning captured substrings. It also defines some
  63 constants whose names start with "REG_"; these are used for setting options and
  64 identifying error codes.
  65 .
  66 .
  67 .SH "COMPILING A PATTERN"
  68 .rs
  69 .sp
  70 The function \fBregcomp()\fP is called to compile a pattern into an
  71 internal form. By default, the pattern is a C string terminated by a binary
  72 zero (but see REG_PEND below). The \fIpreg\fP argument is a pointer to a
  73 \fBregex_t\fP structure that is used as a base for storing information about
  74 the compiled regular expression. (It is also used for input when REG_PEND is
  75 set.)
  76 .P
  77 The argument \fIcflags\fP is either zero, or contains one or more of the bits
  78 defined by the following macros:
  79 .sp
  80   REG_DOTALL
  81 .sp
  82 The PCRE2_DOTALL option is set when the regular expression is passed for
  83 compilation to the native function. Note that REG_DOTALL is not part of the
  84 POSIX standard.
  85 .sp
  86   REG_ICASE
  87 .sp
  88 The PCRE2_CASELESS option is set when the regular expression is passed for
  89 compilation to the native function.
  90 .sp
  91   REG_NEWLINE
  92 .sp
  93 The PCRE2_MULTILINE option is set when the regular expression is passed for
  94 compilation to the native function. Note that this does \fInot\fP mimic the
  95 defined POSIX behaviour for REG_NEWLINE (see the following section).
  96 .sp
  97   REG_NOSPEC
  98 .sp
  99 The PCRE2_LITERAL option is set when the regular expression is passed for
 100 compilation to the native function. This disables all meta characters in the
 101 pattern, causing it to be treated as a literal string. The only other options
 102 that are allowed with REG_NOSPEC are REG_ICASE, REG_NOSUB, REG_PEND, and
 103 REG_UTF. Note that REG_NOSPEC is not part of the POSIX standard.
 104 .sp
 105   REG_NOSUB
 106 .sp
 107 When a pattern that is compiled with this flag is passed to \fBregexec()\fP for
 108 matching, the \fInmatch\fP and \fIpmatch\fP arguments are ignored, and no
 109 captured strings are returned. Versions of the PCRE library prior to 10.22 used
 110 to set the PCRE2_NO_AUTO_CAPTURE compile option, but this no longer happens
 111 because it disables the use of backreferences.
 112 .sp
 113   REG_PEND
 114 .sp
 115 If this option is set, the \fBreg_endp\fP field in the \fIpreg\fP structure
 116 (which has the type const char *) must be set to point to the character beyond
 117 the end of the pattern before calling \fBregcomp()\fP. The pattern itself may
 118 now contain binary zeros, which are treated as data characters. Without
 119 REG_PEND, a binary zero terminates the pattern and the \fBre_endp\fP field is
 120 ignored. This is a GNU extension to the POSIX standard and should be used with
 121 caution in software intended to be portable to other systems.
 122 .sp
 123   REG_UCP
 124 .sp
 125 The PCRE2_UCP option is set when the regular expression is passed for
 126 compilation to the native function. This causes PCRE2 to use Unicode properties
 127 when matchine \ed, \ew, etc., instead of just recognizing ASCII values. Note
 128 that REG_UCP is not part of the POSIX standard.
 129 .sp
 130   REG_UNGREEDY
 131 .sp
 132 The PCRE2_UNGREEDY option is set when the regular expression is passed for
 133 compilation to the native function. Note that REG_UNGREEDY is not part of the
 134 POSIX standard.
 135 .sp
 136   REG_UTF
 137 .sp
 138 The PCRE2_UTF option is set when the regular expression is passed for
 139 compilation to the native function. This causes the pattern itself and all data
 140 strings used for matching it to be treated as UTF-8 strings. Note that REG_UTF
 141 is not part of the POSIX standard.
 142 .P
 143 In the absence of these flags, no options are passed to the native function.
 144 This means the the regex is compiled with PCRE2 default semantics. In
 145 particular, the way it handles newline characters in the subject string is the
 146 Perl way, not the POSIX way. Note that setting PCRE2_MULTILINE has only
 147 \fIsome\fP of the effects specified for REG_NEWLINE. It does not affect the way
 148 newlines are matched by the dot metacharacter (they are not) or by a negative
 149 class such as [^a] (they are).
 150 .P
 151 The yield of \fBregcomp()\fP is zero on success, and non-zero otherwise. The
 152 \fIpreg\fP structure is filled in on success, and one other member of the
 153 structure (as well as \fIre_endp\fP) is public: \fIre_nsub\fP contains the
 154 number of capturing subpatterns in the regular expression. Various error codes
 155 are defined in the header file.
 156 .P
 157 NOTE: If the yield of \fBregcomp()\fP is non-zero, you must not attempt to
 158 use the contents of the \fIpreg\fP structure. If, for example, you pass it to
 159 \fBregexec()\fP, the result is undefined and your program is likely to crash.
 160 .
 161 .
 162 .SH "MATCHING NEWLINE CHARACTERS"
 163 .rs
 164 .sp
 165 This area is not simple, because POSIX and Perl take different views of things.
 166 It is not possible to get PCRE2 to obey POSIX semantics, but then PCRE2 was
 167 never intended to be a POSIX engine. The following table lists the different
 168 possibilities for matching newline characters in Perl and PCRE2:
 169 .sp
 170                           Default   Change with
 171 .sp
 172   . matches newline          no     PCRE2_DOTALL
 173   newline matches [^a]       yes    not changeable
 174   $ matches \en at end        yes    PCRE2_DOLLAR_ENDONLY
 175   $ matches \en in middle     no     PCRE2_MULTILINE
 176   ^ matches \en in middle     no     PCRE2_MULTILINE
 177 .sp
 178 This is the equivalent table for a POSIX-compatible pattern matcher:
 179 .sp
 180                           Default   Change with
 181 .sp
 182   . matches newline          yes    REG_NEWLINE
 183   newline matches [^a]       yes    REG_NEWLINE
 184   $ matches \en at end        no     REG_NEWLINE
 185   $ matches \en in middle     no     REG_NEWLINE
 186   ^ matches \en in middle     no     REG_NEWLINE
 187 .sp
 188 This behaviour is not what happens when PCRE2 is called via its POSIX
 189 API. By default, PCRE2's behaviour is the same as Perl's, except that there is
 190 no equivalent for PCRE2_DOLLAR_ENDONLY in Perl. In both PCRE2 and Perl, there
 191 is no way to stop newline from matching [^a].
 192 .P
 193 Default POSIX newline handling can be obtained by setting PCRE2_DOTALL and
 194 PCRE2_DOLLAR_ENDONLY when calling \fBpcre2_compile()\fP directly, but there is
 195 no way to make PCRE2 behave exactly as for the REG_NEWLINE action. When using
 196 the POSIX API, passing REG_NEWLINE to PCRE2's \fBregcomp()\fP function
 197 causes PCRE2_MULTILINE to be passed to \fBpcre2_compile()\fP, and REG_DOTALL
 198 passes PCRE2_DOTALL. There is no way to pass PCRE2_DOLLAR_ENDONLY.
 199 .
 200 .
 201 .SH "MATCHING A PATTERN"
 202 .rs
 203 .sp
 204 The function \fBregexec()\fP is called to match a compiled pattern \fIpreg\fP
 205 against a given \fIstring\fP, which is by default terminated by a zero byte
 206 (but see REG_STARTEND below), subject to the options in \fIeflags\fP. These can
 207 be:
 208 .sp
 209   REG_NOTBOL
 210 .sp
 211 The PCRE2_NOTBOL option is set when calling the underlying PCRE2 matching
 212 function.
 213 .sp
 214   REG_NOTEMPTY
 215 .sp
 216 The PCRE2_NOTEMPTY option is set when calling the underlying PCRE2 matching
 217 function. Note that REG_NOTEMPTY is not part of the POSIX standard. However,
 218 setting this option can give more POSIX-like behaviour in some situations.
 219 .sp
 220   REG_NOTEOL
 221 .sp
 222 The PCRE2_NOTEOL option is set when calling the underlying PCRE2 matching
 223 function.
 224 .sp
 225   REG_STARTEND
 226 .sp
 227 When this option is set, the subject string starts at \fIstring\fP +
 228 \fIpmatch[0].rm_so\fP and ends at \fIstring\fP + \fIpmatch[0].rm_eo\fP, which
 229 should point to the first character beyond the string. There may be binary
 230 zeros within the subject string, and indeed, using REG_STARTEND is the only
 231 way to pass a subject string that contains a binary zero.
 232 .P
 233 Whatever the value of \fIpmatch[0].rm_so\fP, the offsets of the matched string
 234 and any captured substrings are still given relative to the start of
 235 \fIstring\fP itself. (Before PCRE2 release 10.30 these were given relative to
 236 \fIstring\fP + \fIpmatch[0].rm_so\fP, but this differs from other
 237 implementations.)
 238 .P
 239 This is a BSD extension, compatible with but not specified by IEEE Standard
 240 1003.2 (POSIX.2), and should be used with caution in software intended to be
 241 portable to other systems. Note that a non-zero \fIrm_so\fP does not imply
 242 REG_NOTBOL; REG_STARTEND affects only the location and length of the string,
 243 not how it is matched. Setting REG_STARTEND and passing \fIpmatch\fP as NULL
 244 are mutually exclusive; the error REG_INVARG is returned.
 245 .P
 246 If the pattern was compiled with the REG_NOSUB flag, no data about any matched
 247 strings is returned. The \fInmatch\fP and \fIpmatch\fP arguments of
 248 \fBregexec()\fP are ignored (except possibly as input for REG_STARTEND).
 249 .P
 250 The value of \fInmatch\fP may be zero, and the value \fIpmatch\fP may be NULL
 251 (unless REG_STARTEND is set); in both these cases no data about any matched
 252 strings is returned.
 253 .P
 254 Otherwise, the portion of the string that was matched, and also any captured
 255 substrings, are returned via the \fIpmatch\fP argument, which points to an
 256 array of \fInmatch\fP structures of type \fIregmatch_t\fP, containing the
 257 members \fIrm_so\fP and \fIrm_eo\fP. These contain the byte offset to the first
 258 character of each substring and the offset to the first character after the end
 259 of each substring, respectively. The 0th element of the vector relates to the
 260 entire portion of \fIstring\fP that was matched; subsequent elements relate to
 261 the capturing subpatterns of the regular expression. Unused entries in the
 262 array have both structure members set to -1.
 263 .P
 264 A successful match yields a zero return; various error codes are defined in the
 265 header file, of which REG_NOMATCH is the "expected" failure code.
 266 .
 267 .
 268 .SH "ERROR MESSAGES"
 269 .rs
 270 .sp
 271 The \fBregerror()\fP function maps a non-zero errorcode from either
 272 \fBregcomp()\fP or \fBregexec()\fP to a printable message. If \fIpreg\fP is not
 273 NULL, the error should have arisen from the use of that structure. A message
 274 terminated by a binary zero is placed in \fIerrbuf\fP. If the buffer is too
 275 short, only the first \fIerrbuf_size\fP - 1 characters of the error message are
 276 used. The yield of the function is the size of buffer needed to hold the whole
 277 message, including the terminating zero. This value is greater than
 278 \fIerrbuf_size\fP if the message was truncated.
 279 .
 280 .
 281 .SH MEMORY USAGE
 282 .rs
 283 .sp
 284 Compiling a regular expression causes memory to be allocated and associated
 285 with the \fIpreg\fP structure. The function \fBregfree()\fP frees all such
 286 memory, after which \fIpreg\fP may no longer be used as a compiled expression.
 287 .
 288 .
 289 .SH AUTHOR
 290 .rs
 291 .sp
 292 .nf
 293 Philip Hazel
 294 University Computing Service
 295 Cambridge, England.
 296 .fi
 297 .
 298 .
 299 .SH REVISION
 300 .rs
 301 .sp
 302 .nf
 303 Last updated: 15 June 2017
 304 Copyright (c) 1997-2017 University of Cambridge.
 305 .fi