# ftw

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           ftw — traverse (walk) a file tree
    


## SYNOPSIS



           #include <ftw.h>
    
           int ftw(const char *_path_ , int (*_fn_)(const char *,
               const struct stat *_ptr_ , int _flag_), int _ndirs_);
    


## DESCRIPTION



           The _ftw_() function shall recursively descend the directory
           hierarchy rooted in _path_.  For each object in the hierarchy, _ftw_()
           shall call the function pointed to by _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, filled in as if _stat_() or _lstat_() had been called to
           retrieve the information. Possible values of the integer, defined
           in the _< ftw.h>_ header, are:
    
           FTW_D     For a directory.
    
           FTW_DNR   For a directory that cannot be read.
    
           FTW_F     For a non-directory file.
    
           FTW_SL    For a symbolic link (but see also FTW_NS below).
    
           FTW_NS    For an object other than a symbolic link on which _stat_()
                     could not successfully be executed. If the object is a
                     symbolic link and _stat_() failed, it is unspecified
                     whether _ftw_() passes FTW_SL or FTW_NS to the user-
                     supplied function.
    
           If the integer is FTW_DNR, descendants of that directory shall not
           be processed. If the integer is FTW_NS, the **stat** structure
           contains undefined values. An example of an object that would
           cause FTW_NS to be passed to the function pointed to by _fn_ would
           be a file in a directory with read but without execute (search)
           permission.
    
           The _ftw_() function shall visit a directory before visiting any of
           its descendants.
    
           The _ftw_() function shall use at most one file descriptor for each
           level in the tree.
    
           The argument _ndirs_ should be in the range [1,{OPEN_MAX}].
    
           The tree traversal shall continue until either the tree is
           exhausted, an invocation of _fn_ returns a non-zero value, or some
           error, other than **[EACCES]** , is detected within _ftw_().
    
           The _ndirs_ argument shall specify the maximum number of directory
           streams or file descriptors or both available for use by _ftw_()
           while traversing the tree. When _ftw_() returns it shall close any
           directory streams and file descriptors it uses not counting any
           opened by the application-supplied _fn_ function.
    
           The results are unspecified if the application-supplied _fn_
           function does not preserve the current working directory.
    
           The _ftw_() function need not be thread-safe.
    


## RETURN VALUE



           If the tree is exhausted, _ftw_() shall return 0. If the function
           pointed to by _fn_ returns a non-zero value, _ftw_() shall stop its
           tree traversal and return whatever value was returned by the
           function pointed to by _fn_.  If _ftw_() detects an error, it shall
           return -1 and set _errno_ to indicate the error.
    
           If _ftw_() encounters an error other than **[EACCES]**(see FTW_DNR and
           FTW_NS above), it shall return -1 and set _errno_ to indicate the
           error. The external variable _errno_ may contain any error value
           that is possible when a directory is opened or when one of the
           _stat_ functions is executed on a directory or file.
    


## ERRORS



           The _ftw_() function shall fail if:
    
           **EACCES** Search permission is denied for any component of _path_ or
                  read permission is denied for _path_.
    
           **ELOOP** A loop exists in symbolic links encountered during
                  resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a component of a pathname is longer than
                  {NAME_MAX}.
    
           **ENOENT** A component of _path_ does not name an existing file or _path_
                  is an empty string.
    
           **ENOTDIR**
                  A component of _path_ names an existing file that is neither
                  a directory nor a symbolic link to a directory.
    
           **EOVERFLOW**
                  A field in the **stat** structure cannot be represented
                  correctly in the current programming environment for one or
                  more files found in the file hierarchy.
    
           The _ftw_() function may fail if:
    
           **EINVAL** The value of the _ndirs_ argument is invalid.
    
           **ELOOP** More than {SYMLOOP_MAX} symbolic links were encountered
                  during resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a pathname exceeds {PATH_MAX}, or pathname
                  resolution of a symbolic link produced an intermediate
                  result with a length that exceeds {PATH_MAX}.
    
           In addition, if the function pointed to by _fn_ encounters system
           errors, _errno_ may be set accordingly.
    
           _The following sections are informative._
    


## EXAMPLES



       **Walking a Directory Structure**
           The following example walks the current directory structure,
           calling the _fn_ function for every directory entry, using at most
           10 file descriptors:
    
               #include <ftw.h>
               ...
               if (ftw(".", fn, 10) != 0) {
                   perror("ftw"); exit(2);
               }
    


## APPLICATION USAGE



           The _ftw_() function may allocate dynamic storage during its
           operation. If _ftw_() is forcibly terminated, such as by _longjmp_()
           or _siglongjmp_() being executed by the function pointed to by _fn_ or
           an interrupt routine, _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 the function pointed to by _fn_ return a non-
           zero value at its next invocation.
    
           Applications should use the _nftw_() function instead of the
           obsolescent _ftw_() function.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           The _ftw_() function may be removed in a future version.
    


* * *