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