GNU Info
(libc.info)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. 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_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'
The 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_readdir'
The 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 *)'.
This is a GNU extension.
`gl_opendir'
The 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_stat'
The 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_lstat'
The 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.
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'.
- Data Type: glob64_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. 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_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'
The 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_readdir'
The 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_opendir'
The 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_stat'
The 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_lstat'
The 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.
- 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 Note: 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.
Note: 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.
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 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.
- Function: int glob64 (const char *PATTERN, int FLAGS, int (*ERRFUNC)
(const char *FILENAME, int ERROR-CODE), glob64_t *VECTOR-PTR)
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 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.
automatically generated by info2www version 1.2.2.9