ftw(3C)

NAME

ftw(), nftw() — walk a file tree executing a function

SYNOPSIS

#include <ftw.h> 

int ftw (const char *path, 
         int (*fn)(const char *obj_path, 
                   const struct stat *obj_stat, 
                   int obj_flags), 
         int depth); 

int nftw (const char *path, 
          int (*fn)(const char *obj_path, 
                    const struct stat *obj_stat, 
                    int obj_flags, 
                    struct FTW obj_FTW), 
          int depth, 
          int flags); 

UNIX95

int nftw (const char *path, 
          int (*fn)(const char *obj_path, 
                    const struct stat *obj_stat, 
                    int obj_flags, 
                    struct *FTW obj_FTW), 
          int depth, 
          int flags); 

Obsolescent Interfaces

int nftw2(const char *path, 
          int (*fn)(const char *obj_path, 
                    const struct stat *obj_stat, 
                    int obj_flags, 
                    struct FTW obj_FTW), 
          int depth, 
          int flags); 

DESCRIPTION

The ftw() function recursively descends the directory hierarchy rooted in path. For each object in the hierarchy, ftw() calls fn, passing it a pointer to a null-terminated character string containing the name of the object, a pointer to a stat structure containing information about the object (see lstat() in stat(2)), and an integer, obj_flags. The possible values of obj_flags, defined in the <ftw.h> header file, are:

FTW_F: The object is a file.
FTW_D: The object is a directory.
FTW_SL: The object is a symbolic link.
FTW_DNR: The object is a directory without read permission. fn will not be called for any of its descendants.
FTW_NS: lstat() failed on the object. The contents of the stat structure are undefined. If the failure was caused by a lack of permissions, the walk will continue. For all other errors ftw() will terminate the walk and return -1.

Tree traversal continues until the tree is exhausted, an invocation of fn returns a nonzero value, or an 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 the same value as returned by fn. If ftw() detects an error, it returns -1 and sets the error type in errno (see errno(2)).

ftw() reports a directory before reporting any of its descendants.

ftw() and nftw() use one file descriptor for each level in the tree. The depth argument limits the number of file descriptors that can be used. If depth is 0 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. For best performance, depth should be at least as large as the number of levels in the tree.

nftw() is similar to ftw() except that it takes the additional argument flags, and does not report or enter a directory which has already been visited during the walk. The flags field is the inclusive OR of the following values, as defined in the <ftw.h> header file:

FTW_PHYS

If set, nftw() does a physical walk. It will not follow symbolic links, but will follow hard links.

If clear, nftw() follows both symbolic and hard links. In addition, if the UNIX95 environment is defined, no object will be reported to fn more than once. Classic HP nftw() behavior will report a file as many times as it is referenced.

FTW_MOUNT

If set, nftw() will only report files in the same file system as path. (See WARNINGS for one exception involving loopback file systems (LOFS)).

If clear, nftw() will report all objects encountered in the walk.

FTW_DEPTH

If set, nftw() performs a depth-first search. A directory's contents will be reported before the directory is reported to fn.

If clear, the directory will be reported before its descendants.

FTW_CHDIR

If set, the walk does a chdir() (see chdir(2)) to each directory before reading its contents. At the time a directory is reported to fn, the current working directory will be the parent of the reported directory. A directory must have both read and execute permissions, otherwise the directory is reported as a FTW_DNR object, no chdir() will be done and it will not be entered.

If clear, nftw() will not alter the process' current working directory, and the directory only needs read permission to be reported as a FTW_D or FTW_DP object.

FTW_SERR

If set and any lstat() or stat() failure occurs, fn is called with the FTW_NS object flag and the walk continues.

If clear and lstat() or stat() fails due to lack of permissions, fn is called with the FTW_NS object type. If the UNIX95 environment is defined, the walk continues. The HP classic behavior will terminate the walk and return -1. For any error other than permissions, or any error from other system calls such as opendir(3C) or readdir(3C), nftw() does not call fn, terminates the walk and returns -1.

nftw() calls fn with four arguments for each object reported. The first argument is the path name of the file, directory, or symbolic link. The second argument is a pointer to a stat structure (see lstat(2)) containing information about the object. The third argument is an integer giving additional information as follows:

FTW_F

The object is a file.

FTW_D

The object is a directory.

FTW_DP

The object is a directory and subdirectories have been visited. This can be passed to fn only if FTW_DEPTH is specified.

FTW_SL

The object is a symbolic link. This can be passed to fn only if FTW_PHYS is specified.

FTW_SLN

The object is a symbolic link that does not point to an existing object. This can be passed to fn only if FTW_PHYS is not specified.

FTW_DNR

The object is a directory that cannot be read, or does not have execute permissions when FTW_CHDIR is specified. The function fn is not called for any of the directory's descendants.

FTW_NS

lstat() or stat() failed on the object. The contents of the stat structure passed to fn are undefined. If the failure occurred due to lack of permissions, errno is set to EACCES. If the UNIX95 environment is defined, the walk will always continue after permissions errors. For classic HP behavior, the FTW_SERR flag must be set for the walk to continue.

Note that this behavior differs from ftw().

The fourth argument is different for the default environment and the UNIX95 environment. For the default environment, the fourth argument is a structure FTW. For the UNIX95 environment, the fourth argument is a pointer to a structure FTW (ie: *FTW). FTW contains the following members:

int base; 
int level; 

The value of base is the offset from the first character in the path name to where the base name of the object starts; this path name is passed as the first argument to fn. The value of level indicates depth relative to the start of the walk, where the start level has a value of zero.

APPLICATION USAGE

ftw() can execute concurrently in separate threads. nftw() and nftw2() are serialized if the path argument is relative (i.e., does not start with '/'), or the FTW_CHDIR flag is set. For best concurrency, call nftw() with an absolute starting path and do not set FTW_CHDIR.

To use the UNIX95 prototype, the UNIX95 environment must be defined. This is done by defining the UNIX95 environment variable, passing the _XOPEN_SOURCE_EXTENDED flag as a compiler option, and adding /usr/xpg4/bin to your path. This can be done as follows:

1.: export UNIX95=
2.: PATH=/usr/xpg4/bin:$PATH
3.: cc foo.c -D_XOPEN_SOURCE_EXTENDED

nftw2() is to be obsoleted at a future date.

ERRORS

If ftw() or nftw() fails, it sets errno (see errno(2)) to one of the following values:

[EACCES]: If a component of the path prefix denies search permission, or if read permission is denied for path, fn returns -1 and does not reset errno.
[EINVAL]: The value of the depth argument is invalid.
[ENAMETOOLONG]: The length of the specified path name exceeds PATH_MAX bytes, or the length of a component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect.
[ENOENT]: path points to the name of a file that does not exist, or points to an empty string.
[ENOTDIR]: A component of path is not a directory.
[EOVERFLOW]: One or more of the values in struct stat (st_size or st_blocks) is too large to store in the structure to be passed to the function pointed to by fn. Use ftw64() or nftw64() instead for 32-bit applications.

In addition, if the function pointed to by fn encounters system errors, errno may be set accordingly.

WARNINGS

For 32-bit applications, st_ino will be truncated to its least significant 32-bits for filesystems that use 64-bit values. Note that this will even occur for ftw64() calls because st_ino is defined as an unsigned long.

For 32-bit applications accessing large file systems, use ftw64() or nftw64() instead in order to avoid overflow of the stat structure.

nftw() contains some recursion and it is possible for it to terminate with a memory fault when applied to file trees which contain a large number of directories, or a large number of files when FTW_PHYS is clear and the UNIX95 environment is defined.

nftw() uses malloc() to allocate dynamic storage during operation (see malloc(3C)). If it is forcibly terminated (such as if longjmp() is executed by fn or an interrupt routine), the calling function will not have a chance to free that storage, causing it to remain allocated until the process terminates. 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.

If the starting path is in a loopback file system (LOFS) and FTW_MOUNT is set (to stay within the LOFS), but FTW_PHYS is clear (symbolic and hard links are followed), nftw() cannot determine whether a link referencing a file on the same _device_ is really within the LOFS. It is possible with this specific combination of factors to have some files reported to fn which should not be.

Obsolescent Interfaces

nftw2() is to be obsoleted at a future date.

AUTHOR

ftw(), nftw(), and nftw2() were developed by AT&T and HP.

STANDARDS CONFORMANCE

ftw(): AES, SVID2, SVID3, XPG2, XPG3, XPG4

ftw(3C)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

UNIX95

Obsolescent Interfaces

DESCRIPTION

APPLICATION USAGE

ERRORS

WARNINGS

Obsolescent Interfaces

AUTHOR

SEE ALSO

STANDARDS CONFORMANCE