REGCOMP(3)          Linux Programmer's Manual          REGCOMP(3)

NAME
       regcomp,  regexec,  regerror,  regfree - POSIX regex func-
       tions

SYNOPSIS
       #include <regex.h>

       int regcomp(regex_t *preg, const char *regex, int cflags);
       int regexec(const   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);

POSIX REGEX COMPILING
       regcomp is used to compile a  regular  expression  into  a
       form that is suitable for subsequent regexec searches.

       regcomp  is  supplied  with  preg,  a pointer to a pattern
       buffer storage area; regex, a pointer to  the  null-termi-
       nated  string and cflags, flags used to determine the type
       of compilation.

       All regular expression searching must be done via  a  com-
       piled pattern buffer, thus regexec must always be supplied
       with the address of a regcomp initialised pattern  buffer.

       cflags may be the bitwise-or of one or more of the follow-
       ing:

       REG_EXTENDED
              Use POSIX Extended Regular Expression  syntax  when
              interpreting  regex.  If not set, POSIX Basic Regu-
              lar Expression syntax is used.

       REG_ICASE
              Do  not  differentiate  case.   Subsequent  regexec
              searches  using  this  pattern  buffer will be case
              insensitive.

       REG_NOSUB
              Support for substring addressing of matches is  not
              required.   The  nmatch  and  pmatch  parameters to
              regexec are ignored if the pattern buffer  supplied
              was compiled with this flag set.

       REG_NEWLINE
              Match-any-character  operators  don't  match a new-
              line.

              A non-matching list ([^...])  not containing a new-
              line does not match a newline.

              Match-beginning-of-line  operator  (^)  matches the
              empty string immediately after a  newline,  regard-
              less  of  whether  eflags,  the  execution flags of
              regexec, contains REG_NOTBOL.

              Match-end-of-line operator ($)  matches  the  empty
              string  immediately before a newline, regardless of
              whether eflags contains REG_NOTEOL.

POSIX REGEX MATCHING
       regexec is used to match a null-terminated string  against
       the  precompiled  pattern buffer, preg.  nmatch and pmatch
       are used to provide information regarding the location  of
       any  matches.  eflags may be the bitwise-or of one or both
       of REG_NOTBOL and REG_NOTEOL which cause changes in match-
       ing behaviour described below.

       REG_NOTBOL
              The  match-beginning-of-line  operator always fails
              to match (but see the compilation flag  REG_NEWLINE
              above)  This  flag  may be used when different por-
              tions of a string are passed  to  regexec  and  the
              beginning  of  the string should not be interpreted
              as the beginning of the line.

       REG_NOTEOL
              The  match-end-of-line  operator  always  fails  to
              match  (but  see  the  compilation flag REG_NEWLINE
              above)

   BYTE OFFSETS
       Unless REG_NOSUB was set for the compilation of  the  pat-
       tern  buffer,  it  is  possible  to obtain substring match
       addressing information.  pmatch  must  be  dimensioned  to
       have  at  least  nmatch  elements.  These are filled in by
       regexec with substring match addresses.  Any unused struc-
       ture elements will contain the value -1.

       The  regmatch_t  structure  which is the type of pmatch is
       defined in regex.h.

              typedef struct
              {
                regoff_t rm_so;
                regoff_t rm_eo;
              } regmatch_t;

       Each rm_so element that is not -1 indicates the start off-
       set of the next largest substring match within the string.
       The relative rm_eo element indicates the end offset of the
       match.

POSIX ERROR REPORTING
       regerror  is  used  to  turn  the  error codes that can be
       returned by both regcomp and regexec  into  error  message
       strings.

       regerror  is  passed  the error code, errcode, the pattern
       buffer, preg, a pointer  to  a  character  string  buffer,
       errbuf,  and  the  size of the string buffer, errbuf_size.
       It returns the size of the errbuf required to contain  the
       null-terminated  error message string.  If both errbuf and
       errbuf_size are non-zero, errbuf is  filled  in  with  the
       first  errbuf_size - 1 characters of the error message and
       a terminating null.

POSIX PATTERN BUFFER FREEING
       Supplying regfree with a precompiled pattern buffer,  preg
       will  free  the  memory allocated to the pattern buffer by
       the compiling process, regcomp.

RETURN VALUE
       regcomp returns zero for a successful  compilation  or  an
       error code for failure.

       regexec returns zero for a successful match or REG_NOMATCH
       for failure.

ERRORS
       The following errors can be returned by regcomp:

       REG_BADRPT
              Invalid use of repetition operators such  as  using
              `*' as the first character.

       REG_BADBR
              Invalid use of back reference operator.

       REG_EBRACE
              Un-matched brace interval operators.

       REG_EBRACK
              Un-matched bracket list operators.

       REG_ERANGE
              Invalid  use  of the range operator, eg. the ending
              point of the range occurs  prior  to  the  starting
              point.

       REG_ECTYPE
              Unknown character class name.

       REG_ECOLLATE
              Invalid collating element.

       REG_EPAREN
              Un-matched parenthesis group operators.

       REG_ESUBREG
              Invalid back reference to a subexpression.

       REG_EEND
              Non   specific  error.   This  is  not  defined  by
              POSIX.2.

       REG_EESCAPE
              Trailing backslash.

       REG_BADPAT
              Invalid use of pattern operators such as  group  or
              list.

       REG_ESIZE
              Compiled  regular  expression  requires  a  pattern
              buffer larger than 64Kb.  This is  not  defined  by
              POSIX.2.

       REG_ESPACE
              The regex routines ran out of memory.

CONFORMING TO
       POSIX.2

BUGS
       Currently  (GNU  libc  snapshot 980503), GNU libc does not
       support collating elements in regular expressions.

SEE ALSO
       regex(7), GNU regex manual

GNU                         8 May 1998                          1