NAME
glob, globfree - find pathnames matching a pattern, free memory from glob()
SYNOPSIS
#include <glob.h>
I int glob(const char * pattern , int flags ,
I int (* errfunc ) (const char * epath , int eerrno ),
I glob_t * pglob );
I void globfree(glob_t * pglob );
DESCRIPTION
The
R glob ()
function searches for all the pathnames matching
pattern
according to the rules used by the shell (see
glob(7)).
No tilde expansion or parameter substitution is done; if you want
these, use
wordexp(3).
The
R globfree ()
function frees the dynamically allocated storage from an earlier call
to
R glob ().
The results of a
R glob ()
call are stored in the structure pointed to by
R pglob ,
which is a
glob_t
which is declared in
<glob.h>
and includes the following elements defined by POSIX.2 (more may be
present as an extension):
typedef struct {
size_t gl_pathc; /* Count of paths matched so far */
char **gl_pathv; /* List of matched pathnames. */
size_t gl_offs; /* Slots to reserve in `gl_pathv'. */
} glob_t;
Results are stored in dynamically allocated storage.
The parameter
flags
is made up of bitwise OR of zero or more the following symbolic
constants, which modify the of behavior of
R glob ():
GLOB_ERR
which means to return upon read error (because a directory does not
have read permission, for example),
GLOB_MARK
which means to append a slash to each path which corresponds to a directory,
GLOB_NOSORT
which means don't sort the returned pathnames (they are by default),
GLOB_DOOFFS
which means that
pglob->gl_offs
slots will be reserved at the beginning of the list of strings in
R pglob->pathv ,
GLOB_NOCHECK
which means that, if no pattern matches, to return the original pattern,
GLOB_APPEND
which means to append to the results of a previous call.
Do not set this flag on the first invocation of
R glob ().
GLOB_NOESCAPE
which means that meta characters cannot be quoted by backslashes.
The flags may also include some of the following, which are GNU
extensions and not defined by POSIX.2:
GLOB_PERIOD
which means that a leading period can be matched by meta characters,
GLOB_ALTDIRFUNC
which means that alternative functions
R pglob->gl_closedir ,
R pglob->gl_readdir ,
R pglob->gl_opendir ,
R pglob->gl_lstat , and
pglob->gl_stat
are used for file system access instead of the normal library
functions,
GLOB_BRACE
which means that
csh(1)
style brace expressions
{a,b} are expanded,
GLOB_NOMAGIC
which means that the pattern is returned if it contains no metacharacters,
GLOB_TILDE
which means that tilde expansion is carried out, and
GLOB_ONLYDIR
which means that only directories are matched.
If
errfunc
is not NULL,
it will be called in case of an error with the arguments
R epath ,
a pointer to the path which failed, and
R eerrno ,
the value of
errno
as returned from one of the calls to
opendir(3),
readdir(3),
or
stat(2).
If
errfunc
returns non-zero, or if
GLOB_ERR
is set,
R glob ()
will terminate after the call to
R errfunc .
Upon successful return,
pglob->gl_pathc
contains the number of matched pathnames and
pglob->gl_pathv
a pointer to the list of matched pathnames.
The first pointer after the last pathname is NULL.
It is possible to call
R glob ()
several times.
In that case, the
GLOB_APPEND
flag has to be set in
flags
on the second and later invocations.
As a GNU extension,
pglob->gl_flags
is set to the flags specified, ored with
GLOB_MAGCHAR
if any metacharacters were found.
RETURN VALUE
On successful completion,
R glob ()
returns zero.
Other possible returns are:
GLOB_NOSPACE
for running out of memory,
GLOB_ABORTED
for a read error, and
GLOB_NOMATCH
for no found matches.
CONFORMING TO
POSIX.2, POSIX.1-2001.
NOTES
The structure elements
gl_pathc
and
gl_offs
are declared as
R size_t
in glibc 2.1, as they should according to POSIX.2,
but are declared as
int
in libc4, libc5 and glibc 2.0.
BUGS
The
R glob ()
function may fail due to failure of underlying function calls, such as
malloc(3)
or
opendir(3).
These will store their error code in
R errno .
EXAMPLE
One example of use is the following code, which simulates typing
ls -l *.c ../*.c
in the shell:
glob_t globbuf;
globbuf.gl_offs = 2;
glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] = "-l";
execvp("ls", &globbuf.gl_pathv[0]);
SEE ALSO