4.3BSD-Reno/share/man/cat3/glob.0
GLOB(3) 1990 GLOB(3)
NNAAMMEE
glob, globfree - generate pathnames matching a pattern
SSYYNNOOPPSSIISS
#include <glob.h>
glob(const char *pattern, int flags,
const int (*errfunc)(char *, int), glob_t *pglob);
void globfree(glob_t *pglob);
DDEESSCCRRIIPPTTIIOONN
_G_l_o_b is a pathname generator that implements the rules for
file name pattern matching used by the shell.
The include file _g_l_o_b._h defines the structure type _g_l_o_b__t,
which contains at least the following fields:
typedef struct {
int gl_pathc; /* count of paths matching pattern */
int gl_offs; /* reserved at beginning of gl_pathv */
char **gl_pathv; /* list of paths matching pattern */
} glob_t;
The argument _p_a_t_t_e_r_n is a pointer to a pathname pattern to
be expanded. _G_l_o_b matches all accessible pathnames against
the pattern and creates a list of the pathnames that match.
In order to have access to a pathname, _g_l_o_b requires search
permission on every component of a path except the last and
read permission on each directory of any filename component
of _p_a_t_t_e_r_n that contains any of the special characters
``*'', ``?'' or ``[''.
_G_l_o_b stores the number of matched pathnames into the
_g_l__p_a_t_h_c field, and a pointer to a list of pointers to path-
names into the _g_l__p_a_t_h_v 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.
It is the caller's responsibility to create the structure
pointed to by _p_g_l_o_b. The _g_l_o_b function allocates other
space as needed, including the memory pointed to by
_g_l__p_a_t_h_v.
The argument _f_l_a_g_s is used to modify the behavior of _g_l_o_b.
The value of _f_l_a_g_s is the bitwise inclusive OR of any of the
following values defined in _g_l_o_b._h:
GLOB_APPEND
Append pathnames generated to the ones from a previous
call (or calls) to _g_l_o_b. The value of _g_l__p_a_t_h_c will be
Printed 7/27/90 June 1
GLOB(3) 1990 GLOB(3)
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
_g_l__o_f_f_s when GLOB_DOOFFS is set, nor (obviously) call
_g_l_o_b_f_r_e_e for _p_g_l_o_b.
GLOB_DOOFFS
Make use of the _g_l__o_f_f_s field. If this flag is set,
_g_l__o_f_f_s is used to specify how many NULL pointers to
prepend to the beginning of the _g_l__p_a_t_h_v field. In
other words, _g_l__p_a_t_h_v will point to _g_l__o_f_f_s NULL
pointers, followed by _g_l__p_a_t_h_c pathname pointers, fol-
lowed by a NULL pointer.
GLOB_ERR
Causes _g_l_o_b to return when it encounters a directory
that it cannot open or read. Ordinarily, _g_l_o_b contin-
ues to find matches.
GLOB_MARK
Each pathname that is a directory that matches _p_a_t_t_e_r_n
has a slash appended.
GLOB_NOSORT
By default, the pathnames are sorted in ascending ASCII
order; this flag prevents that sorting (speeding up
_g_l_o_b).
GLOB_NOCHECK
If _p_a_t_t_e_r_n does not match any pathname, then _g_l_o_b
returns a list consisting of only _p_a_t_t_e_r_n, and the
number of matched pathnames is set to 1. If _G_L_O_B__Q_U_O_T_E
is set, its effect is present in the pattern returned.
GLOB_QUOTE
Use the backslash (``\'') 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.
If, during the search, a directory is encountered that can-
not be opened or read and _e_r_r_f_u_n_c is non-NULL, _g_l_o_b calls
(*_e_r_r_f_u_n_c)(_p_a_t_h, _e_r_r_n_o). This may be unintuitive: a pattern
like ``*/Makefile'' will try to _s_t_a_t(2) ``foo/Makefile''
even if ``foo'' is not a directory, resulting in a call to
_e_r_r_f_u_n_c. 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.
Printed 7/27/90 June 2
GLOB(3) 1990 GLOB(3)
If _e_r_r_f_u_n_c returns non-zero, _g_l_o_b stops the scan and returns
_G_L_O_B__A_B_E_N_D after setting _g_l__p_a_t_h_c and _g_l__p_a_t_h_v to reflect
any paths already matched. This also happens if an error is
encountered and _G_L_O_B__E_R_R is set in _f_l_a_g_s, regardless of the
return value of _e_r_r_f_u_n_c, if called. If _G_L_O_B__E_R_R is not set
and either _e_r_r_f_u_n_c is NULL or _e_r_r_f_u_n_c returns zero, the
error is ignored.
The _g_l_o_b_f_r_e_e function frees any space associated with _p_g_l_o_b
from a previous call(s) to _g_l_o_b.
RREETTUURRNNSS
On successful completion, _g_l_o_b returns zero. The field
_g_l__p_a_t_h_c returns the number of matched pathnames and the
field _g_l__p_a_t_h_v contains a pointer to a NULL-terminated list
of matched pathnames. However, if _p_g_l_o_b->_g_l__p_a_t_h_c is zero,
the contents of _p_g_l_o_b->_g_l__p_a_t_h_v is undefined.
If _g_l_o_b 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>:
GLOB_NOSPACE
An attempt to allocate memory failed.
GLOB_ABEND
The scan was stopped because an error was encountered
and either GLOB_ERR was set or (*_e_r_r_f_u_n_c)() returned
non-zero.
The arguments _p_g_l_o_b->_g_l__p_a_t_h_c and _p_g_l_o_b->_g_l__p_a_t_h_v are still
set as specified above.
SSTTAANNDDAARRDDSS
The _g_l_o_b function is expected to be POSIX 1003.2 compatible
with the exception that the flag GLOB_QUOTE should not be
used by applications striving for strict POSIX conformance.
EEXXAAMMPPLLEE
A rough equivalent of ``ls -l *.c *.h'' can be obtained with
the following code:
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);
Printed 7/27/90 June 3
GLOB(3) 1990 GLOB(3)
SSEEEE AALLSSOO
sh(1), fnmatch(3), wordexp(3), regexp(3)
BBUUGGSS
Patterns longer than MAXPATHLEN may cause unchecked errors.
_G_l_o_b may fail and set errno for any of the errors specified
for the library routines _s_t_a_t (_2), _c_l_o_s_e_d_i_r (_3), _o_p_e_n_d_i_r
(_3), _r_e_a_d_d_i_r (_3), _m_a_l_l_o_c (_3), and _f_r_e_e (_3).
Printed 7/27/90 June 4