| blob | f369fc6be73955cc9fcce38e057eb651f1a9454d |
1 .\" $NetBSD: glob.3,v 1.17 2001/03/16 21:09:05 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 March 31, 1998
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 .Fd #include <glob.h>
45 .Ft int
46 .Fn glob "const char *pattern" "int flags" "const 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 .Pa 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 int gl_pathc; /* count of total paths so far */
64 int gl_matchc; /* count of paths matching pattern */
65 int 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 .Pa 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 is set to 1, and the number of matched
186 pathnames set to 0.
187 .It Dv GLOB_NOSORT
188 By default, the pathnames are sorted in ascending
189 .Tn ASCII
190 order;
191 this flag prevents that sorting (speeding up
192 .Fn glob ) .
193 .El
194 .Pp
195 The following values may also be included in
196 .Fa flags ,
197 however, they are non-standard extensions to
198 .St -p1003.2 .
199 .Bl -tag -width GLOB_ALTDIRFUNC
200 .It Dv GLOB_ALTDIRFUNC
201 The following additional fields in the pglob structure have been
202 initialized with alternate functions for glob to use to open, read,
203 and close directories and to get stat information on names found
204 in those directories.
205 .Bd -literal
206 void *(*gl_opendir)(const char * name);
207 struct dirent *(*gl_readdir)(void *);
208 void (*gl_closedir)(void *);
209 int (*gl_lstat)(const char *name, struct stat *st);
210 int (*gl_stat)(const char *name, struct stat *st);
211 .Ed
212 .Pp
213 This extension is provided to allow programs such as
214 .Xr restore 8
215 to provide globbing from directories stored on tape.
216 .It Dv GLOB_BRACE
217 Pre-process the pattern string to expand
218 .Ql {pat,pat,...}
219 strings like
220 .Xr csh 1 .
221 The pattern
222 .Ql {}
223 is left unexpanded for historical reasons
224 .Po
225 .Xr csh 1
226 does the same thing to ease typing of
227 .Xr find 1
228 patterns
229 .Pc .
230 .It Dv GLOB_MAGCHAR
231 Set by the
232 .Fn glob
233 function if the pattern included globbing characters.
234 See the description of the usage of the
235 .Fa gl_matchc
236 structure member for more details.
237 .It Dv GLOB_NOMAGIC
238 Is the same as
239 .Dv GLOB_NOCHECK
240 but it only appends the
241 .Fa pattern
242 if it does not contain any of the special characters ``*'', ``?'' or ``[''.
243 .Dv GLOB_NOMAGIC
244 is provided to simplify implementing the historic
245 .Xr csh 1
246 globbing behavior and should probably not be used anywhere else.
247 .It Dv GLOB_NOESCAPE
248 Disable the use of the backslash
249 .Pq Ql \e
250 character for quoting.
251 .It Dv GLOB_TILDE
252 Expand patterns that start with
253 .Ql ~
254 to user name home directories.
255 .It Dv GLOB_LIMIT
256 Limit the amount of memory used by matches to
257 .Li ARG_MAX
258 This option should be set for programs that can be coerced to a denial of
259 service attack via patterns that expand to a very large number of matches,
260 such as a long string of
261 .Li */../*/..
262 .El
263 .Pp
264 If, during the search, a directory is encountered that cannot be opened
265 or read and
266 .Fa errfunc
267 is
268 .Pf non- Dv NULL ,
269 .Fn glob
270 calls
271 .Fa (*errfunc)(path, errno) .
272 This may be unintuitive: a pattern like
273 .Ql */Makefile
274 will try to
275 .Xr stat 2
276 .Ql foo/Makefile
277 even if
278 .Ql foo
279 is not a directory, resulting in a
280 call to
281 .Fa errfunc .
282 The error routine can suppress this action by testing for
283 .Dv ENOENT
284 and
285 .Dv ENOTDIR ;
286 however, the
287 .Dv GLOB_ERR
288 flag will still cause an immediate
289 return when this happens.
290 .Pp
291 If
292 .Fa errfunc
293 returns non-zero,
294 .Fn glob
295 stops the scan and returns
296 .Dv GLOB_ABORTED
297 after setting
298 .Fa gl_pathc
299 and
300 .Fa gl_pathv
301 to reflect any paths already matched.
302 This also happens if an error is encountered and
303 .Dv GLOB_ERR
304 is set in
305 .Fa flags ,
306 regardless of the return value of
307 .Fa errfunc ,
308 if called.
309 If
310 .Dv GLOB_ERR
311 is not set and either
312 .Fa errfunc
313 is
314 .Dv NULL
315 or
316 .Fa errfunc
317 returns zero, the error is ignored.
318 .Pp
319 The
320 .Fn globfree
321 function frees any space associated with
322 .Fa pglob
323 from a previous call(s) to
324 .Fn glob .
325 .Pp
326 The historical
327 .Dv GLOB_QUOTE
328 flag is no longer supported.
329 Per
330 .St -p1003.2-92 ,
331 backslash escaping of special characters is the default behaviour;
332 it may be disabled by specifying the
333 .Dv GLOB_NOESCAPE
334 flag.
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 parameter 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 following non-zero constants, which are defined
378 in the include file
379 .Aq Pa glob.h :
380 .Bl -tag -width GLOB_ABORTEDXXX
381 .It Dv GLOB_ABORTED
382 The scan was stopped because an error was encountered and either
383 .Dv GLOB_ERR
384 was set or
385 .Fa (*errfunc)()
386 returned non-zero.
387 .It Dv GLOB_NOMATCH
388 The pattern does not match any existing pathname, and
389 .Dv GLOB_NOCHECK
390 was not set int
391 .Dv flags .
392 .It Dv GLOB_NOSPACE
393 An attempt to allocate memory failed, or if
394 .Va errno
395 was 0
396 .Li GLOB_LIMIT
397 was specified in the flags and
398 .Li ARG_MAX
399 patterns were matched.
400 .El
401 .Pp
402 The historical
403 .Dv GLOB_ABEND
404 return constant is no longer supported. Portable applications should use the
405 .Dv GLOB_ABORTED
406 constant instead.
407 .Pp
408 The arguments
409 .Fa pglob\->gl_pathc
410 and
411 .Fa pglob\->gl_pathv
412 are still set as specified above.
413 .Sh ENVIRONMENT
414 .Bl -tag -width HOME -compact
415 .It Ev HOME
416 If defined, used as the home directory of the current user in
417 tilde expansions.
418 .El
419 .Sh EXAMPLE
420 A rough equivalent of
421 .Ql "ls -l *.c *.h"
422 can be obtained with the
423 following code:
424 .Bd -literal -offset indent
425 glob_t g;
427 g.gl_offs = 2;
428 glob("*.c", GLOB_DOOFFS, NULL, &g);
429 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
430 g.gl_pathv[0] = "ls";
431 g.gl_pathv[1] = "-l";
432 execvp("ls", g.gl_pathv);
433 .Ed
434 .Sh SEE ALSO
435 .Xr sh 1 ,
436 .Xr fnmatch 3 ,
437 .Xr regexp 3
438 .Sh STANDARDS
439 The
440 .Fn glob
441 function is expected to be
442 .St -p1003.2
443 compatible with the exception
444 that the flags
445 .Dv GLOB_ALTDIRFUNC,
446 .Dv GLOB_BRACE
447 .Dv GLOB_MAGCHAR,
448 .Dv GLOB_NOMAGIC,
449 .Dv GLOB_TILDE,
450 and
451 .Dv GLOB_LIMIT
452 and the fields
453 .Fa gl_matchc
454 and
455 .Fa gl_flags
456 should not be used by applications striving for strict
457 .Tn POSIX
458 conformance.
459 .Sh HISTORY
460 The
461 .Fn glob
462 and
463 .Fn globfree
464 functions first appeared in
465 .Bx 4.4 .
466 .Sh BUGS
467 Patterns longer than
468 .Dv MAXPATHLEN
469 may cause unchecked errors.
470 .Pp
471 The
472 .Fn glob
473 function may fail and set
474 .Va errno
475 for any of the errors specified for the library routines
476 .Xr stat 2 ,
477 .Xr closedir 3 ,
478 .Xr opendir 3 ,
479 .Xr readdir 3 ,
480 .Xr malloc 3 ,
481 and
482 .Xr free 3 .