HP-UX Reference (11i v1 00/12) - 3 Library Functions N-Z (vol 7)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/nan.3m
________________________________________________________________
___ ___
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:
HP-UX Release 11i: December 2000 − 1 − Section 3−−1025
___
___