18.6.1.4 GNU Searching

Searching means trying to match starting at successive positions within a string. The function re_search does this.

Before calling re_search, you must compile your regular expression. See GNU Regular Expression Compiling.

Here is the function declaration:

int
re_search (struct re_pattern_buffer *pattern_buffer,
           const char *string, const int size,
           const int start, const int range,
           struct re_registers *regs)

whose arguments are the same as those to re_match (see GNU Matching) except that the two arguments start and range replace re_match’s argument start.

If range is positive, then re_search attempts a match starting first at index start, then at start + 1 if that fails, and so on, up to start + range; if range is negative, then it attempts a match starting first at index start, then at start -1 if that fails, and so on.

If start is not between zero and size, then re_search returns -1. When range is positive, re_search adjusts range so that start + range - 1 is between zero and size, if necessary; that way it won’t search outside of string. Similarly, when range is negative, re_search adjusts range so that start + range + 1 is between zero and size, if necessary.

If the fastmap field of pattern_buffer is zero, re_search matches starting at consecutive positions; otherwise, it uses fastmap to make the search more efficient. See Searching with Fastmaps.

If no match is found, re_search returns -1. If a match is found, it returns the index where the match began. If an internal error happens, it returns -2.