regexec() compare string to regular expression	Function
	SYNOPSIS DESCRIPTION PARAMETERS RETURN VALUES CONFORMANCE MULTITHREAD SAFETY LEVEL PORTING ISSUES AVAILABILITY SEE ALSO

---

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 the null-terminated string specified by string with the compiled regular expression preg initialized by a previous call to regcomp(). If it finds a match, regexec() returns 0; otherwise it returns nonzero indicating either no match or an error.

The following structure types contain at least the following members:

The eflags argument is the bitwise inclusive OR of zero or more of the following flags, which are defined in the header <regex.h>:

REG_NOTBOL 

The first character of the string pointed to by string is not the beginning of the line. Therefore, the circumflex character (^), when taken as a special character, does not match the beginning of string.

REG_NOTEOL 

The last character of the string pointed to by string is not the end of the line. Therefore, the dollar sign ($), when taken as a special character, does not match the end of string.

If nmatch is 0 or REG_NOSUB was set in the cflags argument to regcomp(), regexec() ignores the pmatch argument. Otherwise, the pmatch argument must point to an array with at least nmatch elements, and regexec() fills in the elements of that array with offsets of the substrings of string that correspond to the parenthesized subexpressions of pattern: pmatch[i].rm_so is the byte offset of the beginning and pmatch[i].rm_eo is one greater than the byte offset of the end of substring i. (Subexpression i begins at the ith matched open parenthesis, counting from 1.) Offsets in pmatch[0] identify the substring that corresponds to the entire regular expression. Unused elements of pmatch up to pmatch[nmatch-1] are filled with -1. If there are more than nmatch subexpressions in pattern (pattern itself counts as a subexpression), regexec() still does the match, but records only the first nmatch substrings.

When matching a basic or extended regular expression, any given parenthesized subexpression of pattern might participate in the match of several different substrings of string, or it might not match any substring even though the pattern as a whole did match. The following rules are used to determine which substrings to report in pmatch when matching regular expressions:

1. If subexpression i in a regular expression is not contained within another subexpression, and it participated in the match several times, then the byte offsets in pmatch[i] delimit the last such match.
2. If subexpression i is not contained within another subexpression, and it did not participate in an otherwise successful match, the byte offsets in pmatch[i] are -1. A subexpression does not participate in the match if one of the following conditions exists:
• An * or a \{ \} appears immediately after the subexpression in a basic regular expression, or *, ?, or { } appears immediately after the subexpression in an extended regular expression, and the subexpression did not match (matched 0 times).
• A | is used in an extended regular expression to select this subexpression or another, and the other subexpression matched.
3. If subexpression i is contained within another subexpression j, and i is not contained within any other subexpression that is contained within j, and a match of subexpression j is reported in pmatch[j], then the match or nonmatch of subexpression i reported in pmatch[i] is as described in Rule 1 and Rule 2 above, but within the substring reported in pmatch[j] rather than the whole string.
4. If subexpression i is contained in subexpression j, and the byte offsets in pmatch[j] are -1, then the pointers in pmatch[i] also are -1.
5. If subexpression i matched a zero-length string, then both byte offsets in pmatch[i] are the byte offset of the character or null terminator immediately following the zero-length string.

If, when regexec() is called, the locale is different from when the regular expression was compiled, the result is undefined.

If REG_NEWLINE is not set in cflags, then a newline character in pattern or string is treated as an ordinary character. If REG_NEWLINE is set, a newline is treated as an ordinary character except as follows:

• A newline character in string is not matched by a period outside a bracket expression or by any form of a nonmatching list.
• A circumflex (^) in pattern, when used to specify expression anchoring, matches the zero-length string immediately after a newline in string, regardless of the setting of REG_NOTBOL.
• A dollarsign ($) in pattern, when used to specify expression anchoring, matches the zero-length string immediately before a newline in string, regardless of the setting of REG_NOTEOL.

If the preg argument to regexec() is not a compiled regular expression returned by regcomp(), the result is undefined. A preg is no longer treated as a compiled regular expression after it is given to regfree().

---

PARAMETERS

preg 

Points to the compiled regular expression that a previous call to regcomp() initialized.

string 

Points to a null-terminated string.

nmatch 

Is the number of matches allowed.

pmatch 

When nmatch is non-zero, points to an array with at least nmatch elements.

eflags 

The bitwise inclusive OR of zero or more of the flags defined in the header <regex.h>.

---

RETURN VALUES

If successful, the regexec() function returns zero to indicate that string matched pattern. On failure, it returns REG_NOMATCH (defined in <regex.h>) to indicate that there was no match.

---

CONFORMANCE

POSIX.2 (1992)

---

MULTITHREAD SAFETY LEVEL

MT-Safe.

---

PORTING ISSUES

None.

---

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

---

SEE ALSO

Functions:

regcomp(), regerror(), regfree()

---

PTC MKS Toolkit 10.4 Documentation Build 39.