| blob | 50b5b7d46f8912d89525910ce23d2ada8cbbc079 |
1 .\" $NetBSD: glob.3,v 1.34 2009/04/08 19:27:39 wiz 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 April 8, 2009
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 by matches to
260 .Li ARG_MAX .
261 This option should be set for programs that can be coerced to a denial of
262 service attack via patterns that expand to a very large number of matches,
263 such as a long string of
264 .Li */../*/..
265 .It Dv GLOB_PERIOD
266 Allow metacharacters to match a leading period in a filename.
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 .El
276 .Pp
277 If, during the search, a directory is encountered that cannot be opened
278 or read and
279 .Fa errfunc
280 is
281 .Pf non- Dv NULL ,
282 .Fn glob
283 calls
284 .Fa (*errfunc)(path, errno) .
285 This may be unintuitive: a pattern like
286 .Ql */Makefile
287 will try to
288 .Xr stat 2
289 .Ql foo/Makefile
290 even if
291 .Ql foo
292 is not a directory, resulting in a
293 call to
294 .Fa errfunc .
295 The error routine can suppress this action by testing for
296 .Dv ENOENT
297 and
298 .Dv ENOTDIR ;
299 however, the
300 .Dv GLOB_ERR
301 flag will still cause an immediate
302 return when this happens.
303 .Pp
304 If
305 .Fa errfunc
306 returns non-zero,
307 .Fn glob
308 stops the scan and returns
309 .Dv GLOB_ABORTED
310 after setting
311 .Fa gl_pathc
312 and
313 .Fa gl_pathv
314 to reflect any paths already matched.
315 This also happens if an error is encountered and
316 .Dv GLOB_ERR
317 is set in
318 .Fa flags ,
319 regardless of the return value of
320 .Fa errfunc ,
321 if called.
322 If
323 .Dv GLOB_ERR
324 is not set and either
325 .Fa errfunc
326 is
327 .Dv NULL
328 or
329 .Fa errfunc
330 returns zero, the error is ignored.
331 .Pp
332 The
333 .Fn globfree
334 function frees any space associated with
335 .Fa pglob
336 from a previous call(s) to
337 .Fn glob .
338 .Pp
339 The
340 .Fn glob_pattern_p
341 returns
342 .Dv 1
343 if the
344 .Fa pattern
345 has any special characters that
346 .Fn glob
347 will interpret and
348 .Dv 0
349 otherwise.
350 If the
351 .Fa quote
352 argument is non-zero, then backslash quoted characters are ignored.
353 .Pp
354 The historical
355 .Dv GLOB_QUOTE
356 flag is no longer supported.
357 Per
358 .St -p1003.2-92 ,
359 backslash escaping of special characters is the default behaviour;
360 it may be disabled by specifying the
361 .Dv GLOB_NOESCAPE
362 flag.
363 .Sh RETURN VALUES
364 On successful completion,
365 .Fn glob
366 returns zero.
367 In addition the fields of
368 .Fa pglob
369 contain the values described below:
370 .Bl -tag -width GLOB_NOCHECK
371 .It Fa gl_pathc
372 contains the total number of matched pathnames so far.
373 This includes other matches from previous invocations of
374 .Fn glob
375 if
376 .Dv GLOB_APPEND
377 was specified.
378 .It Fa gl_matchc
379 contains the number of matched pathnames in the current invocation of
380 .Fn glob .
381 .It Fa gl_flags
382 contains a copy of the
383 .Fa flags
384 parameter with the bit
385 .Dv GLOB_MAGCHAR
386 set if
387 .Fa pattern
388 contained any of the special characters ``*'', ``?'' or ``['', cleared
389 if not.
390 .It Fa gl_pathv
391 contains a pointer to a
392 .Dv NULL Ns -terminated
393 list of matched pathnames.
394 However, if
395 .Fa gl_pathc
396 is zero, the contents of
397 .Fa gl_pathv
398 are undefined.
399 .El
400 .Pp
401 If
402 .Fn glob
403 terminates due to an error, it sets
404 .Va errno
405 and returns one of the following non-zero constants, which are defined
406 in the include file
407 .Aq Pa glob.h :
408 .Bl -tag -width GLOB_ABORTEDXXX
409 .It Dv GLOB_ABORTED
410 The scan was stopped because an error was encountered and either
411 .Dv GLOB_ERR
412 was set or
413 .Fa (*errfunc)()
414 returned non-zero.
415 .It Dv GLOB_NOMATCH
416 The pattern does not match any existing pathname, and
417 .Dv GLOB_NOCHECK
418 was not set in
419 .Dv flags .
420 .It Dv GLOB_NOSPACE
421 An attempt to allocate memory failed, or if
422 .Va errno
423 was 0
424 .Li GLOB_LIMIT
425 was specified in the flags and
426 .Li ARG_MAX
427 patterns were matched.
428 .El
429 .Pp
430 The historical
431 .Dv GLOB_ABEND
432 return constant is no longer supported.
433 Portable applications should use the
434 .Dv GLOB_ABORTED
435 constant instead.
436 .Pp
437 The arguments
438 .Fa pglob\-\*[Gt]gl_pathc
439 and
440 .Fa pglob\-\*[Gt]gl_pathv
441 are still set as specified above.
442 .Sh ENVIRONMENT
443 .Bl -tag -width HOME -compact
444 .It Ev HOME
445 If defined, used as the home directory of the current user in
446 tilde expansions.
447 .El
448 .Sh EXAMPLES
449 A rough equivalent of
450 .Ql "ls -l *.c *.h"
451 can be obtained with the
452 following code:
453 .Bd -literal -offset indent
454 glob_t g;
456 g.gl_offs = 2;
457 glob("*.c", GLOB_DOOFFS, NULL, \*[Am]g);
458 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, \*[Am]g);
459 g.gl_pathv[0] = "ls";
460 g.gl_pathv[1] = "-l";
461 execvp("ls", g.gl_pathv);
462 .Ed
463 .Sh SEE ALSO
464 .Xr sh 1 ,
465 .Xr fnmatch 3 ,
466 .Xr regexp 3
467 .Sh STANDARDS
468 The
469 .Fn glob
470 function is expected to be
471 .St -p1003.2
472 compatible with the exception
473 that the flags
474 .Dv GLOB_ALTDIRFUNC ,
475 .Dv GLOB_BRACE ,
476 .Dv GLOB_MAGCHAR ,
477 .Dv GLOB_NOMAGIC ,
478 .Dv GLOB_TILDE ,
479 and
480 .Dv GLOB_LIMIT
481 and the fields
482 .Fa gl_matchc
483 and
484 .Fa gl_flags
485 should not be used by applications striving for strict
486 .Tn POSIX
487 conformance.
488 .Sh HISTORY
489 The
490 .Fn glob
491 and
492 .Fn globfree
493 functions first appeared in
494 .Bx 4.4 .
495 The
496 .Fn glob_pattern_p
497 function is modelled after the one found in glibc.
498 .Sh BUGS
499 Patterns longer than
500 .Dv MAXPATHLEN
501 may cause unchecked errors.
502 .Pp
503 The
504 .Fn glob
505 function may fail and set
506 .Va errno
507 for any of the errors specified for the library routines
508 .Xr stat 2 ,
509 .Xr closedir 3 ,
510 .Xr opendir 3 ,
511 .Xr readdir 3 ,
512 .Xr malloc 3 ,
513 and
514 .Xr free 3 .