ftw(3C)                                                   ftw(3C)



NAME
     ftw - walks 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 nullterminated 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 FTW_NS 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.

STATUS MESSAGES AND VALUES
     The tree traversal continues until the tree is exhausted,
     and 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 0.  If fn returns a nonzero value,



January 1992                                                    1

ftw(3C)                                                   ftw(3C)



     ftw stops its tree traversal and returns whatever value was
     returned by fn.

     If ftw encounters an error other than EACCESS, it returns -1
     and errno is set to indicate the error.  The external
     variable errno may contain the error values that are
     possible when a directory is opened or when stat(2) is
     executed on a directory or file.

LIMITATIONS
     Because ftw is recursive, it is possible for it to terminate
     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.

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





























2                                                    January 1992