glob, globfree - Generate pathnames matching a pattern
#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 );
Standard C Library (libc)
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.
Contains the filename pattern to compare against accessible
pathnames. Controls the customizable behavior of the
glob function. Specifies an optional function that, if
specified, is called when the glob() function detects an
error condition. 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.
Contains the pathname that failed because a directory
could not be opened or read. Specifies the errno value
from a failure specified by the epath parameter, as set by
the opendir(), readdir(), or stat() functions.
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. Appends pathnames located
with this call to any pathnames previously located. 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. 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. Specifies that each
pathname that is a directory should have a / (slash)
appended. 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. If the GLOB_NOESCAPE option is
set, a \ (backslash) cannot be used to escape metacharacters.
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.
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.
Indicates the scan was stopped because GLOB_ERROR was set
or errfunc returned a nonzero value. Indicates the pattern
does not match any existing pathname, and
GLOB_NOCHECK was not set in options. 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: Specifies the pathname that failed. 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.
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.
Defines glob() macros, data types, and functions.
Functions: fnmatch(3), opendir(3), readdir(3), stat(2)
Standards: standards(5)
glob(3)
[ Back ] |
