wordexp, wordfree - Perform word expansions
#include <wordexp.h>
int wordexp(
const char *words,
wordexp_t *pwordexp,
int flags ); void wordfree(
wordexp_t *pwordexp );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
wordexp(), wordfree(): XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
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.
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 representing the parameters to a command.
Therefore, the words arameter cannot 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 character, 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 expansion is a
separate word in the list specified by the pwordexp arameter.
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 substitution,
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 contain 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 subsequent 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. Therefore, 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 subsequent 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 wordexp() 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 |, & , ;, <, >, newline, 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 example, 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 commands. Disallowing unquoted shell
special characters also prevents unwanted side effects
such as executing a command or writing to a file.
The wordexp() function can cause a signal to be issued.
If a user program catches the signal, wordexp() may
return an error.
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.
Defines word expansion macros, data types, and functions.
Functions: glob(3)
Standards: standards(5)
wordexp(3)
[ Back ] |
