Click above to get retro games delivered to your door ever month!

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'.

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 (_crt0_startup_flags:.) suppresses any letter-case   
conversions in filenames and forces case-sensitive filename matching.
_preserve_fncase:.   

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;
     }