ftw(3) Library Functions Manual ftw(3)
Name
ftw - walk a file tree
Syntax
#include <ftw.h>
int ftw (path, fn, depth)
char *path;
int (*fn) ( );
int depth;
Description
The subroutine recursively descends the directory hierarchy rooted in path. For each object in the hierarchy, 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, and an integer. For further information, see Possible values of the integer, defined in the <ftw.h> header file, are FTW_F for
a file, FTW_D for a directory, FTW_DNR for a directory that cannot be read, and FTW_NS for an object for which stat could not successfully
be executed. If the integer is FTW_DNR, descendants of that directory will not be processed. If the integer is FTW_NS, the the contents
of the stat structure will be undefined. An example of an object that would cause FTW_NS to be passed to fn would be a file in a directory
with read but without execute (search) permission.
The subroutine visits a directory before visiting any of its descendants.
The tree traversal continues until the tree is exhausted, an invocation of fn returns a nonzero value, or some error is detected within
(such as an I/O error). If the tree is exhausted, returns zero. If fn returns a nonzero value, stops its tree traversal and returns what-
ever value was returned by fn. If detects an error, it returns -1, and sets the error type in errno.
The subroutine uses one file descriptor for each level in the tree. The depth argument limits the number of file descriptors so used. If
depth is zero or negative, the effect is the same as if it were 1. The depth must not be greater than the number of file descriptors cur-
rently available for use. The subroutine will run more quickly if depth is at least as large as the number of levels in the tree.
Restrictions
Because is recursive, it is possible for it to terminate with a memory fault when applied to very deep file structures.
It could be made to run faster and use less storage on deep structures at the cost of considerable complexity.
The subroutine uses to allocate dynamic storage during its operation. If is forcibly terminated, such as by longjmp being executed by fn
or an interrupt routine, will not have a chance to free that storage, so it will remain permanently allocated. A safe way to handle inter-
rupts is to store the fact that an interrupt has occurred, and arrange to have fn return a nonzero value at its next invocation.
Diagnostics
[EACCES] Search permission is denied on a component of path or read permission is denied for path.
[ENAMETOOLONG] The length of the path string exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX}.
[ENOENT] The path argument points to the name of a file which does not exist, or to an empty string and the environment defined is
POSIX or SYSTEM_FIVE.
[ENOTDIR] A component of path is not a directory.
[ENOMEM] Not enough memory was available to complete the file tree walk.
See Also
stat(2), malloc(3)
ftw(3)
Check Out this Related Man Page
FTW(3) Linux Programmer's Manual FTW(3)
NAME
ftw, nftw - file tree walk
SYNOPSIS
#include <ftw.h>
int ftw(const char *dir, int (*fn)(const char *file, const struct stat *sb, int flag), int depth);
int nftw(const char *dir, int (*fn)(const char *file, const struct stat *sb, int flag, struct FTW *s), int depth, int flags);
DESCRIPTION
ftw() walks through the directory tree starting from the indicated directory dir. For each found entry in the tree, it calls fn() with the
full pathname of the entry, a pointer to the stat(2) structure for the entry and an int flag, which value will be one of the following:
FTW_F Item is a normal file
FTW_D Item is a directory
FTW_DNR
Item is a directory which can't be read
FTW_SL Item is a symbolic link
FTW_NS The stat failed on the item which is not a symbolic link
If the item is a symbolic link and stat failed, XPG4v2 states that it is undefined whether FTW_NS or FTW_SL is used.
ftw() recursively calls itself for traversing found directories, handling a directory before its files or subdirectories. To avoid using
up all a program's file descriptors, the depth specifies the number of simultaneous open directories. When the depth is exceeded, ftw()
will become slower because directories have to be closed and reopened. ftw() uses at most one file descriptor for each level in the file
hierarchy.
To stop the tree walk, fn() returns a non-zero value; this value will become the return value of ftw(). Otherwise, ftw() will continue
until it has traversed the entire tree, in which case it will return zero, or until it hits an error other than EACCES (such as a malloc(3)
failure), in which case it will return -1.
Because ftw() uses dynamic data structures, the only safe way to exit out of a tree walk is to return a non-zero value. To handle inter-
rupts, for example, mark that the interrupt occurred and return a non-zero value--don't use longjmp(3) unless the program is going to ter-
minate.
The function nftw() does precisely the same as ftw(), except that it has one additional argument flags (and calls the supplied function
with one more argument). This flags argument is an OR of zero or more of the following flags:
FTW_CHDIR
If set, do a chdir() to each directory before handling its contents.
FTW_DEPTH
If set, do a depth-first search, that is, call the function for the directory itself only after handling the contents of the direc-
tory and its subdirectories.
FTW_MOUNT
If set, stay within the same file system.
FTW_PHYS
If set, do not follow symbolic links. (This is what you want.) If not set, symbolic links are followed, but no file is reported
twice.
If FTW_PHYS is not set, but FTW_DEPTH is set, then the function fn() is never called for a directory that would be a descendant of itself.
The function fn() is called with four arguments: the pathname of the reported entry, a pointer to a struct stat for this entry, an integer
describing its type, and a pointer to a struct FTW. The type will be one of the following: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS (with
meaning as above; FTW_SL occurs only with FTW_PHYS set) or
FTW_DP Item is a directory and all its descendants have been handled already. (This occurs only with FTW_DEPTH set.)
FTW_SLN
Item is a symbolic link pointing to a nonexisting file. (This occurs only with FTW_PHYS unset.)
The struct FTW pointed at by the fourth argument to fn() has at least the fields base, the offset of the item's filename in the pathname
given as first argument of fn(), and level, the depth of the item relative to the starting point (which has depth 0).
NOTES
The function nftw() and the use of FTW_SL with ftw() were introduced in XPG4v2.
On some systems ftw() will never use FTW_SL, on other systems FTW_SL occurs only for symbolic links that do not point to an existing file,
and again on other systems ftw() will use FTW_SL for each symbolic link. For predictable control, use nftw().
Under Linux, libc4 and libc5 and glibc 2.0.6 will use FTW_F for all objects (files, symbolic links, fifos, etc) that can be stat'ed but are
not a directory. The function nftw() is available since glibc 2.1.
CONFORMING TO
AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.
SEE ALSO
stat(2)
Linux 1999-06-25 FTW(3)