ftw(S)                         6 January 1993                         ftw(S)


 Name

    ftw - walk a file tree

 Syntax


    cc  . . .  -lc


    #include  <sys/stat.h>
    #include  <ftw.h>

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


 Description

    The ftw function 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(S)) containing informa-
    tion about the object, and an integer.  Possible values of the integer,
    defined in the <ftw.h> header file, are:

         FTWF      file

         FTWD      directory

         FTWDNR    directory that cannot be read

         FTWNS     object for which stat could not successfully be executed

    If the integer is FTWDNR, descendants of that directory are not pro-
    cessed.  If the integer is FTWNS, the stat structure contains garbage.
    An example of an object that would cause FTWNS to be passed to fn would
    be a file in a directory with read but without execute (search) permis-
    sion.

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

    The ftw function uses one file descriptor for each level in the tree.
    The depth argument limits the number of file descriptors 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 runs faster if depth is at least as large as the number of
    levels in the tree.

 Notes

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

    The ftw function uses malloc to allocate dynamic storage during its
    operation.  If ftw is forcibly terminated (for example, if fn or an
    interrupt routine executes longjmp), ftw does not have a chance to free
    that storage, so it remains 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.

 See also

    malloc(S), stat(S)

 Standards conformance

    ftw is conformant with:
    AT&T SVID Issue 2;
    and X/Open Portability Guide, Issue 3, 1989.