TREEWALK(3) 1988 TREEWALK(3)NAME
ftw, treewalk - tree walk
SYNOPSIS
#include <ftw.h>
ftw(path, function, maxfds)
char *path;
int (*function)(), maxfds;
treewalk(path, function, maxfds, options)
char *path;
int (*function)(), maxfds, options;
DESCRIPTION
The treewalk call descends the directory hierarchy rooted
in path, visiting each node in turn. Visiting a node con
sists of calling the routine function with three argu
ments. The first is the current path name, the second a
pointer to a stat structure containing information about
the path name, and the third a flag value. The declara
tion of the function may be as follows:
#include <sys/stat.h>
function(path, st, flag)
char *path;
struct stat *st;
int flag;
The flag value will be one the following values, as speci
fied in <ftw.h>.
FTW_F a regular file
FTW_D a directory
FTW_D2 second visit to a directory
FTW_DNR an unreadable directory
FTW_NS an unknown type, the stat failed
If the flag value is FTW_NS, the contents of the stat
buffer are undefined.
Maxfds governs the number of file descriptors that tree_
walk may use. If passed as -1, no limit is set. Unless
function needs to open files, -1 is the suggested behav
ior.
Options is a bit mask which changes the behavior of tree_
walk. Its value is set by or'ing together any of the fol
lowing values specified in <ftw.h>.
FTW_CHDIR treewalk may change directories
FTW_DIRLAST visit the node after its
descendents
4, August 1
TREEWALK(3) 1988 TREEWALK(3)
FTW_SYMLINK follow symbolic links
FTW_CHDIR allows treewalk to descend the tree using the
chdir(2) system call. This makes treewalk run much
faster. A side effect of this flag is that all path names
passed to function are relative, not absolute.
By default, treewalk does a depth-first search, visiting
each node before any of its descendents. If function
returns any other value than 0 or -1, treewalk will not
continue, but will return this value to its caller. If
the returned value is -1, treewalk will continue, but no
descendents of the current node will be visited. The
FTW_DIRLAST flag causes treewalk to visit the node again
after all of its descendents have been visited. The sec
ond visit to the directory will call function with the
FTW_D2 flag instead of FTW_D.
If FTW_SYMLINK is set, treewalk will pass the result of a
stat(2) call to function, rather than an lstat(2) call.
In the case of symbolic links pointing to directories,
treewalk will continue down the directory tree pointed to
by the link. If treewalk is unable to indirect through
the link, the node will be ignored and function will not
be called. It should also be noted that if the symbolic
links form a loop, treewalk will not detect this condi
tion.
If treewalk detects any error other than EACCES (see
FTW_NS, FTW_DNR, and FTW_CHDIR, above) or EMFILE (in the
case of running out of file descriptors) it returns -1 to
its caller, leaving errno unchanged.
BUGS
The path string passed to function is the buffer currently
being processed by treewalk and must therefore be copied
before any modifications are made.
HISTORY
The treewalk routine is a superset of the ftw routine as
provided by System V. Ftw is available for compatibility.
SEE ALSOfind(1), getdtablesize(2), stat(2), symlink(2), glob(3)4, August 2
