192 lines
7.2 KiB
HTML
192 lines
7.2 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>pcreposix specification</TITLE>
|
|
</HEAD>
|
|
<body bgcolor="#FFFFFF" text="#00005A">
|
|
<H1>pcreposix specification</H1>
|
|
This HTML document has been generated automatically from the original man page.
|
|
If there is any nonsense in it, please consult the man page in case the
|
|
conversion went wrong.
|
|
<UL>
|
|
<LI><A NAME="TOC1" HREF="#SEC1">NAME</A>
|
|
<LI><A NAME="TOC2" HREF="#SEC2">SYNOPSIS</A>
|
|
<LI><A NAME="TOC3" HREF="#SEC3">DESCRIPTION</A>
|
|
<LI><A NAME="TOC4" HREF="#SEC4">COMPILING A PATTERN</A>
|
|
<LI><A NAME="TOC5" HREF="#SEC5">MATCHING A PATTERN</A>
|
|
<LI><A NAME="TOC6" HREF="#SEC6">ERROR MESSAGES</A>
|
|
<LI><A NAME="TOC7" HREF="#SEC7">STORAGE</A>
|
|
<LI><A NAME="TOC8" HREF="#SEC8">AUTHOR</A>
|
|
</UL>
|
|
<LI><A NAME="SEC1" HREF="#TOC1">NAME</A>
|
|
<P>
|
|
pcreposix - POSIX API for Perl-compatible regular expressions.
|
|
</P>
|
|
<LI><A NAME="SEC2" HREF="#TOC1">SYNOPSIS</A>
|
|
<P>
|
|
<B>#include <pcreposix.h></B>
|
|
</P>
|
|
<P>
|
|
<B>int regcomp(regex_t *<I>preg</I>, const char *<I>pattern</I>,</B>
|
|
<B>int <I>cflags</I>);</B>
|
|
</P>
|
|
<P>
|
|
<B>int regexec(regex_t *<I>preg</I>, const char *<I>string</I>,</B>
|
|
<B>size_t <I>nmatch</I>, regmatch_t <I>pmatch</I>[], int <I>eflags</I>);</B>
|
|
</P>
|
|
<P>
|
|
<B>size_t regerror(int <I>errcode</I>, const regex_t *<I>preg</I>,</B>
|
|
<B>char *<I>errbuf</I>, size_t <I>errbuf_size</I>);</B>
|
|
</P>
|
|
<P>
|
|
<B>void regfree(regex_t *<I>preg</I>);</B>
|
|
</P>
|
|
<LI><A NAME="SEC3" HREF="#TOC1">DESCRIPTION</A>
|
|
<P>
|
|
This set of functions provides a POSIX-style API to the PCRE regular expression
|
|
package. See the <B>pcre</B> documentation for a description of the native API,
|
|
which contains additional functionality.
|
|
</P>
|
|
<P>
|
|
The functions described here are just wrapper functions that ultimately call
|
|
the native API. Their prototypes are defined in the <B>pcreposix.h</B> header
|
|
file, and on Unix systems the library itself is called <B>pcreposix.a</B>, so
|
|
can be accessed by adding <B>-lpcreposix</B> to the command for linking an
|
|
application which uses them. Because the POSIX functions call the native ones,
|
|
it is also necessary to add \fR-lpcre\fR.
|
|
</P>
|
|
<P>
|
|
I have implemented only those option bits that can be reasonably mapped to PCRE
|
|
native options. In addition, the options REG_EXTENDED and REG_NOSUB are defined
|
|
with the value zero. They have no effect, but since programs that are written
|
|
to the POSIX interface often use them, this makes it easier to slot in PCRE as
|
|
a replacement library. Other POSIX options are not even defined.
|
|
</P>
|
|
<P>
|
|
When PCRE is called via these functions, it is only the API that is POSIX-like
|
|
in style. The syntax and semantics of the regular expressions themselves are
|
|
still those of Perl, subject to the setting of various PCRE options, as
|
|
described below.
|
|
</P>
|
|
<P>
|
|
The header for these functions is supplied as <B>pcreposix.h</B> to avoid any
|
|
potential clash with other POSIX libraries. It can, of course, be renamed or
|
|
aliased as <B>regex.h</B>, which is the "correct" name. It provides two
|
|
structure types, <I>regex_t</I> for compiled internal forms, and
|
|
<I>regmatch_t</I> for returning captured substrings. It also defines some
|
|
constants whose names start with "REG_"; these are used for setting options and
|
|
identifying error codes.
|
|
</P>
|
|
<LI><A NAME="SEC4" HREF="#TOC1">COMPILING A PATTERN</A>
|
|
<P>
|
|
The function <B>regcomp()</B> is called to compile a pattern into an
|
|
internal form. The pattern is a C string terminated by a binary zero, and
|
|
is passed in the argument <I>pattern</I>. The <I>preg</I> argument is a pointer
|
|
to a regex_t structure which is used as a base for storing information about
|
|
the compiled expression.
|
|
</P>
|
|
<P>
|
|
The argument <I>cflags</I> is either zero, or contains one or more of the bits
|
|
defined by the following macros:
|
|
</P>
|
|
<P>
|
|
<PRE>
|
|
REG_ICASE
|
|
</PRE>
|
|
</P>
|
|
<P>
|
|
The PCRE_CASELESS option is set when the expression is passed for compilation
|
|
to the native function.
|
|
</P>
|
|
<P>
|
|
<PRE>
|
|
REG_NEWLINE
|
|
</PRE>
|
|
</P>
|
|
<P>
|
|
The PCRE_MULTILINE option is set when the expression is passed for compilation
|
|
to the native function.
|
|
</P>
|
|
<P>
|
|
In the absence of these flags, no options are passed to the native function.
|
|
This means the the regex is compiled with PCRE default semantics. In
|
|
particular, the way it handles newline characters in the subject string is the
|
|
Perl way, not the POSIX way. Note that setting PCRE_MULTILINE has only
|
|
<I>some</I> of the effects specified for REG_NEWLINE. It does not affect the way
|
|
newlines are matched by . (they aren't) or a negative class such as [^a] (they
|
|
are).
|
|
</P>
|
|
<P>
|
|
The yield of <B>regcomp()</B> is zero on success, and non-zero otherwise. The
|
|
<I>preg</I> structure is filled in on success, and one member of the structure
|
|
is publicized: <I>re_nsub</I> contains the number of capturing subpatterns in
|
|
the regular expression. Various error codes are defined in the header file.
|
|
</P>
|
|
<LI><A NAME="SEC5" HREF="#TOC1">MATCHING A PATTERN</A>
|
|
<P>
|
|
The function <B>regexec()</B> is called to match a pre-compiled pattern
|
|
<I>preg</I> against a given <I>string</I>, which is terminated by a zero byte,
|
|
subject to the options in <I>eflags</I>. These can be:
|
|
</P>
|
|
<P>
|
|
<PRE>
|
|
REG_NOTBOL
|
|
</PRE>
|
|
</P>
|
|
<P>
|
|
The PCRE_NOTBOL option is set when calling the underlying PCRE matching
|
|
function.
|
|
</P>
|
|
<P>
|
|
<PRE>
|
|
REG_NOTEOL
|
|
</PRE>
|
|
</P>
|
|
<P>
|
|
The PCRE_NOTEOL option is set when calling the underlying PCRE matching
|
|
function.
|
|
</P>
|
|
<P>
|
|
The portion of the string that was matched, and also any captured substrings,
|
|
are returned via the <I>pmatch</I> argument, which points to an array of
|
|
<I>nmatch</I> structures of type <I>regmatch_t</I>, containing the members
|
|
<I>rm_so</I> and <I>rm_eo</I>. These contain the offset to the first character of
|
|
each substring and the offset to the first character after the end of each
|
|
substring, respectively. The 0th element of the vector relates to the entire
|
|
portion of <I>string</I> that was matched; subsequent elements relate to the
|
|
capturing subpatterns of the regular expression. Unused entries in the array
|
|
have both structure members set to -1.
|
|
</P>
|
|
<P>
|
|
A successful match yields a zero return; various error codes are defined in the
|
|
header file, of which REG_NOMATCH is the "expected" failure code.
|
|
</P>
|
|
<LI><A NAME="SEC6" HREF="#TOC1">ERROR MESSAGES</A>
|
|
<P>
|
|
The <B>regerror()</B> function maps a non-zero errorcode from either
|
|
<B>regcomp</B> or <B>regexec</B> to a printable message. If <I>preg</I> is not
|
|
NULL, the error should have arisen from the use of that structure. A message
|
|
terminated by a binary zero is placed in <I>errbuf</I>. The length of the
|
|
message, including the zero, is limited to <I>errbuf_size</I>. The yield of the
|
|
function is the size of buffer needed to hold the whole message.
|
|
</P>
|
|
<LI><A NAME="SEC7" HREF="#TOC1">STORAGE</A>
|
|
<P>
|
|
Compiling a regular expression causes memory to be allocated and associated
|
|
with the <I>preg</I> structure. The function <B>regfree()</B> frees all such
|
|
memory, after which <I>preg</I> may no longer be used as a compiled expression.
|
|
</P>
|
|
<LI><A NAME="SEC8" HREF="#TOC1">AUTHOR</A>
|
|
<P>
|
|
Philip Hazel <ph10@cam.ac.uk>
|
|
<BR>
|
|
University Computing Service,
|
|
<BR>
|
|
New Museums Site,
|
|
<BR>
|
|
Cambridge CB2 3QG, England.
|
|
<BR>
|
|
Phone: +44 1223 334714
|
|
</P>
|
|
<P>
|
|
Copyright (c) 1997-2000 University of Cambridge.
|