]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) |
0c52f6d6 | 2 | .\" and Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
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. | |
c13182ef | 13 | .\" |
fea681da MK |
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. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
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) | |
24b31b7b | 33 | .\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>, mtk: |
c8f2dd47 | 34 | .\" Rework discussion of nonstandard structure fields. |
fea681da | 35 | .\" |
9ba01802 | 36 | .TH READDIR 3 2019-03-06 "" "Linux Programmer's Manual" |
fea681da | 37 | .SH NAME |
96604453 | 38 | readdir \- read a directory |
fea681da MK |
39 | .SH SYNOPSIS |
40 | .nf | |
fea681da | 41 | .B #include <dirent.h> |
68e4db0a | 42 | .PP |
6dea120e | 43 | .BI "struct dirent *readdir(DIR *" dirp ); |
fea681da MK |
44 | .fi |
45 | .SH DESCRIPTION | |
60a90ecd MK |
46 | The |
47 | .BR readdir () | |
48 | function returns a pointer to a \fIdirent\fP structure | |
fea681da | 49 | representing the next directory entry in the directory stream pointed |
6dea120e | 50 | to by \fIdirp\fP. |
15dd4fb5 | 51 | It returns NULL on reaching the end of the directory stream or if |
fea681da MK |
52 | an error occurred. |
53 | .PP | |
6550b827 | 54 | In the glibc implementation, the |
a03d317b MK |
55 | .I dirent |
56 | structure is defined as follows: | |
57 | .PP | |
bd191423 | 58 | .in +4n |
b8302363 | 59 | .EX |
a03d317b | 60 | struct dirent { |
6550b827 MK |
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 | |
9ee4a2b6 | 65 | by all filesystem types */ |
6550b827 | 66 | char d_name[256]; /* Null-terminated filename */ |
a03d317b | 67 | }; |
b8302363 | 68 | .EE |
bd191423 | 69 | .in |
a03d317b | 70 | .PP |
4b3caf6f | 71 | The only fields in the |
fea681da | 72 | .I dirent |
6550b827 MK |
73 | structure that are mandated by POSIX.1 are |
74 | .IR d_name | |
75 | and | |
4b3caf6f | 76 | .IR d_ino . |
237dedac MK |
77 | The other fields are unstandardized, and not present on all systems; |
78 | see NOTES below for some further details. | |
847e0d88 | 79 | .PP |
6550b827 MK |
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. | |
307b34a8 MK |
103 | This may not match the size of the structure definition shown above; |
104 | see NOTES. | |
6550b827 MK |
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. | |
307b34a8 | 157 | .IR "See NOTES" . |
fea681da | 158 | .PP |
60a90ecd MK |
159 | The data returned by |
160 | .BR readdir () | |
237dedac | 161 | may be overwritten by subsequent calls to |
60a90ecd MK |
162 | .BR readdir () |
163 | for the same directory stream. | |
47297adb | 164 | .SH RETURN VALUE |
6a5dd8b3 | 165 | On success, |
60a90ecd | 166 | .BR readdir () |
6a5dd8b3 | 167 | returns a pointer to a |
c13182ef | 168 | .I dirent |
6a5dd8b3 | 169 | structure. |
90eeb47a MK |
170 | (This structure may be statically allocated; do not attempt to |
171 | .BR free (3) | |
172 | it.) | |
847e0d88 | 173 | .PP |
6a5dd8b3 MK |
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 | |
cca657e2 MK |
178 | .I errno |
179 | is set appropriately. | |
df7a8fc9 MK |
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. | |
fea681da MK |
187 | .SH ERRORS |
188 | .TP | |
189 | .B EBADF | |
6dea120e | 190 | Invalid directory stream descriptor \fIdirp\fP. |
83417e69 | 191 | .SH ATTRIBUTES |
fa7acb92 PH |
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{ | |
83417e69 | 200 | .BR readdir () |
00650a14 | 201 | T} Thread safety MT-Unsafe race:dirstream |
fa7acb92 | 202 | .TE |
847e0d88 | 203 | .sp 1 |
96604453 MK |
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. | |
47297adb | 224 | .SH CONFORMING TO |
cd693fc7 | 225 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
624c55e8 | 226 | .SH NOTES |
6550b827 MK |
227 | A directory stream is opened using |
228 | .BR opendir (3). | |
847e0d88 | 229 | .PP |
6550b827 MK |
230 | The order in which filenames are read by successive calls to |
231 | .BR readdir () | |
232 | depends on the filesystem implementation; | |
58b9f0eb | 233 | it is unlikely that the names will be sorted in any fashion. |
847e0d88 | 234 | .PP |
237dedac MK |
235 | Only the fields |
236 | .I d_name | |
6550b827 | 237 | and (as an XSI extension) |
237dedac | 238 | .I d_ino |
cd693fc7 MK |
239 | are specified in POSIX.1. |
240 | .\" POSIX.1-2001, POSIX.1-2008 | |
6550b827 MK |
241 | Other than Linux, the |
242 | .I d_type | |
243 | field is available mainly only on BSD systems. | |
237dedac MK |
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 | |
bf1c0ede | 247 | in POSIX.1 by testing whether the macros |
237dedac MK |
248 | .BR _DIRENT_HAVE_D_NAMLEN , |
249 | .BR _DIRENT_HAVE_D_RECLEN , | |
250 | .BR _DIRENT_HAVE_D_OFF , | |
251 | or | |
0daa9e92 | 252 | .B _DIRENT_HAVE_D_TYPE |
237dedac | 253 | are defined. |
307b34a8 MK |
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. | |
847e0d88 | 262 | .PP |
307b34a8 MK |
263 | .IR Warning : |
264 | applications should avoid any dependence on the size of the | |
8a61b8f5 | 265 | .I d_name |
307b34a8 MK |
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 | |
d1a71985 | 271 | characters preceding the terminating null byte (\(aq\e0\(aq). |
847e0d88 | 272 | .PP |
307b34a8 MK |
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) | |
307b34a8 MK |
276 | is incorrect; use |
277 | .IR strlen(d_name) | |
278 | instead. | |
2c767761 | 279 | (On some systems, this field is defined as |
307b34a8 | 280 | .IR char\ d_name[1] !) |
0fdfbd14 MK |
281 | By implication, the use |
282 | .IR "sizeof(struct dirent)" | |
a90f441a | 283 | to capture the size of the record including the size of |
0fdfbd14 MK |
284 | .IR d_name |
285 | is also incorrect. | |
847e0d88 | 286 | .PP |
307b34a8 | 287 | Note that while the call |
847e0d88 | 288 | .PP |
307b34a8 | 289 | fpathconf(fd, _PC_NAME_MAX) |
847e0d88 | 290 | .PP |
307b34a8 MK |
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. | |
0fdfbd14 | 296 | In such cases, the |
307b34a8 MK |
297 | .I d_reclen |
298 | field will contain a value that exceeds the size of the glibc | |
299 | .I dirent | |
0fdfbd14 | 300 | structure shown above. |
47297adb | 301 | .SH SEE ALSO |
6a0f91cc | 302 | .BR getdents (2), |
fea681da MK |
303 | .BR read (2), |
304 | .BR closedir (3), | |
305 | .BR dirfd (3), | |
53eef14c | 306 | .BR ftw (3), |
15dd4fb5 | 307 | .BR offsetof (3), |
fea681da | 308 | .BR opendir (3), |
96604453 | 309 | .BR readdir_r (3), |
fea681da MK |
310 | .BR rewinddir (3), |
311 | .BR scandir (3), | |
312 | .BR seekdir (3), | |
0a4f8b7b | 313 | .BR telldir (3) |