GLOB(3)             Linux Programmer's Manual             GLOB(3)

NAME
       glob,  globfree  - find pathnames matching a pattern, free
       memory from glob()

SYNOPSIS
       #include <glob.h>

       int glob(const char *pattern, int flags,
                int errfunc(const char * epath, int eerrno),
                glob_t *pglob);
       void globfree(glob_t *pglob);

DESCRIPTION
       The glob() function searches for all the pathnames  match-
       ing  pattern according to the rules used by the shell (see
       glob(7)).  No tilde expansion or parameter substitution is
       done; if you want these, use wordexp(3).

       The  globfree()  function  frees the dynamically allocated
       storage from an earlier call to glob().

       The results of a glob() call are stored in  the  structure
       pointed  to  by pglob, which is a glob_t which is declared
       in <glob.h> and includes the following elements defined by
       POSIX.2 (more may be present as a GNU extension):

          typedef struct
          {
                  int gl_pathc;       /* Count of paths matched so far  */
                  char **gl_pathv;    /* List of matched pathnames.  */
                  int gl_offs;        /* Slots to reserve in `gl_pathv'.  */
          } glob_t;

       Results are stored in dynamically allocated storage.

       The  parameter  flags  is made up of bitwise OR of zero or
       more the following symbolic constants, which modify the of
       behaviour of glob():

       GLOB_ERR
              which  means  to  return upon read error (because a
              directory does not have read permission, for  exam-
              ple),

       GLOB_MARK
              which  means  to  append a slash to each path which
              corresponds to a directory,

       GLOB_NOSORT
              which means don't sort the returned pathnames (they
              are by default),

       GLOB_DOOFS
              which  means  that  pglob->gl_offs  slots  will  be
              reserved at the beginning of the list of strings in
              pglob->pathv,

       GLOB_NOCHECK
              which  means that, if no pattern matches, to return
              the original pattern,

       GLOB_APPEND
              which means to append to the results of a  previous
              call.  Do not set this flag on the first invocation
              of glob().

       GLOB_NOESCAPE
              which means that meta characters cannot  be  quoted
              by backslashes.

       The  flags  may  also include some of the following, which
       are GNU extensions and not defined by POSIX.2:

       GLOB_PERIOD
              which means that a leading period can be matched by
              meta characters,

       GLOB_ALTDIRFUNC
              which     means    that    alternative    functions
              pglob->gl_closedir,              pglob->gl_readdir,
              pglob->gl_opendir,       pglob->gl_lstat,       and
              pglob->gl_stat are  used  for  file  system  access
              instead of the normal library functions,

       GLOB_BRACE
              which  means  that  csh(1)  style  brace expresions
              {a,b} are expanded,

       GLOB_NOMAGIC
              which means that the pattern is returned if it con-
              tains no metacharacters,

       GLOB_TILDE
              which  means  that  tilde expansion is carried out,
              and

       GLOB_ONLYDIR
              which means that only directories are matched.

       If errfunc is not NULL, it will be called in  case  of  an
       error  with  the  arguments  epath,  a pointer to the path
       which failed, and eerrno, the value of errno  as  returned
       from  one of the calls to opendir(), readdir(), or stat().
       If errfunc returns non-zero, or if GLOB_ERR is set, glob()
       will terminate after the call to errfunc.

       Upon  successful return, pglob->gl_pathc contains the num-
       ber of matched pathnames and pglob->gl_pathv a pointer  to
       the  list  of  matched pathnames.  The first pointer after
       the last pathname is NULL.

       It is possible to call  glob()  several  times.   In  that
       case,  the  GLOB_APPEND flag has to be set in flags on the
       second and later invocations.

       As a GNU extension, pglob->gl_flags is set  to  the  flags
       specified,  ored  with  GLOB_MAGCHAR if any metacharacters
       were found.

RETURN VALUES
       On successful completion, glob() returns zero.  Other pos-
       sible returns are:

       GLOB_NOSPACE
              for running out of memory,

       GLOB_ABORTED
              for a read error, and

       GLOB_NOMATCH
              for no found matches.

EXAMPLES
       One  example of use is the following code, which simulates
       typing ls -l *.c ../*.c in the shell.

          glob_t globbuf;

          globbuf.gl_offs = 2;
          glob("*.c", GLOB_DOOFS, NULL, &globbuf);
          glob("../*.c", GLOB_DOOFS | GLOB_APPEND, NULL, &globbuf);
          globbuf.gl_pathv[0] = "ls";
          globbuf.gl_pathv[1] = "-l";
          execvp("ls", &globbuf.gl_pathv[0]);

CONFORMING TO
       POSIX.2

BUGS
       The glob() function may fail due to failure of  underlying
       function calls, such as malloc() or opendir().  These will
       store their error code in errno.

       The structure elements  gl_pathc  and  gl_offs  should  be
       declared as size_t, according to POSIX.2, but are declared
       as int.

SEE ALSO
       ls(1), sh(1),  stat(2),  exec(3),  malloc(3),  opendir(3),
       readdir(3), wordexp(3), glob(7)

GNU                        11 May 1998                          1