Click above to get retro games delivered to your door ever month!

regexec
=======

Syntax
------

     #include <sys/types.h>
     #include <regex.h>
     
     int regexec(const regex_t *preg, const char *string,
                 size_t nmatch, regmatch_t pmatch[], int eflags);

Description
-----------

`regexec' matches the compiled RE pointed to by PREG against the
STRING, subject to the flags in EFLAGS, and reports results using
NMATCH, PMATCH, and the returned value.  The RE must have been compiled
by a previous invocation of `regcomp' (regcomp:.).  The compiled   
form is not altered during execution of `regexec', so a single compiled
RE can be used simultaneously by multiple threads.

By default, the NUL-terminated string pointed to by STRING is
considered to be the text of an entire line, minus any terminating
newline.

The EFLAGS argument is the bitwise OR of zero or more of the following
flags:

`REG_NOTBOL'
     The first character of the string is not the beginning of a line,
     so the `' anchor should not match before it.  This does not
     affect the behavior of newlines under `REG_NEWLINE' (REG_NEWLINE,
     regcomp:.).   

`REG_NOTEOL'
     The NUL terminating the string does not end a line, so the `$'
     anchor should not match before it.  This does not affect the
     behavior of newlines under `REG_NEWLINE' (REG_NEWLINE, *note
     regcomp::.).

`REG_STARTEND'
     The string is considered to start at STRING + PMATCH[0].RM_SO and
     to have a terminating `NUL' located at STRING + PMATCH[0].RM_EO
     (there need not actually be a `NUL' at that location), regardless
     of the value of NMATCH.  See below for the definition of PMATCH
     and NMATCH.  This is an extension, compatible with but not
     specified by POSIX 1003.2, and should be used with caution in
     software intended to be portable to other systems.  Note that a
     non-zero `rm_so' does not imply `REG_NOTBOL'; `REG_STARTEND'
     affects only the location of the string, not how it is matched.

`REG_TRACE'
     trace execution (printed to stdout)

`REG_LARGE'
     force large representation

`REG_BACKR'
     force use of backref code

Regular Expressions' Syntax, regcomp:, for a discussion of what   
is matched in situations where an RE or a portion thereof could match
any of several substrings of STRING.

If `REG_NOSUB' was specified in the compilation of the RE (REG_NOSUB,
regcomp:.), or if NMATCH is 0, `regexec' ignores the PMATCH   
argument (but see below for the case where `REG_STARTEND' is
specified).  Otherwise, PMATCH should point to an array of NMATCH
structures of type `regmatch_t'.  Such a structure has at least the
members `rm_so' and `rm_eo', both of type `regoff_t' (a signed
arithmetic type at least as large as an `off_t' and a `ssize_t',
containing respectively the offset of the first character of a
substring and the offset of the first character after the end of the
substring.  Offsets are measured from the beginning of the STRING
argument given to `regexec'.  An empty substring is denoted by equal
offsets, both indicating the character following the empty substring.

When `regexec' returns, the 0th member of the PMATCH array is filled in
to indicate what substring of STRING was matched by the entire RE.
Remaining members report what substring was matched by parenthesized
subexpressions within the RE; member `i' reports subexpression `i',
with subexpressions counted (starting at 1) by the order of their
opening parentheses in the RE, left to right.  Unused entries in the
array--corresponding either to subexpressions that did not participate
in the match at all, or to subexpressions that do not exist in the RE
(that is, `i > preg->re_nsub'--have both `rm_so' and `rm_eo' set to
`-1'.  If a subexpression participated in the match several times, the
reported substring is the last one it matched.  (Note, as an example in
particular, that when the RE `(b*)+' matches `bbb', the parenthesized
subexpression matches each of the three `b's and then an infinite
number of empty strings following the last `b', so the reported
substring is one of the empties.)

If `REG_STARTEND' is specified in EFLAGS, PMATCH must point to at least
one `regmatch_t' variable (even if NMATCH is 0 or `REG_NOSUB' was
specified in the compilation of the RE, REG_NOSUB, regcomp:.),   
to hold the input offsets for `REG_STARTEND'.  Use for output is still
entirely controlled by NMATCH; if NMATCH is 0 or `REG_NOSUB' was
specified, the value of `pmatch[0]' will not be changed by a successful
`regexec'.

NMATCH exceeding 0 is expensive; NMATCH exceeding 1 is worse.  Back
references are massively expensive.

Return Value
------------

Normally, `regexec' returns 0 for success and the non-zero code
`REG_NOMATCH' for failure.  Other non-zero error codes may be returned
in exceptional situations.  The list of possible error return values is
below:

`REG_ESPACE'
     ran out of memory

`REG_BADPAT'
     the passed argument PREG doesn't point to an RE compiled by
     `regcomp'

`REG_INVARG'
     invalid argument(s) (e.g., STRING + PMATCH[0].RM_EO is less than
     STRING + PMATCH[0].RM_SO)