NAME
getdents - get directory entries SYNOPSIS int getdents(unsigned int fd, struct linuxdirent *dirp, unsigned int count); Note: There is no glibc wrapper for this system call; see NOTES. DESCRIPTION This is not the function you are interested in. Look at readdir(3) for the POSIX conforming C library interface. This page documents the bare kernel system call interface. The system call getdents() reads several linuxdirent structures from the directory referred to by the open file descriptor fd into the buf‐ fer pointed to by dirp. The argument count specifies the size of that buffer. The linuxdirent structure is declared as follows: struct linuxdirent { unsigned long dino; /* Inode number */ unsigned long doff; /* Offset to next linuxdirent */ unsigned short dreclen; /* Length of this linuxdirent */
char dname[]; /* Filename (null-terminated) */
/* length is actually (dreclen - 2 - offsetof(struct linuxdirent, dname)) */ /* char pad; // Zero padding byte char dtype; // File type (only since Linux
// 2.6.4); offset is (dreclen - 1) */ } dino is an inode number. doff is the distance from the start of the directory to the start of the next linuxdirent. dreclen is the size
of this entire linuxdirent. dname is a null-terminated filename. dtype is a byte at the end of the structure that indicates the file type. It contains one of the following values (defined in
): DTBLK This is a block device. DTCHR This is a character device. DTDIR This is a directory. DTFIFO This is a named pipe (FIFO). DTLNK This is a symbolic link. DTREG This is a regular file. DTSOCK This is a UNIX domain socket. DTUNKNOWN The file type is unknown. The dtype field is implemented since Linux 2.6.4. It occupies a space that was previously a zero-filled padding byte in the linuxdirent structure. Thus, on kernels before 2.6.3, attempting to access this field always provides the value 0 (DTUNKNOWN). Currently, only some file systems (among them: Btrfs, ext2, ext3, and ext4) have full support for returning the file type in dtype. All applications must properly handle a return of DTUNKNOWN. RETURN VALUE On success, the number of bytes read is returned. On end of directory,
0 is returned. On error, -1 is returned, and errno is set appropri‐ ately. ERRORS EBADF Invalid file descriptor fd. EFAULT Argument points outside the calling process's address space. EINVAL Result buffer is too small. ENOENT No such directory. ENOTDIR File descriptor does not refer to a directory. CONFORMING TO SVr4. NOTES Glibc does not provide a wrapper for this system call; call it using syscall(2). You will need to define the linuxdirent structure your‐ self. However, you probably want to use readdir(3) instead. This call supersedes readdir(2). The original Linux getdents() system call did not handle large file systems and large file offsets. Consequently, Linux 2.4 added get‐ dents64(), with wider types for the dino and doff fields employed in the linuxdirent structure. EXAMPLE The program below demonstrates the use of getdents(). The following output shows an example of what we see when running this program on an ext2 directory:
$ ./a.out /testfs/
- nread=120 -
i-node# file type dreclen doff dname 2 directory 16 12 . 2 directory 16 24 .. 11 directory 24 44 lost+found 12 regular 16 56 a 228929 directory 16 68 sub 16353 directory 16 80 sub2 130817 directory 16 4096 sub3 Program source
#define GNUSOURCE
#include
/* Defines DT* constants */ #include
#include
#include
#include
#include
#include
#define handleerror(msg) \ do { perror(msg); exit(EXITFAILURE); } while (0) struct linuxdirent { long dino; offt doff; unsigned short dreclen; char dname[]; };
#define BUFSIZE 1024 int main(int argc, char *argv[]) { int fd, nread; char buf[BUFSIZE]; struct linuxdirent *d; int bpos; char dtype; fd = open(argc > 1 ? argv[1] : ".", ORDONLY | ODIRECTORY);
if (fd == -1) handleerror("open"); for ( ; ; ) { nread = syscall(SYSgetdents, fd, buf, BUFSIZE);
if (nread == -1) handleerror("getdents"); if (nread == 0) break;
printf("- nread=%d -\n", nread);
printf("i-node# file type dreclen doff dname\n"); for (bpos = 0; bpos < nread;) { d = (struct linuxdirent *) (buf + bpos);
printf("%8ld ", d->dino);
dtype = *(buf + bpos + d->dreclen - 1);
printf("%-10s ", (dtype == DTREG) ? "regular" : (dtype == DTDIR) ? "directory" : (dtype == DTFIFO) ? "FIFO" : (dtype == DTSOCK) ? "socket" : (dtype == DTLNK) ? "symlink" : (dtype == DTBLK) ? "block dev" : (dtype == DTCHR) ? "char dev" : "???");
printf("%4d %10lld %s\n", d->dreclen,
(long long) d->doff, d->dname);
bpos += d->dreclen; } } exit(EXITSUCCESS); } SEE ALSO readdir(2), readdir(3) COLOPHON
This page is part of release 3.53 of the Linux man-pages project. A description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
Linux 2012-08-03 GETDENTS(2)