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