ftw(3)                     DG/UX 4.30                      ftw(3)



     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.

          Possible values of the integer that is defined in the
          <ftw.h> header file are as follows:

          FTW_F
               for a file

          FTW_D
               for a directory

          FTW_DNR
               for a directory that cannot be read

          FTW_NS
               for an object that stat could not successfully be
               executed for.

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

          The "walk" 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 and returns whatever value was returned by fn.  If
          ftw detects an error, it returns -1, and sets the error type
          in errno.



     Licensed material--property of copyright holder(s)         Page 1

     ftw(3)                     DG/UX 4.30                      ftw(3)



          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 can terminate with a memory
          fault when applied to very deep file structures.

          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.
































     Licensed material--property of copyright holder(s)         Page 2