Before you can actually match a regular expression, you must compile it. This is not true compilation--it produces a special data structure, not machine instructions. But it is like ordinary compilation in that its purpose is to enable you to "execute" the pattern fast. (See section Matching a Compiled POSIX Regular Expression, for how to use the compiled regular expression for matching.)
There is a special data type for compiled regular expressions:
re_nsub
There are several other fields, but we don't describe them here, because only the functions in the library should use them.
After you create a regex_t
object, you can compile a regular
expression into it by calling regcomp
.
regcomp
"compiles" a regular expression into a
data structure that you can use with regexec
to match against a
string. The compiled regular expression format is designed for
efficient matching. regcomp
stores it into *compiled
.
The parameter pattern points to the regular expression to be
compiled. When using regcomp
, pattern must be
0-terminated. When using regncomp
, pattern must be
len characters long.
regncomp
is not a standard function; strictly POSIX programs
should avoid using it.
It's up to you to allocate an object of type regex_t
and pass its
address to regcomp
.
Before freeing the object of type regex_t
You must pass it
to regfree
. Not doing so may cause subsequent calls to Rx
functions to behave strangely.
The argument cflags lets you specify various options that control the syntax and semantics of regular expressions. See section Flags for POSIX Regular Expressions.
If you use the flag REG_NOSUB
, then regcomp
omits from
the compiled regular expression the information necessary to record
how subexpressions actually match. In this case, you might as well
pass 0
for the matchptr and nmatch arguments when
you call regexec
.
If you don't use REG_NOSUB
, then the compiled regular expression
does have the capacity to record how subexpressions match. Also,
regcomp
tells you how many subexpressions pattern has, by
storing the number in compiled->re_nsub
. You can use that
value to decide how long an array to allocate to hold information about
subexpression matches.
regcomp
returns 0
if it succeeds in compiling the regular
expression; otherwise, it returns a nonzero error code (see the table
below). You can use regerror
to produce an error message string
describing the reason for a nonzero value; see section POSIX Regexp Matching Cleanup.
Here are the possible nonzero values that regcomp
can return:
REG_BADBR
REG_BADPAT
REG_BADRPT
REG_ECOLLATE
REG_ECTYPE
REG_EESCAPE
REG_ESUBREG
REG_EBRACK
REG_EPAREN
REG_EBRACE
REG_ERANGE
REG_ESPACE
regcomp
ran out of memory.
Go to the first, previous, next, last section, table of contents.