GLOB(3C) Standard C Library Functions GLOB(3C)
NAME
glob, globfree - generate path names matching a pattern
SYNOPSIS
#include <glob.h>
int glob(
const char *restrict pattern,
int flags,
int(*errfunc)(const char *
epath, int
eerrno),
glob_t *restrict pglob);
void globfree(
glob_t *pglob);
DESCRIPTION
The
glob() function is a path name generator.
The
globfree() function frees any memory allocated by
glob() associated
with
pglob.
pattern Argument
The argument
pattern is a pointer to a path name pattern to be expanded.
The
glob() function matches all accessible path names against this
pattern and develops a list of all path names that match. In order to
have access to a path name,
glob() 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
following special characters:
* ? [
pglob Argument
The structure type
glob_t is defined in the header
<glob.h> and includes
at least the following members:
size_t gl_pathc; /* Total count of paths matched by */
/* pattern */
char **gl_pathv; /* List of matched path names */
size_t gl_offs; /* # of slots reserved in gl_pathv */
int gl_matchc; /* Count of paths matching pattern. */
int gl_flags; /* Copy of flags parameter to glob. */
The
glob() function stores the number of matched path names into
pglob->gl_pathc and a pointer to a list of pointers to path names into
pglob->gl_pathv. The path names are in sort order as defined by the
current setting of the
LC_COLLATE category. The first pointer after the
last path name is a
NULL pointer. If the pattern does not match any path
names, the returned number of matched paths is set to 0, and the contents
of
pglob->gl_pathv are implementation-dependent.
It is the caller's responsibility to create the structure pointed to by
pglob. The
glob() function allocates other space as needed, including the
memory pointed to by
gl_pathv. The
globfree() function frees any space
associated with
pglob from a previous call to
glob().
flags Argument
The
flags argument is used to control the behavior of
glob(). The value
of
flags is a bitwise inclusive
OR of zero or more of the following
constants, which are defined in the header <
glob.h>:
GLOB_APPEND Append path names generated to the ones from a previous
call to
glob().
GLOB_DOOFFS Make use of
pglob->gl_offs. If this flag is set,
pglob->gl_offs is used to specify how many
NULL pointers
to add to the beginning of
pglob->gl_pathv. In other
words,
pglob->gl_pathv will point to
pglob->gl_offs NULL pointers, followed by
pglob->gl_pathc path name
pointers, followed by a
NULL pointer.
GLOB_ERR Causes
glob() to return when it encounters a directory
that it cannot open or read. Ordinarily,
glob() continues to find matches.
GLOB_MARK Each path name that is a directory that matches
pattern has a slash appended.
GLOB_NOCHECK If
pattern does not match any path name, then
glob() returns a list consisting of only
pattern, and the
number of matched path names is 1.
GLOB_NOESCAPE Disable backslash escaping.
GLOB_NOSORT Ordinarily,
glob() sorts the matching path names
according to the current setting of the
LC_COLLATE category. When this flag is used the order of path
names returned is unspecified.
GLOB_ALTDIRFUNC The following additional fields in the
pglob structure
have been initialized with alternate functions for
glob() to use to open, read, and close directories and
to get stat information on names found in those
directories:
void *(*gl_opendir)(const char *);
struct dirent *(*gl_readdir)(void *);
void (*gl_closedir)(void *);
int (*gl_lstat)(const char *, struct stat *);
int (*gl_stat)(const char *, struct stat *);
This extension is provided to allow programs such as
ufsrestore(8) to provide globbing from directories
stored on tape.
GLOB_BRACE Pre-process the pattern string to expand `{pat,pat,...}'
strings like
csh(1). The pattern `{}' is left
unexpanded for historical reasons. (
csh(1) does the
same thing to ease typing of
find(1) patterns.)
GLOB_MAGCHAR Set by the
glob() function if the pattern included
globbing characters. See the description of the usage
of the
gl_matchc structure member for more details.
GLOB_NOMAGIC Is the same as
GLOB_NOCHECK but it only appends the
pattern if it does not contain any of the special
characters `*', `?', or `['.
GLOB_NOMAGIC is provided
to simplify implementing the historic
csh(1) globbing
behavior and should probably not be used anywhere else.
GLOB_QUOTE This option has no effect and is included for backwards
compatibility with older sources.
GLOB_TILDE Expand patterns that start with `~' to user name home
directories.
GLOB_LIMIT Limit the amount of memory used by matches to
ARG_MAX.
This option should be set for programs that can be
coerced to a denial of service attack via patterns that
expand to a very large number of matches, such as a long
string of `*/../*/..'.
GLOB_KEEPSTAT Retain a copy of the
stat(2) information retrieved for
matching paths in the gl_statv array:
struct stat **gl_statv;
This option may be used to avoid
lstat(2) lookups in
cases where they are expensive.
The
GLOB_APPEND flag can be used to append a new set of path names to
those found in a previous call to
glob(). The following rules apply when
two or more calls to
glob() are made with the same value of
pglob and
without intervening calls to
globfree():
1. The first such call must not set
GLOB_APPEND. All subsequent
calls must set it.
2. All the calls must set
GLOB_DOOFFS, or all must not set it.
3. After the second call,
pglob->gl_pathv points to a list
containing the following:
a. Zero or more
NULL pointers, as specified by
GLOB_DOOFFS and
pglob->gl_offs.
b. Pointers to the path names that were in the
pglob->gl_pathv list before the call, in the same order as
before.
c. Pointers to the new path names generated by the second
call, in the specified order.
4. The count returned in
pglob->gl_pathc will be the total number
of path names from the two calls.
5. The application can change any of the fields after a call to
glob(). If it does, it must reset them to the original value
before a subsequent call, using the same
pglob value, to
globfree() or
glob() with the
GLOB_APPEND flag.
errfunc and
epath Arguments
If, during the search, a directory is encountered that cannot be opened
or read and
errfunc is not a
NULL pointer,
glob() calls
(*errfunc) with
two arguments:
1. The
epath argument is a pointer to the path that failed.
2. The
eerrno argument is the value of
errno from the failure, as
set by the
opendir(3C),
readdir(3C) or
stat(2) functions.
(Other values may be used to report other errors not
explicitly documented for those functions.)
If
(*errfunc) is called and returns non-zero, or if the
GLOB_ERR flag is
set in
flags,
glob() stops the scan and returns
GLOB_ABORTED after
setting
gl_pathc and
gl_pathv in
pglob to reflect the paths already
scanned. If
GLOB_ERR is not set and either
errfunc is a
NULL pointer or
(*errfunc) returns 0, the error is ignored.
RETURN VALUES
On successful completion,
glob() returns zero. In addition the fields of
pglob contain the values described below:
gl_pathc Contains the total number of matched pathnames so far.
This includes other matches from previous invocations of
glob() if
GLOB_APPEND was specified.
gl_matchc Contains the number of matched pathnames in the current
invocation of
glob().
gl_flags Contains a copy of the flags parameter with the bit
GLOB_MAGCHAR set if pattern contained any of the special
characters `*', `?', or `[', cleared if not.
gl_pathv Contains a pointer to a null-terminated list of matched
pathnames. However, if
gl_pathc is zero, the contents of
gl_pathv are undefined.
gl_statv If the
GLOB_KEEPSTAT flag was set,
gl_statv contains a
pointer to a null-terminated list of matched
stat(2) objects corresponding to the paths in
gl_pathc.
If
glob() terminates due to an error, it sets
errno and returns one of
the following non-zero constants. defined in <
glob.h>:
GLOB_ABORTED The scan was stopped because
GLOB_ERR was set or
(*errfunc) returned non-zero.
GLOB_NOMATCH The pattern does not match any existing path name, and
GLOB_NOCHECK was not set in flags.
GLOB_NOSPACE An attempt to allocate memory failed.
GLOB_NOSYS The requested function is not supported by this version
of
glob().
The arguments
pglob->gl_pathc and
pglob->gl_pathv are still set as
specified above.
The
globfree() function returns no value.
USAGE
This function is not provided for the purpose of enabling utilities to
perform path name expansion on their arguments, as this operation is
performed by the shell, and utilities are explicitly not expected to redo
this. Instead, it is provided for applications that need to do path name
expansion on strings obtained from other sources, such as a pattern typed
by a user or read from a file.
If a utility needs to see if a path name matches a given pattern, it can
use
fnmatch(3C).
Note that
gl_pathc and
gl_pathv have meaning even if
glob() fails. This
allows
glob() to report partial results in the event of an error.
However, if
gl_pathc is 0,
gl_pathv is unspecified even if
glob() did not
return an error.
The
GLOB_NOCHECK option could be used when an application wants to expand
a path name if wildcards are specified, but wants to treat the pattern as
just a string otherwise.
The new path names generated by a subsequent call with
GLOB_APPEND are
not sorted together with the previous path names. This mirrors the way
that the shell handles path name expansion when multiple expansions are
done on a command line.
Applications that need tilde and parameter expansion should use the
wordexp(3C) function.
EXAMPLES
Example 1: Example of glob_doofs function.
One use of the
GLOB_DOOFFS flag is by applications that build an argument
list for use with the
execv(),
execve(), or
execvp() functions (see
exec(2)). Suppose, for example, that an application wants to do the
equivalent of:
ls -l *.c
but for some reason:
system("ls -l *.c")
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 approximately simulated using
GLOB_APPEND as follows:
globbuf.gl_offs = 2; glob ("*.c", GLOB_DOOFFS, NULL, &globbuf); glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); ...ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
SEE ALSO
execv(2),
stat(2),
fnmatch(3C),
opendir(3C),
readdir(3C),
wordexp(3C),
attributes(7),
standards(7) November 1, 2003
GLOB(3C)