|
|
HP-UX Reference Volume 4 of 5 > fftw(3C) |
|
NAMEftw(), nftw(), nftw2() — walk a file tree executing a function SYNOPSIS#include <ftw.h> int ftw (const char *path, int (*fn)(const char *obj_path, const struct stat *obj_stat, int obj_flags), int depth); int nftw2(const char *path, int (*fn)(const char *obj_path, const struct stat *obj_stat, int obj_flags, struct FTW obj_FTW), int depth, int flags); int nftw (const char *path, int (*fn)(const char *obj_path, const struct stat *obj_stat, int obj_flags, struct FTW obj_FTW), int depth, int flags); DESCRIPTIONThe ftw() function recursively descends the directory hierarchy rooted in path. For each object in the hierarchy, ftw() calls fn, passing it a pointer to a null-terminated character string containing the name of the object, a pointer to a stat structure containing information about the object (see lstat() in stat(2)), and an integer. The possible values of the integer, defined in the <ftw.h> header file, are:
Tree traversal continues until the tree is exhausted, an invocation of fn returns a nonzero value, or an error is detected within ftw(), such as an I/O error. If the tree is exhausted, ftw() returns zero. If fn returns a nonzero value, ftw() stops its tree traversal and returns the same value as returned by fn. If ftw() detects an error, it returns -1 and sets the error type in errno (see errno(2)). ftw() visits a directory before visiting any of its descendants. ftw() and nftw() use one file descriptor for each level in the tree. The depth argument limits the number of file descriptors that can be used. If depth is 0 or negative, the effect is the same as if it were 1. depth must not be greater than the number of file descriptors currently available for use. For best performance, depth should be at least as large as the number of levels in the tree. nftw() is similar to ftw() except that it takes the additional argument flags. The flags field is the inclusive OR of the following values, as defined in the <ftw.h> header file:
nftw() calls fn with four arguments for each file and directory visited. The first argument is the path name of the file or directory, the second is a pointer to a stat structure (see lstat(2)) containing information about the object, and the third is an integer giving additional information as follows:
The fourth argument is different for the default environment and the UNIX95 environment. For the default environment, the fourth argument is a structure FTW. For the UNIX95 environment, the fourth argument is a pointer to a structure FTW (ie: *FTW ). FTW contains the following members: int base; int level; The value of base is the offset from the first character in the path name to where the base name of the object starts; this path name is passed as the first argument to fn. The value of level indicates depth relative to the start of the walk, where the start level has a value of zero. nftw2() is equivalent to nftw(). This function is provided for HP-UX compatibility in future releases. APPLICATION USAGEftw(), nftw() and nftw2() are thread-safe. These interfaces are not async-cancel-safe. A cancellation point may occur when a thread is executing ftw(), nftw() or nftw2(). To use the UNIX95 prototype, the UNIX95 environment must be defined. This is done by defining the UNIX95 environment variable, passing the _XOPEN_UNIX_EXTENDED flag as a compiler option, and adding /usr/xpg4/bin to your path. This can be done as follows:
ERRORSIf ftw() or nftw() fails, it sets errno (see errno(2)) to one of the following values:
In addition, if the function pointed to by fn encounters system errors, errno may be set accordingly. WARNINGSBecause these functions are recursive, it is possible for them to terminate with a memory fault when applied to very deep file structures. ftw() and nftw() use malloc() to allocate dynamic storage during their operation (see malloc(3C)) If they are forcibly terminated (such as if longjmp() is executed by fn or an interrupt routine), the calling function will not have a chance to free that storage, causing it to remain allocated until the process terminates. A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have fn return a nonzero value at its next invocation. The syntax for nftw() may be changed in a future release. (See nftw2() in the DESCRIPTION section). |
|