nftw(3C)




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

     The  ftw()  function  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))  containing  information  about  the object, and an
     integer. Possible values of  the  integer,  defined  in  the
     <ftw.h> header, 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. Descen-
           dants of the directory are not processed.

     FTW_NS
           The stat() function 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.

     The ftw() function visits a directory before visiting any of
     its descendants.

     The tree traversal continues until the tree is exhausted, an
     invocation  of fn returns a non-zero value, or some error is
     detected within ftw() (such as an I/O error). If the tree is
     exhausted,  ftw() returns 0. If fn returns a non-zero value,
     ftw() stops its tree traversal and  returns  whatever  value
     was returned by fn.

     The  nftw() function is similar  to  ftw()  except  that  it
     takes  the  additional  argument  flags, which is a bitwise-
     inclusive OR of zero or more of the following flags:

     FTW_CHDIR
           If set, nftw() changes the current  working  directory
           to  each  directory as it reports files in that direc-
           tory. If clear, nftw() does  not  change  the  current
           working directory.

     FTW_DEPTH
           If set, nftw() reports all files in a directory before
           reporting  the  directory  itself.  If  clear,  nftw()
           reports any directory before reporting  the  files  in
           that directory.

     FTW_MOUNT
           If set, nftw() reports only files  in  the  same  file
           system  as  path.  If  clear, nftw() reports all files
           encountered during the walk.

     FTW_PHYS
           If set, nftw() performs a physical walk and  does  not
           follow symbolic links.

     If FTW_PHYS is clear and FTW_DEPTH is  set,  nftw()  follows
     links  instead  of  reporting  them, but does not report any
     directory that would be a descendant of itself. If  FTW_PHYS
     is  clear  and  FTW_DEPTH  is  clear,  nftw()  follows links
     instead of reporting them, but does not report the  contents
     of any directory that would be a descendant of itself.

     At each file it encounters, nftw() calls  the  user-supplied
     function fn with four arguments:

        o  The first argument is the pathname of the object.

        o  The second argument is a pointer to  the  stat  buffer
           containing information on the object.

        o  The third argument is  an  integer  giving  additional
           information. Its value is one of the following:

           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. (This condition only occurs
                 if the FTW_DEPTH flag is included in flags.)

           FTW_SL
                 The object is a symbolic link.  (This  condition
                 only  occurs if the FTW_PHYS flag is included in
                 flags.)

           FTW_SLN
                 The object is a symbolic link that points  to  a
                 non-existent  file.  (This condition only occurs
                 if the FTW_PHYS flag is not included in flags.)

           FTW_DNR
                 The object is a directory that cannot  be  read.
                 The  user-defined function fn will not be called
                 for any of its descendants.

           FTW_NS
                 The stat() function failed on the object because
                 of  lack  of  appropriate  permission.  The stat
                 buffer passed to fn is  undefined.   Failure  of
                 stat()  for  any  other  reason is considered an
                 error and nftw() returns -1.

        o  The fourth argument is a pointer to an  FTW  structure
           that contains the following members:

     int   base;
     int   level;

     The base member is the offset of the  object's  filename  in
     the pathname passed as the first argument to fn(). The value
     of level indicates the depth relative to  the  root  of  the
     walk, where the root level is 0.

     Both ftw() and nftw() use one file descriptor for each level
     in  the  tree.  The depth argument limits the number of file
     descriptors used. If depth is zero or negative,  the  effect
     is the same as if it were 1. It must not be greater than the
     number of file descriptors currently available for use.  The
     ftw()  function runs 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 might have  been
     opened by fn.


RETURN VALUES

     If the tree is exhausted, ftw() and nftw() return 0. If  the
     function  pointed  to  by fn returns a non-zero value, ftw()
     and nftw() stop their tree  traversal  and  return  whatever
     value  was  returned  by  the  function pointed to by fn. If
     ftw() and nftw() detect an error,  they return  -1  and  set
     errno to indicate the error.

     If ftw() and nftw() encounter an  error  other  than  EACCES
     (see   FTW_DNR  and  FTW_NS  above),  they return -1 and set
     errno to indicate the error. The external variable errno can
     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() and nftw() functions will fail if:

     ELOOP A loop exists in  symbolic  links  encountered  during
           resolution of the path argument

     ENAMETOOLONG
           The length of the path exceeds {PATH_MAX}, or  a  path
           name component 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 is not 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 will fail if:

     EACCES
           Search permission is denied for any component of  path
           or read permission is denied for path.

     The nftw() function will fail if:

     EACCES
           Search permission is denied for any component of  path
           or read permission is denied for path, or fn() returns
           -1 and does not reset errno.

     The nftw() and ftw() functions may fail if:

     ELOOP Too many symbolic links were encountered during  reso-
           lution of the path argument.

     ENAMETOOLONG
           Pathname resolution of a  symbolic  link  produced  an
           intermediate result whose length exceeds {PATH_MAX}.

     The ftw() function may fail if:

     EINVAL
           The value of the ndirs argument is invalid.

     The nftw() function may fail if:

     EMFILE
           There are {OPEN_MAX} file descriptors  currently  open
           in the calling process.

     ENFILE
           Too many files are currently open in the system.

     If the function pointed to by fn encounters  system  errors,
     errno may be set accordingly.


EXAMPLES

     Example 1: Walk a directory structure using ftw().

     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);
     }

     Example 2: Walk a directory structure using nftw().

     The following example walks the /tmp directory and its  sub-
     directories, calling the nftw() function for every directory
     entry, to a maximum of 5 levels deep.

     #include <ftw.h>
     ...
     int nftwfunc(const char *, const struct stat *, int, struct FTW *);
     int nftwfunc(const char *filename, const struct stat *statptr,
           int fileflags, struct FTW *pfwt)
     {
           return 0;
     }
     ...
     char *startpath = "/tmp";
     int depth = 5;
     int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
     int ret;
     ret = nftw(startpath, nftwfunc, depth, flags);


USAGE

     Because ftw() is recursive, it can terminate with  a  memory
     fault when applied to very deep file structures.

     The ftw()  function  uses  malloc(3C)  to  allocate  dynamic
     storage   during   its   operation.  If  ftw()  is  forcibly
     terminated, such as by longjmp(3C) being executed by  fn  or
     an  interrupt  routine, ftw() will 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 inter-
     rupt has occurred and arrange to have fn return  a  non-zero
     value at its next invocation.

     The ftw() and nftw() functions have transitional  interfaces
     for 64-bit file offsets.  See lf64(5).

     The ftw() function is safe  in  multithreaded  applications.
     The  nftw()  function  is safe in multithreaded applications
     when the FTW_CHDIR flag is not set.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe with exceptions        |
    |_____________________________|_____________________________|


SEE ALSO

     stat(2), longjmp(3C),  malloc(3C),  attributes(5),  lf64(5),
     standards(5)


Man(1) output converted with man2html