glob()

Find paths matching a pattern

Synopsis:

#include <glob.h>

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

Arguments:

pattern

The pattern you want to match. This can include these wildcard characters:

* matches any string, of any length
? matches any single character
[chars] matches any of the characters found in the string chars.

flags

Flags that affect the search; see below.

errfunc

A pointer to a function that glob() calls when it encounters a directory that it can't open or read. For more information, see below.

pglob

A pointer to a glob_t structure where glob() can store the paths found. This structure contains at least the following members:

size_t gl_pathc — the number of pathnames matched by pattern.
char** gl_pathv — a NULL-terminated array of pointers to the pathnames matched by pattern.
size_t gl_offs — the number of pointers to reserve at the beginning of gl_pathv.

You must create the glob_t structure before calling glob(). The glob() function allocates storage as needed for the gl_pathv array. Use globfree() to free this space.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

This function is in libc.a, but not in libc.so (in order to save space).

Description:

The glob() function finds pathnames matching the given pattern.

In order to have access to a pathname, glob() must have search permission on every component of the path except the last, and read permission on each directory of every filename component of pattern that contains any of the special characters (*, ?, [ and ]).

The errfunc argument is a pointer to an error-handler function with this prototype:

int errfunc( const char* epath, int error );

The errfunc function is called when glob() encounters a directory that it can't open or read. The arguments are:

epath: A pointer to the path that failed.
error: The value of errno from the failure. The error argument can be set to any of the values returned by opendir(), readdir(), or stat().

The errfunc function should return 0 if glob() should continue, or a nonzero value if glob() should stop searching.

You can set errfunc to NULL to ignore these types of errors.

The flags argument can be set to any combination of the following bits:

GLOB_APPEND: Append found pathnames to the ones from a previous call from glob().
GLOB_DOOFFS: Use the value in pglob->gl_offs to specify how many NULL pointers to add at the beginning of pglob->pathv. After the call to glob(), pglob->pathv will contain pglob->gl_offs NULL pointers, followed by pglob->gl_pathc pathnames, followed by a NULL pointer. This can be useful if you're building a command to be applied to the matched files.
GLOB_ERR: Cause glob() to return when it encounters a directory that it can't open or read. Otherwise, glob() will continue to find matches.
GLOB_MARK: Append a slash to each matching pathname that's a directory.
GLOB_NOCHECK: If pattern doesn't match any path names, return only the contents of pattern.
GLOB_NOESCAPE: Disable backslash escapes in pattern.
GLOB_NOSORT: Don't sort the returned pathnames; their order will be unspecified. The default is to sort the pathnames.

The following flags are BSD extensions:

GLOB_PERIOD: Allow metacharacters to match leading periods.
GLOB_MAGCHAR: Pattern had globbing characters.
GLOB_ALTDIRFUNC: Use alternately specified directory functions.
GLOB_BRACE: Expand braces the way that the C shell does.
GLOB_NOMAGIC: Similar to GLOB_NOCHECK without magic characters (csh).
GLOB_TILDE: Expand tilde names from the passwd file.
GLOB_NO_DOTDIRS: Make . and .. vanish from wildcards.
GLOB_LIMIT: Limit memory used by matches to ARG_MAX.

Returns:

Zero for success, or an error value.

Errors:

GLOB_ABEND: The scan was stopped because GLOB_ERR was set, or the errfunc function returned nonzero.
GLOB_NOMATCH: The value of pattern doesn't match any existing pathname, and GLOB_NOCHECK wasn't set in flags.
GLOB_NOSPACE: Unable to allocate memory to store the matched paths.

Examples:

This simple example attempts to find all of the .c files in the current directory and print them in the order the filesystem found them.

#include <unistd.h>
#include <stdio.h>
#include <glob.h>

int main( void )
{
    glob_t paths;
    int retval;
    
    paths.gl_pathc = 0;
    paths.gl_pathv = NULL;
    paths.gl_offs = 0;

    retval = glob( "*.c", GLOB_NOCHECK | GLOB_NOSORT,
                   NULL, &paths );
    if( retval == 0 ) {
        int idx;
        
        for( idx = 0; idx < paths.gl_pathc; idx++ ) {
            printf( "[%d]: %s\n", idx, 
                    paths.gl_pathv[idx] );
        }
        
        globfree( &paths );
    } else {
        puts( "glob() failed" );
    }
    
    return 0;
}

Classification:

POSIX 1003.1

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes

Caveats:

Don't change the values in pglob between calling glob() and globfree().