1 '\" te
2 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
3 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
4 .\" Portions Copyright (c) 2012, Gary Mills
5 .\" 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
6 .\" http://www.opengroup.org/bookstore/.
7 .\" 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.
8 .\"
9 .\" $OpenBSD: glob.3,v 1.30 2012/01/20 07:09:42 tedu Exp $
10 .\"
11 .\" Copyright (c) 1989, 1991, 1993, 1994
12 .\" The Regents of the University of California. All rights reserved.
13 .\"
14 .\" This code is derived from software contributed to Berkeley by
15 .\" Guido van Rossum.
16 .\" Redistribution and use in source and binary forms, with or without
17 .\" modification, are permitted provided that the following conditions
18 .\" are met:
19 .\" 1. Redistributions of source code must retain the above copyright
20 .\" notice, this list of conditions and the following disclaimer.
21 .\" 2. Redistributions in binary form must reproduce the above copyright
22 .\" notice, this list of conditions and the following disclaimer in the
23 .\" documentation and/or other materials provided with the distribution.
24 .\" 3. Neither the name of the University nor the names of its contributors
25 .\" may be used to endorse or promote products derived from this software
26 .\" without specific prior written permission.
27 .\"
28 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
29 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
30 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
31 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
32 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
33 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
34 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
35 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
36 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
37 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
38 .\" SUCH DAMAGE.
39 .\"
40 .\" This notice shall appear on any product containing this material.
41 .\" 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.
42 .\" 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.
43 .\" 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]
44 .TH GLOB 3C "Nov 1, 2003"
45 .SH NAME
46 glob, globfree \- generate path names matching a pattern
47 .SH SYNOPSIS
48 .LP
49 .nf
50 #include <glob.h>
51
52 \fBint\fR \fBglob\fR(\fBconst char *restrict\fR \fIpattern\fR, \fBint\fR \fIflags\fR,
53 \fBint(*\fR\fIerrfunc\fR)(const char *\fIepath\fR, int \fIeerrno)\fR,
54 \fBglob_t *restrict\fR \fIpglob\fR);
55 .fi
56
57 .LP
58 .nf
59 \fBvoid\fR \fBglobfree\fR(\fBglob_t *\fR\fIpglob\fR);
60 .fi
61
62 .SH DESCRIPTION
63 .sp
64 .LP
65 The \fBglob()\fR function is a path name generator.
66 .sp
67 .LP
68 The \fBglobfree()\fR function frees any memory allocated by \fBglob()\fR
69 associated with \fIpglob\fR.
70 .SS "\fIpattern\fR Argument"
71 .sp
72 .LP
73 The argument \fIpattern\fR is a pointer to a path name pattern to be expanded.
74 The \fBglob()\fR function matches all accessible path names against this
75 pattern and develops a list of all path names that match. In order to have
76 access to a path name, \fBglob()\fR requires search permission on every
77 component of a path except the last, and read permission on each directory of
78 any filename component of \fIpattern\fR that contains any of the following
79 special characters:
80 .sp
81 .in +2
82 .nf
83 * ? [
84 .fi
85 .in -2
86
87 .SS "\fIpglob\fR Argument"
88 .sp
89 .LP
90 The structure type \fBglob_t\fR is defined in the header \fB<glob.h>\fR and
91 includes at least the following members:
92 .sp
93 .in +2
94 .nf
95 size_t gl_pathc; /* Total count of paths matched by */
96 /* pattern */
97 char **gl_pathv; /* List of matched path names */
98 size_t gl_offs; /* # of slots reserved in gl_pathv */
99 int gl_matchc; /* Count of paths matching pattern. */
100 int gl_flags; /* Copy of flags parameter to glob. */
101 .fi
102 .in -2
103
104 .sp
105 .LP
106 The \fBglob()\fR function stores the number of matched path names into
107 \fIpglob\(mi>\fR\fBgl_pathc\fR and a pointer to a list of pointers to path
108 names into \fIpglob\(mi>\fR\fBgl_pathv.\fR The path names are in sort order as
109 defined by the current setting of the \fBLC_COLLATE\fR category. The first
110 pointer after the last path name is a \fINULL\fR pointer. If the pattern does
111 not match any path names, the returned number of matched paths is set to 0, and
112 the contents of \fIpglob\(mi>\fR\fBgl_pathv\fR are implementation-dependent.
113 .sp
114 .LP
115 It is the caller's responsibility to create the structure pointed to by
116 \fIpglob\fR. The \fBglob()\fR function allocates other space as needed,
117 including the memory pointed to by \fBgl_pathv\fR. The \fBglobfree()\fR
118 function frees any space associated with \fIpglob\fR from a previous call to
119 \fBglob()\fR.
120 .SS "\fIflags\fR Argument"
121 .sp
122 .LP
123 The \fIflags\fR argument is used to control the behavior of \fBglob()\fR. The
124 value of \fIflags\fR is a bitwise inclusive \fBOR\fR of zero or more of the
125 following constants, which are defined in the header <\fBglob.h\fR>:
126 .sp
127 .ne 2
128 .na
129 \fB\fBGLOB_APPEND\fR\fR
130 .ad
131 .RS 17n
132 Append path names generated to the ones from a previous call to \fBglob()\fR.
133 .RE
134
135 .sp
136 .ne 2
137 .na
138 \fB\fBGLOB_DOOFFS\fR\fR
139 .ad
140 .RS 17n
141 Make use of \fIpglob\(mi>\fR\fBgl_offs\fR\fI\&.\fR If this flag is set,
142 \fIpglob\(mi>\fR\fBgl_offs\fR is used to specify how many \fINULL\fR pointers
143 to add to the beginning of \fIpglob\(mi>\fR\fBgl_pathv\fR\fI\&.\fR In other
144 words, \fIpglob\(mi>\fR\fBgl_pathv\fR will point to
145 \fIpglob\(mi>\fR\fBgl_offs\fR \fINULL\fR pointers, followed by
146 \fIpglob\(mi>\fR\fBgl_pathc\fR path name pointers, followed by a \fINULL\fR
147 pointer.
148 .RE
149
150 .sp
151 .ne 2
152 .na
153 \fB\fBGLOB_ERR\fR\fR
154 .ad
155 .RS 17n
156 Causes \fBglob()\fR to return when it encounters a directory that it cannot
157 open or read. Ordinarily, \fBglob()\fR continues to find matches.
158 .RE
159
160 .sp
161 .ne 2
162 .na
163 \fB\fBGLOB_MARK\fR\fR
164 .ad
165 .RS 17n
166 Each path name that is a directory that matches \fIpattern\fR has a slash
167 appended.
168 .RE
169
170 .sp
171 .ne 2
172 .na
173 \fB\fBGLOB_NOCHECK\fR\fR
174 .ad
175 .RS 17n
176 If \fIpattern\fR does not match any path name, then \fBglob()\fR returns a list
177 consisting of only \fIpattern\fR, and the number of matched path names is 1.
178 .RE
179
180 .sp
181 .ne 2
182 .na
183 \fB\fBGLOB_NOESCAPE\fR\fR
184 .ad
185 .RS 17n
186 Disable backslash escaping.
187 .RE
188
189 .sp
190 .ne 2
191 .na
192 \fB\fBGLOB_NOSORT\fR\fR
193 .ad
194 .RS 17n
195 Ordinarily, \fBglob()\fR sorts the matching path names according to the current
196 setting of the \fBLC_COLLATE\fR category. When this flag is used the order of
197 path names returned is unspecified.
198 .RE
199
200 .sp
201 .ne 2
202 .na
203 \fB\fBGLOB_ALTDIRFUNC\fR\fR
204 .ad
205 .RS 17n
206 The following additional fields in the \fIpglob\fR structure
207 have been initialized with alternate functions for
208 \fBglob()\fR to use to open, read, and close directories and
209 to get stat information on names found in those directories:
210 .sp
211 .nf
212 void *(*gl_opendir)(const char *);
213 struct dirent *(*gl_readdir)(void *);
214 void (*gl_closedir)(void *);
215 int (*gl_lstat)(const char *, struct stat *);
216 int (*gl_stat)(const char *, struct stat *);
217 .fi
218 .sp
219 This extension is provided to allow programs such as
220 \fBufsrestore\fR(1M) to provide globbing from directories stored
221 on tape.
222 .RE
223
224 .sp
225 .ne 2
226 .na
227 \fB\fBGLOB_BRACE\fR\fR
228 .ad
229 .RS 17n
230 Pre-process the pattern string to expand `{pat,pat,...}'
231 strings like \fBcsh\fR(1). The pattern `{}' is left unexpanded
232 for historical reasons. (\fBcsh\fR(1) does the same thing
233 to ease typing of \fBfind\fR(1) patterns.)
234 .RE
235
236 .sp
237 .ne 2
238 .na
239 \fB\fBGLOB_MAGCHAR\fR\fR
240 .ad
241 .RS 17n
242 Set by the \fBglob()\fR function if the pattern included globbing
243 characters. See the description of the usage of
244 the \fBgl_matchc\fR structure member for more details.
245 .RE
246
247 .sp
248 .ne 2
249 .na
250 \fB\fBGLOB_NOMAGIC\fR\fR
251 .ad
252 .RS 17n
253 Is the same as \fBGLOB_NOCHECK\fR but it only appends the
254 pattern if it does not contain any of the special characters
255 `*', `?', or `['. \fBGLOB_NOMAGIC\fR is provided to
256 simplify implementing the historic \fBcsh\fR(1) globbing behavior
257 and should probably not be used anywhere else.
258 .RE
259
260 .sp
261 .ne 2
262 .na
263 \fB\fBGLOB_QUOTE\fR\fR
264 .ad
265 .RS 17n
266 This option has no effect and is included for backwards
267 compatibility with older sources.
268 .RE
269
270 .sp
271 .ne 2
272 .na
273 \fB\fBGLOB_TILDE\fR\fR
274 .ad
275 .RS 17n
276 Expand patterns that start with `~' to user name home
277 directories.
278 .RE
279
280 .sp
281 .ne 2
282 .na
283 \fB\fBGLOB_LIMIT\fR\fR
284 .ad
285 .RS 17n
286 Limit the amount of memory used by matches to \fIARG_MAX\fR.
287 This option should be set for programs that can be coerced
288 to a denial of service attack via patterns that
289 expand to a very large number of matches, such as a long
290 string of `*/../*/..'.
291 .RE
292
293 .sp
294 .ne 2
295 .na
296 \fB\fBGLOB_KEEPSTAT\fR\fR
297 .ad
298 .RS 17n
299 Retain a copy of the \fBstat\fR(2) information retrieved for
300 matching paths in the gl_statv array:
301 .sp
302 .nf
303 struct stat **gl_statv;
304 .fi
305 .sp
306 This option may be used to avoid \fBlstat\fR(2) lookups in
307 cases where they are expensive.
308 .RE
309
310 .sp
311 .LP
312 The \fBGLOB_APPEND\fR flag can be used to append a new set of path names to
313 those found in a previous call to \fBglob()\fR. The following rules apply when
314 two or more calls to \fBglob()\fR are made with the same value of \fIpglob\fR
315 and without intervening calls to \fBglobfree()\fR:
316 .RS +4
317 .TP
318 1.
319 The first such call must not set \fBGLOB_APPEND.\fR All subsequent calls
320 must set it.
321 .RE
322 .RS +4
323 .TP
324 2.
325 All the calls must set \fBGLOB_DOOFFS,\fR or all must not set it.
326 .RE
327 .RS +4
328 .TP
329 3.
330 After the second call, \fIpglob\(mi>\fR\fBgl_pathv\fR points to a list
331 containing the following:
332 .RS +4
333 .TP
334 a.
335 Zero or more \fINULL\fR pointers, as specified by \fBGLOB_DOOFFS\fR and
336 \fIpglob\(mi>\fR\fBgl_offs\fR.
337 .RE
338 .RS +4
339 .TP
340 b.
341 Pointers to the path names that were in the \fIpglob\(mi>\fR\fBgl_pathv\fR
342 list before the call, in the same order as before.
343 .RE
344 .RS +4
345 .TP
346 c.
347 Pointers to the new path names generated by the second call, in the
348 specified order.
349 .RE
350 .RE
351 .RS +4
352 .TP
353 4.
354 The count returned in \fIpglob\(mi>\fR\fBgl_pathc\fR will be the total
355 number of path names from the two calls.
356 .RE
357 .RS +4
358 .TP
359 5.
360 The application can change any of the fields after a call to \fBglob()\fR.
361 If it does, it must reset them to the original value before a subsequent call,
362 using the same \fIpglob\fR value, to \fBglobfree()\fR or \fBglob()\fR with the
363 \fBGLOB_APPEND\fR flag.
364 .RE
365 .SS "\fIerrfunc\fR and \fIepath\fR Arguments"
366 .sp
367 .LP
368 If, during the search, a directory is encountered that cannot be opened or read
369 and \fIerrfunc\fR is not a \fINULL\fR pointer, \fBglob()\fR calls
370 \fB(\fR\fI*errfunc\fR\fB)\fR with two arguments:
371 .RS +4
372 .TP
373 1.
374 The \fIepath\fR argument is a pointer to the path that failed.
375 .RE
376 .RS +4
377 .TP
378 2.
379 The \fIeerrno\fR argument is the value of \fIerrno\fR from the failure, as
380 set by the \fBopendir\fR(3C), \fBreaddir\fR(3C) or \fBstat\fR(2) functions.
381 (Other values may be used to report other errors not explicitly documented for
382 those functions.)
383 .RE
384
385 .sp
386 .LP
387 If \fB(\fR\fI*errfunc\fR\fB)\fR is called and returns non-zero, or if the
388 \fBGLOB_ERR\fR flag is set in \fIflags\fR, \fBglob()\fR stops the scan and
389 returns \fBGLOB_ABORTED\fR after setting \fIgl_pathc\fR and \fIgl_pathv\fR in
390 \fIpglob\fR to reflect the paths already scanned. If \fBGLOB_ERR\fR is not set
391 and either \fIerrfunc\fR is a \fINULL\fR pointer or
392 \fB(\fR\fI*errfunc\fR\fB)\fR returns 0, the error is ignored.
393 .SH RETURN VALUES
394 .sp
395 .LP
396 On successful completion, \fBglob()\fR returns zero.
397 In addition the fields of pglob contain the values described below:
398
399 .sp
400 .ne 2
401 .na
402 \fB\fBgl_pathc\fR\fR
403 .ad
404 .RS 16n
405 Contains the total number of matched pathnames so far.
406 This includes other matches from previous invocations of
407 \fBglob()\fR if \fBGLOB_APPEND\fR was specified.
408 .RE
409
410 .sp
411 .ne 2
412 .na
413 \fB\fBgl_matchc\fR\fR
414 .ad
415 .RS 16n
416 Contains the number of matched pathnames in the current
417 invocation of \fBglob()\fR.
418 .RE
419
420 .sp
421 .ne 2
422 .na
423 \fB\fBgl_flags\fR\fR
424 .ad
425 .RS 16n
426 Contains a copy of the flags parameter with the bit
427 \fBGLOB_MAGCHAR\fR set if pattern contained any of the special
428 characters `*', `?', or `[', cleared if not.
429 .RE
430
431 .sp
432 .ne 2
433 .na
434 \fB\fBgl_pathv\fR\fR
435 .ad
436 .RS 16n
437 Contains a pointer to a null-terminated list of matched
438 pathnames. However, if \fBgl_pathc\fR is zero, the contents of
439 \fBgl_pathv\fR are undefined.
440 .RE
441
442 .sp
443 .ne 2
444 .na
445 \fB\fBgl_statv\fR\fR
446 .ad
447 .RS 16n
448 If the \fBGLOB_KEEPSTAT\fR flag was set, \fBgl_statv\fR contains a
449 pointer to a null-terminated list of matched \fBstat\fR(2)
450 objects corresponding to the paths in \fBgl_pathc\fR.
451 .RE
452
453 .sp
454 .LP
455 If \fBglob()\fR terminates due to an error, it sets \fBerrno\fR and
456 returns one of the following non-zero constants. defined in <\fBglob.h\fR>:
457
458 .sp
459 .ne 2
460 .na
461 \fB\fBGLOB_ABORTED\fR\fR
462 .ad
463 .RS 16n
464 The scan was stopped because \fBGLOB_ERR\fR was set or
465 \fB(\fR\fI*errfunc\fR\fB)\fR returned non-zero.
466 .RE
467
468 .sp
469 .ne 2
470 .na
471 \fB\fBGLOB_NOMATCH\fR\fR
472 .ad
473 .RS 16n
474 The pattern does not match any existing path name, and \fBGLOB_NOCHECK\fR was
475 not set in flags.
476 .RE
477
478 .sp
479 .ne 2
480 .na
481 \fB\fBGLOB_NOSPACE\fR\fR
482 .ad
483 .RS 16n
484 An attempt to allocate memory failed.
485 .RE
486
487 .sp
488 .ne 2
489 .na
490 \fB\fBGLOB_NOSYS\fR\fR
491 .ad
492 .RS 16n
493 The requested function is not supported by this version of
494 \fBglob()\fR.
495 .RE
496
497 .LP
498 The arguments \fIpglob\(mi>\fR\fBgl_pathc\fR and \fIpglob\(mi>\fR\fBgl_pathv\fR are still set as
499 specified above.
500 .sp
501 .LP
502 The \fBglobfree()\fR function returns no value.
503 .SH USAGE
504 .sp
505 .LP
506 This function is not provided for the purpose of enabling utilities to perform
507 path name expansion on their arguments, as this operation is performed by the
508 shell, and utilities are explicitly not expected to redo this. Instead, it is
509 provided for applications that need to do path name expansion on strings
510 obtained from other sources, such as a pattern typed by a user or read from a
511 file.
512 .sp
513 .LP
514 If a utility needs to see if a path name matches a given pattern, it can use
515 \fBfnmatch\fR(3C).
516 .sp
517 .LP
518 Note that \fBgl_pathc\fR and \fBgl_pathv\fR have meaning even if \fBglob()\fR
519 fails. This allows \fBglob()\fR to report partial results in the event of an
520 error. However, if \fBgl_pathc\fR is 0, \fBgl_pathv\fR is unspecified even if
521 \fBglob()\fR did not return an error.
522 .sp
523 .LP
524 The \fBGLOB_NOCHECK\fR option could be used when an application wants to expand
525 a path name if wildcards are specified, but wants to treat the pattern as just
526 a string otherwise.
527 .sp
528 .LP
529 The new path names generated by a subsequent call with \fBGLOB_APPEND\fR are
530 not sorted together with the previous path names. This mirrors the way that the
531 shell handles path name expansion when multiple expansions are done on a
532 command line.
533 .sp
534 .LP
535 Applications that need tilde and parameter expansion should use the
536 \fBwordexp\fR(3C) function.
537 .SH EXAMPLES
538 .LP
539 \fBExample 1 \fRExample of \fBglob_doofs\fR function.
540 .sp
541 .LP
542 One use of the \fBGLOB_DOOFFS\fR flag is by applications that build an argument
543 list for use with the \fBexecv()\fR, \fBexecve()\fR, or \fBexecvp()\fR
544 functions (see \fBexec\fR(2)). Suppose, for example, that an application wants
545 to do the equivalent of:
546
547 .sp
548 .in +2
549 .nf
550 \fBls\fR \fB-l\fR *.c
551 .fi
552 .in -2
553
554 .sp
555 .LP
556 but for some reason:
557
558 .sp
559 .in +2
560 .nf
561 system("ls -l *.c")
562 .fi
563 .in -2
564
565 .sp
566 .LP
567 is not acceptable. The application could obtain approximately the same result
568 using the sequence:
569
570 .sp
571 .in +2
572 .nf
573 globbuf.gl_offs = 2;
574 glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
575 globbuf.gl_pathv[0] = "ls";
576 globbuf.gl_pathv[1] = "-l";
577 execvp ("ls", &globbuf.gl_pathv[0]);
578 .fi
579 .in -2
580
581 .sp
582 .LP
583 Using the same example:
584
585 .sp
586 .in +2
587 .nf
588 \fBls\fR \fB-l\fR *.c *.h
589 .fi
590 .in -2
591
592 .sp
593 .LP
594 could be approximately simulated using \fBGLOB_APPEND\fR as follows:
595
596 .sp
597 .in +2
598 .nf
599 \fBglobbuf.gl_offs = 2;
600 glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
601 glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);
602 \&.\|.\|.\fR
603 .fi
604 .in -2
605
606 .SH ATTRIBUTES
607 .sp
608 .LP
609 See \fBattributes\fR(5) for descriptions of the following attributes:
610 .sp
611
612 .sp
613 .TS
614 box;
615 c | c
616 l | l .
617 ATTRIBUTE TYPE ATTRIBUTE VALUE
618 _
619 Interface Stability Standard
620 _
621 MT-Level MT-Safe
622 .TE
623
624 .SH SEE ALSO
625 .sp
626 .LP
627 \fBexecv\fR(2), \fBstat\fR(2), \fBfnmatch\fR(3C), \fBopendir\fR(3C),
628 \fBreaddir\fR(3C), \fBwordexp\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)