nftw - Walk a file tree
#include <ftw.h>
int nftw(
const char *path,
int (*function)(const char *, const struct stat *,
int, struct FTW *),
int depth,
int flags );
The following definition of the nftw() function does not
conform to current standards and is supported only for
backward compatibility:
int nftw(
const char *path,
int (*function)(const char *, const struct stat *,
int, struct FTW),
int depth,
int flags );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
nftw(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies the directory hierarchy to be searched. Specifies
the function to be invoked for each object in the
directory hierarchy. Limits the directory depth for the
search. At most one file descriptor will be used for each
directory level.
In the backward-compatible version of nftw(), this
parameter can be supplied but is not used. Specifies
optional options that modify the operation of
the nftw() function.
The nftw() function recursively searches the directory
hierarchy that descends from the directory specified by
the path parameter. The nftw() function performs the same
operations as ftw(), except that it takes an additional
argument options, which is a bitwise inclusive-OR of zero
or more of the following options: If set, nftw() changes
the current working directory to each directory as it
reports files in that directory. If clear, nftw() does not
change the current working directory. If set, nftw()
reports all files in a directory before reporting the
directory itself. If clear, nftw() reports any directory
before reporting files in that directory. If set, nftw()
reports only files in the same file system as path. If
clear, nftw() reports all files encountered during the
walk. If set, nftw() performs a physical walk and does
not follow symbolic links. If clear, nftw() follows links
instead of reporting them, and does not report the same
file twice.
The nftw() function calls the function parameter with four
arguments at each file and directory. The first argument
is the pathname of the object. The second argument points
to the stat buffer containing information on the object.
The third argument is an integer that identifies the file
type or condition of the object. The value of the integer
is one of the following: A directory. A directory that
cannot be read. When nftw() reports this condition, function
is not called for any of the directory's descendants.
A directory whose subdirectories have been visited. (This
condition occurs only if the FTW_DEPTH option is included
in flags.) A regular file. An object for which the
stat() function failed because of lack of appropriate permission.
The content of the stat() buffer passed to function
is meaningless. Failure of nftw() for any other reason
is considered an error and results in a return value
of -l. A symbolic link. (This condition occurs only if
the FTW_PHYS option is included in flags.) A symbolic
link that names a non-existent file. (This condition
occurs only if the FTW_PHYS option is not included in
flags.)
In the backward-compatible version of nftw, the
FTW_SLN value is not used.
The fourth argument to function is a pointer to an FTW
structure.
In the backward-compatible version of nftw(), the fourth
argument is an FTW structure rather than a pointer to one.
The FTW structure includes the following members:
int base; int level;
The value of base is the offset into the pathname of the
object. This pathname is passed as the first argument to
the function parameter. The value of level specifies the
depth relative to the root of the walk, where the root
level has a value of 0 (zero).
[Tru64 UNIX] When compiled in the X/Open UNIX environment,
calls to the nftw() function are internally renamed
by prepending _E to the function name. When debugging a
module that includes the nftw() function and for which
_XOPEN_SOURCE_EXTENDED has been defined, use _Enftw to
refer to the nftw() call. See standards(5) for information
on when the _XOPEN_SOURCE_EXTENDED macro is defined.
[Tru64 UNIX] The nftw() function is reentrant; care
should be taken to ensure that the function supplied as
argument function is also reentrant.
If the directory hierarchy is completed, the nftw() function
returns a value of 0 (zero).
If the function specified by the function parameter
returns a nonzero value, the nftw() function stops the
search and returns the value that was returned by the
function.
If the nftw() function detects an error other than [EACCES],
a value of -1 is returned, and errno is set to indicate
the error.
If any of the following conditions occurs, the nftw()
function sets errno to the value that corresponds to the
condition. Search permission is denied for any component
of the path parameter or read permission is denied for the
path parameter, or function returns -1 and does not reset
errno. The length of the path string exceeds PATH_MAX, or
a pathname component is longer than NAME_MAX while
_POSIX_NO_TRUNC is in effect.
Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds PATH_MAX.
The path parameter points to the name of a file
that does not exist or points to an empty string.
A component of the path parameter is not a directory.
[Tru64 UNIX] There is insufficient memory
for this operation.
In addition, if the function pointed to by the function
parameter encounters an error, errno may be set accordingly.
Functions: stat(2), ftw(3)
Standards: standards(5)
nftw(3)
[ Back ] |
