FTW(3C) DOMAIN/IX Reference Manual (SYS5) FTW(3C)
NAME
ftw - walk a file tree
USAGE
#include <ftw.h>
int ftw (path, fn, depth)
char *path;
int (*fn) ( );
int depth;
DESCRIPTION
Ftw descends the directory hierarchy rooted in path recur-
sively. For each object in the hierarchy, ftw calls fn,
passing it a pointer to a null-terminated character string
that contains the name of the object, a pointer to a stat
structure (see stat(2)) that contains information about the
object, and an integer. Possible values of the integer, as
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 that stat could not
operate on. 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 useless information. One
example of an object that would cause FTW_NS to be passed to
fn is a file in a directory that has read but no execute
(search) permission.
Ftw enters a directory before entering any of its descen-
dants.
The search continues until the tree is exhausted, until an
invocation of fn returns a nonzero value, or until 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 the descent 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.
NOTES
Because ftw is recursive, it can terminate with a memory
fault, when it is applied to very deep file structures.
Printed 5/10/85 FTW-1
FTW(3C) DOMAIN/IX Reference Manual (SYS5) FTW(3C)
Ftw uses malloc(3C) to allocate dynamic storage during its
operation. If ftw is forcibly terminated, such as by fn
executing longjmp, or by an interrupt routine, ftw does not
have a chance to free that storage, and it will remain per-
manently allocated. A safe way to handle interrupts is to
store the fact that an interrupt has occurred, and arrange
to have fn return a non-zero value at its next invocation.
RELATED INFORMATION
stat(2), malloc(3C).
FTW-2 Printed 5/10/85