Originální popis anglicky:
nftw - walk a file tree
Návod, kniha: POSIX Programmer's Manual
#include <ftw.h>
int nftw(const char *
path, int
(*fn)(const char *,
const struct stat *, int,
struct FTW *), int
depth, int
flags);
The
nftw() function shall recursively descend the directory hierarchy
rooted in
path. The
nftw() function has a similar effect 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() shall change the current working
directory to each directory as it reports files in that directory. If
clear, nftw() shall not change the current working directory.
- FTW_DEPTH
- If set, nftw() shall report all files in a directory
before reporting the directory itself. If clear, nftw() shall
report any directory before reporting the files in that directory.
- FTW_MOUNT
- If set, nftw() shall only report files in the same
file system as path. If clear, nftw() shall report all files
encountered during the walk.
- FTW_PHYS
- If set, nftw() shall perform a physical walk and
shall not follow symbolic links.
If FTW_PHYS is clear and FTW_DEPTH is set,
nftw() shall follow links
instead of reporting them, but shall not report any directory that would be a
descendant of itself. If FTW_PHYS is clear and FTW_DEPTH is clear,
nftw() shall follow links instead of reporting them, but shall not
report the contents of any directory that would be a descendant of itself.
At each file it encounters,
nftw() shall call the user-supplied function
fn with four arguments:
- *
- The first argument is the pathname of the object.
- *
- The second argument is a pointer to the stat buffer
containing information on the object.
- *
- The third argument is an integer giving additional
information. Its value is one of the following:
- FTW_F
The object is a file.
- FTW_D
The object is a directory.
- FTW_DP
The object is a directory and subdirectories
have been visited. (This condition shall only occur if the FTW_DEPTH flag is
included in flags.)
- FTW_SL
The object is a symbolic link. (This condition
shall only occur if the FTW_PHYS flag is included in flags.)
- FTW_SLN
The object is a symbolic link that does not
name an existing file. (This condition shall only occur if the FTW_PHYS flag
is not included in flags.)
- FTW_DNR
The object is a directory that cannot be read.
The fn function shall not be called for any of its descendants.
- FTW_NS
The stat() function failed on the
object because of lack of appropriate permission. The stat buffer
passed to fn is undefined. Failure of stat() for any other
reason is considered an error and nftw() shall return -1.
- *
- 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 results are unspecified if the application-supplied
fn function does
not preserve the current working directory.
The argument
depth sets the maximum number of file descriptors that shall
be used by
nftw() while traversing the file tree. At most one file
descriptor shall be used for each directory level.
The
nftw() function need not be reentrant. A function that is not
required to be reentrant is not required to be thread-safe.
The
nftw() function shall continue until the first of the following
conditions occurs:
- *
- An invocation of fn shall return a non-zero value,
in which case nftw() shall return that value.
- *
- The nftw() function detects an error other than
[EACCES] (see FTW_DNR and FTW_NS above), in which case nftw() shall
return -1 and set errno to indicate the error.
- *
- The tree is exhausted, in which case nftw() shall
return 0.
The
nftw() function shall 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.
- ELOOP
- A loop exists in symbolic links encountered during
resolution of the path argument.
- ENAMETOOLONG
- The length of the path argument exceeds {PATH_MAX}
or a pathname component is longer than {NAME_MAX}.
- 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.
- EOVERFLOW
- A field in the stat structure cannot be represented
correctly in the current programming environment for one or more files
found in the file hierarchy.
The
nftw() function may fail if:
- ELOOP
- More than {SYMLOOP_MAX} symbolic links were encountered
during resolution of the path argument.
- EMFILE
- {OPEN_MAX} file descriptors are currently open in the
calling process.
- ENAMETOOLONG
- Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds {PATH_MAX}.
- ENFILE
- Too many files are currently open in the system.
In addition,
errno may be set if the function pointed to by
fn
causes
errno to be set.
The following sections are informative.
The following example walks the
/tmp directory and its subdirectories,
calling the
nftw() function for every directory entry, to a maximum of
5 levels deep.
#include <ftw.h>
...
int nftwfunc(const char *, const struct stat *, int, struct FTW *);
int nftwfunc(const char *filename, const struct stat *statptr,
int fileflags, struct FTW *pfwt)
{
return 0;
}
...
char *startpath = "/tmp";
int depth = 5;
int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
int ret;
ret = nftw(startpath, nftwfunc, depth, flags);
None.
None.
None.
lstat() ,
opendir() ,
readdir() ,
stat() , the Base
Definitions volume of IEEE Std 1003.1-2001,
<ftw.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard, the original
IEEE and The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.opengroup.org/unix/online.html
.
