|
|
using ftw()
|
|
ftw(3) Library Functions Manual ftw(3) NAME
ftw - Walks a file tree LIBRARY
Standard C Library (libc.so, libc.a) SYNOPSIS
#include <ftw.h> int ftw( const char *path, int(*function)(const char *, const struct stat *, int), int ndirs); 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
Specifies the directory hierarchy to be searched. Specifies the function to be invoked for each object in the directory hierarchy. Speci- fies 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: 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 encoun- tered 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 reen- trant. 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. 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. RELATED INFORMATION
Functions: stat(2), nftw(3) Standards: standards(5) delim off ftw(3)
