ftw(3C) ftw(3C)
NAME
ftw, lftw, 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 lftw (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
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 containing the name of the
object, a pointer to a stat structure (see stat(2)) contain-
ing information about the object, and an integer. Possible
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.
Descendants of the directory will not be pro-
cessed.
FTWNS stat 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.
ftw visits a directory before visiting any of its descen-
dants.
The tree traversal continues until the tree is exhausted, an
invocation of fn returns a nonzero value, or some error is
detected within ftw (such as an I/O error). If the tree is
exhausted, ftw returns zero. If fn returns a nonzero value,
ftw stops its tree traversal and returns whatever value was
returned by fn. If ftw detects an error other than EACCES,
it returns -1, and sets the error type in errno.
lftw is identical to ftw except lstat(2) is invoked instead
of stat(2). Using lstat only effects symbolic links.
Page 1 CX/UX Programmer's Reference Manual
ftw(3C) ftw(3C)
Therefore, if an object in the hierarchy is a symbolic link,
then the stat structure passed to the function indicates
that the object is a symbolic link and does not provide
information about the object that the link points to, as ftw
would do. A second side effect is that a symbolic link to a
directory is treated as a symbolic link (and is not
traversed). See NOTES, below.
The function nftw is similar to ftw except that it takes an
additional argument, flags. The flags field is used to
specify:
FTWPHYS Physical walk, does not follow symbolic links.
Otherwise, nftw will follow links but will not
walk down any path that crosses itself.
FTWMOUNT The walk will not cross a mount point.
FTWDEPTH All subdirectories will be visited before the
directory itself.
FTWCHDIR The walk will change to each directory before
reading it.
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;
base is the offset into the pathname of the base name of the
object. level indicates the depth relative to the rest of
the walk, where the root level is zero.
The values of the third argument are as follows:
FTWF The object is a file.
FTWD The object is a directory.
FTWDP The object is a directory and subdirectories
have been visited.
FTWSLN The object is a symbolic link that points to a
non-existent file.
FTWDNR The object is a directory that cannot be read.
fn will not be called for any of its descen-
dants.
Page 2 CX/UX Programmer's Reference Manual
ftw(3C) ftw(3C)
FTWNS stat failed on the object because of lack of
appropriate permission. The stat buffer passed
to fn is undefined. stat failure other than
lack of appropriate permission (EACCES) is con-
sidered an error and nftw will return -1.
These functions use one file descriptor for each level in
the tree. The depth argument limits the number of file
descriptors so used. If depth is zero or negative, the
effect is the same as if it were 1. depth must not be
greater than the number of file descriptors currently avail-
able for use. The functions will run faster if depth is at
least as large as the number of levels in the tree. When
these functions return, they close any file descriptors they
have opened; they do not close any file descriptors that may
have been opened by fn. All file descriptors used by these
functions have the FD_CLOEXEC flag set.
SEE ALSO
stat(2), malloc(3C).
NOTES
Because these functions are recursive, it is possible for
them to terminate with a memory fault when applied to very
deep file structures.
ftw and lftw use malloc(3C) to allocate dynamic storage dur-
ing its operation. If they are forcibly terminated, such as
by longjmp being executed by fn or an interrupt routine,
they will not have a chance to free that storage, so it will
remain permanently allocated. A safe way to handle inter-
rupts is to store the fact that an interrupt has occurred,
and arrange to have fn return a nonzero value at its next
invocation.
lftw is a non-standard interface that is provided only for
compatibility with previous CX/UX releases. Its use is
discouraged; use nftw with the FTWPHYS flag instead.
Page 3 CX/UX Programmer's Reference Manual