FTW(3C-SVR3)        RISC/os Reference Manual         FTW(3C-SVR3)



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, pass-
     ing it a pointer to a null-terminated character string con-
     taining the name of the object, a pointer to a stat struc-
     ture [see stat(2)] containing information about the object,
     and an integer.  Possible values of the integer, defined in
     the <ftw.h> header file, are FTW_F for a file, FTW_D for a
     directory, FTW_DNR for a directory that cannot be read, and
     FTW_NS for an object for which lstat could not successfully
     be executed.  If the integer is FTW_DNR, descendants of that
     directory will not be processed.  If the integer is FTW_NS,
     the stat structure will contain garbage.  An example of an
     object that would cause FTW_NS to be passed to fn would be a
     file in a directory with read but without execute (search)
     permission.

     ftw visits a directory before visiting any of its descen-
     dants.

     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.  If ftw detects an error, it returns -1, and
     sets the error type in errno.

     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.

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

BUGS
     Because ftw is recursive, it is possible for it to terminate



                        Printed 11/19/92                   Page 1

FTW(3C-SVR3)        RISC/os Reference Manual         FTW(3C-SVR3)



     with a memory fault when applied to very deep file struc-
     tures.

CAVEATS
     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 inter-
     rupts is to store the fact that an interrupt has occurred,
     and arrange to have fn return a nonzero value at its next
     invocation.

     ftw uses lstat (see stat(2)) instead of stat to avoid sym-
     bolic link loops and symbolic links to nonexistent files.








































 Page 2                 Printed 11/19/92