FTW(3C)                              SysV                              FTW(3C)



NAME
     ftw - walk a file tree

SYNOPSIS
     #include <ftw.h>

     int ftw (path, fn, depth)
     char *path;
     int (*fn) ( );
     int depth;

DESCRIPTION
     ftw recursively descends the directory hierarchy rooted in path.  For
     each object in the hierarchy, ftw calls fn, passing it a pointer to a
     null terminated character string containing the name of the object, a
     pointer to a stat structure [see stat(2)] containing information about
     the object, and an integer.

     The integer passed to the function parameter identifies the file type,
     and it has one of the following values:

     FTW_F     Regular file

     FTW_D     Directory

     FTW_DNR   Directory that cannot be read

     FTW_SL    Symbolic link

     FTW_NS    A file for which the stat(2) function could not be executed
               successfully

     If the integer is FTW_DNR, then the files and subdirectories contained in
     that directory are not processed.

     If the integer is FTW_NS, then the stat structure contents are
     meaningless. An example of a file that causes FTW_NS to be passed to the
     function parameter is a file in a directory for which you have read
     permission but not execute (search) permission.

     ftw visits a directory before visiting any of its descendants.

     The tree traversal continues until the tree is exhausted, an invocation
     of fn returns a nonzero value, or some error is detected within ftw (such
     as an I/O error).  If the tree is exhausted, ftw returns zero.  If fn
     returns a nonzero value, ftw stops its tree traversal and returns
     whatever value was returned by fn.

     ftw uses one file descriptor for each level in the tree.  The depth
     argument limits the number of file descriptors so used.  If depth is zero
     or negative, the effect is the same as if it were 1.  depth must not be
     greater than the number of file descriptors currently available for use.
     ftw will run more quickly if depth is at least as large as the number of
     levels in the tree.  When ftw returns it closes any directory streams and
     file descriptors it uses not counting any opened by user supplied fn
     function.

     Ordinarily, symbolic links are traversed by ftw.  In an AES-compliant
     environment, however, they are not followed and FTW_SL is returned
     instead.

RETURN VALUES
     If the directory hierarchy is completed, the ftw function returns a value
     of 0 (zero). If the function specified by the function parameter returns
     a nonzero value, the ftw function stops its search and returns the value
     that was returned by the function. If the ftw function detects an error,
     a value of -1 is returned and errno is set to indicate the error.

ERRORS
     If the ftw function fails, errno is set to one of the following values:

     [EACCES]  Search permission is denied for any component of the path
               parameter or read permission is denied for the path parameter.

     [ENAMETOOLONG]
               The length of the path string exceeds PATH_MAX, or a pathname
               component is longer than NAME_MAX.

     [ENOENT]  The path parameter points to the name of a file which does not
               exist or points to an empty string.

     [ENOTDIR] A component of the path parameter is not a directory.

SEE ALSO
     stat(2), malloc(3C).

BUGS
     Because ftw is recursive, it is possible for it to terminate with a
     memory fault when applied to very deep file structures.

CAVEAT
     ftw uses malloc(3C) to allocate dynamic storage during its operation.  If
     ftw is forcibly terminated, such as by longjmp being executed by fn or an
     interrupt routine, ftw will not have a chance to free that storage, so it
     will remain permanently allocated.  A safe way to handle interrupts is to
     store the fact that an interrupt has occurred, and arrange to have fn
     return a nonzero value at its next invocation.