ftw

Purpose

     Walks a file tree.

Library

     Standard C Library (libc.a)

Syntax

     #include <ftw.h>

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

Description

     The  ftw subroutine  recursively  searches the  directory
     hierarchy that  descends from the directory  specified by
     the path parameter.

     For each file in the  hierarchy, the ftw subroutine calls
     the function specified  by the fn parameter,  passes it a
     pointer to a  null-terminated character string containing
     the name of the file, a  pointer to a stat structure con-
     taining information about the file, and an integer.  (For
     information about the stat structure, see "stat.h.")

     The integer passed to fn identifies the file type, and it
     has one of the following values:

     FTW_F      Regular file
     FTW_D      Directory
     FTW_DNR    Directory that cannot be read
     FTW_NS     A file  for which  stat could not  be executed
                successfully.

     If the integer is FTW_DNR, then the files and subdirecto-
     ries contained in that directory are not processed.

     If the  integer is FTW_NS,  then the stat  structure con-
     tents are meaningless.  An example  of a file that causes
     FTW_NS to  be passed to fn  is a file in  a directory for
     which you  have read permission but  not execute (search)
     permission.

     The ftw subroutine finishes processing a directory before
     processing any of its files or subdirectories.

     The ftw subroutine continues  the search until the direc-
     tory hierarchy  specified by  the path parameter  is com-
     pleted, an invocation of the function specified by the fn
     parameter  returns  a  nonzero  value,  or  an  error  is
     detected within ftw, such as an I/O error.

     If the directory hierarchy  is completed, the ftw subrou-
     tine returns a value of  0.  If the function specified by
     the fn parameter  returns a nonzero value,  ftw stops its
     search and  returns the  value that  was returned  by the
     function.   If the  ftw  subroutine detects  an error,  a
     value of -1 is returned and  errno is set to indicate the
     error.

     The  ftw subroutine  uses  one file  descriptor for  each
     level  in the  tree.  The  depth parameter  specifies the
     maximum  number  of  file  descriptors to  be  used.   In
     general, the ftw  subroutine runs faster if  the value of
     the depth parameter is at least as large as the number of
     levels in  the tree.   However, the depth  parameter must
     not be greater  than the number of  file descriptors cur-
     rently  available for  use.  If  the value  of the  depth
     parameter is 0 or negative, the  effect is the same as if
     it were 1.

     Because the  ftw subroutine is recursive,  it is possible
     for  it to  terminate with  a memory  fault due  to stack
     overflow when applied to very deep file structures.

     The ftw subroutine uses the malloc subroutine to allocate
     dynamic storage  during its operation.  If  ftw is termi-
     nated prior to  its completion, such as  by longjmp being
     executed by the function specified by the fn parameter or
     by  an  interrupt  routine,  then ftw  cannot  free  that
     storage.  The  storage remains allocated.  A  safe way to
     handle interrupts is to store  the fact that an interrupt
     has occurred, and arrange  to have the function specified
     by the fn parameter return  a nonzero value the next time
     it is called.

Related Information

     In this book:  "signal," "malloc, free, realloc, calloc,"
     "setjmp, longjmp," and "stat.h."