|
|
Command option substitution?
|
|
|
|
WORDEXP(3) Linux Programmer's Manual WORDEXP(3) NAME
wordexp, wordfree - perform word expansion like a posix-shell SYNOPSIS
#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 DESCRIPTION
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 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 fol- lowing 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 ", w[i]); wordfree(&p); exit(EXIT_SUCCESS); } SEE ALSO
fnmatch(3), glob(3) COLOPHON
This page is part of release 3.27 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)
