capabilities.7: Add a note about using strace on binaries that have capabilities

[thirdparty/man-pages.git] / man3 / ftw.3

diff --git a/man3/ftw.3 b/man3/ftw.3
index 26e4ccddc771b826f37f18d2d2e7c9eaccc3faf3..36556ca9d2bf659f894f6734f9419df22e5c3fcd 100644 (file)
--- a/man3/ftw.3
+++ b/man3/ftw.3
@@ -33,31 +33,31 @@
 .\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
 .\"    Added an example program.
 .\"
-.TH FTW 3 2017-03-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
@@ -67,7 +67,7 @@ located under the directory \fIdirpath\fP,
 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 ()
@@ -80,7 +80,7 @@ directories have to be closed and reopened.
 .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
@@ -108,7 +108,11 @@ structure returned by a call to
 .BR stat (2)
 for
 .IR fpath .
+.PP
+The
 .I typeflag
+argument passed to
+.IR fn ()
 is an integer that has one of the following values:
 .TP
 .B FTW_F
@@ -169,22 +173,32 @@ is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
 .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
+.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.
 .PP
-The fourth argument that
+The fourth argument
+.RI ( ftwbuf )
+that
 .BR nftw ()
 supplies when calling
 \fIfn\fP()
-is a structure of type \fIFTW\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
@@ -216,7 +230,7 @@ have the handler set a global flag that is checked by \fIfn\fP().
 \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
@@ -261,7 +275,7 @@ to return immediately with the return value
 .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
@@ -297,7 +311,7 @@ If set, stay within the same filesystem
 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 ()
@@ -335,14 +349,14 @@ and (possibly)
 .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,
@@ -368,7 +382,7 @@ T{
 .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
@@ -384,7 +398,7 @@ The function
 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
@@ -402,6 +416,45 @@ is passed in
 .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
@@ -412,7 +465,8 @@ control the value assigned to the \fIflags\fP
 argument when calling
 .BR nftw ().
 .SS Program source
-.nf
+\&
+.EX
 #define _XOPEN_SOURCE 500
 #include <ftw.h>
 #include <stdio.h>
@@ -436,7 +490,7 @@ display_info(const char *fpath, const struct stat *sb,
     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 */
@@ -460,7 +514,7 @@ main(int argc, char *argv[])
 
     exit(EXIT_SUCCESS);
 }
-.fi
+.EE
 .SH SEE ALSO
 .BR stat (2),
 .BR fts (3),