[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1

ftw or ftw64 Subroutine

Purpose

Walks a file tree.

Library

Standard C Library (libc.a)

Syntax

#include <ftw.h>

int ftw (Path, Function, Depth)
char *Path;
int (*Function(const char*, const struct stat*, int);
int Depth;
int ftw64 (Path, Function, Depth)
char *Path;
int (*Function(const char*, const struct stat64*, int);
int Depth;

Description

The ftw and ftw64 subroutines recursively searches the directory hierarchy that descends from the directory specified by the Path parameter.

For each file in the hierarchy, the ftw and ftw64 subroutines call the function specified by the Function parameter. ftw 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. ftw64 passes it a pointer to a null-terminated character string containing the name of the file, a pointer to a stat64 structure containing information about the file, and an integer.

The integer passed to the Function parameter identifies the file type with one of the following values:

FTW_F Regular file
FTW_D Directory
FTW_DNR Directory that cannot be read
FTW_SL Symbolic Link
FTW_NS File for which the stat structure could not be executed successfully

If the integer is FTW-DNR, the files and subdirectories contained in that directory are not processed.

If the integer is FTW-NS, 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 and ftw64 subroutines finish processing a directory before processing any of its files or subdirectories.

The ftw and ftw64 subroutines continue 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 and ftw64 subroutines, such as an I/O error.

The ftw and ftw64 subroutines traverse symbolic links encountered in the resolution of the Path parameter, including the final component. Symbolic links encountered while walking the directory tree rooted at the Path parameter are not traversed.

The ftw and ftw64 subroutines use one file descriptor for each level in the tree. The Depth parameter specifies the maximum number of file descriptors to be used. In general, the ftw and ftw64 subroutines runs faster if the value of the Depth parameter is at least as large as the number of levels in the tree. However, the value of the Depth parameter must not be greater than the number of file descriptors currently available for use. If the value of the Depth parameter is 0 or a negative number, the effect is the same as if it were 1.

Because the ftw and ftw64 subroutines are 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 and ftw64 subroutines use the malloc subroutine to allocate dynamic storage during its operation. If the ftw and ftw64 subroutined is terminated prior to its completion, such as by the longjmp subroutine being executed by the function specified by the Function parameter or by an interrupt routine, the ftw and ftw64 subroutines 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.

Parameters

Path Specifies the directory hierarchy to be searched.
Function Specifies the file type.
Depth Specifies the maximum number of file descriptors to be used. Depth cannot be greater than OPEN_MAX which is described in the sys/limits.h header file.

Return Values

If the tree is exhausted, the ftw and ftw64 subroutines returns a value of 0. If the subroutine pointed to by fn returns a nonzero value, ftw and ftw64 subroutines stops its tree traversal and returns whatever value was returned by the subroutine pointed to by fn. If the ftw and ftw64 subroutines detects an error, it returns a -1 and sets the errno global variable to indicate the error.

Error Codes

If the ftw or ftw64 subroutines detect an error, a value of -1 is returned and the errno global variable is set to indicate the error.

The ftw and ftw64 subroutine are unsuccessful if:

EACCES Search permission is denied for any component of the Path parameter or read permission is denied for Path.
ENAMETOOLONG The length of the path exceeds PATH_MAX while _POSIX_NO_TRUNC is in effect.
ENOENT The Path parameter points to the name of a file that does not exist or points to an empty string.
ENOTDIR A component of the Path parameter is not a directory.

The ftw subroutine is unsuccessful if:

EOVERFLOW A file in Path is of a size larger than 2 Gigabytes.

Implementation Specifics

This subroutines is part of Base Operating System (BOS) Runtime.

Related Information

The malloc, free, realloc, calloc, mallopt, mallinfo, or alloca subroutine, setjmp or longjmp subroutine, signal subroutine, stat subroutine.

Searching and Sorting Example Program and Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Contents | Glossary | Home | Search ]