1 '\" te
2 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
10 .TH GLOB 3C "Nov 1, 2003"
11 .SH NAME
12 glob, globfree \- generate path names matching a pattern
13 .SH SYNOPSIS
14 .LP
15 .nf
16 #include <glob.h>
17
18 \fBint\fR \fBglob\fR(\fBconst char *restrict\fR \fIpattern\fR, \fBint\fR \fIflags\fR,
19 \fBint(*\fR\fIerrfunc\fR)(const char *\fIepath\fR, int \fIeerrno)\fR,
20 \fBglob_t *restrict\fR \fIpglob\fR);
21 .fi
22
23 .LP
24 .nf
25 \fBvoid\fR \fBglobfree\fR(\fBglob_t *\fR\fIpglob\fR);
26 .fi
27
28 .SH DESCRIPTION
29 .sp
30 .LP
31 The \fBglob()\fR function is a path name generator.
32 .sp
33 .LP
34 The \fBglobfree()\fR function frees any memory allocated by \fBglob()\fR
35 associated with \fIpglob\fR.
36 .SS "\fIpattern\fR Argument"
37 .sp
38 .LP
39 The argument \fIpattern\fR is a pointer to a path name pattern to be expanded.
40 The \fBglob()\fR function matches all accessible path names against this
41 pattern and develops a list of all path names that match. In order to have
42 access to a path name, \fBglob()\fR requires search permission on every
43 component of a path except the last, and read permission on each directory of
44 any filename component of \fIpattern\fR that contains any of the following
45 special characters:
46 .sp
47 .in +2
48 .nf
49 * ? [
50 .fi
51 .in -2
52
53 .SS "\fIpglob\fR Argument"
54 .sp
55 .LP
56 The structure type \fBglob_t\fR is defined in the header \fB<glob.h>\fR and
57 includes at least the following members:
58 .sp
59 .in +2
60 .nf
61 size_t gl_pathc; /* count of paths matched by */
62 /* pattern */
63 char **gl_pathv; /* pointer to list of matched */
64 /* path names */
65 size_t gl_offs; /* slots to reserve at beginning */
66 /* of gl_pathv */
67 .fi
68 .in -2
69
70 .sp
71 .LP
72 The \fBglob()\fR function stores the number of matched path names into
73 \fIpglob\(mi>\fR\fBgl_pathc\fR and a pointer to a list of pointers to path
74 names into \fIpglob\(mi>\fR\fBgl_pathv.\fR The path names are in sort order as
75 defined by the current setting of the \fBLC_COLLATE\fR category. The first
76 pointer after the last path name is a \fINULL\fR pointer. If the pattern does
77 not match any path names, the returned number of matched paths is set to 0, and
78 the contents of \fIpglob\(mi>\fR\fBgl_pathv\fR are implementation-dependent.
79 .sp
80 .LP
81 It is the caller's responsibility to create the structure pointed to by
82 \fIpglob\fR. The \fBglob()\fR function allocates other space as needed,
83 including the memory pointed to by \fBgl_pathv\fR. The \fBglobfree()\fR
84 function frees any space associated with \fIpglob\fR from a previous call to
85 \fBglob()\fR.
86 .SS "\fIflags\fR Argument"
87 .sp
88 .LP
89 The \fIflags\fR argument is used to control the behavior of \fBglob()\fR. The
90 value of \fIflags\fR is a bitwise inclusive \fBOR\fR of zero or more of the
91 following constants, which are defined in the header <\fBglob.h\fR>:
92 .sp
93 .ne 2
94 .na
95 \fB\fBGLOB_APPEND\fR\fR
96 .ad
97 .RS 17n
98 Append path names generated to the ones from a previous call to \fBglob()\fR.
99 .RE
100
101 .sp
102 .ne 2
103 .na
104 \fB\fBGLOB_DOOFFS\fR\fR
105 .ad
106 .RS 17n
107 Make use of \fIpglob\(mi>\fR\fBgl_offs\fR\fI\&.\fR If this flag is set,
108 \fIpglob\(mi>\fR\fBgl_offs\fR is used to specify how many \fINULL\fR pointers
109 to add to the beginning of \fIpglob\(mi>\fR\fBgl_pathv\fR\fI\&.\fR In other
110 words, \fIpglob\(mi>\fR\fBgl_pathv\fR will point to
111 \fIpglob\(mi>\fR\fBgl_offs\fR \fINULL\fR pointers, followed by
112 \fIpglob\(mi>\fR\fBgl_pathc\fR path name pointers, followed by a \fINULL\fR
113 pointer.
114 .RE
115
116 .sp
117 .ne 2
118 .na
119 \fB\fBGLOB_ERR\fR\fR
120 .ad
121 .RS 17n
122 Causes \fBglob()\fR to return when it encounters a directory that it cannot
123 open or read. Ordinarily, \fBglob()\fR continues to find matches.
124 .RE
125
126 .sp
127 .ne 2
128 .na
129 \fB\fBGLOB_MARK\fR\fR
130 .ad
131 .RS 17n
132 Each path name that is a directory that matches \fIpattern\fR has a slash
133 appended.
134 .RE
135
136 .sp
137 .ne 2
138 .na
139 \fB\fBGLOB_NOCHECK\fR\fR
140 .ad
141 .RS 17n
142 If \fIpattern\fR does not match any path name, then \fBglob()\fR returns a list
143 consisting of only \fIpattern\fR, and the number of matched path names is 1.
144 .RE
145
146 .sp
147 .ne 2
148 .na
149 \fB\fBGLOB_NOESCAPE\fR\fR
150 .ad
151 .RS 17n
152 Disable backslash escaping.
153 .RE
154
155 .sp
156 .ne 2
157 .na
158 \fB\fBGLOB_NOSORT\fR\fR
159 .ad
160 .RS 17n
161 Ordinarily, \fBglob()\fR sorts the matching path names according to the current
162 setting of the \fBLC_COLLATE\fR category. When this flag is used the order of
163 path names returned is unspecified.
164 .RE
165
166 .sp
167 .LP
168 The \fBGLOB_APPEND\fR flag can be used to append a new set of path names to
169 those found in a previous call to \fBglob()\fR. The following rules apply when
170 two or more calls to \fBglob()\fR are made with the same value of \fIpglob\fR
171 and without intervening calls to \fBglobfree()\fR:
172 .RS +4
173 .TP
174 1.
175 The first such call must not set \fBGLOB_APPEND.\fR All subsequent calls
176 must set it.
177 .RE
178 .RS +4
179 .TP
180 2.
181 All the calls must set \fBGLOB_DOOFFS,\fR or all must not set it.
182 .RE
183 .RS +4
184 .TP
185 3.
186 After the second call, \fIpglob\(mi>\fR\fBgl_pathv\fR points to a list
187 containing the following:
188 .RS +4
189 .TP
190 a.
191 Zero or more \fINULL\fR pointers, as specified by \fBGLOB_DOOFFS\fR and
192 \fIpglob\(mi>\fR\fBgl_offs\fR.
193 .RE
194 .RS +4
195 .TP
196 b.
197 Pointers to the path names that were in the \fIpglob\(mi>\fR\fBgl_pathv\fR
198 list before the call, in the same order as before.
199 .RE
200 .RS +4
201 .TP
202 c.
203 Pointers to the new path names generated by the second call, in the
204 specified order.
205 .RE
206 .RE
207 .RS +4
208 .TP
209 4.
210 The count returned in \fIpglob\(mi>\fR\fBgl_pathc\fR will be the total
211 number of path names from the two calls.
212 .RE
213 .RS +4
214 .TP
215 5.
216 The application can change any of the fields after a call to \fBglob()\fR.
217 If it does, it must reset them to the original value before a subsequent call,
218 using the same \fIpglob\fR value, to \fBglobfree()\fR or \fBglob()\fR with the
219 \fBGLOB_APPEND\fR flag.
220 .RE
221 .SS "\fIerrfunc\fR and \fIepath\fR Arguments"
222 .sp
223 .LP
224 If, during the search, a directory is encountered that cannot be opened or read
225 and \fIerrfunc\fR is not a \fINULL\fR pointer, \fBglob()\fR calls
226 \fB(\fR\fI*errfunc\fR\fB)\fR with two arguments:
227 .RS +4
228 .TP
229 1.
230 The \fIepath\fR argument is a pointer to the path that failed.
231 .RE
232 .RS +4
233 .TP
234 2.
235 The \fIeerrno\fR argument is the value of \fIerrno\fR from the failure, as
236 set by the \fBopendir\fR(3C), \fBreaddir\fR(3C) or \fBstat\fR(2) functions.
237 (Other values may be used to report other errors not explicitly documented for
238 those functions.)
239 .RE
240 .sp
241 .LP
242 The following constants are defined as error return values for \fBglob()\fR:
243 .sp
244 .ne 2
245 .na
246 \fB\fBGLOB_ABORTED\fR\fR
247 .ad
248 .RS 16n
249 The scan was stopped because \fBGLOB_ERR\fR was set or
250 \fB(\fR\fI*errfunc\fR\fB)\fR returned non-zero.
251 .RE
252
253 .sp
254 .ne 2
255 .na
256 \fB\fBGLOB_NOMATCH\fR\fR
257 .ad
258 .RS 16n
259 The pattern does not match any existing path name, and \fBGLOB_NOCHECK\fR was
260 not set in flags.
261 .RE
262
263 .sp
264 .ne 2
265 .na
266 \fB\fBGLOG_NOSPACE\fR\fR
267 .ad
268 .RS 16n
269 An attempt to allocate memory failed.
270 .RE
271
272 .sp
273 .LP
274 If \fB(\fR\fI*errfunc\fR\fB)\fR is called and returns non-zero, or if the
275 \fBGLOB_ERR\fR flag is set in \fIflags\fR, \fBglob()\fR stops the scan and
276 returns \fBGLOB_ABORTED\fR after setting \fIgl_pathc\fR and \fIgl_pathv\fR in
277 \fIpglob\fR to reflect the paths already scanned. If \fBGLOB_ERR\fR is not set
278 and either \fIerrfunc\fR is a \fINULL\fR pointer or
279 \fB(\fR\fI*errfunc\fR\fB)\fR returns 0, the error is ignored.
280 .SH RETURN VALUES
281 .sp
282 .LP
283 The following values are returned by \fBglob()\fR:
284 .sp
285 .ne 2
286 .na
287 \fB\fB0\fR\fR
288 .ad
289 .RS 12n
290 Successful completion. The argument \fIpglob\(mi>\fR\fBgl_pathc\fR returns the
291 number of matched path names and the argument \fIpglob\(mi>\fR\fBgl_pathv\fR
292 contains a pointer to a null-terminated list of matched and sorted path names.
293 However, if \fIpglob\(mi>\fR\fBgl_pathc\fR is 0, the content of
294 \fIpglob\(mi>\fR\fBgl_pathv\fR is undefined.
295 .RE
296
297 .sp
298 .ne 2
299 .na
300 \fB\fBnon-zero\fR\fR
301 .ad
302 .RS 12n
303 An error has occurred. Non-zero constants are defined in <\fBglob.h\fR>. The
304 arguments \fIpglob\(mi>\fR\fBgl_pathc\fR and \fIpglob\(mi>\fR\fBgl_pathv\fR are
305 still set as defined above.
306 .RE
307
308 .sp
309 .LP
310 The \fBglobfree()\fR function returns no value.
311 .SH USAGE
312 .sp
313 .LP
314 This function is not provided for the purpose of enabling utilities to perform
315 path name expansion on their arguments, as this operation is performed by the
316 shell, and utilities are explicitly not expected to redo this. Instead, it is
317 provided for applications that need to do path name expansion on strings
318 obtained from other sources, such as a pattern typed by a user or read from a
319 file.
320 .sp
321 .LP
322 If a utility needs to see if a path name matches a given pattern, it can use
323 \fBfnmatch\fR(3C).
324 .sp
325 .LP
326 Note that \fBgl_pathc\fR and \fBgl_pathv\fR have meaning even if \fBglob()\fR
327 fails. This allows \fBglob()\fR to report partial results in the event of an
328 error. However, if \fBgl_pathc\fR is 0, \fBgl_pathv\fR is unspecified even if
329 \fBglob()\fR did not return an error.
330 .sp
331 .LP
332 The \fBGLOB_NOCHECK\fR option could be used when an application wants to expand
333 a path name if wildcards are specified, but wants to treat the pattern as just
334 a string otherwise.
335 .sp
336 .LP
337 The new path names generated by a subsequent call with \fBGLOB_APPEND\fR are
338 not sorted together with the previous path names. This mirrors the way that the
339 shell handles path name expansion when multiple expansions are done on a
340 command line.
341 .sp
342 .LP
343 Applications that need tilde and parameter expansion should use the
344 \fBwordexp\fR(3C) function.
345 .SH EXAMPLES
346 .LP
347 \fBExample 1 \fRExample of \fBglob_doofs\fR function.
348 .sp
349 .LP
350 One use of the \fBGLOB_DOOFFS\fR flag is by applications that build an argument
351 list for use with the \fBexecv()\fR, \fBexecve()\fR, or \fBexecvp()\fR
352 functions (see \fBexec\fR(2)). Suppose, for example, that an application wants
353 to do the equivalent of:
354
355 .sp
356 .in +2
357 .nf
358 \fBls\fR \fB-l\fR *.c
359 .fi
360 .in -2
361
362 .sp
363 .LP
364 but for some reason:
365
366 .sp
367 .in +2
368 .nf
369 system("ls -l *.c")
370 .fi
371 .in -2
372
373 .sp
374 .LP
375 is not acceptable. The application could obtain approximately the same result
376 using the sequence:
377
378 .sp
379 .in +2
380 .nf
381 globbuf.gl_offs = 2;
382 glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
383 globbuf.gl_pathv[0] = "ls";
384 globbuf.gl_pathv[1] = "-l";
385 execvp ("ls", &globbuf.gl_pathv[0]);
386 .fi
387 .in -2
388
389 .sp
390 .LP
391 Using the same example:
392
393 .sp
394 .in +2
395 .nf
396 \fBls\fR \fB-l\fR *.c *.h
397 .fi
398 .in -2
399
400 .sp
401 .LP
402 could be approximately simulated using \fBGLOB_APPEND\fR as follows:
403
404 .sp
405 .in +2
406 .nf
407 \fBglobbuf.gl_offs = 2;
408 glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
409 glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);
410 \&.\|.\|.\fR
411 .fi
412 .in -2
413
414 .SH ATTRIBUTES
415 .sp
416 .LP
417 See \fBattributes\fR(5) for descriptions of the following attributes:
418 .sp
419
420 .sp
421 .TS
422 box;
423 c | c
424 l | l .
425 ATTRIBUTE TYPE ATTRIBUTE VALUE
426 _
427 Interface Stability Standard
428 _
429 MT-Level MT-Safe
430 .TE
431
432 .SH SEE ALSO
433 .sp
434 .LP
435 \fBexecv\fR(2), \fBstat\fR(2), \fBfnmatch\fR(3C), \fBopendir\fR(3C),
436 \fBreaddir\fR(3C), \fBwordexp\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)