1getdents(2)                   System Calls Manual                  getdents(2)
2
3
4

NAME

6       getdents, getdents64 - get directory entries
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/syscall.h>      /* Definition of SYS_* constants */
13       #include <unistd.h>
14
15       long syscall(SYS_getdents, unsigned int fd, struct linux_dirent *dirp,
16                    unsigned int count);
17
18       #define _GNU_SOURCE           /* See feature_test_macros(7) */
19       #include <dirent.h>
20
21       ssize_t getdents64(int fd, void dirp[.count], size_t count);
22
23       Note:  glibc  provides no wrapper for getdents(), necessitating the use
24       of syscall(2).
25
26       Note: There is no definition  of  struct  linux_dirent  in  glibc;  see
27       NOTES.
28

DESCRIPTION

30       These are not the interfaces you are interested in.  Look at readdir(3)
31       for the POSIX-conforming C library interface.  This page documents  the
32       bare kernel system call interfaces.
33
34   getdents()
35       The  system  call getdents() reads several linux_dirent structures from
36       the directory referred to by the open file descriptor fd into the  buf‐
37       fer  pointed to by dirp.  The argument count specifies the size of that
38       buffer.
39
40       The linux_dirent structure is declared as follows:
41
42           struct linux_dirent {
43               unsigned long  d_ino;     /* Inode number */
44               unsigned long  d_off;     /* Offset to next linux_dirent */
45               unsigned short d_reclen;  /* Length of this linux_dirent */
46               char           d_name[];  /* Filename (null-terminated) */
47                                 /* length is actually (d_reclen - 2 -
48                                    offsetof(struct linux_dirent, d_name)) */
49               /*
50               char           pad;       // Zero padding byte
51               char           d_type;    // File type (only since Linux
52                                         // 2.6.4); offset is (d_reclen - 1)
53               */
54           }
55
56       d_ino is an inode number.  d_off is the distance from the start of  the
57       directory  to the start of the next linux_dirent.  d_reclen is the size
58       of this entire linux_dirent.  d_name is a null-terminated filename.
59
60       d_type is a byte at the end of the structure that  indicates  the  file
61       type.  It contains one of the following values (defined in <dirent.h>):
62
63       DT_BLK      This is a block device.
64
65       DT_CHR      This is a character device.
66
67       DT_DIR      This is a directory.
68
69       DT_FIFO     This is a named pipe (FIFO).
70
71       DT_LNK      This is a symbolic link.
72
73       DT_REG      This is a regular file.
74
75       DT_SOCK     This is a UNIX domain socket.
76
77       DT_UNKNOWN  The file type is unknown.
78
79       The d_type field is implemented since Linux 2.6.4.  It occupies a space
80       that was previously a zero-filled  padding  byte  in  the  linux_dirent
81       structure.   Thus, on kernels up to and including Linux 2.6.3, attempt‐
82       ing to access this field always provides the value 0 (DT_UNKNOWN).
83
84       Currently, only some filesystems (among them: Btrfs,  ext2,  ext3,  and
85       ext4) have full support for returning the file type in d_type.  All ap‐
86       plications must properly handle a return of DT_UNKNOWN.
87
88   getdents64()
89       The original Linux getdents() system call did not handle large filesys‐
90       tems  and  large  file  offsets.   Consequently,  Linux  2.4 added get‐
91       dents64(), with wider types for the d_ino and d_off fields.   In  addi‐
92       tion, getdents64() supports an explicit d_type field.
93
94       The getdents64() system call is like getdents(), except that its second
95       argument is a pointer to a buffer containing structures of the  follow‐
96       ing type:
97
98           struct linux_dirent64 {
99               ino64_t        d_ino;    /* 64-bit inode number */
100               off64_t        d_off;    /* 64-bit offset to next structure */
101               unsigned short d_reclen; /* Size of this dirent */
102               unsigned char  d_type;   /* File type */
103               char           d_name[]; /* Filename (null-terminated) */
104           };
105

RETURN VALUE

107       On success, the number of bytes read is returned.  On end of directory,
108       0 is returned.  On error, -1 is returned, and errno is set to  indicate
109       the error.
110

ERRORS

112       EBADF  Invalid file descriptor fd.
113
114       EFAULT Argument points outside the calling process's address space.
115
116       EINVAL Result buffer is too small.
117
118       ENOENT No such directory.
119
120       ENOTDIR
121              File descriptor does not refer to a directory.
122

STANDARDS

124       None.
125

HISTORY

127       SVr4.
128
129       getdents64()
130              glibc 2.30.
131

NOTES

133       glibc  does not provide a wrapper for getdents(); call getdents() using
134       syscall(2).  In that case you will need to define the  linux_dirent  or
135       linux_dirent64 structure yourself.
136
137       Probably, you want to use readdir(3) instead of these system calls.
138
139       These calls supersede readdir(2).
140

EXAMPLES

142       The  program  below  demonstrates the use of getdents().  The following
143       output shows an example of what we see when running this program on  an
144       ext2 directory:
145
146           $ ./a.out /testfs/
147           --------------- nread=120 ---------------
148           inode#    file type  d_reclen  d_off   d_name
149                  2  directory    16         12  .
150                  2  directory    16         24  ..
151                 11  directory    24         44  lost+found
152                 12  regular      16         56  a
153             228929  directory    16         68  sub
154              16353  directory    16         80  sub2
155             130817  directory    16       4096  sub3
156
157   Program source
158
159       #define _GNU_SOURCE
160       #include <dirent.h>     /* Defines DT_* constants */
161       #include <err.h>
162       #include <fcntl.h>
163       #include <stdint.h>
164       #include <stdio.h>
165       #include <stdlib.h>
166       #include <sys/syscall.h>
167       #include <unistd.h>
168
169       struct linux_dirent {
170           unsigned long  d_ino;
171           off_t          d_off;
172           unsigned short d_reclen;
173           char           d_name[];
174       };
175
176       #define BUF_SIZE 1024
177
178       int
179       main(int argc, char *argv[])
180       {
181           int                  fd;
182           char                 d_type;
183           char                 buf[BUF_SIZE];
184           long                 nread;
185           struct linux_dirent  *d;
186
187           fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY);
188           if (fd == -1)
189               err(EXIT_FAILURE, "open");
190
191           for (;;) {
192               nread = syscall(SYS_getdents, fd, buf, BUF_SIZE);
193               if (nread == -1)
194                   err(EXIT_FAILURE, "getdents");
195
196               if (nread == 0)
197                   break;
198
199               printf("--------------- nread=%ld ---------------\n", nread);
200               printf("inode#    file type  d_reclen  d_off   d_name\n");
201               for (size_t bpos = 0; bpos < nread;) {
202                   d = (struct linux_dirent *) (buf + bpos);
203                   printf("%8lu  ", d->d_ino);
204                   d_type = *(buf + bpos + d->d_reclen - 1);
205                   printf("%-10s ", (d_type == DT_REG) ?  "regular" :
206                                    (d_type == DT_DIR) ?  "directory" :
207                                    (d_type == DT_FIFO) ? "FIFO" :
208                                    (d_type == DT_SOCK) ? "socket" :
209                                    (d_type == DT_LNK) ?  "symlink" :
210                                    (d_type == DT_BLK) ?  "block dev" :
211                                    (d_type == DT_CHR) ?  "char dev" : "???");
212                   printf("%4d %10jd  %s\n", d->d_reclen,
213                          (intmax_t) d->d_off, d->d_name);
214                   bpos += d->d_reclen;
215               }
216           }
217
218           exit(EXIT_SUCCESS);
219       }
220

SEE ALSO

222       readdir(2), readdir(3), inode(7)
223
224
225
226Linux man-pages 6.05              2023-05-03                       getdents(2)
Impressum