glob

Syntax

#include <glob.h> int glob(const char *pattern, int flags, int (*errfunc)(const char *epath, int eerrno), glob_t *pglob);

Description

This function expands a filename wildcard which is passed as pattern. The pattern may include these special characters:

*

Matches zero of more characters.

?

Matches exactly one character (any character).

[...]

Matches one character from a group of characters. If the first character is !, matches any character not in the group. A group is defined as a list of characters between the brackets, e.g. [dkl_], or by two characters separated by - to indicate all characters between and including these two. For example, [a-d] matches a, b, c, or d, and [!a-zA-Z0-9] matches any character that is not alphanumeric.

...

Matches all the subdirectories, recursively (VMS aficionados, rejoice!).

\

Causes the next character to not be treated as special. For example, \[ matches a literal `['. If flags includes GLOB_NOESCAPE, this quoting is disabled and `\' is handled as a simple character.

The variable flags controls certain options of the expansion process. Possible values for flags are as follows:

GLOB_APPEND

Append the matches to those already present in the array pglob->gl_pathv. By default, glob discards all previous contents of pglob->gl_pathv and allocates a new memory block for it. If you use GLOB_APPEND, pglob should point to a structure returned by a previous call to glob.

GLOB_DOOFFS

Skip pglob->gl_offs entries in gl_pathv and put new matches after that point. By default, glob puts the new matches beginning at pglob->gl_pathv[0]. You can use this flag both with GLOB_APPEND (in which case the new matches will be put after the first pglob->gl_offs matches from previous call to glob), or without it (in which case the first pglob->gl_offs entries in pglob->gl_pathv will be filled by NULL pointers).

GLOB_ERR

Stop when an unreadable directory is encountered and call user-defined function errfunc. This cannot happen under DOS (and thus errfunc is never used).

GLOB_MARK

Append a slash to each pathname that is a directory.

GLOB_NOCHECK

If no matches are found, return the pattern itself as the only match. By default, glob doesn't change pglob if no matches are found.

GLOB_NOESCAPE

Disable blackslash as an escape character. By default, backslash quotes special meta-characters in wildcards described above.

GLOB_NOSORT

Do not sort the returned list. By default, the list is sorted alphabetically. This flag causes the files to be returned in the order they were found in the directory.

Given the pattern and the flags, glob expands the pattern and returns a list of files that match the pattern in a structure a pointer to which is passed via pglob. This structure is like this:

typedef struct { size_t gl_pathc; char **gl_pathv; size_t gl_offs; } glob_t;

In the structure, the gl_pathc field holds the number of filenames in gl_pathv list; this includes the filenames produced by this call, plus any previous filenames if GLOB_APPEND or GLOB_DOOFFS were set in flags. The list of matches is returned as an array of pointers to the filenames; gl_pathv holds the address of the array. Thus, the filenames which match the pattern can be accessed as gl_pathv[0], gl_pathv[1], etc. If GLOB_DOOFFS was set in flags, the new matches begin at offset given by gl_offs.

glob allocates memory to hold the filenames. This memory should be freed by calling globfree (see section globfree).

Return Value

Zero on success, or one of these codes:

GLOB_ABORTED

Not used in DJGPP implementation.

GLOB_NOMATCH

No files matched the given pattern.

GLOB_NOSPACE

Not enough memory to accomodate expanded filenames.

GLOB_ERR

Never happens on MSDOS, see above.

Notes

glob will not match names of volume labels.

On MSDOS, filenames are always matched case-insensitively. On filesystems that preserve letter-case in filenames (such as Windows 9x), matches are case-insensitive unless the pattern includes uppercase characters.

On MSDOS, the list of expanded filenames will be returned in lower case, if all the characters of the pattern (except those between brackets [...]) are lower-case; if some of them are upper-case, the expanded filenames will be also in upper case. On filesystems that preserve letter-case in filenames, long filenames are returned as they are found in the directory entry; DOS-style 8+3 filenames are returned as on MSDOS (in lower case if the pattern doesn't include any upper-case letters, in upper case otherwise).

When the environment variable `LFN' is set to n, glob behaves on Windows 9x exactly as it does on MSDOS.

Setting the environment variable `FNCASE' to y, or setting the _CRT0_FLAG_PRESERVE_FILENAME_CASE bit in the _crt0_startup_flags variable (see section _crt0_startup_flags) suppresses any letter-case conversions in filenames and forces case-sensitive filename matching. See section _preserve_fncase.

Portability

ANSI/ISO C	No
POSIX	1003.2-1992; 1003.1-2001

Example

#include <stdlib.h> #include <string.h> #include <glob.h> /* Convert a wildcard pattern into a list of blank-separated filenames which match the wildcard. */ char * glob_pattern(char *wildcard) { char *gfilename; size_t cnt, length; glob_t glob_results; char **p; glob(wildcard, GLOB_NOCHECK, 0, &glob_results); /* How much space do we need? */ for (p = glob_results.gl_pathv, cnt = glob_results.gl_pathc; cnt; p++, cnt--) length += strlen(*p) + 1; /* Allocate the space and generate the list. */ gfilename = (char *) calloc(length, sizeof(char)); for (p = glob_results.gl_pathv, cnt = glob_results.gl_pathc; cnt; p++, cnt--) { strcat(gfilename, *p); if (cnt > 1) strcat(gfilename, " "); } globfree(&glob_results); return gfilename; }