Debian Codegraph @

upstream/debian-unstable/man3/readdir.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright 2008-2016, Michael Kerrisk <[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 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 readdir \- 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 "struct dirent *readdir(DIR *" dirp );
19 .fi
20 .SH DESCRIPTION
21 The
22 .BR readdir ()
23 function returns a pointer to a
24 .I dirent
25 structure
26 representing the next directory entry in the directory stream pointed
27 to by
28 .IR dirp .
29 It returns NULL on reaching the end of the directory stream or if
30 an error occurred.
31 .P
32 In the glibc implementation, the
33 .I dirent
34 structure is defined as follows:
35 .P
36 .in +4n
37 .EX
38 struct dirent {
39 ino_t d_ino; /* Inode number */
40 off_t d_off; /* Not an offset; see below */
41 unsigned short d_reclen; /* Length of this record */
42 unsigned char d_type; /* Type of file; not supported
43 by all filesystem types */
44 char d_name[256]; /* Null\-terminated filename */
45 };
46 .EE
47 .in
48 .P
49 The only fields in the
50 .I dirent
51 structure that are mandated by POSIX.1 are
52 .I .d_name
53 and
54 .IR .d_ino .
55 The other fields are unstandardized, and not present on all systems;
56 see VERSIONS.
57 .P
58 The fields of the
59 .I dirent
60 structure are as follows:
61 .TP
62 .I .d_ino
63 This is the inode number of the file
64 in the filesystem containing
65 the directory on which
66 .BR readdir ()
67 was called.
68 If the directory entry is a mount point,
69 then
70 .I .d_ino
71 differs from
72 .I .st_ino
73 returned by
74 .BR stat (2)
75 on this file:
76 .I .d_ino
77 is the inode number of the mount point,
78 while
79 .I .st_ino
80 is the inode number of the root directory of the mounted filesystem.
81 .TP
82 .I .d_off
83 The value returned in
84 .I .d_off
85 is the same as would be returned by calling
86 .BR telldir (3)
87 at the current position in the directory stream.
88 Be aware that despite its type and name, the
89 .I .d_off
90 field is seldom any kind of directory offset on modern filesystems.
91 .\" https://lwn.net/Articles/544298/
92 Applications should treat this field as an opaque value,
93 making no assumptions about its contents;
94 see also
95 .BR telldir (3).
96 .TP
97 .I .d_reclen
98 This is the size (in bytes) of the returned record.
99 This may not match the size of the structure definition shown above;
100 see VERSIONS.
101 .TP
102 .I .d_type
103 This field contains a value indicating the file type,
104 making it possible to avoid the expense of calling
105 .BR lstat (2)
106 if further actions depend on the type of the file.
107 .IP
108 When a suitable feature test macro is defined
109 .RB ( _DEFAULT_SOURCE
110 since glibc 2.19, or
111 .B _BSD_SOURCE
112 on glibc 2.19 and earlier),
113 glibc defines the following macro constants for the value returned in
114 .IR .d_type :
115 .RS
116 .TP 12
117 .B DT_BLK
118 This is a block device.
119 .TP
120 .B DT_CHR
121 This is a character device.
122 .TP
123 .B DT_DIR
124 This is a directory.
125 .TP
126 .B DT_FIFO
127 This is a named pipe (FIFO).
128 .TP
129 .B DT_LNK
130 This is a symbolic link.
131 .TP
132 .B DT_REG
133 This is a regular file.
134 .TP
135 .B DT_SOCK
136 This is a UNIX domain socket.
137 .TP
138 .B DT_UNKNOWN
139 The file type could not be determined.
140 .RE
141 .IP
142 Currently,
143 .\" kernel 2.6.27
144 .\" The same sentence is in getdents.2
145 only some filesystems (among them: Btrfs, ext2, ext3, and ext4)
146 have full support for returning the file type in
147 .IR .d_type .
148 All applications must properly handle a return of
149 .BR DT_UNKNOWN .
150 .TP
151 .I .d_name
152 This field contains the null terminated filename;
153 see VERSIONS.
154 .P
155 The data returned by
156 .BR readdir ()
157 may be overwritten by subsequent calls to
158 .BR readdir ()
159 for the same directory stream.
160 .SH RETURN VALUE
161 On success,
162 .BR readdir ()
163 returns a pointer to a
164 .I dirent
165 structure.
166 (This structure may be statically allocated;
167 do not attempt to
168 .BR free (3)
169 it.)
170 .P
171 If the end of the directory stream is reached, NULL is returned and
172 .I errno
173 is not changed.
174 If an error occurs, NULL is returned and
175 .I errno
176 is set to indicate the error.
177 To distinguish end of stream from an error, set
178 .I errno
179 to zero before calling
180 .BR readdir ()
181 and then check the value of
182 .I errno
183 if NULL is returned.
184 .SH ERRORS
185 .TP
186 .B EBADF
187 Invalid directory stream descriptor
188 .IR dirp .
189 .SH ATTRIBUTES
190 For an explanation of the terms used in this section, see
191 .BR attributes (7).
192 .TS
193 allbox;
194 lbx lb lb
195 l l l.
196 Interface Attribute Value
197 T{
198 .na
199 .nh
200 .BR readdir ()
201 T} Thread safety MT-Unsafe race:dirstream
202 .TE
203 .P
204 In the current POSIX.1 specification (POSIX.1-2008),
205 .BR readdir ()
206 is not required to be thread-safe.
207 However, in modern implementations (including the glibc implementation),
208 concurrent calls to
209 .BR readdir ()
210 that specify different directory streams are thread-safe.
211 In cases where multiple threads must read from the same directory stream,
212 using
213 .BR readdir ()
214 with external synchronization is still preferable to the use of the deprecated
215 .BR readdir_r (3)
216 function.
217 It is expected that a future version of POSIX.1
218 .\" FIXME .
219 .\" http://www.austingroupbugs.net/view.php?id=696
220 will require that
221 .BR readdir ()
222 be thread-safe when concurrently employed on different directory streams.
223 .SH VERSIONS
224 Only the fields
225 .I .d_name
226 and (as an XSI extension)
227 .I .d_ino
228 are specified in POSIX.1.
229 .\" POSIX.1-2001, POSIX.1-2008
230 Other than Linux, the
231 .I .d_type
232 field is available mainly only on BSD systems.
233 The remaining fields are available on many, but not all systems.
234 Under glibc,
235 programs can check for the availability of the fields not defined
236 in POSIX.1 by testing whether the macros
237 .BR _DIRENT_HAVE_D_NAMLEN ,
238 .BR _DIRENT_HAVE_D_RECLEN ,
239 .BR _DIRENT_HAVE_D_OFF ,
240 or
241 .B _DIRENT_HAVE_D_TYPE
242 are defined.
243 .\"
244 .SS The \f[I].d_name\f[] field
245 The
246 .I dirent
247 structure definition shown above is taken from the glibc headers,
248 and shows the
249 .I .d_name
250 field with a fixed size.
251 .P
252 .IR Warning :
253 applications should avoid any dependence on the size of the
254 .I .d_name
255 field.
256 POSIX defines it as
257 .IR "char\ d_name[]",
258 a character array of unspecified size, with at most
259 .B NAME_MAX
260 characters preceding the terminating null byte (\[aq]\[rs]0\[aq]).
261 .P
262 POSIX.1 explicitly notes that this field should not be used as an lvalue.
263 The standard also notes that the use of
264 .I sizeof(.d_name)
265 is incorrect;
266 use
267 .I strlen(.d_name)
268 instead.
269 (On some systems, this field is defined as
270 .IR char\~d_name[1] !)
271 By implication, the use
272 .I sizeof(struct dirent)
273 to capture the size of the record including the size of
274 .I .d_name
275 is also incorrect.
276 .P
277 Note that while the call
278 .P
279 .in +4n
280 .EX
281 fpathconf(fd, _PC_NAME_MAX)
282 .EE
283 .in
284 .P
285 returns the value 255 for most filesystems,
286 on some filesystems (e.g., CIFS, Windows SMB servers),
287 the null-terminated filename that is (correctly) returned in
288 .I .d_name
289 can actually exceed this size.
290 In such cases, the
291 .I .d_reclen
292 field will contain a value that exceeds the size of the glibc
293 .I dirent
294 structure shown above.
295 .SH STANDARDS
296 POSIX.1-2008.
297 .SH HISTORY
298 POSIX.1-2001, SVr4, 4.3BSD.
299 .SH NOTES
300 A directory stream is opened using
301 .BR opendir (3).
302 .P
303 The order in which filenames are read by successive calls to
304 .BR readdir ()
305 depends on the filesystem implementation;
306 it is unlikely that the names will be sorted in any fashion.
307 .SH SEE ALSO
308 .BR getdents (2),
309 .BR read (2),
310 .BR closedir (3),
311 .BR dirfd (3),
312 .BR ftw (3),
313 .BR offsetof (3),
314 .BR opendir (3),
315 .BR readdir_r (3),
316 .BR rewinddir (3),
317 .BR scandir (3),
318 .BR seekdir (3),
319 .BR telldir (3)