nftw(3)                                                         nftw(3)

  nftw()

  NAME

    nftw() - walk a file tree

  SYNOPSIS

    #include 

    struct FTW {
         int base;
         int level;
    };

    int nftw (const char *path, int (*fn)(const char *,
              const struct stat *, int, struct FTW *), int depth,
              int flag)

  DESCRIPTION

    The nftw(3) call recursively descends the directory hierarchy rooted in
    path, much like ftw(3). However, nftw(3) takes an additional argument
    flag, which is a bitwise inclusive OR of zero or more of these flags:

    FTW_CHDIR
        Changes the current working directory to each directory as it reports
        the files in that directory. If not set, nftw(3) does not change the
        current working directory.

    FTW_DEPTH
        Perform a depth-wise search. If this is set, nftw(3) reports files in
        a directory before reporting the directory itself. Otherwise, nftw(3)
        reports the directory before reporting the files in that directory
        (the same behavior as ftw(3)).

    FTW_MOUNT
        Only report files in the same filesystem as path. If this bit is
        clear, nftw(3) reports all files encountered in the walk.

    FTW_PHYS
        Do a physical walk, ignoring symbolic links. If this bit is clear,
        nftw(3) follows symbolic links instead of reporting them, and does not
        report the same file twice.

    The depth argument is similar to the ftw(3) ndirs argument; it sets the
    maximum number of file descriptors used by nftw(3) while traversing the
    tree. At most one is used per directory level. If depth is 0, limitless
    recursion is allowed.

    For each object it encounters, nftw(3) calls the function pointed to by fn
    with four arguments:

    *     The object's pathname.
    *     A pointer to the stat buffer, containing information on the object.
    *     An integer containing other information. The integer is one of:

          FTW_D
              The object is a directory.

          FTW_DNR
              The object is a directory that cannot be read. In this case,
              children of the directory are not read.

          FTW_DP
              The object is a directory and subdirectories have been visited.
              (This is only reported if the FTW_DEPTH bit is set in the flag.)

          FTW_F
              The object is a file.

          FTW_NS
              The object was not successfully stat(2)'ed. In this case, the
              stat function will contain undefined values. For example, a file
              with read but not execute/search permission can cause this
              value.

          FTW_SL
              The object is a symbolic link. (This is only reported if the
              FTW_PHYS bit is set in the flag.)

          FTW_SLN
              The object is a symbolic link and does not point to an existing
              file. (This is only reported if the FTW_PHYS bit is not set in
              the flag.)
    *     A pointer to an FTW structure: The base value is the offset of the
          object's filename in the pathname passed as the first argument to
          fn(). The level indicates the depth relative to the root of the
          walk; the root level is 0. For example, if path is /, the file /a/b/
          c has a base (offset) of 5 and a level of 3.

    The nftw(3) function uses at most one file descriptor for each level in
    the tree.

  RETURN VALUES

    The ftw(3) function returns 0 when the tree is exhausted. If the function
    pointed to by fn returns a non-zero value or an error (other than
    [EACCES]), the ftw(3) function stops and returns that value. If ftw(3)
    detects an error, it returns -1 and sets errno.

  ERROR VALUES

    The ftw(3) function may fail for the following reasons:

    [EACCES]
        The process does not have permission to read or search a component of
        path.

    [EINVAL]
        The ndirs argument is invalid.

    [ELOOP]
        There were too many symbolic links.

    [ENAMETOOLONG]
        The path is more than {PATH_MAX} characters long, or a path component
        is more than {NAME_MAX} characters long.

    [ENOENT]
        Either a component of path doesn't exist, or path is an empty string.

    [ENOMEM]
        There is not enough memory.

    [ENOTDIR]
        A component of path is not a directory.

  SEE ALSO

    ftw(3)

    opendir(3)

    readdir(2)

    stat(2)

  USAGE NOTES

    The nftw function is not thread safe.

    The nftw function is not async-signal safe.