HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

331

332

333

334

335

336

337

338

339

340

ftw(3C) ftw(3C)

int base;

int level;

The value of base is the offset from the ﬁrst character in the path name to where the base name of the

object starts; this path name is passed as the ﬁrst 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 ﬂag 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 deﬁned. This is done by deﬁning the

UNIX95 environment variable, passing the _XOPEN_SOURCE_EXTENDED

ﬂag as a compiler option, and

adding

/usr/xpg4/bin

to your path. This can be done as follows:

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 preﬁx 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 speciﬁed 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 ﬁle 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

ﬁle trees which contain a large number of directories, or a large number of ﬁles when FTW_PHYS is clear

and the UNIX95 environment is deﬁned.

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 ﬁle 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 ﬁle on the same _device_ is really within the LOFS. It is possible with this speciﬁc combina-

tion of factors to have some ﬁles 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.