wordexp(3C)

NAME

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

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

The words argument is a pointer to a string containing one or more words to be expanded. The expansions are the same as would be performed by the shell (see sh-posix(1)), if words were the part of a command line representing the arguments to a utility. Therefore, words must not contain an unquoted newline character or any of the unquoted shell special characters |, &, ;, < or >, except in the context of shell command substitution. If words contains an unquoted comment character, #, it is treated as the beginning of a token that wordexp() interprets as a comment indicator, causing the remainder of words to be ignored.

The structure type wordexp_t is defined in the header <wordexp.h>, and includes the following members:

we_wordc: A size_t used to keep count of words matched by words.
we_wordv: A char** used as a pointer to a list of expanded words.
we_offs: Also a size_t used to indicate the number of slots to reserve at the beginning of pwordexp->we_wordv.

wordexp() stores the number of generated words into pwordexp->we_wordc. Each individual field created during field splitting or path name expansion is a separated word in the pwordexp->we_wordv list. The words are in order as described in shell word expansions. The first pointer after the last word pointer is a null pointer. The expansion of special parameters (such as $$ or $*) is unspecified.

It is the caller's responsibility to allocate the storage pointed to by pwordexp. wordexp() allocates other space as needed, including memory pointed to by pwordexp->we_wordv.

wordfree() frees any memory associated with pwordexp from a previous call to wordexp().

The flags argument is used to control the behavior of wordexp(). The value of flags is the bitwise inclusive OR of zero or more of the following constants, which are defined in <wordexp.h>:

WRDE_APPEND: Append words generated to the ones from a previous call to wordexp().
WRDE_DOOFFS: Make use of pwordexp->we_offs. If this flag is set, pwordexp->we_offs is used to specify how many null pointers to add to the beginning of pwordexp->we_wordv. In other words, pwordexp->we_wordv points to pwordexp->we_offs null pointers, followed by pwordexp->we_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 call to wordexp(), and has not been passed to wordfree(). The result is the same as if the application had called wordfree() and then called 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.

The WRDE_APPEND flag can be used to append a new set of words to those generated by a previous call to wordexp(). The following rules apply when two or more calls to wordexp() are made with the same value of pwordexp and without intervening calls to wordfree():

The first call must not set WRDE_APPEND. All subsequent calls must set it.
All of the calls must set WRDE_DOOFFS, or all must not set it.
After the second and each subsequent call, pwordexp->we_wordv points to a list containing the following:
- Zero or more null pointers, as specified by WRDE_DOOFFS and pwordexp->we_offs.
- Pointers to the words that were in the pwordexp->we_wordv list before the call, in the same order as before.
- Pointers to the new words generated by the latest call, in the specified order.
The count returned in pwordexp->we_wordc is the total number of words from all of 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 a subsequent call, using the same pwordexp value, to wordfree() or wordexp() with the WRDE_APPEND or WRDE_REUSE flag.

If words contains an unquoted newline, |, &, ;, <, >, parentheses, or curly brackets in an inappropriate context, wordexp() fails, and the number of expanded words is zero.

Unless WRDE_SHOWERR is set in flags, wordexp() redirects stderr to /dev/null for any utilities executed as a result of command substitution while expanding words. If WRDE_SHOWERR is set, wordexp() writes messages to stderr if syntax errors are detected while expanding words.

If WRDE_DOOFFS is set, pwordexp->we_offs has the same value for each wordexp() call and the wordfree() call using a given wordexp().

RETURN VALUE

Upon successful completion, wordexp() returns zero; otherwise, it returns a nonzero value defined in <wordexp.h> to indicate the error:

WRDE_BADCHAR: One of the unquoted characters |, &, ;, <, >, parentheses, or braces appears in words in an inappropriate context.
WRDE_BADVAL: Reference to 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 such as unbalanced parentheses or unterminated string.
WRDE_INTERNAL: Internal error.

If wordexp() returns the error value WRDE_NOSPACE, pwordexp->we_wordc and pwordexp->we_wordv are updated to reflect any words that were successfully expanded. In other cases, they are not modified.

AUTHOR

wordexp() and wordfree() were developed by OSF and HP.

STANDARDS CONFORMANCE

wordexp(): XPG4, POSIX.2

wordfree(): XPG4, POSIX.2

wordexp(3C)

Technical documentation

» Table of Contents

» Index