Walks a file tree.
Standard C Library (libc.a)
int nftw ( Path, Function, Depth, Flags)
const char *Path;
int *(*Function) ( );
int nftw64(Path,Function,Depth) const char *Path; int *(*Function) ( ); int Depth; int Flags;
The nftw and
nftw64 subroutines recursively descend the directory hierarchy rooted in
the Path parameter. The nftw and nftw64 subroutines have a
similar effect to ftw and ftw64 except that they take an additional argument
flags, which is a bitwise inclusive-OR of zero or more of the following
|FTW_CHDIR||If set, the current working directory will change to each directory as files are reported. If clear, the current working directory will not change.|
|FTW_DEPTH||If set, all files in a directory will be reported before the directory itself. If clear, the directory will be reported before any files.|
|FTW_MOUNT||If set, symbolic links will not be followed. If clear the links will be followed.|
|FTW_PHYS||If set, symbolic links will not be followed. If clear the links will be followed, and will not report the same file more than once.|
For each file in the hierarchy, the nftw and nftw64 subroutines call the function specified by the Function parameter. The nftw subroutine passes a pointer to a null-terminated character string containing the name of the file, a pointer to a stat structure containing information about the file, an integer and a pointer to an FTW structure. The nftw64 subroutine passes a pointer to a null-terminated character string containing the name of the file, a pointer to a stat64 structure containing information about the file, an integer and a pointer to an FTW structure.
The nftw subroutine uses the stat system call which will fail on files of size larger than 2 Gigabytes. The nftw64 subroutine must be used if there is a possibility of files of size larger than 2 Gigabytes.
The integer passed to the
Function parameter identifies the file type with one of the
|FTW_DNR||Directory that cannot be read|
|FTW_DP||The Object is a directory and subdirectories have been visited. (This condition will only occur if FTW_DEPTH is included in flags).|
|FTW_SLN||Symbolic Link that does not name an existin file. (This condition will only occur if the FTW_PHYS flag is not included in flags).|
|FTW_NS||File for which the stat structure could not be executed successfully|
If the integer is FTW_DNR, the files and subdirectories contained in that directory are not processed.
If the integer is FTW_NS, the stat structure contents are meaningless. An example of a file that causes FTW_NS to be passed to the Function parameter is a file in a directory for which you have read permission but not execute (search) permission.
The FTW structure pointer passed to the Function parameter contains base which is the offset of the object's filename in the pathname passed as the first argument to Function. The value of level indicates depth relative to the root of the walk.
The nftw and nftw64 subroutines use one file descriptor for each level in the tree. The Depth parameter specifies the maximum number of file descriptors to be used. In general, the nftw and nftw64 run faster of the value of the Depth parameter is at least as large as the number of levels in the tree. However, the value of the Depth parameter must not be greater than the number of file descriptors currently available for use. If the value of the Depth parameter is 0 or a negative number, the effect is the same as if it were 1.
Because the nftw and nftw64 subroutines are recursive, it is possible for it to terminate with a memory fault due to stack overflow when applied to very deep file structures.
The nftw and nftw64 subroutines use the malloc subroutine to allocate dynamic storage during its operation. If the nftw subroutine is terminated prior to its completion, such as by the longjmp subroutine being executed by the function specified by the Function parameter or by an interrupt routine, the nftw subroutine cannot free that storage. The storage remains allocated. A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have the function specified by the Function parameter return a nonzero value the next time it is called.
|Path||Specifies the directory hierarchy to be searched.|
|Function||User supplied function that is called for each file encountered.|
|Depth||Specifies the maximum number of file descriptors to be used. Depth cannot be greater than OPEN_MAX which is described in the sys/limits.h header file.|
If the tree is exhausted, the nftw and nftw64 subroutine returns a value of 0. If the subroutine pointed to by fn returns a nonzero value, nftw and nftw64 stops its tree traversal and returns whatever value was returned by the subroutine pointed to by fn. If the nftw and nftw64 subroutine detects an error, it returns a -1 and sets the errno global variable to indicate the error.
If the nftw or nftw64 subroutines detect an error, a value of -1 is returned and the errno global variable is set to indicate the error.
The nftw and
nftw64 subroutine are unsuccessful if:
|EACCES||Search permission is denied for any component of the Path parameter or read permission is denied for Path.|
|ENAMETOOLONG||The length of the path exceeds PATH_MAX while _POSIX_NO_TRUNC is in effect.|
|ENOENT||The Path parameter points to the name of a file that does not exist or points to an empty string.|
|ENOTDIR||A component of the Path parameter is not a directory.|
The nftw subroutine is
|EOVERFLOW||A file in Path is of a size larger than 2 Gigabytes.|
This subroutines is part of Base Operating System (BOS) Runtime.
The stat or malloc (malloc, free, realloc, calloc, mallopt, mallinfo, alloca, or valloc Subroutine) subroutine.
The ftw (ftw or ftw64 Subroutine) subroutine.