


      FFFFTTTTWWWW((((3333CCCC))))                     ((((UUUUNNNNIIIIXXXX 5555....0000))))                    FFFFTTTTWWWW((((3333CCCC))))



      NNNNAAAAMMMMEEEE
           ftw - walk a file tree

      SSSSYYYYNNNNTTTTAAAAXXXX
           ####iiiinnnncccclllluuuuddddeeee <<<<ffffttttwwww....hhhh>>>>

           iiiinnnntttt ffffttttwwww ((((ppppaaaatttthhhh,,,, ffffnnnn,,,, ddddeeeepppptttthhhh))))
           cccchhhhaaaarrrr ****ppppaaaatttthhhh;;;;
           iiiinnnntttt ((((****ffffnnnn)))) (((( ))));;;;
           iiiinnnntttt ddddeeeepppptttthhhh;;;;

      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
           _F_t_w recursively descends the directory hierarchy rooted in
           _p_a_t_h.  For each object in the hierarchy, _f_t_w calls _f_n,
           passing it a pointer to a null-terminated character string
           containing the name of the object, a pointer to a ssssttttaaaatttt
           structure (see _s_t_a_t(2)) containg 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 _s_t_a_t 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 ssssttttaaaatttt structure will contain garbage.
           An example of an object that would cause FTW_NS to be passed
           to _f_n would be a file in a directory with read but without
           execute (search) permission.

           _F_t_w visits a directory before visiting any of its
           descendants.

           The tree traversal continues until the tree is exhausted, an
           invocation of _f_n returns a nonzero value, or some error is
           detected within _f_t_w (such as an I/O error).  If the tree is
           exhausted, _f_t_w returns zero.  If _f_n returns a nonzero value,
           _f_t_w stops its tree traversal and returns whatever value was
           returned by _f_n.  If _f_t_w detects an error, it returns -1, and
           sets the error type in _e_r_r_n_o.

           _F_t_w uses one file descriptor for each level in the tree.
           The _d_e_p_t_h argument limits the number of file descriptors so
           used.  If _d_e_p_t_h is zero or negative, the effect is the same
           as if it were 1.  _D_e_p_t_h must not be greater than the number
           of file descriptors currently available for use.  _F_t_w will
           run more quickly if _d_e_p_t_h is at least as large as the number
           of levels in the tree.

      SSSSEEEEEEEE AAAALLLLSSSSOOOO
           stat(2), malloc(3C).

      BBBBUUUUGGGGSSSS
           Because _f_t_w is recursive, it is possible for it to terminate



      Page 1                                                   (9010-E)






      FFFFTTTTWWWW((((3333CCCC))))                     ((((UUUUNNNNIIIIXXXX 5555....0000))))                    FFFFTTTTWWWW((((3333CCCC))))



           with a memory fault when applied to very deep file
           structures.
           It could be made to run faster and use less storage on deep
           structures at the cost of considerable complexity.
           _F_t_w uses _m_a_l_l_o_c(3C) to allocate dynamic storage during its
           operation.  If _f_t_w is forcibly terminated, such as by
           _l_o_n_g_j_m_p being executed by _f_n or an interrupt routine, _f_t_w
           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 _f_n return a nonzero value at
           its next invocation.











































      Page 2                                                   (9010-E)



