This interface is made obsolete by
regex(3). It is available from the compatibility library, libcompat.
The
regcomp(),
regexec(),
regsub(), and
regerror() functions implement
egrep(1)-style regular expressions and supporting facilities.
The
regcomp() function compiles a regular expression into a structure of type
regexp, and returns a pointer to it. The space has been allocated using
malloc(3) and may be released by
free(3).
The
regexec() function matches a
NUL-terminated
string against the compiled regular expression in
prog. It returns 1 for success and 0 for failure, and adjusts the contents of
prog's
startp and
endp (see below) accordingly.
The members of a
regexp structure include at least the following (not necessarily in order):
char *startp[NSUBEXP];
char *endp[NSUBEXP];
where
NSUBEXP is defined (as 10) in the header file. Once a successful
regexec() has been done using the
regexp(), each
startp-
endp pair describes one substring within the
string, with the
startp pointing to the first character of the substring and the
endp pointing to the first character following the substring. The 0th substring is the substring of
string that matched the whole regular expression. The others are those substrings that matched parenthesized expressions within the regular expression, with parenthesized expressions numbered in left-to-right order of their opening parentheses.
The
regsub() function copies
source to
dest, making substitutions according to the most recent
regexec() performed using
prog. Each instance of `&' in
source is replaced by the substring indicated by
startp[] and
endp[]. Each instance of ‘\
n', where
n is a digit, is replaced by the substring indicated by
startp[
n] and
endp[
n]. To get a literal `&' or ‘\
n' into
dest, prefix it with `\'; to get a literal `\' preceding `&' or ‘\
n', prefix it with another `\'.
The
regerror() function is called whenever an error is detected in
regcomp(),
regexec(), or
regsub(). The default
regerror() writes the string
msg, with a suitable indicator of origin, on the standard error output and invokes
exit(3). The
regerror() function can be replaced by the user if other actions are desirable.