FTW(S) XENIX System V FTW(S)
Name
ftw - Walks 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 routed in
path. For each object in the hierarchy, ftw calls fn,
passing it a pointer to a null-terminated character string.
This string contains the name of the object, a pointer to a
stat structure with information about the object, and an
integer. Possible values for the integer include 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 successfully executed. These values are
defined in the <ftw.h> header file. If the integer is
FTW_DNR, descendants of the directory will not be processed.
If the integer is FTW_NS, the stat structure will contain
meaningless information. For example, a file in a directory
with read but without execute permission could cause FTW_FN
to be passed to fn.
ftw visits a directory before visiting any of its
descendants. The file tree traversal continues until the
tree is exhausted, fn returns a nonzero value, or some error
is detected within ftw (for example, an I/O error). If the
file tree is exhausted, ftw returns zero. If fn returns a
nonzero value, ftw stops traversing the file tree and
returns the value 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.
depth limits the number of file descriptors. This argument
must not be greater than the number of file descriptors
currently available for use. Zero or negative values for
depth are interpreted as 1. 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 can terminate with a memory
fault when applied to very deep file structures.
Page 1 (printed 8/7/87)
FTW(S) XENIX System V FTW(S)ftw uses malloc(S) to allocate dynamic storage during its
operation. If ftw is forcibly terminated (for example, by
longjmp being executed by fn or by an interrupt routine),
ftw will not have a chance to free that storage, and it will
remain permanently allocated. A safe way to handle
interrupts is to store the fact that an interrupt has
occurred, and have fn return a nonzero value at its next
invocation.
Page 2 (printed 8/7/87)
