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

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

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

              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

              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 glob().

              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:

              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 con-
              tains no metacharacters,

              which  means  that  tilde expansion is carried out,

              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.

       On successful completion, glob() returns zero.  Other pos-
       sible 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),
       readdir(3), wordexp(3), glob(7)

GNU                        11 May 1998                          1