+++ /dev/null
-.TH PCRE 3\r
-.SH NAME\r
-pcreposix - POSIX API for Perl-compatible regular expressions.\r
-.SH SYNOPSIS\r
-.B #include <pcreposix.h>\r
-.PP\r
-.SM\r
-.br\r
-.B int regcomp(regex_t *\fIpreg\fR, const char *\fIpattern\fR,\r
-.ti +5n\r
-.B int \fIcflags\fR);\r
-.PP\r
-.br\r
-.B int regexec(regex_t *\fIpreg\fR, const char *\fIstring\fR,\r
-.ti +5n\r
-.B size_t \fInmatch\fR, regmatch_t \fIpmatch\fR[], int \fIeflags\fR);\r
-.PP\r
-.br\r
-.B size_t regerror(int \fIerrcode\fR, const regex_t *\fIpreg\fR,\r
-.ti +5n\r
-.B char *\fIerrbuf\fR, size_t \fIerrbuf_size\fR);\r
-.PP\r
-.br\r
-.B void regfree(regex_t *\fIpreg\fR);\r
-\r
-\r
-.SH DESCRIPTION\r
-This set of functions provides a POSIX-style API to the PCRE regular expression\r
-package. See the \fBpcre\fR documentation for a description of the native API,\r
-which contains additional functionality.\r
-\r
-The functions described here are just wrapper functions that ultimately call\r
-the native API. Their prototypes are defined in the \fBpcreposix.h\fR header\r
-file, and on Unix systems the library itself is called \fBpcreposix.a\fR, so\r
-can be accessed by adding \fB-lpcreposix\fR to the command for linking an\r
-application which uses them. Because the POSIX functions call the native ones,\r
-it is also necessary to add \fR-lpcre\fR.\r
-\r
-I have implemented only those option bits that can be reasonably mapped to PCRE\r
-native options. In addition, the options REG_EXTENDED and REG_NOSUB are defined\r
-with the value zero. They have no effect, but since programs that are written\r
-to the POSIX interface often use them, this makes it easier to slot in PCRE as\r
-a replacement library. Other POSIX options are not even defined.\r
-\r
-When PCRE is called via these functions, it is only the API that is POSIX-like\r
-in style. The syntax and semantics of the regular expressions themselves are\r
-still those of Perl, subject to the setting of various PCRE options, as\r
-described below.\r
-\r
-The header for these functions is supplied as \fBpcreposix.h\fR to avoid any\r
-potential clash with other POSIX libraries. It can, of course, be renamed or\r
-aliased as \fBregex.h\fR, which is the "correct" name. It provides two\r
-structure types, \fIregex_t\fR for compiled internal forms, and\r
-\fIregmatch_t\fR for returning captured substrings. It also defines some\r
-constants whose names start with "REG_"; these are used for setting options and\r
-identifying error codes.\r
-\r
-\r
-.SH COMPILING A PATTERN\r
-\r
-The function \fBregcomp()\fR is called to compile a pattern into an\r
-internal form. The pattern is a C string terminated by a binary zero, and\r
-is passed in the argument \fIpattern\fR. The \fIpreg\fR argument is a pointer\r
-to a regex_t structure which is used as a base for storing information about\r
-the compiled expression.\r
-\r
-The argument \fIcflags\fR is either zero, or contains one or more of the bits\r
-defined by the following macros:\r
-\r
- REG_ICASE\r
-\r
-The PCRE_CASELESS option is set when the expression is passed for compilation\r
-to the native function.\r
-\r
- REG_NEWLINE\r
-\r
-The PCRE_MULTILINE option is set when the expression is passed for compilation\r
-to the native function.\r
-\r
-In the absence of these flags, no options are passed to the native function.\r
-This means the the regex is compiled with PCRE default semantics. In\r
-particular, the way it handles newline characters in the subject string is the\r
-Perl way, not the POSIX way. Note that setting PCRE_MULTILINE has only\r
-\fIsome\fR of the effects specified for REG_NEWLINE. It does not affect the way\r
-newlines are matched by . (they aren't) or a negative class such as [^a] (they\r
-are).\r
-\r
-The yield of \fBregcomp()\fR is zero on success, and non-zero otherwise. The\r
-\fIpreg\fR structure is filled in on success, and one member of the structure\r
-is publicized: \fIre_nsub\fR contains the number of capturing subpatterns in\r
-the regular expression. Various error codes are defined in the header file.\r
-\r
-\r
-.SH MATCHING A PATTERN\r
-The function \fBregexec()\fR is called to match a pre-compiled pattern\r
-\fIpreg\fR against a given \fIstring\fR, which is terminated by a zero byte,\r
-subject to the options in \fIeflags\fR. These can be:\r
-\r
- REG_NOTBOL\r
-\r
-The PCRE_NOTBOL option is set when calling the underlying PCRE matching\r
-function.\r
-\r
- REG_NOTEOL\r
-\r
-The PCRE_NOTEOL option is set when calling the underlying PCRE matching\r
-function.\r
-\r
-The portion of the string that was matched, and also any captured substrings,\r
-are returned via the \fIpmatch\fR argument, which points to an array of\r
-\fInmatch\fR structures of type \fIregmatch_t\fR, containing the members\r
-\fIrm_so\fR and \fIrm_eo\fR. These contain the offset to the first character of\r
-each substring and the offset to the first character after the end of each\r
-substring, respectively. The 0th element of the vector relates to the entire\r
-portion of \fIstring\fR that was matched; subsequent elements relate to the\r
-capturing subpatterns of the regular expression. Unused entries in the array\r
-have both structure members set to -1.\r
-\r
-A successful match yields a zero return; various error codes are defined in the\r
-header file, of which REG_NOMATCH is the "expected" failure code.\r
-\r
-\r
-.SH ERROR MESSAGES\r
-The \fBregerror()\fR function maps a non-zero errorcode from either\r
-\fBregcomp\fR or \fBregexec\fR to a printable message. If \fIpreg\fR is not\r
-NULL, the error should have arisen from the use of that structure. A message\r
-terminated by a binary zero is placed in \fIerrbuf\fR. The length of the\r
-message, including the zero, is limited to \fIerrbuf_size\fR. The yield of the\r
-function is the size of buffer needed to hold the whole message.\r
-\r
-\r
-.SH STORAGE\r
-Compiling a regular expression causes memory to be allocated and associated\r
-with the \fIpreg\fR structure. The function \fBregfree()\fR frees all such\r
-memory, after which \fIpreg\fR may no longer be used as a compiled expression.\r
-\r
-\r
-.SH AUTHOR\r
-Philip Hazel <ph10@cam.ac.uk>\r
-.br\r
-University Computing Service,\r
-.br\r
-New Museums Site,\r
-.br\r
-Cambridge CB2 3QG, England.\r
-.br\r
-Phone: +44 1223 334714\r
-\r
-Copyright (c) 1997-2000 University of Cambridge.\r
projects / privoxy.git / blobdiff