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


     #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));


     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():

          which means to return upon read error (because a direc-
          tory does not have read permission, for example),

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

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

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

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

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

          which means that meta characters cannot  be  quoted  by

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

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

          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,

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

          which means that the pattern is returned if it contains
          no metacharacters,

          which means that tilde expansion is carried out, and

          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


     On successful completion, glob() returns zero.  Other possi-
     ble returns are:

          for running out of memory,

          for a read error, and

          for no found matches.


     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]);




     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.


     ls(1), sh(1), stat(2), exec(3), malloc(3), opendir(3), read-
     dir(3), wordexp(3), glob(7)