nftw or nftw64 Subroutine

Purpose

Walks a file tree.

Library

Standard C Library (libc.a)

Syntax

int nftw64(Path,Function,Depth)
const char *Path;
int *(*Function) ( );
int Depth;
int Flags;

Description

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 flags:

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 following values:

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.

Parameters

Return Values

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.

Error Codes

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:

The nftw subroutine is unsuccessful if: