Walks a file tree.
Format
#include <ftw.h>
int ftw (const char *path, int(*function)(const char *, const
struct stat *, int), int depth);
1 – Arguments
path
The directory hierarchy to be searched.
function
The function to be invoked for each file in the directory
hierarchy.
depth
The maximum number of directory streams or file descriptors, or
both, available for use by ftw. This argument should be in the
range of 1 to OPEN_MAX.
2 – Description
The ftw function recursively searches the directory hierarchy
that descends from the directory specified by the path argument.
The path argument can be specified in OpenVMS style or UNIX
style.
For each file in the hierarchy, ftw calls the function specified
by the function argument, 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.
The integer identifies the file type. Possible values, defined in
<ftw.h> are:
FTW_F Regular file.
FTW_D Directory.
FTW_DNR Directory that cannot be read.
FTW_NS A file on which stat could not successfully be
executed.
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. For example, a file in a directory for which you
have read permission but not execute (search) permission can
cause the function argument to pass FTW_NS.
The ftw function finishes processing a directory before
processing any of its files or subdirectories.
The ftw function continues the search until:
o The directory hierarchy specified by the path argument is
completed.
o An invocation of the function specified by the function
argument returns a nonzero value.
o An error (such as an I/O error) is detected within the ftw
function.
Because the ftw function is recursive, it is possible for it
to terminate with a memory fault because of stack overflow when
applied to very deep file structures.
The ftw function uses the malloc function to allocate dynamic
storage during its operation. If ftw is forcibly terminated,
as with a call to longjmp from the function pointed to by the
function argument, ftw has no chance to free that storage. It
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 argument return a nonzero value the
next time it is called.
NOTES
o The ftw function is reentrant; make sure that the
function supplied as argument function is also reentrant.
o The C RTL supports a standard-compliant definition of the
stat structure and associated definitions. To use them,
compile your application with the _USE_STD_STAT feature-
test macro defined. See the <stat.h> header file on your
system for more information.
o The ftw function supports UNIX style path name
specifications.
See also malloc, longjump, and stat.
3 – Return Values
0 Indicates success.
x Indicates that the function specified by
the function argument stops its search, and
returns the value that was returned by the
function.
-1 Indicates an error; errno is set to one of the
following values:
o EACCES - Search permission is denied for
any component of the path argument or read
permission is denied for the path argument.
o ENAMETOOLONG - 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.
o ENOENT - The path argument points to the
name of a file that does not exist or
points to an empty string.
o ENOMEM - There is insufficient memory for
this operation.
Also, if the function pointed to by the
function argument encounters an error, errno
can be set accordingly.