Debian Codegraph @

upstream/debian-unstable/man3/readdir_r.3

raw
1 '\" t
2 .\" Copyright 2008-2016, Michael Kerrisk <[email protected]>
3 .\" Copyright 2016, Florian Weimer <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH readdir_r 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 readdir_r \- read a directory
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <dirent.h>
17 .P
18 .BI "[[deprecated]] int readdir_r(DIR *restrict " dirp ,
19 .BI " struct dirent *restrict " entry ,
20 .BI " struct dirent **restrict " result );
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR readdir_r ():
29 .nf
30 _POSIX_C_SOURCE
31 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
32 .fi
33 .SH DESCRIPTION
34 This function is deprecated;
35 use
36 .BR readdir (3)
37 instead.
38 .P
39 The
40 .BR readdir_r ()
41 function was invented as a reentrant version of
42 .BR readdir (3).
43 It reads the next directory entry from the directory stream
44 .IR dirp ,
45 and returns it in the caller-allocated buffer pointed to by
46 .IR entry .
47 For details of the
48 .I dirent
49 structure, see
50 .BR readdir (3).
51 .P
52 A pointer to the returned buffer is placed in
53 .IR *result ;
54 if the end of the directory stream was encountered,
55 then NULL is instead returned in
56 .IR *result .
57 .P
58 It is recommended that applications use
59 .BR readdir (3)
60 instead of
61 .BR readdir_r ().
62 Furthermore, since glibc 2.24, glibc deprecates
63 .BR readdir_r ().
64 The reasons are as follows:
65 .IP \[bu] 3
66 On systems where
67 .B NAME_MAX
68 is undefined, calling
69 .BR readdir_r ()
70 may be unsafe because the interface does not allow the caller to specify
71 the length of the buffer used for the returned directory entry.
72 .IP \[bu]
73 On some systems,
74 .BR readdir_r ()
75 can't read directory entries with very long names.
76 When the glibc implementation encounters such a name,
77 .BR readdir_r ()
78 fails with the error
79 .B ENAMETOOLONG
80 .IR "after the final directory entry has been read" .
81 On some other systems,
82 .BR readdir_r ()
83 may return a success status, but the returned
84 .I d_name
85 field may not be null terminated or may be truncated.
86 .IP \[bu]
87 In the current POSIX.1 specification (POSIX.1-2008),
88 .BR readdir (3)
89 is not required to be thread-safe.
90 However, in modern implementations (including the glibc implementation),
91 concurrent calls to
92 .BR readdir (3)
93 that specify different directory streams are thread-safe.
94 Therefore, the use of
95 .BR readdir_r ()
96 is generally unnecessary in multithreaded programs.
97 In cases where multiple threads must read from the same directory stream,
98 using
99 .BR readdir (3)
100 with external synchronization is still preferable to the use of
101 .BR readdir_r (),
102 for the reasons given in the points above.
103 .IP \[bu]
104 It is expected that a future version of POSIX.1
105 .\" FIXME .
106 .\" http://www.austingroupbugs.net/view.php?id=696
107 will make
108 .BR readdir_r ()
109 obsolete, and require that
110 .BR readdir (3)
111 be thread-safe when concurrently employed on different directory streams.
112 .SH RETURN VALUE
113 The
114 .BR readdir_r ()
115 function returns 0 on success.
116 On error, it returns a positive error number (listed under ERRORS).
117 If the end of the directory stream is reached,
118 .BR readdir_r ()
119 returns 0, and returns NULL in
120 .IR *result .
121 .SH ERRORS
122 .TP
123 .B EBADF
124 Invalid directory stream descriptor
125 .IR dirp .
126 .TP
127 .B ENAMETOOLONG
128 A directory entry whose name was too long to be read was encountered.
129 .SH ATTRIBUTES
130 For an explanation of the terms used in this section, see
131 .BR attributes (7).
132 .TS
133 allbox;
134 lbx lb lb
135 l l l.
136 Interface Attribute Value
137 T{
138 .na
139 .nh
140 .BR readdir_r ()
141 T} Thread safety MT-Safe
142 .TE
143 .SH STANDARDS
144 POSIX.1-2008.
145 .SH HISTORY
146 POSIX.1-2001.
147 .SH SEE ALSO
148 .BR readdir (3)