summaryrefslogtreecommitdiffstats
path: root/man3/readdir_r.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/readdir_r.3')
-rw-r--r--man3/readdir_r.3145
1 files changed, 0 insertions, 145 deletions
diff --git a/man3/readdir_r.3 b/man3/readdir_r.3
deleted file mode 100644
index f90a70b..0000000
--- a/man3/readdir_r.3
+++ /dev/null
@@ -1,145 +0,0 @@
-'\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)