ftw(3) — AIX PS/2 1.2.1



FTW(3,L)                    AIX Technical Reference                    FTW(3,L)



-------------------------------------------------------------------------------
ftw



PURPOSE

Walks a file tree.

LIBRARY

Standard C Library (libc.a)

SYNTAX

#include <ftw.h>




             int ftw (path, fn, depth)   int fn (filename, stat_ptr, file_type)
             char *path;                 char *filename;
             int (*fn) ( );              struct stat *stat_ptr;
             int depth;                  int file_type;



DESCRIPTION

The ftw subroutine recursively searches the directory hierarchy that descends
from the directory specified by the path parameter.

For each file in the hierarchy, the ftw subroutine calls the function specified
by the fn 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.  (For information about the stat
structure, see "stat.h.")

The file_type parameter to fn identifies the file type, and it has one of the
following values:

FTW_F     Regular file
FTW_D     Directory
FTW_DNR   Directory that cannot be read
FTW_NS    A file for which stat 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 fn is a file in a




Processed November 7, 1990         FTW(3,L)                                   1



FTW(3,L)                    AIX Technical Reference                    FTW(3,L)



directory for which you have read permission but not execute (search)
permission.

The ftw subroutine finishes processing a directory before processing any of its
files or subdirectories.

Symbolic links when encountered during the search process are processed
according to the file type of the file to which they are symbolically linked.
Processing of a symbolic link to a directory results in the invocation of fn on
the symbolic link, but processing of the files or subdirectories within the
symbolically linked directory is not done.

Hidden directories encountered during the search process are treated in the
same manner as normal directories.  Each hidden directory component will be
processed in appropriate sequence.

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

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

The ftw subroutine uses 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 subroutine runs faster if the value of the depth parameter
is at least as large as the number of levels in the tree.  However, 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 negative, the
effect is the same as if it were 1.

Because the ftw subroutine 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 subroutine uses the malloc subroutine to allocate dynamic storage
during its operation.  If ftw is terminated prior to its completion, such as by
longjmp being executed by the function specified by the fn parameter or by an
interrupt routine, then ftw 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 fn
parameter return a nonzero value the next time it is called.

ERROR CONDITIONS

The ftw subroutine fails if the following are true:





Processed November 7, 1990         FTW(3,L)                                   2



FTW(3,L)                    AIX Technical Reference                    FTW(3,L)



EACCES    Search permission is denied for any component of path or read
          permission is denied for path.

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

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

ENOTDIR   A component of path is not a directory.

If fn points to a subroutine that encounters errors, additional errno values
may be set.

RELATED INFORMATION

In this book:  "malloc, free, realloc, calloc, valloc, alloca, mallopt,
mallinfo," "setjmp, longjmp, _setjmp, _longjmp," "sigaction, sigvec, signal,"
and "statx, fstatx, stat, fstat, fullstat, ffullstat, lstat."



































Processed November 7, 1990         FTW(3,L)                                   3

Museum

Related Articles