the inner command.@item@cindex arithmetic expansion@dfn{Arithmetic expansion}: Constructs such as @samp{$(($x-1))} arereplaced with the result of the arithmetic computation.@end itemize@item@cindex field splitting@dfn{Field splitting}: subdivision of the text into @dfn{words}.@item@cindex wildcard expansion@dfn{Wildcard expansion}: The replacement of a construct such as @samp{*.c}with a list of @samp{.c} file names.  Wildcard expansion applies to anentire word at a time, and replaces that word with 0 or more file namesthat are themselves words.@item@cindex quote removal@cindex removal of quotes@dfn{Quote removal}: The deletion of string-quotes, now that they havedone their job by inhibiting the above transformations when appropriate.@end enumerateFor the details of these transformations, and how to write the constructsthat use them, see @w{@cite{The BASH Manual}} (to appear).@node Calling Wordexp@subsection Calling @code{wordexp}All the functions, constants and data types for word expansion aredeclared in the header file @file{wordexp.h}.Word expansion produces a vector of words (strings).  To return thisvector, @code{wordexp} uses a special data type, @code{wordexp_t}, whichis a structure.  You pass @code{wordexp} the address of the structure,and it fills in the structure's fields to tell you about the results.@comment wordexp.h@comment POSIX.2@deftp {Data Type} {wordexp_t}This data type holds a pointer to a word vector.  More precisely, itrecords both the address of the word vector and its size.@table @code@item we_wordcThe number of elements in the vector.@item we_wordvThe address of the vector.  This field has type @w{@code{char **}}.@item we_offsThe offset of the first real element of the vector, from its nominaladdress in the @code{we_wordv} field.  Unlike the other fields, thisis always an input to @code{wordexp}, rather than an output from it.If you use a nonzero offset, then that many elements at the beginning ofthe vector are left empty.  (The @code{wordexp} function fills them withnull pointers.)The @code{we_offs} field is meaningful only if you use the@code{WRDE_DOOFFS} flag.  Otherwise, the offset is always zeroregardless of what is in this field, and the first real element comes atthe beginning of the vector.@end table@end deftp@comment wordexp.h@comment POSIX.2@deftypefun int wordexp (const char *@var{words}, wordexp_t *@var{word-vector-ptr}, int @var{flags})Perform word expansion on the string @var{words}, putting the result ina newly allocated vector, and store the size and address of this vectorinto @code{*@var{word-vector-ptr}}.  The argument @var{flags} is acombination of bit flags; see @ref{Flags for Wordexp}, for details ofthe flags.You shouldn't use any of the characters @samp{|&;<>} in the string@var{words} unless they are quoted; likewise for newline.  If you usethese characters unquoted, you will get the @code{WRDE_BADCHAR} errorcode.  Don't use parentheses or braces unless they are quoted or part ofa word expansion construct.  If you use quotation characters @samp{'"`},they should come in pairs that balance.The results of word expansion are a sequence of words.  The function@code{wordexp} allocates a string for each resulting word, thenallocates a vector of type @code{char **} to store the addresses ofthese strings.  The last element of the vector is a null pointer.This vector is called the @dfn{word vector}.To return this vector, @code{wordexp} stores both its address and itslength (number of elements, not counting the terminating null pointer)into @code{*@var{word-vector-ptr}}.If @code{wordexp} succeeds, it returns 0.  Otherwise, it returns oneof these error codes:@table @code@comment wordexp.h@comment POSIX.2@item WRDE_BADCHARThe input string @var{words} contains an unquoted invalid character suchas @samp{|}.@comment wordexp.h@comment POSIX.2@item WRDE_BADVALThe input string refers to an undefined shell variable, and you used the flag@code{WRDE_UNDEF} to forbid such references.@comment wordexp.h@comment POSIX.2@item WRDE_CMDSUBThe input string uses command substitution, and you used the flag@code{WRDE_NOCMD} to forbid command substitution.@comment wordexp.h@comment POSIX.2@item WRDE_NOSPACEIt was impossible to allocate memory to hold the result.  In this case,@code{wordexp} can store part of the results---as much as it couldallocate room for.@comment wordexp.h@comment POSIX.2@item WRDE_SYNTAXThere was a syntax error in the input string.  For example, an unmatchedquoting character is a syntax error.@end table@end deftypefun@comment wordexp.h@comment POSIX.2@deftypefun void wordfree (wordexp_t *@var{word-vector-ptr})Free the storage used for the word-strings and vector that@code{*@var{word-vector-ptr}} points to.  This does not free thestructure @code{*@var{word-vector-ptr}} itself---only the otherdata it points to.@end deftypefun@node Flags for Wordexp@subsection Flags for Word ExpansionThis section describes the flags that you can specify in the @var{flags} argument to @code{wordexp}.  Choose the flags you want,and combine them with the C operator @code{|}.@table @code@comment wordexp.h@comment POSIX.2@item WRDE_APPENDAppend the words from this expansion to the vector of words produced byprevious calls to @code{wordexp}.  This way you can effectively expandseveral words as if they were concatenated with spaces between them.In order for appending to work, you must not modify the contents of theword vector structure between calls to @code{wordexp}.  And, if you set@code{WRDE_DOOFFS} in the first call to @code{wordexp}, you must alsoset it when you append to the results.@comment wordexp.h@comment POSIX.2@item WRDE_DOOFFSLeave blank slots at the beginning of the vector of words.The @code{we_offs} field says how many slots to leave.The blank slots contain null pointers.@comment wordexp.h@comment POSIX.2@item WRDE_NOCMDDon't do command substitution; if the input requests command substitution,report an error.@comment wordexp.h@comment POSIX.2@item WRDE_REUSEReuse a word vector made by a previous call to @code{wordexp}.Instead of allocating a new vector of words, this call to @code{wordexp}will use the vector that already exists (making it larger if necessary).Note that the vector may move, so it is not safe to save an old pointerand use it again after calling @code{wordexp}.  You must fetch@code{we_pathv} anew after each call.@comment wordexp.h@comment POSIX.2@item WRDE_SHOWERRDo show any error messages printed by commands run by command substitution.More precisely, allow these commands to inherit the standard error outputstream of the current process.  By default, @code{wordexp} gives thesecommands a standard error stream that discards all output.@comment wordexp.h@comment POSIX.2@item WRDE_UNDEFIf the input refers to a shell variable that is not defined, report anerror.@end table@node Wordexp Example@subsection @code{wordexp} ExampleHere is an example of using @code{wordexp} to expand several stringsand use the results to run a shell command.  It also shows the use of@code{WRDE_APPEND} to concatenate the expansions and of @code{wordfree}to free the space allocated by @code{wordexp}.@smallexampleintexpand_and_execute (const char *program, const char *options)@{  wordexp_t result;  pid_t pid  int status, i;  /* @r{Expand the string for the program to run.}  */  switch (wordexp (program, &result, 0))    @{    case 0:			/* @r{Successful}.  */      break;    case WRDE_NOSPACE:      /* @r{If the error was @code{WRDE_NOSPACE},}         @r{then perhaps part of the result was allocated.}  */      wordfree (&result);    default:                    /* @r{Some other error.}  */      return -1;    @}  /* @r{Expand the strings specified for the arguments.}  */  for (i = 0; args[i]; i++)    @{      if (wordexp (options, &result, WRDE_APPEND))        @{          wordfree (&result);          return -1;        @}    @}  pid = fork ();  if (pid == 0)    @{      /* @r{This is the child process.  Execute the command.} */      execv (result.we_wordv[0], result.we_wordv);      exit (EXIT_FAILURE);    @}  else if (pid < 0)    /* @r{The fork failed.  Report failure.}  */    status = -1;  else    /* @r{This is the parent process.  Wait for the child to complete.}  */    if (waitpid (pid, &status, 0) != pid)      status = -1;  wordfree (&result);  return status;@}@end smallexampleIn practice, since @code{wordexp} is executed by running a subshell, itwould be faster to do this by concatenating the strings with spacesbetween them and running that as a shell command using @samp{sh -c}.@c No sense finishing this for here.@ignore@node Tilde Expansion@subsection Details of Tilde ExpansionIt's a standard part of shell syntax that you can use @samp{~} at thebeginning of a file name to stand for your own home directory.  Youcan use @samp{~@var{user}} to stand for @var{user}'s home directory.@dfn{Tilde expansion} is the process of converting these abbreviationsto the directory names that they stand for.Tilde expansion applies to the @samp{~} plus all following characters upto whitespace or a slash.  It takes place only at the beginning of aword, and only if none of the characters to be transformed is quoted inany way.Plain @samp{~} uses the value of the environment variable @code{HOME}as the proper home directory name.  @samp{~} followed by a user nameuses @code{getpwname} to look up that user in the user database, anduses whatever directory is recorded there.  Thus, @samp{~} followedby your own name can give different results from plain @samp{~}, ifthe value of @code{HOME} is not really your home directory.@node Variable Substitution@subsection Details of Variable SubstitutionPart of ordinary shell syntax is the use of @samp{$@var{variable}} tosubstitute the value of a shell variable into a command.  This is called@dfn{variable substitution}, and it is one part of doing word expansion.There are two basic ways you can write a variable reference forsubstitution:@table @code@item $@{@var{variable}@}If you write braces around the variable name, then it is completelyunambiguous where the variable name ends.  You can concatenateadditional letters onto the end of the variable value by writing themimmediately after the close brace.  For example, @samp{$@{foo@}s}expands into @samp{tractors}.@item $@var{variable}If you do not put braces around the variable name, then the variablename consists of all the alphanumeric characters and underscores thatfollow the @samp{$}.  The next punctuation character ends the variablename.  Thus, @samp{$foo-bar} refers to the variable @code{foo} and expandsinto @samp{tractor-bar}.@end tableWhen you use braces, you can also use various constructs to modify thevalue that is substituted, or test it in various ways.@table @code@item $@{@var{variable}:-@var{default}@}Substitute the value of @var{variable}, but if that is empty orundefined, use @var{default} instead.@item $@{@var{variable}:=@var{default}@}Substitute the value of @var{variable}, but if that is empty orundefined, use @var{default} instead and set the variable to@var{default}.@item $@{@var{variable}:?@var{message}@}If @var{variable} is defined and not empty, substitute its value.Otherwise, print @var{message} as an error message on the standard errorstream, and consider word expansion a failure.@c ??? How does wordexp report such an error?@item $@{@var{variable}:+@var{replacement}@}Substitute @var{replacement}, but only if @var{variable} is defined andnonempty.  Otherwise, substitute nothing for this construct.@end table@table @code@item $@{#@var{variable}@}Substitute a numeral which expresses in base ten the number ofcharacters in the value of @var{variable}.  @samp{$@{#foo@}} stands for@samp{7}, because @samp{tractor} is seven characters.@end tableThese variants of variable substitution let you remove part of thevariable's value before substituting it.  The @var{prefix} and @var{suffix} are not mere strings; they are wildcard patterns, justlike the patterns that you use to match multiple file names.  Butin this context, they match against parts of the variable valuerather than against file names.@table @code@item $@{@var{variable}%%@var{suffix}@}Substitute the value of @var{variable}, but first discard from thatvariable any portion at the end that matches the pattern @var{suffix}.If there is more than one alternative for how to match against@var{suffix}, this construct uses the longest possible match.Thus, @samp{$@{foo%%r*@}} substitutes @samp{t}, because the largestmatch for @samp{r*} at the end of @samp{tractor} is @samp{ractor}.@item $@{@var{variable}%@var{suffix}@}Substitute the value of @var{variable}, but first discard from thatvariable any portion at the end that matches the pattern @var{suffix}.If there is more than one alternative for how to match against@var{suffix}, this construct uses the shortest possible alternative.Thus, @samp{$@{foo%%r*@}} substitutes @samp{tracto}, because the shortestmatch for @samp{r*} at the end of @samp{tractor} is just @samp{r}.@item $@{@var{variable}##@var{prefix}@}Substitute the value of @var{variable}, but first discard from thatvariable any portion at the beginning that matches the pattern @var{prefix}.If there is more than one alternative for how to match against@var{prefix}, this construct uses the longest possible match.Thus, @samp{$@{foo%%r*@}} substitutes @samp{t}, because the largestmatch for @samp{r*} at the end of @samp{tractor} is @samp{ractor}.@item $@{@var{variable}#@var{prefix}@}Substitute the value of @var{variable}, but first discard from thatvariable any portion at the beginning that matches the pattern @var{prefix}.If there is more than one alternative for how to match against@var{prefix}, this construct uses the shortest possible alternative.Thus, @samp{$@{foo%%r*@}} substitutes @samp{tracto}, because the shortestmatch for @samp{r*} at the end of @samp{tractor} is just @samp{r}.@end ignore