ftw(S)

ftw -- walk a file tree

Syntax

cc . . . -lc

#include  <sys/stat.h>
#include  <ftw.h>

int ftw (path, fn, depth)
char *path;
int (*fn) ();
int depth;

Description

The ftw function 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(S)) containing information about the object, and an integer. Possible values of the integer, defined in the <ftw.h> header file, are:

FTW_F: file
FTW_D: directory
FTW_DNR: directory that cannot be read
FTW_NS: object for which stat could not successfully be executed

If the integer is FTW_DNR, descendants of that directory are not processed. If the integer is FTW_NS, the stat structure contains 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.

The ftw function 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 an 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 other than EACCES, it returns -1 and sets the error type in errno.

The ftw function uses one file descriptor for each level in the tree. The depth argument limits the number of file descriptors 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 runs faster if depth is at least as large as the number of levels in the tree.

Diagnostics

The ftw funcion will fail if:

[EACCES]: Search permission is denied for any component of pathname or read permission is denied for pathname
[ELOOP]: Too many symbolic links were encountered.
[ENAMETOOLONG]: The length of the pathname argument exceeds {PATH_MAX}.
[ENOENT]: A component of pathname does not name an existing directory or pathname is an empty string.
[ENOTDIR]: A component of pathname is not a directory.

The ftw funcion may fail if:

[EINVAL]: The value of ndirs argument is invalid.
[ENAMETOOLONG]: Pathname resolution of a symbolic link produced an intermediate result whos lenght exceeds {PATH_MAX}.

Notes

Because ftw is recursive, it can terminate with a memory fault when applied to very deep file structures.

The ftw function uses malloc to allocate dynamic storage during its operation. If ftw is forcibly terminated (for example, if fn or an interrupt routine executes longjmp), ftw does not have a chance to free that storage, so it remains 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.

Standards conformance

ftw is conformant with: