OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [newlib-1.18.0/] [newlib/] [libc/] [posix/] [glob.3] - Blame information for rev 283

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 207 jeremybenn
.\" 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. All advertising materials mentioning features or use of this software
15
.\"    must display the following acknowledgement:
16
.\"     This product includes software developed by the University of
17
.\"     California, Berkeley and its contributors.
18
.\" 4. Neither the name of the University nor the names of its contributors
19
.\"    may be used to endorse or promote products derived from this software
20
.\"    without specific prior written permission.
21
.\"
22
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32
.\" SUCH DAMAGE.
33
.\"
34
.\"     @(#)glob.3      8.3 (Berkeley) 4/16/94
35
.\" $FreeBSD: src/lib/libc/gen/glob.3,v 1.20 2001/10/01 16:08:51 ru Exp $
36
.\"
37
.Dd April 16, 1994
38
.Dt GLOB 3
39
.Os
40
.Sh NAME
41
.Nm glob ,
42
.Nm globfree
43
.Nd generate pathnames matching a pattern
44
.Sh LIBRARY
45
.Lb libc
46
.Sh SYNOPSIS
47
.In glob.h
48
.Ft int
49
.Fn glob "const char *pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t *pglob"
50
.Ft void
51
.Fn globfree "glob_t *pglob"
52
.Sh DESCRIPTION
53
The
54
.Fn glob
55
function
56
is a pathname generator that implements the rules for file name pattern
57
matching used by the shell.
58
.Pp
59
The include file
60
.Pa glob.h
61
defines the structure type
62
.Fa glob_t ,
63
which contains at least the following fields:
64
.Bd -literal
65
typedef struct {
66
        int gl_pathc;           /* count of total paths so far */
67
        int gl_matchc;          /* count of paths matching pattern */
68
        int gl_offs;            /* reserved at beginning of gl_pathv */
69
        int gl_flags;           /* returned flags */
70
        char **gl_pathv;        /* list of paths matching pattern */
71
} glob_t;
72
.Ed
73
.Pp
74
The argument
75
.Fa pattern
76
is a pointer to a pathname pattern to be expanded.
77
The
78
.Fn glob
79
argument
80
matches all accessible pathnames against the pattern and creates
81
a list of the pathnames that match.
82
In order to have access to a pathname,
83
.Fn glob
84
requires search permission on every component of a path except the last
85
and read permission on each directory of any filename component of
86
.Fa pattern
87
that contains any of the special characters
88
.Ql * ,
89
.Ql ?\&
90
or
91
.Ql \&[ .
92
.Pp
93
The
94
.Fn glob
95
argument
96
stores the number of matched pathnames into the
97
.Fa gl_pathc
98
field, and a pointer to a list of pointers to pathnames into the
99
.Fa gl_pathv
100
field.
101
The first pointer after the last pathname is
102
.Dv NULL .
103
If the pattern does not match any pathnames, the returned number of
104
matched paths is set to zero.
105
.Pp
106
It is the caller's responsibility to create the structure pointed to by
107
.Fa pglob .
108
The
109
.Fn glob
110
function allocates other space as needed, including the memory pointed
111
to by
112
.Fa gl_pathv .
113
.Pp
114
The argument
115
.Fa flags
116
is used to modify the behavior of
117
.Fn glob .
118
The value of
119
.Fa flags
120
is the bitwise inclusive
121
.Tn OR
122
of any of the following
123
values defined in
124
.Pa glob.h :
125
.Bl -tag -width GLOB_ALTDIRFUNC
126
.It Dv GLOB_APPEND
127
Append pathnames generated to the ones from a previous call (or calls)
128
to
129
.Fn glob .
130
The value of
131
.Fa gl_pathc
132
will be the total matches found by this call and the previous call(s).
133
The pathnames are appended to, not merged with the pathnames returned by
134
the previous call(s).
135
Between calls, the caller must not change the setting of the
136
.Dv GLOB_DOOFFS
137
flag, nor change the value of
138
.Fa gl_offs
139
when
140
.Dv GLOB_DOOFFS
141
is set, nor (obviously) call
142
.Fn globfree
143
for
144
.Fa pglob .
145
.It Dv GLOB_DOOFFS
146
Make use of the
147
.Fa gl_offs
148
field.
149
If this flag is set,
150
.Fa gl_offs
151
is used to specify how many
152
.Dv NULL
153
pointers to prepend to the beginning
154
of the
155
.Fa gl_pathv
156
field.
157
In other words,
158
.Fa gl_pathv
159
will point to
160
.Fa gl_offs
161
.Dv NULL
162
pointers,
163
followed by
164
.Fa gl_pathc
165
pathname pointers, followed by a
166
.Dv NULL
167
pointer.
168
.It Dv GLOB_ERR
169
Causes
170
.Fn glob
171
to return when it encounters a directory that it cannot open or read.
172
Ordinarily,
173
.Fn glob
174
continues to find matches.
175
.It Dv GLOB_MARK
176
Each pathname that is a directory that matches
177
.Fa pattern
178
has a slash
179
appended.
180
.It Dv GLOB_NOCHECK
181
If
182
.Fa pattern
183
does not match any pathname, then
184
.Fn glob
185
returns a list
186
consisting of only
187
.Fa pattern ,
188
with the number of total pathnames is set to 1, and the number of matched
189
pathnames set to 0.
190
If
191
.Dv GLOB_QUOTE
192
is set, its effect is present in the pattern returned.
193
.It Dv GLOB_NOSORT
194
By default, the pathnames are sorted in ascending
195
.Tn ASCII
196
order;
197
this flag prevents that sorting (speeding up
198
.Fn glob ) .
199
.El
200
.Pp
201
The following values may also be included in
202
.Fa flags ,
203
however, they are non-standard extensions to
204
.St -p1003.2 .
205
.Bl -tag -width GLOB_ALTDIRFUNC
206
.It Dv GLOB_ALTDIRFUNC
207
The following additional fields in the pglob structure have been
208
initialized with alternate functions for glob to use to open, read,
209
and close directories and to get stat information on names found
210
in those directories.
211
.Bd -literal
212
void *(*gl_opendir)(const char * name);
213
struct dirent *(*gl_readdir)(void *);
214
void (*gl_closedir)(void *);
215
int (*gl_lstat)(const char *name, struct stat *st);
216
int (*gl_stat)(const char *name, struct stat *st);
217
.Ed
218
.Pp
219
This extension is provided to allow programs such as
220
.Xr restore 8
221
to provide globbing from directories stored on tape.
222
.It Dv GLOB_BRACE
223
Pre-process the pattern string to expand
224
.Ql {pat,pat,...}
225
strings like
226
.Xr csh 1 .
227
The pattern
228
.Ql {}
229
is left unexpanded for historical reasons (and
230
.Xr csh 1
231
does the same thing to
232
ease typing
233
of
234
.Xr find 1
235
patterns).
236
.It Dv GLOB_MAGCHAR
237
Set by the
238
.Fn glob
239
function if the pattern included globbing characters.
240
See the description of the usage of the
241
.Fa gl_matchc
242
structure member for more details.
243
.It Dv GLOB_NOMAGIC
244
Is the same as
245
.Dv GLOB_NOCHECK
246
but it only appends the
247
.Fa pattern
248
if it does not contain any of the special characters ``*'', ``?'' or ``[''.
249
.Dv GLOB_NOMAGIC
250
is provided to simplify implementing the historic
251
.Xr csh 1
252
globbing behavior and should probably not be used anywhere else.
253
.It Dv GLOB_QUOTE
254
Use the backslash
255
.Pq Ql \e
256
character for quoting: every occurrence of
257
a backslash followed by a character in the pattern is replaced by that
258
character, avoiding any special interpretation of the character.
259
.It Dv GLOB_TILDE
260
Expand patterns that start with
261
.Ql ~
262
to user name home directories.
263
.It Dv GLOB_LIMIT
264
Limit the total number of returned pathnames to the value provided in
265
.Fa gl_matchc
266
(default
267
.Dv ARG_MAX ) .
268
This option should be set for programs
269
that can be coerced into a denial of service attack
270
via patterns that expand to a very large number of matches,
271
such as a long string of
272
.Ql */../*/.. .
273
.El
274
.Pp
275
If, during the search, a directory is encountered that cannot be opened
276
or read and
277
.Fa errfunc
278
is
279
.Pf non- Dv NULL ,
280
.Fn glob
281
calls
282
.Fa \*(lp*errfunc\*(rp Ns ( Fa path , errno ) .
283
This may be unintuitive: a pattern like
284
.Ql */Makefile
285
will try to
286
.Xr stat 2
287
.Ql foo/Makefile
288
even if
289
.Ql foo
290
is not a directory, resulting in a
291
call to
292
.Fa errfunc .
293
The error routine can suppress this action by testing for
294
.Er ENOENT
295
and
296
.Er ENOTDIR ;
297
however, the
298
.Dv GLOB_ERR
299
flag will still cause an immediate
300
return when this happens.
301
.Pp
302
If
303
.Fa errfunc
304
returns non-zero,
305
.Fn glob
306
stops the scan and returns
307
.Dv GLOB_ABEND
308
after setting
309
.Fa gl_pathc
310
and
311
.Fa gl_pathv
312
to reflect any paths already matched.
313
This also happens if an error is encountered and
314
.Dv GLOB_ERR
315
is set in
316
.Fa flags ,
317
regardless of the return value of
318
.Fa errfunc ,
319
if called.
320
If
321
.Dv GLOB_ERR
322
is not set and either
323
.Fa errfunc
324
is
325
.Dv NULL
326
or
327
.Fa errfunc
328
returns zero, the error is ignored.
329
.Pp
330
The
331
.Fn globfree
332
function frees any space associated with
333
.Fa pglob
334
from a previous call(s) to
335
.Fn glob .
336
.Sh RETURN VALUES
337
On successful completion,
338
.Fn glob
339
returns zero.
340
In addition the fields of
341
.Fa pglob
342
contain the values described below:
343
.Bl -tag -width GLOB_NOCHECK
344
.It Fa gl_pathc
345
contains the total number of matched pathnames so far.
346
This includes other matches from previous invocations of
347
.Fn glob
348
if
349
.Dv GLOB_APPEND
350
was specified.
351
.It Fa gl_matchc
352
contains the number of matched pathnames in the current invocation of
353
.Fn glob .
354
.It Fa gl_flags
355
contains a copy of the
356
.Fa flags
357
parameter with the bit
358
.Dv GLOB_MAGCHAR
359
set if
360
.Fa pattern
361
contained any of the special characters ``*'', ``?'' or ``['', cleared
362
if not.
363
.It Fa gl_pathv
364
contains a pointer to a
365
.Dv NULL Ns -terminated
366
list of matched pathnames.
367
However, if
368
.Fa gl_pathc
369
is zero, the contents of
370
.Fa gl_pathv
371
are undefined.
372
.El
373
.Pp
374
If
375
.Fn glob
376
terminates due to an error, it sets errno and returns one of the
377
following non-zero constants, which are defined in the include
378
file
379
.Aq Pa glob.h :
380
.Bl -tag -width GLOB_NOCHECK
381
.It Dv GLOB_NOSPACE
382
An attempt to allocate memory failed, or if
383
.Fa errno
384
was 0
385
.Dv GLOB_LIMIT
386
was specified in the flags and
387
.Fa pglob\->gl_matchc
388
or more patterns were matched.
389
.It Dv GLOB_ABEND
390
The scan was stopped because an error was encountered and either
391
.Dv GLOB_ERR
392
was set or
393
.Fa \*(lp*errfunc\*(rp\*(lp\*(rp
394
returned non-zero.
395
.El
396
.Pp
397
The arguments
398
.Fa pglob\->gl_pathc
399
and
400
.Fa pglob\->gl_pathv
401
are still set as specified above.
402
.Sh EXAMPLES
403
A rough equivalent of
404
.Ql "ls -l *.c *.h"
405
can be obtained with the
406
following code:
407
.Bd -literal -offset indent
408
glob_t g;
409
 
410
g.gl_offs = 2;
411
glob("*.c", GLOB_DOOFFS, NULL, &g);
412
glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
413
g.gl_pathv[0] = "ls";
414
g.gl_pathv[1] = "-l";
415
execvp("ls", g.gl_pathv);
416
.Ed
417
.Sh SEE ALSO
418
.Xr sh 1 ,
419
.Xr fnmatch 3 ,
420
.Xr regexp 3
421
.Sh STANDARDS
422
The
423
.Fn glob
424
function is expected to be
425
.St -p1003.2
426
compatible with the exception
427
that the flags
428
.Dv GLOB_ALTDIRFUNC ,
429
.Dv GLOB_BRACE ,
430
.Dv GLOB_LIMIT ,
431
.Dv GLOB_MAGCHAR ,
432
.Dv GLOB_NOMAGIC ,
433
.Dv GLOB_QUOTE ,
434
and
435
.Dv GLOB_TILDE ,
436
and the fields
437
.Fa gl_matchc
438
and
439
.Fa gl_flags
440
should not be used by applications striving for strict
441
.Tn POSIX
442
conformance.
443
.Sh HISTORY
444
The
445
.Fn glob
446
and
447
.Fn globfree
448
functions first appeared in
449
.Bx 4.4 .
450
.Sh BUGS
451
Patterns longer than
452
.Dv MAXPATHLEN
453
may cause unchecked errors.
454
.Pp
455
The
456
.Fn glob
457
argument
458
may fail and set errno for any of the errors specified for the
459
library routines
460
.Xr stat 2 ,
461
.Xr closedir 3 ,
462
.Xr opendir 3 ,
463
.Xr readdir 3 ,
464
.Xr malloc 3 ,
465
and
466
.Xr free 3 .

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.