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