ftw.3c (2010 09)

f
ftw(3C) ftw(3C)
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 rela-
tive to the start of the walk, where the start level has a value of zero.
APPLICATION USAGE
ftw() can execute concurrently in separate threads. nftw()
and nftw2() are serialized if the path
argument is relative (i.e., does not start with ’/’), or the
FTW_CHDIR flag is set. For best concurrency, call
nftw() with an absolute starting path and do not set
FTW_CHDIR.
To use the
UNIX95 prototype, the UNIX95
environment must be defined. This is done by defining the
UNIX95 environment variable, passing the _XOPEN_SOURCE_EXTENDED
flag as a compiler option, and
adding
/usr/xpg4/bin
to your path. This can be done as follows:
1.
export UNIX95=
2. PATH=/usr/xpg4/bin:$PATH
3. cc foo.c -D_XOPEN_SOURCE_EXTENDED
nftw2() is to be obsoleted at a future date.
ERRORS
If
ftw() or nftw() fails, it sets errno (see errno (2)) to one of the following values:
[EACCES] If a component of the path prefix denies search permission, or if read permis-
sion is denied for path , fn returns
-1 and does not reset errno.
[EINVAL] The value of the depth argument is invalid.
[ENAMETOOLONG] The length of the specified path name exceeds
PATH_MAX bytes, or the
length of a component of the path name exceeds
NAME_MAX bytes while
_POSIX_NO_TRUNC is in effect.
[ENOENT] path points to the name of a file that does not exist, or points to an empty
string.
[ENOTDIR] A component of path is not a directory.
[EOVERFLOW] One or more of the values in struct stat (st_size or st_blocks)is
too large to store in the structure to be passed to the function pointed to by
fn. Use ftw64() or nftw64() instead for 32-bit applications.
In addition, if the function pointed to by fn encounters system errors,
errno may be set accordingly.
WARNINGS
For 32-bit applications,
st_ino will be truncated to its least significant 32-bits for filesystems that use
64-bit values. Note that this will even occur for ftw64() calls because st_ino is defined as an
unsigned long.
For 32-bit applications accessing large file systems, use
ftw64() or nftw64() instead in order to avoid
overflow of the stat structure.
nftw() contains some recursion and it is possible for it to terminate with a memory fault when applied
to file trees which contain a large number of directories, or a large number of files when FTW_PHYS is
clear and the UNIX95 environment is defined.
nftw() uses malloc() to allocate dynamic storage during operation (see malloc(3C)). If it is 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.
If the starting path is in a loopback file system (LOFS) and
FTW_MOUNT is set (to stay within the LOFS),
but FTW_PHYS is clear (symbolic and hard links are followed), nftw() cannot determine whether a link
referencing a file on the same _device_ is really within the LOFS. It is possible with this specific combi-
nation of factors to have some files reported to fn which should not be.
HP-UX 11i Version 3: September 2010 − 3 − Hewlett-Packard Company 3