]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) |
3 | .\" | |
e4a74ca8 | 4 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
fea681da | 5 | .\" |
4c1c5274 | 6 | .TH wordexp 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
7 | .SH NAME |
8 | wordexp, wordfree \- perform word expansion like a posix-shell | |
05daf905 AC |
9 | .SH LIBRARY |
10 | Standard C library | |
8fc3b2cf | 11 | .RI ( libc ", " \-lc ) |
fea681da | 12 | .SH SYNOPSIS |
ff21c173 | 13 | .nf |
fea681da | 14 | .B "#include <wordexp.h>" |
68e4db0a | 15 | .PP |
e9de3084 AC |
16 | .BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \ |
17 | ", int " flags ); | |
fea681da | 18 | .BI "void wordfree(wordexp_t *" p ); |
ff21c173 | 19 | .fi |
68e4db0a | 20 | .PP |
d39ad78f | 21 | .RS -4 |
cc4615cc MK |
22 | Feature Test Macro Requirements for glibc (see |
23 | .BR feature_test_macros (7)): | |
d39ad78f | 24 | .RE |
68e4db0a | 25 | .PP |
cc4615cc MK |
26 | .BR wordexp (), |
27 | .BR wordfree (): | |
1dd0d7b4 MK |
28 | .nf |
29 | _XOPEN_SOURCE | |
30 | .fi | |
fea681da MK |
31 | .SH DESCRIPTION |
32 | The function | |
63aa9df0 | 33 | .BR wordexp () |
fea681da MK |
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 | |
f19a0f03 | 39 | .I wordexp_t |
fea681da MK |
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 | |
f19a0f03 | 48 | .I size_t |
fea681da MK |
49 | that gives the number of words in the expansion of |
50 | .IR s . | |
51 | The field | |
52 | .I we_wordv | |
53 | is a | |
5049da5b | 54 | .I "char\ **" |
fea681da MK |
55 | that points to the array of words found. |
56 | The field | |
57 | .I we_offs | |
58 | of type | |
f19a0f03 | 59 | .I size_t |
fea681da MK |
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. | |
dd3568a1 | 65 | .PP |
c13182ef | 66 | The function |
63aa9df0 | 67 | .BR wordfree () |
c13182ef MK |
68 | frees the allocated memory again. |
69 | More precisely, it does not free | |
fea681da MK |
70 | its argument, but it frees the array |
71 | .I we_wordv | |
72 | and the strings that points to. | |
73d8cece | 73 | .SS The string argument |
fea681da MK |
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 | |
c13182ef | 79 | parameters. |
7f2a7537 | 80 | In particular, there must not be any unescaped |
fea681da MK |
81 | newline or |, &, ;, <, >, (, ), {, } characters |
82 | outside a command substitution or parameter substitution context. | |
dd3568a1 | 83 | .PP |
fea681da MK |
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. | |
73d8cece | 89 | .SS The expansion |
fea681da | 90 | The expansion done consists of the following stages: |
3f029bc9 | 91 | tilde expansion (replacing \[ti]user by user's home directory), |
fea681da | 92 | variable substitution (replacing $FOO by the value of the environment |
84c517a4 | 93 | variable FOO), command substitution (replacing $(command) or \`command\` |
fea681da MK |
94 | by the output of command), arithmetic expansion, field splitting, |
95 | wildcard expansion, quote removal. | |
dd3568a1 | 96 | .PP |
fea681da | 97 | The result of expansion of special parameters |
8c383102 | 98 | ($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified. |
dd3568a1 | 99 | .PP |
fea681da | 100 | Field splitting is done using the environment variable $IFS. |
735334d4 | 101 | If it is not set, the field separators are space, tab, and newline. |
73d8cece | 102 | .SS The output array |
fea681da MK |
103 | The array |
104 | .I we_wordv | |
105 | contains the words found, followed by a NULL. | |
73d8cece | 106 | .SS The flags argument |
fea681da MK |
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 | |
c02d27b6 | 114 | .B WRDE_DOOFFS |
fea681da MK |
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 | |
c02d27b6 | 122 | .B WRDE_NOCMD |
fea681da MK |
123 | Don't do command substitution. |
124 | .TP | |
125 | .B WRDE_REUSE | |
c4bb193f | 126 | The argument |
fea681da MK |
127 | .I p |
128 | resulted from a previous call to | |
63aa9df0 | 129 | .BR wordexp (), |
fea681da | 130 | and |
63aa9df0 | 131 | .BR wordfree () |
c13182ef MK |
132 | was not called. |
133 | Reuse the allocated storage. | |
fea681da MK |
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. | |
47297adb | 146 | .SH RETURN VALUE |
3cf29587 MK |
147 | On success, |
148 | .BR wordexp () | |
149 | returns 0. | |
150 | On failure, | |
151 | .BR wordexp () | |
152 | returns one of the following nonzero values: | |
fea681da | 153 | .TP |
c13182ef | 154 | .B WRDE_BADCHAR |
fea681da MK |
155 | Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }. |
156 | .TP | |
157 | .B WRDE_BADVAL | |
f3fef736 MK |
158 | An undefined shell variable was referenced, and the |
159 | .B WRDE_UNDEF | |
160 | flag | |
fea681da MK |
161 | told us to consider this an error. |
162 | .TP | |
163 | .B WRDE_CMDSUB | |
62b1156b | 164 | Command substitution requested, but the |
f3fef736 MK |
165 | .B WRDE_NOCMD |
166 | flag told us to consider this an error. | |
fea681da MK |
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. | |
afe3272b ZL |
174 | .SH ATTRIBUTES |
175 | For an explanation of the terms used in this section, see | |
176 | .BR attributes (7). | |
177 | .TS | |
178 | allbox; | |
c466875e | 179 | lb lb lbx |
afe3272b ZL |
180 | l l l. |
181 | Interface Attribute Value | |
182 | T{ | |
9e54434e BR |
183 | .na |
184 | .nh | |
afe3272b ZL |
185 | .BR wordexp () |
186 | T} Thread safety T{ | |
9e54434e BR |
187 | .na |
188 | .nh | |
afe3272b | 189 | MT-Unsafe race:utent const:env |
afe3272b ZL |
190 | env sig:ALRM timer locale |
191 | T} | |
192 | T{ | |
9e54434e BR |
193 | .na |
194 | .nh | |
afe3272b ZL |
195 | .BR wordfree () |
196 | T} Thread safety MT-Safe | |
197 | .TE | |
847e0d88 | 198 | .sp 1 |
afe3272b ZL |
199 | In the above table, |
200 | .I utent | |
201 | in | |
202 | .I race:utent | |
203 | signifies that if any of the functions | |
204 | .BR setutent (3), | |
205 | .BR getutent (3), | |
206 | or | |
207 | .BR endutent (3) | |
208 | are used in parallel in different threads of a program, | |
209 | then data races could occur. | |
bf7bc8b8 | 210 | .BR wordexp () |
afe3272b ZL |
211 | calls those functions, |
212 | so we use race:utent to remind users. | |
3113c7f3 | 213 | .SH STANDARDS |
4131356c AC |
214 | POSIX.1-2008. |
215 | .SH HISTORY | |
216 | POSIX.1-2001. | |
217 | glibc 2.1. | |
a14af333 | 218 | .SH EXAMPLES |
894d8eb5 MK |
219 | The output of the following example program |
220 | is approximately that of "ls [a-c]*.c". | |
dd3568a1 | 221 | .PP |
b0b6ab4e | 222 | .\" SRC BEGIN (wordexp.c) |
a2b7a144 | 223 | .EX |
894d8eb5 MK |
224 | #include <stdio.h> |
225 | #include <stdlib.h> | |
226 | #include <wordexp.h> | |
fe5dba13 | 227 | \& |
894d8eb5 | 228 | int |
7ffb8e37 | 229 | main(void) |
894d8eb5 MK |
230 | { |
231 | wordexp_t p; | |
232 | char **w; | |
fe5dba13 | 233 | \& |
72da9ef1 | 234 | wordexp("[a\-c]*.c", &p, 0); |
894d8eb5 | 235 | w = p.we_wordv; |
b42296e4 | 236 | for (size_t i = 0; i < p.we_wordc; i++) |
31a6818e | 237 | printf("%s\en", w[i]); |
894d8eb5 MK |
238 | wordfree(&p); |
239 | exit(EXIT_SUCCESS); | |
240 | } | |
a2b7a144 | 241 | .EE |
b0b6ab4e | 242 | .\" SRC END |
47297adb | 243 | .SH SEE ALSO |
fea681da MK |
244 | .BR fnmatch (3), |
245 | .BR glob (3) |