Calling Wordexp - The GNU C Library

Next: Flags for Wordexp, Previous: Expansion Stages, Up: Word Expansion

#### 10.4.2 Calling `wordexp`

All the functions, constants and data types for word expansion are declared in the header file `wordexp.h`.

Word expansion produces a vector of words (strings). To return this vector, `wordexp` uses a special data type, `wordexp_t`, which is a structure. You pass `wordexp` the address of the structure, and it fills in the structure's fields to tell you about the results.

— Data Type: wordexp_t

> This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size.

> `we_wordc`
>   The number of elements in the vector.
> `we_wordv`
>   The address of the vector. This field has type `char **`.
> `we_offs`
>   The offset of the first real element of the vector, from its nominal address in the `we_wordv` field. Unlike the other fields, this is always an input to `wordexp`, 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 `wordexp` function fills them with null pointers.)

>   The `we_offs` field is meaningful only if you use the `WRDE_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.

— Function: int wordexp (const char *words, wordexp_t *word-vector-ptr, int flags)

> Perform word expansion on the string words, putting the result in a newly allocated vector, and store the size and address of this vector into `*`word-vector-ptr. The argument flags is a combination of bit flags; see Flags for Wordexp, for details of the flags.

> You shouldn't use any of the characters ‘`|&;<>`’ in the string words unless they are quoted; likewise for newline. If you use these characters unquoted, you will get the `WRDE_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 ‘`'"``’, they should come in pairs that balance.

> The results of word expansion are a sequence of words. The function `wordexp` allocates a string for each resulting word, then allocates a vector of type `char **` to store the addresses of these strings. The last element of the vector is a null pointer. This vector is called the word vector.

> To return this vector, `wordexp` stores both its address and its length (number of elements, not counting the terminating null pointer) into `*`word-vector-ptr.

> If `wordexp` succeeds, it returns 0. Otherwise, it returns one of these error codes:

> `WRDE_BADCHAR`
>   The input string words contains an unquoted invalid character such as ‘`|`’.
> `WRDE_BADVAL`
>   The input string refers to an undefined shell variable, and you used the flag `WRDE_UNDEF` to forbid such references.
> `WRDE_CMDSUB`
>   The input string uses command substitution, and you used the flag `WRDE_NOCMD` to forbid command substitution.
> `WRDE_NOSPACE`
>   It was impossible to allocate memory to hold the result. In this case, `wordexp` can store part of the results—as much as it could allocate room for.
> `WRDE_SYNTAX`
>   There was a syntax error in the input string. For example, an unmatched quoting character is a syntax error.

— Function: void wordfree (wordexp_t *word-vector-ptr)

> Free the storage used for the word-strings and vector that `*`word-vector-ptr points to. This does not free the structure `*`word-vector-ptr itself—only the other data it points to.