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