HP 3000 Manuals HP 3000 Manuals
regexec
Compare string against compiled regular expression.
Sytnax
#include <sys/types.h>
#include <regex.h>
int regexec(const regex_t *reg, const char *string,
size_t maxmatch, regmatch_t submatch[] ,
int flags);
Parameters
reg Must point to an object where regcomp() stored a compiled
regular expression.
string Is the string you want to compare against the regular
expression associated with reg.
maxmatch Is the maximum number of matching substrings that you want
regexec() to find. This should be less than or equal to the
number of elements that can be stored in the submatch array.
submatch[] Points to an array with a length of at least maxmatch where
regexec()strings of string which match the regular expression
reg.
flags Holds flags that affect the behavior of regexec(). Flag
values are represented by symbolic constants defined in
<regex.h>. To get an appropriate flags value, OR the desired
symbols together. Possible symbols are:
REG_NOTBOL Tells regexec() not to treat the beginning of
string as the beginning of the text line.
This means that the special meaning of the
caret (^) (the beginning of the line) never
matches in string.
REG_NOTEO Tell regexec() not to treat the end of string
as the end of the text line. This means that
the special meaning of the dollar sign ($)
(the end of the line) never matches in
string.
Return Values
regexec() returns zero to indicate a successful match, or one of the
following error codes.
Description
regexec() compares the given string to the regular expression reg. reg
must have been created by a previous call to regcomp(). The regcomp()
flags that were specified at the time the regular expression was compiled
affect the results of as specified in the flags to regcomp() or maxmatch
is zero, regexec() simply checks whether or not the given string contains
a match for reg. If so, regexec() returns zero. If there is no match,
regexec() returns the value of REG_NOMATCH, defined in <regex.h>. When
REG_NOSUB is in effect, maxmatch should be zero.
If REG_NOSUB was not specified, regexec() uses the array submatch to
record substrings matching the regular expression. The elements of this
array have the structure type regmatch_t, defined in <regex.h>. This
structure contains at least the following:
char points to the first character of a matching substring.
*rm_sp;
char points to the character immediately following the end of a
*rm_ep; matching substring.
off_t offset from string to the first character of a matching
rm_so; substring.
off_t offset from string to the character immediately following the
rm_eo; end of a matching substring.
submatch[0] contains the first substring of string that matches the
entire regular expression reg. If reg contains parenthesized
subexpressions, submatch[i] contains the substring matching the ith
parenthesized subexpression. For example, if you have a Basic regular
expression
a\(b*\)c\(d*\)
submatch[0] contains the match for the whole regular expression,
submatch[1] contains the match for \(b*\), and submatch[2] contains the
match for \(d*\). Unused elements of submatch have NULL pointers and -1
offsets. If there are more than maxmatch matching substrings, regexec()
finds them but only records maxmatch in submatch.
A parenthesized subexpression of pattern might be part of several
different substring matches, or match nothing even though the expression
as a whole matches. In this case, regexec() follows these rules:
1. If subexpression i participated in the match several times,
submatch[i] refers to the last such match.
2. If subexpression i did not participate in a successful match, the
pointers in submatch[i] are NULL and the byte offsets in
submatch[i] are set to -1. This can happen, for example, if the
regular expression has the form A|B; if string matches the A part
and subexpression i appears in the B part, there is no match for
subexpression i.
3. If subexpression i is contained within another subexpression j, no
other subexpression within j contains i, and submatch[j] reports a
match of subexpression j, then submatch[i] reports the match or
nonmatch of subexpression i as described in rules 1 and 2, but
within the substring reported in submatch[j] rather than the whole
string.
4. If subexpression i is contained in subexpression j, and the
pointers in submatch[j] are NULL, the pointers in submatch[i] are
also NULL and the byte offsets in submatch[i] are set to -1.
5. If subexpression i matches a zero-length string, both pointers and
both byte offsets in submatch[i] indicate the character after the
zero-length string.
Errors
If an error occurs, errno is set to one of the following values:
REG_ESPACE CAUSE There were not enough free system for regexec() to
carry out the comparison.
ACTION Free up more resources, or specify a less complex
regular expression or shorter string.
REG_NOMATCH CAUSE No match was found.
ACTION No action is required.
REG_EFATAL CAUSE Some other error occurred. For example, reg was not
a valid compiled regular expression, or was destroyed
by an errant pointer.
ACTION Check your program carefully.
See Also
grep(1), regcomp(), regfree(), regexp(3)