| blob | 0c3598ffb594db5201236bbd38a6c342c09bdc45 |
1 .\" $NetBSD: glob.3,v 1.42 2012/12/27 21:17:47 christos 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 December 27, 2012
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" "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 one level of backslash escapes removed,
189 the number of total pathnames set to 1, and the number of matched
190 pathnames set to 0.
191 .It Dv GLOB_NOSORT
192 By default, the pathnames are sorted in ascending
193 .Tn ASCII
194 order;
195 this flag prevents that sorting (speeding up
196 .Fn glob ) .
197 .El
198 .Pp
199 The following values may also be included in
200 .Fa flags ,
201 however, they are non-standard extensions to
202 .St -p1003.2 .
203 .Bl -tag -width GLOB_ALTDIRFUNC
204 .It Dv GLOB_ALTDIRFUNC
205 The following additional fields in the pglob structure have been
206 initialized with alternate functions for glob to use to open, read,
207 and close directories and to get stat information on names found
208 in those directories.
209 .Bd -literal
210 void *(*gl_opendir)(const char * name);
211 struct dirent *(*gl_readdir)(void *);
212 void (*gl_closedir)(void *);
213 int (*gl_lstat)(const char *name, struct stat *st);
214 int (*gl_stat)(const char *name, struct stat *st);
215 .Ed
216 .Pp
217 This extension is provided to allow programs such as
218 .Xr restore 8
219 to provide globbing from directories stored on tape.
220 .It Dv GLOB_BRACE
221 Pre-process the pattern string to expand
222 .Ql {pat,pat,...}
223 strings like
224 .Xr csh 1 .
225 The pattern
226 .Ql {}
227 is left unexpanded for historical reasons
228 .Po
229 .Xr csh 1
230 does the same thing to ease typing of
231 .Xr find 1
232 patterns
233 .Pc .
234 .It Dv GLOB_LIMIT
235 Limit the amount of memory used to store matched strings to
236 .Li 64K ,
237 the number of
238 .Xr stat 2
239 calls to 128, and the number of
240 .Xr readdir 3
241 calls to 16K.
242 This option should be set for programs that can be coerced to a denial of
243 service attack via patterns that expand to a very large number of matches,
244 such as a long string of
245 .Li */../*/..
246 .It Dv GLOB_MAGCHAR
247 Set by the
248 .Fn glob
249 function if the pattern included globbing characters.
250 See the description of the usage of the
251 .Fa gl_matchc
252 structure member for more details.
253 .It Dv GLOB_NOESCAPE
254 Disable the use of the backslash
255 .Pq Ql \e
256 character for quoting.
257 .It Dv GLOB_NOMAGIC
258 Is the same as
259 .Dv GLOB_NOCHECK
260 but it only appends the
261 .Fa pattern
262 if it does not contain any of the special characters ``*'', ``?'' or ``[''.
263 .Dv GLOB_NOMAGIC
264 is provided to simplify implementing the historic
265 .Xr csh 1
266 globbing behavior and should probably not be used anywhere else.
267 .It Dv GLOB_NO_DOTDIRS
268 Hide
269 .Sq Li \&.
270 and
271 .Sq Li \&..
272 from metacharacter matches, regardless of whether
273 .Dv GLOB_PERIOD
274 is set and whether the pattern component begins with a literal period.
275 .It Dv GLOB_PERIOD
276 Allow metacharacters to match a leading period in a filename.
277 .It Dv GLOB_STAR
278 Indicates that two adjacent
279 .Li *
280 characters will do a recursive match in all subdirs, without following
281 symbolic links and three adjacent
282 .Li *
283 characters will also follow symbolic links.
284 .It Dv GLOB_TILDE
285 Expand patterns that start with
286 .Ql ~
287 to user name home directories.
288 .El
289 .Pp
290 If, during the search, a directory is encountered that cannot be opened
291 or read and
292 .Fa errfunc
293 is
294 .Pf non- Dv NULL ,
295 .Fn glob
296 calls
297 .Fa (*errfunc)(path, errno) .
298 This may be unintuitive: a pattern like
299 .Ql */Makefile
300 will try to
301 .Xr stat 2
302 .Ql foo/Makefile
303 even if
304 .Ql foo
305 is not a directory, resulting in a
306 call to
307 .Fa errfunc .
308 The error routine can suppress this action by testing for
309 .Dv ENOENT
310 and
311 .Dv ENOTDIR ;
312 however, the
313 .Dv GLOB_ERR
314 flag will still cause an immediate
315 return when this happens.
316 .Pp
317 If
318 .Fa errfunc
319 returns non-zero,
320 .Fn glob
321 stops the scan and returns
322 .Dv GLOB_ABORTED
323 after setting
324 .Fa gl_pathc
325 and
326 .Fa gl_pathv
327 to reflect any paths already matched.
328 This also happens if an error is encountered and
329 .Dv GLOB_ERR
330 is set in
331 .Fa flags ,
332 regardless of the return value of
333 .Fa errfunc ,
334 if called.
335 If
336 .Dv GLOB_ERR
337 is not set and either
338 .Fa errfunc
339 is
340 .Dv NULL
341 or
342 .Fa errfunc
343 returns zero, the error is ignored.
344 .Pp
345 The
346 .Fn globfree
347 function frees any space associated with
348 .Fa pglob
349 from a previous call(s) to
350 .Fn glob .
351 .Pp
352 The
353 .Fn glob_pattern_p
354 returns
355 .Dv 1
356 if the
357 .Fa pattern
358 has any special characters that
359 .Fn glob
360 will interpret and
361 .Dv 0
362 otherwise.
363 If the
364 .Fa quote
365 argument is non-zero, then backslash quoted characters are ignored.
366 .Pp
367 The historical
368 .Dv GLOB_QUOTE
369 flag is no longer supported.
370 Per
371 .St -p1003.2-92 ,
372 backslash escaping of special characters is the default behaviour;
373 it may be disabled by specifying the
374 .Dv GLOB_NOESCAPE
375 flag.
376 .Sh RETURN VALUES
377 On successful completion,
378 .Fn glob
379 returns zero.
380 In addition the fields of
381 .Fa pglob
382 contain the values described below:
383 .Bl -tag -width GLOB_NOCHECK
384 .It Fa gl_pathc
385 contains the total number of matched pathnames so far.
386 This includes other matches from previous invocations of
387 .Fn glob
388 if
389 .Dv GLOB_APPEND
390 was specified.
391 .It Fa gl_matchc
392 contains the number of matched pathnames in the current invocation of
393 .Fn glob .
394 .It Fa gl_flags
395 contains a copy of the
396 .Fa flags
397 parameter with the bit
398 .Dv GLOB_MAGCHAR
399 set if
400 .Fa pattern
401 contained any of the special characters ``*'', ``?'' or ``['', cleared
402 if not.
403 .It Fa gl_pathv
404 contains a pointer to a
405 .Dv NULL Ns -terminated
406 list of matched pathnames.
407 However, if
408 .Fa gl_pathc
409 is zero, the contents of
410 .Fa gl_pathv
411 are undefined.
412 .El
413 .Pp
414 If
415 .Fn glob
416 terminates due to an error, it sets
417 .Va errno
418 and returns one of the following non-zero constants, which are defined
419 in the include file
420 .In glob.h :
421 .Bl -tag -width GLOB_ABORTEDXXX
422 .It Dv GLOB_ABORTED
423 The scan was stopped because an error was encountered and either
424 .Dv GLOB_ERR
425 was set or
426 .Fa (*errfunc)()
427 returned non-zero.
428 .It Dv GLOB_NOMATCH
429 The pattern does not match any existing pathname, and
430 .Dv GLOB_NOCHECK
431 was not set in
432 .Dv flags .
433 .It Dv GLOB_NOSPACE
434 An attempt to allocate memory failed, or if
435 .Va errno
436 was 0
437 .Li GLOB_LIMIT
438 was specified in the flags and
439 .Li ARG_MAX
440 patterns were matched.
441 .El
442 .Pp
443 The historical
444 .Dv GLOB_ABEND
445 return constant is no longer supported.
446 Portable applications should use the
447 .Dv GLOB_ABORTED
448 constant instead.
449 .Pp
450 The arguments
451 .Fa pglob\-\*[Gt]gl_pathc
452 and
453 .Fa pglob\-\*[Gt]gl_pathv
454 are still set as specified above.
455 .Sh ENVIRONMENT
456 .Bl -tag -width HOME -compact
457 .It Ev HOME
458 If defined, used as the home directory of the current user in
459 tilde expansions.
460 .El
461 .Sh EXAMPLES
462 A rough equivalent of
463 .Ql "ls -l *.c *.h"
464 can be obtained with the
465 following code:
466 .Bd -literal -offset indent
467 glob_t g;
469 g.gl_offs = 2;
470 glob("*.c", GLOB_DOOFFS, NULL, \*[Am]g);
471 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, \*[Am]g);
472 g.gl_pathv[0] = "ls";
473 g.gl_pathv[1] = "-l";
474 execvp("ls", g.gl_pathv);
475 .Ed
476 .Sh SEE ALSO
477 .Xr sh 1 ,
478 .Xr fnmatch 3 ,
479 .Xr regexp 3 ,
480 .Xr glob 7
481 .Sh STANDARDS
482 The
483 .Fn glob
484 function is expected to be
485 .St -p1003.2
486 compatible with the exception
487 that the flags
488 .Dv GLOB_ALTDIRFUNC ,
489 .Dv GLOB_BRACE ,
490 .Dv GLOB_LIMIT ,
491 .Dv GLOB_MAGCHAR ,
492 .Dv GLOB_NOESCAPE ,
493 .Dv GLOB_NOMAGIC ,
494 .Dv GLOB_NO_DOTDIRS ,
495 .Dv GLOB_PERIOD ,
496 .Dv GLOB_STAR ,
497 .Dv GLOB_TILDE ,
498 and the fields
499 .Fa gl_matchc
500 and
501 .Fa gl_flags
502 should not be used by applications striving for strict
503 .Tn POSIX
504 conformance.
505 .Sh HISTORY
506 The
507 .Fn glob
508 and
509 .Fn globfree
510 functions first appeared in
511 .Bx 4.4 .
512 The
513 .Fn glob_pattern_p
514 function is modelled after the one found in glibc.
515 .Sh BUGS
516 Patterns longer than
517 .Dv MAXPATHLEN
518 may cause unchecked errors.
519 .Pp
520 The
521 .Fn glob
522 function may fail and set
523 .Va errno
524 for any of the errors specified for the library routines
525 .Xr stat 2 ,
526 .Xr closedir 3 ,
527 .Xr opendir 3 ,
528 .Xr readdir 3 ,
529 .Xr malloc 3 ,
530 and
531 .Xr free 3 .