FTW(3)

NAME
ftw - walk a file tree

SYNOPSIS
#include <ftw.h>
int
ftw(directory, funcptr, depth)
	char *directory;
	int (*funcptr)();
	int depth;
#include <sys/stat.h>
int
funcptr(item, sb, flag)
	char *item;
	struct stat *sb;
	int flag;

DESCRIPTION
Ftw walks through the directory tree starting from the indicated path. For every entry it finds in the tree, it calls the user-supplied funcptr with the calling sequence given in the synopsis above. The first argument is the full pathname of the entry (rooted from the directory parameter given to ftw); the second argument is a pointer to the stat(2) structure for the entry; and the third argument is one of the #define's in the header file. This value will be one of the following:
    FTW_F	Item is a normal file
    FTW_D	Item is a directory
    FTW_NS	The stat failed on the item
    FTW_DNR	Item is a directory which can't be read
Note, however, that FTW_F is a misnomer; anything other than directories are (e.g., symbolic links) get the FTW_F tag.

Ftw recursively calls itself when it encounters a directory. To avoid using up all a program's file descriptors, the depth argument specifies the number of simultaneous open directories to maintain. When the depth is exceeded, the routine will become noticeably slower because directories are closed in ``most-recently-used'' order.

To stop the tree walk, the user-supplied function should return a non-zero value; this value will become the return value of ftw. Otherwise, ftw will continue until it has scanned the entire tree, in which case it will return zero, or until it hits an error 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 interrupts, for example, mark that the interrupt occured and return a non-zero value— don't use longjmp (3) unless the program is going to terminate.

SEE ALSO
stat(2)