regexec -- Execute Compiled Regular Expression

Format

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

Language Level: POSIX, XPG4
regexec compares the null-terminated string against the compiled regular expression preg to find a match between the two.

nmatch is the number of substrings in string that regexec should try to match with subexpressions in preg. The array you supply for pmatch must have at least nmatch elements.

regexec fills in the elements of the array pmatch with offsets of the substrings in string that correspond to the parenthesized subexpressions of the original pattern given to regcomp to create preg. The zeroth element of the array corresponds to the entire pattern. If there are more than nmatch subexpressions, only the first nmatch - 1 are stored. If nmatch is 0, or if the REG_NOSUB flag was set when preg was created with regcomp, regexec ignores the pmatch argument.

The eflags flag defines customizable behavior of regexec:

REG_NOTBOL Indicates that the first character of string is not the beginning of line.
REG_NOTEOL Indicates that the first character of string is not the end of line.

When a basic or extended regular expression is matched, any given parenthesized subexpression of the original pattern could participate in the match of several different substrings of string. The following rules determine which substrings are reported in pmatch:

  1. If a subexpression participated in a match several times, regexec stores the offset of the last matching substring in pmatch.
  2. If a subexpression did not match in the source string, regexec sets the offset shown in pmatch to -1.
  3. If a subexpression contains subexpressions, the data in pmatch refers to the last such subexpression.
  4. If a subexpression matches a zero-length string, the offsets in pmatch refer to the byte immediately following the matching string.

If the REG_NOSUB flag was set when preg was created by regcomp, the contents of pmatch are unspecified. If the REG_NEWLINE flag was not set when preg was created, new-line characters are allowed in string.

Note: If MB_CUR_MAX is specified as 2, the charmap file does not specify the DBCS characters, and a collating element (for example, [:a:]) is specified in the pattern, the DBCS characters will not match against the collating-element even if they have an equivalent weight to the collating-element.

Return Value
If a match is found, regexec returns 0. If no match is found, regexec returns REG_NOMATCH. Otherwise, regexec returns a nonzero value indicating an error. A nonzero return value can be used in a call to regerror.

Example



Regular Expressions


regcomp -- Compile Regular Expression
regerror -- Return Error Message for Regular Expression
regfree -- Free Memory for Regular Expression
<regex.h>