HP 3000 Manuals HP 3000 Manuals
wordexp
Expand special constructions.
Syntax
#include <wordexp.h>
int wordexp (const char *words, wordexp_t *expansions, int flags);
Parameters
words is a string containing various special constructions that are
typically expanded in shell command lines (for example,
command substitutions, directory substitutions, parameter
expansions, and so on).
expansions points to an object of type wordexp_t where wordexp() can
store the expanded version of words. It is created by the
caller.
flags is a collection of flags controlling the wordexp() action.
Flags are specified by ORing together symbolic constants
defined in <wordexp.h>. Possible symbols are:
WRDE_APPEND appends expansions to an existing expansions
list generated by a previous call to
wordexp().
WRDE_DOOFFS uses the we_offs field in the wordexp_t
structure expansions.
WRDE_NOCMD does not perform command substitution.
wordexp() fails if command substitution is
attempted.
WRDE_REUSE expansions was passed to 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().
WRDE_SHOWERR Do not redirect the standard error to
/dev/null.
WRDE_UNDEF Reports error on attempt to expand an
undefined shell variable.
Return Values
If wordexp() completes successfully, it returns zero. Otherwise, it
returns one of the following error messages.
Description
wordexp() expands special constructs in the string words. See the
section Expanded Constructs for a list of the constructs that wordexp()
expands.
wordexp() returns the expansion using a wordexp_t structure. This
structure has the following fields:
int we_wordc; is the number of words in the expansion of words. This
field is set by wordexp().
char points to a list of strings giving the expansions of
**we_wordv; words from words. Each individual field created during
expansion becomes a separate word in the we_wordv list.
The first pointer after the last path name is NULL. This
field is set by wordexp().
int we_offs; tells how many NULL pointers you want at the beginning
of the we_wordv list. This creates a specified amount
of `blank' space at the beginning of we_wordv that can
be used for other purposes. For example, you might fill
this space with other arguments before passing the whole
we_wordv vector as an argument to a function like
execv().
You set we_offs before calling wordexp(). wordexp() puts the specified
number of NULL pointers at the beginning of the we_wordv list before
putting in pointers to the strings giving the expansion of words.
wordexp() only pays attention to we_offs if WRDE_DOOFFS is set in flags.
If WRDE_APPEND is specified, wordexp() follows these rules:
1. If WRDE_DOOFFS is set in the first call to wordexp(), it must be
set in subsequent calls and we_offs must have the same value in
each call.
2. If WRDE_DOOFFS is not set in the first call, it must not be set in
subsequent calls.
3. After the second call, we_wordv points to a list containing: the
number of NULL pointers as determined by WRDE_DOOFFS and we_offs;
pointers to the words that were in the list before the second
call, in the same order as before; and pointers to the new words
obtained by the second call, in the order dictated by the flags
for the second call.
4. we_wordc gives the total number of words from all the calls.
You must not change we_wordc or we_wordv between calls to wordexp().
Expanded Constructs
wordexp() performs the following expansions in the order given:
Directory expands constructs of the form ~logname into the
Substitution full path name of the user logname's home
directory.
Parameter Expansion expands the following constructs:
${parameter}
${parameter:-word}
${parameter:=word}
${parameter:?word}
${parameter:+word}
${#parameter}
${parameterword}
${parameterword}
${parameter#word}
${parameter##word}
The result of the expansion of these constructs is
detailed in the sh(1) man page.
Command Substitution expands the following constructs
$(command)
`command`
by executing command and replacing the construct
with its output.
Arithmetic Expansion expands constructs of the form
$((%%expression%%))
by replacing the construct with the value of the
arithmetic expression.
These expansions are discussed in much greater detail in sh(1).
After performing the various expansions, wordexp() breaks up the result
into separate words. Words are assumed to be separated by any one of the
characters in the string value of the environment variable IFS. If IFS
does not exist, wordexp() assumes that words are separated by one or more
white space characters (blanks, tabs, or newlines). When splitting words
in this way, wordexp()
After breaking up words into these separate words, wordexp() performs
filename generation on names that are not quoted (see sh(1)).
Finally, wordexp() removes backslashes, quotes, and apostrophes from
expanded strings, as appropriate.
NOTE wordexp() does not handle the special meanings of | (pipe), & (put
job in background), ; (separate one command from another), < (input
redirection) or > (output redirection). If the words string
contains any of these outside of quotes or apostrophes, wordexp()
fails and does not expand any words.
Once a program has finished using the paths structure, it should use
wordfree() to free up the space used to store the path name list.
Errors
If an error occurs, errno is set to one of the following values:
WRDE_BADCHAR CAUSE An unquoted shell metacharacter appeared in words in
an inappropriate context.
ACTION Examine and correct the syntax of the words string
that was passed to the function.
WRDE_BADVAL CAUSE You attempted to reference an undefined shell
variable when WRDE_UNDEF was set in flags.
ACTION Unset WRDE_UNDEF, or do not use undefined shell
variables.
WRDE_CMDSUB CAUSE Command substitution was requested when WRDE_NOCMD
was set in flags.
ACTION Unset WRDE_NOCMD, or do not request command
substitution.
WRDE_ERRNO CAUSE A system call failed inside wrdexp(), setting the
variable errno. The failure was one of the
following:
1. confstr() failed to get the name of the shell
2. pipe() was unable to create a pipe
3. wordexp() was unable to fork() or exec() the
shell.
4. waitpid() for a child process failed.
ACTION Check the value of the variable errno to determine
the true cause of the error.
WRDE_NOSPACE CAUSE wordexp() was unable to allocate memory for one of
its operations. we_wordc and we_wordv are still
updated to show whatever words have already expanded.
ACTION Free up more memory.
WRDE_SYNTAX CAUSE words contained a shell syntax error, such as an
unbalanced parentheses or unterminated string.
ACTION Correct the syntax of words.
See Also
sh(1), glob(), wordfree()