ftw(3C)                                                   ftw(3C)



     NAME
          ftw - walk a file tree

     SYNOPSIS
          #include <ftw.h>

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

     DESCRIPTION
          ftw 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
          structure (see stat(2)) 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
          be executed successfully.  If the integer is FTW_DNR,
          descendants of that directory will not be processed.  If the
          integer is FTW_NS, the stat structure will contain garbage.
          An example of an object that would cause FTWNS to be passed
          to fn is a file in a directory with read permission but not
          execute (search) permission.

          ftw visits a directory before visiting any of its
          descendants.

          The tree traversal continues until the tree is exhausted, an
          invocation of fn returns a nonzero value, or an 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.  If ftw detects an error, it returns -1, and
          sets the error type in errno.

          Ftw 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.  depth must not be greater than the number
          of file descriptors currently available for use.  ftw runs
          more quickly if depth is at least as large as the number of
          levels in the tree.

     SEE ALSO
          stat(2), malloc(3C).

     BUGS
          Because ftw is recursive, it is possible for it to terminate



     Page 1                                        (last mod. 1/14/87)

     ftw(3C)                                                   ftw(3C)



          with a memory fault when applied to very deep file
          structures.
          ftw could be made to run faster and use less storage on deep
          structures at the cost of considerable complexity.
          ftw uses malloc(3C) to allocate dynamic storage during its
          operation.  If ftw is forcibly terminated, such as by
          longjmp being executed by fn or an interrupt routine, ftw
          does 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.











































     Page 2                                        (last mod. 1/14/87)