2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl)
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl>
|
|
|
|
.\" Modified 22 July 1995 by Michael Chastain <mec@duracef.shout.net>:
|
|
|
|
.\" Derived from 'readdir.2'.
|
|
|
|
.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
|
2009-07-04 13:04:43 +00:00
|
|
|
.TH GETDENTS 2 2009-07-04 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
getdents \- get directory entries
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
2008-10-02 09:15:28 +00:00
|
|
|
.BI "int getdents(unsigned int " fd ", struct linux_dirent *" dirp ,
|
2008-07-06 14:26:07 +00:00
|
|
|
.BI " unsigned int " count );
|
2004-11-03 13:51:07 +00:00
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
This is not the function you are interested in.
|
|
|
|
Look at
|
|
|
|
.BR readdir (3)
|
|
|
|
for the POSIX conforming C library interface.
|
|
|
|
This page documents the bare kernel system call interface.
|
|
|
|
.PP
|
|
|
|
The system call
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR getdents ()
|
2007-04-12 22:42:49 +00:00
|
|
|
reads several
|
2008-10-02 09:15:28 +00:00
|
|
|
.I linux_dirent
|
2004-11-03 13:51:07 +00:00
|
|
|
structures from the directory
|
2008-06-17 21:51:05 +00:00
|
|
|
referred to by the open file descriptor
|
2004-11-03 13:51:07 +00:00
|
|
|
.I fd
|
2008-06-17 21:51:05 +00:00
|
|
|
into the buffer pointed to by
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR dirp .
|
2008-07-10 20:53:08 +00:00
|
|
|
The argument
|
2004-11-03 13:51:07 +00:00
|
|
|
.I count
|
2009-01-13 04:17:03 +00:00
|
|
|
specifies the size of that buffer.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The
|
2008-10-02 09:15:28 +00:00
|
|
|
.I linux_dirent
|
2004-11-03 13:51:07 +00:00
|
|
|
structure is declared as follows:
|
|
|
|
.PP
|
2007-12-23 14:14:04 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
2008-06-17 21:51:05 +00:00
|
|
|
struct linux_dirent {
|
|
|
|
unsigned long d_ino; /* Inode number */
|
2008-10-02 09:15:28 +00:00
|
|
|
unsigned long d_off; /* Offset to next \fIlinux_dirent\fP */
|
|
|
|
unsigned short d_reclen; /* Length of this \fIlinux_dirent\fP */
|
2008-10-02 11:07:58 +00:00
|
|
|
char d_name[]; /* Filename (null-terminated) */
|
2008-06-26 13:23:48 +00:00
|
|
|
/* length is actually (d_reclen \- 2 \-
|
2008-06-17 21:51:05 +00:00
|
|
|
offsetof(struct linux_dirent, d_name) */
|
2008-10-02 11:07:58 +00:00
|
|
|
/*
|
2009-09-27 07:26:27 +00:00
|
|
|
char pad; // Zero padding byte
|
2008-10-02 11:07:58 +00:00
|
|
|
char d_type; // File type (only since Linux 2.6.4;
|
|
|
|
// offset is (d_reclen \- 1))
|
|
|
|
*/
|
2008-06-17 21:51:05 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
}
|
2007-12-23 21:05:57 +00:00
|
|
|
.fi
|
2007-12-23 14:14:04 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
.I d_ino
|
|
|
|
is an inode number.
|
|
|
|
.I d_off
|
|
|
|
is the distance from the start of the directory to the start of the next
|
2008-10-02 09:15:28 +00:00
|
|
|
.IR linux_dirent .
|
2004-11-03 13:51:07 +00:00
|
|
|
.I d_reclen
|
|
|
|
is the size of this entire
|
2008-10-02 09:15:28 +00:00
|
|
|
.IR linux_dirent .
|
2004-11-03 13:51:07 +00:00
|
|
|
.I d_name
|
2006-02-12 22:15:41 +00:00
|
|
|
is a null-terminated filename.
|
2008-06-17 21:51:05 +00:00
|
|
|
|
|
|
|
.I d_type
|
|
|
|
is a byte at the end of the structure that indicates the file type.
|
2008-10-02 09:35:50 +00:00
|
|
|
It contains one of the following values (defined in
|
|
|
|
.IR <dirent.h> ):
|
2008-06-17 21:51:05 +00:00
|
|
|
.TP 12
|
|
|
|
.B DT_BLK
|
|
|
|
This is a block device.
|
|
|
|
.TP
|
|
|
|
.B DT_CHR
|
|
|
|
This is a character device.
|
|
|
|
.TP
|
|
|
|
.B DT_DIR
|
|
|
|
This is a directory.
|
|
|
|
.TP
|
|
|
|
.B DT_FIFO
|
|
|
|
This is a named pipe (FIFO).
|
|
|
|
.TP
|
|
|
|
.B DT_LNK
|
|
|
|
This is a symbolic link.
|
|
|
|
.TP
|
|
|
|
.B DT_REG
|
|
|
|
This is a regular file.
|
|
|
|
.TP
|
|
|
|
.B DT_SOCK
|
|
|
|
This is a Unix domain socket.
|
|
|
|
.TP
|
|
|
|
.B DT_UNKNOWN
|
|
|
|
The file type is unknown.
|
2008-09-29 13:06:36 +00:00
|
|
|
.PP
|
2009-01-13 04:46:17 +00:00
|
|
|
The
|
|
|
|
.I d_type
|
|
|
|
field is implemented since Linux 2.6.4.
|
|
|
|
It occupies a space that was previously a zero-filled padding byte in the
|
|
|
|
.IR linux_dirent
|
|
|
|
structure.
|
|
|
|
Thus, on kernels before 2.6.3,
|
|
|
|
attempting to access this field always provides the value 0
|
|
|
|
.RB ( DT_UNKNOWN ).
|
|
|
|
.PP
|
2008-10-29 14:20:44 +00:00
|
|
|
Currently,
|
2008-09-29 13:06:36 +00:00
|
|
|
.\" kernel 2.6.27
|
2008-10-29 14:20:44 +00:00
|
|
|
.\" The same sentence is in readdir.2
|
2009-09-27 07:26:27 +00:00
|
|
|
only some file systems (among them: Btrfs, ext2, ext3, and ext4)
|
2009-01-13 04:17:03 +00:00
|
|
|
have full support for returning the file type in
|
2008-09-29 13:06:36 +00:00
|
|
|
.IR d_type .
|
2008-10-29 14:20:44 +00:00
|
|
|
All applications must properly handle a return of
|
2008-09-29 13:06:36 +00:00
|
|
|
.BR DT_UNKNOWN .
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
|
|
|
On success, the number of bytes read is returned.
|
|
|
|
On end of directory, 0 is returned.
|
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
|
|
|
Invalid file descriptor
|
|
|
|
.IR fd .
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
Argument points outside the calling process's address space.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
Result buffer is too small.
|
|
|
|
.TP
|
|
|
|
.B ENOENT
|
|
|
|
No such directory.
|
|
|
|
.TP
|
|
|
|
.B ENOTDIR
|
|
|
|
File descriptor does not refer to a directory.
|
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:17 +00:00
|
|
|
SVr4.
|
|
|
|
.\" SVr4 documents additional ENOLINK, EIO error conditions.
|
2007-05-26 15:22:28 +00:00
|
|
|
.SH NOTES
|
|
|
|
Glibc does not provide a wrapper for this system call; call it using
|
|
|
|
.BR syscall (2).
|
2008-10-02 09:27:17 +00:00
|
|
|
You will need to define the
|
|
|
|
.I linux_dirent
|
|
|
|
structure yourself.
|
2008-06-17 21:51:05 +00:00
|
|
|
|
|
|
|
This call supersedes
|
|
|
|
.BR readdir (2).
|
2008-10-02 11:15:42 +00:00
|
|
|
.SH EXAMPLE
|
|
|
|
The program below demonstrates the use of
|
|
|
|
.BR getdents ().
|
|
|
|
The following output shows an example of what we see when running this
|
|
|
|
program on an ext2 directory:
|
|
|
|
|
|
|
|
.in +4n
|
|
|
|
.nf
|
eventfd.2, execve.2, getdents.2, ioprio_set.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, malloc.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, strtok.3, strtol.3, core.5, proc.5, cpuset.7, mq_overview.7: Global fix: Format user input in shell sessions in boldface
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-10-28 15:37:22 +00:00
|
|
|
.RB "$" " ./a.out /testfs/"
|
2008-10-02 11:15:42 +00:00
|
|
|
--------------- nread=120 ---------------
|
|
|
|
i-node# file type d_reclen d_off d_name
|
|
|
|
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
|
|
|
|
.fi
|
|
|
|
.in
|
eventfd.2, getdents.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strtol.3, core.5: global fix: Add ".SS Program source" to EXAMPLE
Add ".SS Program source" to clearly distinguish shell session and
descriptive text from actual program code.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-10-28 15:51:05 +00:00
|
|
|
.SS Program source
|
eventfd.2, getdents.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, getaddrinfo.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, strtok.3, strtol.3, core.5: srcfix
s/\.R " "/\\\&/ as a way of getting a blank line after a .SS heading.
(Suggested by Sam Varshavchik <mrsam@courier-mta.com>)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-11-05 01:42:45 +00:00
|
|
|
\&
|
2008-10-02 11:15:42 +00:00
|
|
|
.nf
|
|
|
|
#define _GNU_SOURCE
|
|
|
|
#include <dirent.h> /* Defines DT_* constants */
|
|
|
|
#include <fcntl.h>
|
|
|
|
#include <stdio.h>
|
|
|
|
#include <unistd.h>
|
|
|
|
#include <stdlib.h>
|
|
|
|
#include <sys/stat.h>
|
|
|
|
#include <sys/syscall.h>
|
|
|
|
|
2008-11-11 13:35:25 +00:00
|
|
|
#define handle_error(msg) \\
|
|
|
|
do { perror(msg); exit(EXIT_FAILURE); } while (0)
|
2008-10-02 11:15:42 +00:00
|
|
|
|
|
|
|
struct linux_dirent {
|
|
|
|
long d_ino;
|
|
|
|
off_t d_off;
|
|
|
|
unsigned short d_reclen;
|
|
|
|
char d_name[];
|
|
|
|
};
|
|
|
|
|
|
|
|
#define BUF_SIZE 1024
|
|
|
|
|
|
|
|
int
|
|
|
|
main(int argc, char *argv[])
|
|
|
|
{
|
|
|
|
int fd, nread;
|
|
|
|
char buf[BUF_SIZE];
|
|
|
|
struct linux_dirent *d;
|
|
|
|
int bpos;
|
|
|
|
char d_type;
|
|
|
|
|
|
|
|
fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY);
|
|
|
|
if (fd == \-1)
|
2008-11-11 13:35:25 +00:00
|
|
|
handle_error("open");
|
2008-10-02 11:15:42 +00:00
|
|
|
|
|
|
|
for ( ; ; ) {
|
|
|
|
nread = syscall(SYS_getdents, fd, buf, BUF_SIZE);
|
|
|
|
if (nread == \-1)
|
2008-11-11 13:35:25 +00:00
|
|
|
handle_error("getdents");
|
2008-10-02 11:15:42 +00:00
|
|
|
|
|
|
|
if (nread == 0)
|
|
|
|
break;
|
|
|
|
|
|
|
|
printf("\--------------- nread=%d ---------------\\n", nread);
|
|
|
|
printf("i\-node# file type d_reclen d_off d_name\\n");
|
|
|
|
for (bpos = 0; bpos < nread;) {
|
|
|
|
d = (struct linux_dirent *) (buf + bpos);
|
|
|
|
printf("%8ld ", d\->d_ino);
|
|
|
|
d_type = *(buf + bpos + d\->d_reclen - 1);
|
|
|
|
printf("%\-10s ", (d_type == DT_REG) ? "regular" :
|
|
|
|
(d_type == DT_DIR) ? "directory" :
|
|
|
|
(d_type == DT_FIFO) ? "FIFO" :
|
|
|
|
(d_type == DT_SOCK) ? "socket" :
|
|
|
|
(d_type == DT_LNK) ? "symlink" :
|
|
|
|
(d_type == DT_BLK) ? "block dev" :
|
|
|
|
(d_type == DT_CHR) ? "char dev" : "???");
|
|
|
|
printf("%4d %10lld %s\\n", d\->d_reclen,
|
|
|
|
(long long) d\->d_off, (char *) d->d_name);
|
|
|
|
bpos += d\->d_reclen;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
exit(EXIT_SUCCESS);
|
|
|
|
}
|
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR readdir (2),
|
|
|
|
.BR readdir (3)
|