Debian Codegraph @

upstream/debian-trixie/man3/glob.3

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