@code{regcomp} tells you how many subexpressions @var{pattern} has, bystoring the number in @code{@var{compiled}->re_nsub}.  You can use thatvalue to decide how long an array to allocate to hold information aboutsubexpression matches.@code{regcomp} returns @code{0} if it succeeds in compiling the regularexpression; otherwise, it returns a nonzero error code (see the tablebelow).  You can use @code{regerror} to produce an error message stringdescribing the reason for a nonzero value; see @ref{Regexp Cleanup}.@end deftypefunHere are the possible nonzero values that @code{regcomp} can return:@table @code@comment regex.h@comment POSIX.2@item REG_BADBRThere was an invalid @samp{\@{@dots{}\@}} construct in the regularexpression.  A valid @samp{\@{@dots{}\@}} construct must contain eithera single number, or two numbers in increasing order separated by acomma.@comment regex.h@comment POSIX.2@item REG_BADPATThere was a syntax error in the regular expression.@comment regex.h@comment POSIX.2@item REG_BADRPTA repetition operator such as @samp{?} or @samp{*} appeared in a badposition (with no preceding subexpression to act on).@comment regex.h@comment POSIX.2@item REG_ECOLLATEThe regular expression referred to an invalid collating element (one notdefined in the current locale for string collation).  @xref{LocaleCategories}.@comment regex.h@comment POSIX.2@item REG_ECTYPEThe regular expression referred to an invalid character class name.@comment regex.h@comment POSIX.2@item REG_EESCAPEThe regular expression ended with @samp{\}.@comment regex.h@comment POSIX.2@item REG_ESUBREGThere was an invalid number in the @samp{\@var{digit}} construct.@comment regex.h@comment POSIX.2@item REG_EBRACKThere were unbalanced square brackets in the regular expression.@comment regex.h@comment POSIX.2@item REG_EPARENAn extended regular expression had unbalanced parentheses,or a basic regular expression had unbalanced @samp{\(} and @samp{\)}.@comment regex.h@comment POSIX.2@item REG_EBRACEThe regular expression had unbalanced @samp{\@{} and @samp{\@}}.@comment regex.h@comment POSIX.2@item REG_ERANGEOne of the endpoints in a range expression was invalid.@comment regex.h@comment POSIX.2@item REG_ESPACE@code{regcomp} ran out of memory.@end table@node Flags for POSIX Regexps@subsection Flags for POSIX Regular ExpressionsThese are the bit flags that you can use in the @var{cflags} operand whencompiling a regular expression with @code{regcomp}. @table @code@comment regex.h@comment POSIX.2@item REG_EXTENDEDTreat the pattern as an extended regular expression, rather than as abasic regular expression.@comment regex.h@comment POSIX.2@item REG_ICASEIgnore case when matching letters.@comment regex.h@comment POSIX.2@item REG_NOSUBDon't bother storing the contents of the @var{matches-ptr} array.@comment regex.h@comment POSIX.2@item REG_NEWLINETreat a newline in @var{string} as dividing @var{string} into multiplelines, so that @samp{$} can match before the newline and @samp{^} canmatch after.  Also, don't permit @samp{.} to match a newline, and don'tpermit @samp{[^@dots{}]} to match a newline.Otherwise, newline acts like any other ordinary character.@end table@node Matching POSIX Regexps@subsection Matching a Compiled POSIX Regular ExpressionOnce you have compiled a regular expression, as described in @ref{POSIXRegexp Compilation}, you can match it against strings using@code{regexec}.  A match anywhere inside the string counts as success,unless the regular expression contains anchor characters (@samp{^} or@samp{$}).@comment regex.h@comment POSIX.2@deftypefun int regexec (regex_t *@var{compiled}, char *@var{string}, size_t @var{nmatch}, regmatch_t @var{matchptr} @t{[]}, int @var{eflags})This function tries to match the compiled regular expression@code{*@var{compiled}} against @var{string}.@code{regexec} returns @code{0} if the regular expression matches;otherwise, it returns a nonzero value.  See the table below forwhat nonzero values mean.  You can use @code{regerror} to produce anerror message string describing the reason for a nonzero value; see @ref{Regexp Cleanup}.The argument @var{eflags} is a word of bit flags that enable variousoptions.If you want to get information about what part of @var{string} actuallymatched the regular expression or its subexpressions, use the arguments@var{matchptr} and @var{nmatch}.  Otherwise, pass @code{0} for @var{nmatch}, and @code{NULL} for @var{matchptr}.  @xref{RegexpSubexpressions}.@end deftypefunYou must match the regular expression with the same set of currentlocales that were in effect when you compiled the regular expression.The function @code{regexec} accepts the following flags in the@var{eflags} argument:@table @code @comment regex.h@comment POSIX.2@item REG_NOTBOLDo not regard the beginning of the specified string as the beginning ofa line; more generally, don't make any assumptions about what text mightprecede it.@comment regex.h@comment POSIX.2@item REG_NOTEOLDo not regard the end of the specified string as the end of a line; moregenerally, don't make any assumptions about what text might follow it.@end tableHere are the possible nonzero values that @code{regexec} can return:@table @code@comment regex.h@comment POSIX.2@item REG_NOMATCHThe pattern didn't match the string.  This isn't really an error.@comment regex.h@comment POSIX.2@item REG_ESPACE@code{regexec} ran out of memory.@end table@node Regexp Subexpressions@subsection Match Results with SubexpressionsWhen @code{regexec} matches parenthetical subexpressions of@var{pattern}, it records which parts of @var{string} they match.  Itreturns that information by storing the offsets into an array whoseelements are structures of type @code{regmatch_t}.  The first element ofthe array (index @code{0}) records the part of the string that matchedthe entire regular expression.  Each other element of the array recordsthe beginning and end of the part that matched a single parentheticalsubexpression.@comment regex.h@comment POSIX.2@deftp {Data Type} regmatch_tThis is the data type of the @var{matcharray} array that you pass to@code{regexec}.  It containes two structure fields, as follows:@table @code@item rm_soThe offset in @var{string} of the beginning of a substring.  Add thisvalue to @var{string} to get the address of that part.@item rm_eoThe offset in @var{string} of the end of the substring.@end table@end deftp@comment regex.h@comment POSIX.2@deftp {Data Type} regoff_t@code{regoff_t} is an alias for another signed integer type.The fields of @code{regmatch_t} have type @code{regoff_t}.@end deftpThe @code{regmatch_t} elements correspond to subexpressionspositionally; the first element (index @code{1}) records where the firstsubexpression matched, the second element records the secondsubexpression, and so on.  The order of the subexpressions is the orderin which they begin.When you call @code{regexec}, you specify how long the @var{matchptr}array is, with the @var{nmatch} argument.  This tells @code{regexec} howmany elements to store.  If the actual regular expression has more than@var{nmatch} subexpressions, then you won't get offset information aboutthe rest of them.  But this doesn't alter whether the pattern matches aparticular string or not.If you don't want @code{regexec} to return any information about wherethe subexpressions matched, you can either supply @code{0} for@var{nmatch}, or use the flag @code{REG_NOSUB} when you compile thepattern with @code{regcomp}.@node Subexpression Complications@subsection Complications in Subexpression MatchingSometimes a subexpression matches a substring of no characters.  Thishappens when @samp{f\(o*\)} matches the string @samp{fum}.  (It reallymatches just the @samp{f}.)  In this case, both of the offsets identifythe point in the string where the null substring was found.  In thisexample, the offsets are both @code{1}.Sometimes the entire regular expression can match without using some ofits subexpressions at all---for example, when @samp{ba\(na\)*} matches thestring @samp{ba}, the parenthetical subexpression is not used.  Whenthis happens, @code{regexec} stores @code{-1} in both fields of theelement for that subexpression.Sometimes matching the entire regular expression can match a particularsubexpression more than once---for example, when @samp{ba\(na\)*}matches the string @samp{bananana}, the parenthetical subexpressionmatches three times.  When this happens, @code{regexec} usually storesthe offsets of the last part of the string that matched thesubexpression.  In the case of @samp{bananana}, these offsets are@code{6} and @code{8}.But the last match is not always the one that is chosen.  It's moreaccurate to say that the last @emph{opportunity} to match is the onethat takes precedence.  What this means is that when one subexpressionappears within another, then the results reported for the innersubexpression reflect whatever happened on the last match of the outersubexpression.  For an example, consider @samp{\(ba\(na\)*s \)*} matchingthe string @samp{bananas bas }.  The last time the inner expressionactually matches is near the end of the first word.  But it is @emph{considered} again in the second word, and fails to match there.@code{regexec} reports nonuse of the ``na'' subexpression.Another place where this rule applies is when the regular expression@w{@samp{\(ba\(na\)*s \|nefer\(ti\)* \)*}} matches @samp{bananas nefertiti}.The ``na'' subexpression does match in the first word, but it doesn'tmatch in the second word because the other alternative is used there.Once again, the second repetition of the outer subexpression overridesthe first, and within that second repetition, the ``na'' subexpressionis not used.  So @code{regexec} reports nonuse of the ``na''subexpression.@node Regexp Cleanup@subsection POSIX Regexp Matching CleanupWhen you are finished using a compiled regular expression, you canfree the storage it uses by calling @code{regfree}.@comment regex.h@comment POSIX.2@deftypefun void regfree (regex_t *@var{compiled})Calling @code{regfree} frees all the storage that @code{*@var{compiled}}points to.  This includes various internal fields of the @code{regex_t}structure that aren't documented in this manual.@code{regfree} does not free the object @code{*@var{compiled}} itself.@end deftypefunYou should always free the space in a @code{regex_t} structure with@code{regfree} before using the structure to compile another regularexpression.When @code{regcomp} or @code{regexec} reports an error, you can usethe function @code{regerror} to turn it into an error message string.@comment regex.h@comment POSIX.2@deftypefun size_t regerror (int @var{errcode}, regex_t *@var{compiled}, char *@var{buffer}, size_t @var{length})This function produces an error message string for the error code@var{errcode}, and stores the string in @var{length} bytes of memorystarting at @var{buffer}.  For the @var{compiled} argument, supply thesame compiled regular expression structure that @code{regcomp} or@code{regexec} was working with when it got the error.  Alternatively,you can supply @code{NULL} for @var{compiled}; you will still get ameaningful error message, but it might not be as detailed.If the error message can't fit in @var{length} bytes (including aterminating null character), then @code{regerror} truncates it.The string that @code{regerror} stores is always null-terminatedeven if it has been truncated.The return value of @code{regerror} is the minimum length needed tostore the entire error message.  If this is less than @var{length}, thenthe error message was not truncated, and you can use it.  Otherwise, youshould call @code{regerror} again with a larger buffer.Here is a function which uses @code{regerror}, but always dynamicallyallocates a buffer for the error message:@smallexamplechar *get_regerror (int errcode, regex_t *compiled)@{  size_t length = regerror (errcode, compiled, NULL, 0);  char *buffer = xmalloc (length);  (void) regerror (errcode, compiled, buffer, length);  return buffer;@}@end smallexample@end deftypefun@c !!!! this is not actually in the library....@node Word Expansion@section Shell-Style Word Expansion@cindex word expansion@cindex expansion of shell words@dfn{Word expansion} means the process of splitting a string into @dfn{words} and substituting for variables, commands, and wildcardsjust as the shell does.For example, when you write @samp{ls -l foo.c}, this string is splitinto three separate words---@samp{ls}, @samp{-l} and @samp{foo.c}.This is the most basic function of word expansion.When you write @samp{ls *.c}, this can become many words, becausethe word @samp{*.c} can be replaced with any number of file names.This is called @dfn{wildcard expansion}, and it is also a part ofword expansion.When you use @samp{echo $PATH} to print your path, you are takingadvantage of @dfn{variable substitution}, which is also part of wordexpansion.Ordinary programs can perform word expansion just like the shell bycalling the library function @code{wordexp}.@menu* Expansion Stages::	What word expansion does to a string.* Calling Wordexp::	How to call @code{wordexp}.* Flags for Wordexp::   Options you can enable in @code{wordexp}.* Wordexp Example::	A sample program that does word expansion.@end menu@node Expansion Stages@subsection The Stages of Word ExpansionWhen word expansion is applied to a sequence of words, it performs thefollowing transformations in the order shown here:@enumerate@item@cindex tilde expansion@dfn{Tilde expansion}: Replacement of @samp{~foo} with the name ofthe home directory of @samp{foo}.@itemNext, three different transformations are applied in the same step,from left to right:@itemize @bullet@item@cindex variable substitution@cindex substitution of variables and commands@dfn{Variable substitution}: Environment variables are substituted forreferences such as @samp{$foo}.@item@cindex command substitution@dfn{Command substitution}: Constructs such as @w{@samp{`cat foo`}} andthe equivalent @w{@samp{$(cat foo)}} are replaced with the output from