425 lines
15 KiB
HTML
425 lines
15 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of GETDENTS</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>GETDENTS</H1>
|
|
Section: Linux Programmer's Manual (2)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
getdents, getdents64 - get directory entries
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>int getdents(unsigned int </B><I>fd</I><B>, struct linux_dirent *</B><I>dirp</I><B>,</B>
|
|
<B> unsigned int </B><I>count</I><B>);</B>
|
|
<B>int getdents64(unsigned int </B><I>fd</I><B>, struct linux_dirent64 *</B><I>dirp</I><B>,</B>
|
|
<B> unsigned int </B><I>count</I><B>);</B>
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
<I>Note</I>:
|
|
|
|
There are no glibc wrappers for these system calls; see NOTES.
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
These are not the interfaces you are interested in.
|
|
Look at
|
|
<B><A HREF="/cgi-bin/man/man2html?3+readdir">readdir</A></B>(3)
|
|
|
|
for the POSIX-conforming C library interface.
|
|
This page documents the bare kernel system call interfaces.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>getdents()</H3>
|
|
|
|
The system call
|
|
<B>getdents</B>()
|
|
|
|
reads several
|
|
<I>linux_dirent</I>
|
|
|
|
structures from the directory
|
|
referred to by the open file descriptor
|
|
<I>fd</I>
|
|
|
|
into the buffer pointed to by
|
|
<I>dirp</I>.
|
|
|
|
The argument
|
|
<I>count</I>
|
|
|
|
specifies the size of that buffer.
|
|
<P>
|
|
|
|
The
|
|
<I>linux_dirent</I>
|
|
|
|
structure is declared as follows:
|
|
<P>
|
|
|
|
|
|
|
|
struct linux_dirent {
|
|
<BR> unsigned long d_ino; /* Inode number */
|
|
<BR> unsigned long d_off; /* Offset to next <I>linux_dirent</I> */
|
|
<BR> unsigned short d_reclen; /* Length of this <I>linux_dirent</I> */
|
|
<BR> char d_name[]; /* Filename (null-terminated) */
|
|
<BR> /* length is actually (d_reclen - 2 -
|
|
<BR> offsetof(struct linux_dirent, d_name)) */
|
|
<BR> /*
|
|
<BR> char pad; // Zero padding byte
|
|
<BR> char d_type; // File type (only since Linux
|
|
<BR> // 2.6.4); offset is (d_reclen - 1)
|
|
<BR> */
|
|
}
|
|
|
|
|
|
<P>
|
|
|
|
<I>d_ino</I>
|
|
|
|
is an inode number.
|
|
<I>d_off</I>
|
|
|
|
is the distance from the start of the directory to the start of the next
|
|
<I>linux_dirent</I>.
|
|
|
|
<I>d_reclen</I>
|
|
|
|
is the size of this entire
|
|
<I>linux_dirent</I>.
|
|
|
|
<I>d_name</I>
|
|
|
|
is a null-terminated filename.
|
|
<P>
|
|
|
|
<I>d_type</I>
|
|
|
|
is a byte at the end of the structure that indicates the file type.
|
|
It contains one of the following values (defined in
|
|
<I><<A HREF="file:///usr/include/dirent.h">dirent.h</A>></I>):
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>DT_BLK</B>
|
|
|
|
<DD>
|
|
This is a block device.
|
|
<DT id="2"><B>DT_CHR</B>
|
|
|
|
<DD>
|
|
This is a character device.
|
|
<DT id="3"><B>DT_DIR</B>
|
|
|
|
<DD>
|
|
This is a directory.
|
|
<DT id="4"><B>DT_FIFO</B>
|
|
|
|
<DD>
|
|
This is a named pipe (FIFO).
|
|
<DT id="5"><B>DT_LNK</B>
|
|
|
|
<DD>
|
|
This is a symbolic link.
|
|
<DT id="6"><B>DT_REG</B>
|
|
|
|
<DD>
|
|
This is a regular file.
|
|
<DT id="7"><B>DT_SOCK</B>
|
|
|
|
<DD>
|
|
This is a UNIX domain socket.
|
|
<DT id="8"><B>DT_UNKNOWN</B>
|
|
|
|
<DD>
|
|
The file type is unknown.
|
|
</DL>
|
|
<P>
|
|
|
|
The
|
|
<I>d_type</I>
|
|
|
|
field is implemented since Linux 2.6.4.
|
|
It occupies a space that was previously a zero-filled padding byte in the
|
|
<I>linux_dirent</I>
|
|
|
|
structure.
|
|
Thus, on kernels up to and including 2.6.3,
|
|
attempting to access this field always provides the value 0
|
|
(<B>DT_UNKNOWN</B>).
|
|
|
|
<P>
|
|
|
|
Currently,
|
|
|
|
|
|
only some filesystems (among them: Btrfs, ext2, ext3, and ext4)
|
|
have full support for returning the file type in
|
|
<I>d_type</I>.
|
|
|
|
All applications must properly handle a return of
|
|
<B>DT_UNKNOWN</B>.
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>getdents64()</H3>
|
|
|
|
The original Linux
|
|
<B>getdents</B>()
|
|
|
|
system call did not handle large filesystems and large file offsets.
|
|
Consequently, Linux 2.4 added
|
|
<B>getdents64</B>(),
|
|
|
|
with wider types for the
|
|
<I>d_ino</I>
|
|
|
|
and
|
|
<I>d_off</I>
|
|
|
|
fields.
|
|
In addition,
|
|
<B>getdents64</B>()
|
|
|
|
supports an explicit
|
|
<I>d_type</I>
|
|
|
|
field.
|
|
<P>
|
|
|
|
The
|
|
<B>getdents64</B>()
|
|
|
|
system call is like
|
|
<B>getdents</B>(),
|
|
|
|
except that its second argument is a pointer to a buffer containing
|
|
structures of the following type:
|
|
<P>
|
|
|
|
|
|
|
|
struct linux_dirent64 {
|
|
<BR> ino64_t d_ino; /* 64-bit inode number */
|
|
<BR> off64_t d_off; /* 64-bit offset to next structure */
|
|
<BR> unsigned short d_reclen; /* Size of this dirent */
|
|
<BR> unsigned char d_type; /* File type */
|
|
<BR> char d_name[]; /* Filename (null-terminated) */
|
|
};
|
|
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success, the number of bytes read is returned.
|
|
On end of directory, 0 is returned.
|
|
On error, -1 is returned, and
|
|
<I>errno</I>
|
|
|
|
is set appropriately.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="9"><B>EBADF</B>
|
|
|
|
<DD>
|
|
Invalid file descriptor
|
|
<I>fd</I>.
|
|
|
|
<DT id="10"><B>EFAULT</B>
|
|
|
|
<DD>
|
|
Argument points outside the calling process's address space.
|
|
<DT id="11"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
Result buffer is too small.
|
|
<DT id="12"><B>ENOENT</B>
|
|
|
|
<DD>
|
|
No such directory.
|
|
<DT id="13"><B>ENOTDIR</B>
|
|
|
|
<DD>
|
|
File descriptor does not refer to a directory.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
SVr4.
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
Glibc does not provide a wrapper for these system calls; call them using
|
|
<B><A HREF="/cgi-bin/man/man2html?2+syscall">syscall</A></B>(2).
|
|
|
|
You will need to define the
|
|
<I>linux_dirent</I>
|
|
|
|
or
|
|
<I>linux_dirent64</I>
|
|
|
|
structure yourself.
|
|
However, you probably want to use
|
|
<B><A HREF="/cgi-bin/man/man2html?3+readdir">readdir</A></B>(3)
|
|
|
|
instead.
|
|
<P>
|
|
|
|
These calls supersede
|
|
<B><A HREF="/cgi-bin/man/man2html?2+readdir">readdir</A></B>(2).
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
|
|
|
|
The program below demonstrates the use of
|
|
<B>getdents</B>().
|
|
|
|
The following output shows an example of what we see when running this
|
|
program on an ext2 directory:
|
|
<P>
|
|
|
|
|
|
|
|
$<B> ./a.out /testfs/</B>
|
|
|
|
--------------- nread=120 ---------------
|
|
inode# file type d_reclen d_off d_name
|
|
<BR> 2 directory 16 12 .
|
|
<BR> 2 directory 16 24 ..
|
|
<BR> 11 directory 24 44 lost+found
|
|
<BR> 12 regular 16 56 a
|
|
<BR> 228929 directory 16 68 sub
|
|
<BR> 16353 directory 16 80 sub2
|
|
<BR> 130817 directory 16 4096 sub3
|
|
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Program source</H3>
|
|
|
|
|
|
|
|
#define _GNU_SOURCE
|
|
#include <<A HREF="file:///usr/include/dirent.h">dirent.h</A>> /* Defines DT_* constants */
|
|
#include <<A HREF="file:///usr/include/fcntl.h">fcntl.h</A>>
|
|
#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
|
|
#include <<A HREF="file:///usr/include/unistd.h">unistd.h</A>>
|
|
#include <<A HREF="file:///usr/include/stdlib.h">stdlib.h</A>>
|
|
#include <<A HREF="file:///usr/include/sys/stat.h">sys/stat.h</A>>
|
|
#include <<A HREF="file:///usr/include/sys/syscall.h">sys/syscall.h</A>>
|
|
<P>
|
|
#define handle_error(msg) \
|
|
<BR> do { perror(msg); exit(EXIT_FAILURE); } while (0)
|
|
<P>
|
|
struct linux_dirent {
|
|
<BR> long d_ino;
|
|
<BR> off_t d_off;
|
|
<BR> unsigned short d_reclen;
|
|
<BR> char d_name[];
|
|
};
|
|
<P>
|
|
#define BUF_SIZE 1024
|
|
<P>
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
<BR> int fd, nread;
|
|
<BR> char buf[BUF_SIZE];
|
|
<BR> struct linux_dirent *d;
|
|
<BR> int bpos;
|
|
<BR> char d_type;
|
|
<P>
|
|
<BR> fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY);
|
|
<BR> if (fd == -1)
|
|
<BR> handle_error("open");
|
|
<P>
|
|
<BR> for ( ; ; ) {
|
|
<BR> nread = syscall(SYS_getdents, fd, buf, BUF_SIZE);
|
|
<BR> if (nread == -1)
|
|
<BR> handle_error("getdents");
|
|
<P>
|
|
<BR> if (nread == 0)
|
|
<BR> break;
|
|
<P>
|
|
<BR> printf("--------------- nread=%d ---------------\n", nread);
|
|
<BR> printf("inode# file type d_reclen d_off d_name\n");
|
|
<BR> for (bpos = 0; bpos < nread;) {
|
|
<BR> d = (struct linux_dirent *) (buf + bpos);
|
|
<BR> printf("%8ld ", d->d_ino);
|
|
<BR> d_type = *(buf + bpos + d->d_reclen - 1);
|
|
<BR> printf("%-10s ", (d_type == DT_REG) ? "regular" :
|
|
<BR> (d_type == DT_DIR) ? "directory" :
|
|
<BR> (d_type == DT_FIFO) ? "FIFO" :
|
|
<BR> (d_type == DT_SOCK) ? "socket" :
|
|
<BR> (d_type == DT_LNK) ? "symlink" :
|
|
<BR> (d_type == DT_BLK) ? "block dev" :
|
|
<BR> (d_type == DT_CHR) ? "char dev" : "???");
|
|
<BR> printf("%4d %10lld %s\n", d->d_reclen,
|
|
<BR> (long long) d->d_off, d->d_name);
|
|
<BR> bpos += d->d_reclen;
|
|
<BR> }
|
|
<BR> }
|
|
<P>
|
|
<BR> exit(EXIT_SUCCESS);
|
|
}
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+readdir">readdir</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+readdir">readdir</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+inode">inode</A></B>(7)
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="14"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="15"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="16"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="17"><A HREF="#lbAE">getdents()</A><DD>
|
|
<DT id="18"><A HREF="#lbAF">getdents64()</A><DD>
|
|
</DL>
|
|
<DT id="19"><A HREF="#lbAG">RETURN VALUE</A><DD>
|
|
<DT id="20"><A HREF="#lbAH">ERRORS</A><DD>
|
|
<DT id="21"><A HREF="#lbAI">CONFORMING TO</A><DD>
|
|
<DT id="22"><A HREF="#lbAJ">NOTES</A><DD>
|
|
<DT id="23"><A HREF="#lbAK">EXAMPLE</A><DD>
|
|
<DL>
|
|
<DT id="24"><A HREF="#lbAL">Program source</A><DD>
|
|
</DL>
|
|
<DT id="25"><A HREF="#lbAM">SEE ALSO</A><DD>
|
|
<DT id="26"><A HREF="#lbAN">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:32 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|