18.6.1.3 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 (see 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 an 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 of pattern_buffer. (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.