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().