2 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .TH wordexp 3 (date) "Linux man-pages (unreleased)"
8 wordexp, wordfree \- perform word expansion like a posix-shell
11 .RI ( libc ", " \-lc )
14 .B "#include <wordexp.h>"
16 .BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \
18 .BI "void wordfree(wordexp_t *" p );
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
34 performs a shell-like expansion of the string
36 and returns the result in the structure pointed to by
40 is a structure that at least has the fields
49 that gives the number of words in the expansion of
55 that points to the array of words found.
60 is sometimes (depending on
62 see below) used to indicate the number of initial elements in the
64 array that should be filled with NULLs.
68 frees the allocated memory again.
69 More precisely, it does not free
70 its argument, but it frees the array
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
76 of the parameters to a command, the string
78 must not contain characters that would be illegal in shell command
80 In particular, there must not be any unescaped
81 newline or |, &, ;, <, >, (, ), {, } characters
82 outside a command substitution or parameter substitution context.
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.
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.
97 The result of expansion of special parameters
98 ($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified.
100 Field splitting is done using the environment variable $IFS.
101 If it is not set, the field separators are space, tab, and newline.
105 contains the words found, followed by a NULL.
106 .SS The flags argument
109 argument is a bitwise inclusive OR of the following values:
112 Append the words found to the array resulting from a previous call.
117 initial NULLs in the array
119 (These are not counted in the returned
123 Don't do command substitution.
128 resulted from a previous call to
133 Reuse the allocated storage.
136 Normally during command substitution
140 This flag specifies that
142 is not to be redirected.
145 Consider it an error if an undefined shell variable is expanded.
152 returns one of the following nonzero values:
155 Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
158 An undefined shell variable was referenced, and the
161 told us to consider this an error.
164 Command substitution requested, but the
166 flag told us to consider this an error.
172 Shell syntax error, such as unbalanced parentheses or
175 For an explanation of the terms used in this section, see
181 Interface Attribute Value
189 MT-Unsafe race:utent const:env
190 env sig:ALRM timer locale
196 T} Thread safety MT-Safe
203 signifies that if any of the functions
208 are used in parallel in different threads of a program,
209 then data races could occur.
211 calls those functions,
212 so we use race:utent to remind users.
219 The output of the following example program
220 is approximately that of "ls [a-c]*.c".
222 .\" SRC BEGIN (wordexp.c)
234 wordexp("[a\-c]*.c", &p, 0);
236 for (size_t i = 0; i < p.we_wordc; i++)
237 printf("%s\en", w[i]);