Technical Reference: Base Operating System and Extensions, Volume 1

nftw or nftw64 Subroutine

Purpose

Walks a file tree.

Library

Standard C Library (libc.a)

Syntax

#include <ftw.h> int nftw ( Path, Function, Depth, Flags) const char *Path; int *(*Function) ( ); int Depth; int Flags;

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:

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

FTW_F	Regular file
FTW_D	Directory
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_SL	Symbolic Link
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.

Parameters

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.

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:

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 unsuccessful if:

EOVERFLOW

A file in Path is of a size larger than 2 Gigabytes.

Related Information

The stat or malloc (malloc, free, realloc, calloc, mallopt, mallinfo, mallinfo_heap, alloca, or valloc Subroutine) subroutine.

The ftw (ftw or ftw64 Subroutine) subroutine.