original/man3/wordexp.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .TH WORDEXP 3 2008-07-14  "" "Linux Programmer's Manual"
  25 .SH NAME
  26 wordexp, wordfree \- perform word expansion like a posix-shell
  27 .SH SYNOPSIS
  28 .B "#include <wordexp.h>"
  29 .sp
  30 .BI "int wordexp(const char *" s ", wordexp_t *" p ", int " flags );
  31 .sp
  32 .BI "void wordfree(wordexp_t *" p );
  33 .sp
  34 .in -4n
  35 Feature Test Macro Requirements for glibc (see
  36 .BR feature_test_macros (7)):
  37 .in
  38 .sp
  39 .BR wordexp (),
  40 .BR wordfree ():
  41 _XOPEN_SOURCE
  42 .SH DESCRIPTION
  43 The function
  44 .BR wordexp ()
  45 performs a shell-like expansion of the string
  46 .I s
  47 and returns the result in the structure pointed to by
  48 .IR p .
  49 The data type
  50 .I wordexp_t
  51 is a structure that at least has the fields
  52 .IR we_wordc ,
  53 .IR we_wordv ,
  54 and
  55 .IR we_offs .
  56 The field
  57 .I we_wordc
  58 is a
  59 .I size_t
  60 that gives the number of words in the expansion of
  61 .IR s .
  62 The field
  63 .I we_wordv
  64 is a
  65 .I "char\ **"
  66 that points to the array of words found.
  67 The field
  68 .I we_offs
  69 of type
  70 .I size_t
  71 is sometimes (depending on
  72 .IR flags ,
  73 see below) used to indicate the number of initial elements in the
  74 .I we_wordv
  75 array that should be filled with NULLs.
  76 .LP
  77 The function
  78 .BR wordfree ()
  79 frees the allocated memory again.
  80 More precisely, it does not free
  81 its argument, but it frees the array
  82 .I we_wordv
  83 and the strings that points to.
  84 .SS The string argument
  85 Since the expansion is the same as the expansion by the shell (see
  86 .BR sh (1))
  87 of the parameters to a command, the string
  88 .I s
  89 must not contain characters that would be illegal in shell command
  90 parameters.
  91 In particular, there must not be any unescaped
  92 newline or |, &, ;, <, >, (, ), {, } characters
  93 outside a command substitution or parameter substitution context.
  94 .LP
  95 If the argument
  96 .I s
  97 contains a word that starts with an unquoted comment character #,
  98 then it is unspecified whether that word and all following words
  99 are ignored, or the # is treated as a non-comment character.
 100 .SS The expansion
 101 The expansion done consists of the following stages:
 102 tilde expansion (replacing ~user by user's home directory),
 103 variable substitution (replacing $FOO by the value of the environment
 104 variable FOO), command substitution (replacing $(command) or \`command\`
 105 by the output of command), arithmetic expansion, field splitting,
 106 wildcard expansion, quote removal.
 107 .LP
 108 The result of expansion of special parameters
 109 ($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified.
 110 .LP
 111 Field splitting is done using the environment variable $IFS.
 112 If it is not set, the field separators are space, tab and newline.
 113 .SS The output array
 114 The array
 115 .I we_wordv
 116 contains the words found, followed by a NULL.
 117 .SS The flags argument
 118 The
 119 .I flag
 120 argument is a bitwise inclusive OR of the following values:
 121 .TP
 122 .B WRDE_APPEND
 123 Append the words found to the array resulting from a previous call.
 124 .TP
 125 .B WRDE_DOOFFS
 126 Insert
 127 .I we_offs
 128 initial NULLs in the array
 129 .IR we_wordv .
 130 (These are not counted in the returned
 131 .IR we_wordc .)
 132 .TP
 133 .B WRDE_NOCMD
 134 Don't do command substitution.
 135 .TP
 136 .B WRDE_REUSE
 137 The argument
 138 .I p
 139 resulted from a previous call to
 140 .BR wordexp (),
 141 and
 142 .BR wordfree ()
 143 was not called.
 144 Reuse the allocated storage.
 145 .TP
 146 .B WRDE_SHOWERR
 147 Normally during command substitution
 148 .I stderr
 149 is redirected to
 150 .IR /dev/null .
 151 This flag specifies that
 152 .I stderr
 153 is not to be redirected.
 154 .TP
 155 .B WRDE_UNDEF
 156 Consider it an error if an undefined shell variable is expanded.
 157 .SH RETURN VALUE
 158 In case of success 0 is returned.
 159 In case of error
 160 one of the following five values is returned.
 161 .TP
 162 .B WRDE_BADCHAR
 163 Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
 164 .TP
 165 .B WRDE_BADVAL
 166 An undefined shell variable was referenced, and the
 167 .B WRDE_UNDEF
 168 flag
 169 told us to consider this an error.
 170 .TP
 171 .B WRDE_CMDSUB
 172 Command substitution occurred, and the
 173 .B WRDE_NOCMD
 174 flag told us to consider this an error.
 175 .TP
 176 .B WRDE_NOSPACE
 177 Out of memory.
 178 .TP
 179 .B WRDE_SYNTAX
 180 Shell syntax error, such as unbalanced parentheses or
 181 unmatched quotes.
 182 .SH VERSIONS
 183 .BR wordexp ()
 184 and
 185 .BR wordfree ()
 186 are provided in glibc since version 2.1.
 187 .SH CONFORMING TO
 188 POSIX.1-2001.
 189 .SH EXAMPLE
 190 The output of the following example program
 191 is approximately that of "ls [a-c]*.c".
 192 .LP
 193 .nf
 194 #include <stdio.h>
 195 #include <stdlib.h>
 196 #include <wordexp.h>
 197
 198 int
 199 main(int argc, char **argv)
 200 {
 201     wordexp_t p;
 202     char **w;
 203     int i;
 204
 205     wordexp("[a\-c]*.c", &p, 0);
 206     w = p.we_wordv;
 207     for (i = 0; i < p.we_wordc; i++)
 208         printf("%s\en", w[i]);
 209     wordfree(&p);
 210     exit(EXIT_SUCCESS);
 211 }
 212 .fi
 213 .SH SEE ALSO
 214 .BR fnmatch (3),
 215 .BR glob (3)
 216 .SH COLOPHON
 217 This page is part of release 3.67 of the Linux
 218 .I man-pages
 219 project.
 220 A description of the project,
 221 information about reporting bugs,
 222 and the latest version of this page,
 223 can be found at
 224 \%http://www.kernel.org/doc/man\-pages/.