Debian Codegraph @

upstream/debian-trixie/man2/getdents.2

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