ftw(3C) ftw(3C)
NAME
ftw, nftw, ftw64, nftw64 - walk a file tree
SYNOPSIS
#include <ftw.h>
int ftw(const char *path,
int (*fn) (const char *, const struct stat *ptr, int flag),
int ndirs);
int nftw(const char *path,
int (*fn) (const char *, const struct stat *, int, struct FTW *),
int depth, int flags);
int ftw64(const char *path,
int (*fn) (const char *, const struct stat64 *, int), int ndirs);
int nftw64(const char *path,
int (*fn) (const char *, const struct stat64 *, int, struct FTW *),
int depth, int flags);
DESCRIPTION
ftw() 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 con-
taining the name of the object, a pointer to a stat structure [see
stat(2)] containing information about the object, and an integer. Pos-
sible values of the integer, defined in the ftw.h header file, are:
FTWF The object is a file.
FTWD The object is a directory.
FTWDNR The object is a directory that cannot be read. Descen-
dants of the directory will not be processed.
FTWSL A symbolic link (but see also FTWNS below).
FTWNS An object other than a symbolic link on which stat()
could not successfully be executed. If the object is a
symbolic link and stat() failed, it is unspecified
whether ftw() passes FTWSL or FTWNS to the user-
supplied function.
If the integer is FTWDNR, descendants of that directory will not be
processed. If the integer is FTWNS, the stat structure will contain
undefined values. An example of an object that would cause FTWNS to
be passed to the function pointed to by fn would be a file in a direc-
tory with read but without execute (search) permission.
The ftw() function visits a directory before visiting any of its des-
cendants.
Page 1 Reliant UNIX 5.44 Printed 11/98
ftw(3C) ftw(3C)
The ftw() function uses at most one file descriptor for each level in
the tree.
The argument ndirs should be in the range of 1 to OPENMAX.
The tree traversal continues until the tree is exhausted, an invoca-
tion of fn returns a non-zero value, or some error, other than EACCES,
is detected within ftw().
The ndirs argument specifies the maximum number of directory streams
or file descriptors or both available for use by ftw() while travers-
ing the tree. When ftw() returns it closes any directory streams and
file descriptors it uses not counting any opened by the application-
supplied fn function.
The function nftw() is similar to ftw() except that it takes an addi-
tional argument, flags, which is a bitwise inclusive-OR of zero or
more of the following flags:
FTWCHDIR If set, nftw() will change the current working directory
to each directory as it reports files in that directory.
If clear, nftw() will not change the current working
directory.
FTWDEPTH If set, nftw() will report all files in a directory
before reporting the directory itself. If clear, nftw()
will report any directory before reporting the files in
that directory.
FTWMOUNT If set, nftw() will only report files in the same file
system as path. If clear, nftw() will report all files
encountered during the walk.
FTWNONFS If set, nftw() does not go into directories that have
been mounted with NFS. If nftw() is started with this
option in an NFS directory, it ends without performing
any action.
FTWPHYS If set, nftw() performs a physical walk and does not
follow symbolic links. If clear, nftw() will follow
links instead of reporting them, and will not report the
same file twice.
The function nftw() calls fn with four arguments at each file and
directory. The first argument is the pathname of the object, the
second is a pointer to the stat buffer, the third is an integer giving
additional information, and the fourth is a struct FTW that contains
the following members:
int base;
int level;
Page 2 Reliant UNIX 5.44 Printed 11/98
ftw(3C) ftw(3C)
base is the offset into the pathname of the base name of the object.
level specifies which levels in the hierarchy have already been
traversed, and which are still to visit. The lowest level has the
value 0.
The meanings of the third argument values are as follows:
FTWF The object is a file.
FTWD The object is a directory.
FTWDP The object is a directory and subdirectories have
already been traversed. (This condition will only occur
if the FTWDEPTH flag is included in flags.)
FTWSL The object is a symbolic link. (This condition will only
occur if the FTWPHYS flag is included in flags.)
FTWSLN The object is a symbolic link that points to a non-
existent file. (This condition will only occur if the
FTWPHYS flag is not included in flags.)
FTWDNR The object is a directory that cannot be read. fn will
not be called for any of its descendants.
FTWNS stat cannot process the object because of lack of
appropriate permission. The stat buffer passed to fn is
undefined. stat failures for other reasons are con-
sidered an error and nftw() will return -1.
The depth argument sets the maximum number of file descriptors that
will be used by nftw() while traversing the file tree. At most one
file descriptor will be used for each directory level.
There is no functional difference between ftw()/nftw() and
ftw64()/nftw64(), except for the interpretation of stat/stat64 [see
stat(5)].
RETURN VALUE
If the tree is exhausted, ftw() returns 0. If the function pointed to
by fn returns a non-zero value, ftw() stops its tree traversal and
returns whatever value was returned by the function pointed to by fn.
If ftw() detects an error, it returns -1 and sets errno to indicate
the error.
If ftw() encounters an error other than EACCES (see FTWDNR and FTWNS
above), it returns -1 and errno is set to indicate the error. The
external variable errno may contain any error value that is possible
when a directory is opened or when one of the stat functions is exe-
cuted on a directory or file.
The same applies for the nftw() function.
Page 3 Reliant UNIX 5.44 Printed 11/98
ftw(3C) ftw(3C)
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
The ftw() and nftw() function will fail if:
ENAMETOOLONG The length of the path exceeds PATHMAX, or a pathname
component is longer than NAMEMAX.
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.
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 ftw() and nftw() function may fail if:
ELOOP Too many symbolic links were encountered in resolving path.
ENAMETOOLONG Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds PATHMAX.
The ftw() function may fail if:
EINVAL The value of the ndirs argument is invalid.
The nftw() function may fail if:
EMFILE OPENMAX file descriptors are currently open in the cal-
ling process.
ENFILE Too many files are currently open in the system.
In addition, if the function pointed to by fn encounters system
errors, errno may be set accordingly.
NOTES
Because ftw() is recursive, it is possible for it to terminate with a
memory fault when applied to file trees which have too many hierarchi-
cal levels, ftw() uses malloc(3C) to allocate dynamic storage during
its operation. If ftw() is forcibly terminated, such as by longjmp()
being executed by fn or an interrupt routine, ftw() will not have a
Page 4 Reliant UNIX 5.44 Printed 11/98
ftw(3C) ftw(3C)
chance to free that storage, so it will remain permanently allocated.
Interrupts can be handled by arranging that fn returns a nonzero value
at its next invocation.
SEE ALSO
stat(2), malloc(3C), ftw(5), lfs(5), stat(5).
Page 5 Reliant UNIX 5.44 Printed 11/98