FTWX(3X)

NAME
ftwx -- file tree walk

SYNOPSIS

#include "ftwx.h"

int ftwx( path, func, depth, flags )
char *path ;
int (*func)() ;
int depth ;
int flags ;

DESCRIPTION

ftwx() is an extension to ftw(3) that optionally follows symbolic links (the default is not to follow them). It recursively descends the directory tree whose root is path. For each object it finds (an object is anything that is in the file system name space, like a directory, a socket, a regular file, a device etc.) it invokes func() passing it a pointer to a string containing the object path name (the first component of the path will be path), a pointer to a stat() structure that contains information about the object, and a flag (of type int). The user function is never invoked for the directory entries "." and "..". Possible flag values are:

FTW_D
    the object is a directory

FTW_DNR
    the object is a directory that is not readable

FTW_F
    the object is not a directory

FTW_NS
    the stat() of the object failed. The value of the pointer passed to the user function is undefined. This flag value will be returned for directory entries of a directory for which execute access is not permitted.

ftwx visits a directory before visiting any of the files in the directory. The tree walk continues until the tree is exhausted, the user function returns a negative value or some error occurs (since -1 indicates an error in ftwx(), the user function should not return that value). If the user function returns a positive value for a directory, that directory is not traversed. Symbolic links are followed if the flag is FTWX_FOLLOW.

The depth argument determines how deep in the tree to go. The original path is at depth 0. If depth is FTWX_ALL, there is no depth limit. However since ftwx() uses a file descriptor for each level of the tree, there is a limit to the tree depth that it can process that depends on the number of available file descriptors.

RETURN VALUES

ftwx() returns 0 if is successful, -1 if an error occurs (errno is set) and the (negative) value returned by the user function if that occurs.

SEE ALSO

ftw(3)