Returns a list of existing files for a user supplied pathname
(with optional wildcards).
This function is supported on OpenVMS Integrity servers and
Alpha only.
Format
#include <glob.h>
int glob (const char *pattern, int flags, int (*errfunc)(const
char *epath, int eerrno), glob_t *pglob);
1 – Function Variants
The glob function has variants named _glob32 and _glob64 for use
with 32-bit and 64-bit pointer sizes, respectively.
2 – Arguments
pattern
The pattern string to match with accessible files and pathnames.
This pattern can have wildcards.
flags
Controls the customizable behavior of the glob function.
errfunc
An optional function that, if specified, is called when the glob
function detects an error condition, or if not specified, is
NULL.
epath
First argument of the optional errfunc function, epath is the
pathname that failed because a directory could not be opened or
read.
eerrno
Second argument of the optional errfunc function, eerrno is the
errno value from a failure specified by the epath argument as set
by the opendir, readdir, or stat functions.
pglob
Pointer to a glob_t structure that returns the matching
accessible existing filenames. The structure is allocated by the
caller. The array of structures containing the located filenames
that match the pattern argument are stored by the glob function
into the structure. The last entry is a NULL pointer.
The structure type glob_t is defined in the <glob.h> header file
and includes at least the following members:
size_t gl_pathc //Count of paths matched by pattern.
char ** gl_pathv //Pointer to a list of matched pathnames.
size_t gl_offs //Slots to reserve at the beginning of gl_pathv.
3 – Description
The glob function constructs a list of accessible files that
match the pattern argument.
The glob function operates in one of two modes: UNIX mode or
OpenVMS mode.
You can select UNIX mode explicitly by enabling the feature
logical DECC$GLOB_UNIX_STYLE, which is disabled by default.
The glob function defaults to OpenVMS mode unless one of the
following conditions is met (in which case glob uses UNIX mode):
o The DECC$GLOB_UNIX_STYLE is enabled.
o The DECC$FILENAME_UNIX_ONLY feature logical is enabled.
o The glob function checks the specified pattern for pathname
indications, such as directory delimiters, and determines it
to be a UNIX style pathname.
OpenVMS mode
This mode allows an OpenVMS programmer to give an OpenVMS style
pattern to the glob function and get expected OpenVMS style
output. The OpenVMS style pattern is what a user would expect
from DCL commands or as input to the SYS$PARSE and SYS$SEARCH
system routines.
In this mode, you can use any of the expected OpenVMS wildcards
(see the OpenVMS documentation for additional information).
OpenVMS mode does not support the UNIX wildcard ?, or [] pattern
matching. OpenVMS users expect [] to be available as directory
delimiters.
Some additional behavior differences between OpenVMS mode and
UNIX mode:
o OpenVMS mode outputs full file specifications, not relative
ones, as in UNIX mode.
o The GLOB_MARK flag is ignored in OpenVMS mode because it
is not meaningful to append a slash (/) to a directory on
OpenVMS.
For example:
Sample pattern input Sample output
[.SUBDIR1]A.TXT DEV:[DIR.SUBDIR1]A.TXT;1
[.SUB*]%.* DEV:[DIR.SUBDIR1]A.TXT;1
UNIX mode
You can enable this mode explicitly with:
$ DEFINE DECC$GLOB_UNIX_STYLE ENABLE
UNIX mode is also enabled if the DECC$FILENAME_UNIX_ONLY feature
logical is set, or if the glob function determines that the
specified pattern looks like a UNIX style pathname.
In UNIX mode, the glob function follows the X/Open specification
where possible.
For example:
Sample pattern input Sample output
./a/b/c ./a/b/c
./?/b/* ./a/b/c
[a-c] c
Standard Description
The glob function matches all accessible pathnames against this
pattern and develops a list of all pathnames that match. To
have access to a pathname, the glob function requires search
permission on every component of a pathname except the last, and
read permission on each directory of any filename component of
the pattern argument.
The glob function stores the number of matched pathnames and a
pointer to a list of pointers to pathnames in the pglob argument.
The pathnames are sorted, based on the setting of the LC_COLLATE
category in the current locale. The first pointer after the last
pathname is NULL. If the pattern does not match any pathnames,
the returned number of matched pathnames is 0.
It is the caller's responsibility to create the structure pointed
to by the pglob argument. The glob function allocates other space
as needed. The globfree function frees any space associated with
the pglob argument as a result of a previous call to the glob
function.
The flags argument is used to control the behavior of the glob
function. The flags value is the bitwise inclusive OR (|) of any
of the following constants, which are defined in the <glob.h>
header file:
GLOB_APPEND Appends pathnames located with this call to any
pathnames previously located.
GLOB_DOOFFS Uses the gl_offs structure to specify the number
of NULL pointers to add to the beginning of the gl_
pathv component of the pglob argument.
GLOB_ERR Causes the glob function to return when it
encounters a directory that it cannot open or
read. If the GLOB_ERR flag is not set, the glob
function continues to find matches if it encounters
a directory that it cannot open or read.
GLOB_MARK Specifies that each pathname that is a directory
should have a slash (/) appended. GLOB_MARK is
ignored in OpenVMS mode because it is not meaningful
to append a slash to a directory on OpenVMS systems.
GLOB_ If the pattern argument does not match any pathname,
NOCHECK then the glob function returns a list consisting
only of the pattern argument, and the number of
matched pathnames is 1.
GLOB_ If the GLOB_NOESCAPE flag is set, a backslash (\)
NOESCAPE cannot be used to escape metacharacters.
The GLOB_APPEND flag can be used to append a new set of pathnames
to those found in a previous call to the glob function. The
following rules apply when two or more calls to the glob function
are made with the same value of the pglob argument, and without
intervening calls to the globfree function:
o If the application sets the GLOB_DOOFFS flag in the first call
to the glob function, then it is also set in the second call,
and the value of the gl_offs field of the pglob argument is
not modified between the calls.
o If the application did not set the GLOB_DOOFFS flag in the
first call to the glob function, then it is not set in the
second call.
o After the second call, pglob->gl_pathv points to a list
containing the following:
- Zero or more NULLs, as specified by the GLOB_DOOFFS flag
and pglob->gl_offs.
- Pointers to the pathnames that were in the pglob->gl_pathv
list before the call, in the same order as after the first
call to the glob function.
- Pointers to the new pathnames generated by the second call,
in the specified order.
o The count returned in the pglob->gl_offs argument is the total
number of pathnames from the two calls.
o The application should not modify the pglob->gl_pathc or
pglob->gl_pathv fields between the two calls.
On successful completion, the glob function returns a value of 0
(zero). The pglob->gl_pathc field returns the number of matched
pathnames and the pglob->gl_pathv field contains a pointer to
a NULL-terminated list of matched and sorted pathnames. If the
number of matched pathnames in the pglob->gl_pathc argument is 0
(zero), the pointer in the pglob->gl_pathv argument is undefined.
If the glob function terminates because of an error, the function
returns one of the nonzero constants GLOB_ABORTED, GLOB_NOMATCH,
or GLOB_NOSPACE, defined in the <glob.h> header file. In this
case, the pglob argument values are still set as defined above.
If, during the search, a directory is encountered that cannot
be opened or read and the errfunc argument value is not NULL,
the glob function calls errfunc with the two arguments epath and
eerno:
epath-The pathname that failed because a directory could not
be opened or read.
eerno-The errno value from a failure specified by the epath
argument as set by the opendir, readdir, or stat functions.
If errfunc is called and returns nonzero, or if the GLOB_ERR flag
is set in flags, the glob function stops the scan and returns
GLOB_ABORTED after setting the pglob argument to reflect the
pathnames already scanned. If GLOB_ERR is not set and either
errfunc is NULL or errfunc returns zero, the error is ignored.
No errno values are returned.
See also globfree, readdir, and stat.
4 – Return Values
0 Successful completion.
GLOB_ABORTED The scan was stopped because GLOB_ERROR was
set or errfunc returned a nonzero value.
GLOB_NOMATCH The pattern does not match any existing
pathname, and GLOB_NOCHECK was not set in
flags.
GLOB_NOSPACE An attempt to allocate memory failed.