nftw(3C)
NAME
ftw, nftw - walk a file tree
SYNOPSIS
#include <ftw.h>
int ftw(const char *path, int (*fn) (const char *, const
struct stat *, int), int depth);
int nftw(const char *path, int (*fn) (const char *, const
struct stat *, int, struct FTW *), int depth, int flags);
DESCRIPTION
The ftw() function recursively descends the directory
hierarchy rooted in path. For each object in the hierarchy,
ftw() calls the user-defined function fn, passing it a
pointer to a null-terminated character string containing the
name of the object, a pointer to a stat structure (see
stat(2)) containing information about the object, and an
integer. Possible values of the integer, defined in the
<ftw.h> header, are:
FTW_F The object is a file.
FTW_D The object is a directory.
FTW_DNR
The object is a directory that cannot be read. Descen-
dants of the directory are not processed.
FTW_NS
The stat() function failed on the object because of
lack of appropriate permission or the object is a sym-
bolic link that points to a non-existent file. The
stat buffer passed to fn is undefined.
The ftw() function visits a directory before visiting any of
its descendants.
The tree traversal continues until the tree is exhausted, an
invocation of fn returns a non-zero value, or some error is
detected within ftw() (such as an I/O error). If the tree is
exhausted, ftw() returns 0. If fn returns a non-zero value,
ftw() stops its tree traversal and returns whatever value
was returned by fn.
The nftw() function is similar to ftw() except that it
takes the additional argument flags, which is a bitwise-
inclusive OR of zero or more of the following flags:
FTW_CHDIR
If set, nftw() changes the current working directory
to each directory as it reports files in that direc-
tory. If clear, nftw() does not change the current
working directory.
FTW_DEPTH
If set, nftw() reports all files in a directory before
reporting the directory itself. If clear, nftw()
reports any directory before reporting the files in
that directory.
FTW_MOUNT
If set, nftw() reports only files in the same file
system as path. If clear, nftw() reports all files
encountered during the walk.
FTW_PHYS
If set, nftw() performs a physical walk and does not
follow symbolic links.
If FTW_PHYS is clear and FTW_DEPTH is set, nftw() follows
links instead of reporting them, but does not report any
directory that would be a descendant of itself. If FTW_PHYS
is clear and FTW_DEPTH is clear, nftw() follows links
instead of reporting them, but does not report the contents
of any directory that would be a descendant of itself.
At each file it encounters, nftw() calls the user-supplied
function fn with four arguments:
o The first argument is the pathname of the object.
o The second argument is a pointer to the stat buffer
containing information on the object.
o The third argument is an integer giving additional
information. Its value is one of the following:
FTW_F The object is a file.
FTW_D The object is a directory.
FTW_DP
The object is a directory and subdirectories
have been visited. (This condition only occurs
if the FTW_DEPTH flag is included in flags.)
FTW_SL
The object is a symbolic link. (This condition
only occurs if the FTW_PHYS flag is included in
flags.)
FTW_SLN
The object is a symbolic link that points to a
non-existent file. (This condition only occurs
if the FTW_PHYS flag is not included in flags.)
FTW_DNR
The object is a directory that cannot be read.
The user-defined function fn will not be called
for any of its descendants.
FTW_NS
The stat() function failed on the object because
of lack of appropriate permission. The stat
buffer passed to fn is undefined. Failure of
stat() for any other reason is considered an
error and nftw() returns -1.
o The fourth argument is a pointer to an FTW structure
that contains the following members:
int base;
int level;
The base member is the offset of the object's filename in
the pathname passed as the first argument to fn(). The value
of level indicates the depth relative to the root of the
walk, where the root level is 0.
Both ftw() and nftw() use one file descriptor for each level
in the tree. The depth argument limits the number of file
descriptors used. If depth is zero or negative, the effect
is the same as if it were 1. It must not be greater than the
number of file descriptors currently available for use. The
ftw() function runs faster if depth is at least as large as
the number of levels in the tree. When ftw() and nftw()
return, they close any file descriptors they have opened;
they do not close any file descriptors that might have been
opened by fn.
RETURN VALUES
If the tree is exhausted, ftw() and nftw() return 0. If the
function pointed to by fn returns a non-zero value, ftw()
and nftw() stop their tree traversal and return whatever
value was returned by the function pointed to by fn. If
ftw() and nftw() detect an error, they return -1 and set
errno to indicate the error.
If ftw() and nftw() encounter an error other than EACCES
(see FTW_DNR and FTW_NS above), they return -1 and set
errno to indicate the error. The external variable errno can
contain any error value that is possible when a directory is
opened or when one of the stat functions is executed on a
directory or file.
ERRORS
The ftw() and nftw() functions will fail if:
ELOOP A loop exists in symbolic links encountered during
resolution of the path argument
ENAMETOOLONG
The length of the path exceeds {PATH_MAX}, or a path
name component is longer than {NAME_MAX}.
ENOENT
A component of path does not name an existing file or
path is an empty string.
ENOTDIR
A component of path is not a directory.
EOVERFLOW
A field in the stat structure cannot be represented
correctly in the current programming environment for
one or more files found in the file hierarchy.
The ftw() function will fail if:
EACCES
Search permission is denied for any component of path
or read permission is denied for path.
The nftw() function will fail if:
EACCES
Search permission is denied for any component of path
or read permission is denied for path, or fn() returns
-1 and does not reset errno.
The nftw() and ftw() functions may fail if:
ELOOP Too many symbolic links were encountered during reso-
lution of the path argument.
ENAMETOOLONG
Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds {PATH_MAX}.
The ftw() function may fail if:
EINVAL
The value of the ndirs argument is invalid.
The nftw() function may fail if:
EMFILE
There are {OPEN_MAX} file descriptors currently open
in the calling process.
ENFILE
Too many files are currently open in the system.
If the function pointed to by fn encounters system errors,
errno may be set accordingly.
EXAMPLES
Example 1: Walk a directory structure using ftw().
The following example walks the current directory structure,
calling the fn() function for every directory entry, using
at most 10 file descriptors:
#include <ftw.h>
...
if (ftw(".", fn, 10) != 0) {
perror("ftw"); exit(2);
}
Example 2: Walk a directory structure using nftw().
The following example walks the /tmp directory and its sub-
directories, calling the nftw() function for every directory
entry, to a maximum of 5 levels deep.
#include <ftw.h>
...
int nftwfunc(const char *, const struct stat *, int, struct FTW *);
int nftwfunc(const char *filename, const struct stat *statptr,
int fileflags, struct FTW *pfwt)
{
return 0;
}
...
char *startpath = "/tmp";
int depth = 5;
int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
int ret;
ret = nftw(startpath, nftwfunc, depth, flags);
USAGE
Because ftw() is recursive, it can terminate with a memory
fault when applied to very deep file structures.
The ftw() function uses malloc(3C) to allocate dynamic
storage during its operation. If ftw() is forcibly
terminated, such as by longjmp(3C) being executed by fn or
an interrupt routine, ftw() will not have a chance to free
that storage, so it remains permanently allocated. A safe
way to handle interrupts is to store the fact that an inter-
rupt has occurred and arrange to have fn return a non-zero
value at its next invocation.
The ftw() and nftw() functions have transitional interfaces
for 64-bit file offsets. See lf64(5).
The ftw() function is safe in multithreaded applications.
The nftw() function is safe in multithreaded applications
when the FTW_CHDIR flag is not set.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Standard |
|_____________________________|_____________________________|
| MT-Level | Safe with exceptions |
|_____________________________|_____________________________|
SEE ALSO
stat(2), longjmp(3C), malloc(3C), attributes(5), lf64(5),
standards(5)
Man(1) output converted with
man2html