HP-UX Reference (11i v1 00/12) - 3 Library Functions A-M (vol 6)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/!!!intro.3c
________________________________________________________________
___ ___
f
ftw(3C) ftw(3C)
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(), nftw() and nftw2() are thread-safe. These interfaces are not async-cancel-safe. A cancella-
tion point may occur when a thread is executing ftw(), nftw() or nftw2(). ftw() can execute con-
currently 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 per-
mission 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 of the values in
struct stat (st_size or st_blocks) is too large to
store into the structure to be passed to the function pointed to by fn.
In addition, if the function pointed to by fn encounters system errors,
errno may be set accordingly.
WARNINGS
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 combina-
tion of factors to have some files reported to fn which should not be.
Obsolescent Interfaces
nftw2() is to be obsoleted at a future date.
AUTHOR
ftw(), nftw(), and nftw2() were developed by AT&T and HP.
HP-UX Release 11i: December 2000 − 3 − Section 3−−263
___
___