summaryrefslogtreecommitdiffstats
path: root/man3/ftw.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/ftw.3')
-rw-r--r--man3/ftw.337
1 files changed, 18 insertions, 19 deletions
diff --git a/man3/ftw.3 b/man3/ftw.3
index b231135..1488b92 100644
--- a/man3/ftw.3
+++ b/man3/ftw.3
@@ -15,7 +15,7 @@
.\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Added an example program.
.\"
-.TH ftw 3 2023-07-20 "Linux man-pages 6.05.01"
+.TH ftw 3 2023-10-31 "Linux man-pages 6.7"
.SH NAME
ftw, nftw \- file tree walk
.SH LIBRARY
@@ -24,24 +24,24 @@ Standard C library
.SH SYNOPSIS
.nf
.B #include <ftw.h>
-.PP
+.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 );
-.PP
+.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
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR nftw ():
.nf
_XOPEN_SOURCE >= 500
@@ -53,7 +53,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
+.P
To avoid using up all of the calling process's file descriptors,
\fInopenfd\fP specifies the maximum number of directories that
.BR nftw ()
@@ -66,7 +66,7 @@ directories have to be closed and reopened.
.BR nftw ()
uses at most
one file descriptor for each level in the directory tree.
-.PP
+.P
For each entry found in the tree,
.BR nftw ()
calls
@@ -94,7 +94,7 @@ structure returned by a call to
.BR stat (2)
for
.IR fpath .
-.PP
+.P
The
.I typeflag
argument passed to
@@ -167,7 +167,7 @@ contains information returned by performing
.BR lstat (2)
on the "dangling" symbolic link.
(But see BUGS.)
-.PP
+.P
The fourth argument
.RI ( ftwbuf )
that
@@ -175,7 +175,7 @@ that
supplies when calling
\fIfn\fP()
is a pointer to a structure of type \fIFTW\fP:
-.PP
+.P
.in +4n
.EX
struct FTW {
@@ -184,7 +184,7 @@ struct FTW {
};
.EE
.in
-.PP
+.P
.I base
is the offset of the filename (i.e., basename component)
in the pathname given in
@@ -195,7 +195,7 @@ is the depth of
in the directory tree, relative to the root of the tree
.RI ( dirpath ,
which has depth 0).
-.PP
+.P
To stop the tree walk, \fIfn\fP() returns a nonzero value; this
value will become the return value of
.BR nftw ().
@@ -206,7 +206,7 @@ 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.
-.PP
+.P
Because
.BR nftw ()
uses dynamic data structures, the only safe way to
@@ -216,7 +216,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
+.P
The \fIflags\fP argument of
.BR nftw ()
is formed by ORing zero or more of the
@@ -258,10 +258,10 @@ Causes
.BR nftw ()
to return immediately with the return value
\fBFTW_STOP\fP.
-.PP
+.P
Other return values could be associated with new actions in the future;
\fIfn\fP() should not return values other than those listed above.
-.PP
+.P
The feature test macro
.B _GNU_SOURCE
must be defined
@@ -335,14 +335,14 @@ and (possibly)
.BR FTW_SL .
.SH RETURN VALUE
These functions return 0 on success, and \-1 if an error occurs.
-.PP
+.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 ().
-.PP
+.P
If
.BR nftw ()
is called with the \fBFTW_ACTIONRETVAL\fP flag,
@@ -369,7 +369,6 @@ T{
.BR ftw ()
T} Thread safety MT-Safe
.TE
-.sp 1
.SH VERSIONS
In some implementations (e.g., glibc),
.BR ftw ()