]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" References consulted: | |
26 | .\" Linux libc source code | |
27 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
28 | .\" 386BSD man pages | |
29 | .\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu) | |
30 | .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) | |
31 | .\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl) | |
24b31b7b | 32 | .\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>, mtk: |
c8f2dd47 | 33 | .\" Rework discussion of nonstandard structure fields. |
30da9614 | 34 | .\" 2008-09-11, mtk, Document readdir_r(). |
fea681da | 35 | .\" |
460495ca | 36 | .TH READDIR 3 2015-08-08 "" "Linux Programmer's Manual" |
fea681da | 37 | .SH NAME |
15dd4fb5 | 38 | readdir, readdir_r \- read a directory |
fea681da MK |
39 | .SH SYNOPSIS |
40 | .nf | |
fea681da MK |
41 | .B #include <dirent.h> |
42 | .sp | |
6dea120e | 43 | .BI "struct dirent *readdir(DIR *" dirp ); |
15dd4fb5 | 44 | .sp |
6dea120e | 45 | .BI "int readdir_r(DIR *" dirp ", struct dirent *" entry \ |
15dd4fb5 | 46 | ", struct dirent **" result ); |
fea681da | 47 | .fi |
0f200f07 MK |
48 | .sp |
49 | .in -4n | |
50 | Feature Test Macro Requirements for glibc (see | |
51 | .BR feature_test_macros (7)): | |
52 | .ad l | |
53 | .in | |
54 | .sp | |
55 | .BR readdir_r (): | |
503be136 | 56 | .RS 4 |
0f200f07 MK |
57 | _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE || |
58 | _SVID_SOURCE || _POSIX_SOURCE | |
503be136 | 59 | .RE |
0f200f07 | 60 | .ad b |
fea681da | 61 | .SH DESCRIPTION |
60a90ecd MK |
62 | The |
63 | .BR readdir () | |
64 | function returns a pointer to a \fIdirent\fP structure | |
fea681da | 65 | representing the next directory entry in the directory stream pointed |
6dea120e | 66 | to by \fIdirp\fP. |
15dd4fb5 | 67 | It returns NULL on reaching the end of the directory stream or if |
fea681da MK |
68 | an error occurred. |
69 | .PP | |
a03d317b MK |
70 | On Linux, the |
71 | .I dirent | |
72 | structure is defined as follows: | |
73 | .PP | |
bd191423 | 74 | .in +4n |
a03d317b MK |
75 | .nf |
76 | struct dirent { | |
77 | ino_t d_ino; /* inode number */ | |
73f4bf1e | 78 | off_t d_off; /* not an offset; see NOTES */ |
a03d317b | 79 | unsigned short d_reclen; /* length of this record */ |
efb92ba1 | 80 | unsigned char d_type; /* type of file; not supported |
9ee4a2b6 | 81 | by all filesystem types */ |
a03d317b MK |
82 | char d_name[256]; /* filename */ |
83 | }; | |
84 | .fi | |
bd191423 | 85 | .in |
a03d317b | 86 | .PP |
4b3caf6f | 87 | The only fields in the |
fea681da | 88 | .I dirent |
4b3caf6f MK |
89 | structure that are mandated by POSIX.1 are: |
90 | .IR d_name [], | |
fea681da MK |
91 | of unspecified size, with at most |
92 | .B NAME_MAX | |
f24e3a3a | 93 | characters preceding the terminating null byte (\(aq\\0\(aq); |
4b3caf6f MK |
94 | and (as an XSI extension) |
95 | .IR d_ino . | |
237dedac MK |
96 | The other fields are unstandardized, and not present on all systems; |
97 | see NOTES below for some further details. | |
fea681da | 98 | .PP |
60a90ecd MK |
99 | The data returned by |
100 | .BR readdir () | |
237dedac | 101 | may be overwritten by subsequent calls to |
60a90ecd MK |
102 | .BR readdir () |
103 | for the same directory stream. | |
15dd4fb5 MK |
104 | |
105 | The | |
106 | .BR readdir_r () | |
107 | function is a reentrant version of | |
108 | .BR readdir (). | |
109 | It reads the next directory entry from the directory stream | |
6dea120e | 110 | .IR dirp , |
15dd4fb5 MK |
111 | and returns it in the caller-allocated buffer pointed to by |
112 | .IR entry . | |
113 | (See NOTES for information on allocating this buffer.) | |
114 | A pointer to the returned item is placed in | |
115 | .IR *result ; | |
116 | if the end of the directory stream was encountered, | |
117 | then NULL is instead returned in | |
118 | .IR *result . | |
47297adb | 119 | .SH RETURN VALUE |
6a5dd8b3 | 120 | On success, |
60a90ecd | 121 | .BR readdir () |
6a5dd8b3 | 122 | returns a pointer to a |
c13182ef | 123 | .I dirent |
6a5dd8b3 | 124 | structure. |
90eeb47a MK |
125 | (This structure may be statically allocated; do not attempt to |
126 | .BR free (3) | |
127 | it.) | |
6a5dd8b3 MK |
128 | If the end of the directory stream is reached, NULL is returned and |
129 | .I errno | |
130 | is not changed. | |
131 | If an error occurs, NULL is returned and | |
cca657e2 MK |
132 | .I errno |
133 | is set appropriately. | |
15dd4fb5 MK |
134 | |
135 | The | |
136 | .BR readdir_r () | |
137 | function returns 0 on success. | |
636036b6 | 138 | On error, it returns a positive error number (listed under ERRORS). |
15dd4fb5 MK |
139 | If the end of the directory stream is reached, |
140 | .BR readdir_r () | |
141 | returns 0, and returns NULL in | |
142 | .IR *result . | |
fea681da MK |
143 | .SH ERRORS |
144 | .TP | |
145 | .B EBADF | |
6dea120e | 146 | Invalid directory stream descriptor \fIdirp\fP. |
83417e69 | 147 | .SH ATTRIBUTES |
fa7acb92 PH |
148 | For an explanation of the terms used in this section, see |
149 | .BR attributes (7). | |
150 | .TS | |
151 | allbox; | |
152 | lb lb lb | |
153 | l l l. | |
154 | Interface Attribute Value | |
155 | T{ | |
83417e69 | 156 | .BR readdir () |
00650a14 | 157 | T} Thread safety MT-Unsafe race:dirstream |
fa7acb92 | 158 | T{ |
83417e69 | 159 | .BR readdir_r () |
fa7acb92 PH |
160 | T} Thread safety MT-Safe |
161 | .TE | |
47297adb | 162 | .SH CONFORMING TO |
cd693fc7 | 163 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
624c55e8 | 164 | .SH NOTES |
237dedac MK |
165 | Only the fields |
166 | .I d_name | |
167 | and | |
168 | .I d_ino | |
cd693fc7 MK |
169 | are specified in POSIX.1. |
170 | .\" POSIX.1-2001, POSIX.1-2008 | |
237dedac MK |
171 | The remaining fields are available on many, but not all systems. |
172 | Under glibc, | |
173 | programs can check for the availability of the fields not defined | |
bf1c0ede | 174 | in POSIX.1 by testing whether the macros |
237dedac MK |
175 | .BR _DIRENT_HAVE_D_NAMLEN , |
176 | .BR _DIRENT_HAVE_D_RECLEN , | |
177 | .BR _DIRENT_HAVE_D_OFF , | |
178 | or | |
0daa9e92 | 179 | .B _DIRENT_HAVE_D_TYPE |
237dedac MK |
180 | are defined. |
181 | ||
73f4bf1e MK |
182 | The value returned in |
183 | .I d_off | |
184 | is the same as would be returned by calling | |
185 | .BR telldir (3) | |
186 | at the current position in the directory stream. | |
187 | Be aware that despite its type and name, the | |
188 | .I d_off | |
9ee4a2b6 | 189 | field is seldom any kind of directory offset on modern filesystems. |
73f4bf1e MK |
190 | .\" https://lwn.net/Articles/544298/ |
191 | Applications should treat this field as an opaque value, | |
192 | making no assumptions about its contents; see also | |
193 | .BR telldir (3). | |
194 | ||
237dedac MK |
195 | Other than Linux, the |
196 | .I d_type | |
197 | field is available mainly only on BSD systems. | |
0dd0df4e | 198 | This field makes it possible to avoid the expense of calling |
19eee0a6 MK |
199 | .BR lstat (2) |
200 | if further actions depend on the type of the file. | |
624c55e8 MK |
201 | If the |
202 | .B _BSD_SOURCE | |
203 | feature test macro is defined, | |
204 | then glibc defines the following macro constants | |
205 | for the value returned in | |
237dedac | 206 | .IR d_type : |
624c55e8 | 207 | .TP 12 |
7bcd4333 MK |
208 | .B DT_BLK |
209 | This is a block device. | |
624c55e8 | 210 | .TP |
7bcd4333 MK |
211 | .B DT_CHR |
212 | This is a character device. | |
58f362c3 | 213 | .TP |
624c55e8 MK |
214 | .B DT_DIR |
215 | This is a directory. | |
216 | .TP | |
217 | .B DT_FIFO | |
7bcd4333 MK |
218 | This is a named pipe (FIFO). |
219 | .TP | |
220 | .B DT_LNK | |
221 | This is a symbolic link. | |
222 | .TP | |
223 | .B DT_REG | |
224 | This is a regular file. | |
624c55e8 MK |
225 | .TP |
226 | .B DT_SOCK | |
008f1ecc | 227 | This is a UNIX domain socket. |
624c55e8 | 228 | .TP |
7bcd4333 MK |
229 | .B DT_UNKNOWN |
230 | The file type is unknown. | |
231 | .\" The glibc manual says that on some systems this is the only | |
232 | .\" value returned | |
237dedac MK |
233 | .PP |
234 | If the file type could not be determined, the value | |
0daa9e92 | 235 | .B DT_UNKNOWN |
237dedac MK |
236 | is returned in |
237 | .IR d_type . | |
15dd4fb5 | 238 | |
2250b3ee | 239 | Currently, |
efb92ba1 | 240 | .\" kernel 2.6.27 |
2250b3ee | 241 | .\" The same sentence is in getdents.2 |
9ee4a2b6 | 242 | only some filesystems (among them: Btrfs, ext2, ext3, and ext4) |
037f4132 | 243 | have full support for returning the file type in |
efb92ba1 | 244 | .IR d_type . |
2250b3ee | 245 | All applications must properly handle a return of |
efb92ba1 MK |
246 | .BR DT_UNKNOWN . |
247 | ||
15dd4fb5 MK |
248 | Since POSIX.1 does not specify the size of the |
249 | .I d_name | |
c8f2dd47 | 250 | field, and other nonstandard fields may precede that field within the |
15dd4fb5 MK |
251 | .I dirent |
252 | structure, portable applications that use | |
253 | .BR readdir_r () | |
254 | should allocate the buffer whose address is passed in | |
255 | .IR entry | |
256 | as follows: | |
257 | .in +4n | |
258 | .nf | |
259 | ||
eb059156 | 260 | name_max = pathconf(dirpath, _PC_NAME_MAX); |
62389489 | 261 | if (name_max == \-1) /* Limit not defined, or error */ |
eb059156 MK |
262 | name_max = 255; /* Take a guess */ |
263 | len = offsetof(struct dirent, d_name) + name_max + 1; | |
15dd4fb5 MK |
264 | entryp = malloc(len); |
265 | ||
266 | .fi | |
267 | .in | |
268 | (POSIX.1 requires that | |
269 | .I d_name | |
270 | is the last field in a | |
271 | .IR "struct dirent" .) | |
47297adb | 272 | .SH SEE ALSO |
6a0f91cc | 273 | .BR getdents (2), |
fea681da MK |
274 | .BR read (2), |
275 | .BR closedir (3), | |
276 | .BR dirfd (3), | |
53eef14c | 277 | .BR ftw (3), |
15dd4fb5 | 278 | .BR offsetof (3), |
fea681da MK |
279 | .BR opendir (3), |
280 | .BR rewinddir (3), | |
281 | .BR scandir (3), | |
282 | .BR seekdir (3), | |
0a4f8b7b | 283 | .BR telldir (3) |