Open System Services Library Calls Reference Manual (G06.28+, H06.05+)

regcomp(3) OSS Library Calls Reference Manual
DESCRIPTION
|
The regcomp(), regerror(), regexec(), and regfree() functions perform regular expression |
matching. The regcomp() function compiles a regular expression and the regexec() function |
compares the compiled regular expression to a string. The regerror() function returns text asso- |
ciated with an error condition encountered by regcomp() or regexec(). The regfree() function |
frees the internal storage allocated for the compiled regular expression. |
The regcomp() function compiles the basic or extended regular expression specified by the pat- |
tern parameter and places the output in the preg structure. |
The regexec() function compares the NULL terminated string in the string parameter against the |
compiled basic or extended regular expression in the preg parameter. If a match is found, the |
regexec() function returns a value of 0 (zero). The regexec() function returns a nonzero value if |
there is no match or if there is an error. |
If the value of the nmatch parameter is 0 (zero), or if the REG_NOSUB flag was set on the call |
to the regcomp() function, the regexec() function ignores the pmatch parameter. Otherwise, the |
pmatch parameter points to an array of at least the number of elements specified by the nmatch |
parameter. The regexec() function fills in the elements of the array pointed to by the pmatch |
parameter with offsets of the substrings of the string parameter. The elements of the pmatch |
array correspond to the parenthetic subexpressions of the original pattern parameter that was |
specified to the regcomp() function. The pmatch[i].rm_so structure is the byte offset of the |
beginning of the substring, and the pmatch[i].rm_eo structure is one greater than the byte offset |
of the end of the substring. Subexpression i begins at the ith matched open parenthesis, counting |
from 1. The 0 (zero) element of the array corresponds to the entire pattern. Unused elements of |
the pmatch parameter, up to the value pmatch[nmatch-1], are filled with -1. If there are more |
than the number of subexpressions specified by the nmatch parameter (the pattern parameter |
itself counts as a subexpression), only the first nmatch-1 are recorded. |
When matching a basic or extended regular expression, any given parenthetic subexpression of |
the pattern parameter can participate in the match of several different substrings of the string |
parameter; however, it may not match any substring even though the pattern as a whole did |
match. The following rules are used to determine which substrings to report in the pmatch |
parameter when matching regular expressions: |
|
• ||
If a subexpression in a regular expression participated in the match several times, the |
offset of the last matching substring is reported in the pmatch parameter. |
|
• ||
If a subexpression did not participate in a match, then the byte offset in the pmatch |
parameter is a value of -1. |
|
• ||
If a subexpression is contained in a subexpression, the data in the pmatch parameter |
refers to the last such subexpression. |
|
• ||
If a subexpression is contained in a subexpression and the byte offsets in the pmatch |
parameter have a value of -1, the pointers in the pmatch parameter also have a value of |
-1. |
5−92 Hewlett-Packard Company 527187-007