/contrib/tcsh/glob.3

  1.\"	$NetBSD: glob.3,v 1.17 2001/03/16 21:09:05 christos Exp $
  2.\"
  3.\" Copyright (c) 1989, 1991, 1993, 1994
  4.\"	The Regents of the University of California.  All rights reserved.
  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.
 16.\" 3. Neither the name of the University nor the names of its contributors
 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.\"
 32.\"     @(#)glob.3	8.3 (Berkeley) 4/16/94
 33.\"
 34.Dd March 31, 1998
 35.Dt GLOB 3
 36.Os
 37.Sh NAME
 38.Nm glob ,
 39.Nm globfree
 40.Nd generate pathnames matching a pattern
 41.Sh LIBRARY
 42.Lb libc
 43.Sh SYNOPSIS
 44.Fd #include <glob.h>
 45.Ft int
 46.Fn glob "const char *pattern" "int flags" "const 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.
187.It Dv GLOB_NOSORT
188By default, the pathnames are sorted in ascending
189.Tn ASCII
190order;
191this flag prevents that sorting (speeding up
192.Fn glob ) .
193.El
194.Pp
195The following values may also be included in
196.Fa flags ,
197however, they are non-standard extensions to
198.St -p1003.2 .
199.Bl -tag -width GLOB_ALTDIRFUNC
200.It Dv GLOB_ALTDIRFUNC
201The following additional fields in the pglob structure have been
202initialized with alternate functions for glob to use to open, read,
203and close directories and to get stat information on names found
204in those directories.
205.Bd -literal
206	void *(*gl_opendir)(const char * name);
207	struct dirent *(*gl_readdir)(void *);
208	void (*gl_closedir)(void *);
209	int (*gl_lstat)(const char *name, struct stat *st);
210	int (*gl_stat)(const char *name, struct stat *st);
211.Ed
212.Pp
213This extension is provided to allow programs such as
214.Xr restore 8
215to provide globbing from directories stored on tape.
216.It Dv GLOB_BRACE
217Pre-process the pattern string to expand
218.Ql {pat,pat,...}
219strings like
220.Xr csh 1 .
221The pattern
222.Ql {}
223is left unexpanded for historical reasons
224.Po
225.Xr csh 1
226does the same thing to ease typing of
227.Xr find 1
228patterns
229.Pc .
230.It Dv GLOB_MAGCHAR
231Set by the
232.Fn glob
233function if the pattern included globbing characters.
234See the description of the usage of the
235.Fa gl_matchc
236structure member for more details.
237.It Dv GLOB_NOMAGIC
238Is the same as
239.Dv GLOB_NOCHECK
240but it only appends the
241.Fa pattern
242if it does not contain any of the special characters ``*'', ``?'' or ``[''.
243.Dv GLOB_NOMAGIC
244is provided to simplify implementing the historic
245.Xr csh 1
246globbing behavior and should probably not be used anywhere else.
247.It Dv GLOB_NOESCAPE
248Disable the use of the backslash
249.Pq Ql \e
250character for quoting.
251.It Dv GLOB_TILDE
252Expand patterns that start with
253.Ql ~
254to user name home directories.
255.It Dv GLOB_LIMIT
256Limit the amount of memory used by matches to
257.Li ARG_MAX
258This option should be set for programs that can be coerced to a denial of
259service attack via patterns that expand to a very large number of matches,
260such as a long string of 
261.Li */../*/..
262.El
263.Pp
264If, during the search, a directory is encountered that cannot be opened
265or read and
266.Fa errfunc
267is
268.Pf non- Dv NULL ,
269.Fn glob
270calls
271.Fa (*errfunc)(path, errno) .
272This may be unintuitive: a pattern like
273.Ql */Makefile
274will try to
275.Xr stat 2
276.Ql foo/Makefile
277even if
278.Ql foo
279is not a directory, resulting in a
280call to
281.Fa errfunc .
282The error routine can suppress this action by testing for
283.Dv ENOENT
284and
285.Dv ENOTDIR ;
286however, the
287.Dv GLOB_ERR
288flag will still cause an immediate
289return when this happens.
290.Pp
291If
292.Fa errfunc
293returns non-zero,
294.Fn glob
295stops the scan and returns
296.Dv GLOB_ABORTED
297after setting
298.Fa gl_pathc
299and
300.Fa gl_pathv
301to reflect any paths already matched.
302This also happens if an error is encountered and
303.Dv GLOB_ERR
304is set in
305.Fa flags ,
306regardless of the return value of
307.Fa errfunc ,
308if called.
309If
310.Dv GLOB_ERR
311is not set and either
312.Fa errfunc
313is
314.Dv NULL
315or
316.Fa errfunc
317returns zero, the error is ignored.
318.Pp
319The
320.Fn globfree
321function frees any space associated with
322.Fa pglob
323from a previous call(s) to
324.Fn glob .
325.Pp
326The historical
327.Dv GLOB_QUOTE
328flag is no longer supported.
329Per
330.St -p1003.2-92 ,
331backslash escaping of special characters is the default behaviour;
332it may be disabled by specifying the
333.Dv GLOB_NOESCAPE
334flag.
335.Sh RETURN VALUES
336On successful completion,
337.Fn glob
338returns zero.
339In addition the fields of
340.Fa pglob
341contain the values described below:
342.Bl -tag -width GLOB_NOCHECK
343.It Fa gl_pathc
344contains the total number of matched pathnames so far.
345This includes other matches from previous invocations of
346.Fn glob
347if
348.Dv GLOB_APPEND
349was specified.
350.It Fa gl_matchc
351contains the number of matched pathnames in the current invocation of
352.Fn glob .
353.It Fa gl_flags
354contains a copy of the
355.Fa flags
356parameter with the bit
357.Dv GLOB_MAGCHAR
358set if
359.Fa pattern
360contained any of the special characters ``*'', ``?'' or ``['', cleared
361if not.
362.It Fa gl_pathv
363contains a pointer to a
364.Dv NULL Ns -terminated
365list of matched pathnames.
366However, if
367.Fa gl_pathc
368is zero, the contents of
369.Fa gl_pathv
370are undefined.
371.El
372.Pp
373If
374.Fn glob
375terminates due to an error, it sets
376.Va errno
377and returns one of the following non-zero constants, which are defined
378in the include file
379.Aq Pa glob.h :
380.Bl -tag -width GLOB_ABORTEDXXX
381.It Dv GLOB_ABORTED
382The scan was stopped because an error was encountered and either
383.Dv GLOB_ERR
384was set or
385.Fa (*errfunc)()
386returned non-zero.
387.It Dv GLOB_NOMATCH
388The pattern does not match any existing pathname, and
389.Dv GLOB_NOCHECK
390was not set int
391.Dv flags .
392.It Dv GLOB_NOSPACE
393An attempt to allocate memory failed, or if
394.Va errno 
395was 0
396.Li GLOB_LIMIT
397was specified in the flags and
398.Li ARG_MAX
399patterns were matched.
400.El
401.Pp
402The historical
403.Dv GLOB_ABEND
404return constant is no longer supported.  Portable applications should use the
405.Dv GLOB_ABORTED
406constant instead.
407.Pp
408The arguments
409.Fa pglob\->gl_pathc
410and
411.Fa pglob\->gl_pathv
412are still set as specified above.
413.Sh ENVIRONMENT
414.Bl -tag -width HOME -compact
415.It Ev HOME
416If defined, used as the home directory of the current user in
417tilde expansions.
418.El
419.Sh EXAMPLE
420A rough equivalent of
421.Ql "ls -l *.c *.h"
422can be obtained with the
423following code:
424.Bd -literal -offset indent
425glob_t g;
426
427g.gl_offs = 2;
428glob("*.c", GLOB_DOOFFS, NULL, &g);
429glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
430g.gl_pathv[0] = "ls";
431g.gl_pathv[1] = "-l";
432execvp("ls", g.gl_pathv);
433.Ed
434.Sh SEE ALSO
435.Xr sh 1 ,
436.Xr fnmatch 3 ,
437.Xr regexp 3
438.Sh STANDARDS
439The
440.Fn glob
441function is expected to be
442.St -p1003.2
443compatible with the exception
444that the flags
445.Dv GLOB_ALTDIRFUNC,
446.Dv GLOB_BRACE
447.Dv GLOB_MAGCHAR,
448.Dv GLOB_NOMAGIC,
449.Dv GLOB_TILDE,
450and
451.Dv GLOB_LIMIT
452and the fields
453.Fa gl_matchc
454and
455.Fa gl_flags
456should not be used by applications striving for strict
457.Tn POSIX
458conformance.
459.Sh HISTORY
460The
461.Fn glob
462and
463.Fn globfree
464functions first appeared in
465.Bx 4.4 .
466.Sh BUGS
467Patterns longer than
468.Dv MAXPATHLEN
469may cause unchecked errors.
470.Pp
471The
472.Fn glob
473function may fail and set
474.Va errno
475for any of the errors specified for the library routines
476.Xr stat 2 ,
477.Xr closedir 3 ,
478.Xr opendir 3 ,
479.Xr readdir 3 ,
480.Xr malloc 3 ,
481and
482.Xr free 3 .