FTW(3) | Library Functions Manual | FTW(3) |
ftw, nftw
—
traverse (walk) a file tree
#include
<ftw.h>
int
ftw
(const char *path,
int (*fn)(const char *,
const struct stat *ptr, int flag),
int depth);
int
nftw
(const char *path,
int (*fn)(const char *,
const struct stat *ptr, int flag,
struct FTW *), int depth,
int flags);
The
ftw
() and
nftw
() functions traverse (walk) the directory
hierarchy rooted in path. For each object in the
hierarchy, these functions call the function pointed to by
fn. The ftw
() function passes
this function a pointer to a NUL-terminated string containing the name of
the object, a pointer to a stat structure corresponding to the object, and
an integer flag. The nftw
() function passes the
aforementioned arguments plus a pointer to a FTW
structure as defined by ⟨ftw.h⟩ (shown
below):
struct FTW { int base; /* offset of basename into pathname */ int level; /* directory depth relative to starting point */ };
Possible values for the flag passed to fn are:
FTW_F
FTW_D
FTW_DNR
FTW_DP
nftw
()
only).FTW_NS
FTW_SL
FTW_SLN
nftw
()
only).The
ftw
()
function traverses the tree in pre-order. That is, it processes the
directory before the directory's contents.
The depth argument specifies the maximum number of file descriptors to keep open while traversing the tree. It has no effect in this implementation.
The
nftw
()
function has an additional flags argument with the
following possible values:
FTW_PHYS
FTW_MOUNT
nftw
()
traverses the tree in pre-order.nftw
() will change its starting directory. The
current working directory will be restored to its original value before
nftw
() returns.If the tree was traversed successfully, the
ftw
() and nftw
() functions
return 0. If the function pointed to by fn returns a
non-zero value, ftw
() and
nftw
() will stop processing the tree and return the
value from fn. Both functions return -1 if an error is
detected.
The ftw
() and
nftw
() functions may fail and set
errno for any of the errors specified for the library
functions close(2),
open(2),
stat(2),
malloc(3),
opendir(3) and
readdir(3). If the
FTW_CHDIR
flag is set, the
nftw
() function may fail and set
errno for any of the errors specified for
chdir(2). In addition, either function
may fail and set errno as follows:
EINVAL
]OPEN_MAX
.The ftw
() and
nftw
() functions are far more tolerant of symlink
cycles and are lax in reporting errors while accessing the initial path.
When nftw
() is passed
FTW_MOUNT
, it will pass the mount point to the
callback function.
chdir(2), close(2), open(2), stat(2), fts(3), malloc(3), opendir(3), readdir(3), compat(5)
The ftw
() and
nftw
() functions conform to IEEE
Std 1003.1-2001 (“POSIX.1”) and
Version 3 of the Single UNIX Specification
(“SUSv3”).
Prior to MacOS X 10.4 ftw
did not follow
symlinks.
The depth argument is currently ignored.
May 20, 2003 | macOS 14.6 |