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 direc
tories, handling a directory before its files or subdirec
tories. To avoid using up all a program's file descrip
tors, 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
interrupt occurred and return a non-zero value--don't use
longjmp(3) unless the program is going to terminate.
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 han
dling its contents.
FTW_DEPTH
If set, do a depth-first search, that is, call the
function for the directory itself only after han
dling the contents of the directory and its subdi
rectories.
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 path
name 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).
The function nftw() and the use of FTW_SL with ftw() were
introduced in XPG4v2. Under Linux, libc4 and libc5 and
glibc 2.0.6 will use FTW_F for all objects (files, sym
bolic links, fifos, etc) that can be stat'ed but are not a
directory. First glibc 2.1 supports FTW_SL and nftw().
CONFORMING TO
AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.
SEE ALSO
stat(2)
Man(1) output converted with
man2html