Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

OSS Library Calls (n - r) regcomp(3)
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.
• 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 c
fl
ags 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.
527187-017 Hewlett-Packard Company 5−165