The GNU C Library - Calling Glob

Calling 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.

Data Type glob_t

This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size.

gl_pathc

The number of elements in the vector.

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_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.

Function int glob (const char *pattern, int flags, int (*errfunc) (const char *filename, int error-code), glob_t *vector-ptr)

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. See Flags for Globbing, 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.