ftw - Walks a file tree
#include <ftw.h>
int ftw(
const char *path,
int (*function)(const char *, const struct stat *,
int),
int ndirs );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
ftw(): 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. Specifies the maximum number of
directory streams or file descriptors (or both) available
for use by ftw(). This parameter is not used in Tru64 UNIX
implementations of ftw().
This parameter must be in the range of 1 to
OPEN_MAX.
For backward compatibility with operating system
versions prior to Digital UNIX Version 4.O, ftw()
takes a depth argument instead of ndirs. The depth
parameter specifies the directory depth for the
search, but it is not used.
The ftw() function recursively searches the directory
hierarchy that descends from the directory specified by
the path parameter.
For each object in the hierarchy, the ftw() function calls
the function specified by the function parameter, passes
it a pointer to a null-terminated character string containing
the name of the file, a pointer to a stat structure
containing information about the file, and an integer.
(See the stat(2) reference page for more information
about this structure.)
The integer passed to the function parameter identifies
the file type or condition of the object, and it has one
of the following values: A directory. A directory that
cannot be read. A regular file. A file, other than a
symbolic link, for which the stat() function failed. For
example, FTW_NS is passed to function when a file is in a
directory with read permission, but without execute
(search) permission. A symbolic link.
If the integer is FTW_DNR, then the files and subdirectories
contained in that directory are not processed.
If the integer is FTW_NS, then the stat structure contents
are meaningless.
The ftw() function finishes processing a directory before
processing any of its files or subdirectories.
The ftw() function uses at most one file descriptor for
each level in the directory hierarchy.
The ftw() function continues the search until the directory
hierarchy specified by the path parameter is completed,
an invocation of the function specified by the
function parameter returns a nonzero value, or an error
other than [EACCES] is detected within the ftw() function
(such as an I/O error).
The ndirs parameter specifies the maximum number of directory
streams or file descriptors (or both) available for
use by the ftw() function while traversing the directory
hierarchy. When ftw() returns it closes any directory
streams and file descriptors it uses not counting any
opened by the application-supplied function.
The ftw() function traverses symbolic links encountered in
the resolution of path, including the final component.
Symbolic links encountered while walking the directory
tree rooted at path are not traversed.
[Tru64 UNIX] When compiled in the X/Open UNIX environment,
calls to the ftw() function are internally renamed
by prepending _E to the function name. When debugging a
module that includes the ftw() function and for which
_XOPEN_SOURCE_EXTENDED has been defined, use _Eftw to
refer to the ftw() call. See standards(5) for information
on when the _XOPEN_SOURCE_EXTENDED macro is defined.
[Tru64 UNIX] The ftw() function is reentrant; care should
be taken to ensure that the function supplied as argument
function is also reentrant.
Because the ftw() function is recursive, it is possible
for it to terminate with a memory fault due to stack overflow
when applied to very deep file structures.
The ftw() function uses the malloc() function to allocate
dynamic storage during its operation. If the ftw() function
is terminated prior to its completion, such as by the
longjmp() function being executed by the function specified
by the function parameter or by an interrupt routine,
the ftw() function cannot free that storage. The storage
remains allocated. A safe way to handle interrupts is to
store the fact that an interrupt has occurred, and arrange
to have the function specified by the function parameter
return a nonzero value the next time it is called.
If the directory hierarchy is completed, the ftw() function
returns a value of 0 (zero).
If the function specified by the function parameter
returns a nonzero value, the ftw() function stops the
search and returns the value that was returned by the
function.
If the ftw() 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 ftw() 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. Too many symbolic links were encountered.
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), nftw(3)
Standards: standards(5)
ftw(3)
[ Back ] |
