wordexp(3C) wordexp(3C)
NAME
wordexp, wordfree - perform word expansions
SYNOPSIS
#include <wordexp.h>
int wordexp(const char *words, wordexpt *pwordexp, int flags);
void wordfree(wordexpt *pwordexp);
DESCRIPTION
The wordexp() function 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 will be the same as would be per-
formed by the shell if words were the part of a command line repre-
senting the arguments to a utility. Therefore, words must not contain
an unquoted newline or any of the unquoted shell special characters:
| & ; < >
except in the context of command substitution (command substitution
allows the output of a command to be substituted in place of the com-
mand name itself). It also must not contain unquoted parantheses or
braces, except in the context of command or variable substitution. If
the argument words contains an unquoted comment character (number
sign) that is the beginning of a token, wordexp() may treat the com-
ment character as a regular character, or may interpret it as a com-
ment indicator and ignore the remainder of words.
The structure wordexpt is defined in the header wordexp.h and
includes at least the following members:
______________________________________________________________________
| Member Type | Member Name | Description |
|_______________|_______________|_____________________________________|
| sizet | wewordc | Count of words matched by words |
|_______________|_______________|_____________________________________|
| char ** | wewordv | Pointer to list of expanded words |
|_______________|_______________|_____________________________________|
| sizet | weoffs | ots to reserve at the beginning |
| | | of pwordexp->wewordv |
|_______________|_______________|_____________________________________|
The wordexp() function stores the number of generated words into
pword->wewordc and a pointer to a list of pointers to words in
pwordexp->wewordv. Each individual field created during field split-
ting or pathname expansion is a separate word in the
pwordexp->wewordv list.The first pointer after the last word pointer
will be a null pointer. The expansion of special parameters (like *,
@, #, ?, - $, !, 0) is undefined.
Page 1 Reliant UNIX 5.44 Printed 11/98
wordexp(3C) wordexp(3C)
Field Splitting
After parameter expansion, command substitution and arithmetic expan-
sion the shell will scan the results of expansions and substitutions
that did not occur in double-quotes for field-splitting and multiple
fields can result. The shell will treat each character of the IFS
(environment variable for input field separator) as a delimiter and
use the delimiters to split the results of parameter expansion and
command substitution into fields.
1. If the value of IFS is a space, tab and newline character, or if it
is unset, any sequence of space, tab or newline characters at the
beginning or end of the input will be ignored and any sequence of
those characters within the input will delimit a field.
2. If the value of IFS is null, no field splitting will be performed.
3. Otherwise, the following rules will be applied in sequence. The
term "IFS white space" is used to mean any sequence (zero or more
instances) of white-space characters that are in the IFS value.
- IFS white space is ignored at the beginning and end of the
input.
- Each occurrence in the input of an IFS character that is not IFS
white space, along with any adjacent IFS white space, will del-
imit a field.
- Non-zero length IFS white space will delimit a field.
Pathname Expansion
After field splitting, if set -f is not in effect, each field in the
resulting command line will be expanded using the pattern matching
notation.
Word Expansions
The order of word expansions is as follows:
1. Tilde expansion, parameter expansion, command substitution and
arithmetic expansion are performed beginning to end.
2. Field splitting is performed on the portions of the fields gen-
erated by step 1, unless IFS is null.
3. Pathname expansion is performed, unless set -f is in effect.
4. Quote removal always is performed last.
Page 2 Reliant UNIX 5.44 Printed 11/98
wordexp(3C) wordexp(3C)
If the complete expansion appropriate for a word results in an empty
field, that empty field will be deleted from the list of fields that
form the completely expanded command, unless the original word con-
tained single-quote or double-quote characters.
The $ character is used to introduce parameter expansion, command sub-
stitution or arithmetic evaluation. If an unquoted $ is followed by a
character that is either not numeric, the name of one of the special
parameters, a valid first character of a variable name, a left curly
brace ({) or a left paranthesis, the result is unspecified.
IFS is used for performing field splitting on the results of parameter
and command substitution; it is not used for splitting all fields.
Previous versions of the shell used it for splitting all fields during
field splitting, but this has severe problems because the shell can no
longer parse its own script. There are also important security impli-
cations caused by this behavior. All useful applications of IFS use it
for parsing input of the read utility and for splitting the results of
parameter and command substitution.
The wordexp() function is intended to be used by an application that
wants to do all of the shells expansions on a word or words obtained
from a user. For example, if the application prompts for a filename
(or a list of filenames) and then uses wordexp() to process the input,
the user could respond with anything that would be valid as input to
the shell.
It is the callers responsibility to allocate the storage pointed to by
pwordexp. The wordexp() function allocates other space as needed,
including memory pointed to by pwordexp->wewordv. The wordfree()
function 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 fol-
lowing constants, which are defined in wordexp.h:
WRDEAPPEND Append words generated to the ones from a previous
call to wordexp().
WRDEDOOFFS Make use of pwordexp->weoffs. If this flag is set,
pwordexp->weoffs is used to specify how many null
pointers to add to the beginning of
pwordexp->wewordv. In other words, pwordexp->wewordv
will point to pwordexp->weoffs null pointers, fol-
lowed by pwordexp->wewordc word pointers, followed by
a null pointer.
WRDENOCMD Fail if command substitution is requested.
Page 3 Reliant UNIX 5.44 Printed 11/98
wordexp(3C) wordexp(3C)
WRDEREUSE The pwordexp argument was passed to a previous suc-
cessful call to wordexp(), and has not been passed to
wordfree(). The result will be the same as if the
application had called wordfree() and then called
wordexp() without WRDEREUSE.
WRDESHOWERR Do not redirect stderr to /dev/null.
WRDEUNDEF Report error on an attempt to expand an undefined
shell variable.
The WRDEAPPEND 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():
1. The first such call must not set WRDEAPPEND. All subsequent calls
must set it.
2. All of the other calls must set WRDEDOOFFS, or all must not set
it.
3. After the second and each subsequent call, pwordexp->wewordv will
point to a list containing the following:
- zero or more null pointers, as specified by WRDEDOOFFS and
pwordexp->weoffs
- pointers to the words that were in the pwordexp->wewordv list
before the call, in the same order as before
- pointers to the new words generated by the latest call, in the
specified order
4. The count returned in pwordexp->wewordc will be the total number
of words from all of the calls.
5. The application can change any of the fields after a call to
wordexp(), but if it does it must reset them to the original value
before a subsequent call, using the same pwordexp value, to
wordfree() or wordexp() with the WRDEAPPEND or WRDEREUSE flag.
If words contains an unquoted:
<newline> | & , < > ( ) { }
in an appropriate context, wordexp() will fail, and the number of
expanded words will be zero.
Page 4 Reliant UNIX 5.44 Printed 11/98
wordexp(3C) wordexp(3C)
Unless WRDESHOWERR is set in flags, wordexp() will redirect stderr to
/dev/null for any utilities executed as a result of command substitu-
tion while expanding words. If WRDESHOWERR is set, wordexp() may
write messages to stderr if syntax errors are detected while expanding
words.
If WRDEDOOFFS is set, then pwordexp->weoffs must have the same value
for each wordexp() call and wordfree() call using a given pwordexp.
The WRDENOCMD flag is provided for applications that, for security or
other reasons, want to prevent a user from executing shell commands.
Disallowing unquoted shell special characters also prevents unwanted
side effects such as executing a command or writing a file.
The following constants are defined as error return values:
WRDEBADCHAR One of the unquoted characters: <newline>, >, &, ;, <,
>, (, ), {, } appears in words in an inappropriate
context.
WRDEBADVAL Reference to undefined shell variable when WRDEUNDEF
is set in flags.
WRDECMDSUB Command substitution requested when WRDENOCMD was set
in flags.
WRDENOSPACE Attempt to allocate memory failed.
WRDESYNTAX Shell syntax error, such as unbalanced parantheses or
unterminated string.
RESULT
On successful completion, wordexp() returns zero.
Otherwise, a non-zero value as described in wordexp.h is returned to
indicate an error. If wordexp() returns the value WRDENOSPACE, then
pwordexp->wewordc and pwordexp->wewordv will be updated to reflect
any words that were successfully expanded. In other cases, they will
not be modified.
The wordfree() function returns no value.
SEE ALSO
fnmatch(3C), glob(3C), wordexp(5).
Page 5 Reliant UNIX 5.44 Printed 11/98