glob()

Updated: April 19, 2023

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.

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; they'll appear in an arbitrary order. 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().