1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .TH WORDEXP 3 2021-08-27 GNU "Linux Programmer's Manual"
7 wordexp, wordfree \- perform word expansion like a posix-shell
10 .RI ( libc ", " \-lc )
13 .B "#include <wordexp.h>"
15 .BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \
17 .BI "void wordfree(wordexp_t *" p );
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
33 performs a shell-like expansion of the string
35 and returns the result in the structure pointed to by
39 is a structure that at least has the fields
48 that gives the number of words in the expansion of
54 that points to the array of words found.
59 is sometimes (depending on
61 see below) used to indicate the number of initial elements in the
63 array that should be filled with NULLs.
67 frees the allocated memory again.
68 More precisely, it does not free
69 its argument, but it frees the array
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
75 of the parameters to a command, the string
77 must not contain characters that would be illegal in shell command
79 In particular, there must not be any unescaped
80 newline or |, &, ;, <, >, (, ), {, } characters
81 outside a command substitution or parameter substitution context.
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.
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.
96 The result of expansion of special parameters
97 ($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified.
99 Field splitting is done using the environment variable $IFS.
100 If it is not set, the field separators are space, tab, and newline.
104 contains the words found, followed by a NULL.
105 .SS The flags argument
108 argument is a bitwise inclusive OR of the following values:
111 Append the words found to the array resulting from a previous call.
116 initial NULLs in the array
118 (These are not counted in the returned
122 Don't do command substitution.
127 resulted from a previous call to
132 Reuse the allocated storage.
135 Normally during command substitution
139 This flag specifies that
141 is not to be redirected.
144 Consider it an error if an undefined shell variable is expanded.
151 returns one of the following nonzero values:
154 Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
157 An undefined shell variable was referenced, and the
160 told us to consider this an error.
163 Command substitution requested, but the
165 flag told us to consider this an error.
171 Shell syntax error, such as unbalanced parentheses or
177 are provided in glibc since version 2.1.
179 For an explanation of the terms used in this section, see
187 Interface Attribute Value
191 MT-Unsafe race:utent const:env
192 env sig:ALRM timer locale
196 T} Thread safety MT-Safe
205 signifies that if any of the functions
210 are used in parallel in different threads of a program,
211 then data races could occur.
213 calls those functions,
214 so we use race:utent to remind users.
216 POSIX.1-2001, POSIX.1-2008.
218 The output of the following example program
219 is approximately that of "ls [a-c]*.c".
227 main(int argc, char *argv[])
232 wordexp("[a\-c]*.c", &p, 0);
234 for (int i = 0; i < p.we_wordc; i++)
235 printf("%s\en", w[i]);