Standards
Standards / Extensions |
C or C++ |
Dependencies |
XPG4.2
Single UNIX Specification, Version 3
|
both |
|
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <ftw.h>
int nftw(const char *path,
int (*fn)(const char *, const struct stat *, int, struct FTW *),
int fd_limit, int flags);
General description
The nftw()
function recursively descends the directory hierarchy rooted in
path.
It is similar to ftw() except that it takes an additional argument
flags,
which is a bitwise inclusive-OR of zero or more of the following
flags:
- FTW_CHDIR
- 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.
- FTW_DEPTH
- 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.
- FTW_MOUNT
- 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.
- FTW_PHYS
- 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.
At each file it encounters, nftw() calls the
user-supplied function
fn with four arguments:
- the first argument is the pathname of the object.
- the second argument is a pointer to a stat buffer containing information
on the object.
- the third argument is an integer giving additional information.
Its value is one of the following:
- FTW_D
- for a directory
- FTW_DNR
- for a directory
that cannot be read
- FTW_DP
- for a directory
whose subdirectories have been visited. (This condition will only
occur if FTW_DEPTH is included in flags.)
- FTW_F
- for a file
- FTW_NS
- for an object other
than a symbolic link on which stat() could not be successfully executed.
If the object is a symbolic link, and stat() failed, it is unspecified
whether nftw() passes FTW_SL or FTW_NS to the user-supplied function.
- FTW_SL
- for a symbolic
link
- FTW_SLN
- for a symbolic
link that does not name an existing file. (This condition will only
occur if FTW_PHYS is not included in flags.)
- the fourth argument is a pointer to an FTW structure. The value
of base is the offset of the object's filename
in the pathname passed as the first argument to fn().
The value of level indicates depth relative
to the root of the walk, where the root level is 0.
The argument fd_limit limits
the directory depth for the search. At most one file descriptor will
be used for each directory level.
Large
file support for z/OS UNIX files: Large z/OS UNIX files are supported
automatically for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications
must be compiled with the option LANGLVL(LONGLONG) and define the
_LARGE_FILES feature test macro before any headers are included to
enable this function to operate on z/OS UNIX files that are larger
than 2 GB in size. File size and offset fields are enlarged to 63
bits in width. Therefore, any other function operating on the file
is required to define the _LARGE_FILES feature test macro as well.
Special
behavior for C++: Because
C and C++ linkage
conventions are incompatible, nftw() cannot receive a C++ function
pointer as the argument. If you attempt to pass a C++ function
pointer to nftw(), the compiler will flag it as an error. You can
pass a C or C++ function
to nftw() by declaring it as extern "C".
Returned value
nftw() continues until the
first of the following conditions occurs:
- An invocation of fn() returns a nonzero
value, in which case nftw() returns that value.
- The nftw() function detects an error other than EACCES (see FTW_DNR
and FTW_NS above), in which case nftw() returns -1 and sets errno
to indicate the error.
- The tree is exhausted, in which case nftw() returns 0.
If unsuccessful, nftw() sets errno to one of the following
values. All other errnos returned by nftw() are unchanged.
- Error Code
- Description
- 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.
- ELOOP
- Too many symbolic links were encountered.
- EMFILE
- OPEN_MAX file descriptors are currently open in the calling process.
- ENAMETOOLONG
- One of the following error conditions exists:
- Pathname resolution of a symbolic link produced an intermediate
result whose length exceeds PATH_MAX.
- The length of path exceeds PATH_MAX,
or a pathname component is longer than PATH_MAX.
- ENFILE
- Too many files are currently open in the system.
- 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 errno value might also be set if the function fn causes
it to be set.