| blob | 9656e39a77742a13fdf0ba3cedbfeb70413b6f99 |
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 .\" 4. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)glob.3 8.3 (Berkeley) 4/16/94
31 .\" $FreeBSD: src/lib/libc/gen/glob.3,v 1.32 2007/01/09 00:27:54 imp Exp $
32 .\" $DragonFly: src/lib/libc/gen/glob.3,v 1.5 2007/06/30 19:03:52 swildner Exp $
33 .\"
34 .Dd December 6, 2005
35 .Dt GLOB 3
36 .Os
37 .Sh NAME
38 .Nm glob ,
39 .Nm globfree
40 .Nd generate pathnames matching a pattern
41 .Sh LIBRARY
42 .Lb libc
43 .Sh SYNOPSIS
44 .In glob.h
45 .Ft int
46 .Fn glob "const char *pattern" "int flags" "int (*errfunc)(const 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 .In 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 size_t gl_pathc; /* count of total paths so far */
64 size_t gl_matchc; /* count of paths matching pattern */
65 size_t 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 .In glob.h :
122 .Bl -tag -width GLOB_ALTDIRFUNC
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 set to 1, and the number of matched
186 pathnames set to 0.
187 The effect of backslash escaping is present in the pattern returned.
188 .It Dv GLOB_NOESCAPE
189 By default, a backslash
190 .Pq Ql \e
191 character is used to escape the following character in the pattern,
192 avoiding any special interpretation of the character.
193 If
194 .Dv GLOB_NOESCAPE
195 is set, backslash escaping is disabled.
196 .It Dv GLOB_NOSORT
197 By default, the pathnames are sorted in ascending
198 .Tn ASCII
199 order;
200 this flag prevents that sorting (speeding up
201 .Fn glob ) .
202 .El
203 .Pp
204 The following values may also be included in
205 .Fa flags ,
206 however, they are non-standard extensions to
207 .St -p1003.2 .
208 .Bl -tag -width GLOB_ALTDIRFUNC
209 .It Dv GLOB_ALTDIRFUNC
210 The following additional fields in the pglob structure have been
211 initialized with alternate functions for glob to use to open, read,
212 and close directories and to get stat information on names found
213 in those directories.
214 .Bd -literal
215 void *(*gl_opendir)(const char * name);
216 struct dirent *(*gl_readdir)(void *);
217 void (*gl_closedir)(void *);
218 int (*gl_lstat)(const char *name, struct stat *st);
219 int (*gl_stat)(const char *name, struct stat *st);
220 .Ed
221 .Pp
222 This extension is provided to allow programs such as
223 .Xr restore 8
224 to provide globbing from directories stored on tape.
225 .It Dv GLOB_BRACE
226 Pre-process the pattern string to expand
227 .Ql {pat,pat,...}
228 strings like
229 .Xr csh 1 .
230 The pattern
231 .Ql {}
232 is left unexpanded for historical reasons (and
233 .Xr csh 1
234 does the same thing to
235 ease typing
236 of
237 .Xr find 1
238 patterns).
239 .It Dv GLOB_MAGCHAR
240 Set by the
241 .Fn glob
242 function if the pattern included globbing characters.
243 See the description of the usage of the
244 .Fa gl_matchc
245 structure member for more details.
246 .It Dv GLOB_NOMAGIC
247 Is the same as
248 .Dv GLOB_NOCHECK
249 but it only appends the
250 .Fa pattern
251 if it does not contain any of the special characters ``*'', ``?'' or ``[''.
252 .Dv GLOB_NOMAGIC
253 is provided to simplify implementing the historic
254 .Xr csh 1
255 globbing behavior and should probably not be used anywhere else.
256 .It Dv GLOB_TILDE
257 Expand patterns that start with
258 .Ql ~
259 to user name home directories.
260 .It Dv GLOB_LIMIT
261 Limit the total number of returned pathnames to the value provided in
262 .Fa gl_matchc
263 (default
264 .Dv ARG_MAX ) .
265 This option should be set for programs
266 that can be coerced into a denial of service attack
267 via patterns that expand to a very large number of matches,
268 such as a long string of
269 .Ql */../*/.. .
270 .It Dv GLOB_PERIOD
271 Allow matching of pathnames which start with a period.
272 .El
273 .Pp
274 If, during the search, a directory is encountered that cannot be opened
275 or read and
276 .Fa errfunc
277 is
278 .Pf non- Dv NULL ,
279 .Fn glob
280 calls
281 .Fa \*(lp*errfunc\*(rp Ns ( Fa path , errno ) .
282 This may be unintuitive: a pattern like
283 .Ql */Makefile
284 will try to
285 .Xr stat 2
286 .Ql foo/Makefile
287 even if
288 .Ql foo
289 is not a directory, resulting in a
290 call to
291 .Fa errfunc .
292 The error routine can suppress this action by testing for
293 .Er ENOENT
294 and
295 .Er ENOTDIR ;
296 however, the
297 .Dv GLOB_ERR
298 flag will still cause an immediate
299 return when this happens.
300 .Pp
301 If
302 .Fa errfunc
303 returns non-zero,
304 .Fn glob
305 stops the scan and returns
306 .Dv GLOB_ABORTED
307 after setting
308 .Fa gl_pathc
309 and
310 .Fa gl_pathv
311 to reflect any paths already matched.
312 This also happens if an error is encountered and
313 .Dv GLOB_ERR
314 is set in
315 .Fa flags ,
316 regardless of the return value of
317 .Fa errfunc ,
318 if called.
319 If
320 .Dv GLOB_ERR
321 is not set and either
322 .Fa errfunc
323 is
324 .Dv NULL
325 or
326 .Fa errfunc
327 returns zero, the error is ignored.
328 .Pp
329 The
330 .Fn globfree
331 function frees any space associated with
332 .Fa pglob
333 from a previous call(s) to
334 .Fn glob .
335 .Sh RETURN VALUES
336 On successful completion,
337 .Fn glob
338 returns zero.
339 In addition the fields of
340 .Fa pglob
341 contain the values described below:
342 .Bl -tag -width GLOB_NOCHECK
343 .It Fa gl_pathc
344 contains the total number of matched pathnames so far.
345 This includes other matches from previous invocations of
346 .Fn glob
347 if
348 .Dv GLOB_APPEND
349 was specified.
350 .It Fa gl_matchc
351 contains the number of matched pathnames in the current invocation of
352 .Fn glob .
353 .It Fa gl_flags
354 contains a copy of the
355 .Fa flags
356 argument with the bit
357 .Dv GLOB_MAGCHAR
358 set if
359 .Fa pattern
360 contained any of the special characters ``*'', ``?'' or ``['', cleared
361 if not.
362 .It Fa gl_pathv
363 contains a pointer to a
364 .Dv NULL Ns -terminated
365 list of matched pathnames.
366 However, if
367 .Fa gl_pathc
368 is zero, the contents of
369 .Fa gl_pathv
370 are undefined.
371 .El
372 .Pp
373 If
374 .Fn glob
375 terminates due to an error, it sets
376 .Va errno
377 and returns one of the
378 following non-zero constants, which are defined in the include file
379 .In 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_ABORTED
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 .It Dv GLOB_NOMATCH
396 The pattern did not match a pathname and
397 .Dv GLOB_NOCHECK
398 was not set.
399 .El
400 .Pp
401 The arguments
402 .Fa pglob\->gl_pathc
403 and
404 .Fa pglob\->gl_pathv
405 are still set as specified above.
406 .Sh EXAMPLES
407 A rough equivalent of
408 .Ql "ls -l *.c *.h"
409 can be obtained with the
410 following code:
411 .Bd -literal -offset indent
412 glob_t g;
414 g.gl_offs = 2;
415 glob("*.c", GLOB_DOOFFS, NULL, &g);
416 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
417 g.gl_pathv[0] = "ls";
418 g.gl_pathv[1] = "-l";
419 execvp("ls", g.gl_pathv);
420 .Ed
421 .Sh SEE ALSO
422 .Xr sh 1 ,
423 .Xr fnmatch 3 ,
424 .Xr regexp 3
425 .Sh STANDARDS
426 The current implementation of the
427 .Fn glob
428 function
429 .Em does not
430 conform to
431 .St -p1003.2 .
432 Collating symbol expressions, equivalence class expressions and
433 character class expressions are not supported.
434 .Pp
435 The flags
436 .Dv GLOB_ALTDIRFUNC ,
437 .Dv GLOB_BRACE ,
438 .Dv GLOB_LIMIT ,
439 .Dv GLOB_MAGCHAR ,
440 .Dv GLOB_NOMAGIC ,
441 and
442 .Dv GLOB_TILDE ,
443 and the fields
444 .Fa gl_matchc
445 and
446 .Fa gl_flags
447 are extensions to the
448 .Tn POSIX
449 standard and
450 should not be used by applications striving for strict
451 conformance.
452 .Sh HISTORY
453 The
454 .Fn glob
455 and
456 .Fn globfree
457 functions first appeared in
458 .Bx 4.4 .
459 .Sh BUGS
460 Patterns longer than
461 .Dv MAXPATHLEN
462 may cause unchecked errors.
463 .Pp
464 The
465 .Fn glob
466 argument may fail and set
467 .Va errno
468 for any of the errors specified for the library routines
469 .Xr stat 2 ,
470 .Xr closedir 3 ,
471 .Xr opendir 3 ,
472 .Xr readdir 3 ,
473 .Xr malloc 3 ,
474 and
475 .Xr free 3 .