Annotation of src/lib/libc/gen/glob.3, Revision 1.40.2.2
1.40.2.2! yamt 1: .\" $NetBSD: glob.3,v 1.40.2.1 2012/10/30 18:58:47 yamt 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.
1.28 agc 16: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 17: .\" may be used to endorse or promote products derived from this software
18: .\" without specific prior written permission.
19: .\"
20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30: .\" SUCH DAMAGE.
31: .\"
1.9 cgd 32: .\" @(#)glob.3 8.3 (Berkeley) 4/16/94
1.1 cgd 33: .\"
1.40.2.2! yamt 34: .Dd December 27, 2012
1.1 cgd 35: .Dt GLOB 3
36: .Os
37: .Sh NAME
38: .Nm glob ,
1.34 wiz 39: .Nm globfree ,
40: .Nm glob_pattern_p
1.1 cgd 41: .Nd generate pathnames matching a pattern
1.12 perry 42: .Sh LIBRARY
43: .Lb libc
1.1 cgd 44: .Sh SYNOPSIS
1.25 wiz 45: .In glob.h
1.1 cgd 46: .Ft int
1.40 wiz 47: .Fn glob "const char * restrict pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t * restrict pglob"
1.14 fair 48: .Ft void
1.1 cgd 49: .Fn globfree "glob_t *pglob"
1.33 christos 50: .Ft int
51: .Fn glob_pattern_p "const char *pattern" "int quote"
1.1 cgd 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 {
1.30 christos 66: size_t gl_pathc; /* count of total paths so far */
67: size_t gl_matchc; /* count of paths matching pattern */
68: size_t gl_offs; /* reserved at beginning of gl_pathv */
1.1 cgd 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 * ,
1.27 wiz 89: .Ql \&?
1.1 cgd 90: or
1.27 wiz 91: .Ql \&[ .
1.1 cgd 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
1.14 fair 102: .Dv NULL .
1.1 cgd 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 :
1.4 cgd 125: .Bl -tag -width GLOB_ALTDIRFUNC
1.1 cgd 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 ,
1.40.2.2! yamt 188: with one level of backslash escapes removed,
! 189: the number of total pathnames set to 1, and the number of matched
1.1 cgd 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.40.2.1 yamt 234: .It Dv GLOB_LIMIT
235: Limit the amount of memory used to store matched strings to
236: .Li 64K ,
237: the number of
238: .Xr stat 2
239: calls to 128, and the number of
240: .Xr readdir 3
241: calls to 16K.
242: This option should be set for programs that can be coerced to a denial of
243: service attack via patterns that expand to a very large number of matches,
244: such as a long string of
245: .Li */../*/..
1.4 cgd 246: .It Dv GLOB_MAGCHAR
247: Set by the
248: .Fn glob
249: function if the pattern included globbing characters.
1.14 fair 250: See the description of the usage of the
1.4 cgd 251: .Fa gl_matchc
252: structure member for more details.
1.40.2.1 yamt 253: .It Dv GLOB_NOESCAPE
254: Disable the use of the backslash
255: .Pq Ql \e
256: character for quoting.
1.1 cgd 257: .It Dv GLOB_NOMAGIC
1.14 fair 258: Is the same as
259: .Dv GLOB_NOCHECK
1.1 cgd 260: but it only appends the
261: .Fa pattern
262: if it does not contain any of the special characters ``*'', ``?'' or ``[''.
1.14 fair 263: .Dv GLOB_NOMAGIC
1.1 cgd 264: is provided to simplify implementing the historic
265: .Xr csh 1
266: globbing behavior and should probably not be used anywhere else.
1.32 christos 267: .It Dv GLOB_NO_DOTDIRS
268: Hide
269: .Sq Li \&.
270: and
271: .Sq Li \&..
272: from metacharacter matches, regardless of whether
273: .Dv GLOB_PERIOD
274: is set and whether the pattern component begins with a literal period.
1.40.2.1 yamt 275: .It Dv GLOB_PERIOD
276: Allow metacharacters to match a leading period in a filename.
277: .It Dv GLOB_STAR
1.38 christos 278: Indicates that two adjacent
279: .Li *
280: characters will do a recursive match in all subdirs, without following
281: symbolic links and three adjacent
282: .Li *
283: characters will also follow symbolic links.
1.40.2.1 yamt 284: .It Dv GLOB_TILDE
285: Expand patterns that start with
286: .Ql ~
287: to user name home directories.
1.1 cgd 288: .El
289: .Pp
290: If, during the search, a directory is encountered that cannot be opened
291: or read and
292: .Fa errfunc
293: is
1.14 fair 294: .Pf non- Dv NULL ,
1.1 cgd 295: .Fn glob
296: calls
1.4 cgd 297: .Fa (*errfunc)(path, errno) .
1.1 cgd 298: This may be unintuitive: a pattern like
299: .Ql */Makefile
300: will try to
301: .Xr stat 2
302: .Ql foo/Makefile
303: even if
304: .Ql foo
305: is not a directory, resulting in a
306: call to
307: .Fa errfunc .
308: The error routine can suppress this action by testing for
309: .Dv ENOENT
310: and
1.14 fair 311: .Dv ENOTDIR ;
1.1 cgd 312: however, the
313: .Dv GLOB_ERR
314: flag will still cause an immediate
315: return when this happens.
316: .Pp
317: If
318: .Fa errfunc
319: returns non-zero,
320: .Fn glob
321: stops the scan and returns
1.13 kleink 322: .Dv GLOB_ABORTED
1.1 cgd 323: after setting
324: .Fa gl_pathc
325: and
326: .Fa gl_pathv
327: to reflect any paths already matched.
328: This also happens if an error is encountered and
329: .Dv GLOB_ERR
330: is set in
331: .Fa flags ,
332: regardless of the return value of
333: .Fa errfunc ,
334: if called.
335: If
336: .Dv GLOB_ERR
337: is not set and either
338: .Fa errfunc
339: is
340: .Dv NULL
341: or
342: .Fa errfunc
343: returns zero, the error is ignored.
344: .Pp
345: The
346: .Fn globfree
347: function frees any space associated with
348: .Fa pglob
349: from a previous call(s) to
350: .Fn glob .
1.15 kleink 351: .Pp
1.33 christos 352: The
353: .Fn glob_pattern_p
354: returns
355: .Dv 1
356: if the
357: .Fa pattern
358: has any special characters that
359: .Fn glob
360: will interpret and
361: .Dv 0
362: otherwise.
363: If the
364: .Fa quote
365: argument is non-zero, then backslash quoted characters are ignored.
366: .Pp
1.15 kleink 367: The historical
368: .Dv GLOB_QUOTE
369: flag is no longer supported.
370: Per
371: .St -p1003.2-92 ,
372: backslash escaping of special characters is the default behaviour;
373: it may be disabled by specifying the
374: .Dv GLOB_NOESCAPE
375: flag.
1.1 cgd 376: .Sh RETURN VALUES
377: On successful completion,
378: .Fn glob
379: returns zero.
380: In addition the fields of
381: .Fa pglob
382: contain the values described below:
383: .Bl -tag -width GLOB_NOCHECK
384: .It Fa gl_pathc
385: contains the total number of matched pathnames so far.
1.14 fair 386: This includes other matches from previous invocations of
1.1 cgd 387: .Fn glob
1.14 fair 388: if
1.1 cgd 389: .Dv GLOB_APPEND
390: was specified.
391: .It Fa gl_matchc
392: contains the number of matched pathnames in the current invocation of
393: .Fn glob .
394: .It Fa gl_flags
1.14 fair 395: contains a copy of the
1.1 cgd 396: .Fa flags
397: parameter with the bit
398: .Dv GLOB_MAGCHAR
399: set if
400: .Fa pattern
401: contained any of the special characters ``*'', ``?'' or ``['', cleared
402: if not.
403: .It Fa gl_pathv
404: contains a pointer to a
1.14 fair 405: .Dv NULL Ns -terminated
1.1 cgd 406: list of matched pathnames.
407: However, if
408: .Fa gl_pathc
409: is zero, the contents of
410: .Fa gl_pathv
411: are undefined.
412: .El
413: .Pp
414: If
415: .Fn glob
1.14 fair 416: terminates due to an error, it sets
417: .Va errno
418: and returns one of the following non-zero constants, which are defined
1.6 jtc 419: in the include file
1.36 joerg 420: .In glob.h :
1.15 kleink 421: .Bl -tag -width GLOB_ABORTEDXXX
1.13 kleink 422: .It Dv GLOB_ABORTED
1.1 cgd 423: The scan was stopped because an error was encountered and either
424: .Dv GLOB_ERR
425: was set or
426: .Fa (*errfunc)()
427: returned non-zero.
1.15 kleink 428: .It Dv GLOB_NOMATCH
429: The pattern does not match any existing pathname, and
430: .Dv GLOB_NOCHECK
1.29 grant 431: was not set in
1.15 kleink 432: .Dv flags .
433: .It Dv GLOB_NOSPACE
1.16 christos 434: An attempt to allocate memory failed, or if
1.18 wiz 435: .Va errno
1.16 christos 436: was 0
437: .Li GLOB_LIMIT
438: was specified in the flags and
439: .Li ARG_MAX
440: patterns were matched.
1.1 cgd 441: .El
1.13 kleink 442: .Pp
443: The historical
444: .Dv GLOB_ABEND
1.24 wiz 445: return constant is no longer supported.
446: Portable applications should use the
1.13 kleink 447: .Dv GLOB_ABORTED
448: constant instead.
1.1 cgd 449: .Pp
450: The arguments
1.22 ross 451: .Fa pglob\-\*[Gt]gl_pathc
1.1 cgd 452: and
1.22 ross 453: .Fa pglob\-\*[Gt]gl_pathv
1.1 cgd 454: are still set as specified above.
1.11 lukem 455: .Sh ENVIRONMENT
456: .Bl -tag -width HOME -compact
457: .It Ev HOME
458: If defined, used as the home directory of the current user in
459: tilde expansions.
460: .El
1.19 wiz 461: .Sh EXAMPLES
1.9 cgd 462: A rough equivalent of
463: .Ql "ls -l *.c *.h"
464: can be obtained with the
465: following code:
466: .Bd -literal -offset indent
467: glob_t g;
468:
469: g.gl_offs = 2;
1.23 ross 470: glob("*.c", GLOB_DOOFFS, NULL, \*[Am]g);
471: glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, \*[Am]g);
1.9 cgd 472: g.gl_pathv[0] = "ls";
473: g.gl_pathv[1] = "-l";
474: execvp("ls", g.gl_pathv);
475: .Ed
1.1 cgd 476: .Sh SEE ALSO
477: .Xr sh 1 ,
478: .Xr fnmatch 3 ,
1.39 jruoho 479: .Xr regexp 3 ,
480: .Xr glob 7
1.1 cgd 481: .Sh STANDARDS
482: The
483: .Fn glob
484: function is expected to be
485: .St -p1003.2
486: compatible with the exception
1.2 mycroft 487: that the flags
1.19 wiz 488: .Dv GLOB_ALTDIRFUNC ,
489: .Dv GLOB_BRACE ,
1.40.2.1 yamt 490: .Dv GLOB_LIMIT ,
1.19 wiz 491: .Dv GLOB_MAGCHAR ,
1.40.2.1 yamt 492: .Dv GLOB_NOESCAPE ,
1.19 wiz 493: .Dv GLOB_NOMAGIC ,
1.40.2.1 yamt 494: .Dv GLOB_NO_DOTDIRS ,
495: .Dv GLOB_PERIOD ,
496: .Dv GLOB_STAR ,
1.19 wiz 497: .Dv GLOB_TILDE ,
1.14 fair 498: and the fields
1.1 cgd 499: .Fa gl_matchc
1.14 fair 500: and
1.1 cgd 501: .Fa gl_flags
502: should not be used by applications striving for strict
503: .Tn POSIX
504: conformance.
505: .Sh HISTORY
506: The
507: .Fn glob
508: and
509: .Fn globfree
1.14 fair 510: functions first appeared in
1.5 jtc 511: .Bx 4.4 .
1.35 joerg 512: The
1.33 christos 513: .Fn glob_pattern_p
514: function is modelled after the one found in glibc.
1.1 cgd 515: .Sh BUGS
516: Patterns longer than
517: .Dv MAXPATHLEN
518: may cause unchecked errors.
519: .Pp
520: The
521: .Fn glob
1.14 fair 522: function may fail and set
523: .Va errno
1.6 jtc 524: for any of the errors specified for the library routines
1.1 cgd 525: .Xr stat 2 ,
526: .Xr closedir 3 ,
527: .Xr opendir 3 ,
528: .Xr readdir 3 ,
529: .Xr malloc 3 ,
530: and
531: .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