Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1989, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" Guido van Rossum. | |
6 | .\" Redistribution and use in source and binary forms, with or without | |
7 | .\" modification, are permitted provided that the following conditions | |
8 | .\" are met: | |
9 | .\" 1. Redistributions of source code must retain the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer. | |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer in the | |
13 | .\" documentation and/or other materials provided with the distribution. | |
14 | .\" 3. All advertising materials mentioning features or use of this software | |
15 | .\" must display the following acknowledgement: | |
16 | .\" This product includes software developed by the University of | |
17 | .\" California, Berkeley and its contributors. | |
18 | .\" 4. Neither the name of the University nor the names of its contributors | |
19 | .\" may be used to endorse or promote products derived from this software | |
20 | .\" without specific prior written permission. | |
21 | .\" | |
22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
32 | .\" SUCH DAMAGE. | |
33 | .\" | |
78ed81a3 | 34 | .\" @(#)glob.3 5.7 (Berkeley) 12/2/92 |
15637ed4 | 35 | .\" |
78ed81a3 | 36 | .Dd December 2, 1992 |
15637ed4 RG |
37 | .Dt GLOB 3 |
38 | .Os | |
39 | .Sh NAME | |
40 | .Nm glob , | |
41 | .Nm globfree | |
42 | .Nd generate pathnames matching a pattern | |
43 | .Sh SYNOPSIS | |
44 | .Fd #include <glob.h> | |
45 | .Ft int | |
46 | .Fn glob "const char *pattern" "int flags" "const int (*errfunc)(char *, int)" "glob_t *pglob" | |
47 | .Ft void | |
48 | .Fn globfree "glob_t *pglob" | |
49 | .Sh DESCRIPTION | |
50 | The | |
51 | .Fn glob | |
52 | function | |
53 | is a pathname generator that implements the rules for file name pattern | |
54 | matching used by the shell. | |
55 | .Pp | |
56 | The include file | |
57 | .Pa glob.h | |
58 | defines the structure type | |
59 | .Fa glob_t , | |
60 | which contains at least the following fields: | |
61 | .Bd -literal | |
62 | typedef struct { | |
63 | int gl_pathc; /* count of total paths so far */ | |
64 | int gl_matchc; /* count of paths matching pattern */ | |
65 | int gl_offs; /* reserved at beginning of gl_pathv */ | |
66 | int gl_flags; /* returned flags */ | |
67 | char **gl_pathv; /* list of paths matching pattern */ | |
68 | } glob_t; | |
69 | .Ed | |
70 | .Pp | |
71 | The argument | |
72 | .Fa pattern | |
73 | is a pointer to a pathname pattern to be expanded. | |
74 | The | |
75 | .Fn glob | |
76 | argument | |
77 | matches all accessible pathnames against the pattern and creates | |
78 | a list of the pathnames that match. | |
79 | In order to have access to a pathname, | |
80 | .Fn glob | |
81 | requires search permission on every component of a path except the last | |
82 | and read permission on each directory of any filename component of | |
83 | .Fa pattern | |
84 | that contains any of the special characters | |
85 | .Ql * , | |
86 | .Ql ? | |
87 | or | |
88 | .Ql [ . | |
89 | .Pp | |
90 | The | |
91 | .Fn glob | |
92 | argument | |
93 | stores the number of matched pathnames into the | |
94 | .Fa gl_pathc | |
95 | field, and a pointer to a list of pointers to pathnames into the | |
96 | .Fa gl_pathv | |
97 | field. | |
98 | The first pointer after the last pathname is | |
99 | .Dv NULL . | |
100 | If the pattern does not match any pathnames, the returned number of | |
101 | matched paths is set to zero. | |
102 | .Pp | |
103 | It is the caller's responsibility to create the structure pointed to by | |
104 | .Fa pglob . | |
105 | The | |
106 | .Fn glob | |
107 | function allocates other space as needed, including the memory pointed | |
108 | to by | |
109 | .Fa gl_pathv . | |
110 | .Pp | |
111 | The argument | |
112 | .Fa flags | |
113 | is used to modify the behavior of | |
114 | .Fn glob . | |
115 | The value of | |
116 | .Fa flags | |
117 | is the bitwise inclusive | |
118 | .Tn OR | |
119 | of any of the following | |
120 | values defined in | |
121 | .Pa glob.h : | |
122 | .Bl -tag -width GLOB_NOCHECK | |
123 | .It Dv GLOB_APPEND | |
124 | Append pathnames generated to the ones from a previous call (or calls) | |
125 | to | |
126 | .Fn glob . | |
127 | The value of | |
128 | .Fa gl_pathc | |
129 | will be the total matches found by this call and the previous call(s). | |
130 | The pathnames are appended to, not merged with the pathnames returned by | |
131 | the previous call(s). | |
132 | Between calls, the caller must not change the setting of the | |
133 | .Dv GLOB_DOOFFS | |
134 | flag, nor change the value of | |
135 | .Fa gl_offs | |
136 | when | |
137 | .Dv GLOB_DOOFFS | |
138 | is set, nor (obviously) call | |
139 | .Fn globfree | |
140 | for | |
141 | .Fa pglob . | |
142 | .It Dv GLOB_DOOFFS | |
143 | Make use of the | |
144 | .Fa gl_offs | |
145 | field. | |
146 | If this flag is set, | |
147 | .Fa gl_offs | |
148 | is used to specify how many | |
149 | .Dv NULL | |
150 | pointers to prepend to the beginning | |
151 | of the | |
152 | .Fa gl_pathv | |
153 | field. | |
154 | In other words, | |
155 | .Fa gl_pathv | |
156 | will point to | |
157 | .Fa gl_offs | |
158 | .Dv NULL | |
159 | pointers, | |
160 | followed by | |
161 | .Fa gl_pathc | |
162 | pathname pointers, followed by a | |
163 | .Dv NULL | |
164 | pointer. | |
165 | .It Dv GLOB_ERR | |
166 | Causes | |
167 | .Fn glob | |
168 | to return when it encounters a directory that it cannot open or read. | |
169 | Ordinarily, | |
170 | .Fn glob | |
171 | continues to find matches. | |
172 | .It Dv GLOB_MARK | |
173 | Each pathname that is a directory that matches | |
174 | .Fa pattern | |
175 | has a slash | |
176 | appended. | |
177 | .It Dv GLOB_NOCHECK | |
178 | If | |
179 | .Fa pattern | |
180 | does not match any pathname, then | |
181 | .Fn glob | |
182 | returns a list | |
183 | consisting of only | |
184 | .Fa pattern , | |
185 | with the number of total pathnames is set to 1, and the number of matched | |
186 | pathnames set to 0. | |
187 | If | |
188 | .Dv GLOB_QUOTE | |
189 | is set, its effect is present in the pattern returned. | |
190 | .It Dv GLOB_NOMAGIC | |
191 | Is the same as | |
192 | .Dv GLOB_NOCHECK | |
193 | but it only appends the | |
194 | .Fa pattern | |
195 | if it does not contain any of the special characters ``*'', ``?'' or ``[''. | |
196 | .Dv GLOB_NOMAGIC | |
197 | is provided to simplify implementing the historic | |
198 | .Xr csh 1 | |
199 | globbing behavior and should probably not be used anywhere else. | |
200 | .It Dv GLOB_NOSORT | |
201 | By default, the pathnames are sorted in ascending | |
202 | .Tn ASCII | |
203 | order; | |
204 | this flag prevents that sorting (speeding up | |
205 | .Fn glob ) . | |
206 | .It Dv GLOB_QUOTE | |
207 | Use the backslash | |
208 | .Pq Ql \e | |
209 | character for quoting: every occurrence of | |
210 | a backslash followed by a character in the pattern is replaced by that | |
211 | character, avoiding any special interpretation of the character. | |
78ed81a3 | 212 | .It Dv GLOB_ALTDIRFUNC |
213 | The following additional fields in the pglob structure have been | |
214 | initialized with alternate functions for glob to use to open, read, | |
215 | and close directories and to get stat information on names found | |
216 | in those directories. | |
217 | .Bd -literal | |
218 | void *(*gl_opendir)(); | |
219 | struct dirent *(*gl_readdir)(); | |
220 | void (*gl_closedir)(); | |
221 | int (*gl_lstat)(); | |
222 | int (*gl_stat)(); | |
223 | .Ed | |
224 | .Pp | |
225 | This non-standard extension is provided to allow programs such | |
226 | as restore to provide globbing from directories stored on tape. | |
15637ed4 RG |
227 | .El |
228 | .Pp | |
229 | If, during the search, a directory is encountered that cannot be opened | |
230 | or read and | |
231 | .Fa errfunc | |
232 | is | |
233 | .Pf non- Dv NULL , | |
234 | .Fn glob | |
235 | calls | |
236 | .Fa (*errfunc)(path,errno) . | |
237 | This may be unintuitive: a pattern like | |
238 | .Ql */Makefile | |
239 | will try to | |
240 | .Xr stat 2 | |
241 | .Ql foo/Makefile | |
242 | even if | |
243 | .Ql foo | |
244 | is not a directory, resulting in a | |
245 | call to | |
246 | .Fa errfunc . | |
247 | The error routine can suppress this action by testing for | |
248 | .Dv ENOENT | |
249 | and | |
250 | .Dv ENOTDIR ; | |
251 | however, the | |
252 | .Dv GLOB_ERR | |
253 | flag will still cause an immediate | |
254 | return when this happens. | |
255 | .Pp | |
256 | If | |
257 | .Fa errfunc | |
258 | returns non-zero, | |
259 | .Fn glob | |
260 | stops the scan and returns | |
261 | .Dv GLOB_ABEND | |
262 | after setting | |
263 | .Fa gl_pathc | |
264 | and | |
265 | .Fa gl_pathv | |
266 | to reflect any paths already matched. | |
267 | This also happens if an error is encountered and | |
268 | .Dv GLOB_ERR | |
269 | is set in | |
270 | .Fa flags , | |
271 | regardless of the return value of | |
272 | .Fa errfunc , | |
273 | if called. | |
274 | If | |
275 | .Dv GLOB_ERR | |
276 | is not set and either | |
277 | .Fa errfunc | |
278 | is | |
279 | .Dv NULL | |
280 | or | |
281 | .Fa errfunc | |
282 | returns zero, the error is ignored. | |
283 | .Pp | |
284 | The | |
285 | .Fn globfree | |
286 | function frees any space associated with | |
287 | .Fa pglob | |
288 | from a previous call(s) to | |
289 | .Fn glob . | |
290 | .Sh RETURN VALUES | |
291 | On successful completion, | |
292 | .Fn glob | |
293 | returns zero. | |
294 | In addition the fields of | |
295 | .Fa pglob | |
296 | contain the values described below: | |
297 | .Bl -tag -width GLOB_NOCHECK | |
298 | .It Fa gl_pathc | |
299 | contains the total number of matched pathnames so far. | |
300 | This includes other matches from previous invocations of | |
301 | .Fn glob | |
302 | if | |
303 | .Dv GLOB_APPEND | |
304 | was specified. | |
305 | .It Fa gl_matchc | |
306 | contains the number of matched pathnames in the current invocation of | |
307 | .Fn glob . | |
308 | .It Fa gl_flags | |
309 | contains a copy of the | |
310 | .Fa flags | |
311 | parameter with the bit | |
312 | .Dv GLOB_MAGCHAR | |
313 | set if | |
314 | .Fa pattern | |
315 | contained any of the special characters ``*'', ``?'' or ``['', cleared | |
316 | if not. | |
317 | .It Fa gl_pathv | |
318 | contains a pointer to a | |
319 | .Dv NULL Ns -terminated | |
320 | list of matched pathnames. | |
321 | However, if | |
322 | .Fa gl_pathc | |
323 | is zero, the contents of | |
324 | .Fa gl_pathv | |
325 | are undefined. | |
326 | .El | |
327 | .Pp | |
328 | If | |
329 | .Fn glob | |
330 | terminates due to an error, it sets errno and returns one of the | |
331 | following non-zero constants, which are defined in the include | |
332 | file | |
333 | .Aq Pa glob.h : | |
334 | .Bl -tag -width GLOB_NOCHECK | |
335 | .It Dv GLOB_NOSPACE | |
336 | An attempt to allocate memory failed. | |
337 | .It Dv GLOB_ABEND | |
338 | The scan was stopped because an error was encountered and either | |
339 | .Dv GLOB_ERR | |
340 | was set or | |
341 | .Fa (*errfunc)() | |
342 | returned non-zero. | |
343 | .El | |
344 | .Pp | |
345 | The arguments | |
346 | .Fa pglob\->gl_pathc | |
347 | and | |
348 | .Fa pglob\->gl_pathv | |
349 | are still set as specified above. | |
350 | .Sh SEE ALSO | |
351 | .Xr sh 1 , | |
352 | .Xr fnmatch 3 , | |
353 | .Xr wordexp 3 , | |
354 | .Xr regexp 3 | |
355 | .Sh STANDARDS | |
356 | The | |
357 | .Fn glob | |
358 | function is expected to be | |
359 | .St -p1003.2 | |
360 | compatible with the exception | |
78ed81a3 | 361 | that the flags |
362 | .Dv GLOB_ALTDIRFUNC | |
363 | and | |
15637ed4 RG |
364 | .Dv GLOB_QUOTE |
365 | and the fields | |
366 | .Fa gl_matchc | |
367 | and | |
368 | .Fa gl_flags | |
369 | should not be used by applications striving for strict | |
370 | .Tn POSIX | |
371 | conformance. | |
372 | .Sh EXAMPLE | |
373 | A rough equivalent of | |
374 | .Ql "ls -l *.c *.h" | |
375 | can be obtained with the | |
376 | following code: | |
377 | .Bd -literal -offset indent | |
378 | GLOB_t g; | |
379 | ||
380 | g.gl_offs = 2; | |
381 | glob("*.c", GLOB_DOOFFS, NULL, &g); | |
382 | glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); | |
383 | g.gl_pathv[0] = "ls"; | |
384 | g.gl_pathv[1] = "-l"; | |
385 | execvp("ls", g.gl_pathv); | |
386 | .Ed | |
387 | .Sh HISTORY | |
388 | The | |
389 | .Fn glob | |
390 | and | |
391 | .Fn globfree | |
392 | functions are | |
393 | .Ud . | |
394 | .Sh BUGS | |
395 | Patterns longer than | |
396 | .Dv MAXPATHLEN | |
397 | may cause unchecked errors. | |
398 | .Pp | |
399 | The | |
400 | .Fn glob | |
401 | argument | |
402 | may fail and set errno for any of the errors specified for the | |
403 | library routines | |
404 | .Xr stat 2 , | |
405 | .Xr closedir 3 , | |
406 | .Xr opendir 3 , | |
407 | .Xr readdir 3 , | |
408 | .Xr malloc 3 , | |
409 | and | |
410 | .Xr free 3 . |