NAME    [Toc]    [Back]

     ftw, nftw - traverse (walk) a file tree

SYNOPSIS    [Toc]    [Back]

     #include <ftw.h>

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

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

DESCRIPTION    [Toc]    [Back]

     These functions are provided for compatibility  with  legacy
code.  New
     code should use the fts(3) functions.

     The ftw() and nftw() functions traverse (walk) the directory
hierarchy
     rooted in path.  For each object  in  the  hierarchy,  these
functions call
     the  function  pointed  to by fn.  The ftw() function passes
this function a
     pointer to a NUL-terminated string containing  the  name  of
the object, a
     pointer to a stat structure corresponding to the object, and
an integer
     flag.  The nftw() function passes the  aforementioned  arguments plus a
     pointer  to a FTW structure as defined by <ftw.h> (shown below):

     struct FTW {
         int base;   /* offset of basename into pathname */
         int level;  /*  directory  depth  relative  to  starting
point */
     };

     Possible values for the flag passed to fn are:

     FTW_F    A regular file.

     FTW_D    A directory being visited in pre-order.

     FTW_DNR   A  directory  which cannot be read.  The directory
will not be descended
 into.

     FTW_DP   A directory being visited in post-order (nftw() only).

     FTW_NS    A file for which no stat(2) information was available.  The contents
 of the stat structure are undefined.

     FTW_SL   A symbolic link.

     FTW_SLN  A symbolic link with a non-existent target  (nftw()
only).

     The  ftw()  function  traverses the tree in pre-order.  That
is, it processes
 the directory before the directory's contents.

     The maxfds argument specifies the maximum number of file descriptors to
     keep  open  while  traversing the tree.  It has no effect in
this implementation.


     The nftw() function has an additional  flags  argument  with
the following
     possible values:

     FTW_PHYS   Physical walk, don't follow symbolic links.

     FTW_MOUNT  The walk will not cross a mount point.

     FTW_DEPTH  Process directories in post-order.  Contents of a
directory
                are visited before the directory itself.  By  default, nftw()
                traverses the tree in pre-order.

     FTW_CHDIR   Change to a directory before reading it.  By default, nftw()
                will change its starting directory.  The  current
working directory
  will  be  restored to its original value
before nftw()
                returns.

RETURN VALUES    [Toc]    [Back]

     If the tree was traversed successfully, the ftw() and nftw()
functions
     return  0.   If the function pointed to by fn returns a nonzero value,
     ftw() and nftw() will stop processing the  tree  and  return
the value from
     fn.  Both functions return -1 if an error is detected.

ERRORS    [Toc]    [Back]

     The  ftw()  and  nftw() functions may fail and set errno for
any of the errors
 specified for the library functions close(2),  open(2),
stat(2),
     malloc(3),  opendir(3)  and  readdir(3).   If the FGTW_CHDIR
flag is set, the
     nftw() function may fail and set errno for any of the errors
specified
     for chdir(2).  In addition, either function may fail and set
errno as
     follows:

     [EINVAL]      The maxfds argument is less than 1 or  greater
than
                   OPEN_MAX.

SEE ALSO    [Toc]    [Back]

     chdir(2),  close(2),  open(2),  stat(2),  fts(3), malloc(3),
opendir(3),
     readdir(3)

STANDARDS    [Toc]    [Back]

     The  ftw()  and  nftw()  functions  conform  to   IEEE   Std
1003.1-2001
     (``POSIX'').

BUGS    [Toc]    [Back]

     The maxfds argument is currently ignored.

OpenBSD      3.6                           May      20,      2003