wordexp(), wordfree() -- perform word expansions

SYNOPSIS

#include <wordexp.h>

int wordexp(const char *words, wordexp_t *pwordexp, int flags);

void wordfree(wordexp_t *pwordexp);

DESCRIPTION

The wordexp() performs word expansions subject to standard shell quoting and places the list of expanded words in the structure pointed to by pwordexp.

The expansion of words is the same as that performed by sh if words were arguments to a utility on a sh command line.

words cannot contain an unquoted newline or any of the following special characters:

|   &   ;   <   >

except in the context of command substitution. words may also not contain unquoted parentheses or braces, except in the context of command or variable substitution. If words contains an unquoted comment character (#) that begins a token, wordexp() may treat treat it as a regular character or as a comment indicator. If it is treated as a comment character, wordexp() ignores the remainder of words.

The wordexp() function stores the number of generated words in the we_wordc member of pwordexp and a pointer to a list of pointers to words in the we_wordv member.

The caller must allocate the storage pointed to by pwordexp; however, wordexp() allocates other memory as needed, including that pointed to by the we_wordv member of pwordexp.

The flags argument controls the behavior of wordexp(). Its value is the bitwise-OR of one or more of the following flags:

WRDE_APPEND: Appends words to those generated by previous wordexp() calls with the same pwordexp argument.
WRDE_DOOFFS: Use the we_offs member of pwordexp to specify the number of null pointers to add to the beginning of the we_wordv member of pwordexp. In other words, the we_wordv member points to we_offs null pointers, followed by wordc word pointers, followed by a null pointer.
WRDE_NOCMD: Fail if command substitution is requested.
WRDE_REUSE: The pwordexp argument was passed to a previous successful wordexp() call, and has not been passed to wordfree(). The result is the same as if the application called wordfree() followed by wordexp() without WRDE_REUSE.
WRDE_SHOWERR: Do not redirect the standard error stream. Normally, wordexp() redirects any output on the standard error stream generated when executing utilities during command substitution to /dev/null.
WRDE_UNDEF: Report an error on an attempt to expand an undefined shell variable.

The wordfree() function frees all memory associated with pwordexp from a previous call to wordexp().

PARAMETERS

flags: Contains a bitwise-OR value that controls the behavior of wordexp().
pwordexp: Points to a wordexp_t structure that contains the expanded words.
words: Points to the string on which word expansion is to be performed.

RETURN VALUES

The wordfree() function does not return a value.

On success, wordexp() returns 0. On failure, it returns an error values. If the returned error value is WRDE_NOSPACE, the we_wordc and we_wordv members of pwordexp reflect the words that were successfully expanded. For all other error values, pwordexp is unchanged. Possible error values are:

WRDE_BADCHAR: An unquoted metacharacter appeared in the wrong place.
WRDE_BADVAL: There was an undefined environment variable reference with the WRDE_UNDEF flag set.
WRDE_CMDSUB: Command substitution was requested with the WRDE_NOCMD flag set.
WRDE_NOSPACE: The process ran out of memory.
WRDE_SYNTAX: There was a sh syntax error.

wordexp(), wordfree()
perform word expansions

Function

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

CONFORMANCE

MULTITHREAD SAFETY LEVEL

PORTING ISSUES

AVAILABILITY

SEE ALSO

wordexp(), wordfree() perform word expansions

Function

wordexp(), wordfree()
perform word expansions