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  matching
     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 direc-
          tory does not have read permission, for example),

     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 contains
          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  ter-
     minate after the call to errfunc.


     Upon successful return, pglob->gl_pathc contains the  number
     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 possi-
     ble 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), read-
     dir(3), wordexp(3), glob(7)