Merging upstream version 6.8.

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

1 files changed, 145 insertions, 0 deletions

diff --git a/man/man3/readdir_r.3 b/man/man3/readdir_r.3
new file mode 100644
index 0000000..a46c19c
--- /dev/null
+++ b/man/man3/readdir_r.3
@@ -0,0 +1,145 @@
+'\" t
+.\" Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2016 Florian Weimer <fweimer@redhat.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH readdir_r 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+readdir_r \- read a directory
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <dirent.h>
+.P
+.BI "[[deprecated]] int readdir_r(DIR *restrict " dirp ,
+.BI "                             struct dirent *restrict " entry ,
+.BI "                             struct dirent **restrict " result );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR readdir_r ():
+.nf
+    _POSIX_C_SOURCE
+        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+This function is deprecated; use
+.BR readdir (3)
+instead.
+.P
+The
+.BR readdir_r ()
+function was invented as a reentrant version of
+.BR readdir (3).
+It reads the next directory entry from the directory stream
+.IR dirp ,
+and returns it in the caller-allocated buffer pointed to by
+.IR entry .
+For details of the
+.I dirent
+structure, see
+.BR readdir (3).
+.P
+A pointer to the returned buffer is placed in
+.IR *result ;
+if the end of the directory stream was encountered,
+then NULL is instead returned in
+.IR *result .
+.P
+It is recommended that applications use
+.BR readdir (3)
+instead of
+.BR readdir_r ().
+Furthermore, since glibc 2.24, glibc deprecates
+.BR readdir_r ().
+The reasons are as follows:
+.IP \[bu] 3
+On systems where
+.B NAME_MAX
+is undefined, calling
+.BR readdir_r ()
+may be unsafe because the interface does not allow the caller to specify
+the length of the buffer used for the returned directory entry.
+.IP \[bu]
+On some systems,
+.BR readdir_r ()
+can't read directory entries with very long names.
+When the glibc implementation encounters such a name,
+.BR readdir_r ()
+fails with the error
+.B ENAMETOOLONG
+.IR "after the final directory entry has been read" .
+On some other systems,
+.BR readdir_r ()
+may return a success status, but the returned
+.I d_name
+field may not be null terminated or may be truncated.
+.IP \[bu]
+In the current POSIX.1 specification (POSIX.1-2008),
+.BR readdir (3)
+is not required to be thread-safe.
+However, in modern implementations (including the glibc implementation),
+concurrent calls to
+.BR readdir (3)
+that specify different directory streams are thread-safe.
+Therefore, the use of
+.BR readdir_r ()
+is generally unnecessary in multithreaded programs.
+In cases where multiple threads must read from the same directory stream,
+using
+.BR readdir (3)
+with external synchronization is still preferable to the use of
+.BR readdir_r (),
+for the reasons given in the points above.
+.IP \[bu]
+It is expected that a future version of POSIX.1
+.\" FIXME .
+.\" http://www.austingroupbugs.net/view.php?id=696
+will make
+.BR readdir_r ()
+obsolete, and require that
+.BR readdir (3)
+be thread-safe when concurrently employed on different directory streams.
+.SH RETURN VALUE
+The
+.BR readdir_r ()
+function returns 0 on success.
+On error, it returns a positive error number (listed under ERRORS).
+If the end of the directory stream is reached,
+.BR readdir_r ()
+returns 0, and returns NULL in
+.IR *result .
+.SH ERRORS
+.TP
+.B EBADF
+Invalid directory stream descriptor \fIdirp\fP.
+.TP
+.B ENAMETOOLONG
+A directory entry whose name was too long to be read was encountered.
+.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 readdir_r ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH SEE ALSO
+.BR readdir (3)