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