GNU Matching
------------

  Matching the GNU way means trying to match as much of a string as
possible starting at a position within it you specify.  Once you've
compiled a pattern into a pattern buffer (*note GNU Regular Expression
Compiling::.), you can ask the matcher to match that pattern against a
string using:

     int
     re_match (struct re_pattern_buffer *PATTERN_BUFFER,
               const char *STRING, const int SIZE,
               const int START, struct re_registers *REGS)

PATTERN_BUFFER is the address of a pattern buffer containing a compiled
pattern.  STRING is the string you want to match; it can contain
newline and null characters.  SIZE is the length of that string.  START
is the string index at which you want to begin matching; the first
character of STRING is at index zero.  See Using Registers, for a
explanation of REGS; you can safely pass zero.

  `re_match' matches the regular expression in PATTERN_BUFFER against
the string STRING according to the syntax in PATTERN_BUFFERS's `syntax'
field.  (See GNU Regular Expression Compiling, for how to set it.)
The function returns -1 if the compiled pattern does not match any part
of STRING and -2 if an internal error happens; otherwise, it returns
how many (possibly zero) characters of STRING the pattern matched.

  An example: suppose PATTERN_BUFFER points to a pattern buffer
containing the compiled pattern for `a*', and STRING points to `aaaaab'
(whereupon SIZE should be 6). Then if START is 2, `re_match' returns 3,
i.e., `a*' would have matched the last three `a's in STRING.  If START
is 0, `re_match' returns 5, i.e., `a*' would have matched all the `a's
in STRING.  If START is either 5 or 6, it returns zero.

  If START is not between zero and SIZE, then `re_match' returns -1.