NAME
ftw, nftw - 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);
int nftw (
const char *path,
int (*function)(const char *, const struct stat *, int,
struct FTW),
int depth);
int flags);
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.
flags Specifies optional flags that modify the operation
of the nftw() function only.
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_F Regular file
FTW_D Directory
FTW_DNR Directory that cannot be read
FTW_SL Symbolic link
FTW_NS A 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 parame-
ter 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. Sym-
bolic links encountered while walking the directory tree
rooted at path will not be traversed.
The nftw() function provides the same features as does
ftw(), but with the following additional flags:
FTW_PHYS Physically walks the file tree, but does not fol-
low symbolic links. If this flag is not specified,
the nftw() function does follow links, but does
not walk down any path that crosses itself.
FTW_MOUNT Mount points are not crossed during the walk.
FTW_DEPTH All subdirectories are to be visited before the
directory itself.
FTW_CHDIR The walk changes to each directory before reading
its contents.
The nftw() function calls the function parameter with four
arguments at each file and directory. The first argument is
the pathname of the object. The second argument points to
the stat buffer. The third argument identifies all of the
file types used by the ftw() function (see above). In addi-
tion, the nftw() function provides the following file type:
FTW_DP A directory whose directories have been visited.
The fourth argument is a struct FTW. This structure contains
the following members:
int base;
int level;
The value of base is the offset into the pathname of the
object. This pathname is passed as the first argument to
the function parameter. The value of level specifies the
depth relative to the root of the walk, where the root level
has a value of zero.
NOTES
The ftw() function is reentrant, but care should be taken to
ensure that the function supplied as argument function is
also reentrant.
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 indi-
cate 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 while
[_POSIX_NO_TRUNC] is in effect.
[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 direc-
tory.
[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)
Acknowledgement and Disclaimer