| blob | 7d8e47a65d0f7ca4fa5984d7f4de67d19045ae70 |
1 .\" $NetBSD: glob.3,v 1.39 2010/11/30 21:03:07 jruoho Exp $
2 .\"
3 .\" Copyright (c) 1989, 1991, 1993, 1994
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to Berkeley by
7 .\" Guido van Rossum.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" @(#)glob.3 8.3 (Berkeley) 4/16/94
33 .\"
34 .Dd November 30, 2010
35 .Dt GLOB 3
36 .Os
37 .Sh NAME
38 .Nm glob ,
39 .Nm globfree ,
40 .Nm glob_pattern_p
41 .Nd generate pathnames matching a pattern
42 .Sh LIBRARY
43 .Lb libc
44 .Sh SYNOPSIS
45 .In glob.h
46 .Ft int
47 .Fn glob "const char * restrict pattern" "int flags" "const int (*errfunc)(const char *, int)" "glob_t * restrict pglob"
48 .Ft void
49 .Fn globfree "glob_t *pglob"
50 .Ft int
51 .Fn glob_pattern_p "const char *pattern" "int quote"
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 size_t gl_pathc; /* count of total paths so far */
67 size_t gl_matchc; /* count of paths matching pattern */
68 size_t 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 set to 1, and the number of matched
189 pathnames set to 0.
190 .It Dv GLOB_NOSORT
191 By default, the pathnames are sorted in ascending
192 .Tn ASCII
193 order;
194 this flag prevents that sorting (speeding up
195 .Fn glob ) .
196 .El
197 .Pp
198 The following values may also be included in
199 .Fa flags ,
200 however, they are non-standard extensions to
201 .St -p1003.2 .
202 .Bl -tag -width GLOB_ALTDIRFUNC
203 .It Dv GLOB_ALTDIRFUNC
204 The following additional fields in the pglob structure have been
205 initialized with alternate functions for glob to use to open, read,
206 and close directories and to get stat information on names found
207 in those directories.
208 .Bd -literal
209 void *(*gl_opendir)(const char * name);
210 struct dirent *(*gl_readdir)(void *);
211 void (*gl_closedir)(void *);
212 int (*gl_lstat)(const char *name, struct stat *st);
213 int (*gl_stat)(const char *name, struct stat *st);
214 .Ed
215 .Pp
216 This extension is provided to allow programs such as
217 .Xr restore 8
218 to provide globbing from directories stored on tape.
219 .It Dv GLOB_BRACE
220 Pre-process the pattern string to expand
221 .Ql {pat,pat,...}
222 strings like
223 .Xr csh 1 .
224 The pattern
225 .Ql {}
226 is left unexpanded for historical reasons
227 .Po
228 .Xr csh 1
229 does the same thing to ease typing of
230 .Xr find 1
231 patterns
232 .Pc .
233 .It Dv GLOB_MAGCHAR
234 Set by the
235 .Fn glob
236 function if the pattern included globbing characters.
237 See the description of the usage of the
238 .Fa gl_matchc
239 structure member for more details.
240 .It Dv GLOB_NOMAGIC
241 Is the same as
242 .Dv GLOB_NOCHECK
243 but it only appends the
244 .Fa pattern
245 if it does not contain any of the special characters ``*'', ``?'' or ``[''.
246 .Dv GLOB_NOMAGIC
247 is provided to simplify implementing the historic
248 .Xr csh 1
249 globbing behavior and should probably not be used anywhere else.
250 .It Dv GLOB_NOESCAPE
251 Disable the use of the backslash
252 .Pq Ql \e
253 character for quoting.
254 .It Dv GLOB_TILDE
255 Expand patterns that start with
256 .Ql ~
257 to user name home directories.
258 .It Dv GLOB_LIMIT
259 Limit the amount of memory used to store matched strings to
260 .Li 64K ,
261 the number of
262 .Xr stat 2
263 calls to 128, and the number of
264 .Xr readdir 3
265 calls to 16K.
266 This option should be set for programs that can be coerced to a denial of
267 service attack via patterns that expand to a very large number of matches,
268 such as a long string of
269 .Li */../*/..
270 .It Dv GLOB_PERIOD
271 Allow metacharacters to match a leading period in a filename.
272 .It Dv GLOB_NO_DOTDIRS
273 Hide
274 .Sq Li \&.
275 and
276 .Sq Li \&..
277 from metacharacter matches, regardless of whether
278 .Dv GLOB_PERIOD
279 is set and whether the pattern component begins with a literal period.
280 .Dv GLOB_STAR
281 Indicates that two adjacent
282 .Li *
283 characters will do a recursive match in all subdirs, without following
284 symbolic links and three adjacent
285 .Li *
286 characters will also follow symbolic links.
287 .El
288 .Pp
289 If, during the search, a directory is encountered that cannot be opened
290 or read and
291 .Fa errfunc
292 is
293 .Pf non- Dv NULL ,
294 .Fn glob
295 calls
296 .Fa (*errfunc)(path, errno) .
297 This may be unintuitive: a pattern like
298 .Ql */Makefile
299 will try to
300 .Xr stat 2
301 .Ql foo/Makefile
302 even if
303 .Ql foo
304 is not a directory, resulting in a
305 call to
306 .Fa errfunc .
307 The error routine can suppress this action by testing for
308 .Dv ENOENT
309 and
310 .Dv ENOTDIR ;
311 however, the
312 .Dv GLOB_ERR
313 flag will still cause an immediate
314 return when this happens.
315 .Pp
316 If
317 .Fa errfunc
318 returns non-zero,
319 .Fn glob
320 stops the scan and returns
321 .Dv GLOB_ABORTED
322 after setting
323 .Fa gl_pathc
324 and
325 .Fa gl_pathv
326 to reflect any paths already matched.
327 This also happens if an error is encountered and
328 .Dv GLOB_ERR
329 is set in
330 .Fa flags ,
331 regardless of the return value of
332 .Fa errfunc ,
333 if called.
334 If
335 .Dv GLOB_ERR
336 is not set and either
337 .Fa errfunc
338 is
339 .Dv NULL
340 or
341 .Fa errfunc
342 returns zero, the error is ignored.
343 .Pp
344 The
345 .Fn globfree
346 function frees any space associated with
347 .Fa pglob
348 from a previous call(s) to
349 .Fn glob .
350 .Pp
351 The
352 .Fn glob_pattern_p
353 returns
354 .Dv 1
355 if the
356 .Fa pattern
357 has any special characters that
358 .Fn glob
359 will interpret and
360 .Dv 0
361 otherwise.
362 If the
363 .Fa quote
364 argument is non-zero, then backslash quoted characters are ignored.
365 .Pp
366 The historical
367 .Dv GLOB_QUOTE
368 flag is no longer supported.
369 Per
370 .St -p1003.2-92 ,
371 backslash escaping of special characters is the default behaviour;
372 it may be disabled by specifying the
373 .Dv GLOB_NOESCAPE
374 flag.
375 .Sh RETURN VALUES
376 On successful completion,
377 .Fn glob
378 returns zero.
379 In addition the fields of
380 .Fa pglob
381 contain the values described below:
382 .Bl -tag -width GLOB_NOCHECK
383 .It Fa gl_pathc
384 contains the total number of matched pathnames so far.
385 This includes other matches from previous invocations of
386 .Fn glob
387 if
388 .Dv GLOB_APPEND
389 was specified.
390 .It Fa gl_matchc
391 contains the number of matched pathnames in the current invocation of
392 .Fn glob .
393 .It Fa gl_flags
394 contains a copy of the
395 .Fa flags
396 parameter with the bit
397 .Dv GLOB_MAGCHAR
398 set if
399 .Fa pattern
400 contained any of the special characters ``*'', ``?'' or ``['', cleared
401 if not.
402 .It Fa gl_pathv
403 contains a pointer to a
404 .Dv NULL Ns -terminated
405 list of matched pathnames.
406 However, if
407 .Fa gl_pathc
408 is zero, the contents of
409 .Fa gl_pathv
410 are undefined.
411 .El
412 .Pp
413 If
414 .Fn glob
415 terminates due to an error, it sets
416 .Va errno
417 and returns one of the following non-zero constants, which are defined
418 in the include file
419 .In glob.h :
420 .Bl -tag -width GLOB_ABORTEDXXX
421 .It Dv GLOB_ABORTED
422 The scan was stopped because an error was encountered and either
423 .Dv GLOB_ERR
424 was set or
425 .Fa (*errfunc)()
426 returned non-zero.
427 .It Dv GLOB_NOMATCH
428 The pattern does not match any existing pathname, and
429 .Dv GLOB_NOCHECK
430 was not set in
431 .Dv flags .
432 .It Dv GLOB_NOSPACE
433 An attempt to allocate memory failed, or if
434 .Va errno
435 was 0
436 .Li GLOB_LIMIT
437 was specified in the flags and
438 .Li ARG_MAX
439 patterns were matched.
440 .El
441 .Pp
442 The historical
443 .Dv GLOB_ABEND
444 return constant is no longer supported.
445 Portable applications should use the
446 .Dv GLOB_ABORTED
447 constant instead.
448 .Pp
449 The arguments
450 .Fa pglob\-\*[Gt]gl_pathc
451 and
452 .Fa pglob\-\*[Gt]gl_pathv
453 are still set as specified above.
454 .Sh ENVIRONMENT
455 .Bl -tag -width HOME -compact
456 .It Ev HOME
457 If defined, used as the home directory of the current user in
458 tilde expansions.
459 .El
460 .Sh EXAMPLES
461 A rough equivalent of
462 .Ql "ls -l *.c *.h"
463 can be obtained with the
464 following code:
465 .Bd -literal -offset indent
466 glob_t g;
468 g.gl_offs = 2;
469 glob("*.c", GLOB_DOOFFS, NULL, \*[Am]g);
470 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, \*[Am]g);
471 g.gl_pathv[0] = "ls";
472 g.gl_pathv[1] = "-l";
473 execvp("ls", g.gl_pathv);
474 .Ed
475 .Sh SEE ALSO
476 .Xr sh 1 ,
477 .Xr fnmatch 3 ,
478 .Xr regexp 3 ,
479 .Xr glob 7
480 .Sh STANDARDS
481 The
482 .Fn glob
483 function is expected to be
484 .St -p1003.2
485 compatible with the exception
486 that the flags
487 .Dv GLOB_ALTDIRFUNC ,
488 .Dv GLOB_BRACE ,
489 .Dv GLOB_MAGCHAR ,
490 .Dv GLOB_NOMAGIC ,
491 .Dv GLOB_TILDE ,
492 and
493 .Dv GLOB_LIMIT
494 and the fields
495 .Fa gl_matchc
496 and
497 .Fa gl_flags
498 should not be used by applications striving for strict
499 .Tn POSIX
500 conformance.
501 .Sh HISTORY
502 The
503 .Fn glob
504 and
505 .Fn globfree
506 functions first appeared in
507 .Bx 4.4 .
508 The
509 .Fn glob_pattern_p
510 function is modelled after the one found in glibc.
511 .Sh BUGS
512 Patterns longer than
513 .Dv MAXPATHLEN
514 may cause unchecked errors.
515 .Pp
516 The
517 .Fn glob
518 function may fail and set
519 .Va errno
520 for any of the errors specified for the library routines
521 .Xr stat 2 ,
522 .Xr closedir 3 ,
523 .Xr opendir 3 ,
524 .Xr readdir 3 ,
525 .Xr malloc 3 ,
526 and
527 .Xr free 3 .