glob
glob(3C) glob(3C)
NAME
glob(), globfree() - file name generation function
SYNOPSIS
#include
int glob(
const char *pattern,
int flags,
int (*errfunc)(const char *, int),
glob_t *pglob
);
void globfree(glob_t *pglob);
DESCRIPTION
glob() is a path name generator. pattern is a pointer to a path name
pattern to be expanded. If pattern contains any of the special
characters *, ?, or [, pattern is matched against all accessible path
names. In order to have access to a path name, glob() requires:
o Search permission on every component of a path except the
last.
o Read permission on each directory of any file name component
of pattern that contains any of the above special characters.
glob() stores the number of matched path names in pglob -> gl_pathc
and a pointer to a sorted list of path names in pglob->gl_pathv. The
first pointer after the last path name is a NULL pointer.
It is the caller's responsibility to allocate space for the structure
pointed to by pglob. glob() allocates other space as needed,
including the memory pointed to by gl_pathv. globfree() frees any
space associated with pglob from a previous call to glob().
The flags argument is used to control the behavior of glob(). The
value of flags is the bit-wise inclusive OR of the following constants
defined in :
GLOB_NOESCAPE Disable backslash escaping.
GLOB_ERR Causes glob() to return when it first
encounters a directory that it cannot open or
read. Ordinarily, glob() continues to find
matches.
GLOB_MARK Each path name that matches pattern and is a
directory, has a / appended.
Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996
glob(3C) glob(3C)
GLOB_NOSORT Ordinarily, glob() sorts the matching path
names according to the currently active
collation sequence as defined by the
LC_COLLATE category. When this flag is used,
the order of path names returned is
unspecified.
GLOB_NOCHECK If pattern does not match any path name,
glob() returns a list consisting of only
pattern, and the number of matched path names
is 1.
GLOB_DOOFFS Make use of pglob->gl_offs. If this flag is
set, pglob->gl_offs is used to specify how
many NULL pointers to add to the beginning of
pglob->gl_pathv. In other words,
pglob->gl_pathv points to pglob->gl_offs NULL
pointers, followed by pglob->gl_pathc path
name pointers, followed by a NULL pointer.
GLOB_APPEND Append path names generated to the ones from
a previous call to glob().
The GLOB_APPEND flag can be used to append a new set of path
names to those found in a previous call to glob(). The following
rules apply when two or more calls to glob() are made with the
same value of pglob and without intervening calls to globfree():
o The first call must not set GLOB_APPEND. All subsequent
calls must set it.
o All of the calls must set GLOB_DOOFFS, or all must not
set it.
o After the second call, pglob->gl_pathv points to a list
containing the following:
o Zero or more NULL pointers, as specified by
GOB_DOOFFS and pglob->gl_offs.
o Pointers to the path names that were in the
pglob->gl_pathv list before the call, in the same
order as before.
o Pointers to the new path names generated by the
second call, in the specified order.
o The count returned in pglob->gl_pathc will be the total
number of path names from the two calls.
Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996
glob(3C) glob(3C)
o The application can change any of the fields after a call
to glob(). If it does, it must reset them to the
original value before a subsequent call, using the same
pglob value, to globfree() or glob() with the GLOB_APPEND
flag.
If, during the search, a directory is encountered that cannot be
opened or read and errfunc is not NULL, glob() calls (*errfunc)() with
two arguments:
o A pointer to the path that failed.
o The value of errno from the failure.
If errfunc is called and returns nonzero, or if the GLOB_ERR flag is
set in flags, glob() stops the scan and returns GLOB_ABORTED after
setting gl_pathc and gl_pathv in pglob to reflect the paths already
scanned. If GLOB_ERR is not set and either errfunc is NULL or
(*errfunc)() returns zero, the error is ignored.
Pattern Matching Notation
The form of the patterns is the Pattern Matching Notation as qualified
for Filename Expansion (see regexp(5)) with the following exceptions:
o Tilde (~) expansion is not performed.
o Variable expansion is not performed.
EXTERNAL INFLUENCES
Locale
The LC_COLLATE category determines the collating sequence used in
compiling and executing regular expressions, and also the order of the
returned paths if GLOB_NOSORT is not selected.
The LC_CTYPE category determines the interpretation of text as single
byte and/or multibyte characters, and determines which characters are
matched by character class expressions in regular expressions.
International Code Set Support
Single byte and multibyte character code sets are supported.
RETURN VALUE
If glob() terminates due to an error, it returns one of the following
constants (defined in ); otherwise, it returns zero.
GLOB_NOSPACE An attempt to allocate memory failed.
GLOB_ABORTED The scan was stopped because GLOB_ERR was set
or (*errfunc)() returned nonzero.
Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996
glob(3C) glob(3C)
GLOB_NOMATCH The pattern does not match any existing path
name, and GLOB_NOCHECK was not set in flags.
In any case, the argument pglob->gl_pathc returns the number of
matched path names and the argument pglob->gl_pathv contains a pointer
to a null-terminated list of matched and sorted path names.
However, if pglob->gl_pathc is zero, the content of pglob->gl_pathv is
undefined.
If the pattern argument passed to glob() is badly constructed, glob()
returns zero and sets gl_pathc to zero unless GLOB_NOCHECK was set, in
which case pattern is returned and gl_pathc is set to 1.
WARNINGS
GLOB_APPEND must not be set in an initial call to glob().
AUTHOR
glob() and globfree() were developed by OSF and HP.
SEE ALSO
sh(1), fnmatch(3C), regexp(5).
STANDARDS CONFORMANCE
glob(): XPG4, POSIX.2
globfree(): XPG4, POSIX.2
Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996