huschi.net

NFTW(3P)                   POSIX Programmer's Manual                  NFTW(3P)

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
       nftw - walk a file tree
SYNOPSIS
       #include <ftw.h>
       int nftw(const char *path, int (*fn)(const char *,
              const struct stat *, int, struct FTW *), int depth, int flags);

DESCRIPTION
       The nftw() function shall recursively descend the  directory  hierarchy
       rooted  in  path.  The  nftw()  function  has a similar effect to ftw()
       except that it takes an additional argument flags, which is a  bitwise-
       inclusive OR of zero or more of the following flags:
       FTW_CHDIR
              If  set,  nftw()  shall  change the current working directory to
              each directory as it reports files in that directory. If  clear,
              nftw() shall not change the current working directory.
       FTW_DEPTH
              If  set,  nftw()  shall  report  all files in a directory before
              reporting the directory itself. If clear,  nftw()  shall  report
              any directory before reporting the files in that directory.
       FTW_MOUNT
              If  set,  nftw() shall only report files in the same file system
              as path. If clear, nftw() shall  report  all  files  encountered
              during the walk.
       FTW_PHYS
              If  set, nftw() shall perform a physical walk and shall not fol-
              low symbolic links.

       If FTW_PHYS is clear and FTW_DEPTH is set, nftw()  shall  follow  links
       instead  of  reporting  them,  but  shall not report any directory that
       would be a descendant of itself. If FTW_PHYS is clear and FTW_DEPTH  is
       clear,  nftw()  shall follow links instead of reporting them, but shall
       not report the contents of any directory that would be a descendant  of
       itself.
       At  each  file it encounters, nftw() shall call the user-supplied func-
       tion fn with four arguments:
        * The first argument is the pathname of the object.
        * The second argument is a  pointer  to  the  stat  buffer  containing
          information on the object.
        * 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  shall  only  occur  if  the  FTW_DEPTH flag is
              included in flags.)
       FTW_SL
              The object is a symbolic link. (This condition shall only  occur
              if the FTW_PHYS flag is included in flags.)
       FTW_SLN
              The  object  is  a  symbolic link that does not name an existing
              file.  (This condition shall only occur if the FTW_PHYS flag  is
              not included in flags.)
       FTW_DNR
              The  object  is a directory that cannot be read. The fn function
              shall 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 unde-
              fined. Failure of stat() for any other reason is  considered  an
              error and nftw() shall return -1.

        * The  fourth  argument is a pointer to an FTW structure. The value of
          base is the offset of the object's filename in the  pathname  passed
          as the first argument to fn. The value of level indicates depth rel-
          ative to the root of the walk, where the root level is 0.
       The results are unspecified if  the  application-supplied  fn  function
       does not preserve the current working directory.
       The  argument  depth  sets  the maximum number of file descriptors that
       shall be used by nftw() while traversing the file  tree.  At  most  one
       file descriptor shall be used for each directory level.
       The  nftw()  function  need  not  be  reentrant. A function that is not
       required to be reentrant is not required to be thread-safe.
RETURN VALUE
       The nftw() function shall continue until the  first  of  the  following
       conditions occurs:
        * An  invocation  of  fn  shall return a non-zero value, in which case
          nftw() shall return that value.
        * The nftw() function  detects  an  error  other  than  [EACCES]  (see
          FTW_DNR  and FTW_NS above), in which case nftw() shall return -1 and
          set errno to indicate the error.
        * The tree is exhausted, in which case nftw() shall return 0.
ERRORS
       The nftw() function shall 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.
       ELOOP  A loop exists in symbolic links encountered during resolution of
              the path argument.
       ENAMETOOLONG
              The length of the path argument exceeds {PATH_MAX} or a pathname
              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 nftw() function may fail if:
       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
              resolution of the path argument.
       EMFILE {OPEN_MAX} file descriptors are currently open  in  the  calling
              process.
       ENAMETOOLONG
              Pathname  resolution of a symbolic link produced an intermediate
              result whose length exceeds {PATH_MAX}.
       ENFILE Too many files are currently open in the system.

       In addition, errno may be set if the function pointed to by  fn  causes
       errno to be set.
       The following sections are informative.
EXAMPLES
       The  following example walks the /tmp directory and its subdirectories,
       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);
APPLICATION USAGE
       None.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       lstat(),  opendir(),  readdir(), stat(), the Base Definitions volume of
       IEEE Std 1003.1-2001, <ftw.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                             NFTW(3P)