


PCRE(3)                                                   PCRE(3)


NAME
       pcreposix  - POSIX API for Perl-compatible regular expres-
       sions.

SYNOPSIS
       #include <pcreposix.h>

       int regcomp(regex_t *preg, const char *pattern,
            int cflags);

       int regexec(regex_t *preg, const char *string,
            size_t nmatch, regmatch_t pmatch[], int eflags);

       size_t regerror(int errcode, const regex_t *preg,
            char *errbuf, size_t errbuf_size);

       void regfree(regex_t *preg);



DESCRIPTION
       This set of functions provides a POSIX-style  API  to  the
       PCRE  regular  expression  package.  See  pcre  (3)  for a
       description of the native API, which  contains  additional
       functionality. The functions described here are just wrap-
       per functions that ultimately call the native API.

       As I am pretty ignorant about POSIX, these functions  must
       be  considered  as  experimental.  I have implemented only
       those option bits that can be reasonably  mapped  to  PCRE
       native  options. Other POSIX options are not even defined.
       It may be that it is useful to define, but  ignore,  other
       options.  Feedback  from more knowledgeable folk may cause
       this kind of detail to change.

       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.

       The header for these functions is supplied as  pcreposix.h
       to  avoid  any potential clash with other POSIX libraries.
       It can, of course, be renamed or aliased as regex.h, which
       is  the  "correct"  name. It provides two structure types,
       regex_t for compiled internal forms,  and  regmatch_t  for
       returning  captured  substrings. It also defines some con-
       stants whose names start with "REG_"; these are  used  for
       setting options and identifying error codes.



COMPILING A PATTERN
       The function regcomp() is called to compile a pattern into



                                                                1





PCRE(3)                                                   PCRE(3)


       an internal form. The pattern is a C string terminated  by
       a  binary zero, and is passed in the argument pattern. The
       preg argument is a pointer to a regex_t structure which is
       used  as a base for storing information about the compiled
       expression.

       The argument cflags is either zero,  or  contains  one  or
       more of the bits defined by the following macros:

         REG_ICASE

       The  PCRE_CASELESS  option  is  set when the expression is
       passed for compilation to the native function.

         REG_NEWLINE

       The PCRE_MULTILINE option is set when  the  expression  is
       passed for compilation to the native function.

       The  yield  of  regcomp() is zero on success, and non-zero
       otherwise. The preg structure is filled in on success, and
       one  member  of  the structure is publicized: re_nsub con-
       tains the number of capturing subpatterns in  the  regular
       expression.  Various error codes are defined in the header
       file.



MATCHING A PATTERN
       The function regexec() is called to match  a  pre-compiled
       pattern  preg  against a given string, which is terminated
       by a zero byte, subject to the options  in  eflags.  These
       can be:

         REG_NOTBOL

       The  PCRE_NOTBOL option is set when calling the underlying
       PCRE matching function.

         REG_NOTEOL

       The PCRE_NOTEOL option is set when calling the  underlying
       PCRE matching function.

       The  portion  of the string that was matched, and also any
       captured substrings, are returned via the pmatch argument,
       which points to an array of nmatch structures of type reg-
       match_t, containing the members  rm_so  and  rm_eo.  These
       contain  the  offset  to  the first character of each sub-
       string 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  string  that  was
       matched;  subsequent elements relate to the capturing sub-
       patterns of the regular expression. Unused entries in  the



                                                                2





PCRE(3)                                                   PCRE(3)


       array have both structure members set to -1.

       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.



ERROR MESSAGES
       The  regerror()  function  maps  a non-zero errorcode from
       either regcomp or regexec to a printable message. If  preg
       is  not NULL, the error should have arisen from the use of
       that structure. A message terminated by a binary  zero  is
       placed in errbuf. The length of the message, including the
       zero, is limited to errbuf_size. The yield of the function
       is the size of buffer needed to hold the whole message.



STORAGE
       Compiling  a  regular expression causes memory to be allo-
       cated and associated with the preg structure. The function
       regfree()  frees  all such memory, after which preg may no
       longer be used as a compiled expression.



AUTHOR
       Philip Hazel <ph10@cam.ac.uk>
       University Computing Service,
       New Museums Site,
       Cambridge CB2 3QG, England.
       Phone: +44 1223 334714

       Copyright (c) 1998 University of Cambridge.
