1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
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.
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.
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.
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/>.
24 .TH WORDEXP 3 2017-09-15 "" "Linux Programmer's Manual"
26 wordexp, wordfree \- perform word expansion like a posix-shell
28 .B "#include <wordexp.h>"
30 .BI "int wordexp(const char *" s ", wordexp_t *" p ", int " flags );
32 .BI "void wordfree(wordexp_t *" p );
35 Feature Test Macro Requirements for glibc (see
36 .BR feature_test_macros (7)):
45 performs a shell-like expansion of the string
47 and returns the result in the structure pointed to by
51 is a structure that at least has the fields
60 that gives the number of words in the expansion of
66 that points to the array of words found.
71 is sometimes (depending on
73 see below) used to indicate the number of initial elements in the
75 array that should be filled with NULLs.
79 frees the allocated memory again.
80 More precisely, it does not free
81 its argument, but it frees the array
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
87 of the parameters to a command, the string
89 must not contain characters that would be illegal in shell command
91 In particular, there must not be any unescaped
92 newline or |, &, ;, <, >, (, ), {, } characters
93 outside a command substitution or parameter substitution context.
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.
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.
108 The result of expansion of special parameters
109 ($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified.
111 Field splitting is done using the environment variable $IFS.
112 If it is not set, the field separators are space, tab and newline.
116 contains the words found, followed by a NULL.
117 .SS The flags argument
120 argument is a bitwise inclusive OR of the following values:
123 Append the words found to the array resulting from a previous call.
128 initial NULLs in the array
130 (These are not counted in the returned
134 Don't do command substitution.
139 resulted from a previous call to
144 Reuse the allocated storage.
147 Normally during command substitution
151 This flag specifies that
153 is not to be redirected.
156 Consider it an error if an undefined shell variable is expanded.
158 In case of success 0 is returned.
160 one of the following five values is returned.
163 Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
166 An undefined shell variable was referenced, and the
169 told us to consider this an error.
172 Command substitution requested, but the
174 flag told us to consider this an error.
180 Shell syntax error, such as unbalanced parentheses or
186 are provided in glibc since version 2.1.
188 For an explanation of the terms used in this section, see
194 Interface Attribute Value
198 MT-Unsafe race:utent const:env
200 env sig:ALRM timer locale
204 T} Thread safety MT-Safe
211 signifies that if any of the functions
216 are used in parallel in different threads of a program,
217 then data races could occur.
219 calls those functions,
220 so we use race:utent to remind users.
222 POSIX.1-2001, POSIX.1-2008.
224 The output of the following example program
225 is approximately that of "ls [a-c]*.c".
233 main(int argc, char **argv)
239 wordexp("[a\-c]*.c", &p, 0);
241 for (i = 0; i < p.we_wordc; i++)
242 printf("%s\en", w[i]);