wordexp(3C)wordexp(3C)NAMEwordexp(), wordfree() - perform word expansions
SYNOPSISDESCRIPTION
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 per‐
formed by the shell (see sh-posix(1)), if words were the part of a com‐
mand 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 interprets as a comment indi‐
cator, causing the remainder of words to be ignored.
The structure type is defined in the header and includes the following
members:
A used to keep count of words matched by
words.
A used as a pointer to a list of expanded
words.
Also a used to indicate the number of slots to
reserve at the beginning of
stores the number of generated words into Each individual field created
during field splitting or path name expansion is a separated word in
the list. The words are in order as described in shell word expan‐
sions. 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. allocates other space as needed, including memory pointed to
by
frees any memory associated with pwordexp from a previous call to
The flags argument is used to control the behavior of The value of
flags is the bitwise inclusive OR of zero or more of the following con‐
stants, which are defined in
Append words generated to the ones from a previous call to
Make use of If this flag is set, is used to specify how
many null pointers to add to the beginning
of In other words, points to null pointers,
followed by word pointers, followed by a
null pointer.
Fail if command substitution is requested.
The pwordexp argument was passed to a previous
successful call to and has not been passed
to The result is the same as if the applica‐
tion had called and then called without
Do not redirect stderr to
Report error on an attempt to expand an undefined shell vari‐
able.
The flag can be used to append a new set of words to those generated by
a previous call to The following rules apply when two or more calls to
are made with the same value of pwordexp and without intervening calls
to
· The first call must not set All subsequent calls must set it.
· All of the calls must set or all must not set it.
· After the second and each subsequent call, points to a list
containing the following:
· Zero or more null pointers, as specified by and
· Pointers to the words that were in the 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 is the total number of words from all
of the calls.
· The application can change any of the fields after a call to
but if it does, it must reset them to the original value
before a subsequent call, using the same pwordexp value, to
or with the or flag.
If words contains an unquoted newline, parentheses, or curly brackets
in an inappropriate context, fails, and the number of expanded words is
zero.
Unless is set in flags, redirects stderr to for any utilities executed
as a result of command substitution while expanding words. If is set,
writes messages to stderr if syntax errors are detected while expanding
words.
If is set, has the same value for each call and the call using a given
RETURN VALUE
Upon successful completion, returns zero; otherwise, it returns a
nonzero value defined in to indicate the error:
One of the unquoted characters
parentheses, or braces appears in words in
an inappropriate context.
Reference to undefined shell variable when
is set in flags.
Command substitution requested when
was set in flags.
Attempt to allocate memory failed.
Shell syntax error such as unbalanced parentheses
or unterminated string.
Internal error.
If returns the error value and are updated to reflect any words that
were successfully expanded. In other cases, they are not modified.
AUTHOR
and were developed by OSF and HP.
SEE ALSOsh-posix(1), fnmatch(3C), glob(3C), regexp(5), thread_safety(5).
STANDARDS CONFORMANCEwordexp(3C)
