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