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