 |
Index for
Section 3 |
|
 |
Alphabetical
listing for N |
|
 |
Bottom of
page |
|
nftw(3)
NAME
nftw - Walk a file tree
SYNOPSIS
#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 );
LIBRARY
Standard C Library (libc)
STANDARDS
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.
PARAMETERS
path
Specifies the directory hierarchy to be searched.
function
Specifies the function to be invoked for each object in the directory
hierarchy.
depth
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.
flags
Specifies optional options that modify the operation of the nftw()
function.
DESCRIPTION
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:
FTW_CHDIR
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.
FTW_DEPTH
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.
FTW_MOUNT
If set, nftw() reports only files in the same file system as path. If
clear, nftw() reports all files encountered during the walk.
FTW_PHYS
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:
FTW_D
A directory.
FTW_DNR
A directory that cannot be read. When nftw() reports this condition,
function is not called for any of the directory's descendants.
FTW_DP
A directory whose subdirectories have been visited. (This condition
occurs only if the FTW_DEPTH option is included in flags.)
FTW_F
A regular file.
FTW_NS
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.
FTW_SL
A symbolic link. (This condition occurs only if the FTW_PHYS option is
included in flags.)
FTW_SLN
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).
NOTES
[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.
RETURN VALUES
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.
ERRORS
If any of the following conditions occurs, the nftw() function sets errno
to the value that corresponds to the condition.
[EACCES]
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.
[ENAMETOOLONG]
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.
[ENOENT]
The path parameter points to the name of a file that does not exist or
points to an empty string.
[ENOTDIR]
A component of the path parameter is not a directory.
[ENOMEM]
[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.
SEE ALSO
Functions: stat(2), ftw(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for N |
|
 |
Top of
page |
|