HP-UX Reference (11i v3 07/02) - 3 Library Functions N-Z (vol 7)

w
wordexp(3C) 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 sub-
stitution. 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, fol-
lowed 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 wor-
dexp()
, 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:
662 Hewlett-Packard Company − 1 − HP-UX 11i Version 3: February 2007