@Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.
Œ

ˆ‰SEC277Št�”›Pattern Matching

@�”˜The GNU C Library provides pattern matching facilities for two kinds of patterns: regular expressions and file-name wildcards. The library also provides a facility for expanding variable and command references and parsing text into words in the way the shell does.
ˆ‰SEC278Št�”›Wildcard Matching

‰IDX1405Š@�”˜This section describes how to match a wildcard pattern against a particular string. The result is a yes or no answer: does the string fit the pattern or not. The symbols described here are all declared in H`fnmatch.h'@.

AFunction:@ int Dfnmatch@ B(const char *Bpattern@, const char *Bstring@, int Bflags@)
Â‰IDX1406Š@�”˜This function tests whether the string Bstring@ matches the pattern Bpattern@. It returns H0@ if they do match; otherwise, it returns the nonzero value HFNM_NOMATCH@. The arguments Bpattern@ and Bstring@ are both strings.
The argument Bflags@ is a combination of flag bits that alter the details of matching. See below for a list of the defined flags.
In the GNU C Library, Hfnmatch@ cannot experience an "error"---it always returns an answer for whether the match succeeds. However, other implementations of Hfnmatch@ might sometimes report "errors". They would do so by returning nonzero values that are not equal to HFNM_NOMATCH@.À

These are the available flags for the Bflags@ argument:
HFNM_FILE_NAME
Â@Treat the H`/'@ character specially, for matching file names. If this flag is set, wildcard constructs in Bpattern@ cannot match H`/'@ in Bstring@. Thus, the only way to match H`/'@ is with an explicit H`/'@ in Bpattern@.
ÀHFNM_PATHNAME
Â@This is an alias for HFNM_FILE_NAME@; it comes from POSIX.2. We don't recommend this name because we don't use the term "pathname" for file names.
ÀHFNM_PERIOD
Â@Treat the H`.'@ character specially if it appears at the beginning of Bstring@. If this flag is set, wildcard constructs in Bpattern@ cannot match H`.'@ as the first character of Bstring@. If you set both HFNM_PERIOD@ and HFNM_FILE_NAME@, then the special treatment applies to H`.'@ following H`/'@ as well as to H`.'@ at the beginning of Bstring@. (The shell uses the HFNM_PERIOD@ and HFNM_FILE_NAME@ flags together for matching file names.)
ÀHFNM_NOESCAPE
Â@Don't treat the H`\'@ character specially in patterns. Normally, H`\'@ quotes the following character, turning off its special meaning (if any) so that it matches only itself. When quoting is enabled, the pattern H`\?'@ matches only the string H`?'@, because the question mark in the pattern acts like an ordinary character. If you use HFNM_NOESCAPE@, then H`\'@ is an ordinary character.
ÀHFNM_LEADING_DIR
Â@Ignore a trailing sequence of characters starting with a H`/'@ in Bstring@; that is to say, test whether Bstring@ starts with a directory name that Bpattern@ matches. If this flag is set, either H`foo*'@ or H`foobar'@ as a pattern would match the string H`foobar/frobozz'@.
ÀHFNM_CASEFOLD
Â@Ignore case in comparing Bstring@ to Bpattern@.À

ˆ‰SEC279Št�”›Globbing

‰IDX1407Š@�”˜The archetypal use of wildcards is for matching against the files in a directory, and making a list of all the matches. This is called Bglobbing@.
You could do this using Hfnmatch@, by reading the directory entries one by one and testing each one with Hfnmatch@. But that would be slow (and complex, since you would have to handle subdirectories by hand).
The library provides a function Hglob@ to make this particular use of wildcards convenient. Hglob@ and the other symbols in this section are declared in H`glob.h'@.
ˆ‰SEC280ŠT�”›Calling \glob

@�”˜The result of globbing is a vector of file names (strings). To return this vector, Hglob@ uses a special data type, Hglob_t@, which is a structure. You pass Hglob@ the address of the structure, and it fills in the structure's fields to tell you about the results.

AData Type:@ Dglob_t
Â‰IDX1408Š@�”˜This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size.
Hgl_pathc
Ä@The number of elements in the vector.
ÂHgl_pathv
Ä@The address of the vector. This field has type Hchar **@.
ÂHgl_offs
Ä@The offset of the first real element of the vector, from its nominal address in the Hgl_pathv@ field. Unlike the other fields, this is always an input to Hglob@, rather than an output from it. If you use a nonzero offset, then that many elements at the beginning of the vector are left empty. (The Hglob@ function fills them with null pointers.) The Hgl_offs@ field is meaningful only if you use the HGLOB_DOOFFS@ flag. Otherwise, the offset is always zero regardless of what is in this field, and the first real element comes at the beginning of the vector.Â
À

AFunction:@ int Dglob@ B(const char *Bpattern@, int Bflags@, int (*Berrfunc@) (const char *Bfilename@, int Berror-code@), glob_t *Bvector-ptr@)
Â‰IDX1409Š@�”˜The function Hglob@ does globbing using the pattern Bpattern@ in the current directory. It puts the result in a newly allocated vector, and stores the size and address of this vector into H*Jvector-ptr@. The argument Bflags@ is a combination of bit flags; see section ‰ŠP�”›Flags for Globbing@�”˜, for details of the flags.
The result of globbing is a sequence of file names. The function Hglob@ allocates a string for each resulting word, then allocates a vector of type Hchar **@ to store the addresses of these strings. The last element of the vector is a null pointer. This vector is called the Bword vector@.
To return this vector, Hglob@ stores both its address and its length (number of elements, not counting the terminating null pointer) into H*Jvector-ptr@.
Normally, Hglob@ sorts the file names alphabetically before returning them. You can turn this off with the flag HGLOB_NOSORT@ if you want to get the information as fast as possible. Usually it's a good idea to let Hglob@ sort them--if you process the files in alphabetical order, the users will have a feel for the rate of progress that your application is making.
If Hglob@ succeeds, it returns 0. Otherwise, it returns one of these error codes:
HGLOB_ABORTED
Ä@There was an error opening a directory, and you used the flag HGLOB_ERR@ or your specified Berrfunc@ returned a nonzero value. See below for an explanation of the HGLOB_ERR@ flag and Berrfunc@.
ÂHGLOB_NOMATCH
Ä@The pattern didn't match any existing files. If you use the HGLOB_NOCHECK@ flag, then you never get this error code, because that flag tells Hglob@ to Bpretend@ that the pattern matched at least one file.
ÂHGLOB_NOSPACE
Ä@It was impossible to allocate memory to hold the result.Â

In the event of an error, Hglob@ stores information in H*Jvector-ptr@ about all the matches it has found so far.À

ˆ‰SEC281ŠT�”›Flags for Globbing

@�”˜This section describes the flags that you can specify in the Bflags@ argument to Hglob@. Choose the flags you want, and combine them with the C bitwise OR operator H|@.
HGLOB_APPEND
Â@Append the words from this expansion to the vector of words produced by previous calls to Hglob@. This way you can effectively expand several words as if they were concatenated with spaces between them. In order for appending to work, you must not modify the contents of the word vector structure between calls to Hglob@. And, if you set HGLOB_DOOFFS@ in the first call to Hglob@, you must also set it when you append to the results. Note that the pointer stored in Hgl_pathv@ may no longer be valid after you call Hglob@ the second time, because Hglob@ might have relocated the vector. So always fetch Hgl_pathv@ from the Hglob_t@ structure after each Hglob@ call; Dnever@ save the pointer across calls.
ÀHGLOB_DOOFFS
Â@Leave blank slots at the beginning of the vector of words. The Hgl_offs@ field says how many slots to leave. The blank slots contain null pointers.
ÀHGLOB_ERR
Â@Give up right away and report an error if there is any difficulty reading the directories that must be read in order to expand Bpattern@ fully. Such difficulties might include a directory in which you don't have the requisite access. Normally, Hglob@ tries its best to keep on going despite any errors, reading whatever directories it can. You can exercise even more control than this by specifying an error-handler function Berrfunc@ when you call Hglob@. If Berrfunc@ is not a null pointer, then Hglob@ doesn't give up right away when it can't read a directory; instead, it calls Berrfunc@ with two arguments, like this: (*Berrfunc@) (Bfilename@, Berror-code@) The argument Bfilename@ is the name of the directory that Hglob@ couldn't open or couldn't read, and Berror-code@ is the Herrno@ value that was reported to Hglob@. If the error handler function returns nonzero, then Hglob@ gives up right away. Otherwise, it continues.
ÀHGLOB_MARK
Â@If the pattern matches the name of a directory, append H`/'@ to the directory's name when returning it.
ÀHGLOB_NOCHECK
Â@If the pattern doesn't match any file names, return the pattern itself as if it were a file name that had been matched. (Normally, when the pattern doesn't match anything, Hglob@ returns that there were no matches.)
ÀHGLOB_NOSORT
Â@Don't sort the file names; return them in no particular order. (In practice, the order will depend on the order of the entries in the directory.) The only reason Bnot@ to sort is to save time.
ÀHGLOB_NOESCAPE
Â@Don't treat the H`\'@ character specially in patterns. Normally, H`\'@ quotes the following character, turning off its special meaning (if any) so that it matches only itself. When quoting is enabled, the pattern H`\?'@ matches only the string H`?'@, because the question mark in the pattern acts like an ordinary character. If you use HGLOB_NOESCAPE@, then H`\'@ is an ordinary character. Hglob@ does its work by calling the function Hfnmatch@ repeatedly. It handles the flag HGLOB_NOESCAPE@ by turning on the HFNM_NOESCAPE@ flag in calls to Hfnmatch@.À

ˆ‰SEC282Št�”›Regular Expression Matching

@�”˜The GNU C library supports two interfaces for matching regular expressions. One is the standard POSIX.2 interface, and the other is what the GNU system has had for many years.
Both interfaces are declared in the header file H`regex.h'@. If you define H_POSIX_C_SOURCE@, then only the POSIX.2 functions, structures, and constants are declared.
ˆ‰SEC283ŠT�”›POSIX Regular Expression Compilation

@�”˜Before you can actually match a regular expression, you must Bcompile@ 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 ‰ŠP�”›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:

AData Type:@ Dregex_t
Â‰IDX1410Š@�”˜This type of object holds a compiled regular expression. It is actually a structure. It has just one field that your programs should look at:
Hre_nsub
Ä@This field holds the number of parenthetical subexpressions in the regular expression that was compiled.Â

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 Hregex_t@ object, you can compile a regular expression into it by calling Hregcomp@.

AFunction:@ int Dregcomp@ B(regex_t *Bcompiled@, const char *Bpattern@, int Bcflags@)
Â‰IDX1411Š@�”˜The function Hregcomp@ "compiles" a regular expression into a data structure that you can use with Hregexec@ to match against a string. The compiled regular expression format is designed for efficient matching. Hregcomp@ stores it into H*Jcompiled@.
It's up to you to allocate an object of type Hregex_t@ and pass its address to Hregcomp@.
The argument Bcflags@ lets you specify various options that control the syntax and semantics of regular expressions. See section ‰ŠP�”›Flags for POSIX Regular Expressions@�”˜.
If you use the flag HREG_NOSUB@, then Hregcomp@ omits from the compiled regular expression the information necessary to record how subexpressions actually match. In this case, you might as well pass H0@ for the Bmatchptr@ and Bnmatch@ arguments when you call Hregexec@.
If you don't use HREG_NOSUB@, then the compiled regular expression does have the capacity to record how subexpressions match. Also, Hregcomp@ tells you how many subexpressions Bpattern@ has, by storing the number in JcompiledH->re_nsub@. You can use that value to decide how long an array to allocate to hold information about subexpression matches.
Hregcomp@ returns H0@ if it succeeds in compiling the regular expression; otherwise, it returns a nonzero error code (see the table below). You can use Hregerror@ to produce an error message string describing the reason for a nonzero value; see section ‰ŠP�”›POSIX Regexp Matching Cleanup@�”˜. À

Here are the possible nonzero values that Hregcomp@ can return:
HREG_BADBR
Â@There was an invalid H`\{...\}'@ construct in the regular expression. A valid H`\{...\}'@ construct must contain either a single number, or two numbers in increasing order separated by a comma.
ÀHREG_BADPAT
Â@There was a syntax error in the regular expression.
ÀHREG_BADRPT
Â@A repetition operator such as H`?'@ or H`*'@ appeared in a bad position (with no preceding subexpression to act on).
ÀHREG_ECOLLATE
Â@The regular expression referred to an invalid collating element (one not defined in the current locale for string collation). See section ‰ŠP�”›Categories of Activities that Locales Affect@�”˜.
ÀHREG_ECTYPE
Â@The regular expression referred to an invalid character class name.
ÀHREG_EESCAPE
Â@The regular expression ended with H`\'@.
ÀHREG_ESUBREG
Â@There was an invalid number in the H`\JdigitH'@ construct.
ÀHREG_EBRACK
Â@There were unbalanced square brackets in the regular expression.
ÀHREG_EPAREN
Â@An extended regular expression had unbalanced parentheses, or a basic regular expression had unbalanced H`\('@ and H`\)'@.
ÀHREG_EBRACE
Â@The regular expression had unbalanced H`\{'@ and H`\}'@.
ÀHREG_ERANGE
Â@One of the endpoints in a range expression was invalid.
ÀHREG_ESPACE
ÂHregcomp@ ran out of memory.À

ˆ‰SEC284ŠT�”›Flags for POSIX Regular Expressions

@�”˜These are the bit flags that you can use in the Bcflags@ operand when compiling a regular expression with Hregcomp@.
HREG_EXTENDED
Â@Treat the pattern as an extended regular expression, rather than as a basic regular expression.
ÀHREG_ICASE
Â@Ignore case when matching letters.
ÀHREG_NOSUB
Â@Don't bother storing the contents of the Bmatches-ptr@ array.
ÀHREG_NEWLINE
Â@Treat a newline in Bstring@ as dividing Bstring@ into multiple lines, so that H`$'@ can match before the newline and H`^'@ can match after. Also, don't permit H`.'@ to match a newline, and don't permit H`[^...]'@ to match a newline. Otherwise, newline acts like any other ordinary character.À

ˆ‰SEC285ŠT�”›Matching a Compiled POSIX Regular Expression

@�”˜Once you have compiled a regular expression, as described in section ‰ŠP�”›POSIX Regular Expression Compilation@�”˜, you can match it against strings using Hregexec@. A match anywhere inside the string counts as success, unless the regular expression contains anchor characters (H`^'@ or H`$'@).

AFunction:@ int Dregexec@ B(regex_t *Bcompiled@, char *Bstring@, size_t Bnmatch@, regmatch_t Bmatchptr@ H[]@, int Beflags@)
Â‰IDX1412Š@�”˜This function tries to match the compiled regular expression H*Jcompiled@ against Bstring@.
Hregexec@ returns H0@ if the regular expression matches; otherwise, it returns a nonzero value. See the table below for what nonzero values mean. You can use Hregerror@ to produce an error message string describing the reason for a nonzero value; see section ‰ŠP�”›POSIX Regexp Matching Cleanup@�”˜.
The argument Beflags@ is a word of bit flags that enable various options.
If you want to get information about what part of Bstring@ actually matched the regular expression or its subexpressions, use the arguments Bmatchptr@ and Bnmatch@. Otherwise, pass H0@ for Bnmatch@, and HNULL@ for Bmatchptr@. See section ‰ŠP�”›Match Results with Subexpressions@�”˜.À

You must match the regular expression with the same set of current locales that were in effect when you compiled the regular expression.
The function Hregexec@ accepts the following flags in the Beflags@ argument:
HREG_NOTBOL
Â@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.
ÀHREG_NOTEOL
Â@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.À

Here are the possible nonzero values that Hregexec@ can return:
HREG_NOMATCH
Â@The pattern didn't match the string. This isn't really an error.
ÀHREG_ESPACE
ÂHregexec@ ran out of memory.À

ˆ‰SEC286ŠT�”›Match Results with Subexpressions

@�”˜When Hregexec@ matches parenthetical subexpressions of Bpattern@, it records which parts of Bstring@ they match. It returns that information by storing the offsets into an array whose elements are structures of type Hregmatch_t@. The first element of the array (index H0@) 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.

AData Type:@ Dregmatch_t
Â‰IDX1413Š@�”˜This is the data type of the Bmatcharray@ array that you pass to Hregexec@. It contains two structure fields, as follows:
Hrm_so
Ä@The offset in Bstring@ of the beginning of a substring. Add this value to Bstring@ to get the address of that part.
ÂHrm_eo
Ä@The offset in Bstring@ of the end of the substring.Â
À

AData Type:@ Dregoff_t
Â‰IDX1414ŠH�”˜regoff_t@ is an alias for another signed integer type. The fields of Hregmatch_t@ have type Hregoff_t@.À

The Hregmatch_t@ elements correspond to subexpressions positionally; the first element (index H1@) 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.
When you call Hregexec@, you specify how long the Bmatchptr@ array is, with the Bnmatch@ argument. This tells Hregexec@ how many elements to store. If the actual regular expression has more than Bnmatch@ 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.
If you don't want Hregexec@ to return any information about where the subexpressions matched, you can either supply H0@ for Bnmatch@, or use the flag HREG_NOSUB@ when you compile the pattern with Hregcomp@.
ˆ‰SEC287ŠT�”›Complications in Subexpression Matching

@�”˜Sometimes a subexpression matches a substring of no characters. This happens when H`f\(o*\)'@ matches the string H`fum'@. (It really matches just the H`f'@.) 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 H1@.
Sometimes the entire regular expression can match without using some of its subexpressions at all--for example, when H`ba\(na\)*'@ matches the string H`ba'@, the parenthetical subexpression is not used. When this happens, Hregexec@ stores H-1@ in both fields of the element for that subexpression.
Sometimes matching the entire regular expression can match a particular subexpression more than once--for example, when H`ba\(na\)*'@ matches the string H`bananana'@, the parenthetical subexpression matches three times. When this happens, Hregexec@ usually stores the offsets of the last part of the string that matched the subexpression. In the case of H`bananana'@, these offsets are H6@ and H8@.
But the last match is not always the one that is chosen. It's more accurate to say that the last Bopportunity@ 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 H`\(ba\(na\)*s \)*'@ matching the string H`bananas bas '@. The last time the inner expression actually matches is near the end of the first word. But it is Bconsidered@ again in the second word, and fails to match there. Hregexec@ reports nonuse of the "na" subexpression.
Another place where this rule applies is when the regular expression H`\(ba\(na\)*s \|nefer\(ti\)* \)*'@ matches H`bananas nefertiti'@. 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 Hregexec@ reports nonuse of the "na" subexpression.
ˆ‰SEC288ŠT�”›POSIX Regexp Matching Cleanup

@�”˜When you are finished using a compiled regular expression, you can free the storage it uses by calling Hregfree@.

AFunction:@ void Dregfree@ B(regex_t *Bcompiled@)
Â‰IDX1415Š@�”˜Calling Hregfree@ frees all the storage that H*Jcompiled@ points to. This includes various internal fields of the Hregex_t@ structure that aren't documented in this manual.
Hregfree@ does not free the object H*Jcompiled@ itself.À

You should always free the space in a Hregex_t@ structure with Hregfree@ before using the structure to compile another regular expression.
When Hregcomp@ or Hregexec@ reports an error, you can use the function Hregerror@ to turn it into an error message string.

AFunction:@ size_t Dregerror@ B(int Berrcode@, regex_t *Bcompiled@, char *Bbuffer@, size_t Blength@)
Â‰IDX1416Š@�”˜This function produces an error message string for the error code Berrcode@, and stores the string in Blength@ bytes of memory starting at Bbuffer@. For the Bcompiled@ argument, supply the same compiled regular expression structure that Hregcomp@ or Hregexec@ was working with when it got the error. Alternatively, you can supply HNULL@ for Bcompiled@; you will still get a meaningful error message, but it might not be as detailed.
If the error message can't fit in Blength@ bytes (including a terminating null character), then Hregerror@ truncates it. The string that Hregerror@ stores is always null-terminated even if it has been truncated.
The return value of Hregerror@ is the minimum length needed to store the entire error message. If this is less than Blength@, then the error message was not truncated, and you can use it. Otherwise, you should call Hregerror@ again with a larger buffer.
Here is a function which uses Hregerror@, but always dynamically allocates a buffer for the error message: char *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;
} À

ˆ‰SEC289Št�”›Shell-Style Word Expansion

‰IDX1417Š‰IDX1418Š
B�”˜Word expansion@ means the process of splitting a string into Bwords@ and substituting for variables, commands, and wildcards just as the shell does.
For example, when you write H`ls -l foo.c'@, this string is split into three separate words---H`ls'@, H`-l'@ and H`foo.c'@. This is the most basic function of word expansion.
When you write H`ls *.c'@, this can become many words, because the word H`*.c'@ can be replaced with any number of file names. This is called Bwildcard expansion@, and it is also a part of word expansion.
When you use H`echo $PATH'@ to print your path, you are taking advantage of Bvariable substitution@, which is also part of word expansion.
Ordinary programs can perform word expansion just like the shell by calling the library function Hwordexp@.
ˆ‰SEC290ŠT�”›The Stages of Word Expansion

@�”˜When word expansion is applied to a sequence of words, it performs the following transformations in the order shown here: þÂ
1. ‰IDX1419ŠB�”˜Tilde expansion@: Replacement of H`~foo'@ with the name of the home directory of H`foo'@.
2. Next, three different transformations are applied in the same step, from left to right: Ä
• ‰IDX1420Š‰IDX1421ŠB�”˜Variable substitution@: Environment variables are substituted for references such as H`$foo'@.
• ‰IDX1422ŠB�”˜Command substitution@: Constructs such as H``cat foo`'@ and the equivalent H`$(cat foo)'@ are replaced with the output from the inner command.
• ‰IDX1423ŠB�”˜Arithmetic expansion@: Constructs such as H`$(($x-1))'@ are replaced with the result of the arithmetic computation.Â
3. ‰IDX1424ŠB�”˜Field splitting@: subdivision of the text into Bwords@.
4. ‰IDX1425ŠB�”˜Wildcard expansion@: The replacement of a construct such as H`*.c'@ with a list of H`.c'@ file names. Wildcard expansion applies to an entire word at a time, and replaces that word with 0 or more file names that are themselves words.
5. ‰IDX1426Š‰IDX1427ŠB�”˜Quote removal@: The deletion of string-quotes, now that they have done their job by inhibiting the above transformations when appropriate.Àð
For the details of these transformations, and how to write the constructs that use them, see BThe BASH Manual@ (to appear).
ˆ‰SEC291ŠT�”›Calling \wordexp

@�”˜All the functions, constants and data types for word expansion are declared in the header file H`wordexp.h'@.
Word expansion produces a vector of words (strings). To return this vector, Hwordexp@ uses a special data type, Hwordexp_t@, which is a structure. You pass Hwordexp@ the address of the structure, and it fills in the structure's fields to tell you about the results.

AData Type:@ Dwordexp_t
Â‰IDX1428Š@�”˜This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size.
Hwe_wordc
Ä@The number of elements in the vector.
ÂHwe_wordv
Ä@The address of the vector. This field has type Hchar **@.
ÂHwe_offs
Ä@The offset of the first real element of the vector, from its nominal address in the Hwe_wordv@ field. Unlike the other fields, this is always an input to Hwordexp@, rather than an output from it. If you use a nonzero offset, then that many elements at the beginning of the vector are left empty. (The Hwordexp@ function fills them with null pointers.) The Hwe_offs@ field is meaningful only if you use the HWRDE_DOOFFS@ flag. Otherwise, the offset is always zero regardless of what is in this field, and the first real element comes at the beginning of the vector.Â
À

AFunction:@ int Dwordexp@ B(const char *Bwords@, wordexp_t *Bword-vector-ptr@, int Bflags@)
Â‰IDX1429Š@�”˜Perform word expansion on the string Bwords@, putting the result in a newly allocated vector, and store the size and address of this vector into H*Jword-vector-ptr@. The argument Bflags@ is a combination of bit flags; see section ‰ŠP�”›Flags for Word Expansion@�”˜, for details of the flags.
You shouldn't use any of the characters H`|&;<>'@ in the string Bwords@ unless they are quoted; likewise for newline. If you use these characters unquoted, you will get the HWRDE_BADCHAR@ error code. Don't use parentheses or braces unless they are quoted or part of a word expansion construct. If you use quotation characters H`'"`'@, they should come in pairs that balance.
The results of word expansion are a sequence of words. The function Hwordexp@ allocates a string for each resulting word, then allocates a vector of type Hchar **@ to store the addresses of these strings. The last element of the vector is a null pointer. This vector is called the Bword vector@.
To return this vector, Hwordexp@ stores both its address and its length (number of elements, not counting the terminating null pointer) into H*Jword-vector-ptr@.
If Hwordexp@ succeeds, it returns 0. Otherwise, it returns one of these error codes:
HWRDE_BADCHAR
Ä@The input string Bwords@ contains an unquoted invalid character such as H`|'@.
ÂHWRDE_BADVAL
Ä@The input string refers to an undefined shell variable, and you used the flag HWRDE_UNDEF@ to forbid such references.
ÂHWRDE_CMDSUB
Ä@The input string uses command substitution, and you used the flag HWRDE_NOCMD@ to forbid command substitution.
ÂHWRDE_NOSPACE
Ä@It was impossible to allocate memory to hold the result. In this case, Hwordexp@ can store part of the results--as much as it could allocate room for.
ÂHWRDE_SYNTAX
Ä@There was a syntax error in the input string. For example, an unmatched quoting character is a syntax error.Â
À

AFunction:@ void Dwordfree@ B(wordexp_t *Bword-vector-ptr@)
Â‰IDX1430Š@�”˜Free the storage used for the word-strings and vector that H*Jword-vector-ptr@ points to. This does not free the structure H*Jword-vector-ptr@ itself--only the other data it points to.À

ˆ‰SEC292ŠT�”›Flags for Word Expansion

@�”˜This section describes the flags that you can specify in the Bflags@ argument to Hwordexp@. Choose the flags you want, and combine them with the C operator H|@.
HWRDE_APPEND
Â@Append the words from this expansion to the vector of words produced by previous calls to Hwordexp@. This way you can effectively expand several words as if they were concatenated with spaces between them. In order for appending to work, you must not modify the contents of the word vector structure between calls to Hwordexp@. And, if you set HWRDE_DOOFFS@ in the first call to Hwordexp@, you must also set it when you append to the results.
ÀHWRDE_DOOFFS
Â@Leave blank slots at the beginning of the vector of words. The Hwe_offs@ field says how many slots to leave. The blank slots contain null pointers.
ÀHWRDE_NOCMD
Â@Don't do command substitution; if the input requests command substitution, report an error.
ÀHWRDE_REUSE
Â@Reuse a word vector made by a previous call to Hwordexp@. Instead of allocating a new vector of words, this call to Hwordexp@ 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 pointer and use it again after calling Hwordexp@. You must fetch Hwe_pathv@ anew after each call.
ÀHWRDE_SHOWERR
Â@Do show any error messages printed by commands run by command substitution. More precisely, allow these commands to inherit the standard error output stream of the current process. By default, Hwordexp@ gives these commands a standard error stream that discards all output.
ÀHWRDE_UNDEF
Â@If the input refers to a shell variable that is not defined, report an error.À

ˆ‰SEC293Š\�”›wordexpT Example

@�”˜Here is an example of using Hwordexp@ to expand several strings and use the results to run a shell command. It also shows the use of HWRDE_APPEND@ to concatenate the expansions and of Hwordfree@ to free the space allocated by Hwordexp@. int
expand_and_execute (const char *program, const char *options)
{
wordexp_t result;
pid_t pid
int status, i;

/* Expand the string for the program to run. */
switch (wordexp (program, &result, 0))
{
case 0: /* Successful. */
break;
case WRDE_NOSPACE:
/* If the error was HWRDE_NOSPACE@,
then perhaps part of the result was allocated. */
wordfree (&result);
default: /* Some other error. */
return -1;
}

/* 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)
{
/* This is the child process. Execute the command. */
execv (result.we_wordv[0], result.we_wordv);
exit (EXIT_FAILURE);
}
else if (pid < 0)
/* The fork failed. Report failure. */
status = -1;
else
/* This is the parent process. Wait for the child to complete. */
if (waitpid (pid, &status, 0) != pid)
status = -1;

wordfree (&result);
return status;
}
In practice, since Hwordexp@ is executed by running a subshell, it would be faster to do this by concatenating the strings with spaces between them and running that as a shell command using H`sh -c'@.
Œ
Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.