GLOB(3) BSD Library Functions Manual GLOB(3)

NAME
     gglloobb, gglloobbffrreeee - generate pathnames matching a pattern

LLIIBBRRAARRYY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##iinncclluuddee <>

     int
     gglloobb(const char *pattern, int flags, int (*errfunc)(const char *, int),
         globt *pglob);

     void
     gglloobbffrreeee(globt *pglob);

DESCRIPTION
     The gglloobb() function is a pathname generator that implements the rules for
     file name pattern matching used by the shell.

     The include file  defines the structure type globt, which con-
     tains at least the following fields:

     typedef struct {
             int glpathc;           /* count of total paths so far */
             int glmatchc;          /* count of paths matching pattern */
             int gloffs;            /* reserved at beginning of glpathv */
             int glflags;           /* returned flags */
             char **glpathv;        /* list of paths matching pattern */
     } globt;

     The argument pattern is a pointer to a pathname pattern to be expanded.
     The gglloobb() argument matches all accessible pathnames against the pattern
     and creates a list of the pathnames that match.  In order to have access
     to a pathname, gglloobb() requires search permission on every component of a
     path except the last and read permission on each directory of any file-
     name component of pattern that contains any of the special characters
     `*', `?' or `['.

     The gglloobb() argument stores the number of matched pathnames into the
     glpathc field, and a pointer to a list of pointers to pathnames into the
     glpathv field.  The first pointer after the last pathname is NULL.  If
     the pattern does not match any pathnames, the returned number of matched
     paths is set to zero.

     It is the caller's responsibility to create the structure pointed to by
     pglob.  The gglloobb() function allocates other space as needed, including
     the memory pointed to by glpathv.

     The argument flags is used to modify the behavior of gglloobb().  The value
     of flags is the bitwise inclusive OR of any of the following values
     defined in :

     GLOBAPPEND      Append pathnames generated to the ones from a previous
                      call (or calls) to gglloobb().  The value of glpathc will
                      be the total matches found by this call and the previous
                      call(s).  The pathnames are appended to, not merged with
                      the pathnames returned by the previous call(s).  Between
                      calls, the caller must not change the setting of the
                      GLOBDOOFFS flag, nor change the value of gloffs when
                      GLOBDOOFFS is set, nor (obviously) call gglloobbffrreeee() for
                      pglob.

     GLOBDOOFFS      Make use of the gloffs field.  If this flag is set,
                      gloffs is used to specify how many NULL pointers to
                      prepend to the beginning of the glpathv field.  In
                      other words, glpathv will point to gloffs NULL point-
                      ers, followed by glpathc pathname pointers, followed by
                      a NULL pointer.

     GLOBERR         Causes gglloobb() to return when it encounters a directory
                      that it cannot open or read.  Ordinarily, gglloobb() contin-
                      ues to find matches.

     GLOBMARK        Each pathname that is a directory that matches pattern
                      has a slash appended.

     GLOBNOCHECK     If pattern does not match any pathname, then gglloobb()
                      returns a list consisting of only pattern, with the num-
                      ber of total pathnames set to 1, and the number of
                      matched pathnames set to 0.  The effect of backslash
                      escaping is present in the pattern returned.

     GLOBNOESCAPE    By default, a backslash (`\') character is used to
                      escape the following character in the pattern, avoiding
                      any special interpretation of the character.  If
                      GLOBNOESCAPE is set, backslash escaping is disabled.

     GLOBNOSORT      By default, the pathnames are sorted in ascending ASCII
                      order; this flag prevents that sorting (speeding up
                      gglloobb()).

     The following values may also be included in flags, however, they are
     non-standard extensions to IEEE Std 1003.2 (``POSIX.2'').

     GLOBALTDIRFUNC  The following additional fields in the pglob structure
                      have been initialized with alternate functions for glob
                      to use to open, read, and close directories and to get
                      stat information on names found in those directories.

                      void *(*glopendir)(const char * name);
                      struct dirent *(*glreaddir)(void *);
                      void (*glclosedir)(void *);
                      int (*gllstat)(const char *name, struct stat *st);
                      int (*glstat)(const char *name, struct stat *st);

                      This extension is provided to allow programs such as
                      restore(8) to provide globbing from directories stored
                      on tape.

     GLOBBRACE       Pre-process the pattern string to expand `{pat,pat,...}'
                      strings like csh(1).  The pattern `{}' is left unex-
                      panded for historical reasons (and csh(1) does the same
                      thing to ease typing of find(1) patterns).

     GLOBMAGCHAR     Set by the gglloobb() function if the pattern included glob-
                      bing characters.  See the description of the usage of
                      the glmatchc structure member for more details.

     GLOBNOMAGIC     Is the same as GLOBNOCHECK but it only appends the
                      pattern if it does not contain any of the special char-
                      acters ``*'', ``?'' or ``[''.  GLOBNOMAGIC is provided
                      to simplify implementing the historic csh(1) globbing
                      behavior and should probably not be used anywhere else.

     GLOBTILDE       Expand patterns that start with `~' to user name home
                      directories.

     GLOBLIMIT       Limit the total number of returned pathnames to the
                      value provided in glmatchc (default ARGMAX).  This
                      option should be set for programs that can be coerced
                      into a denial of service attack via patterns that expand
                      to a very large number of matches, such as a long string
                      of `*/../*/..'.

     If, during the search, a directory is encountered that cannot be opened
     or read and errfunc is non-NULL, gglloobb() calls (*errfunc)(path, errno).
     This may be unintuitive: a pattern like `*/Makefile' will try to stat(2)
     `foo/Makefile' even if `foo' is not a directory, resulting in a call to
     errfunc.  The error routine can suppress this action by testing for
     ENOENT and ENOTDIR; however, the GLOBERR flag will still cause an imme-
     diate return when this happens.

     If errfunc returns non-zero, gglloobb() stops the scan and returns
     GLOBABORTED after setting glpathc and glpathv to reflect any paths
     already matched.  This also happens if an error is encountered and
     GLOBERR is set in flags, regardless of the return value of errfunc, if
     called.  If GLOBERR is not set and either errfunc is NULL or errfunc
     returns zero, the error is ignored.

     The gglloobbffrreeee() function frees any space associated with pglob from a pre-
     vious call(s) to gglloobb().

RETURN VALUES
     On successful completion, gglloobb() returns zero.  In addition the fields of
     pglob contain the values described below:

     glpathc      contains the total number of matched pathnames so far.
                   This includes other matches from previous invocations of
                   gglloobb() if GLOBAPPEND was specified.

     glmatchc     contains the number of matched pathnames in the current
                   invocation of gglloobb().

     glflags      contains a copy of the flags argument with the bit
                   GLOBMAGCHAR set if pattern contained any of the special
                   characters ``*'', ``?'' or ``['', cleared if not.

     glpathv      contains a pointer to a NULL-terminated list of matched
                   pathnames.  However, if glpathc is zero, the contents of
                   glpathv are undefined.

     If gglloobb() terminates due to an error, it sets errno and returns one of
     the following non-zero constants, which are defined in the include file
     :

     GLOBNOSPACE  An attempt to allocate memory failed, or if errno was 0
                   GLOBLIMIT was specified in the flags and pglob->glmatchc
                   or more patterns were matched.

     GLOBABORTED  The scan was stopped because an error was encountered and
                   either GLOBERR was set or (*errfunc)() returned non-zero.

     GLOBNOMATCH  The pattern did not match a pathname and GLOBNOCHECK was
                   not set.

     The arguments pglob->glpathc and pglob->glpathv are still set as speci-
     fied above.

EEXXAAMMPPLLEESS
     A rough equivalent of `ls -l *.c *.h' can be obtained with the following
     code:

           globt g;

           g.gloffs = 2;
           glob("*.c", GLOBDOOFFS, NULL, &g);
           glob("*.h", GLOBDOOFFS | GLOBAPPEND, NULL, &g);
           g.glpathv[0] = "ls";
           g.glpathv[1] = "-l";
           execvp("ls", g.glpathv);

SEE ALSO
     sh(1), fnmatch(3), regexp(3)

STANDARDS     The current implementation of the gglloobb() function does not conform to
     IEEE Std 1003.2 (``POSIX.2'').  Collating symbol expressions, equivalence
     class expressions and character class expressions are not supported.

     The flags GLOBALTDIRFUNC, GLOBBRACE, GLOBLIMIT, GLOBMAGCHAR,
     GLOBNOMAGIC, and GLOBTILDE, and the fields glmatchc and glflags are
     extensions to the POSIX standard and should not be used by applications
     striving for strict conformance.

HISTORY     The gglloobb() and gglloobbffrreeee() functions first appeared in 4.4BSD.

BUGS
     Patterns longer than MAXPATHLEN may cause unchecked errors.

     The gglloobb() argument may fail and set errno for any of the errors speci-
     fied for the library routines stat(2), closedir(3), opendir(3),
     readdir(3), malloc(3), and free(3).

BSD                            September 1, 2004                           BSD