FTW(S)                   XENIX System V                    FTW(S)



     Name
          ftw - Walks a file tree.

     Syntax
          #include <ftw.h>

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

     Description
          ftw recursively descends the directory hierarchy routed in
          path.  For each object in the hierarchy, ftw calls fn,
          passing it a pointer to a null-terminated character string.
          This string contains the name of the object, a pointer to a
          stat structure with information about the object, and an
          integer.  Possible values for the integer include 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 stat
          could not be successfully executed.  These values are
          defined in the <ftw.h> header file.  If the integer is
          FTW_DNR, descendants of the directory will not be processed.
          If the integer is FTW_NS, the stat structure will contain
          meaningless information.  For example, a file in a directory
          with read but without execute permission could cause FTW_FN
          to be passed to fn.

          ftw visits a directory before visiting any of its
          descendants.  The file tree traversal continues until the
          tree is exhausted, fn returns a nonzero value, or some error
          is detected within ftw (for example, an I/O error).  If the
          file tree is exhausted, ftw returns zero.  If fn returns a
          nonzero value, ftw stops traversing the file tree and
          returns the value 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.
          depth limits the number of file descriptors. This argument
          must not be greater than the number of file descriptors
          currently available for use.  Zero or negative values for
          depth are interpreted as 1.  ftw will run more quickly if
          depth is at least as large as the number of levels in the
          tree.

     See Also
          stat(S), malloc(S)

     Notes
          Because ftw is recursive, it can terminate with a memory
          fault when applied to very deep file structures.




     Page 1                                           (printed 8/7/87)

     FTW(S)                   XENIX System V                    FTW(S)



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















































     Page 2                                           (printed 8/7/87)