Print this page
1097 glob(3c) needs to support non-POSIX options
3341 The sftp command should use the native glob()
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/glob.3c
+++ new/usr/src/man/man3c/glob.3c
1 1 '\" te
2 -.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
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
3 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
4 6 .\" http://www.opengroup.org/bookstore/.
5 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 +.\"
6 40 .\" This notice shall appear on any product containing this material.
7 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.
8 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.
9 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]
10 44 .TH GLOB 3C "Nov 1, 2003"
11 45 .SH NAME
12 46 glob, globfree \- generate path names matching a pattern
13 47 .SH SYNOPSIS
14 48 .LP
15 49 .nf
16 50 #include <glob.h>
17 51
18 52 \fBint\fR \fBglob\fR(\fBconst char *restrict\fR \fIpattern\fR, \fBint\fR \fIflags\fR,
19 53 \fBint(*\fR\fIerrfunc\fR)(const char *\fIepath\fR, int \fIeerrno)\fR,
20 54 \fBglob_t *restrict\fR \fIpglob\fR);
21 55 .fi
22 56
23 57 .LP
24 58 .nf
25 59 \fBvoid\fR \fBglobfree\fR(\fBglob_t *\fR\fIpglob\fR);
26 60 .fi
27 61
28 62 .SH DESCRIPTION
29 63 .sp
30 64 .LP
31 65 The \fBglob()\fR function is a path name generator.
32 66 .sp
33 67 .LP
34 68 The \fBglobfree()\fR function frees any memory allocated by \fBglob()\fR
35 69 associated with \fIpglob\fR.
36 70 .SS "\fIpattern\fR Argument"
37 71 .sp
38 72 .LP
39 73 The argument \fIpattern\fR is a pointer to a path name pattern to be expanded.
40 74 The \fBglob()\fR function matches all accessible path names against this
41 75 pattern and develops a list of all path names that match. In order to have
42 76 access to a path name, \fBglob()\fR requires search permission on every
43 77 component of a path except the last, and read permission on each directory of
44 78 any filename component of \fIpattern\fR that contains any of the following
45 79 special characters:
46 80 .sp
47 81 .in +2
48 82 .nf
49 83 * ? [
50 84 .fi
|
↓ open down ↓ |
35 lines elided |
↑ open up ↑ |
51 85 .in -2
52 86
53 87 .SS "\fIpglob\fR Argument"
54 88 .sp
55 89 .LP
56 90 The structure type \fBglob_t\fR is defined in the header \fB<glob.h>\fR and
57 91 includes at least the following members:
58 92 .sp
59 93 .in +2
60 94 .nf
61 -size_t gl_pathc; /* count of paths matched by */
95 +size_t gl_pathc; /* Total count of paths matched by */
62 96 /* 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 */
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. */
67 101 .fi
68 102 .in -2
69 103
70 104 .sp
71 105 .LP
72 106 The \fBglob()\fR function stores the number of matched path names into
73 107 \fIpglob\(mi>\fR\fBgl_pathc\fR and a pointer to a list of pointers to path
74 108 names into \fIpglob\(mi>\fR\fBgl_pathv.\fR The path names are in sort order as
75 109 defined by the current setting of the \fBLC_COLLATE\fR category. The first
76 110 pointer after the last path name is a \fINULL\fR pointer. If the pattern does
77 111 not match any path names, the returned number of matched paths is set to 0, and
78 112 the contents of \fIpglob\(mi>\fR\fBgl_pathv\fR are implementation-dependent.
79 113 .sp
80 114 .LP
81 115 It is the caller's responsibility to create the structure pointed to by
82 116 \fIpglob\fR. The \fBglob()\fR function allocates other space as needed,
83 117 including the memory pointed to by \fBgl_pathv\fR. The \fBglobfree()\fR
84 118 function frees any space associated with \fIpglob\fR from a previous call to
85 119 \fBglob()\fR.
86 120 .SS "\fIflags\fR Argument"
87 121 .sp
88 122 .LP
89 123 The \fIflags\fR argument is used to control the behavior of \fBglob()\fR. The
90 124 value of \fIflags\fR is a bitwise inclusive \fBOR\fR of zero or more of the
91 125 following constants, which are defined in the header <\fBglob.h\fR>:
92 126 .sp
93 127 .ne 2
94 128 .na
95 129 \fB\fBGLOB_APPEND\fR\fR
96 130 .ad
97 131 .RS 17n
98 132 Append path names generated to the ones from a previous call to \fBglob()\fR.
99 133 .RE
100 134
101 135 .sp
102 136 .ne 2
103 137 .na
104 138 \fB\fBGLOB_DOOFFS\fR\fR
105 139 .ad
106 140 .RS 17n
107 141 Make use of \fIpglob\(mi>\fR\fBgl_offs\fR\fI\&.\fR If this flag is set,
108 142 \fIpglob\(mi>\fR\fBgl_offs\fR is used to specify how many \fINULL\fR pointers
109 143 to add to the beginning of \fIpglob\(mi>\fR\fBgl_pathv\fR\fI\&.\fR In other
110 144 words, \fIpglob\(mi>\fR\fBgl_pathv\fR will point to
111 145 \fIpglob\(mi>\fR\fBgl_offs\fR \fINULL\fR pointers, followed by
112 146 \fIpglob\(mi>\fR\fBgl_pathc\fR path name pointers, followed by a \fINULL\fR
113 147 pointer.
114 148 .RE
115 149
116 150 .sp
117 151 .ne 2
118 152 .na
119 153 \fB\fBGLOB_ERR\fR\fR
120 154 .ad
121 155 .RS 17n
122 156 Causes \fBglob()\fR to return when it encounters a directory that it cannot
123 157 open or read. Ordinarily, \fBglob()\fR continues to find matches.
124 158 .RE
125 159
126 160 .sp
127 161 .ne 2
128 162 .na
129 163 \fB\fBGLOB_MARK\fR\fR
130 164 .ad
131 165 .RS 17n
132 166 Each path name that is a directory that matches \fIpattern\fR has a slash
133 167 appended.
134 168 .RE
135 169
136 170 .sp
137 171 .ne 2
138 172 .na
139 173 \fB\fBGLOB_NOCHECK\fR\fR
140 174 .ad
141 175 .RS 17n
142 176 If \fIpattern\fR does not match any path name, then \fBglob()\fR returns a list
143 177 consisting of only \fIpattern\fR, and the number of matched path names is 1.
144 178 .RE
145 179
146 180 .sp
147 181 .ne 2
148 182 .na
149 183 \fB\fBGLOB_NOESCAPE\fR\fR
150 184 .ad
151 185 .RS 17n
152 186 Disable backslash escaping.
153 187 .RE
154 188
155 189 .sp
156 190 .ne 2
|
↓ open down ↓ |
80 lines elided |
↑ open up ↑ |
157 191 .na
158 192 \fB\fBGLOB_NOSORT\fR\fR
159 193 .ad
160 194 .RS 17n
161 195 Ordinarily, \fBglob()\fR sorts the matching path names according to the current
162 196 setting of the \fBLC_COLLATE\fR category. When this flag is used the order of
163 197 path names returned is unspecified.
164 198 .RE
165 199
166 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
167 311 .LP
168 312 The \fBGLOB_APPEND\fR flag can be used to append a new set of path names to
169 313 those found in a previous call to \fBglob()\fR. The following rules apply when
170 314 two or more calls to \fBglob()\fR are made with the same value of \fIpglob\fR
171 315 and without intervening calls to \fBglobfree()\fR:
172 316 .RS +4
173 317 .TP
174 318 1.
175 319 The first such call must not set \fBGLOB_APPEND.\fR All subsequent calls
176 320 must set it.
177 321 .RE
178 322 .RS +4
179 323 .TP
180 324 2.
181 325 All the calls must set \fBGLOB_DOOFFS,\fR or all must not set it.
182 326 .RE
183 327 .RS +4
184 328 .TP
185 329 3.
186 330 After the second call, \fIpglob\(mi>\fR\fBgl_pathv\fR points to a list
187 331 containing the following:
188 332 .RS +4
189 333 .TP
190 334 a.
191 335 Zero or more \fINULL\fR pointers, as specified by \fBGLOB_DOOFFS\fR and
192 336 \fIpglob\(mi>\fR\fBgl_offs\fR.
193 337 .RE
194 338 .RS +4
195 339 .TP
196 340 b.
197 341 Pointers to the path names that were in the \fIpglob\(mi>\fR\fBgl_pathv\fR
198 342 list before the call, in the same order as before.
199 343 .RE
200 344 .RS +4
201 345 .TP
202 346 c.
203 347 Pointers to the new path names generated by the second call, in the
204 348 specified order.
205 349 .RE
206 350 .RE
207 351 .RS +4
208 352 .TP
209 353 4.
210 354 The count returned in \fIpglob\(mi>\fR\fBgl_pathc\fR will be the total
211 355 number of path names from the two calls.
212 356 .RE
213 357 .RS +4
214 358 .TP
215 359 5.
216 360 The application can change any of the fields after a call to \fBglob()\fR.
217 361 If it does, it must reset them to the original value before a subsequent call,
218 362 using the same \fIpglob\fR value, to \fBglobfree()\fR or \fBglob()\fR with the
219 363 \fBGLOB_APPEND\fR flag.
220 364 .RE
221 365 .SS "\fIerrfunc\fR and \fIepath\fR Arguments"
222 366 .sp
223 367 .LP
224 368 If, during the search, a directory is encountered that cannot be opened or read
225 369 and \fIerrfunc\fR is not a \fINULL\fR pointer, \fBglob()\fR calls
226 370 \fB(\fR\fI*errfunc\fR\fB)\fR with two arguments:
227 371 .RS +4
228 372 .TP
229 373 1.
|
↓ open down ↓ |
53 lines elided |
↑ open up ↑ |
230 374 The \fIepath\fR argument is a pointer to the path that failed.
231 375 .RE
232 376 .RS +4
233 377 .TP
234 378 2.
235 379 The \fIeerrno\fR argument is the value of \fIerrno\fR from the failure, as
236 380 set by the \fBopendir\fR(3C), \fBreaddir\fR(3C) or \fBstat\fR(2) functions.
237 381 (Other values may be used to report other errors not explicitly documented for
238 382 those functions.)
239 383 .RE
384 +
240 385 .sp
241 386 .LP
242 -The following constants are defined as error return values for \fBglob()\fR:
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
243 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
244 400 .ne 2
245 401 .na
246 -\fB\fBGLOB_ABORTED\fR\fR
402 +\fB\fBgl_pathc\fR\fR
247 403 .ad
248 404 .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.
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.
251 408 .RE
252 409
253 410 .sp
254 411 .ne 2
255 412 .na
256 -\fB\fBGLOB_NOMATCH\fR\fR
413 +\fB\fBgl_matchc\fR\fR
257 414 .ad
258 415 .RS 16n
259 -The pattern does not match any existing path name, and \fBGLOB_NOCHECK\fR was
260 -not set in flags.
416 +Contains the number of matched pathnames in the current
417 +invocation of \fBglob()\fR.
261 418 .RE
262 419
263 420 .sp
264 421 .ne 2
265 422 .na
266 -\fB\fBGLOG_NOSPACE\fR\fR
423 +\fB\fBgl_flags\fR\fR
267 424 .ad
268 425 .RS 16n
269 -An attempt to allocate memory failed.
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.
270 429 .RE
271 430
272 431 .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
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 +
281 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
282 454 .LP
283 -The following values are returned by \fBglob()\fR:
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 +
284 458 .sp
285 459 .ne 2
286 460 .na
287 -\fB\fB0\fR\fR
461 +\fB\fBGLOB_ABORTED\fR\fR
288 462 .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.
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.
295 466 .RE
296 467
297 468 .sp
298 469 .ne 2
299 470 .na
300 -\fB\fBnon-zero\fR\fR
471 +\fB\fBGLOB_NOMATCH\fR\fR
301 472 .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.
473 +.RS 16n
474 +The pattern does not match any existing path name, and \fBGLOB_NOCHECK\fR was
475 +not set in flags.
306 476 .RE
307 477
308 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 +
309 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
310 502 The \fBglobfree()\fR function returns no value.
311 503 .SH USAGE
312 504 .sp
313 505 .LP
314 506 This function is not provided for the purpose of enabling utilities to perform
315 507 path name expansion on their arguments, as this operation is performed by the
316 508 shell, and utilities are explicitly not expected to redo this. Instead, it is
317 509 provided for applications that need to do path name expansion on strings
318 510 obtained from other sources, such as a pattern typed by a user or read from a
319 511 file.
320 512 .sp
321 513 .LP
322 514 If a utility needs to see if a path name matches a given pattern, it can use
323 515 \fBfnmatch\fR(3C).
324 516 .sp
325 517 .LP
326 518 Note that \fBgl_pathc\fR and \fBgl_pathv\fR have meaning even if \fBglob()\fR
327 519 fails. This allows \fBglob()\fR to report partial results in the event of an
328 520 error. However, if \fBgl_pathc\fR is 0, \fBgl_pathv\fR is unspecified even if
329 521 \fBglob()\fR did not return an error.
330 522 .sp
331 523 .LP
332 524 The \fBGLOB_NOCHECK\fR option could be used when an application wants to expand
333 525 a path name if wildcards are specified, but wants to treat the pattern as just
334 526 a string otherwise.
335 527 .sp
336 528 .LP
337 529 The new path names generated by a subsequent call with \fBGLOB_APPEND\fR are
338 530 not sorted together with the previous path names. This mirrors the way that the
339 531 shell handles path name expansion when multiple expansions are done on a
340 532 command line.
341 533 .sp
342 534 .LP
343 535 Applications that need tilde and parameter expansion should use the
344 536 \fBwordexp\fR(3C) function.
345 537 .SH EXAMPLES
346 538 .LP
347 539 \fBExample 1 \fRExample of \fBglob_doofs\fR function.
348 540 .sp
349 541 .LP
350 542 One use of the \fBGLOB_DOOFFS\fR flag is by applications that build an argument
351 543 list for use with the \fBexecv()\fR, \fBexecve()\fR, or \fBexecvp()\fR
352 544 functions (see \fBexec\fR(2)). Suppose, for example, that an application wants
353 545 to do the equivalent of:
354 546
355 547 .sp
356 548 .in +2
357 549 .nf
358 550 \fBls\fR \fB-l\fR *.c
359 551 .fi
360 552 .in -2
361 553
362 554 .sp
363 555 .LP
364 556 but for some reason:
365 557
366 558 .sp
367 559 .in +2
368 560 .nf
369 561 system("ls -l *.c")
370 562 .fi
371 563 .in -2
372 564
373 565 .sp
374 566 .LP
375 567 is not acceptable. The application could obtain approximately the same result
376 568 using the sequence:
377 569
378 570 .sp
379 571 .in +2
380 572 .nf
381 573 globbuf.gl_offs = 2;
382 574 glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
383 575 globbuf.gl_pathv[0] = "ls";
384 576 globbuf.gl_pathv[1] = "-l";
385 577 execvp ("ls", &globbuf.gl_pathv[0]);
386 578 .fi
387 579 .in -2
388 580
389 581 .sp
390 582 .LP
391 583 Using the same example:
392 584
393 585 .sp
394 586 .in +2
395 587 .nf
396 588 \fBls\fR \fB-l\fR *.c *.h
397 589 .fi
398 590 .in -2
399 591
400 592 .sp
401 593 .LP
402 594 could be approximately simulated using \fBGLOB_APPEND\fR as follows:
403 595
404 596 .sp
405 597 .in +2
406 598 .nf
407 599 \fBglobbuf.gl_offs = 2;
408 600 glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
409 601 glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);
410 602 \&.\|.\|.\fR
411 603 .fi
412 604 .in -2
413 605
414 606 .SH ATTRIBUTES
415 607 .sp
416 608 .LP
417 609 See \fBattributes\fR(5) for descriptions of the following attributes:
418 610 .sp
419 611
420 612 .sp
421 613 .TS
422 614 box;
423 615 c | c
424 616 l | l .
425 617 ATTRIBUTE TYPE ATTRIBUTE VALUE
426 618 _
427 619 Interface Stability Standard
428 620 _
429 621 MT-Level MT-Safe
430 622 .TE
431 623
432 624 .SH SEE ALSO
433 625 .sp
434 626 .LP
435 627 \fBexecv\fR(2), \fBstat\fR(2), \fBfnmatch\fR(3C), \fBopendir\fR(3C),
436 628 \fBreaddir\fR(3C), \fBwordexp\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
|
↓ open down ↓ |
117 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX