 |
» |
|
|
|
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 *rm_sp;
points to the first character of a matching substring.
- char *rm_ep;
points to the character immediately following the end
of a matching substring.
- off_t rm_so;
offset from string to the first character of a matching
substring.
- off_t rm_eo;
offset from string to the character immediately
following the 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 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: If subexpression i participated in the match several
times, submatch[i] refers to the last such match.
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.
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.
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.
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) |
