glob()

generate path names matching a pattern 

Function


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

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:

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.


CONFORMANCE

POSIX.2 (1992).


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

The GLOB_NOCASE flag was added because file names are case-insensitive on Windows.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
globfree(), opendir(), readdir(), stat()


PTC MKS Toolkit 10.1 patch 1 Documentation Build 2.