Walk a file tree
Synopsis:
#include <ftw.h>
int nftw( const char *path,
int (*fn)( const char *fname,
const struct stat *sbuf,
int flags,
struct FTW *ftw),
int depth,
int flags);
int nftw64( const char *path,
int (*fn)( const char *fname,
const struct stat64 *sbuf,
int flags,
struct FTW *ftw),
int depth,
int flags);
Arguments:
- path
- The path of the directory whose file tree you want to walk.
- fn
- A pointer to a function that you want to call for each file; see below.
- depth
- The maximum number of file descriptors that nftw() can use.
The nftw() function uses one file descriptor for each level
in the tree.
If depth is zero or negative, the effect is the same as if it
were 1.
The depth must not be greater than the number of file descriptors
currently available for use.
The nftw() function is faster if depth is at least as
large as the number of levels in the tree.
- flags
- The value of flags is constructed by the bitwise ORing of
values from the following list, defined in the <ftw.h>
header file.
- FTW_CHDIR
- If set, nftw() changes the current working directory to each
directory as it reports files in that directory.
- FTW_DEPTH
- If set, nftw() reports all files in a directory before
reporting the directory itself (otherwise the directory is reported before
any file it contains).
- FTW_MOUNT
- If set, nftw() only reports files on the same filesystem as path.
- FTW_PHYS
- If set, nftw() performs a physical walk and doesn't follow any symbolic link.
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Note:
These functions are in libc.a, but not in libc.so
(in order to save space).
Description:
The nftw() and nftw64() functions recursively descend the directory
hierarchy identified by path.
The nftw64() function is a large-file support version of nftw().
Note:
In QNX Neutrino 6.6 or later, the large-file support functions and data types
appear in the name space only if you define
_LARGEFILE64_SOURCE when you compile your code.
For more information, see
Classification
in What's in a Function Description?
For each object in the hierarchy,
nftw() calls the user-defined function fn(),
passing to it:
- a pointer to a NULL-terminated character string containing
the name of the object
- a pointer to a stat structure (see
stat())
containing information about the object
- 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 can't be read.
Descendents of the directory aren't processed.
- FTW_DP
- The object is a directory, and its contents have been reported.
See the FTW_DEPTH flag above.
- FTW_NS
- The stat() failed on the object because the
permissions weren't appropriate.
Don't assume that the stat buffer contains valid data.
- FTW_SL
- The object is a symbolic link. See the FTW_PHYS flag above.
- FTW_SLN
- The object is a symbolic link that does not name an existing file.
- a pointer to a FTW structure, which contains the following fields:
- base
- The offset of the objects filename in the pathname passed as the first argument to fn().
- level
- The depth relative to the root of the walk (where the root is level 0).
- quit
- A flag that can be set to control the behavior of nftw()
within the current directory. If assigned, it may be given the following values:
- FTW_SKR
- Skip the remainder of this directory
- FTW_SKD
- If the object is FTW_D, then don't enter into this directory.
The tree traversal continues until the tree is exhausted, an
invocation of fn() returns a nonzero value, or some error is
detected within nftw() (such as an I/O error). If the tree
is exhausted, nftw() returns zero.
If fn() returns a nonzero
value, nftw() stops its tree traversal and returns whatever
value was returned by fn().
When nftw()
returns, it closes any file descriptors it
opened; it doesn't close any file descriptors that may have
been opened by fn().
Returns:
- 0
- Success.
- -1
- An error (other than EACCES) occurred
(errno is set).
Classification:
nftw() is
POSIX 1003.1;
nftw64() is
Large-file support
Safety: |
|
Cancellation point |
Yes |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |
Caveats:
Because nftw() is recursive, it might
terminate with a memory fault when applied to very deep file structures.
This function uses malloc() to allocate dynamic storage during its operation.
If nftw() is forcibly terminated, for example
if longjmp() is executed by fn() or an interrupt routine,
nftw() doesn't 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 interrupt has
occurred, and arrange to have fn() return a nonzero value at
its next invocation.