Copyright Digital Equipment Corp. All rights reserved.
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.