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); |
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.
First a small example. The output is approximately that of "ls [a-c]*.c".
#include <stdio.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);
}
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 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 flag
argument is a bitwise inclusive OR of the following
values:
WRDE_APPENDAppend the words found to the array resulting from a previous call.
WRDE_DOOFFSInsert we_offs initial NULLs
in the array we_wordv. (These are
not counted in the returned we_wordc.)
WRDE_NOCMDDon't do command substitution.
WRDE_REUSEThe parameter p resulted from a
previous call to wordexp(), and wordfree() was not called. Reuse
the allocated storage.
WRDE_SHOWERRNormally during command substitution stderr is redirected to /dev/null. This flag specifies that
stderr is not to be
redirected.
WRDE_UNDEFConsider 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_BADCHARIllegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
WRDE_BADVALAn undefined shell variable was referenced, and the WRDE_UNDEF flag told us to consider this an error.
WRDE_CMDSUBCommand substitution occurred, and the WRDE_NOCMD flag told us to consider this an error.
WRDE_NOSPACEOut of memory.
WRDE_SYNTAXShell syntax error, such as unbalanced parentheses or unmatched quotes.
|
|