path: root/usr/src/man/man3c/ftw.3c

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
.\"
.TH FTW 3C "Jan 30, 2007"
.SH NAME
ftw, nftw \- walk a file tree
.SH SYNOPSIS
.LP
.nf
#include <ftw.h>

\fBint\fR \fBftw\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR (*\fIfn\fR) (\fBconst char *\fR,
     \fBconst struct stat *\fR, \fBint\fR), \fBint\fR \fIdepth\fR);
.fi

.LP
.nf
\fBint\fR \fBnftw\fR(\fBconst char *\fR\fIpath\fR, \fBint (*\fR\fIfn\fR) (\fBconst char *\fR,
     \fBconst struct stat *\fR, \fBint\fR, \fBstruct FTW *\fR), \fBint\fR \fIdepth\fR,
     \fBint\fR \fIflags\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBftw()\fR function recursively descends the directory hierarchy rooted in
\fIpath\fR. For each object in the hierarchy, \fBftw()\fR calls the
user-defined function \fIfn\fR, passing it a pointer to a null-terminated
character string containing the name of the object, a pointer to a \fBstat\fR
structure (see \fBstat\fR(2)) containing information about the object, and an
integer. Possible values of the integer, defined in the <\fBftw.h\fR> header,
are:
.sp
.ne 2
.na
\fB\fBFTW_F\fR\fR
.ad
.RS 11n
The object is a file.
.RE

.sp
.ne 2
.na
\fB\fBFTW_D\fR\fR
.ad
.RS 11n
The object is a directory.
.RE

.sp
.ne 2
.na
\fB\fBFTW_DNR\fR\fR
.ad
.RS 11n
The object is a directory that cannot be read. Descendants of the directory are
not processed.
.RE

.sp
.ne 2
.na
\fB\fBFTW_NS\fR\fR
.ad
.RS 11n
The \fBstat()\fR 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 \fBstat\fR buffer passed to \fIfn\fR is undefined.
.RE

.sp
.LP
The \fBftw()\fR function visits a directory before visiting any of its
descendants.
.sp
.LP
The tree traversal continues until the tree is exhausted, an invocation of
\fIfn\fR returns a non-zero value, or some error is detected within \fBftw()\fR
(such as an I/O error). If the tree is exhausted, \fBftw()\fR returns \fB0\fR.
If \fIfn\fR returns a non-zero value, \fBftw()\fR stops its tree traversal and
returns whatever value was returned by \fIfn\fR.
.sp
.LP
The  \fBnftw()\fR function is similar to \fBftw()\fR except that it takes the
additional argument \fIflags\fR, which is a bitwise-inclusive OR of zero or
more of the following flags:
.sp
.ne 2
.na
\fB\fBFTW_CHDIR\fR\fR
.ad
.RS 13n
If set, \fBnftw()\fR changes the current working directory to each directory as
it reports files in that directory. If clear, \fBnftw()\fR does not change the
current working directory.
.RE

.sp
.ne 2
.na
\fB\fBFTW_DEPTH\fR\fR
.ad
.RS 13n
If set, \fBnftw()\fR reports all files in a directory before reporting the
directory itself. If clear, \fBnftw()\fR reports any directory before reporting
the files in that directory.
.RE

.sp
.ne 2
.na
\fB\fBFTW_MOUNT\fR\fR
.ad
.RS 13n
If set, \fBnftw()\fR reports only files in the same file system as path. If
clear, \fBnftw()\fR reports all files encountered during the walk.
.RE

.sp
.ne 2
.na
\fB\fBFTW_PHYS\fR\fR
.ad
.RS 13n
If set, \fBnftw()\fR performs a physical walk and does not follow symbolic
links.
.RE

.sp
.LP
If \fBFTW_PHYS\fR is clear and \fBFTW_DEPTH\fR is set, \fBnftw()\fR follows
links instead of reporting them, but does not report any directory that would
be a descendant of itself. If \fBFTW_PHYS\fR is clear and \fBFTW_DEPTH\fR is
clear, \fBnftw()\fR follows links instead of reporting them, but does not
report the contents of any directory that would be a descendant of itself.
.sp
.LP
At each file it encounters, \fBnftw()\fR calls the user-supplied function
\fIfn\fR with four arguments:
.RS +4
.TP
.ie t \(bu
.el o
The first argument is the pathname of the object.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The second argument is a pointer to the \fBstat\fR buffer containing
information on the object.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The third argument is an integer giving additional information. Its value is
one of the following:
.RS

.sp
.ne 2
.na
\fB\fBFTW_F\fR\fR
.ad
.RS 11n
The object is a file.
.RE

.sp
.ne 2
.na
\fB\fBFTW_D\fR\fR
.ad
.RS 11n
The object is a directory.
.RE

.sp
.ne 2
.na
\fB\fBFTW_DP\fR\fR
.ad
.RS 11n
The object is a directory and subdirectories have been visited. (This condition
only occurs if the FTW_DEPTH flag is included in flags.)
.RE

.sp
.ne 2
.na
\fB\fBFTW_SL\fR\fR
.ad
.RS 11n
The object is a symbolic link. (This condition only occurs if the FTW_PHYS flag
is included in flags.)
.RE

.sp
.ne 2
.na
\fB\fBFTW_SLN\fR\fR
.ad
.RS 11n
The object is a symbolic link that points to a non-existent file. (This
condition only occurs if the FTW_PHYS flag is not included in flags.)
.RE

.sp
.ne 2
.na
\fB\fBFTW_DNR\fR\fR
.ad
.RS 11n
The object is a directory that cannot be read.  The user-defined function
\fIfn\fR will not be called for any of its descendants.
.RE

.sp
.ne 2
.na
\fB\fBFTW_NS\fR\fR
.ad
.RS 11n
The \fBstat()\fR function failed on the object because of lack of appropriate
permission. The stat buffer passed to \fIfn\fR is undefined.  Failure of
\fBstat()\fR for any other reason is considered an error and \fBnftw()\fR
returns \(mi1.
.RE

.RE

.RE
.RS +4
.TP
.ie t \(bu
.el o
The fourth argument is a pointer to an \fBFTW\fR structure that contains the
following members:
.sp
.in +2
.nf
int   base;
int   level;
.fi
.in -2

The \fBbase\fR member is the offset of the object's filename in the pathname
passed as the first argument to \fIfn\fR(). The value of \fBlevel\fR indicates
the depth relative to the root of the walk, where the root level is 0.
.sp
The results are unspecified if the application-supplied \fIfn\fR() function
does not preserve the current working directory.
.RE
.sp
.LP
Both \fBftw()\fR and \fBnftw()\fR use one file descriptor for each level in the
tree. The \fIdepth\fR argument limits the number of file descriptors used. If
\fIdepth\fR is zero or negative, the effect is the same as if it were 1. It
must not be greater than the number of file descriptors currently available for
use.  The \fBftw()\fR function runs faster if \fIdepth\fR is at least as large
as the number of levels in the tree. Both \fBftw()\fR and \fBnftw()\fR 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
\fIpath\fR argument exceeds {\fBPATH_MAX\fR} requirements, or for \fBftw()\fR,
the specified depth is less than 2, or for \fBnftw()\fR, the specified depth is
less than 2 and \fBFTW_CHDIR\fR is not set. When \fBftw()\fR and \fBnftw()\fR
return, they close any file descriptors they have opened; they do not close any
file descriptors that might have been opened by \fIfn\fR.
.SH RETURN VALUES
.sp
.LP
If the tree is exhausted, \fBftw()\fR and \fBnftw()\fR return \fB0\fR. If the
function pointed to by \fIfn\fR returns a non-zero value, \fBftw()\fR and
\fBnftw()\fR stop their tree traversal and return whatever value was returned
by the function pointed to by \fIfn\fR. If \fBftw()\fR and \fBnftw()\fR detect
an error,  they return \fB\(mi1\fR and set \fBerrno\fR to indicate the error.
.sp
.LP
If \fBftw()\fR and \fBnftw()\fR encounter an error other than \fBEACCES\fR (see
\fBFTW_DNR\fR and \fBFTW_NS\fR above),  they return \fB\(mi1\fR and set
\fBerrno\fR to indicate the error. The external variable \fBerrno\fR can
contain any error value that is possible when a directory is opened or when one
of the \fBstat\fR functions is executed on a directory or file.
.SH ERRORS
.sp
.LP
The \fBftw()\fR and \fBnftw()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBELOOP\fR\fR
.ad
.RS 16n
A loop exists in symbolic links encountered during resolution of the \fIpath\fR
argument
.RE

.sp
.ne 2
.na
\fB\fBENAMETOOLONG\fR\fR
.ad
.RS 16n
The length of the path name pointed to by the \fIpath\fR argument exceeds
{\fBPATH_MAX\fR}, or a path name component is longer than {\fBNAME_MAX\fR}.
.RE

.sp
.ne 2
.na
\fB\fBENOENT\fR\fR
.ad
.RS 16n
A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
empty string.
.RE

.sp
.ne 2
.na
\fB\fBENOTDIR\fR\fR
.ad
.RS 16n
A component of \fIpath\fR is not a directory.
.RE

.sp
.ne 2
.na
\fB\fBEOVERFLOW\fR\fR
.ad
.RS 16n
A field in the \fBstat\fR structure cannot be represented correctly in the
current programming environment for one or more files found in the file
hierarchy.
.RE

.sp
.LP
The \fBftw()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 16n
Search permission is denied for any component of \fIpath\fR or read permission
is denied for \fIpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBENAMETOOLONG\fR\fR
.ad
.RS 16n
The \fBftw()\fR function has descended to a path that exceeds {\fBPATH_MAX\fR}
and the depth argument specified by the application is less than 2 and
\fBFTW_CHDIR\fR is not set.
.RE

.sp
.LP
The \fBnftw()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 10n
Search permission is denied for any component of \fIpath\fR or read permission
is denied for \fIpath\fR, or \fIfn\fR() returns \(mi1 and does not reset
\fBerrno\fR.
.RE

.sp
.LP
The \fBnftw()\fR and \fBftw()\fR functions may fail if:
.sp
.ne 2
.na
\fB\fBELOOP\fR\fR
.ad
.RS 16n
Too many symbolic links were encountered during resolution of the \fIpath\fR
argument.
.RE

.sp
.ne 2
.na
\fB\fBENAMETOOLONG\fR\fR
.ad
.RS 16n
Pathname resolution of a symbolic link in the path name pointed to by the
\fIpath\fR argument produced an intermediate result whose length exceeds
{\fBPATH_MAX\fR}.
.RE

.sp
.LP
The \fBftw()\fR function may fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The value of the \fIdepth\fR argument is invalid.
.RE

.sp
.LP
The \fBnftw()\fR function may fail if:
.sp
.ne 2
.na
\fB\fBEMFILE\fR\fR
.ad
.RS 10n
There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
process.
.RE

.sp
.ne 2
.na
\fB\fBENFILE\fR\fR
.ad
.RS 10n
Too many files are currently open in the system.
.RE

.sp
.LP
If the function pointed to by \fIfn\fR encounters system errors, \fBerrno\fR
may be set accordingly.
.SH EXAMPLES
.LP
\fBExample 1 \fRWalk a directory structure using \fBftw()\fR.
.sp
.LP
The following example walks the current directory structure, calling the
\fIfn\fR() function for every directory entry, using at most 10 file
descriptors:

.sp
.in +2
.nf
#include <ftw.h>
\&...
if (ftw(".", fn, 10) != 0) {
       perror("ftw"); exit(2);
}
.fi
.in -2

.LP
\fBExample 2 \fRWalk a directory structure using \fBnftw()\fR.
.sp
.LP
The following example walks the \fB/tmp\fR directory and its subdirectories,
calling the \fBnftw()\fR function for every directory entry, to a maximum of 5
levels deep.

.sp
.in +2
.nf
#include <ftw.h>
\&...
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 = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
int ret;
ret = nftw(startpath, nftwfunc, depth, flags);
.fi
.in -2

.SH USAGE
.sp
.LP
Because \fBftw()\fR and \fBnftw()\fR are recursive, they can terminate with a
memory fault when applied by a thread with a small stack to very deep file
structures.
.sp
.LP
The \fBftw()\fR and \fBnftw()\fR functions allocate resources (memory, file
descriptors) during their operation. If \fBftw()\fR they are forcibly
terminated, such as by \fBlongjmp\fR(3C) being executed by \fIfn\fR or an
interrupt routine, they will not have a chance to free those resources, so they
remain permanently allocated. A safe way to handle interrupts is to store the
fact that an interrupt has occurred and arrange to have \fIfn\fR return a
non-zero value at its next invocation.
.sp
.LP
The \fBftw()\fR and \fBnftw()\fR functions have transitional interfaces for
64-bit file offsets.  See \fBlf64\fR(5).
.sp
.LP
The \fBftw()\fR function is safe in multithreaded applications. The
\fBnftw()\fR function is safe in multithreaded applications when the
\fBFTW_CHDIR\fR flag is not set.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
_
MT-Level	MT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
\fBstat\fR(2), \fBlongjmp\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5),
\fBstandards\fR(5)