glob

NAME

glob, globfree - find pathnames matching a pattern, free memory from glob()

SYNOPSIS

#include <glob.h>
 I int glob(const char * pattern , int  flags ,

I int (* errfunc ) (const char * epath , int eerrno ),
I glob_t * pglob );
I void globfree(glob_t * pglob );

DESCRIPTION

The R glob () function searches for all the pathnames matching pattern according to the rules used by the shell (see glob(7)). No tilde expansion or parameter substitution is done; if you want these, use wordexp(3).
The R globfree () function frees the dynamically allocated storage from an earlier call to R glob ().
The results of a R glob () call are stored in the structure pointed to by R pglob , which is a glob_t which is declared in <glob.h> and includes the following elements defined by POSIX.2 (more may be present as an extension):

typedef struct {
    size_t   gl_pathc;    /* Count of paths matched so far  */
    char   **gl_pathv;    /* List of matched pathnames.  */
    size_t   gl_offs;     /* Slots to reserve in `gl_pathv'.  */
} glob_t;
Results are stored in dynamically allocated storage.
The parameter flags is made up of bitwise OR of zero or more the following symbolic constants, which modify the of behavior of R glob ():
GLOB_ERR
which means to return upon read error (because a directory does not have read permission, for example),
GLOB_MARK
which means to append a slash to each path which corresponds to a directory,
GLOB_NOSORT
which means don't sort the returned pathnames (they are by default),
GLOB_DOOFFS
which means that pglob->gl_offs slots will be reserved at the beginning of the list of strings in R pglob->pathv ,
GLOB_NOCHECK
which means that, if no pattern matches, to return the original pattern,
GLOB_APPEND
which means to append to the results of a previous call. Do not set this flag on the first invocation of R glob ().
GLOB_NOESCAPE
which means that meta characters cannot be quoted by backslashes.
The flags may also include some of the following, which are GNU extensions and not defined by POSIX.2:
GLOB_PERIOD
which means that a leading period can be matched by meta characters,
GLOB_ALTDIRFUNC
which means that alternative functions R pglob->gl_closedir , R pglob->gl_readdir , R pglob->gl_opendir , R pglob->gl_lstat , and pglob->gl_stat are used for file system access instead of the normal library functions,
GLOB_BRACE
which means that csh(1) style brace expressions {a,b} are expanded,
GLOB_NOMAGIC
which means that the pattern is returned if it contains no metacharacters,
GLOB_TILDE
which means that tilde expansion is carried out, and
GLOB_ONLYDIR
which means that only directories are matched.
If errfunc is not NULL, it will be called in case of an error with the arguments R epath , a pointer to the path which failed, and R eerrno , the value of errno as returned from one of the calls to opendir(3), readdir(3), or stat(2). If errfunc returns non-zero, or if GLOB_ERR is set, R glob () will terminate after the call to R errfunc .
Upon successful return, pglob->gl_pathc contains the number of matched pathnames and pglob->gl_pathv a pointer to the list of matched pathnames. The first pointer after the last pathname is NULL.
It is possible to call R glob () several times. In that case, the GLOB_APPEND flag has to be set in flags on the second and later invocations.
As a GNU extension, pglob->gl_flags is set to the flags specified, ored with GLOB_MAGCHAR if any metacharacters were found.

RETURN VALUE

On successful completion, R glob () returns zero. Other possible returns are:
GLOB_NOSPACE
for running out of memory,
GLOB_ABORTED
for a read error, and
GLOB_NOMATCH
for no found matches.

CONFORMING TO

POSIX.2, POSIX.1-2001.

NOTES

The structure elements gl_pathc and gl_offs are declared as R size_t in glibc 2.1, as they should according to POSIX.2, but are declared as int in libc4, libc5 and glibc 2.0.

BUGS

The R glob () function may fail due to failure of underlying function calls, such as malloc(3) or opendir(3). These will store their error code in R errno .

EXAMPLE

One example of use is the following code, which simulates typing ls -l *.c ../*.c in the shell:
glob_t globbuf;

globbuf.gl_offs = 2;
glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] = "-l";
execvp("ls", &globbuf.gl_pathv[0]);

SEE ALSO

ls(1), sh(1), stat(2), exec(3), fnmatch(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7)