ftw(3)ftw(3)NAMEftw - Walks a file tree
SYNOPSIS
#include <ftw.h>
int ftw(
const char *path,
int (*function)(const char *, const struct stat *, int),
int ndirs );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
ftw(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the directory hierarchy to be searched. Specifies the func‐
tion to be invoked for each object in the directory hierarchy. Speci‐
fies the maximum number of directory streams or file descriptors (or
both) available for use by ftw(). This parameter is not used in Tru64
UNIX implementations of ftw().
This parameter must be in the range of 1 to OPEN_MAX.
For backward compatibility with operating system versions prior
to Digital UNIX Version 4.O, ftw() takes a depth argument
instead of ndirs. The depth parameter specifies the directory
depth for the search, but it is not used.
DESCRIPTION
The ftw() function recursively searches the directory hierarchy that
descends from the directory specified by the path parameter.
For each object in the hierarchy, the ftw() function calls the function
specified by the function parameter, passes it a pointer to a null-ter‐
minated 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(2) reference page for more information about this struc‐
ture.)
The integer passed to the function parameter identifies the file type
or condition of the object, and it has one of the following values: A
directory. A directory that cannot be read. A regular file. A file,
other than a symbolic link, for which the stat() function failed. For
example, FTW_NS is passed to function when a file is in a directory
with read permission, but without execute (search) permission. A sym‐
bolic link.
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 meaning‐
less.
The ftw() function finishes processing a directory before processing
any of its files or subdirectories.
The ftw() function uses at most one file descriptor for each level in
the directory hierarchy.
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 other than [EACCES] is detected within the ftw() function
(such as an I/O error).
The ndirs parameter specifies the maximum number of directory streams
or file descriptors (or both) available for use by the ftw() function
while traversing the directory hierarchy. When ftw() returns it closes
any directory streams and file descriptors it uses not counting any
opened by the application-supplied function.
The ftw() function traverses symbolic links encountered in the resolu‐
tion of path, including the final component. Symbolic links encoun‐
tered while walking the directory tree rooted at path are not tra‐
versed.
NOTES
[Tru64 UNIX] When compiled in the X/Open UNIX environment, calls to
the ftw() function are internally renamed by prepending _E to the func‐
tion name. When debugging a module that includes the ftw() function and
for which _XOPEN_SOURCE_EXTENDED has been defined, use _Eftw to refer
to the ftw() call. See standards(5) for information on when the
_XOPEN_SOURCE_EXTENDED macro is defined.
[Tru64 UNIX] The ftw() function is reentrant; care should be taken to
ensure that the function supplied as argument function is also reen‐
trant.
Because the ftw() function is recursive, it is possible for it to ter‐
minate 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 stor‐
age 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 rou‐
tine, 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.
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 the search and returns the value that
was returned by the function.
If the ftw() function detects an error other than [EACCES], a value of
-1 is returned, and errno is set to indicate the error.
ERRORS
If any of the following conditions occurs, the ftw() function sets
errno to the value that corresponds to the condition. Search permis‐
sion is denied for any component of the path parameter or read permis‐
sion is denied for the path parameter. Too many symbolic links were
encountered. The length of the path string exceeds PATH_MAX, or a
pathname component is longer than NAME_MAX while _POSIX_NO_TRUNC is in
effect.
Pathname resolution of a symbolic link produced an intermediate
result whose length exceeds PATH_MAX. The path parameter points
to the name of a file that does not exist or points to an empty
string. A component of the path parameter is not a directory.
[Tru64 UNIX] 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.
SEE ALSO
Functions: stat(2), nftw(3)
Standards: standards(5)ftw(3)