regexec()

compare a string with a compiled regular expression

Synopsis:

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

Description:

The regexec() function compares string against the compiled regular expression preg. If regexec() finds a match, it returns zero, otherwise it returns nonzero.

The preg argument must have been successfully initialized by regcomp(). It represents a compiled form of either a Basic Regular Expression or Extended Regular Expression. These classes are rigorously defined in IEEE P1003.2, Regular Expression Notation, and are summarized in the documentation for regcomp().

Matches are recorded in the pmatch array, with nmatch specifying the maximum number of matches to record. The regmatch_t structure contains the pointer members rm_sp and rm_ep, which are updated to identify the start and end of each matched substring. The pointers in pmatch[0] identify the substring corresponding to the entire expression, while those in pmatch[1...nmatch] identify up to the first nmatch subexpressions. Unused elements of the pmatch array are set to NULL.

You can disable the recording of substrings by either specifying REG_NOSUB in regcomp(), or by setting nmatch to zero.

The eflags argument specifies execution parameters to regexec(). For example, you may need to call regexec() multiple times if the line you're processing is too large to fit into string. The eflags argument is the bitwise inclusive OR of zero or more of the following flags:

REG_NOTBOL

string doesn't point to the beginning of a line.

REG_NOTEOL

The end of string isn't the end of a line.

Returns:

If the function regexec() successfully matches string with preg, it returns 0. If unsuccessful, or an error occurs, regexec() returns a nonzero value.

Examples:

See regcomp().

Classification:

POSIX 1003.2

See also:

regcomp(), regerror(), regfree()