ftw.3c (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

ftw(3C) ftw(3C)

NAME

ftw(), nftw() - walk a ﬁle 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 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);

UNIX95

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);

Obsolescent Interfaces

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);

DESCRIPTION

The 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()

stat (2)), and an integer, obj_ﬂags. The possible values of obj_ﬂags, deﬁned in the

<ftw.h> header ﬁle,

are:

FTW_F The object is a ﬁle.

FTW_D The object is a directory.

FTW_SL The object is a symbolic link.

FTW_DNR The object is a directory without read permission. fn will not be called for any of its

descendants.

FTW_NS lstat() failed on the object. The contents of the stat structure are undeﬁned.

If the failure was caused by a lack of permissions, the walk will continue. For all

other errors ftw() will terminate the walk and return -1.

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() reports a directory before reporting any of its descendants.

ftw() and nftw() use one ﬁle descriptor for each level in the tree. The depth argument limits the

number of ﬁle 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 ﬁle descriptors currently available for use. For best

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (4 pages)

PAGE 1
ftw(3C) ftw(3C) NAME ftw(), nftw() - walk a file tree executing a function SYNOPSIS #include
PAGE 2
ftw(3C) ftw(3C) 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, and does not report or enter a directory which has already been visited during the walk. The flags field is the inclusive OR of the following values, as defined in the header file: FTW_PHYS If set, nftw() does a physical walk. It will not follow symbolic links, but will follow hard links.
PAGE 3
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 relative to the start of the walk, where the start level has a value of zero. APPLICATION USAGE ftw() can execute concurrently in separate threads.
PAGE 4
ftw(3C) ftw(3C) Obsolescent Interfaces nftw2() is to be obsoleted at a future date. AUTHOR ftw(), nftw(), and nftw2() were developed by AT&T and HP. SEE ALSO stat(2), fgetpos64(3S), malloc(3C), thread_safety(5).