ftw(), ftw64()

recursively descends a directory hierarchy 

Function

SYNOPSIS

#include <ftw.h>

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

int ftw64(const char *path, int (*fn)(const char *, const struct stat64 *, int), int ndirs);

DESCRIPTION

The ftw() function recursively descends the directory hierarchy rooted at the specified path. For each object in the hierarchy, ftw() calls the specified function, 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 flag. Possible values for the flag are:

FTW_D 

For a directory.

FTW_DNR 

For a directory that cannot be read.

FTW_F 

For a file.

FTW_NS 

For an object on which stat() could not be successfully executed.

If the flag is FTW_DNR, descendants of the directory are not be processed. If the flag is FTW_NS, the stat structure contains undefined values. An example of an object that would cause FTW_NS to be passed to the specified function 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 of the tree.

The tree traversal continues until the tree is exhausted, the user-supplied function returns a non-zero value, or some error, other than EACCES, is detected within ftw().

The ftw64() function is identical to the ftw() function except that it can work with disk files that are larger than 2 gigabyte. The ftw64() function is a part of the large file extensions.

PARAMETERS

path 

Specifies the root of the directory hierarchy to be traversed.

fn 

Is the function to be called for each element of the tree.

ndirs 

Specifies the maximum number of directory streams or file descriptors (or both) that are available for use by ftw() while traversing the tree. This should be in the range of [1, OPEN_MAX].

RETURN VALUES

On success, ftw() and ftw64() return 0. If the specified function returns a non-zero value, ftw() or ftw64() stops its tree traversal and returns whatever value was returned by the function. If ftw() or ftw64() detects an error, it returns -1 and sets errno to one of the following value:

EACCES 

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

EINVAL 

The value specified for ndirs is invalid.

ENAMETOOLONG 

The length of path exceeds PATH_MAX, or a path name component is longer than NAME_MAX, or either condition holds for a path name generated during the tree traversal.

ENOENT 

path points to an empty string or to the name of a file that does not exist.

ENOMEM 

Insufficient memory is available to complete the request.

ENOTDIR 

A component of the path name prefix is not a directory.

The ftw() function may also return errno values specified for stat(), opendir(), or readdir(). In addition, if the user specified function encounters system errors, errno may be set accordingly.

CONFORMANCE

UNIX 98.

ftw64(): Large File Specification, revision 1.5.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

None.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
nftw(), opendir(), readdir(), stat()

Miscellaneous:
lf64, struct stat

PTC MKS Toolkit 10.5 Documentation Build 40.