library_9.html

Linux程序员的工作手册

expression into it by calling <CODE>regcomp</CODE>.
<P>
<A NAME="IDX400"></A>
<U>Function:</U> int <B>regcomp</B> <I>(regex_t *<VAR>compiled</VAR>, const char *<VAR>pattern</VAR>, int <VAR>cflags</VAR>)</I><P>
The function <CODE>regcomp</CODE> "compiles" a regular expression into a
data structure that you can use with <CODE>regexec</CODE> to match against a
string.  The compiled regular expression format is designed for
efficient matching.  <CODE>regcomp</CODE> stores it into <CODE>*<VAR>compiled</VAR></CODE>.
<P>
It's up to you to allocate an object of type <CODE>regex_t</CODE> and pass its
address to <CODE>regcomp</CODE>.
<P>
The argument <VAR>cflags</VAR> lets you specify various options that control
the syntax and semantics of regular expressions.  See section <A HREF="library_9.html#SEC98" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_9.html#SEC98">Flags for POSIX Regular Expressions</A>.
<P>
If you use the flag <CODE>REG_NOSUB</CODE>, then <CODE>regcomp</CODE> omits from
the compiled regular expression the information necessary to record
how subexpressions actually match.  In this case, you might as well
pass <CODE>0</CODE> for the <VAR>matchptr</VAR> and <VAR>nmatch</VAR> arguments when
you call <CODE>regexec</CODE>.
<P>
If you don't use <CODE>REG_NOSUB</CODE>, then the compiled regular expression
does have the capacity to record how subexpressions match.  Also,
<CODE>regcomp</CODE> tells you how many subexpressions <VAR>pattern</VAR> has, by
storing the number in <CODE><VAR>compiled</VAR>-&#62;re_nsub</CODE>.  You can use that
value to decide how long an array to allocate to hold information about
subexpression matches.
<P>
<CODE>regcomp</CODE> returns <CODE>0</CODE> if it succeeds in compiling the regular
expression; otherwise, it returns a nonzero error code (see the table
below).  You can use <CODE>regerror</CODE> to produce an error message string
describing the reason for a nonzero value; see section <A HREF="library_9.html#SEC102" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_9.html#SEC102">POSIX Regexp Matching Cleanup</A>.
<P>
Here are the possible nonzero values that <CODE>regcomp</CODE> can return:
<P>
<DL COMPACT>
<DT><CODE>REG_BADBR</CODE>
<DD>There was an invalid <SAMP>`\{...\}'</SAMP> construct in the regular
expression.  A valid <SAMP>`\{...\}'</SAMP> construct must contain either
a single number, or two numbers in increasing order separated by a
comma.
<P>
<DT><CODE>REG_BADPAT</CODE>
<DD>There was a syntax error in the regular expression.
<P>
<DT><CODE>REG_BADRPT</CODE>
<DD>A repetition operator such as <SAMP>`?'</SAMP> or <SAMP>`*'</SAMP> appeared in a bad
position (with no preceding subexpression to act on).
<P>
<DT><CODE>REG_ECOLLATE</CODE>
<DD>The regular expression referred to an invalid collating element (one not
defined in the current locale for string collation).  See section <A HREF="library_7.html#SEC79" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_7.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>REG_ECTYPE</CODE>
<DD>The regular expression referred to an invalid character class name.
<P>
<DT><CODE>REG_EESCAPE</CODE>
<DD>The regular expression ended with <SAMP>`\'</SAMP>.
<P>
<DT><CODE>REG_ESUBREG</CODE>
<DD>There was an invalid number in the <SAMP>`\<VAR>digit</VAR>'</SAMP> construct.
<P>
<DT><CODE>REG_EBRACK</CODE>
<DD>There were unbalanced square brackets in the regular expression.
<P>
<DT><CODE>REG_EPAREN</CODE>
<DD>An extended regular expression had unbalanced parentheses,
or a basic regular expression had unbalanced <SAMP>`\('</SAMP> and <SAMP>`\)'</SAMP>.
<P>
<DT><CODE>REG_EBRACE</CODE>
<DD>The regular expression had unbalanced <SAMP>`\{'</SAMP> and <SAMP>`\}'</SAMP>.
<P>
<DT><CODE>REG_ERANGE</CODE>
<DD>One of the endpoints in a range expression was invalid.
<P>
<DT><CODE>REG_ESPACE</CODE>
<DD><CODE>regcomp</CODE> or <CODE>regexec</CODE> ran out of memory.
</DL>
<P>
<H3><A NAME="SEC98" HREF="library_toc.html#SEC98" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC98">Flags for POSIX Regular Expressions</A></H3>
<P>
These are the bit flags that you can use in the <VAR>cflags</VAR> operand when
compiling a regular expression with <CODE>regcomp</CODE>.
 
<DL COMPACT>
<DT><CODE>REG_EXTENDED</CODE>
<DD>Treat the pattern as an extended regular expression, rather than as a
basic regular expression.
<P>
<DT><CODE>REG_ICASE</CODE>
<DD>Ignore case when matching letters.
<P>
<DT><CODE>REG_NOSUB</CODE>
<DD>Don't bother storing the contents of the <VAR>matches_ptr</VAR> array.
<P>
<DT><CODE>REG_NEWLINE</CODE>
<DD>Treat a newline in <VAR>string</VAR> as dividing <VAR>string</VAR> into multiple
lines, so that <SAMP>`$'</SAMP> can match before the newline and <SAMP>`^'</SAMP> can
match after.  Also, don't permit <SAMP>`.'</SAMP> to match a newline, and don't
permit <SAMP>`[^...]'</SAMP> to match a newline.
<P>
Otherwise, newline acts like any other ordinary character.
</DL>
<P>
<H3><A NAME="SEC99" HREF="library_toc.html#SEC99" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC99">Matching a Compiled POSIX Regular Expression</A></H3>
<P>
Once you have compiled a regular expression, as described in section <A HREF="library_9.html#SEC97" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_9.html#SEC97">POSIX Regular Expression Compilation</A>, you can match it against strings using
<CODE>regexec</CODE>.  A match anywhere inside the string counts as success,
unless the regular expression contains anchor characters (<SAMP>`^'</SAMP> or
<SAMP>`$'</SAMP>).
<P>
<A NAME="IDX401"></A>
<U>Function:</U> int <B>regexec</B> <I>(regex_t *<VAR>compiled</VAR>, char *<VAR>string</VAR>, size_t <VAR>nmatch</VAR>, regmatch_t <VAR>matchptr</VAR> <TT>[]</TT>, int <VAR>eflags</VAR>)</I><P>
This function tries to match the compiled regular expression
<CODE>*<VAR>compiled</VAR></CODE> against <VAR>string</VAR>.
<P>
<CODE>regexec</CODE> returns <CODE>0</CODE> if the regular expression matches;
otherwise, it returns a nonzero value.  See the table below for
what nonzero values mean.  You can use <CODE>regerror</CODE> to produce an
error message string describing the reason for a nonzero value; 
see section <A HREF="library_9.html#SEC102" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_9.html#SEC102">POSIX Regexp Matching Cleanup</A>.
<P>
The argument <VAR>eflags</VAR> is a word of bit flags that enable various
options.
<P>
If you want to get information about what part of <VAR>string</VAR> actually
matched the regular expression or its subexpressions, use the arguments
<VAR>matchptr</VAR> and <VAR>nmatch</VAR>.  Otherwise, pass <CODE>0</CODE> for 
<VAR>nmatch</VAR>, and <CODE>NULL</CODE> for <VAR>matchptr</VAR>.  See section <A HREF="library_9.html#SEC100" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_9.html#SEC100">Subexpressions Match Results</A>.
<P>
You must match the regular expression with the same set of current
locales that were in effect when you compiled the regular expression.
<P>
The function <CODE>regexec</CODE> accepts the following flags in the
<VAR>eflags</VAR> argument:
<P>
<DL COMPACT>
<DT><CODE>REG_NOTBOL</CODE>
<DD>Do not regard the beginning of the specified string as the beginning of
a line; more generally, don't make any assumptions about what text might
precede it.
<P>
<DT><CODE>REG_NOTEOL</CODE>
<DD>Do not regard the end of the specified string as the end of a line; more
generally, don't make any assumptions about what text might follow it.
</DL>
<P>
Here are the possible nonzero values that <CODE>regexec</CODE> can return:
<P>
<DL COMPACT>
<DT><CODE>REG_NOMATCH</CODE>
<DD>The pattern didn't match the string.  This isn't really an error.
<P>
<DT><CODE>REG_ESPACE</CODE>
<DD><CODE>regcomp</CODE> or <CODE>regexec</CODE> ran out of memory.
</DL>
<P>
<H3><A NAME="SEC100" HREF="library_toc.html#SEC100" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC100">Subexpressions Match Results</A></H3>
<P>
When <CODE>regexec</CODE> matches parenthetical subexpressions of
<VAR>pattern</VAR>, it records which parts of <VAR>string</VAR> they match.  It
returns that information by storing the offsets into an array whose
elements are structures of type <CODE>regmatch_t</CODE>.  The first element of
the array records the part of the string that matched the entire regular
expression.  Each other element of the array records the beginning and
end of the part that matched a single parenthetical subexpression.
<P>
<A NAME="IDX402"></A>
<U>Data Type:</U> <B>regmatch_t</B><P>
This is the data type of the <VAR>matcharray</VAR> array that you pass to
<CODE>regexec</CODE>.  It containes two structure fields, as follows:
<P>
<DL COMPACT>
<DT><CODE>rm_so</CODE>
<DD>The offset in <VAR>string</VAR> of the beginning of a substring.  Add this
value to <VAR>string</VAR> to get the address of that part.
<P>
<DT><CODE>rm_eo</CODE>
<DD>The offset in <VAR>string</VAR> of the end of the substring.
</DL>
<P>
<A NAME="IDX403"></A>
<U>Data Type:</U> <B>regoff_t</B><P>
<CODE>regoff_t</CODE> is an alias for another signed integer type.
The fields of <CODE>regmatch_t</CODE> have type <CODE>regoff_t</CODE>.
<P>
The <CODE>regmatch_t</CODE> elements correspond to subexpressions
positionally; the first element records where the first subexpression
matched, the second element records the second subexpression, and so on.
The order of the subexpressions is the order in which they begin.
<P>
When you call <CODE>regexec</CODE>, you specify how long the <VAR>matchptr</VAR>
array is, with the <VAR>nmatch</VAR> argument.  This tells <CODE>regexec</CODE> how
many elements to store.  If the actual regular expression has more than
<VAR>nmatch</VAR> subexpressions, then you won't get offset information about
the rest of them.  But this doesn't alter whether the pattern matches a
particular string or not.
<P>
If you don't want <CODE>regexec</CODE> to return any information about where
the subexpressions matched, you can either supply <CODE>0</CODE> for
<VAR>nmatch</VAR>, or use the flag <CODE>REG_NOSUB</CODE> when you compile the
pattern with <CODE>regcomp</CODE>.
<P>
<H3><A NAME="SEC101" HREF="library_toc.html#SEC101" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC101">Complications in Subexpression Matching</A></H3>
<P>
Sometimes a subexpression matches a substring of no characters.  This
happens when <SAMP>`f\(o*\)'</SAMP> matches the string <SAMP>`fum'</SAMP>.  (It really
matches just the <SAMP>`f'</SAMP>.)  In this case, both of the offsets identify
the point in the string where the null substring was found.  In this
example, the offsets are both <CODE>1</CODE>.
<P>
Sometimes the entire regular expression can match without using some of
its subexpressions at all--for example, when <SAMP>`ba\(na\)*'</SAMP> matches the
string <SAMP>`ba'</SAMP>, the parenthetical subexpression is not used.  When
this happens, <CODE>regexec</CODE> stores <CODE>-1</CODE> in both fields of the
element for that subexpression.
<P>
Sometimes matching the entire regular expression can match a particular
subexpression more than once--for example, when <SAMP>`ba\(na\)*'</SAMP>
matches the string <SAMP>`bananana'</SAMP>, the parenthetical subexpression
matches three times.  When this happens, <CODE>regexec</CODE> usually stores
the offsets of the last part of the string that matched the
subexpression.  In the case of <SAMP>`bananana'</SAMP>, these offsets are
<CODE>6</CODE> and <CODE>8</CODE>.
<P>
But the last match is not always the one that is chosen.  It's more
accurate to say that the last <EM>opportunity</EM> to match is the one
that takes precedence.  What this means is that when one subexpression
appears within another, then the results reported for the inner
subexpression reflect whatever happened on the last match of the outer
subexpression.  For an example, consider <SAMP>`\(ba\(na\)*s \)'</SAMP> matching
the string <SAMP>`bananas bas '</SAMP>.  The last time the inner expression
actually matches is near the end of the first word.  But it is 
<EM>considered</EM> again in the second word, and fails to match there.
<CODE>regexec</CODE> reports nonuse of the "na" subexpression.
<P>
Another place where this rule applies is when <SAMP>`\(ba\(na\)*s
\|nefer\(ti\)* \)*'</SAMP> matches <SAMP>`bananas nefertiti'</SAMP>.  The "na"
subexpression does match in the first word, but it doesn't match in the
second word because the other alternative is used there.  Once again,
the second repetition of the outer subexpression overrides the first,
and within that second repetition, the "na" subexpression is not used.
So <CODE>regexec</CODE> reports nonuse of the "na" subexpression.
<P>
<H3><A NAME="SEC102" HREF="library_toc.html#SEC102" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC102">POSIX Regexp Matching Cleanup</A></H3>
<P>
When you are finished using a compiled regular expression, you can
free the storage it uses by calling <CODE>regfree</CODE>.
<P>
<A NAME="IDX404"></A>
<U>Function:</U> void <B>regfree</B> <I>(regex_t *<VAR>compiled</VAR>)</I><P>
Calling <CODE>regfree</CODE> frees all the storage that <CODE>*<VAR>compiled</VAR></CODE>
points to.  This includes various internal fields of the <CODE>regex_t</CODE>
structure that aren't documented in this manual.
<P>
<CODE>regfree</CODE> does not free the object <CODE>*<VAR>compiled</VAR></CODE> itself.
<P>
You should always free the space in a <CODE>regex_t</CODE> structure with
<CODE>regfree</CODE> before using the structure to compile another regular
expression.
<P>
When <CODE>regcomp</CODE> or <CODE>regexec</CODE> reports an error, you can use
the function <CODE>regerror</CODE> to turn it into an error message string.
<P>
<A NAME="IDX405"></A>
<U>Function:</U> size_t <B>regerror</B> <I>(int <VAR>errcode</VAR>, regex_t *<VAR>compiled</VAR>, char *<VAR>buffer</VAR>, size_t <VAR>length</VAR>)</I><P>
This function produces an error message string for the error code
<VAR>errcode</VAR>, and stores the string in <VAR>length</VAR> bytes of memory
starting at <VAR>buffer</VAR>.  For the <VAR>compiled</VAR> argument, supply the
same compiled regular expression structure that <CODE>regcomp</CODE> or
<CODE>regexec</CODE> was working with when it got the error.  Alternatively,
you can supply <CODE>NULL</CODE> for <VAR>compiled</VAR>; you will still get a
meaningful error message, but it might not be as detailed.
<P>
If the error message can't fit in <VAR>length</VAR> bytes (including a
terminating null character), then <CODE>regerror</CODE> truncates it.
The string that <CODE>regerror</CODE> stores is always null-terminated
even if it has been truncated.
<P>
The return value of <CODE>regerror</CODE> is the minimum length needed to
store the entire error message.  If this is less than <VAR>length</VAR>, then
the error message was not truncated, and you can use it.  Otherwise, you
should call <CODE>regerror</CODE> again with a larger buffer.
<P>
<PRE>
char *get_regerror (int errcode, regex_t *compiled)
{
  size_t length = regerror (errcode, compiled, NULL, 0);