ftw(3C)
NAME
ftw, ftwh, nftw, nftwh − walk a file tree
SYNOPSIS
#include <ftw.h>
int ftw (char *path, int (*fn)(),
int ftwh (char *path, int (*fn)(),
int nftw (char *path, int (*fn)(),
int nftwh (char *path, int (*fn)(),
DESCRIPTION
ftw() 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 stat(2)), and an integer. Possible values of the integer, defined in the <ftw.h> header file, are:
FTW_F The object is a file.
FTW_D The object is a directory,
FTW_DNR The object is a directory without read permission. fn will not be called for any of its descendants.
FTW_NS stat() could not successfully be executed on the object. The contents of the stat structure is undefined. If the stat() failure is because the object is in a directory without search permission, fn is called and the walk continues. If stat() fails for any other reason, ftw() does not call fn, sets errno, and returns −1.
Tree traversal continues until the tree is exhausted, an invocation of fn returns a nonzero value, or some error is detected within ftw() (such as an I/O error). If the tree is exhausted, ftw() returns zero. If fn returns a non-zero value, ftw() stops its tree traversal and returns whatever value was returned by fn. If ftw() detects an error, it returns −1 and sets the error type in errno.
ftw() visits a directory before visiting any of its descendants.
ftw(), ftwh(), nftw(), and nftwh() 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.
ftwh() is eqivalent to ftw() except that ftwh() also traverses hidden directories (context dependent files — see cdf(4)).
nftw() is similar to ftw() except that it takes the additional argument flags. The flags field is the inclusive OR of the following values, as defined in the <ftw.h> header file:
FTW_PHYS nftw() does a physical walk. It does not follow symbolic links. nftw() follows hard links but does not walk down any path that crosses itself. If FTW_PHYS is not specified nftw() follows symbolic and hard links but does not walk a path that crosses itself.
FTW_MOUNT The walk does not cross a mount point. This means the walk does not visit any files that reside on a device other than the one where the walk started. It does not cross NFS mount points.
FTW_DEPTH nftw() performs a depth-first search. This means that a directory’s contents are visited before the directory itself is visited.
FTW_CHDIR The walk does a chdir() (see chdir(2)) to each directory before reading it.
FTW_CDF The walk traverses hidden directories (context dependent files — see cdf(4)).
FTW_SERR The walk normally terminates and returns −1 if stat() fails for any reason. If FTW_SERR is specified and a stat() failure is encountered, fn is called, and the walk continues.
nftw() calls fn with four arguments for each file and directory visited. The first argument is the pathname of the file or directory, the second is a pointer to a stat structure (see stat(2)) containing information about the object, and the third 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_DNR The object is a directory that cannot be read. fn is not called for any of its descendants.
FTW_NS stat() failed on the object. The contents of the stat structure passed to fn are undefined. If the stat() failure occured because the object is in a directory without search permission, errno is set, and nftw() returns −1 after calling fn. Note that this behavior differs from ftw(). If stat() fails for any other reason, nftw() does not call fn, sets errno, and returns −1. This behavior can be altered by specifing the FTW_SERR flag.
The fourth argument is a structure FTW which contains the following members:
int base;
int level;
The value of base is the offset from the first character in the pathname to where the basename of the object starts; this pathname 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.
nftwh() is equivalent to nftw() except that nftwh() also traverses hidden directories (context dependent files — see cdf(4)). nftwh() is equivalent to calling nftw() with the FTW_CDF flag specified.
ERRORS
ftw(), ftwh(), nftw(), and nftwh() fail if any of the following conditions are encountered:
[EACCES] If a component of the path prefix denies search permission or read permission is denied for path, and fn returns −1 and does not reset errno.
[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.
[EINVAL] The value of the depth argument is invalid.
In addition, if the function pointed to by fn encounters system errors, errno may be set accordingly.
WARNINGS
On Series 300, 400 and 700 systems, ftw() uses lstat() instead of stat() to get the structure containing information about the object (ftw() uses stat() on Series 800 systems). See stat(2).
Because these functions are recursive, it is possible for them to terminate with a memory fault when applied to very deep file structures.
ftw(), ftwh(), nftw(), and nftwh() use malloc() to allocate dynamic storage during their operation. If they are 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.
AUTHOR
ftw(), ftwh(), nftw(), and nftwh were developed by AT&T and HP.
SEE ALSO
STANDARDS CONFORMANCE
ftw(): AES, SVID2, XPG2, XPG3, XPG4
Hewlett-Packard Company — HP-UX Release 9.0: August 1992