| NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON | The Linux Programming Interface |
WORDEXP(3) Linux Programmer's Manual WORDEXP(3)
wordexp, wordfree - perform word expansion like a posix-shell
#include <wordexp.h>
int wordexp(const char *s, wordexp_t *p, int flags);
void wordfree(wordexp_t *p);
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
wordexp(), wordfree(): _XOPEN_SOURCE
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.
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 unescaped 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 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 array we_wordv contains the words found, followed by a NULL.
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.
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.
wordexp() and wordfree() are provided in glibc since version 2.1.
POSIX.1-2001.
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);
}
fnmatch(3), glob(3)
This page is part of release 3.32 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/.
2008-07-14 WORDEXP(3)
HTML rendering created 2010-12-03 by Michael Kerrisk, author of The Linux Programming Interface