nftw() — Traverse a file tree

Standards

Standards / Extensions C or C++ Dependencies

XPG4.2
Single UNIX Specification, Version 3

 both  

Format

#define _XOPEN_SOURCE_EXTENDED 1
#include <ftw.h>

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

General description

The nftw() function recursively descends the directory hierarchy rooted in path. It is similar to ftw() except that it takes an additional argument flags, which is a bitwise inclusive-OR of zero or more of the following flags:
FTW_CHDIR
If set, nftw() will change the current working directory to each directory as it reports files in that directory. If clear, nftw() will not change the current working directory.
FTW_DEPTH
If set, nftw() will report all files in a directory before reporting the directory itself. If clear, nftw() will report any directory before reporting the files in that directory.
FTW_MOUNT
If set, nftw() will only report files in the same file system as path. If clear, nftw() will report all files encountered during the walk.
FTW_PHYS
If set, nftw() performs a physical walk and does not follow symbolic links. If clear, nftw() will follow links instead of reporting them, and will not report the same file twice.
At each file it encounters, nftw() calls the user-supplied function fn with four arguments:
  • the first argument is the pathname of the object.
  • the second argument is a pointer to a stat buffer containing information on the object.
  • the third argument is an integer giving additional information. Its value is one of the following:
    FTW_D
    for a directory
    FTW_DNR
    for a directory that cannot be read
    FTW_DP
    for a directory whose subdirectories have been visited. (This condition will only occur if FTW_DEPTH is included in flags.)
    FTW_F
    for a file
    FTW_NS
    for an object other than a symbolic link on which stat() could not be successfully executed. If the object is a symbolic link, and stat() failed, it is unspecified whether nftw() passes FTW_SL or FTW_NS to the user-supplied function.
    FTW_SL
    for a symbolic link
    FTW_SLN
    for a symbolic link that does not name an existing file. (This condition will only occur if FTW_PHYS is not included in flags.)
  • the fourth argument is a pointer to an FTW structure. The value of base is the offset of the object's filename in the pathname passed as the first argument to fn(). The value of level indicates depth relative to the root of the walk, where the root level is 0.

The argument fd_limit limits the directory depth for the search. At most one file descriptor will be used for each directory level.

Large file support for z/OS UNIX files: Large z/OS UNIX files are supported automatically for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications must be compiled with the option LANGLVL(LONGLONG) and define the _LARGE_FILES feature test macro before any headers are included to enable this function to operate on z/OS UNIX files that are larger than 2 GB in size. File size and offset fields are enlarged to 63 bits in width. Therefore, any other function operating on the file is required to define the _LARGE_FILES feature test macro as well.

Special behavior for C++: Because C and C++ linkage conventions are incompatible, nftw() cannot receive a C++ function pointer as the argument. If you attempt to pass a C++ function pointer to nftw(), the compiler will flag it as an error. You can pass a C or C++ function to nftw() by declaring it as extern "C".

Returned value

nftw() continues until the first of the following conditions occurs:
  • An invocation of fn() returns a nonzero value, in which case nftw() returns that value.
  • The nftw() function detects an error other than EACCES (see FTW_DNR and FTW_NS above), in which case nftw() returns -1 and sets errno to indicate the error.
  • The tree is exhausted, in which case nftw() returns 0.
If unsuccessful, nftw() sets errno to one of the following values. All other errnos returned by nftw() are unchanged.
Error Code
Description
EACCES
Search permission is denied for any component of path or read permission is denied for path, or fn() returns -1 and does not reset errno.
ELOOP
Too many symbolic links were encountered.
EMFILE
OPEN_MAX file descriptors are currently open in the calling process.
ENAMETOOLONG
One of the following error conditions exists:
  • Pathname resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX.
  • The length of path exceeds PATH_MAX, or a pathname component is longer than PATH_MAX.
ENFILE
Too many files are currently open in the system.
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 errno value might also be set if the function fn causes it to be set.

Related information

Parent topic: Library functions