Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 502 insertions, 0 deletions

diff --git a/man/man3/ftw.3 b/man/man3/ftw.3
new file mode 100644
index 0000000..41fd4dc
--- /dev/null
+++ b/man/man3/ftw.3
@@ -0,0 +1,502 @@
+'\" t
+.\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
+.\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
+.\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net>
+.\" and copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" 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>
+.\"  	document FTW_ACTIONRETVAL; include .SH RETURN VALUE;
+.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and
+.\"	Michael Kerrisk <mtk.manpages@gmail.com>
+.\" 	reorganized and rewrote much of the page
+.\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"	Added an example program.
+.\"
+.TH ftw 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+ftw, nftw \- file tree walk
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <ftw.h>
+.P
+.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 );
+.P
+.B [[deprecated]]
+.BI "int ftw(const char *" dirpath ,
+.BI "        int (*" fn ")(const char *" fpath ", const struct stat *" sb ,
+.BI "                  int " typeflag ),
+.BI "        int " nopenfd );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR nftw ():
+.nf
+    _XOPEN_SOURCE >= 500
+.fi
+.SH DESCRIPTION
+.BR nftw ()
+walks through the directory tree that is
+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).
+.P
+To avoid using up all of the calling process's file descriptors,
+\fInopenfd\fP specifies the maximum number of directories that
+.BR nftw ()
+will hold open simultaneously.
+When
+the search depth exceeds this,
+.BR nftw ()
+will become slower because
+directories have to be closed and reopened.
+.BR nftw ()
+uses at most
+one file descriptor for each level in the directory tree.
+.P
+For each entry found in the tree,
+.BR nftw ()
+calls
+\fIfn\fP() with four arguments:
+.IR fpath ,
+.IR sb ,
+.IR typeflag ,
+and
+.IR ftwbuf .
+.I fpath
+is the pathname of the entry,
+and is expressed either as a pathname relative to the calling process's
+current working directory at the time of the call to
+.BR nftw (),
+if
+.I dirpath
+was expressed as a relative pathname,
+or as an absolute pathname, if
+.I dirpath
+was expressed as an absolute pathname.
+.I sb
+is a pointer to the
+.I stat
+structure returned by a call to
+.BR stat (2)
+for
+.IR fpath .
+.P
+The
+.I typeflag
+argument passed to
+.IR fn ()
+is an integer that has one of the following values:
+.TP
+.B FTW_F
+.I fpath
+is a regular file.
+.TP
+.B FTW_D
+.I fpath
+is a directory.
+.TP
+.B FTW_DNR
+.I fpath
+is a directory which can't be read.
+.TP
+.B FTW_DP
+.I fpath
+is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
+(If
+.B FTW_DEPTH
+was not specified in
+.IR flags ,
+then directories will always be visited with
+.I typeflag
+set to
+.BR FTW_D .)
+All of the files
+and subdirectories within \fIfpath\fP have been processed.
+.TP
+.B FTW_NS
+The
+.BR stat (2)
+call failed on
+.IR fpath ,
+which is not a symbolic link.
+The probable cause for this is that the caller had read permission
+on the parent directory, so that the filename
+.I fpath
+could be seen,
+but did not have execute permission,
+so that the file could not be reached for
+.BR stat (2).
+The contents of the buffer pointed to by
+.I sb
+are undefined.
+.TP
+.B FTW_SL
+.I fpath
+is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
+.\" To obtain the definition of this constant from
+.\" .IR <ftw.h> ,
+.\" either
+.\" .B _BSD_SOURCE
+.\" must be defined, or
+.\" .BR _XOPEN_SOURCE
+.\" must be defined with a value of 500 or more.
+.TP
+.B FTW_SLN
+.I fpath
+is a symbolic link pointing to a nonexistent file.
+(This occurs only if \fBFTW_PHYS\fP is not set.)
+In this case the
+.I sb
+argument passed to
+.IR fn ()
+contains information returned by performing
+.BR lstat (2)
+on the "dangling" symbolic link.
+(But see BUGS.)
+.P
+The fourth argument
+.RI ( ftwbuf )
+that
+.BR nftw ()
+supplies when calling
+\fIfn\fP()
+is a pointer to a structure of type \fIFTW\fP:
+.P
+.in +4n
+.EX
+struct FTW {
+    int base;
+    int level;
+};
+.EE
+.in
+.P
+.I base
+is the offset of the filename (i.e., basename component)
+in the pathname given in
+.IR fpath .
+.I level
+is the depth of
+.I fpath
+in the directory tree, relative to the root of the tree
+.RI ( dirpath ,
+which has depth 0).
+.P
+To stop the tree walk, \fIfn\fP() returns a nonzero value; this
+value will become the return value of
+.BR nftw ().
+As long as \fIfn\fP() returns 0,
+.BR nftw ()
+will continue either until it has traversed the entire tree,
+in which case it will return zero,
+or until it encounters an error (such as a
+.BR malloc (3)
+failure), in which case it will return \-1.
+.P
+Because
+.BR nftw ()
+uses dynamic data structures, the only safe way to
+exit out of a tree walk is to return a nonzero value from \fIfn\fP().
+To allow a signal to terminate the walk without causing a memory leak,
+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.
+.P
+The \fIflags\fP argument of
+.BR nftw ()
+is formed by ORing zero or more of the
+following flags:
+.TP
+.BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
+If this glibc-specific flag is set, then
+.BR nftw ()
+handles the return value from
+.IR fn ()
+differently.
+.IR fn ()
+should return one of the following values:
+.RS
+.TP
+.B FTW_CONTINUE
+Instructs
+.BR nftw ()
+to continue normally.
+.TP
+.B FTW_SKIP_SIBLINGS
+If \fIfn\fP() returns this value, then
+siblings of the current entry will be skipped,
+and processing continues in the parent.
+.\" If \fBFTW_DEPTH\fP
+.\" is set, the entry's parent directory is processed next (with
+.\" \fIflag\fP set to \fBFTW_DP\fP).
+.TP
+.B FTW_SKIP_SUBTREE
+If \fIfn\fP() is called with an entry that is a directory
+(\fItypeflag\fP is \fBFTW_D\fP), this return
+value will prevent objects within that directory from being passed as
+arguments to \fIfn\fP().
+.BR nftw ()
+continues processing with the next sibling of the directory.
+.TP
+.B FTW_STOP
+Causes
+.BR nftw ()
+to return immediately with the return value
+\fBFTW_STOP\fP.
+.P
+Other return values could be associated with new actions in the future;
+\fIfn\fP() should not return values other than those listed above.
+.P
+The feature test macro
+.B _GNU_SOURCE
+must be defined
+(before including
+.I any
+header files)
+in order to
+obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
+.RE
+.TP
+.B FTW_CHDIR
+If set, do a
+.BR chdir (2)
+to each directory before handling its contents.
+This is useful if the program needs to perform some action
+in the directory in which \fIfpath\fP resides.
+(Specifying this flag has no effect on the pathname that is passed in the
+.I fpath
+argument of
+.IR fn .)
+.TP
+.B FTW_DEPTH
+If set, do a post-order traversal, that is, call \fIfn\fP() for
+the directory itself \fIafter\fP handling the contents of the directory
+and its subdirectories.
+(By default, each directory is handled \fIbefore\fP its contents.)
+.TP
+.B FTW_MOUNT
+If set, stay within the same filesystem
+(i.e., do not cross mount points).
+.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.
+.IP
+If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
+then the function
+.IR fn ()
+is never called for a directory that would be a descendant of itself.
+.SS ftw()
+.BR ftw ()
+is an older function that offers a subset of the functionality of
+.BR nftw ().
+The notable differences are as follows:
+.IP \[bu] 3
+.BR ftw ()
+has no
+.I flags
+argument.
+It behaves the same as when
+.BR nftw ()
+is called with
+.I flags
+specified as zero.
+.IP \[bu]
+The callback function,
+.IR fn (),
+is not supplied with a fourth argument.
+.IP \[bu]
+The range of values that is passed via the
+.I typeflag
+argument supplied to
+.IR fn ()
+is smaller: just
+.BR FTW_F ,
+.BR FTW_D ,
+.BR FTW_DNR ,
+.BR FTW_NS ,
+and (possibly)
+.BR FTW_SL .
+.SH RETURN VALUE
+These functions return 0 on success, and \-1 if an error occurs.
+.P
+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 ().
+.P
+If
+.BR nftw ()
+is called with the \fBFTW_ACTIONRETVAL\fP flag,
+then the only nonzero value that should be used by \fIfn\fP()
+to terminate the tree walk is \fBFTW_STOP\fP,
+and that value is returned as the result of
+.BR nftw ().
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR nftw ()
+T}	Thread safety	MT-Safe cwd
+T{
+.na
+.nh
+.BR ftw ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+In some implementations (e.g., glibc),
+.BR ftw ()
+will never use \fBFTW_SL\fP; on other systems \fBFTW_SL\fP occurs only
+for symbolic links that do not point to an existing file;
+and again on other systems
+.BR ftw ()
+will use \fBFTW_SL\fP for each symbolic link.
+If
+.I fpath
+is a symbolic link and
+.BR stat (2)
+failed, POSIX.1-2008 states
+that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP
+is passed in
+.IR typeflag .
+For predictable results, use
+.BR nftw ().
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR ftw ()
+POSIX.1-2001, SVr4, SUSv1.
+POSIX.1-2008 marks it as obsolete.
+.TP
+.BR nftw ()
+glibc 2.1.
+POSIX.1-2001, SUSv1.
+.TP
+.B FTW_SL
+POSIX.1-2001, SUSv1.
+.SH NOTES
+POSIX.1-2008 notes that the results are unspecified if
+.I fn
+does not preserve the current working directory.
+.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.
+It displays various information about each file.
+The second command-line argument can be used to specify characters that
+control the value assigned to the \fIflags\fP
+argument when calling
+.BR nftw ().
+.SS Program source
+\&
+.\" SRC BEGIN (ftw.c)
+.EX
+#define _XOPEN_SOURCE 500
+#include <ftw.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+\&
+static int
+display_info(const char *fpath, const struct stat *sb,
+             int tflag, struct FTW *ftwbuf)
+{
+    printf("%\-3s %2d ",
+           (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
+           (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
+           (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
+           (tflag == FTW_SLN) ? "sln" : "???",
+           ftwbuf\->level);
+\&
+    if (tflag == FTW_NS)
+        printf("\-\-\-\-\-\-\-");
+    else
+        printf("%7jd", (intmax_t) sb\->st_size);
+\&
+    printf("   %\-40s %d %s\en",
+           fpath, ftwbuf\->base, fpath + ftwbuf\->base);
+\&
+    return 0;           /* To tell nftw() to continue */
+}
+\&
+int
+main(int argc, char *argv[])
+{
+    int flags = 0;
+\&
+    if (argc > 2 && strchr(argv[2], \[aq]d\[aq]) != NULL)
+        flags |= FTW_DEPTH;
+    if (argc > 2 && strchr(argv[2], \[aq]p\[aq]) != NULL)
+        flags |= FTW_PHYS;
+\&
+    if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
+        == \-1)
+    {
+        perror("nftw");
+        exit(EXIT_FAILURE);
+    }
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR stat (2),
+.BR fts (3),
+.BR readdir (3)