 |
» |
|
|
|
Generate path name list matching pattern.
Syntax | |
#include <glob.h>
int glob(const char *pattern, int flags,
int (*errfunc)(const char *name, int errno),
glob_t *paths);
|
Parameters | |
- pattern
is a string giving a path name pattern, possibly containing wild card characters and other path name generation constructs.
- flags
is a collection of flags controlling the glob() action. Flags are specified by ORing together symbolic constants defined in <glob.h>. Possible symbols are:
- GLOB_APPEND
appends path names to an existing paths list
generated by a previous call to glob().
- GLOB_DOOFFS
uses the gl_offs field in the glob_t structure
paths.
- GLOB_ERR
tells glob() to return when it encounters a
directory it cannot open or read. By default,
glob() continues to look for matches (see also
errfunc.)
- GLOB_MARK
distinguishes between directories and files with names that match pattern by putting a slash (/) after directory names.
- GLOB_NOCHECK
takes a special action if no path names match
pattern. By default, glob() returns a null list if
there are no path names matching pattern. However,
if GLOB_NOCHECK is specified, glob() returns a list
consisting only of pattern and indicates that the
number of matched path names is 1. You might use
this option if an argument can be either a path name
or a normal string.
- GLOB_NOESCAPE
turns off escape character functionality. By
default, glob() treats a backslash (\) as the escape
character. - GLOB_NOSORT
does not sort matching path names. By default,
glob() sorts the path names according to the current
locale's collating sequence.
- errfunc
is a function to be called if glob() finds a directory
that cannot be opened or read. If the errfunc pointer
is NULL, glob() ignores such directories; otherwise,
glob() calls the function indicated by errfunc, passing
two arguments:
giving the name of the directory that
could not be opened or read;
an int giving the value of errno set by the function
that tried to open or read the directory. This
function could be opendir(), readdir(), or stat().
- paths
points to an area where glob() can store a glob_t
structure. This structure gives the list of path names
matching pattern and other information. It must be
created by the caller.
Description | |
glob() generates a list of all accessible path names
matching pattern. For access to a path name, glob() must
have search permission on every component of the path name
except the last, and must have read permission on the
parent directory of each filename component of pattern
that contains any of the wild card characters *, ?, or [.
The path name list is given using a glob_t structure.
This structure has the following fields:
- size_t gl_pathc
is the number of path names that match pattern. This is zero if glob() finds no matching path names. However, if GLOB_NOCHECK is specified, gl_pathc is always 1, as discussed under the description of GLOB_NOCHECK in the Parameters section. This field is set by glob().
- char **gl_pathv
points to a list of strings giving the path names that matched pattern. The first pointer after the last path name is NULL. This field is set by glob().
- size_t gl_offs
tells how many NULL pointers you want at the beginning of the gl_pathv list. This creates a specified amount of blank space at the beginning of gl_pathv that can be used for other purposes. For example, you might fill this space with other arguments before passing the whole gl_pathv vector as an argument to a function like execv().
Before calling glob(), set gl_offs to the number of NULL
pointers that glob() inserts in the gl_pathv list. These
NULL pointers precede the pointers to the strings which
identify path names that match pattern. glob() only uses
the value in gl_offs if you have set GLOB_DOOFFS in flags.
If GLOB_APPEND is specified to add new path names to an existing list, glob() follows these rules:
If GLOB_DOOFFS is set in the first call to glob(), it must be set in subsequent calls and gl_offs must have the same value in each call;
If GLOB_DOOFFS is not set in the first call, it must not be set in subsequent calls;
After the second call, gl_pathv points to a list containing:
The number of NULL pointers as determined by GLOB_DOOFFS and gl_offs;
Pointers to the path names that were in the list before the second call, in the same order as before;
Pointers to the new path names obtained by the second call, in the order dictated by the flags for the second call.
gl_pathc gives the total number of path names from all the calls.
The application should not change gl_pathc or gl_pathv
between calls.
As noted earlier, the function given by (*errfunc) () is
called if glob() encounters a directory that cannot be
opened or read. If (*errfunc) () returns non-zero or if
GLOB_ERR is set in flags, glob() sets paths to reflect the
path names already obtained, then returns with a result of
GLOB_ABORTED. (This symbolic constant is defined in
<glob.h>.) If GLOB_ERR is not specified and if either
errfunc is NULL or (*errfunc) () returns zero, glob()
ignores the error and continues searching for matching
path names.
Return Values | |
- 0
Completes successfully
- Error Value
Not successful
If glob() terminates prematurely with one of these errors, it still sets paths->gl_pathc and paths->gl_pathv to show whatever path names it has already found.
Once a program has finished using the paths structure, it should use globfree() to free up the space used to store the path name list.
Errors | |
If an error occurs, errno is set to one of the following values:
| GLOB_NOSPACE | CAUSE | glob() was unable to allocate memory for at least one of the path names obtained. | | | ACTION | Free up more memory. | | GLOB_NOMATCH | CAUSE | glob() did not find any path names which matched pattern and GLOB_NOCHECK was not set in the flags. | | | ACTION | No action required. | | GLOB_ABORTED | CAUSE | glob() stopped because GLOB_ERR was set (perhaps a directory could not be opened or read), or because (*errfunc) () returned non-zero. | | | ACTION | Check that the offending directory exists, that it was named properly, and that you have appropriate permissions. |
See Also | |
fnmatch(), globfree()
|
