glob(), globfree() - generate pathnames matching a pattern
#include <glob.h>
int glob (const char *pattern, int flags,
const int (*errfunc)(const char *, int), glob_t *pglob)
void globfree (glob_t *pglob)
The glob(3) function is a pathname generator that implements the rules for file name pattern matching used by the standard shell.
The include file <glob.h> defines the structure type glob_t, which contains at least the following fields:
typedef struct {
int gl_pathc; /* count of total paths so far */
int gl_matchc; /* count of paths matching pattern */
int gl_offs; /* reserved at beginning of gl_pathv */
int gl_flags; /* returned flags */
char **gl_pathv; /* list of paths matching pattern */
} glob_t;
The argument pattern is a pointer to a pathname pattern
to be expanded. The glob(3) argument matches all accessible pathnames
against the pattern and creates a list of the pathnames that match.
In order to have access to a pathname, glob(3) requires search
permission on every component of a path except the last and read
permission on each directory of any filename component of
pattern that contains any of the special characters
*, ? or [.
The glob(3) argument stores the number of matched pathnames into the gl_pathc field, and a pointer to a list of pointers to pathnames into the gl_pathv field. The first pointer after the last pathname is NULL. If the pattern does not match any pathnames, the returned number of matched paths is set to zero.
It is the caller's responsibility to create the structure pointed to by pglob. The glob(3) function allocates other space as needed, including the memory pointed to by gl_pathv.
The argument flags is used to modify the behavior of glob(3). The value of flags is the bitwise inclusive OR of any of the following values defined in <glob.h>:
The following values may also be included in flags, however, they are non-standard extensions to
void *(*gl_opendir)(const char * name);
struct dirent *(*gl_readdir)(void *);
void (*gl_closedir)(void *);
int (*gl_lstat)(const char *name, struct stat *st);
int (*gl_stat)(const char *name, struct stat *st);
This extension is provided to allow programs such as restore() to provide globbing from directories stored on tape.
{pat,pat,...} strings like Csh(1)The
{} is left unexpanded for historical reasons
(Csh(1) does the same thing to ease typing of
find() patterns).(\ character for quoting: every
occurrence of a backslash followed by a character in the pattern is
replaced by that character, avoiding any special interpretation of
the character.~ to user name
home directories.If, during the search, a directory is encountered that cannot be opened or read and errfunc is non-NULL, glob(3) calls (*errfunc This may be unintuitive: a pattern like */Makefile will try to stat(2) foo/Makefile even if foo is not a directory, resulting in a call to errfunc. The error routine can suppress this action by testing for ENOENT and ENOTDIR; however, the GLOB_ERR flag will still cause an immediate return when this happens.
If errfunc returns non-zero, glob(3) stops the scan and returns GLOB_ABEND after setting gl_pathc and gl_pathv to reflect any paths already matched. This also happens if an error is encountered and GLOB_ERR is set in flags, regardless of the return value of errfunc, if called. If GLOB_ERR is not set and either errfunc is NULL or errfunc returns zero, the error is ignored.
The globfree(3) function frees any space associated with pglob from a previous call(s) to glob(3).
On successful completion, glob(3) returns zero. In addition the fields of pglob contain the values described below:
If glob(3) terminates due to an error, it sets errno and returns one of the following non-zero constants, which are defined in the include file <glob.h>:
The arguments pglob->gl_pathc and pglob->gl_pathv are still set as specified above.
A rough equivalent of ls -l *.c *.h can be obtained
with the following code:
glob_t g;
g.gl_offs = 2;
glob("*.c", GLOB_DOOFFS, NULL, &g);
glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
g.gl_pathv[0] = "ls";
g.gl_pathv[1] = "-l";
execvp("ls", g.gl_pathv);
The file name matching implemented by glob(3) is the basic set of matches specified by the Open Group's specification. It treats the characters *, ?, and [ as special. It does not support all of the special matches that are part of the KornShell (such as *(), for example).
sh(1)
fnmatch(3)
regexec(3)
Patterns longer than {MAXPATHLEN} may cause unchecked errors.
The glob(3) argument may fail and set errno for any of the errors specified for the library routines stat(2), closedir(3), opendir(3), readdir(2), malloc(3), and free(3).