ftw(3)                                                           ftw(3)

  ftw()

  NAME

    ftw() - walk a file tree

  SYNOPSIS

    #include 

    int ftw (const char *path, int (*fn)(const char *,
             const struct stat *ptr, int flag), int ndirs);

  DESCRIPTION

    The ftw(3) call recursively descends the directory hierarchy rooted in
    path, calling the function pointed to by fn for each object. A null or
    empty string for path is an error. For each call, the function pointed to
    by fn is passed a pointer to the name of the object (a null-terminated
    character string), a pointer to a stat structure that contains information
    about the object, and an integer flag which defines the type of the
    object. Possible values of flag are:

    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_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.

    The ndirs argument specifies the maximum number of file descriptors for
    use by ftw(3) while traversing the tree. The limit is a resource advisory
    for which nftw(3) adjusts itself accordingly. The value of ndirs should be
    between 1 and {OPEN_MAX}. A value of zero allows ftw(3) to use as many
    file descriptors as it needs and can obtain for maximum performance.

    When ftw(3) returns, it closes any directory streams and file descriptors
    it uses, not counting any opened by the function pointed to by fn.

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

  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]
        Insufficient memory.

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

  SEE ALSO

    longjmp(3)

    malloc(3)

    nftw(3)

    opendir(3)

    siglongjmp(3)

    stat(2)

  USAGE NOTES

    The ftw function is not thread safe.

    The ftw function is not async-signal safe.