Next: Flags for Globbing, Up: Globbing
globThe 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_pathc- The number of elements in the vector, excluding the initial null entries if the GLOB_DOOFFS flag is used (see gl_offs below).
gl_pathv- The address of the vector. This field has type
char **.gl_offs- The offset of the first real element of the vector, from its nominal address in the
gl_pathvfield. Unlike the other fields, this is always an input toglob, 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
globfunction fills them with null pointers.)The
gl_offsfield is meaningful only if you use theGLOB_DOOFFSflag. 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- The address of an alternative implementation of the
closedirfunction. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isvoid (*) (void *).This is a GNU extension.
gl_readdir- The address of an alternative implementation of the
readdirfunction used to read the contents of a directory. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isstruct dirent *(*) (void *).This is a GNU extension.
gl_opendir- The address of an alternative implementation of the
opendirfunction. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isvoid *(*) (const char *).This is a GNU extension.
gl_stat- The address of an alternative implementation of the
statfunction to get information about an object in the filesystem. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isint (*) (const char *, struct stat *).This is a GNU extension.
gl_lstat- The address of an alternative implementation of the
lstatfunction to get information about an object in the filesystems, not following symbolic links. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isint (*) (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.
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_pathc- The number of elements in the vector, excluding the initial null entries if the GLOB_DOOFFS flag is used (see gl_offs below).
gl_pathv- The address of the vector. This field has type
char **.gl_offs- The offset of the first real element of the vector, from its nominal address in the
gl_pathvfield. Unlike the other fields, this is always an input toglob, 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
globfunction fills them with null pointers.)The
gl_offsfield is meaningful only if you use theGLOB_DOOFFSflag. 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- The address of an alternative implementation of the
closedirfunction. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isvoid (*) (void *).This is a GNU extension.
gl_readdir- The address of an alternative implementation of the
readdir64function used to read the contents of a directory. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isstruct dirent64 *(*) (void *).This is a GNU extension.
gl_opendir- The address of an alternative implementation of the
opendirfunction. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isvoid *(*) (const char *).This is a GNU extension.
gl_stat- The address of an alternative implementation of the
stat64function to get information about an object in the filesystem. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isint (*) (const char *, struct stat64 *).This is a GNU extension.
gl_lstat- The address of an alternative implementation of the
lstat64function to get information about an object in the filesystems, not following symbolic links. It is used if theGLOB_ALTDIRFUNCbit is set in the flag parameter. The type of this field isint (*) (const char *, struct stat64 *).This is a GNU extension.
The function
globdoes 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
globallocates a string for each resulting word, then allocates a vector of typechar **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,
globstores both its address and its length (number of elements, not counting the terminating null pointer) into*vector-ptr.Normally,
globsorts the file names alphabetically before returning them. You can turn this off with the flagGLOB_NOSORTif you want to get the information as fast as possible. Usually it's a good idea to letglobsort 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
globsucceeds, 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_ERRor your specified errfunc returned a nonzero value. for an explanation of theGLOB_ERRflag and errfunc.GLOB_NOMATCH- The pattern didn't match any existing files. If you use the
GLOB_NOCHECKflag, then you never get this error code, because that flag tellsglobto 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,
globstores information in*vector-ptr about all the matches it has found so far.It is important to notice that the
globfunction will not fail if it encounters directories or files which cannot be handled without the LFS interfaces. The implementation ofglobis 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 andstatfunctions complicates things a bit. If these callback functions are used and a large file or directory is encounteredglobcan fail.
The
glob64function 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 aglob64function is added by the extensions of the GNUglobimplementation which allows the user to provide own directory handling andstatfunctions. Thereaddirandstatfunctions do depend on the choice of_FILE_OFFSET_BITSsince the definition of the typesstruct direntandstruct statwill change depending on the choice.Beside this difference the
glob64works just likeglobin all aspects.This function is a GNU extension.