Debian Codegraph @

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