glob (3) - Linux Manuals
glob: find pathnames matching a pattern, free memory from glob()
NAME
glob, globfree - find pathnames matching a pattern, free memory from glob()
SYNOPSIS
#include <glob.h> int glob(const char *pattern, int flags, int (*errfunc) (const char *epath, int eerrno), glob_t *pglob); void globfree(glob_t *pglob);
DESCRIPTION
The 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 globfree() function frees the dynamically allocated storage from an earlier call to glob().
The results of a glob() call are stored in the structure pointed to by pglob. This structure is of type glob_t (declared in <glob.h>) and includes the following elements defined by POSIX.2 (more may be present as an extension):
typedef struct {
Results are stored in dynamically allocated storage.
The argument
flags
is made up of the bitwise OR of zero or more the following symbolic
constants, which modify the behavior of
glob():
flags
may also include any of the following, which are GNU
extensions and not defined by POSIX.2:
If
errfunc
is not NULL,
it will be called in case of an error with the arguments
epath,
a pointer to the path which failed, and
eerrno,
the value of
errno
as returned from one of the calls to
opendir(3),
readdir(3),
or
stat(2).
If
errfunc
returns nonzero, or if
GLOB_ERR
is set,
glob()
will terminate after the call to
errfunc.
Upon successful return,
pglob->gl_pathc
contains the number of matched pathnames and
pglob->gl_pathv
contains a pointer to the list of pointers to matched pathnames.
The list of pointers is terminated by a null pointer.
It is possible to call
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.
In the above table,
utent
in
race:utent
signifies that if any of the functions
setutent(3),
getutent(3),
or
endutent(3)
are used in parallel in different threads of a program,
then data races could occur.
glob()
calls those functions,
so we use race:utent to remind users.
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]);
RETURN VALUE
On successful completion,
glob()
returns zero.
Other possible returns are:
ATTRIBUTES
For an explanation of the terms used in this section, see
attributes(7).
Interface Attribute Value
glob()
Thread safety
MT-Unsafe race:utent env
sig:ALRM timer locale
globfree()
Thread safety MT-Safe CONFORMING TO
POSIX.1-2001, POSIX.1-2008, POSIX.2.
NOTES
The structure elements
gl_pathc
and
gl_offs
are declared as
size_t
in glibc 2.1, as they should be according to POSIX.2,
but are declared as
int
in glibc 2.0.
BUGS
The
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
errno.
EXAMPLES
One example of use is the following code, which simulates typing
COLOPHON
This page is part of release 5.10 of the Linux
man-pages
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
https://www.kernel.org/doc/man-pages/.
SEE ALSO
ls(1),
sh(1),
stat(2),
exec(3),
fnmatch(3),
malloc(3),
opendir(3),
readdir(3),
wordexp(3),
glob(7)