The function
wordexp()
performs a shell-like expansion of the string
s
and returns the result in the structure pointed to by
p.
The data type
wordexp_t
is a structure that at least has the fields
we_wordc,
we_wordv,
and
we_offs.
The field
we_wordc
is a
size_t
that gives the number of words in the expansion of
s.
The field
we_wordv
is a
char **
that points to the array of words found.
The field
we_offs
of type
size_t
is sometimes (depending on
flags,
see below) used to indicate the number of initial elements in the
we_wordv
array that should be filled with NULLs.
The function
wordfree()
frees the allocated memory again.
More precisely, it does not free
its argument, but it frees the array
we_wordv
and the strings that points to.
The string argument
Since the expansion is the same as the expansion by the shell (see
sh(1))
of the parameters to a command, the string
s
must not contain characters that would be illegal in shell command
parameters.
In particular, there must not be any non-escaped
newline or |, &, ;, <, >, (, ), {, } characters
outside a command substitution or parameter substitution context.
If the argument
s
contains a word that starts with an unquoted comment character #,
then it is unspecified whether that word and all following words
are ignored, or the # is treated as a non-comment character.
The expansion
The expansion done consists of the following stages:
tilde expansion (replacing ~user by user's home directory),
variable substitution (replacing $FOO by the value of the environment
variable FOO), command substitution (replacing $(command) or `command`
by the output of command), arithmetic expansion, field splitting,
wildcard expansion, quote removal.
The result of expansion of special parameters
($@, $*, $#, $?, $-, $$, $!, $0) is unspecified.
Field splitting is done using the environment variable $IFS.
If it is not set, the field separators are space, tab and newline.
The output array
The array
we_wordv
contains the words found, followed by a NULL.
The flags argument
The
flag
argument is a bitwise inclusive OR of the following values:
WRDE_APPEND
Append the words found to the array resulting from a previous call.
WRDE_DOOFFS
Insert
we_offs
initial NULLs in the array
we_wordv.
(These are not counted in the returned
we_wordc.)
WRDE_NOCMD
Don't do command substitution.
WRDE_REUSE
The argument
p
resulted from a previous call to
wordexp(),
and
wordfree()
was not called.
Reuse the allocated storage.
WRDE_SHOWERR
Normally during command substitution
stderr
is redirected to
/dev/null.
This flag specifies that
stderr
is not to be redirected.
WRDE_UNDEF
Consider it an error if an undefined shell variable is expanded.
RETURN VALUE
In case of success 0 is returned.
In case of error
one of the following five values is returned.
WRDE_BADCHAR
Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
WRDE_BADVAL
An undefined shell variable was referenced, and the
WRDE_UNDEF
flag
told us to consider this an error.
WRDE_CMDSUB
Command substitution occurred, and the
WRDE_NOCMD
flag told us to consider this an error.
WRDE_NOSPACE
Out of memory.
WRDE_SYNTAX
Shell syntax error, such as unbalanced parentheses or
unmatched quotes.
VERSIONS
wordexp()
and
wordfree()
are provided in glibc since version 2.1.
CONFORMING TO
POSIX.1-2001.
EXAMPLE
The output of the following example program
is approximately that of "ls [a-c]*.c".
#include <stdio.h>
#include <stdlib.h>
#include <wordexp.h>
int
main(int argc, char **argv)
{
wordexp_t p;
char **w;
int i;
wordexp("[a-c]*.c", &p, 0);
w = p.we_wordv;
for (i=0; i < p.we_wordc; i++)
printf("%s\n", w[i]);
wordfree(&p);
exit(EXIT_SUCCESS);
}
This page is part of release 3.14 of the Linux
man-pages
project.
A description of the project,
and information about reporting bugs,
can be found at
http://www.kernel.org/doc/man-pages/.
