unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

FTW(3)                     Library Functions Manual                     FTW(3)



NAME
       ftw - walk a file tree

SYNOPSIS
       #include <&lt;ftw.h>&gt;

       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(2V))  containing  information
       about  the  object,  and  an  integer.  Possible values of the integer,
       defined in the <&lt;ftw.h>&gt; 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 stat() could not successfully be executed.  If  the
       integer  is  FTW_DNR,  descendants  of  that directory will not be pro-
       cessed.  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 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(2V), malloc(3V)

BUGS
       Because  ftw()  is recursive, it is possible for it to terminate 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.

       ftw() uses malloc(3V) 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.



                               22 November 1987                         FTW(3)