FTWX

Section: Miscellaneous Library Functions (3X)
Updated: 25 January 1992
Index Return to Main Contents

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.