freebsd/contrib/tcsh/glob.3

.\" Copyright (c) 1989 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Guido van Rossum.
.\"
.\" Redistribution and use in source and binary forms are permitted provided
.\" that: (1) source distributions retain this entire copyright notice and
.\" comment, and (2) distributions including binaries display the following
.\" acknowledgement:  ``This product includes software developed by the
.\" University of California, Berkeley and its contributors'' in the
.\" documentation or other materials provided with the distribution and in
.\" all advertising materials mentioning features or use of this software.
.\" Neither the name of the University nor the names of its contributors may
.\" be used to endorse or promote products derived from this software without
.\" specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\"	@(#)glob.3	5.3 (Berkeley) 3/19/91
.\"
.TH GLOB 3 "March 19, 1991"
.UC 7
.SH NAME
glob, globfree \- generate pathnames matching a pattern
.SH SYNOPSIS
.nf
#include <glob.h>

glob(const char *pattern, int flags,
	const int (*errfunc)(char *, int), glob_t *pglob);

void globfree(glob_t *pglob);
.fi
.SH DESCRIPTION
.I Glob
is a pathname generator that implements the rules for file name pattern
matching used by the shell.
.PP
The include file
.I glob.h
defines the structure type
.IR glob_t ,
which contains at least the following fields:
.sp
.RS
.nf
.ta .5i +\w'char **gl_pathv;\0\0\0'u
typedef struct {
	int gl_pathc;		/* count of total paths so far */
	int gl_matchc;		/* count of paths matching pattern */
	int gl_offs;		/* reserved at beginning of gl_pathv */
	int gl_flags;		/* returned flags */
	char **gl_pathv;	/* list of paths matching pattern */
} glob_t;
.fi
.RE
.PP
The argument
.I pattern
is a pointer to a pathname pattern to be expanded.
.I Glob
matches all accessible pathnames against the pattern and creates
a list of the pathnames that match.
In order to have access to a pathname,
.I glob
requires search permission on every component of a path except the last
and read permission on each directory of any filename component of
.I pattern
that contains any of the special characters ``*'', ``?'' or ``[''.
.PP
.I Glob
stores the number of matched pathnames into the
.I gl_pathc
field, and a pointer to a list of pointers to pathnames into the
.I gl_pathv
field.
The first pointer after the last pathname is NULL.
If the pattern does not match any pathnames, the returned number of
matched paths is set to zero.
.PP
It is the caller's responsibility to create the structure pointed to by
.IR pglob .
The
.I glob
function allocates other space as needed, including the memory pointed
to by
.IR gl_pathv .
.PP
The argument
.I flags
is used to modify the behavior of
.IR glob .
The value of
.I flags
is the bitwise inclusive OR of any of the following
values defined in
.IR glob.h :
.TP
GLOB_APPEND
Append pathnames generated to the ones from a previous call (or calls)
to
.IR glob .
The value of
.I gl_pathc
will be the total matches found by this call and the previous call(s).
The pathnames are appended to, not merged with the pathnames returned by
the previous call(s).
Between calls, the caller must not change the setting of the
GLOB_DOOFFS flag, nor change the value of
.I gl_offs
when
GLOB_DOOFFS is set, nor (obviously) call
.I globfree
for
.I pglob.
.TP
GLOB_DOOFFS
Make use of the
.I gl_offs
field.
If this flag is set,
.I gl_offs
is used to specify how many NULL pointers to prepend to the beginning
of the
.I gl_pathv
field.
In other words,
.I gl_pathv
will point to
.I gl_offs
NULL pointers,
followed by
.I gl_pathc
pathname pointers, followed by a NULL pointer.
.TP
GLOB_ERR
Causes
.I glob
to return when it encounters a directory that it cannot open or read.
Ordinarily,
.I glob
continues to find matches.
.TP
GLOB_MARK
Each pathname that is a directory that matches
.I pattern
has a slash
appended.
.TP
GLOB_NOSORT
By default, the pathnames are sorted in ascending ASCII order;
this flag prevents that sorting (speeding up
.IR glob ).
.TP
GLOB_NOCHECK
If
.I pattern
does not match any pathname, then
.I glob
returns a list
consisting of only
.IR pattern ,
with the number of total pathnames is set to 1, and the number of matched
pathnames set to 0.
If
.I GLOB_QUOTE
is set, its effect is present in the pattern returned.
.TP
GLOB_QUOTE
Use the backslash (``\e'') character for quoting: every occurrence of
a backslash followed by a character in the pattern is replaced by that
character, avoiding any special interpretation of the character.
.TP
GLOB_NOMAGIC
Is the same as GLOB_NOCHECK but it only appends the
.IR pattern
if it does not contain any of the special characters ``*'', ``?'' or ``[''.
GLOB_NOMAGIC is used to simplify implementing the globbing behavior in
.IR csh(1).
.PP
If, during the search, a directory is encountered that cannot be opened
or read and
.I errfunc
is non-NULL,
.I glob
calls (*\fIerrfunc\fP)(\fIpath\fP, \fIerrno\fP).
This may be unintuitive: a pattern like ``*/Makefile'' will try to
.IR stat (2)
``foo/Makefile'' even if ``foo'' is not a directory, resulting in a
call to
.IR errfunc .
The error routine can suppress this action by testing for ENOENT and
ENOTDIR; however, the GLOB_ERR flag will still cause an immediate
return when this happens.
.PP
If
.I errfunc
returns non-zero,
.I glob
stops the scan and returns
.I GLOB_ABEND
after setting
.I gl_pathc
and
.I gl_pathv
to reflect any paths already matched.
This also happens if an error is encountered and
.I GLOB_ERR
is set in
.IR flags ,
regardless of the return value of
.IR errfunc ,
if called.
If
.I GLOB_ERR
is not set and either
.I errfunc
is NULL or
.I errfunc
returns zero, the error is ignored.
.PP
The
.I globfree
function frees any space associated with
.I pglob
from a previous call(s) to
.IR glob .
.SH RETURNS
On successful completion,
.I glob
returns zero.
In addition the fields of
.I pglob
contain the values described below:
.TP
.I gl_pathc
contains the total number of matched pathnames so far.
This includes other matches from previous invocations of 
.I glob 
if 
.I GLOB_APPEND 
was specified.
.TP
.I gl_matchc
contains the number of matched pathnames in the current invocation of
.I glob.
.TP
.I gl_flags
contains a copy of the 
.I flags 
parameter with the bit GLOB_MAGCHAR set if
.I pattern
contained any of the special characters ``*'', ``?'' or ``['', cleared
if not.
.TP
.I gl_pathv
contains a pointer to a NULL-terminated list of matched pathnames.
However, if
.I gl_pathc
is zero, the contents of
.I gl_pathv
are undefined.
.PP
If
.I glob
terminates due to an error, it sets errno and returns one of the
following non-zero constants, which are defined in the include
file <glob.h>:
.TP
GLOB_NOSPACE
An attempt to allocate memory failed.
.TP
GLOB_ABEND
The scan was stopped because an error was encountered and either
GLOB_ERR was set or (*\fIerrfunc\fR)() returned non-zero.
.PP
The arguments
.I pglob->gl_pathc
and
.I pglob->gl_pathv
are still set as specified above.
.SH STANDARDS
The
.I glob
function is expected to be POSIX 1003.2 compatible with the exception
that the flag 
.I GLOB_QUOTE 
and the fields 
.I gl_matchc 
and 
.I gl_flags 
should not be used by applications striving for strict POSIX conformance.
.SH EXAMPLE
A rough equivalent of ``ls -l *.c *.h'' can be obtained with the
following code:
.sp
.nf
.RS
glob_t g;

g.gl_offs = 2;
glob("*.c", GLOB_DOOFFS, NULL, &g);
glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
g.gl_pathv[0] = "ls";
g.gl_pathv[1] = "-l";
execvp("ls", g.gl_pathv);
.RE
.fi
.SH SEE ALSO
sh(1), fnmatch(3), wordexp(3), regexp(3)
.SH BUGS
Patterns longer than MAXPATHLEN may cause unchecked errors.
.PP
.I Glob
may fail and set errno for any of the errors specified for the
library routines
.I stat (2),
.I closedir (3),
.I opendir (3),
.I readdir (3),
.I malloc (3),
and
.I free (3).