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 consists of calling the routine function with three arguments. 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 declaration 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 specified 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 treewalk may use. If passed as -1, no limit is set. Unless function needs to open files, -1 is the suggested behavior.

Options is a bit mask which changes the behavior of treewalk. Its value is set by or'ing together any of the following values specified in <ftw.h>.

     FTW_CHDIR    treewalk may change directories
     FTW_DIRLAST    visit the node after its descendents
     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 second 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 condition.

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 ALSO
find(1), getdtablesize(2), stat(2), symlink(2), glob(3)