# glob

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           glob, globfree — generate pathnames matching a pattern
    


## SYNOPSIS



           #include <glob.h>
    
           int glob(const char *restrict _pattern_ , int _flags_ ,
               int(*_errfunc_)(const char *_epath_ , int _eerrno_),
               glob_t *restrict _pglob_);
           void globfree(glob_t *_pglob_);
    


## DESCRIPTION



           The _glob_() function is a pathname generator that shall implement
           the rules defined in the Shell and Utilities volume of
           POSIX.1‐2017, _Section 2.13_ , _Pattern Matching Notation_ , with
           optional support for rule 3 in the Shell and Utilities volume of
           POSIX.1‐2017, _Section 2.13.3_ , _Patterns Used for Filename_
           _Expansion_.
    
           The structure type **glob_t** is defined in _< glob.h>_ and includes at
           least the following members:
       ┌───────────────┬──────────────┬─────────────────────────────────────────┐
       │ **Member Type** │ **Member Name** │               **Description** │
       ├───────────────┼──────────────┼─────────────────────────────────────────┤
       │ **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_.                               │
       └───────────────┴──────────────┴─────────────────────────────────────────┘
    
           The argument _pattern_ is a pointer to a pathname pattern to be
           expanded. The _glob_() function shall match all accessible pathnames
           against this pattern and develop a list of all pathnames that
           match. In order to have access to a pathname, _glob_() requires
           search permission on every component of a path except the last,
           and read permission on each directory of any filename component of
           _pattern_ that contains any of the following special characters:
           **'*'** , **'?'** , and **'['**.
    
           The _glob_() function shall store the number of matched pathnames
           into _pglob_ ->_gl_pathc_ and a pointer to a list of pointers to
           pathnames into _pglob_ ->_gl_pathv_. The pathnames shall be in sort
           order as defined by the current setting of the _LC_COLLATE_
           category; see the Base Definitions volume of POSIX.1‐2017, _Section_
           _7.3.2_ , _LC_COLLATE_.  The first pointer after the last pathname
           shall be a null pointer. If the pattern does not match any
           pathnames, the returned number of matched paths is set to 0, and
           the contents of _pglob_ ->_gl_pathv_ are implementation-defined.
    
           It is the caller's responsibility to create the structure pointed
           to by _pglob_.  The _glob_() function shall allocate other space as
           needed, including the memory pointed to by _gl_pathv_.  The
           _globfree_() function shall free 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 a bitwise-inclusive OR of zero or more of the
           following constants, which are defined in _< glob.h>_:
    
           GLOB_APPEND   Append pathnames generated to the ones from a
                         previous call to _glob_().
    
           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_ shall point to
                         _pglob_ ->_gl_offs_ null pointers, followed by
                         _pglob_ ->_gl_pathc_ pathname pointers, followed by a
                         null pointer.
    
           GLOB_ERR      Cause _glob_() to return when it encounters a
                         directory that it cannot open or read.  Ordinarily,
                         _glob_() continues to find matches.
    
           GLOB_MARK     Each pathname that is a directory that matches
                         _pattern_ shall have a <slash> appended.
    
           GLOB_NOCHECK  Supports rule 3 in the Shell and Utilities volume of
                         POSIX.1‐2017, _Section 2.13.3_ , _Patterns Used for_
                         _Filename Expansion_.  If _pattern_ does not match any
                         pathname, then _glob_() shall return a list consisting
                         of only _pattern_ , and the number of matched pathnames
                         is 1.
    
           GLOB_NOESCAPE Disable backslash escaping.
    
           GLOB_NOSORT   Ordinarily, _glob_() sorts the matching pathnames
                         according to the current setting of the _LC_COLLATE_
                         category; see the Base Definitions volume of
                         POSIX.1‐2017, _Section 7.3.2_ , _LC_COLLATE_.  When this
                         flag is used, the order of pathnames returned is
                         unspecified.
    
           The GLOB_APPEND flag can be used to append a new set of pathnames
           to those found in a previous call to _glob_().  The following rules
           apply to applications when two or more calls to _glob_() are made
           with the same value of _pglob_ and without intervening calls to
           _globfree_():
    
            1. The first such call shall not set GLOB_APPEND. All subsequent
               calls shall set it.
    
            2. All the calls shall set GLOB_DOOFFS, or all shall not set it.
    
            3. After the second call, _pglob_ ->_gl_pathv_ points to a list
               containing the following:
    
                a. Zero or more null pointers, as specified by GLOB_DOOFFS
                   and _pglob_ ->_gl_offs_.
    
                b. Pointers to the pathnames that were in the _pglob_ ->_gl_pathv_
                   list before the call, in the same order as before.
    
                c. Pointers to the new pathnames generated by the second
                   call, in the specified order.
    
            4. The count returned in _pglob_ ->_gl_pathc_ shall be the total
               number of pathnames from the two calls.
    
            5. The application can change any of the fields after a call to
               _glob_().  If it does, the application shall 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 a null pointer, _glob_() calls
           _(_()*errfunc ) with two arguments:
    
            1. The _epath_ argument is a pointer to the path that failed.
    
            2. The _eerrno_ argument is the value of _errno_ from the failure, as
               set by _opendir_(), _readdir_(), or _stat_().  (Other values may be
               used to report other errors not explicitly documented for
               those functions.)
    
           If _(_()*errfunc ) is called and returns non-zero, or if the
           GLOB_ERR flag is set in _flags_ , _glob_() shall stop the scan and
           return 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 a null pointer or _(_()*errfunc ) returns 0, the
           error shall be ignored.
    
           The _glob_() function shall not fail because of large files.
    


## RETURN VALUE



           Upon successful completion, _glob_() shall return 0. The argument
           _pglob_ ->_gl_pathc_ shall return the number of matched pathnames and
           the argument _pglob_ ->_gl_pathv_ shall contain a pointer to a null-
           terminated list of matched and sorted pathnames. However, if
           _pglob_ ->_gl_pathc_ is 0, the content of _pglob_ ->_gl_pathv_ is undefined.
    
           The _globfree_() function shall not return a value.
    
           If _glob_() terminates due to an error, it shall return one of the
           non-zero constants defined in _< glob.h>_.  The arguments
           _pglob_ ->_gl_pathc_ and _pglob_ ->_gl_pathv_ are still set as defined
           above.
    


## ERRORS



           The _glob_() function shall fail and return the corresponding value
           if:
    
           GLOB_ABORTED  The scan was stopped because GLOB_ERR was set or
                         _(_()*errfunc ) returned non-zero.
    
           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.
    
           _The following sections are informative._
    


## EXAMPLES



           One use of the GLOB_DOOFFS flag is by applications that build an
           argument list for use with _execv_(), _execve_(), or _execvp_().
           Suppose, for example, that an application wants to do the
           equivalent of:
    
               ls -l *.c
    
           but for some reason:
    
               system("ls -l *.c")
    
           is not acceptable. The application could obtain approximately the
           same result using the sequence:
    
               globbuf.gl_offs = 2;
               glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
               globbuf.gl_pathv[0] = "ls";
               globbuf.gl_pathv[1] = "-l";
               execvp("ls", &globbuf.gl_pathv[0]);
    
           Using the same example:
    
               ls -l *.c *.h
    
           could be approximately simulated using GLOB_APPEND as follows:
    
               globbuf.gl_offs = 2;
               glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
               glob("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);
               ...
    


## APPLICATION USAGE



           This function is not provided for the purpose of enabling
           utilities to perform pathname expansion on their arguments, as
           this operation is performed by the shell, and utilities are
           explicitly not expected to redo this. Instead, it is provided for
           applications that need to do pathname expansion on strings
           obtained from other sources, such as a pattern typed by a user or
           read from a file.
    
           If a utility needs to see if a pathname matches a given pattern,
           it can use _fnmatch_().
    
           Note that _gl_pathc_ and _gl_pathv_ have meaning even if _glob_() fails.
           This allows _glob_() to report partial results in the event of an
           error. However, if _gl_pathc_ is 0, _gl_pathv_ is unspecified even if
           _glob_() did not return an error.
    
           The GLOB_NOCHECK option could be used when an application wants to
           expand a pathname if wildcards are specified, but wants to treat
           the pattern as just a string otherwise. The _sh_ utility might use
           this for option-arguments, for example.
    
           The new pathnames generated by a subsequent call with GLOB_APPEND
           are not sorted together with the previous pathnames. This mirrors
           the way that the shell handles pathname expansion when multiple
           expansions are done on a command line.
    
           Applications that need tilde and parameter expansion should use
           _wordexp_().
    


## RATIONALE



           It was claimed that the GLOB_DOOFFS flag is unnecessary because it
           could be simulated using:
    
               new = (char **)malloc((n + pglob->gl_pathc + 1)
                      * sizeof(char *));
               (void) memcpy(new+n, pglob->gl_pathv,
                      pglob->gl_pathc * sizeof(char *));
               (void) memset(new, 0, n * sizeof(char *));
               free(pglob->gl_pathv);
               pglob->gl_pathv = new;
    
           However, this assumes that the memory pointed to by _gl_pathv_ is a
           block that was separately created using _malloc_().  This is not
           necessarily the case. An application should make no assumptions
           about how the memory referenced by fields in _pglob_ was allocated.
           It might have been obtained from _malloc_() in a large chunk and
           then carved up within _glob_(), or it might have been created using
           a different memory allocator. It is not the intent of the standard
           developers to specify or imply how the memory used by _glob_() is
           managed.
    
           The GLOB_APPEND flag would be used when an application wants to
           expand several different patterns into a single list.
    


## FUTURE DIRECTIONS



           None.
    


* * *