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.

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

Caveats:

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

See also:

globfree(), wordexp(), wordfree()