Guardian Native C Library Calls Reference Manual (G06.28+, H06.04+)

regcomp(3) Guardian Native C Library Calls Reference Manual
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.
• If a subexpression matched a zero-length string, the offsets in the pmatch parameter refer
to the byte immediately following the matching string.
If the REG_NOSUB flag was set in the cflags parameter in the call to the regcomp() function,
and the nmatch parameter is not equal to 0 (zero) in the call to the regexec function, the content
of the pmatch array is unspecified.
If the REG_NEWLINE flag was not set in the cflags parameter when the regcomp() function
was called, then a newline character in the pattern or string parameter is treated as an ordinary
character. If the REG_NEWLINE flag was set when the regcomp() function was called, the
newline character is treated as an ordinary character, except as follows:
• A newline character in the string parameter is not matched by a . (dot) outside of a
bracket expression or by any form of a nonmatching list.
• A ˆ (circumflex) in the pattern parameter, when used to specify expression anchoring,
matches the zero-length string immediately after a newline character in the string param-
eter, regardless of the setting of the REG_NOTBOL flag.
• A $ (dollar sign) in the pattern parameter, when used to specify expression anchoring,
matches the zero-length string immediately before a newline character in the string
parameter, regardless of the setting of the REG_NOTEOL flag.
The regerror() function returns the text associated with the specified error code. If the
regcomp() or regexec() function fails, it returns a nonzero error code. If this return value is
assigned to the errcode parameter, the regerror() function returns the text of the associated mes-
sage.
The regfree() function frees any memory allocated by the regcomp() function associated with
the preg parameter. An expression defined by the preg parameter is no longer treated as a com-
piled basic or extended regular expression after it is given to the regfree() function.
5−62 Hewlett-Packard Company 527192-005