FTW(3C)                              SysV                              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 successfully be executed.  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 FTW_NS to be passed to fn would be a file
     in a directory with read but without 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 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.  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 will run 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 with a
     memory fault when applied to very deep file structures.

CAVEAT
     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 will not have a chance to free that storage, so it
     will remain 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.