man3/wordexp.3

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