mirror of https://github.com/mkerrisk/man-pages
169 lines
5.7 KiB
Groff
169 lines
5.7 KiB
Groff
.\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
|
|
.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
|
|
.\" Fri Jun 25 00:34:07 CEST 1999
|
|
.\"
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
.\" the License, or (at your option) any later version.
|
|
.\"
|
|
.\" The GNU General Public License's references to "object code"
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
.\" document formatting or typesetting system, including
|
|
.\" intermediate and printed output.
|
|
.\"
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, write to the Free
|
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
|
.\" USA.
|
|
.\"
|
|
.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
|
|
.TH FTW 3 1999-06-25 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
ftw, nftw \- file tree walk
|
|
.SH SYNOPSIS
|
|
.B #include <ftw.h>
|
|
.sp
|
|
.BI "int ftw(const char *" dir ", int (*" fn ")(const"
|
|
.BI "char *" file ", const struct stat *" sb ", int " flag ),
|
|
.BI "int " nopenfd );
|
|
.sp
|
|
.BI "int nftw(const char *" dir ", int (*" fn ")(const"
|
|
.BI "char *" file ", const struct stat *" sb ", int " flag ,
|
|
.BI "struct FTW *" s ),
|
|
.BI "int " nopenfd ", int " flags );
|
|
.SH DESCRIPTION
|
|
\fBftw\fP() walks through the directory tree starting from the indicated
|
|
directory \fIdir\fP. For each found entry in the tree, it calls
|
|
\fIfn\fP() with the full pathname of the entry, a pointer to the
|
|
.BR stat (2)
|
|
structure for the entry and an int \fIflag\fP, which value will be one of
|
|
the following:
|
|
.TP
|
|
.B FTW_F
|
|
Item is a normal file
|
|
.TP
|
|
.B FTW_D
|
|
Item is a directory
|
|
.TP
|
|
.B FTW_DNR
|
|
Item is a directory which can't be read
|
|
.TP
|
|
.B FTW_SL
|
|
Item is a symbolic link
|
|
.TP
|
|
.B FTW_NS
|
|
The stat failed on the item which is not a symbolic link
|
|
.LP
|
|
If the item is a symbolic link and stat failed, XPG4v2 states
|
|
that it is undefined whether FTW_NS or FTW_SL is used.
|
|
.PP
|
|
\fBftw\fP() recursively calls itself for traversing found directories,
|
|
handling a directory before its files or subdirectories.
|
|
To avoid using up all a program's file descriptors, \fInopenfd\fP
|
|
specifies the maximum number of simultaneous open directories. When
|
|
the search depth exceeds this, \fBftw\fP() will become slower because
|
|
directories have to be closed and reopened. \fBftw\fP() uses at most
|
|
one file descriptor for each level in the file hierarchy.
|
|
.PP
|
|
To stop the tree walk, \fIfn\fP() returns a non-zero value; this
|
|
value will become the return value of \fBftw\fP(). Otherwise,
|
|
\fBftw\fP() will continue until it has traversed the entire tree, in
|
|
which case it will return zero, or until it hits an error other than EACCES
|
|
(such as a
|
|
.BR malloc (3)
|
|
failure), in which case it will return \-1.
|
|
.PP
|
|
Because \fBftw\fP() uses dynamic data structures, the only safe way to
|
|
exit out of a tree walk is to return a non-zero value. To handle
|
|
interrupts, for example, mark that the interrupt occurred and return a
|
|
non-zero value\(emdon't use
|
|
.BR longjmp (3)
|
|
unless the program is going to terminate.
|
|
|
|
The function \fBnftw\fP() does precisely the same as \fBftw\fP(),
|
|
except that it has one additional argument \fIflags\fP
|
|
(and calls the supplied function with one more argument).
|
|
This \fIflags\fP argument is an OR of zero or more of the following flags:
|
|
.TP
|
|
.B FTW_CHDIR
|
|
If set, do a
|
|
.IR chdir ()
|
|
to each directory before handling its contents.
|
|
.TP
|
|
.B FTW_DEPTH
|
|
If set, do a depth-first search, that is, call the function for
|
|
the directory itself only after handling the contents of the directory
|
|
and its subdirectories.
|
|
.TP
|
|
.B FTW_MOUNT
|
|
If set, stay within the same file system.
|
|
.TP
|
|
.B FTW_PHYS
|
|
If set, do not follow symbolic links.
|
|
(This is what you want.)
|
|
If not set, symbolic links are followed, but no file is reported twice.
|
|
.LP
|
|
If FTW_PHYS is not set, but FTW_DEPTH is set, then the function
|
|
.IR fn ()
|
|
is never called for a directory that would be a descendant of itself.
|
|
.LP
|
|
The function
|
|
.IR fn ()
|
|
is called with four arguments: the pathname of the reported entry,
|
|
a pointer to a struct stat for this entry, an integer describing
|
|
its type, and a pointer to a struct FTW. The type will be one
|
|
of the following: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS
|
|
(with meaning as above; FTW_SL occurs only with FTW_PHYS set) or
|
|
.TP
|
|
.B FTW_DP
|
|
Item is a directory and all its descendants have been handled
|
|
already. (This occurs only with FTW_DEPTH set.)
|
|
.TP
|
|
.B FTW_SLN
|
|
Item is a symbolic link pointing to a nonexisting file.
|
|
(This occurs only with FTW_PHYS unset.)
|
|
.LP
|
|
The struct FTW pointed to by the fourth argument to
|
|
.IR fn ()
|
|
has at least the fields
|
|
.IR base ,
|
|
the offset of the item's filename in the pathname
|
|
given as first argument of
|
|
.IR fn (),
|
|
and
|
|
.IR level ,
|
|
the depth of the item relative to the starting point
|
|
(which has depth 0).
|
|
.SH NOTES
|
|
The function
|
|
.IR nftw ()
|
|
and the use of FTW_SL with
|
|
.IR ftw ()
|
|
were introduced in XPG4v2.
|
|
.LP
|
|
On some systems
|
|
.IR ftw ()
|
|
will never use FTW_SL, on other systems FTW_SL occurs only
|
|
for symbolic links that do not point to an existing file,
|
|
and again on other systems
|
|
.IR ftw ()
|
|
will use FTW_SL for each symbolic link. For predictable control, use
|
|
.IR nftw ().
|
|
.LP
|
|
Under Linux, libc4 and libc5 and glibc 2.0.6 will
|
|
use FTW_F for all objects (files, symbolic links, fifos, etc)
|
|
that can be stat'ed but are not a directory.
|
|
The function
|
|
.IR nftw ()
|
|
is available since glibc 2.1.
|
|
.SH "CONFORMING TO"
|
|
AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.
|
|
.SH "SEE ALSO"
|
|
.BR stat (2)
|