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);
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"
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
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.
|
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);
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"
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
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.
|