ftw(3)
_________________________________________________________________
ftw Subroutine
walk 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 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 that is defined in the <ftw.h>
header file are as follows:
FTW_F
for a file
FTW_D
for a directory
FTW_DNR
for a directory that cannot be read
FTW_NS
for an object that stat could not successfully be executed
for.
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 "walk" 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
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
ftw(3)
returns zero. If fn returns a nonzero value, ftw stops 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.
SEE ALSO
stat(2), malloc(3C).
BUGS
Because ftw is recursive, it can terminate with a memory fault
when applied to very deep file structures.
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.
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)