Debian Codegraph @

upstream/debian-trixie/man3/readdir.3

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