Debian Codegraph @

upstream/debian-unstable/man2/getdents.2

raw
1 .\" Copyright 1995, Andries E. Brouwer <[email protected]>
2 .\" Copyright 2008-2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH getdents 2 2026-04-08 "Linux man-pages 6.18"
8 .SH NAME
9 getdents, getdents64 \- get directory entries
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
16 .B #include <unistd.h>
17 .P
18 .BI "long syscall(SYS_getdents, unsigned int " fd \
19 ", struct linux_dirent *" dirp ,
20 .BI " unsigned int " count );
21 .P
22 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
23 .B #include <dirent.h>
24 .P
25 .BR "ssize_t getdents64(" "size_t count;"
26 .BI " int " fd ", void " dirp [ count "], size_t " count );
27 .fi
28 .P
29 .IR Note :
30 glibc provides no wrapper for
31 .BR getdents (),
32 necessitating the use of
33 .BR syscall (2).
34 .P
35 .IR Note :
36 There is no definition of
37 .I struct linux_dirent
38 in glibc;
39 see NOTES.
40 .SH DESCRIPTION
41 These are not the interfaces you are interested in.
42 Look at
43 .BR readdir (3)
44 for the POSIX-conforming C library interface.
45 .SS getdents()
46 The system call
47 .BR getdents ()
48 reads several
49 .I linux_dirent
50 structures from the directory
51 referred to by the open file descriptor
52 .I fd
53 into the buffer pointed to by
54 .IR dirp .
55 The argument
56 .I count
57 specifies the size of that buffer.
58 .P
59 The
60 .I linux_dirent
61 structure is declared as follows:
62 .P
63 .in +4n
64 .EX
65 struct linux_dirent {
66 unsigned long d_ino; /* Inode number */
67 unsigned long d_off; /* Not an offset; see below */
68 unsigned short d_reclen; /* Length of this \f[I]linux_dirent\f[] */
69 char d_name[]; /* Filename (null\-terminated) */
70 /* length is actually (d_reclen \- 2 \-
71 offsetof(struct linux_dirent, d_name)) */
72 /*
73 char pad; // Zero padding byte
74 char d_type; // File type (only since Linux
75 // 2.6.4); offset is (d_reclen \- 1)
76 */
77 }
78 .EE
79 .in
80 .P
81 .I d_ino
82 is an inode number.
83 .I d_off
84 is a filesystem-specific value with no specific meaning to user space,
85 though on older filesystems it used to be
86 the distance from the start of the directory to the start of the next
87 .IR linux_dirent ;
88 see
89 .BR readdir (3).
90 .I d_reclen
91 is the size of this entire
92 .IR linux_dirent .
93 .I d_name
94 is a null-terminated filename.
95 .P
96 .I d_type
97 is a byte at the end of the structure that indicates the file type.
98 It contains one of the following values (defined in
99 .IR <dirent.h> ):
100 .TP 12
101 .B DT_BLK
102 This is a block device.
103 .TP
104 .B DT_CHR
105 This is a character device.
106 .TP
107 .B DT_DIR
108 This is a directory.
109 .TP
110 .B DT_FIFO
111 This is a named pipe (FIFO).
112 .TP
113 .B DT_LNK
114 This is a symbolic link.
115 .TP
116 .B DT_REG
117 This is a regular file.
118 .TP
119 .B DT_SOCK
120 This is a UNIX domain socket.
121 .TP
122 .B DT_UNKNOWN
123 The file type is unknown.
124 .P
125 The
126 .I d_type
127 field is implemented since Linux 2.6.4.
128 It occupies a space that was previously a zero-filled padding byte in the
129 .I linux_dirent
130 structure.
131 Thus, on kernels up to and including Linux 2.6.3,
132 attempting to access this field always provides the value 0
133 .RB ( DT_UNKNOWN ).
134 .P
135 Currently,
136 .\" kernel 2.6.27
137 .\" The same sentence is in readdir.2
138 only some filesystems (among them: Btrfs, ext2, ext3, and ext4)
139 have full support for returning the file type in
140 .IR d_type .
141 All applications must properly handle a return of
142 .BR DT_UNKNOWN .
143 .SS getdents64()
144 The original Linux
145 .BR getdents ()
146 system call did not handle large filesystems and large file offsets.
147 Consequently, Linux 2.4 added
148 .BR getdents64 (),
149 with wider types for the
150 .I d_ino
151 and
152 .I d_off
153 fields.
154 In addition,
155 .BR getdents64 ()
156 supports an explicit
157 .I d_type
158 field.
159 .P
160 The
161 .BR getdents64 ()
162 system call is like
163 .BR getdents (),
164 except that its second argument is a pointer to a buffer containing
165 structures of the following type:
166 .P
167 .in +4n
168 .EX
169 struct linux_dirent64 {
170 ino64_t d_ino; /* 64\-bit inode number */
171 off64_t d_off; /* Not an offset; see getdents() */
172 unsigned short d_reclen; /* Size of this dirent */
173 unsigned char d_type; /* File type */
174 char d_name[]; /* Filename (null\-terminated) */
175 };
176 .EE
177 .in
178 .SH RETURN VALUE
179 On success, the number of bytes read is returned.
180 On end of directory, 0 is returned.
181 On error, \-1 is returned, and
182 .I errno
183 is set to indicate the error.
184 .SH ERRORS
185 .TP
186 .B EBADF
187 Invalid file descriptor
188 .IR fd .
189 .TP
190 .B EFAULT
191 Argument points outside the calling process's address space.
192 .TP
193 .B EINVAL
194 Result buffer is too small.
195 .TP
196 .B ENOENT
197 No such directory.
198 .TP
199 .B ENOTDIR
200 File descriptor does not refer to a directory.
201 .SH STANDARDS
202 None.
203 .SH HISTORY
204 .TP
205 .BR getdents ()
206 SVr4.
207 .\" SVr4 documents additional ENOLINK, EIO error conditions.
208 .TP
209 .BR getdents64 ()
210 glibc 2.30.
211 .SH NOTES
212 glibc does not provide a wrapper for
213 .BR getdents ();
214 call
215 .BR getdents ()
216 using
217 .BR syscall (2).
218 In that case you will need to define the
219 .I linux_dirent
220 structure yourself.
221 .P
222 The
223 .BR getdents64 ()
224 system call accepts an
225 .B unsigned int
226 argument
227 .I count
228 and assumes that
229 .I count
230 does not exceed
231 .BR INT_MAX .
232 The glibc wrapper function sets
233 .I count
234 to
235 .B INT_MAX
236 if it exceeds
237 .BR INT_MAX .
238 glibc defines a
239 .I dirent64
240 structure, which is similar to
241 .I linux_dirent64
242 but with a 256-byte
243 .IR d_name .
244 .P
245 Probably, you want to use
246 .BR readdir (3)
247 instead of these system calls.
248 .P
249 These calls supersede
250 .BR readdir (2).
251 .SH EXAMPLES
252 .\" FIXME The example program needs to be revised, since it uses the older
253 .\" getdents() system call and the structure with smaller field widths.
254 The program below demonstrates the use of
255 .BR getdents ().
256 The following output shows an example of what we see when running this
257 program on an ext2 directory:
258 .P
259 .in +4n
260 .EX
261 .RB "$" " ./a.out /testfs/"
262 -\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=120 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
263 inode# file type d_reclen d_off d_name
264 2 directory 16 12 .
265 2 directory 16 24 ..
266 11 directory 24 44 lost+found
267 12 regular 16 56 a
268 228929 directory 16 68 sub
269 16353 directory 16 80 sub2
270 130817 directory 16 4096 sub3
271 .EE
272 .in
273 .SS Program source
274 \&
275 .\" SRC BEGIN (getdents.c)
276 .EX
277 #define _GNU_SOURCE
278 #include <dirent.h> /* Defines DT_* constants */
279 #include <err.h>
280 #include <fcntl.h>
281 #include <stdint.h>
282 #include <stdio.h>
283 #include <stdlib.h>
284 #include <sys/syscall.h>
285 #include <sys/types.h>
286 #include <unistd.h>
287 \&
288 struct linux_dirent {
289 unsigned long d_ino;
290 off_t d_off;
291 unsigned short d_reclen;
292 char d_name[];
293 };
294 \&
295 #define BUF_SIZE 1024
296 \&
297 int
298 main(int argc, char *argv[])
299 {
300 int fd;
301 char d_type;
302 char buf[BUF_SIZE];
303 long nread;
304 struct linux_dirent *d;
305 \&
306 fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY);
307 if (fd == \-1)
308 err(EXIT_FAILURE, "open");
309 \&
310 for (;;) {
311 nread = syscall(SYS_getdents, fd, buf, BUF_SIZE);
312 if (nread == \-1)
313 err(EXIT_FAILURE, "getdents");
314 \&
315 if (nread == 0)
316 break;
317 \&
318 printf("\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=%ld \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\[rs]n", nread);
319 printf("inode# file type d_reclen d_off d_name\[rs]n");
320 for (size_t bpos = 0; bpos < nread;) {
321 d = (struct linux_dirent *) (buf + bpos);
322 printf("%8lu ", d\->d_ino);
323 d_type = *(buf + bpos + d\->d_reclen \- 1);
324 printf("%\-10s ", (d_type == DT_REG) ? "regular" :
325 (d_type == DT_DIR) ? "directory" :
326 (d_type == DT_FIFO) ? "FIFO" :
327 (d_type == DT_SOCK) ? "socket" :
328 (d_type == DT_LNK) ? "symlink" :
329 (d_type == DT_BLK) ? "block dev" :
330 (d_type == DT_CHR) ? "char dev" : "???");
331 printf("%4d %10jd %s\[rs]n", d\->d_reclen,
332 (intmax_t) d\->d_off, d\->d_name);
333 bpos += d\->d_reclen;
334 }
335 }
336 \&
337 exit(EXIT_SUCCESS);
338 }
339 .EE
340 .\" SRC END
341 .SH SEE ALSO
342 .BR readdir (2),
343 .BR readdir (3),
344 .BR inode (7)