Debian Codegraph @

upstream/debian-unstable/man3/glob.3

raw
1 '\" t
2 .\" Copyright 1993, Thomas Koenig <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH glob 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 glob, globfree \- find pathnames matching a pattern, free memory from glob()
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <glob.h>
16 .P
17 .BI "int glob(const char *restrict " pattern ", int " flags ,
18 .BI " typeof(int (const char *" epath ", int " eerrno ")) *" errfunc ,
19 .BI " glob_t *restrict " pglob );
20 .BI "void globfree(glob_t *" pglob );
21 .fi
22 .SH DESCRIPTION
23 The
24 .BR glob ()
25 function searches for all the pathnames matching
26 .I pattern
27 according to the rules used by the shell
28 (see
29 .BR glob (7)).
30 No tilde expansion or parameter substitution is done;
31 if you want these,
32 use
33 .BR wordexp (3).
34 .P
35 The
36 .BR globfree ()
37 function frees the dynamically allocated storage from an earlier call
38 to
39 .BR glob ().
40 .P
41 The results of a
42 .BR glob ()
43 call are stored in the structure pointed to by
44 .IR pglob .
45 This structure is of type
46 .I glob_t
47 (declared in
48 .IR <glob.h> )
49 and includes the following elements defined by POSIX.2 (more may be
50 present as an extension):
51 .P
52 .in +4n
53 .EX
54 typedef struct {
55 size_t gl_pathc; /* Count of paths matched so far */
56 char **gl_pathv; /* List of matched pathnames. */
57 size_t gl_offs; /* Slots to reserve in \f[I]gl_pathv\f[]. */
58 } glob_t;
59 .EE
60 .in
61 .P
62 Results are stored in dynamically allocated storage.
63 .P
64 The argument
65 .I flags
66 is made up of the bitwise OR of zero or more the following symbolic
67 constants, which modify the behavior of
68 .BR glob ():
69 .TP
70 .B GLOB_ERR
71 Return upon a read error (because a directory does not
72 have read permission, for example).
73 By default,
74 .BR glob ()
75 attempts carry on despite errors,
76 reading all of the directories that it can.
77 .TP
78 .B GLOB_MARK
79 Append a slash to each path which corresponds to a directory.
80 .TP
81 .B GLOB_NOSORT
82 Don't sort the returned pathnames.
83 The only reason to do this is to save processing time.
84 By default, the returned pathnames are sorted.
85 .TP
86 .B GLOB_DOOFFS
87 Reserve
88 .I pglob\->gl_offs
89 slots at the beginning of the list of strings in
90 .IR pglob\->pathv .
91 The reserved slots contain null pointers.
92 .TP
93 .B GLOB_NOCHECK
94 If no pattern matches, return the original pattern.
95 By default,
96 .BR glob ()
97 returns
98 .B GLOB_NOMATCH
99 if there are no matches.
100 .TP
101 .B GLOB_APPEND
102 Append the results of this call to the vector of results
103 returned by a previous call to
104 .BR glob ().
105 Do not set this flag on the first invocation of
106 .BR glob ().
107 .TP
108 .B GLOB_NOESCAPE
109 Don't allow backslash (\[aq]\[rs]\[aq]) to be used as an escape
110 character.
111 Normally, a backslash can be used to quote the following character,
112 providing a mechanism to turn off the special meaning
113 metacharacters.
114 .P
115 .I flags
116 may also include any of the following, which are GNU
117 extensions and not defined by POSIX.2:
118 .TP
119 .B GLOB_PERIOD
120 Allow a leading period to be matched by metacharacters.
121 By default, metacharacters can't match a leading period.
122 .TP
123 .B GLOB_ALTDIRFUNC
124 Use alternative functions
125 .IR pglob\->gl_closedir ,
126 .IR pglob\->gl_readdir ,
127 .IR pglob\->gl_opendir ,
128 .IR pglob\->gl_lstat ,
129 and
130 .I pglob\->gl_stat
131 for filesystem access instead of the normal library
132 functions.
133 .TP
134 .B GLOB_BRACE
135 Expand
136 .BR csh (1)
137 style brace expressions of the form
138 .BR {a,b} .
139 Brace expressions can be nested.
140 Thus, for example, specifying the pattern
141 "{foo/{,cat,dog},bar}" would return the same results as four separate
142 .BR glob ()
143 calls using the strings:
144 "foo/",
145 "foo/cat",
146 "foo/dog",
147 and
148 "bar".
149 .TP
150 .B GLOB_NOMAGIC
151 If the pattern contains no metacharacters,
152 then it should be returned as the sole matching word,
153 even if there is no file with that name.
154 .TP
155 .B GLOB_TILDE
156 Carry out tilde expansion.
157 If a tilde (\[aq]\[ti]\[aq]) is the only character in the pattern,
158 or an initial tilde is followed immediately by a slash (\[aq]/\[aq]),
159 then the home directory of the caller is substituted for
160 the tilde.
161 If an initial tilde is followed by a username (e.g., "\[ti]andrea/bin"),
162 then the tilde and username are substituted by the home directory
163 of that user.
164 If the username is invalid, or the home directory cannot be
165 determined, then no substitution is performed.
166 .TP
167 .B GLOB_TILDE_CHECK
168 This provides behavior similar to that of
169 .BR GLOB_TILDE .
170 The difference is that if the username is invalid, or the
171 home directory cannot be determined, then
172 instead of using the pattern itself as the name,
173 .BR glob ()
174 returns
175 .B GLOB_NOMATCH
176 to indicate an error.
177 .TP
178 .B GLOB_ONLYDIR
179 This is a
180 .I hint
181 to
182 .BR glob ()
183 that the caller is interested only in directories that match the pattern.
184 If the implementation can easily determine file-type information,
185 then nondirectory files are not returned to the caller.
186 However, the caller must still check that returned files
187 are directories.
188 (The purpose of this flag is merely to optimize performance when
189 the caller is interested only in directories.)
190 .P
191 If
192 .I errfunc
193 is not NULL,
194 it will be called in case of an error with the arguments
195 .IR epath ,
196 a pointer to the path which failed, and
197 .IR eerrno ,
198 the value of
199 .I errno
200 as returned from one of the calls to
201 .BR opendir (3),
202 .BR readdir (3),
203 or
204 .BR stat (2).
205 If
206 .I errfunc
207 returns nonzero, or if
208 .B GLOB_ERR
209 is set,
210 .BR glob ()
211 will terminate after the call to
212 .IR errfunc .
213 .P
214 Upon successful return,
215 .I pglob\->gl_pathc
216 contains the number of matched pathnames and
217 .I pglob\->gl_pathv
218 contains a pointer to the list of pointers to matched pathnames.
219 The list of pointers is terminated by a null pointer.
220 .P
221 It is possible to call
222 .BR glob ()
223 several times.
224 In that case, the
225 .B GLOB_APPEND
226 flag has to be set in
227 .I flags
228 on the second and later invocations.
229 .P
230 As a GNU extension,
231 .I pglob\->gl_flags
232 is set to the flags specified,
233 .BR or ed
234 with
235 .B GLOB_MAGCHAR
236 if any metacharacters were found.
237 .SH RETURN VALUE
238 On successful completion,
239 .BR glob ()
240 returns zero.
241 Other possible returns are:
242 .TP
243 .B GLOB_NOSPACE
244 for running out of memory,
245 .TP
246 .B GLOB_ABORTED
247 for a read error, and
248 .TP
249 .B GLOB_NOMATCH
250 for no found matches.
251 .SH ATTRIBUTES
252 For an explanation of the terms used in this section, see
253 .BR attributes (7).
254 .TS
255 allbox;
256 lb lb lbx
257 l l l.
258 Interface Attribute Value
259 T{
260 .na
261 .nh
262 .BR glob ()
263 T} Thread safety T{
264 .na
265 .nh
266 MT-Unsafe race:utent env
267 sig:ALRM timer locale
268 T}
269 T{
270 .na
271 .nh
272 .BR globfree ()
273 T} Thread safety MT-Safe
274 .TE
275 .P
276 In the above table,
277 .I utent
278 in
279 .I race:utent
280 signifies that if any of the functions
281 .BR setutent (3),
282 .BR getutent (3),
283 or
284 .BR endutent (3)
285 are used in parallel in different threads of a program,
286 then data races could occur.
287 .BR glob ()
288 calls those functions,
289 so we use race:utent to remind users.
290 .SH STANDARDS
291 POSIX.1-2008.
292 .SH HISTORY
293 POSIX.1-2001, POSIX.2.
294 .SH NOTES
295 The structure elements
296 .I gl_pathc
297 and
298 .I gl_offs
299 are declared as
300 .I size_t
301 in glibc 2.1, as they should be according to POSIX.2,
302 but are declared as
303 .I int
304 in glibc 2.0.
305 .SH BUGS
306 The
307 .BR glob ()
308 function may fail due to failure of underlying function calls, such as
309 .BR malloc (3)
310 or
311 .BR opendir (3).
312 These will store their error code in
313 .IR errno .
314 .SH EXAMPLES
315 One example of use is the following code, which simulates typing
316 .P
317 .in +4n
318 .EX
319 ls \-l *.c ../*.c
320 .EE
321 .in
322 .P
323 in the shell:
324 .P
325 .in +4n
326 .EX
327 glob_t globbuf;
328 \&
329 globbuf.gl_offs = 2;
330 glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
331 glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
332 globbuf.gl_pathv[0] = "ls";
333 globbuf.gl_pathv[1] = "\-l";
334 execvp("ls", &globbuf.gl_pathv[0]);
335 .EE
336 .in
337 .SH SEE ALSO
338 .BR ls (1),
339 .BR sh (1),
340 .BR stat (2),
341 .BR exec (3),
342 .BR fnmatch (3),
343 .BR malloc (3),
344 .BR opendir (3),
345 .BR readdir (3),
346 .BR wordexp (3),
347 .BR glob (7)