nftw(), nftw64() -- walk file tree

SYNOPSIS

#include <ftw.h>

int nftw(const char *path, int (*fn)(const char *, const struct stat *, int, struct FTW *), int depth, int flags);

int nftw64(const char *path, int (*fn)(const char *, const struct stat64 *, int, struct FTW *), int depth, int flags);

The nftw() function recursively descends the directory hierarchy rooted at the specified path. The behavior is similar to ftw(), except that it takes an additional flags argument, which is a bitwise-OR of zero or more of the following values:

FTW_CHDIR: If set, nftw() changes the current working directory to each directory as it reports file in that directory. If clear, nftw() does not change the current working directory.
FTW_DEPTH: If set, nftw() reports all files in a directory before reporting the directory itself. If clear, nftw() reports any directory before reporting the files in that directory.
FTW_MOUNT: If set, nftw() only reports files in the same file system as the specified path. If clear, nftw() reports all files encountered during a walk.
FTW_PHYS: If set, nftw() performs a physical walk and does not follow symbolic links. If clear, nftw() follows links instead of reporting them, and does not report the same file twice.

For each object in the hierarchy, ntw() calls the specified function, passing it the following arguments:

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,

An integer flag. Possible values for the flag are:

FTW_F: For a file.
FTW_D: For a directory.
FTW_DP: For a directory for which the contents have already been visited. This condition only occurs if the FTW_DEPTH flag is specified.
FTW_SL: For a symbolic link. This condition only occurs if the FTW_PHYS flag is specified.
FTW_SLN: For a symbolic link that does not name an existing file. This condition only occurs if the FTW_PHYS flag is not specified.
FTW_DNR: For a directory that cannot be read. The user function is not called for any of its descendants.
FTW_NS: For an object on which stat() could not be successfully executed. The stat buffer passed to the function is undefined.

A pointer to an FTW structure. The value of the base member is the offset of the object's file name in the path name passed as the first argument to the function. The value of the level member indicates the depth relative to the root of the walk, where the root level is 0.

The nftw() 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 nftw().

The nftw64() function is identical to the nftw() function except that it can properly handle disk files that are larger than 2 gigabytes. The nftw64() function is a part of the large file extensions.

PARAMETERS

path: Is the root of the directory hierarchy to be traversed.
fn: Is the function to be called for each element of the tree.
depth: Specifies the maximum number of directory streams or file descriptors (or both) that are available for use by nftw() while traversing the tree. This should be in the range of [1, OPEN_MAX].
flags: Indicates the flag values, as described in the DESCRIPTION section.

RETURN VALUES

On success, nftw() or nftw64() returns 0. If the specified function returns a non-zero value, nftw() or nftw64() stops its tree traversal and returns whatever value was returned by the function. If nftw() or nftw64() 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 depth 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 nftw() function may also return errno values specified for stat(), lstat(), opendir(), readdir(), or chdir(). In addition, if the user specified function encounters system errors, errno may be set accordingly.

nftw(), nftw64()
walk file tree

Function

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

CONFORMANCE

MULTITHREAD SAFETY LEVEL

PORTING ISSUES

AVAILABILITY

SEE ALSO

nftw(), nftw64() walk file tree

Function

nftw(), nftw64()
walk file tree