man3/wordexp.3

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