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