wordexp(3C)

wordexp, wordfree -- perform word expansions

Synopsis

   #include <wordexp.h>
   
   int wordexp(const char string, wordexp_t pword, int flags);
   

   void wordfree(wordexp_t pword);

Description

These functions are part of the X/Open Portability Guide Issue 4 optional POSIX2 C-Language Binding feature group.

wordexp performs word expansions and places the list of expanded words into the structure pointed to by pword.

The first argument is a pointer to a string containing one or more words to be expanded. The expansions are the same as those performed by the shell if string are part of a command line representing the arguments to a utility. Therefore, string must not contain an unquoted newline or any of the unquoted shell special characters:

   |  & ; < >

except in the context of command substitution. It also must not contain unquoted parentheses or braces, except in the context of command or variable substitution. If string contains an unquoted comment character that is the beginning of a token, wordexp may treat the comment character as a regular character, or may interpret it as a comment indicator and ignore the remainder of string.

wordexp stores the number of generated words into a pointer to a list of pointers. Each individual field created during field splitting or pathname expansion is a separate word in the list. The first pointer after the last word pointer is a null pointer. The expansion of special parameters is unspecified.

You must allocate the storage pointed to by pword. wordexp allocates other space as needed, including memory pointed to by pword. wordfree frees any memory associated with pword from a previous call to wordexp.

flags controls the behavior of wordexp. The value of flags is the bitwise inclusive OR of zero or more of the following constants:

WRDE_APPEND: Append words generated to the ones from a previous call.
WRDE_DOOFFS: The value of the wrde_dooffs member pointed to by pword specifies how many null pointers to add to the beginning of pword.
WRDE_NOCMD: Fail if a command substitution is requested.
WRDE_REUSE: pword was passed to a previous successful call to wordexp, and has not been passed to wordfree. The result is the same as if wordfree had been called before wordexp without WRDE_REUSE.
WRDE_SHOWERR: Do not redirect stderr to /dev/null.
WRDE_UNDEF: Report error on an attempt to expand an undefined shell variable.

You can use WRDE_APPEND to append a new set of words to those generated by a previous call to wordexp. If two or more calls to wordexp are made with the same value of pword and without intervening calls to wordfree, the following rules apply:

The first call must not set WRDE_APPEND. All following calls must set it.
All calls must set WRDE_DOOFFS or none can set it.
After the second, and each following call, pword will point to a list containing:
- Zero or more null pointers as specified by wrde_dooffs and WRDE_DOOFFS.
- Pointers to the words that were in the pword list before the call, in the same order as before
- Pointers to the new words generated by the latest call, in specified order.
The count returned in the wrde_dooffs member is the total number of words from all the calls.

The application can change any of the fields after a call to wordexp, but if it does it must reset them to the original value before later calls, using the same pword value, to wordfree or wordexp with the WRDE_APPEND or WRD_REUSE flag.

If string contains any of the following shell special characters:

   <newline> |  & ; < > ( ) { }

in an inappropriate context, wordexp will fail and the number of expanded words will be zero.

If WRDE_SHOWERR is set in flags, wordexp will redirect stderr to dev/null for any utilities executed as a result of command substitution while expanding words. wordexp may also write messages to stderr if syntax errors are detected.

If WRDE_DOOFFSS is set, pwordexp must have the same value for each wordexp call and wordfree call using a given pwordexp.

Return values

wordexp returns 0 if successful.

wordfree returns no value.

Errors

In the following conditions, wordexp returns and sets errno to:

WRDE_BADCHAR: One of the unquoted characters appears in words in an inappropriate context.
WRDE_BADVAL: Reference to an undefined shell variable when WRDE_UNDEF is set in flags.
WRDE_CMDSUB: Command substitution requested when WRDE_NOCMD was set in flags.
WRDE_NOSPACE: Attempt to allocate memory failed.
WRDE_SYNTAX: Shell syntax error.

If wordexp returns WRDE_NOSPACE, the structure is modified to indicate any successfully expanded words. In other cases there is no update.

References

fnmatch(3C), glob(3C), wordexp(5)