POSIX Matching
--------------

  Matching the POSIX way means trying to match a null-terminated string
starting at its first character.  Once you've compiled a pattern into a
pattern buffer (see POSIX Regular Expression Compiling.), you can
ask the matcher to match that pattern against a string using:

     int
     regexec (const regex_t *PREG, const char *STRING,
              size_t NMATCH, regmatch_t PMATCH[], int EFLAGS)

PREG is the address of a pattern buffer for a compiled pattern.  STRING
is the string you want to match.

  See Using Byte Offsets, for an explanation of PMATCH.  If you
pass zero for NMATCH or you compiled PREG with the compilation flag
`REG_NOSUB' set, then `regexec' will ignore PMATCH; otherwise, you must
allocate it to have at least NMATCH elements.  `regexec' will record
NMATCH byte offsets in PMATCH, and set to -1 any unused elements up to
PMATCH`[NMATCH]' - 1.

  EFLAGS specifies "execution flags"--namely, the two bits `REG_NOTBOL'
and `REG_NOTEOL' (defined in `regex.h').  If you set `REG_NOTBOL', then
the match-beginning-of-line operator (*note Match-beginning-of-line
Operator::.) always fails to match.  This lets you match against pieces
of a line, as you would need to if, say, searching for repeated
instances of a given pattern in a line; it would work correctly for
patterns both with and without match-beginning-of-line operators.
`REG_NOTEOL' works analogously for the match-end-of-line operator
(see Match-end-of-line Operator.); it exists for symmetry.

  `regexec' tries to find a match for PREG in STRING according to the
syntax in PREG's `syntax' field.  (*Note POSIX Regular Expression
Compiling::, for how to set it.)  The function returns zero if the
compiled pattern matches STRING and `REG_NOMATCH' (defined in
`regex.h') if it doesn't.