README: Update links
[man-pages.git] / man3 / wordexp.3
blob94a2a393bd990e433525691edc807dd4a5122235
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>"
16 .BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \
17 ", int " flags );
18 .BI "void wordfree(wordexp_t *" p );
19 .fi
21 .RS -4
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
24 .RE
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.
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.
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.
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.
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
108 .I flag
109 argument is a bitwise inclusive OR of the following values:
111 .B WRDE_APPEND
112 Append the words found to the array resulting from a previous call.
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 .)
122 .B WRDE_NOCMD
123 Don't do command substitution.
125 .B WRDE_REUSE
126 The argument
127 .I p
128 resulted from a previous call to
129 .BR wordexp (),
131 .BR wordfree ()
132 was not called.
133 Reuse the allocated storage.
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.
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:
154 .B WRDE_BADCHAR
155 Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
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.
163 .B WRDE_CMDSUB
164 Command substitution requested, but the
165 .B WRDE_NOCMD
166 flag told us to consider this an error.
168 .B WRDE_NOSPACE
169 Out of memory.
171 .B WRDE_SYNTAX
172 Shell syntax error, such as unbalanced parentheses or
173 unmatched quotes.
174 .SH ATTRIBUTES
175 For an explanation of the terms used in this section, see
176 .BR attributes (7).
178 allbox;
179 lb lb lbx
180 l l l.
181 Interface       Attribute       Value
185 .BR wordexp ()
186 T}      Thread safety   T{
189 MT-Unsafe race:utent const:env
190 env sig:ALRM timer locale
195 .BR wordfree ()
196 T}      Thread safety   MT-Safe
199 In the above table,
200 .I utent
202 .I race:utent
203 signifies that if any of the functions
204 .BR setutent (3),
205 .BR getutent (3),
207 .BR endutent (3)
208 are used in parallel in different threads of a program,
209 then data races could occur.
210 .BR wordexp ()
211 calls those functions,
212 so we use race:utent to remind users.
213 .SH STANDARDS
214 POSIX.1-2008.
215 .SH HISTORY
216 POSIX.1-2001.
217 glibc 2.1.
218 .SH EXAMPLES
219 The output of the following example program
220 is approximately that of "ls [a-c]*.c".
222 .\" SRC BEGIN (wordexp.c)
224 #include <stdio.h>
225 #include <stdlib.h>
226 #include <wordexp.h>
229 main(void)
231     wordexp_t p;
232     char **w;
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);
242 .\" SRC END
243 .SH SEE ALSO
244 .BR fnmatch (3),
245 .BR glob (3)