glob
The result of globbing is a vector of file names (strings). To return
this vector, glob
uses a special data type, glob_t
, which
is a structure. You pass glob
the address of the structure, and
it fills in the structure's fields to tell you about the results.
gl_pathc
gl_pathv
char **
.
gl_offs
gl_pathv
field. Unlike the other fields, this
is always an input to glob
, rather than an output from it.
If you use a nonzero offset, then that many elements at the beginning of
the vector are left empty. (The glob
function fills them with
null pointers.)
The gl_offs
field is meaningful only if you use the
GLOB_DOOFFS
flag. Otherwise, the offset is always zero
regardless of what is in this field, and the first real element comes at
the beginning of the vector.
gl_closedir
closedir
function. It is used if the GLOB_ALTDIRFUNC
bit is set in
the flag parameter. The type of this field is
void (*) (void *)
.
This is a GNU extension.
gl_readdir
readdir
function used to read the contents of a directory. It is used if the
GLOB_ALTDIRFUNC
bit is set in the flag parameter. The type of
this field is struct dirent *(*) (void *)
.
This is a GNU extension.
gl_opendir
opendir
function. It is used if the GLOB_ALTDIRFUNC
bit is set in
the flag parameter. The type of this field is
void *(*) (const char *)
.
This is a GNU extension.
gl_stat
stat
function
to get information about an object in the filesystem. It is used if the
GLOB_ALTDIRFUNC
bit is set in the flag parameter. The type of
this field is int (*) (const char *, struct stat *)
.
This is a GNU extension.
gl_lstat
lstat
function to get information about an object in the filesystems, not
following symbolic links. It is used if the GLOB_ALTDIRFUNC
bit
is set in the flag parameter. The type of this field is int
(*) (const char *,
struct stat *).
This is a GNU extension.
For use in the glob64
function `glob.h' contains another
definition for a very similar type. glob64_t
differs from
glob_t
only in the types of the members gl_readdir
,
gl_stat
, and gl_lstat
.
gl_pathc
gl_pathv
char **
.
gl_offs
gl_pathv
field. Unlike the other fields, this
is always an input to glob
, rather than an output from it.
If you use a nonzero offset, then that many elements at the beginning of
the vector are left empty. (The glob
function fills them with
null pointers.)
The gl_offs
field is meaningful only if you use the
GLOB_DOOFFS
flag. Otherwise, the offset is always zero
regardless of what is in this field, and the first real element comes at
the beginning of the vector.
gl_closedir
closedir
function. It is used if the GLOB_ALTDIRFUNC
bit is set in
the flag parameter. The type of this field is
void (*) (void *)
.
This is a GNU extension.
gl_readdir
readdir64
function used to read the contents of a directory. It is used if the
GLOB_ALTDIRFUNC
bit is set in the flag parameter. The type of
this field is struct dirent64 *(*) (void *)
.
This is a GNU extension.
gl_opendir
opendir
function. It is used if the GLOB_ALTDIRFUNC
bit is set in
the flag parameter. The type of this field is
void *(*) (const char *)
.
This is a GNU extension.
gl_stat
stat64
function
to get information about an object in the filesystem. It is used if the
GLOB_ALTDIRFUNC
bit is set in the flag parameter. The type of
this field is int (*) (const char *, struct stat64 *)
.
This is a GNU extension.
gl_lstat
lstat64
function to get information about an object in the filesystems, not
following symbolic links. It is used if the GLOB_ALTDIRFUNC
bit
is set in the flag parameter. The type of this field is int
(*) (const char *,
struct stat64 *).
This is a GNU extension.
glob
does globbing using the pattern pattern
in the current directory. It puts the result in a newly allocated
vector, and stores the size and address of this vector into
*vector-ptr
. The argument flags is a combination of
bit flags; see section Flags for Globbing, for details of the flags.
The result of globbing is a sequence of file names. The function
glob
allocates a string for each resulting word, then
allocates a vector of type char **
to store the addresses of
these strings. The last element of the vector is a null pointer.
This vector is called the word vector.
To return this vector, glob
stores both its address and its
length (number of elements, not counting the terminating null pointer)
into *vector-ptr
.
Normally, glob
sorts the file names alphabetically before
returning them. You can turn this off with the flag GLOB_NOSORT
if you want to get the information as fast as possible. Usually it's
a good idea to let glob
sort them--if you process the files in
alphabetical order, the users will have a feel for the rate of progress
that your application is making.
If glob
succeeds, it returns 0. Otherwise, it returns one
of these error codes:
GLOB_ABORTED
GLOB_ERR
or your specified errfunc returned a nonzero
value.
See below
for an explanation of the GLOB_ERR
flag and errfunc.
GLOB_NOMATCH
GLOB_NOCHECK
flag, then you never get this error code, because
that flag tells glob
to pretend that the pattern matched
at least one file.
GLOB_NOSPACE
In the event of an error, glob
stores information in
*vector-ptr
about all the matches it has found so far.
It is important to notive that the glob
function will not fail if
it encounters directories or files which cannot be handled without the
LFS interfaces. The implementation of glob
is supposed to use
these functions internally. This at least is the assumptions made by
the Unix standard. The GNU extension of allowing the user to provide
own directory handling and stat
functions complicates things a
bit. If these callback functions are used and a large file or directory
is encountered glob
can fail.
glob64
function was added as part of the Large File Summit
extensions but is not part of the original LFS proposal. The reason for
this is simple: it is not necessary. The necessity for a glob64
function is added by the extensions of the GNU glob
implementation which allows the user to provide own directory handling
and stat
functions. The readdir
and stat
functions
do depend on the choice of _FILE_OFFSET_BITS
since the definition
of the types struct dirent
and struct stat
will change
depending on the choice.
Beside this difference the glob64
works just like glob
in
all aspects.
This function is a GNU extension.
Go to the first, previous, next, last section, table of contents.