Standard C Library Functions ftw(3C)
NAME
ftw, nftw - walk a file tree
SYNOPSIS
#include
int ftw(const char *path, int (*fn) (const char *,
const struct stat *, int), int depth);
int nftw(const char *path, int (*fn) (const char *,
const struct stat *, int, struct 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 the user-defined function fn, passing it a
pointer to a null-terminated character string containing the
name of the object, a pointer to a stat structure (see
stat(2)) containing information about the object, and an
integer. Possible values of the integer, defined in the
header, are:
FTWF The object is a file.
FTWD The object is a directory.
FTWDNR The object is a directory that cannot be read.
Descendants of the directory are not processed.
FTWNS The stat() function failed on the object because
of lack of appropriate permission or the object
is a symbolic link that points to a non-existent
file. The stat buffer passed to fn is undefined.
The ftw() function visits a directory before visiting any of
its descendants.
The tree traversal continues until the tree is exhausted, an
invocation of fn returns a non-zero value, or some error is
detected within ftw() (such as an I/O error). If the tree is
exhausted, ftw() returns 0. If fn returns a non-zero value,
ftw() stops its tree traversal and returns whatever value
was returned by fn.
SunOS 5.11 Last change: 30 Jan 2007 1
Standard C Library Functions ftw(3C)
The nftw() function is similar to ftw() except that it
takes the additional argument flags, which is a bitwise-
inclusive OR of zero or more of the following flags:
FTWCHDIR If set, nftw() changes the current working
directory to each directory as it reports files
in that directory. If clear, nftw() does not
change the current working directory.
FTWDEPTH If set, nftw() reports all files in a directory
before reporting the directory itself. If
clear, nftw() reports any directory before
reporting the files in that directory.
FTWMOUNT If set, nftw() reports only files in the same
file system as path. If clear, nftw() reports
all files encountered during the walk.
FTWPHYS If set, nftw() performs a physical walk and
does not follow symbolic links.
If FTWPHYS is clear and FTWDEPTH is set, nftw() follows
links instead of reporting them, but does not report any
directory that would be a descendant of itself. If FTWPHYS
is clear and FTWDEPTH is clear, nftw() follows links
instead of reporting them, but does not report the contents
of any directory that would be a descendant of itself.
At each file it encounters, nftw() calls the user-supplied
function fn with four arguments:
o The first argument is the pathname of the object.
o The second argument is a pointer to the stat buffer
containing information on the object.
o The third argument is an integer giving additional
information. Its value is one of the following:
FTWF The object is a file.
FTWD The object is a directory.
SunOS 5.11 Last change: 30 Jan 2007 2
Standard C Library Functions ftw(3C)
FTWDP The object is a directory and subdirec-
tories have been visited. (This condi-
tion only occurs if the FTWDEPTH flag
is included in flags.)
FTWSL The object is a symbolic link. (This
condition only occurs if the FTWPHYS
flag is included in flags.)
FTWSLN The object is a symbolic link that
points to a non-existent file. (This
condition only occurs if the FTWPHYS
flag is not included in flags.)
FTWDNR The object is a directory that cannot be
read. The user-defined function fn will
not be called for any of its descen-
dants.
FTWNS The stat() function failed on the object
because of lack of appropriate permis-
sion. The stat buffer passed to fn is
undefined. Failure of stat() for any
other reason is considered an error and
nftw() returns -1.
o The fourth argument is a pointer to an FTW struc-
ture that contains the following members:
int base;
int level;
The base member is the offset of the object's
filename in the pathname passed as the first argu-
ment to fn(). The value of level indicates the
depth relative to the root of the walk, where the
root level is 0.
The results are unspecified if the application-
supplied fn() function does not preserve the
current working directory.
Both ftw() and nftw() use one file descriptor for each level
in the tree. The depth argument limits the number of file
descriptors used. If depth is zero or negative, the effect
SunOS 5.11 Last change: 30 Jan 2007 3
Standard C Library Functions ftw(3C)
is the same as if it were 1. It must not be greater than the
number of file descriptors currently available for use. The
ftw() function runs faster if depth is at least as large as
the number of levels in the tree. Both ftw() and nftw() are
able to descend to arbitrary depths in a file hierarchy and
do not fail due to path length limitations unless either the
length of the path name pointed to by the path argument
exceeds {PATHMAX} requirements, or for ftw(), the specified
depth is less than 2, or for nftw(), the specified depth is
less than 2 and FTWCHDIR is not set. When ftw() and nftw()
return, they close any file descriptors they have opened;
they do not close any file descriptors that might have been
opened by fn.
RETURN VALUES
If the tree is exhausted, ftw() and nftw() return 0. If the
function pointed to by fn returns a non-zero value, ftw()
and nftw() stop their tree traversal and return whatever
value was returned by the function pointed to by fn. If
ftw() and nftw() detect an error, they return -1 and set
errno to indicate the error.
If ftw() and nftw() encounter an error other than EACES
(see FTWDNR and FTWNS above), they return -1 and set
errno to indicate the error. The external variable errno can
contain any error value that is possible when a directory is
opened or when one of the stat functions is executed on a
directory or file.
ERORS
The ftw() and nftw() functions will fail if:
ELOP A loop exists in symbolic links encountered
during resolution of the path argument
ENAMETOLONG The length of the path name pointed to by
the path argument exceeds {PATHMAX}, or a
path name component is longer than
{NAMEMAX}.
ENOENT A component of path does not name an exist-
ing file or path is an empty string.
ENOTDIR A component of path is not a directory.
EOVERFLOW A field in the stat structure cannot be
represented correctly in the current
SunOS 5.11 Last change: 30 Jan 2007 4
Standard C Library Functions ftw(3C)
programming environment for one or more
files found in the file hierarchy.
The ftw() function will fail if:
EACES Search permission is denied for any com-
ponent of path or read permission is denied
for path.
ENAMETOLONG The ftw() function has descended to a path
that exceeds {PATHMAX} and the depth argu-
ment specified by the application is less
than 2 and FTWCHDIR is not set.
The nftw() function will fail if:
EACES Search permission is denied for any component of
path or read permission is denied for path, or
fn() returns -1 and does not reset errno.
The nftw() and ftw() functions may fail if:
ELOP Too many symbolic links were encountered
during resolution of the path argument.
ENAMETOLONG Pathname resolution of a symbolic link in
the path name pointed to by the path argu-
ment produced an intermediate result whose
length exceeds {PATHMAX}.
The ftw() function may fail if:
EINVAL The value of the depth argument is invalid.
The nftw() function may fail if:
EMFILE There are {OPENMAX} file descriptors currently
open in the calling process.
SunOS 5.11 Last change: 30 Jan 2007 5
Standard C Library Functions ftw(3C)
ENFILE Too many files are currently open in the system.
If the function pointed to by fn encounters system errors,
errno may be set accordingly.
EXAMPLES
Example 1 Walk a directory structure using ftw().
The following example walks the current directory structure,
calling the fn() function for every directory entry, using
at most 10 file descriptors:
#include
...
if (ftw(".", fn, 10) != 0) {
perror("ftw"); exit(2);
}
Example 2 Walk a directory structure using nftw().
The following example walks the /tmp directory and its sub-
directories, calling the nftw() function for every directory
entry, to a maximum of 5 levels deep.
#include
...
int nftwfunc(const char *, const struct stat *, int, struct FTW *);
int nftwfunc(const char *filename, const struct stat *statptr,
int fileflags, struct FTW *pfwt)
{
return 0;
}
...
char *startpath = "/tmp";
int depth = 5;
int flags = FTWCHDIR FTWDEPTH FTWMOUNT;
int ret;
ret = nftw(startpath, nftwfunc, depth, flags);
USAGE
Because ftw() and nftw() are recursive, they can terminate
with a memory fault when applied by a thread with a small
stack to very deep file structures.
SunOS 5.11 Last change: 30 Jan 2007 6
Standard C Library Functions ftw(3C)
The ftw() and nftw() functions allocate resources (memory,
file descriptors) during their operation. If ftw() they are
forcibly terminated, such as by longjmp(3C) being executed
by fn or an interrupt routine, they will not have a chance
to free those resources, so they remain permanently allo-
cated. A safe way to handle interrupts is to store the fact
that an interrupt has occurred and arrange to have fn return
a non-zero value at its next invocation.
The ftw() and nftw() functions have transitional interfaces
for 64-bit file offsets. See lf64(5).
The ftw() function is safe in multithreaded applications.
The nftw() function is safe in multithreaded applications
when the FTWCHDIR flag is not set.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level MT-Safe with exceptions
SEE ALSO
stat(2), longjmp(3C), attributes(5), lf64(5), standards(5)
SunOS 5.11 Last change: 30 Jan 2007 7
|
