wordexp(3)wordexp(3)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 );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
wordexp(), wordfree(): XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the string containing the tokens to be expanded. Contains a
pointer to a wordexp_t structure. Contains a bit option specifying the
configurable aspects of the wordexp() function.
DESCRIPTION
The wordexp() function performs word expansions equivalent to the word
expansion that would be performed by the shell if the contents of the
words parameter were arguments on the command line. The list of
expanded words are placed in thepwordexp parameter.
The expansions are the same as that which would be performed by the
shell if the words parameter were the part of a command line repre‐
senting the parameters to a command. Therefore, the words arameter can‐
not contain an unquoted newline character or any of the unquoted shell
special characters:
| & ; < >
except in the case of command substitution. The words parameter also
cannot contain unquoted parentheses or braces, except in the case of
command or variable substitution. If the words parameter contains an
unquoted comment character (#) that is the beginning of a token, the
wordexp() function may treat the comment character as a regular char‐
acter, or may interpret it as a comment indicator and ignore the
remainder of the expression in the words parameter.
The wordexp() function stores the number of generated words and a
pointer to a list of pointers to words in the pwordexp parameter. Each
individual field created during the field splitting or pathname expan‐
sion is a separate word in the list specified by the pwordexp arame‐
ter. The first pointer after the last token in the list is a null
pointer. The expansion of special parameters *, @, #, ?, -, $, !, and
0 is unspecified. The words are expanded in the following order: Tilde
expansion is performed first. Parameter expansion, command substitu‐
tion, and arithmetic expansion are performed next, from beginning to
end. Field splitting is then performed on fields generated by step 2,
unless the IFS (Input Field Separators) is full. Pathname expansion is
performed, unless the set -f command is in effect. Quote removal is
always performed last.
The pwordexp structure is allocated by the caller, but memory to con‐
tain the expanded tokens is allocated by the wordexp() function and
added to the structure as needed. The wordfree() function frees any
memory associated with pwordexp() from a previous call to wordexp().
The value of the flags parameter is the bitwise inclusive OR of the
following constants, which are defined in the wordexp.h file: Appends
words generated to those generated by a previous call to the wordexp()
function. Makes use of the we_offs structure. If the WRDE_DOOFFS
option is set, the we_offs structure is used to specify the number of
null pointers to add to the beginning of the we_words structure. If
the WRDE_DOOFFS option is not set in the first call to the wordexp()
function with the pwordexp parameter, it should not be set in subse‐
quent calls to the wordexp() function with the pwordexp parameter.
Fails if command substitution is requested. The pwordexp parameter was
passed to a previous successful call to the wordexp() function. There‐
fore, the memory previously allocated may be reused. Does not redirect
standard error to /dev/null. Reports error on an attempt to expand an
undefined shell variable.
The WRDE_APPEND option can be used to append a new set of words to
those generated by a previous call to the wordexp() function. The
following rules apply when two or more calls to the wordexp() function
are made with the same value of the pwordexp parameter and without
intervening calls to the wordfree() function: The first such call does
not set the WRDE_APPEND option. All subsequent calls set it. For a
single invocation of the wordexp() function, all calls either set the
WRDE_DOOFFS option, or do not set it. After the second and each subse‐
quent call, the pwordexp parameter points to a list containing the
following: Zero or more null characters, as specified by the
WRDE_DOOFFS option and the we_offs field of the wordexp_t structure.
Pointers to the words that were in the pwordexp parameter 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 the
pwordexp parameter is the total number of words from all of the calls.
The application should not modify the pwordexp parameter between the
calls.
Unless the WRDE_SHOWERR option is set in the flags parameter, the word‐
exp() function redirects standard error to /dev/null for any utilities
executed as a result of command substitution while expanding the words
parameter. If the WRDE_SHOWERR option is set, the wordexp() function
can write messages to standard error if syntax errors are detected
while expanding the words parameter.
If any of the following conditions occurs, the wordexp() function
returns the corresponding nonzero constant, which is defined in the
wordexp.h file. One of the unquoted characters |, & , ;, <, >, new‐
line, parenthesis, or braces appears in the words parameter in an
inappropriate context. Reference to undefined shell variable when the
WRDE_UNDEF option is set in the flags parameter. Command substitution
requested when the WRDE_NOCMD option is set in the flags parameter. An
attempt to allocate memory was unsuccessful. Shell syntax error, such
as unbalanced parentheses or unterminated string.
The wordexp() function allows an application to perform all of the
shell's expansions on a word or words obtained from a user. For exam‐
ple, if the application prompts for a filename (or a list of file
names) and then uses the wordexp() function to process the input, the
user could respond with anything that would be valid as input to the
shell.
The WRDE_NOCMD option is provided for applications that, for security
or other reasons, want to prevent a user from executing shell com‐
mands. Disallowing unquoted shell special characters also prevents
unwanted side effects such as executing a command or writing to a
file.
NOTES
The wordexp() function can cause a signal to be issued. If a user pro‐
gram catches the signal, wordexp() may return an error.
RETURN VALUES
If no errors are encountered while expanding the words parameter, the
wordexp() function returns a value of 0 (zero). If an error occurs,
the function returns a nonzero value indicating the error.
If the wordexp() function returns the error value WRDE_NOSPACE, then
the expression in the pwordexp parameter is updated to reflect any
words that were successfully expanded. In other cases, the pwordexp
parameter is not modified.
The wordfree() function returns no value.
FILES
Defines word expansion macros, data types, and functions.
SEE ALSO
Functions: glob(3)
Standards: standards(5)wordexp(3)
