*** UNIX MANUAL PAGE BROWSER ***

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 stan- dards as follows: ftw(): XPG4, XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Specifies the directory hierarchy to be searched. Specifies the func- tion 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 the Digital UNIX Version 4.0 implementation of ftw(). [XPG4-UNIX] 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 in- stead 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-ter- minated 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 struc- ture.) 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. [XPG4-UNIX] 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. [XPG4-UNIX] 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 meaning- less. The ftw() function finishes processing a directory before processing any of its files or subdirectories. [XPG4-UNIX] 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 resolu- tion of path, including the final component. Symbolic links encoun- tered while walking the directory tree rooted at path are not tra- versed. NOTES [Digital] 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. [Digital] The ftw() function is reentrant; care should be taken to en- sure that the function supplied as argument function is also reentrant. Because the ftw() function is recursive, it is possible for it to ter- minate 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 stor- age 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 rou- tine, 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 er- rno 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 encoun- tered. 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. [XPG4-UNIX] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX. The path pa- rameter 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. [Digital] There is insufficient memory for this operation. In addition, if the function pointed to by the function parameter en- counters an error, errno may be set accordingly. RELATED INFORMATION Functions: stat(2), nftw(3) Standards: standards(5) delim off ftw(3)