FTW(3) Library Functions Manual FTW(3)
ftw - walk a file tree
int ftw(path, fn, depth)
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(2V)) 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 pro-
cessed. 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
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.
Because ftw() is recursive, it is possible for it to terminate 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(3V) 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.
22 November 1987 FTW(3)