ftw(3)                              CLIX                              ftw(3)



  NAME

    ftw - Walks a file tree

  LIBRARY

    libc.a

  SYNOPSIS

    #include <ftw.h>

    int ftw(
      char *path ,
      int (*fn)() ,
      int depth );

  PARAMETERS

    path    A pointer to a pathname.

    fn      A pointer to a function returning an integer.

    depth   An integer representing the number of file descriptors in the path
            descended.

  DESCRIPTION

    The ftw() function recursively descends the directory hierarchy rooted in
    path.  For each object in the hierarchy, ftw() calls (*fn)(), passing it a
    pointer to a null-terminated character string containing the name of the
    object, a pointer to a stat() stat()] containing information about the
    object, and an integer.  Possible values of the integer, defined in the
    <ftw.h> header file, are FTW_F for a file, FTW_D for a directory, FTW_DNR
    for a directory that cannot be read, and FTW_NS for an object for which
    stat() could not successfully be executed.  If the integer is FTW_DNR,
    descendants of that directory are processed.  If the integer is FTW_NS,
    the stat() structure contains garbage.  An example of an object causing
    FTW_NS to be passed to (*fn)() is a file in a directory with read but
    without execute (search) permission.

    The ftw() function visits a directory before visiting any of its
    descendants.

    The ftw() function uses one file descriptor for each level in the tree.
    The depth argument limits the number of file descriptors so used.  If
    depth is zero or negative, the effect is the same as if it were 1.  The
    value of depth must not be greater than the number of file descriptors
    currently available for use.   The ftw() function runs faster if depth is
    at least as large as the number of levels in the tree.




  2/94 - Intergraph Corporation                                              1

  ftw(3)                              CLIX                              ftw(3)



  EXAMPLES

    #include <stdio.h>
    #include <sys/types.h>
    #include <sys/stat.h>

    int myfunc(path,statbuf,ftype)
    char *path;
    struct stat *statbuf;
    int ftype;
    {
          printf("current file == %s\n",path);
          return 0;
    }

    void main (argc,argv)
    int argc;
    char **argv;
    {
          if(argc==2)
               printf("result of ftw (%s, myfunc,) ==%d\n",
                      argv[1], ftw(argv[1], myfunc, 0));
    }


  NOTES

    The ftw() uses malloc() to allocate dynamic storage during its operation.
    If ftw() is forcibly terminated, such as by longjmp() being executed by
    (*fn)() or an interrupt function, ftw() will not have a chance to free
    that storage, so it remains permanently allocated.  A safe way to handle
    interrupts is to store the fact that an interrupt has occurred, and
    arrange to have (*fn)() return a nonzero value at its next invocation.

  CAUTIONS

    Because ftw() is recursive, it is possible for it to terminate with a
    memory fault when applied to very deep file structures.

  RETURN VALUES

    The tree traversal continues until the tree is exhausted, an invocation of
    (*fn)() returns a nonzero value, or some error is detected within ftw()
    (such as an I/O error).  If the tree is exhausted, ftw() returns zero.  If
    (*fn)() returns a nonzero value, ftw() stops its tree traversal and
    returns whatever value was returned by (*fn)().

  ERRORS

    If ftw() detects an error, it returns -1 and sets the error type in errno.




  2                                              Intergraph Corporation - 2/94

  ftw(3)                              CLIX                              ftw(3)



  RELATED INFORMATION

    Functions:  stat(2), malloc(3)



















































  2/94 - Intergraph Corporation                                              3