 |
Index for
Section 3 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
glob(3)
NAME
glob, globfree - Generate pathnames matching a pattern
SYNOPSIS
#include <glob.h>
int glob(
const char *pattern,
int options,
int (*errfunc)(const char *epath, int eerrno),
glob_t *pglob );
void globfree(
glob_t *pglob );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
glob(), globfree(): XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
pattern
Contains the filename pattern to compare against accessible pathnames.
flags
Controls the customizable behavior of the glob function.
errfunc
Specifies an optional function that, if specified, is called when the
glob() function detects an error condition.
pglob
Contains a pointer to a glob_t structure. The structure is allocated by
the caller. The array of structures containing the filenames located
that match the pattern parameter are stored by the glob() function into
the structure. The last entry is a NULL pointer.
epath
Contains the pathname that failed because a directory could not be
opened or read.
eerrno
Specifies the errno value from a failure specified by the epath
parameter, as set by the opendir(), readdir(), or stat() functions.
DESCRIPTION
The glob() function constructs a list of accessible files that match the
pattern parameter.
The glob() function matches all accessible pathnames against this pattern
and develops a list of all pathnames that match. In order to have access to
a pathname, the glob() function requires search permission on every
component of a pathname except the last, and read permission on each
directory of any filename component of the pattern parameter that contains
any of the special characters * (asterisk), ? (question mark), or [ (open
bracket).
The glob() function stores the number of matched pathnames and a pointer to
a list of pointers to pathnames in the pglob parameter. The pathnames are
sorted, based on the setting of the LC_COLLATE category in the current
locale. The first pointer after the last pathname is NULL. If the pattern
does not match any pathnames, the returned number of matched pathnames is 0
(zero).
It is the caller's responsibility to create the structure pointed to by the
pglob parameter. The glob()function allocates other space as needed. The
globfree() function frees any space associated with the pglob parameter due
to a previous call to the glob() function.
The flags parameter is used to control the behavior of the glob() function.
The flags value is the bitwise inclusive OR (|) of any of the following
constants, which are defined in the glob.h file.
GLOB_APPEND
Appends pathnames located with this call to any pathnames previously
located.
GLOB_DOOFFS
Uses the gl_offs structure to specify the number of NULL pointers to
add to the beginning of the gl_pathv component of the pglob parameter.
GLOB_ERR
Causes the glob() function to return when it encounters a directory
that it cannot open or read. If the GLOB_ERR option is not set, the
glob() function continues to find matches if it encounters a directory
that it cannot open or read.
GLOB_MARK
Specifies that each pathname that is a directory should have a /
(slash) appended.
GLOB_NOCHECK
If the pattern parameter does not match any pathname, then the glob()
function returns a list consisting only of the pattern parameter, and
the number of matched patterns is one.
GLOB_NOESCAPE
If the GLOB_NOESCAPE option is set, a \ (backslash) cannot be used to
escape metacharacters.
GLOB_NOSORT
Specifies that the list of pathnames need not be sorted. If the
GLOB_NOSORT option is not set, pathnames are collated according to the
current setting of the LC_COLLATE category.
The GLOB_APPEND option can be used to append a new set of pathnames to
those found in a previous call to the glob() function. The following rules
apply when two or more calls to the glob() function are made with the same
value of the pglob parameter and without intervening calls to the glob()
function:
· If the application set the GLOB_DOOFFS option in the first call to the
glob() function, then it is also set in the second call, and the value
of the gl_ofs field of the pglob parameter is not modified between the
calls.
· If the application did not set the GLOB_DOOFFS option in the first
call to the glob() function, then it is not set in the second call.
· After the second call, the gl_pattr field of the pglob parameter
points to a list containing the following:
-- Zero or more NULLs, as specified by the GLOB_DOOFFS option and
pglob->gl_offs.
-- Pointers to the pathnames that were in the pglob->gl_pathv list
before the call, in the same order as after the first call to the
glob() function.
-- Pointers to the new pathnames generated by the second call, in
the specified order.
· The count returned in the pglob->gl_pathc parameter is the total
number of pathnames from the two calls.
· The application should not modify the pglob->gl_pathc or pglob-
>gl_pathv fields between the two calls.
RETURN VALUES
On successful completion, the glob() function returns a value of 0 (zero).
The pglob->gl_pathc field returns the number of matched pathnames and the
pglob->gl_pathv field contains a pointer to a NULL-terminated list of
matched and sorted pathnames. If the number of matched pathnames in the
pglob->gl_pathc parameter is 0 (zero), the pointer in the pglob->gl_pathv
parameter is undefined.
If the glob() function terminates due to an error, the function returns one
of the following nonzero constants. These are defined in the glob.h file.
In this case, the pglob parameter values are still set as defined above.
GLOB_ABORTED
Indicates the scan was stopped because GLOB_ERROR was set or errfunc
returned a nonzero value.
GLOB_NOMATCH
Indicates the pattern does not match any existing pathname, and
GLOB_NOCHECK was not set in options.
GLOB_NOSPACE
Indicates an attempt to allocate memory failed.
If, during the search, a directory is encountered that cannot be opened or
read and the errfunc parameter value is not NULL, the glob() function calls
errfunc with two arguments:
epath
Specifies the pathname that failed.
eerrno
Specifies the value of errno from the failure, as set by the opendir(),
readdir(), or stat() functions.
If errfunc is called and returns nonzero, or if the GLOB_ERR option is set
in flags, the glob() function stops the scan and returns GLOB_ABORTED after
setting the pglob parameter to reflect the pathnames already scanned. If
GLOB_ERR is not set and either errfunc is NULL or errfunc returns zero, the
error is ignored.
No errno values are returned.
EXAMPLES
Note that the pglob parameter has meaning even if the glob() function
fails. This allows the glob() function to report partial results in the
event of an error. However, if the number of matched pathnames is 0
(zero), the pointer in the pglob parameter is unspecified even if the
glob() function did not return an error.
The GLOB_NOCHECK option can be used when an application wants to expand a
pathname if wildcards are specified, but wants to treat the pattern as just
a string otherwise. The sh command can use this for option parameters, for
example.
One use of the GLOB_DOOFFS option is for applications that build an
argument list for use with the execv(), execve(), or execvp() functions;
for example, if an application needs to do the equivalent of ls -l *.c, but
for some reason this is not acceptable. The application could obtain
approximately the same result using the sequence:
globbuf.gl_offs = 2;
glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] ="-l";
execvp ("ls", &globbuf.gl_pathv[0]);
Using the same example, ls -l *.c *.h could be approximated using the
GLOB_APPEND option as follows:
globbuf.gl_offs = 2;
glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);
The new pathnames generated by a subsequent call with the GLOB_APPEND
option set are not sorted together with the previous pathnames. This
process mirrors the way that the shell handles pathname expansion when
multiple expansions are done on a command line.
FILES
/usr/include/glob.h
Defines glob() macros, data types, and functions.
SEE ALSO
Functions: fnmatch(3), opendir(3), readdir(3), stat(2)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|