int ftw(const char path, int (fn) (const char , const struct stat , int), int depth);
int ftw64(const char path, int (fn) (const char , const struct stat64 , int), int depth);
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);
ftw visits a directory before visiting any of its descendants.
The tree traversal continues until the tree is exhausted, an invocation of fn returns a nonzero value, or some error is detected within ftw (such as an I/O error). If the tree is exhausted, ftw returns zero. If fn returns a nonzero value, ftw stops its tree traversal and returns whatever value was returned by fn. If ftw detects an error other than EACCES, it returns -1, and sets the error type in errno.
The function nftw is similar to ftw except that it takes an additional argument, flags. The flags field is used to specify:
The function nftw calls fn with four arguments at each file
The first argument is the pathname of the object, the second
is a pointer to the stat buffer, the third is an integer
giving additional information,
and the fourth is a
struct FTW that contains the following members:
int base; int level;
base is the offset into the pathname of the base name of the object. level indicates the depth relative to the rest of the walk, where the root level is zero.
The values of the third argument are as follows:
Both ftw and nftw use one file descriptor for each level in the tree. The depth argument limits the number of file descriptors so used. If depth is zero or negative, the effect is the same as if it were 1. depth must not be greater than the number of file descriptors currently available for use. ftw will run faster if depth is at least as large as the number of levels in the tree. When ftw and nftw return, they close any file descriptors they have opened; they do not close any file descriptors that may have been opened by fn.
ftw uses malloc(3C) to allocate dynamic storage during its operation. If ftw is forcibly terminated, such as by longjmp being executed by fn or an interrupt routine, ftw will not have a chance to free that storage, so it will 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 nonzero value at its next invocation.