Open System Services Library Calls Reference Manual (G06.28+, H06.05+)

OSS Library Calls (n - r) nftw(3)
DESCRIPTION
The nftw() function recursively searches the directory hierarchy that descends from the directory
specified by the path parameter. For each file in the hierarchy, nftw() calls the function pointed
to by the function parameter and passes four arguments.
The flag value passed to the function parameter identifies the file type of the object specified for
the object parameter or provides other information that modifies the operation of the nftw() func-
tion. The flag value can be one of the following:
FTW_D Specifies that the object is a directory.
FTW_DNR Specifies that the object is a directory that cannot be read.
FTW_DP Specifies that the object is a directory and that subdirectories have already been
traversed. This value is used only when the flags parameter includes the
FTW_DEPTH flag.
FTW_F Specifies that the object is a regular file.
FTW_NS Specifies that the object is a file for which the stat() function could not be exe-
cuted successfully.
FTW_SL Specifies that the object is a symbolic link. This value is used only when the
flags parameter includes the FTW_PHYS flag.
FTW_SLN Specifies that the object is a symbolic link that does not name an existing file.
This value is used only when the flags parameter does not include the
FTW_PHYS flag.
If flag is FTW_DNR, the files and subdirectories contained in that directory are not processed.
If flag is FTW_NS, the stat structure contents are meaningless. An example of a file that causes
FTW_NS to be passed to the function parameter is a file in a directory for which you have read
permission but not execute (search) permission. This condition also returns the value [EACCES]
in errno.
The nftw() function finishes processing a directory before processing any of its files or subdirec-
tories.
The nftw() function continues the search until either the directory hierarchy specified by the path
parameter is completely searched, an invocation of the function specified by the function parame-
ter returns a nonzero value, or an error is detected within nftw( ), such as an I/O error.
Because nftw( ) is recursive, it can terminate with a memory fault because of stack overflow
when the function is called for very deep tree structures.
The nftw() function uses the malloc() function to allocate dynamic storage during its operation.
If nftw() is terminated prior to its completion, such as when the longjmp() function is executed
by the function specified by the function parameter, nftw( ) cannot free that storage. The storage
remains allocated.
The nftw() function traverses symbolic links encountered in the resolution of path, including the
final component. Symbolic links encountered while traversing the directory tree rooted at path
are not traversed.
Use on Guardian Objects
All Guardian files (that is, files in /G) that are visible to the opendir( ) function can be traversed.
This includes temporary and structured files.
Safeguard subsystem security controls on Guardian objects do not affect the outcome of a call to
the nftw( ) function.
527187-007 Hewlett-Packard Company 5−5