#include <ftw.h>

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

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

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

The ftw() function visits a directory before visiting any of its descendants.

The tree traversal continues until the tree is exhausted, an invocation of fn returns a non-zero value, or some error is detected within ftw() (such as an I/O error). If the tree is exhausted, ftw() returns 0. If fn returns a non-zero value, ftw() stops its tree traversal and returns whatever value was returned by fn.

The nftw() function is similar to ftw() except that it takes the additional argument flags, which is a bitwise-inclusive OR of zero or more of the following flags: FTW_CHDIR

If FTW_PHYS is clear and FTW_DEPTH is set, nftw() follows links instead of reporting them, but does not report any directory that would be a descendant of itself. If FTW_PHYS is clear and FTW_DEPTH is clear, nftw() follows links instead of reporting them, but does not report the contents of any directory that would be a descendant of itself.

At each file it encounters, nftw() calls the user-supplied function fn with four arguments:

int base;
int level;

Both ftw() and nftw() use one file descriptor for each level in the tree. The depth argument limits the number of file descriptors used. If depth is zero or negative, the effect is the same as if it were 1. It must not be greater than the number of file descriptors currently available for use. The ftw() function runs faster if depth is at least as large as the number of levels in the tree. Both ftw() and nftw() are able to descend to arbitrary depths in a file hierarchy and do not fail due to path length limitations unless either the length of the path name pointed to by the path argument exceeds {PATH_MAX} requirements, or for ftw(), the specified depth is less than 2, or for nftw(), the specified depth is less than 2 and FTW_CHDIR is not set. When ftw() and nftw() return, they close any file descriptors they have opened; they do not close any file descriptors that might have been opened by fn.

If the tree is exhausted, ftw() and nftw() return 0. If the function pointed to by fn returns a non-zero value, ftw() and nftw() stop their tree traversal and return whatever value was returned by the function pointed to by fn. If ftw() and nftw() detect an error, they return -1 and set errno to indicate the error.

If ftw() and nftw() encounter an error other than EACCES (see FTW_DNR and FTW_NS above), they return -1 and set errno to indicate the error. The external variable errno can 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.

The ftw() and nftw() functions will fail if: ELOOP

The ftw() function will fail if: EACCES

The nftw() function will fail if: EACCES

The nftw() and ftw() functions may fail if: ELOOP

The ftw() function may fail if: EINVAL

The nftw() function may fail if: EMFILE

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

Example 1 Walk a directory structure using ftw().

The following example walks the current directory structure, calling the fn() function for every directory entry, using at most 10 file descriptors:

#include <ftw.h>
...
if (ftw(".", fn, 10) != 0) {
 perror("ftw"); exit(2);
}

Example 2 Walk a directory structure using nftw().

The following example walks the /tmp directory and its subdirectories, calling the nftw() function for every directory entry, to a maximum of 5 levels deep.

#include <ftw.h>
...
int nftwfunc(const char *, const struct stat *, int, struct FTW *);
int nftwfunc(const char *filename, const struct stat *statptr,
 int fileflags, struct FTW *pfwt)
{
 return 0;
}
...
char *startpath = "/tmp";
int depth = 5;
int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
int ret;
ret = nftw(startpath, nftwfunc, depth, flags);

Because ftw() and nftw() are recursive, they can terminate with a memory fault when applied by a thread with a small stack to very deep file structures.

The ftw() and nftw() functions allocate resources (memory, file descriptors) during their operation. If ftw() they are forcibly terminated, such as by longjmp(3C) being executed by fn or an interrupt routine, they will not have a chance to free those resources, so they remain permanently allocated. A safe way to handle interrupts is to store the fact that an interrupt has occurred and arrange to have fn return a non-zero value at its next invocation.

The ftw() and nftw() functions have transitional interfaces for 64-bit file offsets. See lf64(5).

The ftw() function is safe in multithreaded applications. The nftw() function is safe in multithreaded applications when the FTW_CHDIR flag is not set.

See attributes(5) for descriptions of the following attributes:

stat(2), longjmp(3C), attributes(5), lf64(5), standards(5)