NAME

ftw - traverse (walk) a file tree

 SYNOPSIS

#include <ftw.h>

int ftw(const char *path, int (*fn)(const char *,
    const struct stat *ptr, int flag), int ndirs);

 DESCRIPTION

The ftw() function recursively descends the directory hierarchy rooted in path. For each object in the hierarchy, ftw() calls the function pointed to by fn, passing it a pointer to a null-terminated character string containing the name of the object, a pointer to a stat structure containing information about the object, and an integer. Possible values of the integer, defined in the <ftw.h> header, are:

FTW_D

For a directory.

FTW_DNR

For a directory that cannot be read.

FTW_F

For a file.

FTW_SL

For a symbolic link (but see also FTW_NS below).

FTW_NS

For an object other than a symbolic link on which stat() could not successfully be executed. If the object is a symbolic link and stat() failed, it is unspecified whether ftw() passes FTW_SL or FTW_NS to the user-supplied function.

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 undefined values. An example of an object that would cause FTW_NS to be passed to the function pointed to by 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 ftw() function uses at most one file descriptor for each level in the tree.

The argument ndirs should be in the range of 1 to {OPEN_MAX}.

The tree traversal continues until the tree is exhausted, an invocation of fn returns a non-zero value, or some error, other than [EACCES], is detected within ftw().

The ndirs argument specifies the maximum number of directory streams or file descriptors or both available for use by ftw() while traversing the tree. When ftw() returns it closes any directory streams and file descriptors it uses not counting any opened by the application-supplied fn() function.

 RETURN VALUE

If the tree is exhausted, ftw() returns 0. If the function pointed to by fn returns a non-zero value, ftw() stops its tree traversal and returns whatever value was returned by the function pointed to by fn(). If ftw() detects an error, it returns -1 and sets errno to indicate the error.

If ftw() encounters an error other than [EACCES] (see FTW_DNR and FTW_NS above), it returns -1 and errno is set to indicate the error. The external variable errno may contain any error value that is possible when a directory is opened or when one of the stat functions is executed on a directory or file.

 ERRORS

The ftw() function will fail if:

[EACCES]

Search permission is denied for any component of path or read permission is denied for path.

[ELOOP]

Too many symbolic links were encountered.

[ENAMETOOLONG]

The length of the path exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX}.

[ENOENT]

A component of path does not name an existing file or path is an empty string.

[ENOTDIR]

A component of path is not a directory.

The ftw() function may fail if:

[EINVAL]

The value of the ndirs argument is invalid.

[ENAMETOOLONG]

Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.

In addition, if the function pointed to by fn encounters system errors, errno may be set accordingly.

 EXAMPLES

None.

 APPLICATION USAGE

The ftw() may allocate dynamic storage during its operation. If ftw() is forcibly terminated, such as by longjmp() or siglongjmp() being executed by the function pointed to 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 the function pointed to by fn return a non-zero value at its next invocation.

 FUTURE DIRECTIONS

None.

 SEE ALSO

longjmp(), lstat(), malloc(), nftw(), opendir(), siglongjmp(), stat(), <ftw.h>, <sys/stat.h>.

DERIVATION

Derived from Issue 1 of the SVID.