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