.\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net>
.\" and copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
-.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
-.\" 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, see
-.\" <http://www.gnu.org/licenses/>.
-.\" %%%LICENSE_END
+.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net>
.\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Added an example program.
.\"
-.TH FTW 3 2017-07-13 "Linux" "Linux Programmer's Manual"
+.TH FTW 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
.SH NAME
ftw, nftw \- file tree walk
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <ftw.h>
.PP
.BI "int nftw(const char *" dirpath ,
-.BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
-.BI " int " typeflag ", struct FTW *" ftwbuf ),
+.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb ,
+.BI " int " typeflag ", struct FTW *" ftwbuf ),
.BI " int " nopenfd ", int " flags );
.PP
-.B #include <ftw.h>
-.PP
.BI "int ftw(const char *" dirpath ,
-.BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
-.BI " int " typeflag ),
+.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb ,
+.BI " int " typeflag ),
.BI " int " nopenfd );
.fi
.PP
-.in -4n
+.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
-.in
+.RE
.PP
.BR nftw ():
-_XOPEN_SOURCE >= 500
+.nf
+ _XOPEN_SOURCE >= 500
+.fi
.SH DESCRIPTION
.BR nftw ()
walks through the directory tree that is
current working directory at the time of the call to
.BR nftw (),
if
-.IR dirpath
+.I dirpath
was expressed as a relative pathname,
or as an absolute pathname, if
.I dirpath
.I fpath
is a symbolic link pointing to a nonexistent file.
(This occurs only if \fBFTW_PHYS\fP is not set.)
-On most implementations, in this case the
+In this case the
.I sb
argument passed to
.IR fn ()
contains information returned by performing
.BR lstat (2)
-on the symbolic link.
-For the details on Linux, see BUGS.
+on the "dangling" symbolic link.
+(But see BUGS.)
.PP
The fourth argument
.RI ( ftwbuf )
supplies when calling
\fIfn\fP()
is a pointer to a structure of type \fIFTW\fP:
+.PP
.in +4n
-.nf
-
+.EX
struct FTW {
int base;
int level;
};
-
-.fi
+.EE
.in
+.PP
.I base
is the offset of the filename (i.e., basename component)
in the pathname given in
.IP * 3
.BR ftw ()
has no
-.IR flags
+.I flags
argument.
It behaves the same as when
.BR nftw ()
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
+.ad l
+.nh
.TS
allbox;
-lb lb lb
+lbx lb lb
l l l.
Interface Attribute Value
T{
.BR ftw ()
T} Thread safety MT-Safe
.TE
+.hy
+.ad
.sp 1
-.SH CONFORMING TO
+.SH STANDARDS
POSIX.1-2001, POSIX.1-2008, SVr4, SUSv1.
POSIX.1-2008 marks
.BR ftw ()
and the use of \fBFTW_SL\fP with
.BR ftw ()
were introduced in SUSv1.
-.LP
+.PP
In some implementations (e.g., glibc),
.BR ftw ()
will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
.IR typeflag .
For predictable results, use
.BR nftw ().
-.SH EXAMPLE
+.SH BUGS
+According to POSIX.1-2008, when the
+.I typeflag
+argument passed to
+.IR fn ()
+contains
+.BR FTW_SLN ,
+the buffer pointed to by
+.I sb
+should contain information about the dangling symbolic link
+(obtained by calling
+.BR lstat (2)
+on the link).
+Early glibc versions correctly followed the POSIX specification on this point.
+However, as a result of a regression introduced in glibc 2.4,
+the contents of the buffer pointed to by
+.I sb
+were undefined when
+.B FTW_SLN
+is passed in
+.IR typeflag .
+(More precisely, the contents of the buffer were left unchanged in this case.)
+This regression was eventually fixed in glibc 2.30,
+.\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736
+.\" http://austingroupbugs.net/view.php?id=1121
+.\" glibc commit 6ba205b2c35e3e024c8c12d2ee1b73363e84da87
+.\" https://sourceware.org/bugzilla/show_bug.cgi?id=23501
+so that the glibc implementation (once more) follows the POSIX specification.
+.SH EXAMPLES
The following program traverses the directory tree under the path named
in its first command-line argument, or under the current directory
if no argument is supplied.
argument when calling
.BR nftw ().
.SS Program source
+\&
.EX
#define _XOPEN_SOURCE 500
#include <ftw.h>
else
printf("%7jd", (intmax_t) sb\->st_size);
- printf(" %\-40s %d %s\\n",
+ printf(" %\-40s %d %s\en",
fpath, ftwbuf\->base, fpath + ftwbuf\->base);
return 0; /* To tell nftw() to continue */
exit(EXIT_SUCCESS);
}
.EE
-.SH BUGS
-In the specification of
-.BR nftw (),
-POSIX.1 notes that when
-.B FTW_NS
-is passed as the
-.I typeflag
-argument of
-.IR fn (),
-then the contents of the buffer pointed to by the
-.I sb
-argument are undefined.
-The standard makes no such statement for the case where
-.B FTW_SLN
-is passed in
-.IR typeflag ,
-with the implication that the contents of the buffer pointed to by
-.I sb
-are defined.
-And indeed this is the case on most implementations: the buffer pointed to by
-.I sb
-contains the results produced by applying
-.BR lstat (2)
-to the symbolic link.
-In early glibc, the behavior was the same.
-However, since glibc 2.4, the contents of the buffer pointed to by
-.I sb
-are undefined when
-.B FTW_SLN
-is passed in
-.IR typeflag .
-This change
-.I appears
-to be an unintended regression,
-but it is not (yet) clear if the behavior will be restored to that
-provided in the original glibc implementation (and on other implementations).
-.\" FIXME .
-.\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736
-.\" http://austingroupbugs.net/view.php?id=1121
.SH SEE ALSO
.BR stat (2),
.BR fts (3),
projects / thirdparty / man-pages.git / blobdiff