glob(3) Library Functions Manual glob(3)
NAME
glob, globfree - Generate pathnames matching a pattern
LIBRARY
Standard C Library (libc.so, libc.a)
SYNOPSIS
#include <glob.h>
int glob(
const char *pattern,
int flags,
int (*errfunc)(const char *epath, int eerrno),
glob_t *pglob);
void globfree(
glob_t *pglob);
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
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 param-
eter 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.
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. 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 flag 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 flag is set, a (backslash)
cannot be used to escape metacharacters. Specifies that the list of pathnames need not be sorted. If the GLOB_NOSORT flag is not set,
pathnames are collated according to the current setting of the LC_COLLATE category.
The GLOB_APPEND flag 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 flag 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 flag 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 flag 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.
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 flag 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 flag parameters, for example.
One use of the GLOB_DOOFFS flag 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", &glob-
buf.gl_pathv[0]);
Using the same example, ls -l *.c *.h could be approximated using the GLOB_APPEND flag 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 flag 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.
RETURN VALUES
On successful completion, the glob() function returns a value of 0 (zero). The pglob->gl_pathc field returns the number of matched path-
names 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
flags. 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 flag 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.
FILES
Defines glob() macros, data types, and functions.
RELATED INFORMATION
Functions: fnmatch(3), opendir(3), readdir(3), stat(2)
Standards: standards(5) delim off
glob(3)