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