FTW(S) UNIX System V FTW(S)
Name
ftw - walk a file tree
Syntax
#include <ftw.h>
int ftw (path, fn, depth)
char *path;
int (*fn) ( );
int depth;
Description
The ftw function 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(S)) 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.
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
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(S), malloc(S)
Notes
Because ftw is recursive, it is possible for it to terminate
with a memory fault when applied to very deep file
structures.
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
interrupts is to store the fact that an interrupt has
occurred, and arrange to have fn return a nonzero value at
its next invocation.
Standards Conformance
ftw is conformant with:
AT&T SVID Issue 2, Select Code 307-127;
and The X/Open Portability Guide II of January 1987.
(printed 6/20/89)