 |
Index for
Section 3 |
|
 |
Alphabetical
listing for F |
|
 |
Bottom of
page |
|
ftw(3)
NAME
ftw - Walks a file tree
SYNOPSIS
#include <ftw.h>
int ftw(
const char *path,
int (*function)(const char *, const struct stat *, int),
int ndirs );
LIBRARY
Standard C Library (libc)
STANDARDS
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.
PARAMETERS
path
Specifies the directory hierarchy to be searched.
function
Specifies the function to be invoked for each object in the directory
hierarchy.
ndirs
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.
DESCRIPTION
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:
FTW_D
A directory.
FTW_DNR
A directory that cannot be read.
FTW_F
A regular file.
FTW_NS
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.
FTW_SL
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.
NOTES
[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.
RETURN VALUES
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.
ERRORS
If any of the following conditions occurs, the ftw() 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.
[ELOOP]
Too many symbolic links were encountered.
[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), nftw(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for F |
|
 |
Top of
page |
|