'\"macro stdmacro
.if n .pH g3c.ftw @(#)ftw	40.18 of 10/25/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} ftw 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} ftw 3C "C Programming Language Utilities"
.if \nX=2 .ds x} ftw 3C "" "\&"
.if \nX=3 .ds x} ftw "" "" "\&"
.TH \*(x}
.SH NAME
\f4ftw\f1, \f4nftw\f1 \- walk a file tree
.SH SYNOPSIS
\f4#include <ftw.h>\f1
.PP
\f4int ftw (const char \(**path, int (\(**fn) (const char \(**, const struct 
.br
.nf
    stat \(**, int), int depth);\fP
.PP
\f4int nftw (const char \(**path, int (\(**fn) (const char \(**, const struct
.br
    stat \(**, int, struct FTW\(**), int depth, int flags);\fP
.fi    
.SH DESCRIPTION
\f4ftw\fP
recursively descends the directory hierarchy
rooted in
.IR path .
For each object in the hierarchy,
\f4ftw\fP
calls the user-defined function
.IR fn ,
passing it a pointer to a null-terminated
character string containing the name of the object,
a pointer to a
\f4stat\f1
structure (see
\f4stat\fP(2))
containing information about the object, and an integer.
Possible values of the integer, defined in the \f4ftw.h\f1 header file, are:
.TP 12
\f4FTW_F\fP
The object is a file.
.TP 12
\f4FTW_D\fP
The object is a directory.
.TP 12
\f4FTW_DNR\fP
The object is a directory that cannot be read.
Descendants of the directory will not be processed.
.TP 12
\f4FTW_NS\fP
\f4stat\fP
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 \f2fn\f1 is undefined.
.PP
\f4ftw\fP
visits a directory before visiting any of its descendants.
.PP
The tree traversal continues until the tree is exhausted,
an invocation of
.I fn\^
returns a nonzero value,
or some error is detected within
\f4ftw\fP
(such as an \s-1I/O\s+1 error).
If the tree is exhausted,
\f4ftw\fP
returns zero.
If
.I fn\^
returns a nonzero value,
\f4ftw\fP
stops its tree traversal and returns whatever
value was returned by
.IR fn .
If
\f4ftw\fP
detects an error other than \f4EACCES\fP, it returns
\-1, and sets the error type in
\f4errno\f1.
.P
The function \f4nftw\f1 is similar to \f4ftw\fP except
that it takes an additional argument, \f2flags\f1.
The \f2flags\f1 field is used to specify:
.TP 12
\f4FTW_PHYS\fP
Physical walk, does not follow symbolic links.
Otherwise, \f4nftw\f1 will follow links but will not
walk down any path that crosses itself.
.TP 12
\f4FTW_MOUNT\fP
The walk will not cross a mount point.
.TP 12
\f4FTW_DEPTH\fP
All subdirectories will be visited before the
directory itself.
.TP 12
\f4FTW_CHDIR\fP
The walk will change to each directory before
reading it.
.PP
The function \f4nftw\f1 calls \f2fn\f1 with four arguments at each file
and directory.
The first argument is the pathname of the object, the second
is a pointer to the \f4stat\f1 buffer, the third is an integer
giving additional information,
and the fourth is a \f4struct FTW\f1 that contains the following members:
.sp .5
.RS 5
.nf
.ft4
int base;
int level;
.ft1
.fi
.RE
.bp
.sp .5
\f4base\f1 is the offset into the pathname
of the base name of the object.
\f4level\f1 indicates the depth relative to
the rest of the walk, where the root
level is zero.
.P
The values of the third argument are as follows:
.TP 12
\f4FTW_F\fP
The object is a file.
.TP 12
\f4FTW_D\fP
The object is a directory.
.TP 12
\f4FTW_DP\fP
The object is a directory and subdirectories have been visited.
.TP 12
\f4FTW_SLN\fP
The object is a symbolic link that points to a
non-existent file.
.TP 12
\f4FTW_DNR\fP
The object is a directory that cannot be read.
\f2fn\f1 will not be called for any of its descendants.
.TP 12
\f4FTW_NS\fP
\f4stat\fP failed on the object because of lack of appropriate permission.
The stat buffer passed to \f2fn\f1 is undefined.
\f4stat\fP failure other than lack of appropriate
permission (\f4EACCES\f1) is considered an error and \f4nftw\f1
will return \-1.
.PP
Both \f4ftw\fP and \f4nftw\f1
use one file descriptor for each level in the tree.
The
.I depth\^
argument limits the number of file descriptors so used.
If
.I depth\^
is zero or negative, the effect is the same as if it were 1.
.I depth\^
must not be greater than the number of file descriptors currently
available for use.
\f4ftw\fP
will run faster if
.I depth\^
is at least as large as the number of levels in the tree.
When \f4ftw\fP and \f4nftw\fP return, they close any file descriptors
they have opened; they do not close any file descriptors that may have
been opened by \f2fn\fP.
.SH SEE ALSO
\f4stat\fP(2), \f4malloc\fP(3C).
.SH NOTES
Because
\f4ftw\fP
is recursive, it is possible for it to terminate with a memory
fault when applied to very deep file structures.
.P
\f4ftw\fP
uses
\f4malloc\fP(3C)
to allocate dynamic storage during its operation.
If
\f4ftw\fP
is forcibly terminated, such as by
\f4longjmp\fP
being executed by
.I fn\^
or an interrupt routine,
\f4ftw\fP
will not have a chance to free that storage,
so it will remain permanently allocated.
A safe way to handle interrupts is to store
the fact that an interrupt has occurred,
and arrange to have
.I fn\^
return a nonzero value at its next invocation.
.\"	@(#)ftw.3c	6.3 of 10/20/83
.Ee
