.\" 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 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
ftw, nftw \- file tree walk
.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 " 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 " nopenfd );
.fi
-.sp
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
-.sp
+.PP
.BR nftw ():
_XOPEN_SOURCE >= 500
.SH DESCRIPTION
and calls \fIfn\fP() once for each entry in the tree.
By default, directories are handled before the files and
subdirectories they contain (preorder traversal).
-
+.PP
To avoid using up all of the calling process's file descriptors,
\fInopenfd\fP specifies the maximum number of directories that
.BR nftw ()
.BR nftw ()
uses at most
one file descriptor for each level in the directory tree.
-
+.PP
For each entry found in the tree,
.BR nftw ()
calls
.BR stat (2)
for
.IR fpath .
-
+.PP
The
.I typeflag
argument passed to
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
\fIDon't\fP use
.BR longjmp (3)
unless the program is going to terminate.
-
+.PP
The \fIflags\fP argument of
.BR nftw ()
is formed by ORing zero or more of the
.PP
Other return values could be associated with new actions in the future;
\fIfn\fP() should not return values other than those listed above.
-
+.PP
The feature test macro
.B _GNU_SOURCE
must be defined
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.
-.sp
+.IP
If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
then the function
.IR fn ()
.BR FTW_SL .
.SH RETURN VALUE
These functions return 0 on success, and \-1 if an error occurs.
-
+.PP
If \fIfn\fP() returns nonzero,
then the tree walk is terminated and the value returned by \fIfn\fP()
is returned as the result of
.BR ftw ()
or
.BR nftw ().
-
+.PP
If
.BR nftw ()
is called with the \fBFTW_ACTIONRETVAL\fP flag,
.BR ftw ()
T} Thread safety MT-Safe
.TE
-
+.sp 1
.SH CONFORMING TO
POSIX.1-2001, POSIX.1-2008, SVr4, SUSv1.
POSIX.1-2008 marks
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 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 EXAMPLE
The following program traverses the directory tree under the path named
in its first command-line argument, or under the current directory
argument when calling
.BR nftw ().
.SS Program source
-.nf
+\&
+.EX
#define _XOPEN_SOURCE 500
#include <ftw.h>
#include <stdio.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);
}
-.fi
-.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
+.EE
.SH SEE ALSO
.BR stat (2),
.BR fts (3),
projects / thirdparty / man-pages.git / blobdiff