FTW(3C-SVR4)        RISC/os Reference Manual         FTW(3C-SVR4)



NAME
     ftw, nftw - walk a file tree

SYNOPSIS
     #include <ftw.h>

     int ftw (const char *path, int (*fn) (const char *, const
          struct  stat *, int), int depth);

     int nftw (const char *path, int (*fn) (const char *, const
          struct stat *, int, struct FTW*), int depth, int
          flags);

DESCRIPTION
     ftw recursively descends the directory hierarchy rooted in
     path.  For each object in the hierarchy, ftw calls the
     user-defined function 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)) contain-
     ing information about the object, and an integer.  Possible
     values of the integer, defined in the ftw.h header file,
     are:

     FTW_F       The object is a file.

     FTW_D       The object is a directory.

     FTW_DNR     The object is a directory that cannot be read.
                 Descendants of the directory will not be pro-
                 cessed.

     FTW_NS      stat failed on the object because of lack of
                 appropriate permission or the object is a sym-
                 bolic link that points to a non-existent file.
                 The stat buffer passed to fn is undefined.

     ftw 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 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 other than EACCES,
     it returns -1, and sets the error type in errno.

     The function nftw is similar to ftw except that it takes an
     additional argument, flags.  The flags field is used to
     specify:

     FTW_PHYS    Physical walk, does not follow symbolic links.



                        Printed 11/19/92                   Page 1

FTW(3C-SVR4)        RISC/os Reference Manual         FTW(3C-SVR4)



                 Otherwise, nftw will follow links but will not
                 walk down any path that crosses itself.

     FTW_MOUNT   The walk will not cross a mount point.

     FTW_DEPTH   All subdirectories will be visited before the
                 directory itself.

     FTW_CHDIR   The walk will change to each directory before
                 reading it.

     The function nftw calls fn with four arguments at each file
     and directory.  The first argument is the pathname of the
     object, the second is a pointer to the stat buffer, the
     third is an integer giving additional information, and the
     fourth is a pointer to a struct FTW that contains the fol-
     lowing members:

          int  quit;
          int  base;
          int  level;
     base is the offset into the pathname of the base name of the
     object.  level indicates the depth relative to the rest of
     the walk, where the root level is zero.

     The values of the third argument are as follows:

     FTW_F       The object is a file.

     FTW_D       The object is a directory.

     FTW_DP      The object is a directory and subdirectories
                 have been visited.

     FTW_SLN     The object is a symbolic link that points to a
                 non-existent file.

     FTW_DNR     The object is a directory that cannot be read.
                 fn will not be called for any of its descen-
                 dants.

     FTW_NS      stat failed on the object because of lack of
                 appropriate permission.  The stat buffer passed
                 to fn is undefined.  stat failure other than
                 lack of appropriate permission (EACCES) is con-
                 sidered an error and nftw will return -1.

     Both ftw and nftw use 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



 Page 2                 Printed 11/19/92

FTW(3C-SVR4)        RISC/os Reference Manual         FTW(3C-SVR4)



     available for use.  ftw will run faster if depth is at least
     as large as the number of levels in the tree.  When ftw and
     nftw return, they close any file descriptors they have
     opened; they do not close any file descriptors that may have
     been opened by fn.

SEE ALSO
     stat(2), malloc(3C).

NOTES
     Because ftw is recursive, it is possible for it to terminate
     with a memory fault when applied to very deep file struc-
     tures.

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

































                        Printed 11/19/92                   Page 3