nftw(), nftw64()

walk file tree 

Function


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);


DESCRIPTION

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:

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.

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.


CONFORMANCE

UNIX 98, with exceptions


MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

This function is MT-Safe unless the FTW_CHDIR flag is specified.


PORTING ISSUES

Windows current supports neither symbolic links nor mounted file systems, so the FTW_MOUNT and FTW_PHYS flags have no effect.


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:
chdir(), ftw(), lstat(), opendir(), readdir(), stat()

Miscellaneous:
l64, struct stat


PTC MKS Toolkit 10.3 Documentation Build 39.