FTW(3)                     Library Functions Manual                     FTW(3)

       ftw - walk a file tree

       #include <ftw.h>

       ftw(directory, funcptr, depth)
            char *directory;
            int (*funcptr)();
            int depth;

       #include <sys/stat.h>

       funcptr(item, sb, flag)
            char *item;
            struct stat *sb;
            int flag;

       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
              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.