*** UNIX MANUAL PAGE BROWSER ***

nftw(3) Library Functions Manual nftw(3) NAME nftw - Walks a file tree LIBRARY Standard C Library (libc.so, libc.a) 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); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: nftw(): 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. 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. Specifies optional flags that mod- ify 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 flags, which is a bitwise inclusive-OR of zero or more of the following flags: If set, nftw() changes the current working directory to each directory as it reports files in that direc- tory. If clear, nftw() does not change the current working directory. If set, nftw() reports all files in a directory before reporting the directory itself. If clear, nftw() reports any directory before re- porting files in that directory. If set, nftw() reports only files in the same file system as path. If clear, nftw() reports all files en- countered during the walk. If set, nftw() performs a physical walk and does not follow symbolic links. If clear, nftw() follows links in- stead 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 infor- mation 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: A directory. A directory that cannot be read. When nftw() reports this condition, function is not called for any of the directory's descendants. A directory whose subdirectories have been visited. (This condition occurs only if the FTW_DEPTH flag is in- cluded in flags.) A regular file. 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 re- turn value of -l. A symbolic link. (This condition occurs only if the FTW_PHYS flag is included in flags.) [XPG4-UNIX] A symbolic link that names a non-ex- istent file. (This condition occurs only if the FTW_PHYS flag is not included in flags.) In the backward-compatible version of nftw, the FTW_SLN value is not used. [XPG4-UNIX] 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 [Digital] 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. [Digital] The nftw() function is reentrant; care should be taken to ensure that the function supplied as argument function is also reen- trant. 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 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, or function returns -1 and does not re- set errno. The length of the path string exceeds PATH_MAX, or a path- name component is longer than NAME_MAX while _POSIX_NO_TRUNC is in ef- fect. 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. [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), ftw(3) Standards: standards(5) delim off nftw(3)