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