FTW(3C) (C Programming Language Utilities) FTW(3C)
NAME
ftw - walk 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 null-terminated 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
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.
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.
Page 1 May 1989
FTW(3C) (C Programming Language Utilities) FTW(3C)
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(2), malloc(3C).
BUGS
Because ftw is recursive, it is possible for it to terminate
with a memory fault when applied to very deep file
structures.
CAVEAT
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
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.
Page 2 May 1989