1 .\" Copyright (c) 1989 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
7 .\" Redistribution and use in source and binary forms are permitted provided
8 .\" that: (1) source distributions retain this entire copyright notice and
9 .\" comment, and (2) distributions including binaries display the following
10 .\" acknowledgement: ``This product includes software developed by the
11 .\" University of California, Berkeley and its contributors'' in the
12 .\" documentation or other materials provided with the distribution and in
13 .\" all advertising materials mentioning features or use of this software.
14 .\" Neither the name of the University nor the names of its contributors may
15 .\" be used to endorse or promote products derived from this software without
16 .\" specific prior written permission.
17 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
18 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
21 .\" @(#)glob.3 5.3 (Berkeley) 3/19/91
23 .TH GLOB 3 "March 19, 1991"
26 glob, globfree \- generate pathnames matching a pattern
31 glob(const char *pattern, int flags,
32 const int (*errfunc)(char *, int), glob_t *pglob);
34 void globfree(glob_t *pglob);
38 is a pathname generator that implements the rules for file name pattern
39 matching used by the shell.
43 defines the structure type
45 which contains at least the following fields:
49 .ta .5i +\w'char **gl_pathv;\0\0\0'u
51 int gl_pathc; /* count of total paths so far */
52 int gl_matchc; /* count of paths matching pattern */
53 int gl_offs; /* reserved at beginning of gl_pathv */
54 int gl_flags; /* returned flags */
55 char **gl_pathv; /* list of paths matching pattern */
62 is a pointer to a pathname pattern to be expanded.
64 matches all accessible pathnames against the pattern and creates
65 a list of the pathnames that match.
66 In order to have access to a pathname,
68 requires search permission on every component of a path except the last
69 and read permission on each directory of any filename component of
71 that contains any of the special characters ``*'', ``?'' or ``[''.
74 stores the number of matched pathnames into the
76 field, and a pointer to a list of pointers to pathnames into the
79 The first pointer after the last pathname is NULL.
80 If the pattern does not match any pathnames, the returned number of
81 matched paths is set to zero.
83 It is the caller's responsibility to create the structure pointed to by
87 function allocates other space as needed, including the memory pointed
93 is used to modify the behavior of
97 is the bitwise inclusive OR of any of the following
102 Append pathnames generated to the ones from a previous call (or calls)
107 will be the total matches found by this call and the previous call(s).
108 The pathnames are appended to, not merged with the pathnames returned by
109 the previous call(s).
110 Between calls, the caller must not change the setting of the
111 GLOB_DOOFFS flag, nor change the value of
114 GLOB_DOOFFS is set, nor (obviously) call
125 is used to specify how many NULL pointers to prepend to the beginning
136 pathname pointers, followed by a NULL pointer.
141 to return when it encounters a directory that it cannot open or read.
144 continues to find matches.
147 Each pathname that is a directory that matches
153 By default, the pathnames are sorted in ascending ASCII order;
154 this flag prevents that sorting (speeding up
160 does not match any pathname, then
165 with the number of total pathnames is set to 1, and the number of matched
169 is set, its effect is present in the pattern returned.
172 Use the backslash (``\e'') character for quoting: every occurrence of
173 a backslash followed by a character in the pattern is replaced by that
174 character, avoiding any special interpretation of the character.
177 Is the same as GLOB_NOCHECK but it only appends the
179 if it does not contain any of the special characters ``*'', ``?'' or ``[''.
180 GLOB_NOMAGIC is used to simplify implementing the globbing behavior in
183 If, during the search, a directory is encountered that cannot be opened
188 calls (*\fIerrfunc\fP)(\fIpath\fP, \fIerrno\fP).
189 This may be unintuitive: a pattern like ``*/Makefile'' will try to
191 ``foo/Makefile'' even if ``foo'' is not a directory, resulting in a
194 The error routine can suppress this action by testing for ENOENT and
195 ENOTDIR; however, the GLOB_ERR flag will still cause an immediate
196 return when this happens.
202 stops the scan and returns
208 to reflect any paths already matched.
209 This also happens if an error is encountered and
213 regardless of the return value of
218 is not set and either
222 returns zero, the error is ignored.
226 function frees any space associated with
228 from a previous call(s) to
231 On successful completion,
234 In addition the fields of
236 contain the values described below:
239 contains the total number of matched pathnames so far.
240 This includes other matches from previous invocations of
247 contains the number of matched pathnames in the current invocation of
251 contains a copy of the
253 parameter with the bit GLOB_MAGCHAR set if
255 contained any of the special characters ``*'', ``?'' or ``['', cleared
259 contains a pointer to a NULL-terminated list of matched pathnames.
262 is zero, the contents of
268 terminates due to an error, it sets errno and returns one of the
269 following non-zero constants, which are defined in the include
273 An attempt to allocate memory failed.
276 The scan was stopped because an error was encountered and either
277 GLOB_ERR was set or (*\fIerrfunc\fR)() returned non-zero.
283 are still set as specified above.
287 function is expected to be POSIX 1003.2 compatible with the exception
294 should not be used by applications striving for strict POSIX conformance.
296 A rough equivalent of ``ls -l *.c *.h'' can be obtained with the
304 glob("*.c", GLOB_DOOFFS, NULL, &g);
305 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
306 g.gl_pathv[0] = "ls";
307 g.gl_pathv[1] = "-l";
308 execvp("ls", g.gl_pathv);
312 sh(1), fnmatch(3), wordexp(3), regexp(3)
314 Patterns longer than MAXPATHLEN may cause unchecked errors.
317 may fail and set errno for any of the errors specified for the