1 .\" Copyright (c) 1989, 1991, 1993, 1994
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
30 .\" @(#)glob.3 8.3 (Berkeley) 4/16/94
38 .Nd generate pathnames matching a pattern
44 .Fn glob "const char * restrict pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t * restrict pglob"
46 .Fn globfree "glob_t *pglob"
51 is a pathname generator that implements the rules for file name pattern
52 matching used by the shell.
56 defines the structure type
58 which contains at least the following fields:
61 size_t gl_pathc; /* count of total paths so far */
62 size_t gl_matchc; /* count of paths matching pattern */
63 size_t gl_offs; /* reserved at beginning of gl_pathv */
64 int gl_flags; /* returned flags */
65 char **gl_pathv; /* list of paths matching pattern */
71 is a pointer to a pathname pattern to be expanded.
75 matches all accessible pathnames against the pattern and creates
76 a list of the pathnames that match.
77 In order to have access to a pathname,
79 requires search permission on every component of a path except the last
80 and read permission on each directory of any filename component of
82 that contains any of the special characters
91 stores the number of matched pathnames into the
93 field, and a pointer to a list of pointers to pathnames into the
96 The first pointer after the last pathname is
98 If the pattern does not match any pathnames, the returned number of
99 matched paths is set to zero.
101 It is the caller's responsibility to create the structure pointed to by
105 function allocates other space as needed, including the memory pointed
111 is used to modify the behavior of
115 is the bitwise inclusive
117 of any of the following
120 .Bl -tag -width GLOB_ALTDIRFUNC
122 Append pathnames generated to the ones from a previous call (or calls)
127 will be the total matches found by this call and the previous call(s).
128 The pathnames are appended to, not merged with the pathnames returned by
129 the previous call(s).
130 Between calls, the caller must not change the setting of the
132 flag, nor change the value of
136 is set, nor (obviously) call
146 is used to specify how many
148 pointers to prepend to the beginning
160 pathname pointers, followed by a
166 to return when it encounters a directory that it cannot open or read.
169 continues to find matches.
171 Each pathname that is a directory that matches
178 does not match any pathname, then
183 with the number of total pathnames set to 1, and the number of matched
185 The effect of backslash escaping is present in the pattern returned.
187 By default, a backslash
189 character is used to escape the following character in the pattern,
190 avoiding any special interpretation of the character.
193 is set, backslash escaping is disabled.
195 By default, the pathnames are sorted in ascending
198 this flag prevents that sorting (speeding up
202 The following values may also be included in
204 however, they are non-standard extensions to
206 .Bl -tag -width GLOB_ALTDIRFUNC
207 .It Dv GLOB_ALTDIRFUNC
208 The following additional fields in the pglob structure have been
209 initialized with alternate functions for glob to use to open, read,
210 and close directories and to get stat information on names found
211 in those directories.
213 void *(*gl_opendir)(const char * name);
214 struct dirent *(*gl_readdir)(void *);
215 void (*gl_closedir)(void *);
216 int (*gl_lstat)(const char *name, struct stat *st);
217 int (*gl_stat)(const char *name, struct stat *st);
220 This extension is provided to allow programs such as
222 to provide globbing from directories stored on tape.
224 Pre-process the pattern string to expand
230 is left unexpanded for historical reasons (and
232 does the same thing to
240 function if the pattern included globbing characters.
241 See the description of the usage of the
243 structure member for more details.
247 but it only appends the
249 if it does not contain any of the special characters ``*'', ``?'' or ``[''.
251 is provided to simplify implementing the historic
253 globbing behavior and should probably not be used anywhere else.
255 Expand patterns that start with
257 to user name home directories.
259 Limit the total number of returned pathnames to the value provided in
263 This option should be set for programs
264 that can be coerced into a denial of service attack
265 via patterns that expand to a very large number of matches,
266 such as a long string of
270 If, during the search, a directory is encountered that cannot be opened
277 .Fa \*(lp*errfunc\*(rp Ns ( Fa path , errno ) ,
280 flag will cause an immediate
281 return when this happens.
287 stops the scan and returns
293 to reflect any paths already matched.
294 This also happens if an error is encountered and
298 regardless of the return value of
303 is not set and either
309 returns zero, the error is ignored.
313 function frees any space associated with
315 from a previous call(s) to
318 On successful completion,
321 In addition the fields of
323 contain the values described below:
324 .Bl -tag -width GLOB_NOCHECK
326 contains the total number of matched pathnames so far.
327 This includes other matches from previous invocations of
333 contains the number of matched pathnames in the current invocation of
336 contains a copy of the
338 argument with the bit
342 contained any of the special characters ``*'', ``?'' or ``['', cleared
345 contains a pointer to a
346 .Dv NULL Ns -terminated
347 list of matched pathnames.
350 is zero, the contents of
357 terminates due to an error, it sets errno and returns one of the
358 following non-zero constants, which are defined in the include
361 .Bl -tag -width GLOB_NOCHECK
363 An attempt to allocate memory failed, or if
367 was specified in the flags and
368 .Fa pglob\->gl_matchc
369 or more patterns were matched.
371 The scan was stopped because an error was encountered and either
374 .Fa \*(lp*errfunc\*(rp\*(lp\*(rp
377 The pattern did not match a pathname and
386 are still set as specified above.
388 A rough equivalent of
390 can be obtained with the
392 .Bd -literal -offset indent
396 glob("*.c", GLOB_DOOFFS, NULL, &g);
397 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
398 g.gl_pathv[0] = "ls";
399 g.gl_pathv[1] = "-l";
400 execvp("ls", g.gl_pathv);
407 The current implementation of the
413 Collating symbol expressions, equivalence class expressions and
414 character class expressions are not supported.
417 .Dv GLOB_ALTDIRFUNC ,
428 are extensions to the
431 should not be used by applications striving for strict
438 functions first appeared in
443 may cause unchecked errors.
448 may fail and set errno for any of the errors specified for the