NAME

ftw, nftw − Walks a file tree

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <ftw.h>

int ftw(
        const char ∗path,
        int(∗function)(const char ∗, const struct stat ∗, int),
        int depth);

int nftw(
        const char ∗path,
        int(∗function)(const char ∗, const struct stat ∗, int, struct FTW),
        int depth),
        int flags);

PARAMETERS

pathSpecifies the directory hierarchy to be searched. 

functionSpecifies the function to be invoked for each file in the directory hierarchy. 

depthNo longer used. 

flagsSpecifies optional flags that modify the operation of the nftw() function only. 

DESCRIPTION

The ftw() function recursively searches the directory hierarchy that descends from the directory specified by the path parameter. 

For each file in the hierarchy, the ftw() function calls the function specified by the function parameter, passes it 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, and an integer. (See the stat(2) reference page for more information about this structure.) 

The integer passed to the function parameter identifies the file type, and it has one of the following values:

FTW_FRegular file. 

FTW_DDirectory. 

FTW_DNRDirectory that cannot be read. 

FTW_SLSymbolic link. 

FTW_NSA file for which the lstat() function could not be executed successfully. 

If the integer is FTW_DNR, then the files and subdirectories contained in that directory are not processed. 

If the integer is FTW_NS, then 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() function finishes processing a directory before processing any of its files or subdirectories. 

The ftw() function continues the search until the directory hierarchy specified by the path parameter is completed, an invocation of the function specified by the function parameter returns a nonzero value, or an error is detected within the ftw() function, such as an I/O error. 

Because the ftw() function is recursive, it is possible for it to terminate with a memory fault due to stack overflow when applied to very deep file structures. 

The ftw() function uses the malloc() function to allocate dynamic storage during its operation. If the ftw() function is terminated prior to its completion, such as by the longjmp() function being executed by the function specified by the function parameter or by an interrupt routine, the ftw() function 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. 

The ftw() function traverses symbolic links encountered in the resolution of path, including the final component.  Symbolic links encountered while walking the directory tree rooted at path will not be traversed. 

The nftw() function provides the same features as does ftw(), but with the following additional flags:

FTW_PHYSPhysically walks the file tree, but does not follow symbolic links. If this flag is not specified, the nftw() function does follow links, but does not walk down any path that crosses itself. 

FTW_MOUNT
Mount points are not crossed during the walk.

FTW_DEPTH
All subdirectories are to be visited before the directory itself.

FTW_CHDIR
The walk changes to each directory before reading its contents.

The nftw() function calls  the function parameter with four arguments at each file and directory. The first argument is the pathname of the object. The second argument points to the stat buffer. The third argument identifies all of the file types used by the ftw() function (see the previous description). In addition, the nftw() function provides the following file type:

FTW_DPA directory whose directories have been visited. 

The fourth argument is a struct FTW. This structure contains the following members:

int base;
int level;

The value of base is the offset into the pathname of the object.  This pathname is passed as the first argument to the function parameter. The value of level specifies the depth relative to the root of the walk, where the root level has a value of 0 (zero). 

NOTES

The ftw() and nftw() functions are reentrant; care should be taken to ensure that the function supplied as argument function is also reentrant. 

AES Support Level:
Trial use.

RETURN VALUES

If the directory hierarchy is completed, the ftw() and nftw() functions return a value of 0 (zero).  If the function specified by the function parameter returns a nonzero value, the ftw() and nftw() functions stop their search and return the value that was returned by the function.  If the ftw() and nftw() functions detect an error, a value of -1 is returned, and errno is set to indicate the error. 

ERRORS

If any of the following conditions occurs, the ftw() and nftw() functions set errno to the value that corresponds to the condition. 

[EACCES]Search permission is denied for any component of the path parameter or read permission is denied for the path parameter. 

[ENAMETOOLONG]
The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_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. 

[ENOMEM]There is insufficient memory for this operation. 

In addition, if the function pointed to by the function parameter encounters an error, errno may be set accordingly. 

RELATED INFORMATION

Functions: stat(2).