]>
Commit | Line | Data |
---|---|---|
96604453 MK |
1 | .\" Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" and Copyright (C) 2016 Florian Weimer <fweimer@redhat.com> | |
3 | .\" | |
4 | .\" %%%LICENSE_START(VERBATIM) | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
26 | .TH READDIR_R 3 2016-03-01 "" "Linux Programmer's Manual" | |
27 | .SH NAME | |
28 | readdir_r \- read a directory | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #include <dirent.h> | |
aa80442a | 32 | .PP |
96604453 MK |
33 | .BI "int readdir_r(DIR *" dirp ", struct dirent *" entry \ |
34 | ", struct dirent **" result ); | |
35 | .fi | |
aa80442a | 36 | .PP |
96604453 MK |
37 | .in -4n |
38 | Feature Test Macro Requirements for glibc (see | |
39 | .BR feature_test_macros (7)): | |
40 | .ad l | |
41 | .in | |
aa80442a | 42 | .PP |
96604453 MK |
43 | .BR readdir_r (): |
44 | .RS 4 | |
45 | _POSIX_C_SOURCE | |
46 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE | |
47 | .RE | |
48 | .ad b | |
49 | .SH DESCRIPTION | |
50 | This function is deprecated; use | |
51 | .BR readdir (3) | |
52 | instead. | |
aa80442a | 53 | .PP |
96604453 MK |
54 | The |
55 | .BR readdir_r () | |
56 | function was invented as a reentrant version of | |
57 | .BR readdir (3). | |
58 | It reads the next directory entry from the directory stream | |
59 | .IR dirp , | |
60 | and returns it in the caller-allocated buffer pointed to by | |
61 | .IR entry . | |
62 | For details of the | |
63 | .IR dirent | |
64 | structure, see | |
48bafe7c | 65 | .BR readdir (3). |
aa80442a | 66 | .PP |
96604453 MK |
67 | A pointer to the returned buffer is placed in |
68 | .IR *result ; | |
69 | if the end of the directory stream was encountered, | |
70 | then NULL is instead returned in | |
71 | .IR *result . | |
aa80442a | 72 | .PP |
96604453 | 73 | It is recommended that applications use |
fca8d7eb | 74 | .BR readdir (3) |
96604453 MK |
75 | instead of |
76 | .BR readdir_r (). | |
77 | Furthermore, since version 2.24, glibc deprecates | |
78 | .BR readdir_r (). | |
79 | The reasons are as follows: | |
80 | .IP * 3 | |
81 | On systems where | |
82 | .BR NAME_MAX | |
83 | is undefined, calling | |
84 | .BR readdir_r () | |
85 | may be unsafe because the interface does not allow the caller to specify | |
86 | the length of the buffer used for the returned directory entry. | |
87 | .IP * | |
88 | On some systems, | |
89 | .BR readdir_r () | |
90 | can't read directory entries with very long names. | |
91 | When the glibc implementation encounters such a name, | |
92 | .BR readdir_r () | |
93 | fails with the error | |
94 | .B ENAMETOOLONG | |
95 | .IR "after the final directory entry has been read" . | |
96 | On some other systems, | |
97 | .BR readdir_r () | |
98 | may return a success status, but the returned | |
99 | .IR d_name | |
100 | field may not be null terminated or may be truncated. | |
101 | .IP * | |
102 | In the current POSIX.1 specification (POSIX.1-2008), | |
103 | .BR readdir (3) | |
104 | is not required to be thread-safe. | |
105 | However, in modern implementations (including the glibc implementation), | |
106 | concurrent calls to | |
107 | .BR readdir (3) | |
108 | that specify different directory streams are thread-safe. | |
109 | Therefore, the use of | |
110 | .BR readdir_r () | |
111 | is generally unnecessary in multithreaded programs. | |
112 | In cases where multiple threads must read from the same directory stream, | |
113 | using | |
114 | .BR readdir (3) | |
115 | with external synchronization is still preferable to the use of | |
116 | .BR readdir_r (), | |
117 | for the reasons given in the points above. | |
118 | .IP * | |
119 | It is expected that a future version of POSIX.1 | |
120 | .\" FIXME . | |
121 | .\" http://www.austingroupbugs.net/view.php?id=696 | |
122 | will make | |
123 | .BR readdir_r () | |
124 | obsolete, and require that | |
fca8d7eb | 125 | .BR readdir (3) |
96604453 MK |
126 | be thread-safe when concurrently employed on different directory streams. |
127 | .SH RETURN VALUE | |
128 | The | |
129 | .BR readdir_r () | |
130 | function returns 0 on success. | |
131 | On error, it returns a positive error number (listed under ERRORS). | |
132 | If the end of the directory stream is reached, | |
133 | .BR readdir_r () | |
134 | returns 0, and returns NULL in | |
135 | .IR *result . | |
136 | .SH ERRORS | |
137 | .TP | |
138 | .B EBADF | |
139 | Invalid directory stream descriptor \fIdirp\fP. | |
140 | .TP | |
d260f95e | 141 | .B ENAMETOOLONG |
96604453 MK |
142 | A directory entry whose name was too long to be read was encountered. |
143 | .SH ATTRIBUTES | |
144 | For an explanation of the terms used in this section, see | |
145 | .BR attributes (7). | |
146 | .TS | |
147 | allbox; | |
148 | lb lb lb | |
149 | l l l. | |
150 | Interface Attribute Value | |
151 | T{ | |
152 | .BR readdir_r () | |
153 | T} Thread safety MT-Safe | |
154 | .TE | |
155 | .SH CONFORMING TO | |
156 | POSIX.1-2001, POSIX.1-2008. | |
157 | .SH SEE ALSO | |
158 | .BR readdir (3) |