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.