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