wordexp(3C) wordexp(3C)
NAME
wordexp(), wordfree() - perform word expansions
SYNOPSIS
DESCRIPTION
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 substi-
tution. If words contains an unquoted comment character, it is treated as the beginning of a token that interprets as a comment indicator,
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 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. 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 application had called and then called without
Do not redirect stderr to
Report error on an attempt to expand an undefined shell variable.
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
o The first call must not set All subsequent calls must set it.
o All of the calls must set or all must not set it.
o After the second and each subsequent call, points to a list containing the following:
o Zero or more null pointers, as specified by and
o Pointers to the words that were in the list before the call, in the same order as before.
o Pointers to the new words generated by the latest call, in the specified order.
o The count returned in is the total number of words from all of the calls.
o 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 ALSO
sh-posix(1), fnmatch(3C), glob(3C), regexp(5), thread_safety(5).
STANDARDS CONFORMANCE
wordexp(3C)