regexec()

Updated: April 19, 2023

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:

libregex

Use the -l regex option to qcc to link against this library.

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.