1 | .\" Copyright (c) 1989, 1991, 1993, 1994 |
---|
2 | .\" The Regents of the University of California. 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 | .\" |
---|
34 | .\" @(#)glob.3 8.3 (Berkeley) 4/16/94 |
---|
35 | .\" $FreeBSD: src/lib/libc/gen/glob.3,v 1.20 2001/10/01 16:08:51 ru Exp $ |
---|
36 | .\" |
---|
37 | .Dd April 16, 1994 |
---|
38 | .Dt GLOB 3 |
---|
39 | .Os |
---|
40 | .Sh NAME |
---|
41 | .Nm glob , |
---|
42 | .Nm globfree |
---|
43 | .Nd generate pathnames matching a pattern |
---|
44 | .Sh LIBRARY |
---|
45 | .Lb libc |
---|
46 | .Sh SYNOPSIS |
---|
47 | .In glob.h |
---|
48 | .Ft int |
---|
49 | .Fn glob "const char *pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t *pglob" |
---|
50 | .Ft void |
---|
51 | .Fn globfree "glob_t *pglob" |
---|
52 | .Sh DESCRIPTION |
---|
53 | The |
---|
54 | .Fn glob |
---|
55 | function |
---|
56 | is a pathname generator that implements the rules for file name pattern |
---|
57 | matching used by the shell. |
---|
58 | .Pp |
---|
59 | The include file |
---|
60 | .Pa glob.h |
---|
61 | defines the structure type |
---|
62 | .Fa glob_t , |
---|
63 | which contains at least the following fields: |
---|
64 | .Bd -literal |
---|
65 | typedef struct { |
---|
66 | int gl_pathc; /* count of total paths so far */ |
---|
67 | int gl_matchc; /* count of paths matching pattern */ |
---|
68 | int gl_offs; /* reserved at beginning of gl_pathv */ |
---|
69 | int gl_flags; /* returned flags */ |
---|
70 | char **gl_pathv; /* list of paths matching pattern */ |
---|
71 | } glob_t; |
---|
72 | .Ed |
---|
73 | .Pp |
---|
74 | The argument |
---|
75 | .Fa pattern |
---|
76 | is a pointer to a pathname pattern to be expanded. |
---|
77 | The |
---|
78 | .Fn glob |
---|
79 | argument |
---|
80 | matches all accessible pathnames against the pattern and creates |
---|
81 | a list of the pathnames that match. |
---|
82 | In order to have access to a pathname, |
---|
83 | .Fn glob |
---|
84 | requires search permission on every component of a path except the last |
---|
85 | and read permission on each directory of any filename component of |
---|
86 | .Fa pattern |
---|
87 | that contains any of the special characters |
---|
88 | .Ql * , |
---|
89 | .Ql ?\& |
---|
90 | or |
---|
91 | .Ql \&[ . |
---|
92 | .Pp |
---|
93 | The |
---|
94 | .Fn glob |
---|
95 | argument |
---|
96 | stores the number of matched pathnames into the |
---|
97 | .Fa gl_pathc |
---|
98 | field, and a pointer to a list of pointers to pathnames into the |
---|
99 | .Fa gl_pathv |
---|
100 | field. |
---|
101 | The first pointer after the last pathname is |
---|
102 | .Dv NULL . |
---|
103 | If the pattern does not match any pathnames, the returned number of |
---|
104 | matched paths is set to zero. |
---|
105 | .Pp |
---|
106 | It is the caller's responsibility to create the structure pointed to by |
---|
107 | .Fa pglob . |
---|
108 | The |
---|
109 | .Fn glob |
---|
110 | function allocates other space as needed, including the memory pointed |
---|
111 | to by |
---|
112 | .Fa gl_pathv . |
---|
113 | .Pp |
---|
114 | The argument |
---|
115 | .Fa flags |
---|
116 | is used to modify the behavior of |
---|
117 | .Fn glob . |
---|
118 | The value of |
---|
119 | .Fa flags |
---|
120 | is the bitwise inclusive |
---|
121 | .Tn OR |
---|
122 | of any of the following |
---|
123 | values defined in |
---|
124 | .Pa glob.h : |
---|
125 | .Bl -tag -width GLOB_ALTDIRFUNC |
---|
126 | .It Dv GLOB_APPEND |
---|
127 | Append pathnames generated to the ones from a previous call (or calls) |
---|
128 | to |
---|
129 | .Fn glob . |
---|
130 | The value of |
---|
131 | .Fa gl_pathc |
---|
132 | will be the total matches found by this call and the previous call(s). |
---|
133 | The pathnames are appended to, not merged with the pathnames returned by |
---|
134 | the previous call(s). |
---|
135 | Between calls, the caller must not change the setting of the |
---|
136 | .Dv GLOB_DOOFFS |
---|
137 | flag, nor change the value of |
---|
138 | .Fa gl_offs |
---|
139 | when |
---|
140 | .Dv GLOB_DOOFFS |
---|
141 | is set, nor (obviously) call |
---|
142 | .Fn globfree |
---|
143 | for |
---|
144 | .Fa pglob . |
---|
145 | .It Dv GLOB_DOOFFS |
---|
146 | Make use of the |
---|
147 | .Fa gl_offs |
---|
148 | field. |
---|
149 | If this flag is set, |
---|
150 | .Fa gl_offs |
---|
151 | is used to specify how many |
---|
152 | .Dv NULL |
---|
153 | pointers to prepend to the beginning |
---|
154 | of the |
---|
155 | .Fa gl_pathv |
---|
156 | field. |
---|
157 | In other words, |
---|
158 | .Fa gl_pathv |
---|
159 | will point to |
---|
160 | .Fa gl_offs |
---|
161 | .Dv NULL |
---|
162 | pointers, |
---|
163 | followed by |
---|
164 | .Fa gl_pathc |
---|
165 | pathname pointers, followed by a |
---|
166 | .Dv NULL |
---|
167 | pointer. |
---|
168 | .It Dv GLOB_ERR |
---|
169 | Causes |
---|
170 | .Fn glob |
---|
171 | to return when it encounters a directory that it cannot open or read. |
---|
172 | Ordinarily, |
---|
173 | .Fn glob |
---|
174 | continues to find matches. |
---|
175 | .It Dv GLOB_MARK |
---|
176 | Each pathname that is a directory that matches |
---|
177 | .Fa pattern |
---|
178 | has a slash |
---|
179 | appended. |
---|
180 | .It Dv GLOB_NOCHECK |
---|
181 | If |
---|
182 | .Fa pattern |
---|
183 | does not match any pathname, then |
---|
184 | .Fn glob |
---|
185 | returns a list |
---|
186 | consisting of only |
---|
187 | .Fa pattern , |
---|
188 | with the number of total pathnames is set to 1, and the number of matched |
---|
189 | pathnames set to 0. |
---|
190 | If |
---|
191 | .Dv GLOB_QUOTE |
---|
192 | is set, its effect is present in the pattern returned. |
---|
193 | .It Dv GLOB_NOSORT |
---|
194 | By default, the pathnames are sorted in ascending |
---|
195 | .Tn ASCII |
---|
196 | order; |
---|
197 | this flag prevents that sorting (speeding up |
---|
198 | .Fn glob ) . |
---|
199 | .El |
---|
200 | .Pp |
---|
201 | The following values may also be included in |
---|
202 | .Fa flags , |
---|
203 | however, they are non-standard extensions to |
---|
204 | .St -p1003.2 . |
---|
205 | .Bl -tag -width GLOB_ALTDIRFUNC |
---|
206 | .It Dv GLOB_ALTDIRFUNC |
---|
207 | The following additional fields in the pglob structure have been |
---|
208 | initialized with alternate functions for glob to use to open, read, |
---|
209 | and close directories and to get stat information on names found |
---|
210 | in those directories. |
---|
211 | .Bd -literal |
---|
212 | void *(*gl_opendir)(const char * name); |
---|
213 | struct dirent *(*gl_readdir)(void *); |
---|
214 | void (*gl_closedir)(void *); |
---|
215 | int (*gl_lstat)(const char *name, struct stat *st); |
---|
216 | int (*gl_stat)(const char *name, struct stat *st); |
---|
217 | .Ed |
---|
218 | .Pp |
---|
219 | This extension is provided to allow programs such as |
---|
220 | .Xr restore 8 |
---|
221 | to provide globbing from directories stored on tape. |
---|
222 | .It Dv GLOB_BRACE |
---|
223 | Pre-process the pattern string to expand |
---|
224 | .Ql {pat,pat,...} |
---|
225 | strings like |
---|
226 | .Xr csh 1 . |
---|
227 | The pattern |
---|
228 | .Ql {} |
---|
229 | is left unexpanded for historical reasons (and |
---|
230 | .Xr csh 1 |
---|
231 | does the same thing to |
---|
232 | ease typing |
---|
233 | of |
---|
234 | .Xr find 1 |
---|
235 | patterns). |
---|
236 | .It Dv GLOB_MAGCHAR |
---|
237 | Set by the |
---|
238 | .Fn glob |
---|
239 | function if the pattern included globbing characters. |
---|
240 | See the description of the usage of the |
---|
241 | .Fa gl_matchc |
---|
242 | structure member for more details. |
---|
243 | .It Dv GLOB_NOMAGIC |
---|
244 | Is the same as |
---|
245 | .Dv GLOB_NOCHECK |
---|
246 | but it only appends the |
---|
247 | .Fa pattern |
---|
248 | if it does not contain any of the special characters ``*'', ``?'' or ``[''. |
---|
249 | .Dv GLOB_NOMAGIC |
---|
250 | is provided to simplify implementing the historic |
---|
251 | .Xr csh 1 |
---|
252 | globbing behavior and should probably not be used anywhere else. |
---|
253 | .It Dv GLOB_QUOTE |
---|
254 | Use the backslash |
---|
255 | .Pq Ql \e |
---|
256 | character for quoting: every occurrence of |
---|
257 | a backslash followed by a character in the pattern is replaced by that |
---|
258 | character, avoiding any special interpretation of the character. |
---|
259 | .It Dv GLOB_TILDE |
---|
260 | Expand patterns that start with |
---|
261 | .Ql ~ |
---|
262 | to user name home directories. |
---|
263 | .It Dv GLOB_LIMIT |
---|
264 | Limit the total number of returned pathnames to the value provided in |
---|
265 | .Fa gl_matchc |
---|
266 | (default |
---|
267 | .Dv ARG_MAX ) . |
---|
268 | This option should be set for programs |
---|
269 | that can be coerced into a denial of service attack |
---|
270 | via patterns that expand to a very large number of matches, |
---|
271 | such as a long string of |
---|
272 | .Ql */../*/.. . |
---|
273 | .El |
---|
274 | .Pp |
---|
275 | If, during the search, a directory is encountered that cannot be opened |
---|
276 | or read and |
---|
277 | .Fa errfunc |
---|
278 | is |
---|
279 | .Pf non- Dv NULL , |
---|
280 | .Fn glob |
---|
281 | calls |
---|
282 | .Fa \*(lp*errfunc\*(rp Ns ( Fa path , errno ) . |
---|
283 | This may be unintuitive: a pattern like |
---|
284 | .Ql */Makefile |
---|
285 | will try to |
---|
286 | .Xr stat 2 |
---|
287 | .Ql foo/Makefile |
---|
288 | even if |
---|
289 | .Ql foo |
---|
290 | is not a directory, resulting in a |
---|
291 | call to |
---|
292 | .Fa errfunc . |
---|
293 | The error routine can suppress this action by testing for |
---|
294 | .Er ENOENT |
---|
295 | and |
---|
296 | .Er ENOTDIR ; |
---|
297 | however, the |
---|
298 | .Dv GLOB_ERR |
---|
299 | flag will still cause an immediate |
---|
300 | return when this happens. |
---|
301 | .Pp |
---|
302 | If |
---|
303 | .Fa errfunc |
---|
304 | returns non-zero, |
---|
305 | .Fn glob |
---|
306 | stops the scan and returns |
---|
307 | .Dv GLOB_ABEND |
---|
308 | after setting |
---|
309 | .Fa gl_pathc |
---|
310 | and |
---|
311 | .Fa gl_pathv |
---|
312 | to reflect any paths already matched. |
---|
313 | This also happens if an error is encountered and |
---|
314 | .Dv GLOB_ERR |
---|
315 | is set in |
---|
316 | .Fa flags , |
---|
317 | regardless of the return value of |
---|
318 | .Fa errfunc , |
---|
319 | if called. |
---|
320 | If |
---|
321 | .Dv GLOB_ERR |
---|
322 | is not set and either |
---|
323 | .Fa errfunc |
---|
324 | is |
---|
325 | .Dv NULL |
---|
326 | or |
---|
327 | .Fa errfunc |
---|
328 | returns zero, the error is ignored. |
---|
329 | .Pp |
---|
330 | The |
---|
331 | .Fn globfree |
---|
332 | function frees any space associated with |
---|
333 | .Fa pglob |
---|
334 | from a previous call(s) to |
---|
335 | .Fn glob . |
---|
336 | .Sh RETURN VALUES |
---|
337 | On successful completion, |
---|
338 | .Fn glob |
---|
339 | returns zero. |
---|
340 | In addition the fields of |
---|
341 | .Fa pglob |
---|
342 | contain the values described below: |
---|
343 | .Bl -tag -width GLOB_NOCHECK |
---|
344 | .It Fa gl_pathc |
---|
345 | contains the total number of matched pathnames so far. |
---|
346 | This includes other matches from previous invocations of |
---|
347 | .Fn glob |
---|
348 | if |
---|
349 | .Dv GLOB_APPEND |
---|
350 | was specified. |
---|
351 | .It Fa gl_matchc |
---|
352 | contains the number of matched pathnames in the current invocation of |
---|
353 | .Fn glob . |
---|
354 | .It Fa gl_flags |
---|
355 | contains a copy of the |
---|
356 | .Fa flags |
---|
357 | parameter with the bit |
---|
358 | .Dv GLOB_MAGCHAR |
---|
359 | set if |
---|
360 | .Fa pattern |
---|
361 | contained any of the special characters ``*'', ``?'' or ``['', cleared |
---|
362 | if not. |
---|
363 | .It Fa gl_pathv |
---|
364 | contains a pointer to a |
---|
365 | .Dv NULL Ns -terminated |
---|
366 | list of matched pathnames. |
---|
367 | However, if |
---|
368 | .Fa gl_pathc |
---|
369 | is zero, the contents of |
---|
370 | .Fa gl_pathv |
---|
371 | are undefined. |
---|
372 | .El |
---|
373 | .Pp |
---|
374 | If |
---|
375 | .Fn glob |
---|
376 | terminates due to an error, it sets errno and returns one of the |
---|
377 | following non-zero constants, which are defined in the include |
---|
378 | file |
---|
379 | .Aq Pa glob.h : |
---|
380 | .Bl -tag -width GLOB_NOCHECK |
---|
381 | .It Dv GLOB_NOSPACE |
---|
382 | An attempt to allocate memory failed, or if |
---|
383 | .Fa errno |
---|
384 | was 0 |
---|
385 | .Dv GLOB_LIMIT |
---|
386 | was specified in the flags and |
---|
387 | .Fa pglob\->gl_matchc |
---|
388 | or more patterns were matched. |
---|
389 | .It Dv GLOB_ABEND |
---|
390 | The scan was stopped because an error was encountered and either |
---|
391 | .Dv GLOB_ERR |
---|
392 | was set or |
---|
393 | .Fa \*(lp*errfunc\*(rp\*(lp\*(rp |
---|
394 | returned non-zero. |
---|
395 | .El |
---|
396 | .Pp |
---|
397 | The arguments |
---|
398 | .Fa pglob\->gl_pathc |
---|
399 | and |
---|
400 | .Fa pglob\->gl_pathv |
---|
401 | are still set as specified above. |
---|
402 | .Sh EXAMPLES |
---|
403 | A rough equivalent of |
---|
404 | .Ql "ls -l *.c *.h" |
---|
405 | can be obtained with the |
---|
406 | following code: |
---|
407 | .Bd -literal -offset indent |
---|
408 | glob_t g; |
---|
409 | |
---|
410 | g.gl_offs = 2; |
---|
411 | glob("*.c", GLOB_DOOFFS, NULL, &g); |
---|
412 | glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); |
---|
413 | g.gl_pathv[0] = "ls"; |
---|
414 | g.gl_pathv[1] = "-l"; |
---|
415 | execvp("ls", g.gl_pathv); |
---|
416 | .Ed |
---|
417 | .Sh SEE ALSO |
---|
418 | .Xr sh 1 , |
---|
419 | .Xr fnmatch 3 , |
---|
420 | .Xr regexp 3 |
---|
421 | .Sh STANDARDS |
---|
422 | The |
---|
423 | .Fn glob |
---|
424 | function is expected to be |
---|
425 | .St -p1003.2 |
---|
426 | compatible with the exception |
---|
427 | that the flags |
---|
428 | .Dv GLOB_ALTDIRFUNC , |
---|
429 | .Dv GLOB_BRACE , |
---|
430 | .Dv GLOB_LIMIT , |
---|
431 | .Dv GLOB_MAGCHAR , |
---|
432 | .Dv GLOB_NOMAGIC , |
---|
433 | .Dv GLOB_QUOTE , |
---|
434 | and |
---|
435 | .Dv GLOB_TILDE , |
---|
436 | and the fields |
---|
437 | .Fa gl_matchc |
---|
438 | and |
---|
439 | .Fa gl_flags |
---|
440 | should not be used by applications striving for strict |
---|
441 | .Tn POSIX |
---|
442 | conformance. |
---|
443 | .Sh HISTORY |
---|
444 | The |
---|
445 | .Fn glob |
---|
446 | and |
---|
447 | .Fn globfree |
---|
448 | functions first appeared in |
---|
449 | .Bx 4.4 . |
---|
450 | .Sh BUGS |
---|
451 | Patterns longer than |
---|
452 | .Dv MAXPATHLEN |
---|
453 | may cause unchecked errors. |
---|
454 | .Pp |
---|
455 | The |
---|
456 | .Fn glob |
---|
457 | argument |
---|
458 | may fail and set errno for any of the errors specified for the |
---|
459 | library routines |
---|
460 | .Xr stat 2 , |
---|
461 | .Xr closedir 3 , |
---|
462 | .Xr opendir 3 , |
---|
463 | .Xr readdir 3 , |
---|
464 | .Xr malloc 3 , |
---|
465 | and |
---|
466 | .Xr free 3 . |
---|