1 FTW(3C)                  Standard C Library Functions                  FTW(3C)
   2 
   3 
   4 
   5 NAME
   6        ftw, nftw - walk a file tree
   7 
   8 SYNOPSIS
   9        #include <ftw.h>
  10 
  11        int ftw(const char *path, int (*fn) (const char *,
  12             const struct stat *, int), int depth);
  13 
  14 
  15        int nftw(const char *path, int (*fn) (const char *,
  16             const struct stat *, int, struct FTW *), int depth,
  17             int flags);
  18 
  19 
  20 DESCRIPTION
  21        The ftw() function recursively descends the directory hierarchy rooted
  22        in path. For each object in the hierarchy, ftw() calls the user-defined
  23        function fn, passing it a pointer to a null-terminated character string
  24        containing the name of the object, a pointer to a stat structure (see
  25        stat(2)) containing information about the object, and an integer.
  26        Possible values of the integer, defined in the <ftw.h> header, are:
  27 
  28        FTW_F
  29                   The object is a file.
  30 
  31 
  32        FTW_D
  33                   The object is a directory.
  34 
  35 
  36        FTW_DNR
  37                   The object is a directory that cannot be read. Descendants
  38                   of the directory are not processed.
  39 
  40 
  41        FTW_NS
  42                   The stat() function failed on the object because of lack of
  43                   appropriate permission or the object is a symbolic link that
  44                   points to a non-existent file.  The stat buffer passed to fn
  45                   is undefined.
  46 
  47 
  48 
  49        The ftw() function visits a directory before visiting any of its
  50        descendants.
  51 
  52 
  53        The tree traversal continues until the tree is exhausted, an invocation
  54        of fn returns a non-zero value, or some error is detected within ftw()
  55        (such as an I/O error). If the tree is exhausted, ftw() returns 0.  If
  56        fn returns a non-zero value, ftw() stops its tree traversal and returns
  57        whatever value was returned by fn.
  58 
  59 
  60        The  nftw() function is similar to ftw() except that it takes the
  61        additional argument flags, which is a bitwise-inclusive OR of zero or
  62        more of the following flags:
  63 
  64        FTW_CHDIR
  65                     If set, nftw() changes the current working directory to
  66                     each directory as it reports files in that directory. If
  67                     clear, nftw() does not change the current working
  68                     directory.
  69 
  70 
  71        FTW_DEPTH
  72                     If set, nftw() reports all files in a directory before
  73                     reporting the directory itself. If clear, nftw() reports
  74                     any directory before reporting the files in that
  75                     directory.
  76 
  77 
  78        FTW_MOUNT
  79                     If set, nftw() reports only files in the same file system
  80                     as path. If clear, nftw() reports all files encountered
  81                     during the walk.
  82 
  83 
  84        FTW_PHYS
  85                     If set, nftw() performs a physical walk and does not
  86                     follow symbolic links.
  87 
  88 
  89 
  90        If FTW_PHYS is clear and FTW_DEPTH is set, nftw() follows links instead
  91        of reporting them, but does not report any directory that would be a
  92        descendant of itself. If FTW_PHYS is clear and FTW_DEPTH is clear,
  93        nftw() follows links instead of reporting them, but does not report the
  94        contents of any directory that would be a descendant of itself.
  95 
  96 
  97        At each file it encounters, nftw() calls the user-supplied function fn
  98        with four arguments:
  99 
 100            o      The first argument is the pathname of the object.
 101 
 102            o      The second argument is a pointer to the stat buffer
 103                   containing information on the object.
 104 
 105            o      The third argument is an integer giving additional
 106                   information. Its value is one of the following:
 107 
 108 
 109                   FTW_F
 110                              The object is a file.
 111 
 112 
 113                   FTW_D
 114                              The object is a directory.
 115 
 116 
 117                   FTW_DP
 118                              The object is a directory and subdirectories have
 119                              been visited. (This condition only occurs if the
 120                              FTW_DEPTH flag is included in flags.)
 121 
 122 
 123                   FTW_SL
 124                              The object is a symbolic link. (This condition
 125                              only occurs if the FTW_PHYS flag is included in
 126                              flags.)
 127 
 128 
 129                   FTW_SLN
 130                              The object is a symbolic link that points to a
 131                              non-existent file. (This condition only occurs if
 132                              the FTW_PHYS flag is not included in flags.)
 133 
 134 
 135                   FTW_DNR
 136                              The object is a directory that cannot be read.
 137                              The user-defined function fn will not be called
 138                              for any of its descendants.
 139 
 140 
 141                   FTW_NS
 142                              The stat() function failed on the object because
 143                              of lack of appropriate permission. The stat
 144                              buffer passed to fn is undefined.  Failure of
 145                              stat() for any other reason is considered an
 146                              error and nftw() returns 1.
 147 
 148 
 149 
 150            o      The fourth argument is a pointer to an FTW structure that
 151                   contains the following members:
 152 
 153                     int   quit;
 154                     int   base;
 155                     int   level;
 156 
 157                   The quit member has a default value of 0, but can be set to
 158                   the following values:
 159 
 160 
 161                   FTW_SKIP or FTW_PRUNE
 162                              This object and its descendants are pruned from
 163                              the search.
 164 
 165 
 166                   FTW_FOLLOW
 167                              If this object is a symbolic link, follow the
 168                              link to its physical counterpart.
 169 
 170 
 171                   The base member is the offset of the object's filename in
 172                   the pathname passed as the first argument to fn(). The value
 173                   of level indicates the depth relative to the root of the
 174                   walk, where the root level is 0.
 175 
 176                   The results are unspecified if the application-supplied fn()
 177                   function does not preserve the current working directory.
 178 
 179 
 180            Both ftw() and nftw() use one file descriptor for each level in the
 181            tree. The depth argument limits the number of file descriptors
 182            used. If depth is zero or negative, the effect is the same as if it
 183            were 1. It must not be greater than the number of file descriptors
 184            currently available for use.  The ftw() function runs faster if
 185            depth is at least as large as the number of levels in the tree.
 186            Both ftw() and nftw() are able to descend to arbitrary depths in a
 187            file hierarchy and do not fail due to path length limitations
 188            unless either the length of the path name pointed to by the path
 189            argument exceeds {PATH_MAX} requirements, or for ftw(), the
 190            specified depth is less than 2, or for nftw(), the specified depth
 191            is less than 2 and FTW_CHDIR is not set. When ftw() and nftw()
 192            return, they close any file descriptors they have opened; they do
 193            not close any file descriptors that might have been opened by fn.
 194 
 195 RETURN VALUES
 196        If the tree is exhausted, ftw() and nftw() return 0. If the function
 197        pointed to by fn returns a non-zero value, ftw() and nftw() stop their
 198        tree traversal and return whatever value was returned by the function
 199        pointed to by fn. If ftw() and nftw() detect an error,  they return1
 200        and set errno to indicate the error.
 201 
 202 
 203        If ftw() and nftw() encounter an error other than EACCES (see FTW_DNR
 204        and FTW_NS above),  they return1 and set errno to indicate the error.
 205        The external variable errno can contain any error value that is
 206        possible when a directory is opened or when one of the stat functions
 207        is executed on a directory or file.
 208 
 209 ERRORS
 210        The ftw() and nftw() functions will fail if:
 211 
 212        ELOOP
 213                        A loop exists in symbolic links encountered during
 214                        resolution of the path argument
 215 
 216 
 217        ENAMETOOLONG
 218                        The length of the path name pointed to by the path
 219                        argument exceeds {PATH_MAX}, or a path name component
 220                        is longer than {NAME_MAX}.
 221 
 222 
 223        ENOENT
 224                        A component of path does not name an existing file or
 225                        path is an empty string.
 226 
 227 
 228        ENOTDIR
 229                        A component of path is not a directory.
 230 
 231 
 232        EOVERFLOW
 233                        A field in the stat structure cannot be represented
 234                        correctly in the current programming environment for
 235                        one or more files found in the file hierarchy.
 236 
 237 
 238 
 239        The ftw() function will fail if:
 240 
 241        EACCES
 242                        Search permission is denied for any component of path
 243                        or read permission is denied for path.
 244 
 245 
 246        ENAMETOOLONG
 247                        The ftw() function has descended to a path that exceeds
 248                        {PATH_MAX} and the depth argument specified by the
 249                        application is less than 2 and FTW_CHDIR is not set.
 250 
 251 
 252 
 253        The nftw() function will fail if:
 254 
 255        EACCES
 256                  Search permission is denied for any component of path or read
 257                  permission is denied for path, or fn() returns 1 and does not
 258                  reset errno.
 259 
 260 
 261 
 262        The nftw() and ftw() functions may fail if:
 263 
 264        ELOOP
 265                        Too many symbolic links were encountered during
 266                        resolution of the path argument.
 267 
 268 
 269        ENAMETOOLONG
 270                        Pathname resolution of a symbolic link in the path name
 271                        pointed to by the path argument produced an
 272                        intermediate result whose length exceeds {PATH_MAX}.
 273 
 274 
 275 
 276        The ftw() function may fail if:
 277 
 278        EINVAL
 279                  The value of the depth argument is invalid.
 280 
 281 
 282 
 283        The nftw() function may fail if:
 284 
 285        EMFILE
 286                  There are {OPEN_MAX} file descriptors currently open in the
 287                  calling process.
 288 
 289 
 290        ENFILE
 291                  Too many files are currently open in the system.
 292 
 293 
 294 
 295        If the function pointed to by fn encounters system errors, errno may be
 296        set accordingly.
 297 
 298 EXAMPLES
 299        Example 1 Walk a directory structure using ftw().
 300 
 301 
 302        The following example walks the current directory structure, calling
 303        the fn() function for every directory entry, using at most 10 file
 304        descriptors:
 305 
 306 
 307          #include <ftw.h>
 308          ...
 309          if (ftw(".", fn, 10) != 0) {
 310                 perror("ftw"); exit(2);
 311          }
 312 
 313 
 314        Example 2 Walk a directory structure using nftw().
 315 
 316 
 317        The following example walks the /tmp directory and its subdirectories,
 318        calling the nftw() function for every directory entry, to a maximum of
 319        5 levels deep.
 320 
 321 
 322          #include <ftw.h>
 323          ...
 324          int nftwfunc(const char *, const struct stat *, int, struct FTW *);
 325          int nftwfunc(const char *filename, const struct stat *statptr,
 326                int fileflags, struct FTW *pfwt)
 327          {
 328                return 0;
 329          }
 330          ...
 331          char *startpath = "/tmp";
 332          int depth = 5;
 333          int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
 334          int ret;
 335          ret = nftw(startpath, nftwfunc, depth, flags);
 336 
 337 
 338 USAGE
 339        Because ftw() and nftw() are recursive, they can terminate with a
 340        memory fault when applied by a thread with a small stack to very deep
 341        file structures.
 342 
 343 
 344        The ftw() and nftw() functions allocate resources (memory, file
 345        descriptors) during their operation. If ftw() they are forcibly
 346        terminated, such as by longjmp(3C) being executed by fn or an interrupt
 347        routine, they will not have a chance to free those resources, so they
 348        remain permanently allocated. A safe way to handle interrupts is to
 349        store the fact that an interrupt has occurred and arrange to have fn
 350        return a non-zero value at its next invocation.
 351 
 352 
 353        The ftw() and nftw() functions have transitional interfaces for 64-bit
 354        file offsets.  See lf64(5).
 355 
 356 
 357        The ftw() function is safe in multithreaded applications. The nftw()
 358        function is safe in multithreaded applications when the FTW_CHDIR flag
 359        is not set.
 360 
 361 ATTRIBUTES
 362        See attributes(5) for descriptions of the following attributes:
 363 
 364 
 365 
 366 
 367        +--------------------+-------------------------+
 368        |  ATTRIBUTE TYPE    |     ATTRIBUTE VALUE     |
 369        +--------------------+-------------------------+
 370        |Interface Stability | Standard                |
 371        +--------------------+-------------------------+
 372        |MT-Level            | MT-Safe with exceptions |
 373        +--------------------+-------------------------+
 374 
 375 SEE ALSO
 376        stat(2), longjmp(3C), attributes(5), lf64(5), standards(5)
 377 
 378 
 379 
 380                                January 30, 2007                        FTW(3C)