


      FTW(3C)                     (UNIX 5.0)                    FTW(3C)



      NAME
           ftw - walk a file tree

      SYNTAX
           #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)) containg 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



      Page 1                                         (73 A2 02MTA REV1)






      FTW(3C)                     (UNIX 5.0)                    FTW(3C)



           with a memory fault when applied to very deep file
           structures.
           It 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
           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.











































      Page 2                                         (73 A2 02MTA REV1)



