ftw()

NAME

ftw() - walk a file tree

SYNOPSIS

#include <ftw.h>


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. Since symbolic links are not supported under INTERIX, this is unlikely to occur.

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. Since symbolic links are not supported on INTERIX, this error should not occur.

[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(2)

siglongjmp(3)

stat(2)