OSF

NAME

ftw - Walks a file tree

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <ftw.h>

int ftw (
const char ∗path,
int (∗function)(const char ∗, const struct stat ∗, int),
int depth  );

PARAMETERS

pathSpecifies the directory hierarchy to be searched. 

functionSpecifies the file type. 

depthSpecifies the maximum number of file descriptors to be used. 

DESCRIPTION

The ftw() function recursively searches the directory hierarchy that descends from the directory specified by the path parameter. 

For each file in the hierarchy, the ftw() function calls the function specified by the function parameter, passes it a pointer to a null-terminated character string containing the name of the file, a pointer to a stat structure containing information about the file, and an integer. (See the stat() function for more information about this structure.) 

The integer passed to the function parameter identifies the file type, and it has one of the following values:

FTW_FRegular file

FTW_DDirectory

FTW_DNRDirectory that cannot be read

FTW_SLSymbolic link

FTW_NSA file for which the lstat() function could not be executed successfully

If the integer is FTW_DNR, then the files and subdirectories contained in that directory are not processed. 

If the integer is FTW_NS, then the stat structure contents are meaningless. An example of a file that causes FTW_NS to be passed to the function parameter is a file in a directory for which you have read permission but not execute (search) permission. 

The ftw() function finishes processing a directory before processing any of its files or subdirectories. 

The ftw() function continues the search until the directory hierarchy specified by the path parameter is completed, an invocation of the function specified by the function parameter returns a nonzero value, or an error is detected within the ftw() function, such as an I/O error. 

Because the ftw() function is recursive, it is possible for it to terminate with a memory fault due to stack overflow when applied to very deep file structures. 

The ftw() function uses the malloc() function to allocate dynamic storage during its operation. If the ftw() function is terminated prior to its completion, such as by the longjmp() function being executed by the function specified by the function parameter or by an interrupt routine, the ftw() function cannot free that storage. The storage remains allocated. A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have the function specified by the function parameter return a nonzero value the next time it is called. 

The ftw() function traverses symbolic links encountered in the resolution of path, including the final component.  Symbolic links encountered while walking the directory tree rooted at path will not be traversed. 

NOTES

AES Support Level:
Trial use

RETURN VALUES

If the directory hierarchy is completed, the ftw() function returns a value of 0 (zero). If the function specified by the function parameter returns a nonzero value, the ftw() function stops its search and returns the value that was returned by the function.  If the ftw() function detects an error, a value of -1 is returned and errno is set to indicate the error. 

ERRORS

If the ftw() function fails, errno may be set to one of the following values:

[EACCES]Search permission is denied for any component of the path parameter or read permission is denied for the path parameter. 

[ENAMETOOLONG]
The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX. 

[ENOENT]The path parameter points to the name of a file which does not exist or points to an empty string. 

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

[ENOMEM]There is insufficient memory for this operation. 

In addition, if the function pointed to by the function parameter encounters an error, errno may be set accordingly. 

RELATED INFORMATION

Functions: malloc(3), setjmp(3), sigaction(2), stat(2)