HP 3000 Manuals HP 3000 Manuals
glob
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:
* a const char * 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 is the number of path names that match pattern. This is zero
gl_pathc 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 points to a list of strings giving the path names that matched
**gl_pathv pattern. The first pointer after the last path name is NULL.
This field is set by glob().
size_t tells how many NULL pointers you want at the beginning of the
gl_offs 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 Not successful
Value
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()