glob() -- generate path names matching a pattern

SYNOPSIS

#include <glob.h>

int glob(const char *pattern, int flags, int (*errfunc)(const char *epath, int eerrno), glob_t *pglob);

DESCRIPTION

The glob() function is a path name generator that implements the rules defined for shell pattern and file name matching. The structure glob_t includes at least the following members:

Member Type	Member Name	Description
`size_t`	`gl_pathc`	Count of paths matched by the specified pattern.
`char **`	`gl_pathv`	Pointer to a list of matched path names.
`size_t`	`gl_offs`	Slots to reserve at the beginning of `gl_pathv`.

The pattern parameter is a pointer to a path name pattern to be expanded. The glob() function matches all accessible path names against the 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 the path except the last, and read permission on each directory of any file name component of pattern that contains any of the special characters:

*   ?   [

The glob() function stores the number of path names in the gl_pathc member of pglob and a pointer to a list of pointers to path names in the gl_pathv member of pglob. The path names are sorted alphabetically, unless the GLOB_NOSORT flag is specified. The list of path names is terminated by a null pointer. If the pattern does not match any path names, the returned number of matched paths is 0, and the contents of the gl_pathv member of pglob are undefined.

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 the gl_pathv member. Call globfree() to release this allocated space.

The flags argument is used to control the behavior of glob(). The value is a bitwise-OR of zero or more of the following constants:

GLOB_APPEND: Append path names generated to the ones from a previous call to glob().
GLOB_DOOFFS: Make use of the gl_offs member of pglob. If this flag is set, the gl_offs member is used to specify how many null pointers to add to the beginning of the gl_pathv array. In other words, the gl_pathv array points to gl_offs null pointers, followed by gl_pathcpath 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 the pattern has a slash appended to the name.
GLOB_NOCASE: Ignore case when performing pattern matching and sorting.
GLOB_NOCHECK: If the specified pattern does not match any path name, glob() returns a list consisting of pattern, and the number of matched path names is 1.
GLOB_NOESCAPE: Disable backspace escaping.
GLOB_NOSORT: Do not sort the path name list. The order of the returned path names is unspecified.

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():

The first such call must not set GLOB_APPEND. All subsequent calls must set it.

All the calls must set GLOB_DOOFFS, or all must not set it.

After the second call, the gl_pathv member points to a list containing the following:
- Zero or more null pointers, as specified by GLOB_DOOFFS and the gl_offs member.
- Pointers to the path names that were in the gl_pathv list before the call, in the same order as before.
- Pointers to the new path names generated by the second call, in the specified order.

The count returned in the gl_pathc member is the total number of path names from the two calls.

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 to glob() with the GLOB_APPEND flag.

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:

The epath parameter is a pointer to the path that failed.

The eerrno parameter is the value of errno from the failure, as set by opendir(), readdir(), or stat().

If (*errfunc()) is called and returns non-zero, or if the GLOB_ERR flag was set, glob() stops the scan and returns GLOB_ABORTED after setting gl_pathc and gl_pathv 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.

PARAMETERS

pattern: Points to the path name pattern to be expanded.
flags: Controls the behavior of glob(). The value of flags is defined in the DESCRIPTION section.
errfunc: Points to a function to be called on error, as defined in the DESCRIPTION section.
pglob: Points to the structure that the caller created. This structure must be passed to globfree() to release storage allocated by glob().

RETURN VALUES

If successful, the glob() function returns a zero. The gl_pathc member of pglob returns the number of matched path names, and the gl_pathv member of pglob contains a pointer to a null-terminated list of matched (and potentially sorted) path names. On failure, glob() returns one of the following values:

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()
generate path names matching a pattern

Function

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

CONFORMANCE

MULTITHREAD SAFETY LEVEL

PORTING ISSUES

AVAILABILITY

SEE ALSO

glob() generate path names matching a pattern

Function

glob()
generate path names matching a pattern