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 );

Arguments:

preg

A pointer to the regex_t object for the regular expression that you want to execute. You must have compiled the expression by calling regcomp().

string

The string that you want to match against the regular expression.

nmatch

The maximum number of matches to record in pmatch.

pmatch

An array of regmatch_t objects where the function can record the matches; see below.

eflags

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 — the string argument doesn't point to the beginning of a line.
REG_NOTEOL — the end of string isn't the end of a line.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Note: This function is in libc.a, but not in libc.so (in order to save space).

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 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().

The regexec() function records the matches in the pmatch array, with nmatch specifying the maximum number of matches to record. The regmatch_t structure is defined as:

typedef struct {
	regoff_t rm_so;
	regoff_t rm_eo;
} regmatch_t;

The members are:

rm_so: The byte offset from the beginning of the string to the beginning of the matched substring.
rm_eo: One greater than the offset from the beginning of the string to the end of the matched substring.

The offsets 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 -1.

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

Returns:

0: The string argument matches preg.
<>0: A match wasn't found, or an error occurred (use regerror() to get an explanation).

Examples:

See regcomp().

Classification:

POSIX 1003.1

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes

Contributing author:

Henry Spencer. For license information, see “Licensing information” in Typographical Conventions, Support, and Licensing.