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.
This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size. The GNU implementation contains some more fields which are non-standard extensions.
gl_pathcThe number of elements in the vector, excluding the initial null entries if the GLOB_DOOFFS flag is used (see gl_offs below).
gl_pathvThe address of the vector. This field has type char **.
gl_offsThe offset of the first real element of the vector, from its nominal
address in the 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_closedirThe address of an alternative implementation of the 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_readdirThe address of an alternative implementation of the 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 *).
An implementation of gl_readdir needs to initialize the following
members of the struct dirent object:
d_typeThis member should be set to the file type of the entry if it is known.
Otherwise, the value DT_UNKNOWN can be used. The glob
function may use the specified file type to avoid callbacks in cases
where the file type indicates that the data is not required.
d_inoThis member needs to be non-zero, otherwise glob may skip the
current entry and call the gl_readdir callback function again to
retrieve another entry.
d_nameThis member must be set to the name of the entry. It must be null-terminated.
The example below shows how to allocate a struct dirent object
containing a given name.
#include <dirent.h>
#include <errno.h>
#include <stddef.h>
#include <stdlib.h>
#include <string.h>
struct dirent *
mkdirent (const char *name)
{
size_t dirent_size = offsetof (struct dirent, d_name) + 1;
size_t name_length = strlen (name);
size_t total_size = dirent_size + name_length;
if (total_size < dirent_size)
{
errno = ENOMEM;
return NULL;
}
struct dirent *result = malloc (total_size);
if (result == NULL)
return NULL;
result->d_type = DT_UNKNOWN;
result->d_ino = 1; /* Do not skip this entry. */
memcpy (result->d_name, name, name_length + 1);
return result;
}
The glob function reads the struct dirent members listed
above and makes a copy of the file name in the d_name member
immediately after the gl_readdir callback function returns.
Future invocations of any of the callback functions may deallocate or
reuse the buffer. It is the responsibility of the caller of the
glob function to allocate and deallocate the buffer, around the
call to glob or using the callback functions. For example, an
application could allocate the buffer in the gl_readdir callback
function, and deallocate it in the gl_closedir callback function.
The gl_readdir member is a GNU extension.
gl_opendirThe address of an alternative implementation of the 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_statThe address of an alternative implementation of the 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_lstatThe address of an alternative implementation of the 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.
gl_flagsThe flags used when glob was called. In addition, GLOB_MAGCHAR
might be set. See Flags for Globbing for more details.
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.
This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size. The GNU implementation contains some more fields which are non-standard extensions.
gl_pathcThe number of elements in the vector, excluding the initial null entries if the GLOB_DOOFFS flag is used (see gl_offs below).
gl_pathvThe address of the vector. This field has type char **.
gl_offsThe offset of the first real element of the vector, from its nominal
address in the 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_closedirThe address of an alternative implementation of the 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_readdirThe address of an alternative implementation of the 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_opendirThe address of an alternative implementation of the 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_statThe address of an alternative implementation of the 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_lstatThe address of an alternative implementation of the 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.
gl_flagsThe flags used when glob was called. In addition, GLOB_MAGCHAR
might be set. See Flags for Globbing for more details.
This is a GNU extension.
int glob (const char *pattern, int flags, int (*errfunc) (const char *filename, int error-code), glob_t *vector-ptr) ¶Preliminary: | MT-Unsafe race:utent env sig:ALRM timer locale | AS-Unsafe dlopen plugin corrupt heap lock | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.
The function 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 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 ¶There was an error opening a directory, and you used the flag
GLOB_ERR or your specified errfunc returned a nonzero
value.
for an explanation of the GLOB_ERR flag and errfunc.
GLOB_NOMATCH ¶The pattern didn’t match any existing files. If you use the
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 ¶It was impossible to allocate memory to hold the result.
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 notice 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 assumption made by
the Unix standard. The GNU extension of allowing the user to provide their
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.
int glob64 (const char *pattern, int flags, int (*errfunc) (const char *filename, int error-code), glob64_t *vector-ptr) ¶Preliminary: | MT-Unsafe race:utent env sig:ALRM timer locale | AS-Unsafe dlopen corrupt heap lock | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.
The 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 their 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.
Besides this difference, glob64 works just like glob in
all aspects.
This function is a GNU extension.