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