FTW(3C)
NAME
ftw, ftwh − walk a file tree
SYNOPSIS
#include <ftw.h>
int ftw (path, fn, depth)
char *path;
int (*fn) ( );
int depth;
int ftwh (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. 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.
Ftwh performs the same function as ftw but ftwh also traverses hidden directories (context dependent files, see cdf(4)).
ERRORS
ftw() will fail if any of the following occurs:
[EACCES] Search permission is denied for any component of path.
[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the length of a component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect.
[ENOENT] Path points to the name of a file that does not exist, or points to an empty string.
[ENOTDIR] A component of path is not a directory.
ftw() may fail if:
[EINVAL] The value of the depth argument is invalid.
In addition, if the function pointed to by fn encounters system errors, errno may be set accordingly.
WARNINGS
Because ftw is recursive, it is possible for it to terminate with a memory fault when applied to very deep file structures.
It can be made to run faster and use less storage on deep structures at the cost of considerable complexity.
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.
AUTHOR
Ftw was developed by AT&T. Ftwh was developed by HP.
SEE ALSO
STANDARDS CONFORMANCE
ftw: SVID2, XPG2, XPG3
Hewlett-Packard Company — HP-UX Release 7.0: Sept 1989