ultrix man page for ftw

ftw(3)							     Library Functions Manual							    ftw(3)

Name
       ftw - walk a file tree

Syntax
       #include <ftw.h>

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

Description
       The  subroutine	recursively  descends  the  directory  hierarchy rooted in path.  For each object in the hierarchy, calls fn, passing it a
       pointer to a null-terminated character string containing the name of the object, a pointer to a stat structure containing information about
       the object, and an integer.  For further information, see 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 stat 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 the contents
       of the stat structure will be undefined.  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.

       The subroutine 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
       (such as an I/O error).	If the tree is exhausted, returns zero.  If fn returns a nonzero value, stops its tree traversal and returns what-
       ever value was returned by fn.  If detects an error, it returns -1, and sets the error type in errno.

       The  subroutine 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.  The depth must not be greater than the number of file descriptors  cur-
       rently available for use.  The subroutine will run more quickly if depth is at least as large as the number of levels in the tree.

Restrictions
       Because 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.
       The  subroutine	uses to allocate dynamic storage during its operation.	If is forcibly terminated, such as by longjmp being executed by fn
       or an interrupt routine, will not have a chance to free that storage, so it will remain permanently allocated.  A safe way to handle inter-
       rupts is to store the fact that an interrupt has occurred, and arrange to have fn return a nonzero value at its next invocation.

Diagnostics
       [EACCES]       Search permission is denied on a component of path or read permission is denied for path.

       [ENAMETOOLONG] The length of the path string exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX}.

       [ENOENT]       The  path  argument  points to the name of a file which does not exist, or to an empty string and the environment defined is
		      POSIX or SYSTEM_FIVE.

       [ENOTDIR]      A component of path is not a directory.

       [ENOMEM]       Not enough memory was available to complete the file tree walk.

See Also
       stat(2), malloc(3)

																	    ftw(3)