FTW(3C)              INTERACTIVE UNIX System              FTW(3C)



          NAME
               ftw - walk a file tree

          SYNOPSIS
               #include <ftw.h>

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

          DESCRIPTION
               The ftw function recursively descends the directory hierar-
               chy rooted in path.  For each object in the hierarchy, ftw
               calls fn, passing it a pointer to a null-terminated charac-
               ter 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, des-
               cendants 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.

               The ftw function 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.

               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.  Depth must not be
               greater than the number of file descriptors currently avail-
               able 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


          Rev. C Software Development Set                            Page 1

          FTW(3C)              INTERACTIVE UNIX System              FTW(3C)



               structures.

          CAVEAT
               The ftw function 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 routine,
               ftw will not have a chance to free that storage, so it will
               remain permanently allocated.  A safe way to handle inter-
               rupts is to store the fact that an interrupt has occurred,
               and arrange to have fn return a nonzero value at its next
               invocation.












































          Rev. C Software Development Set                            Page 2