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 2021-03-22  "" "Linux Programmer's Manual"
  25 .SH NAME
  26 wordexp, wordfree \- perform word expansion like a posix-shell
  27 .SH SYNOPSIS
  28 .nf
  29 .B "#include <wordexp.h>"
  30 .PP
  31 .BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \
  32 ", int " flags );
  33 .BI "void wordfree(wordexp_t *" p );
  34 .fi
  35 .PP
  36 .RS -4
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .RE
  40 .PP
  41 .BR wordexp (),
  42 .BR wordfree ():
  43 .nf
  44     _XOPEN_SOURCE
  45 .fi
  46 .SH DESCRIPTION
  47 The function
  48 .BR wordexp ()
  49 performs a shell-like expansion of the string
  50 .I s
  51 and returns the result in the structure pointed to by
  52 .IR p .
  53 The data type
  54 .I wordexp_t
  55 is a structure that at least has the fields
  56 .IR we_wordc ,
  57 .IR we_wordv ,
  58 and
  59 .IR we_offs .
  60 The field
  61 .I we_wordc
  62 is a
  63 .I size_t
  64 that gives the number of words in the expansion of
  65 .IR s .
  66 The field
  67 .I we_wordv
  68 is a
  69 .I "char\ **"
  70 that points to the array of words found.
  71 The field
  72 .I we_offs
  73 of type
  74 .I size_t
  75 is sometimes (depending on
  76 .IR flags ,
  77 see below) used to indicate the number of initial elements in the
  78 .I we_wordv
  79 array that should be filled with NULLs.
  80 .PP
  81 The function
  82 .BR wordfree ()
  83 frees the allocated memory again.
  84 More precisely, it does not free
  85 its argument, but it frees the array
  86 .I we_wordv
  87 and the strings that points to.
  88 .SS The string argument
  89 Since the expansion is the same as the expansion by the shell (see
  90 .BR sh (1))
  91 of the parameters to a command, the string
  92 .I s
  93 must not contain characters that would be illegal in shell command
  94 parameters.
  95 In particular, there must not be any unescaped
  96 newline or |, &, ;, <, >, (, ), {, } characters
  97 outside a command substitution or parameter substitution context.
  98 .PP
  99 If the argument
 100 .I s
 101 contains a word that starts with an unquoted comment character #,
 102 then it is unspecified whether that word and all following words
 103 are ignored, or the # is treated as a non-comment character.
 104 .SS The expansion
 105 The expansion done consists of the following stages:
 106 tilde expansion (replacing \(tiuser by user's home directory),
 107 variable substitution (replacing $FOO by the value of the environment
 108 variable FOO), command substitution (replacing $(command) or \`command\`
 109 by the output of command), arithmetic expansion, field splitting,
 110 wildcard expansion, quote removal.
 111 .PP
 112 The result of expansion of special parameters
 113 ($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified.
 114 .PP
 115 Field splitting is done using the environment variable $IFS.
 116 If it is not set, the field separators are space, tab, and newline.
 117 .SS The output array
 118 The array
 119 .I we_wordv
 120 contains the words found, followed by a NULL.
 121 .SS The flags argument
 122 The
 123 .I flag
 124 argument is a bitwise inclusive OR of the following values:
 125 .TP
 126 .B WRDE_APPEND
 127 Append the words found to the array resulting from a previous call.
 128 .TP
 129 .B WRDE_DOOFFS
 130 Insert
 131 .I we_offs
 132 initial NULLs in the array
 133 .IR we_wordv .
 134 (These are not counted in the returned
 135 .IR we_wordc .)
 136 .TP
 137 .B WRDE_NOCMD
 138 Don't do command substitution.
 139 .TP
 140 .B WRDE_REUSE
 141 The argument
 142 .I p
 143 resulted from a previous call to
 144 .BR wordexp (),
 145 and
 146 .BR wordfree ()
 147 was not called.
 148 Reuse the allocated storage.
 149 .TP
 150 .B WRDE_SHOWERR
 151 Normally during command substitution
 152 .I stderr
 153 is redirected to
 154 .IR /dev/null .
 155 This flag specifies that
 156 .I stderr
 157 is not to be redirected.
 158 .TP
 159 .B WRDE_UNDEF
 160 Consider it an error if an undefined shell variable is expanded.
 161 .SH RETURN VALUE
 162 On success,
 163 .BR wordexp ()
 164 returns 0.
 165 On failure,
 166 .BR wordexp ()
 167 returns one of the following nonzero values:
 168 .TP
 169 .B WRDE_BADCHAR
 170 Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
 171 .TP
 172 .B WRDE_BADVAL
 173 An undefined shell variable was referenced, and the
 174 .B WRDE_UNDEF
 175 flag
 176 told us to consider this an error.
 177 .TP
 178 .B WRDE_CMDSUB
 179 Command substitution requested, but the
 180 .B WRDE_NOCMD
 181 flag told us to consider this an error.
 182 .TP
 183 .B WRDE_NOSPACE
 184 Out of memory.
 185 .TP
 186 .B WRDE_SYNTAX
 187 Shell syntax error, such as unbalanced parentheses or
 188 unmatched quotes.
 189 .SH VERSIONS
 190 .BR wordexp ()
 191 and
 192 .BR wordfree ()
 193 are provided in glibc since version 2.1.
 194 .SH ATTRIBUTES
 195 For an explanation of the terms used in this section, see
 196 .BR attributes (7).
 197 .ad l
 198 .nh
 199 .TS
 200 allbox;
 201 lb lb lbx
 202 l l l.
 203 Interface       Attribute       Value
 204 T{
 205 .BR wordexp ()
 206 T}      Thread safety   T{
 207 MT-Unsafe race:utent const:env
 208 env sig:ALRM timer locale
 209 T}
 210 T{
 211 .BR wordfree ()
 212 T}      Thread safety   MT-Safe
 213 .TE
 214 .hy
 215 .ad
 216 .sp 1
 217 In the above table,
 218 .I utent
 219 in
 220 .I race:utent
 221 signifies that if any of the functions
 222 .BR setutent (3),
 223 .BR getutent (3),
 224 or
 225 .BR endutent (3)
 226 are used in parallel in different threads of a program,
 227 then data races could occur.
 228 .BR wordexp ()
 229 calls those functions,
 230 so we use race:utent to remind users.
 231 .SH CONFORMING TO
 232 POSIX.1-2001, POSIX.1-2008.
 233 .SH EXAMPLES
 234 The output of the following example program
 235 is approximately that of "ls [a-c]*.c".
 236 .PP
 237 .EX
 238 #include <stdio.h>
 239 #include <stdlib.h>
 240 #include <wordexp.h>
 241
 242 int
 243 main(int argc, char *argv[])
 244 {
 245     wordexp_t p;
 246     char **w;
 247
 248     wordexp("[a\-c]*.c", &p, 0);
 249     w = p.we_wordv;
 250     for (int i = 0; i < p.we_wordc; i++)
 251         printf("%s\en", w[i]);
 252     wordfree(&p);
 253     exit(EXIT_SUCCESS);
 254 }
 255 .EE
 256 .SH SEE ALSO
 257 .BR fnmatch (3),
 258 .BR glob (3)