original/man2/getdents.2

   1 .\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl>
  26 .\" Modified 22 July 1995 by Michael Chastain <mec@duracef.shout.net>:
  27 .\"   Derived from 'readdir.2'.
  28 .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
  29 .\"
  30 .TH GETDENTS 2  2012-08-03 "Linux" "Linux Programmer's Manual"
  31 .SH NAME
  32 getdents \- get directory entries
  33 .SH SYNOPSIS
  34 .nf
  35 .BI "int getdents(unsigned int " fd ", struct linux_dirent *" dirp ,
  36 .BI "             unsigned int " count );
  37 .fi
  38
  39 .IR Note :
  40 There is no glibc wrapper for this system call; see NOTES.
  41 .SH DESCRIPTION
  42 This is not the function you are interested in.
  43 Look at
  44 .BR readdir (3)
  45 for the POSIX conforming C library interface.
  46 This page documents the bare kernel system call interface.
  47 .PP
  48 The system call
  49 .BR getdents ()
  50 reads several
  51 .I linux_dirent
  52 structures from the directory
  53 referred to by the open file descriptor
  54 .I fd
  55 into the buffer pointed to by
  56 .IR dirp .
  57 The argument
  58 .I count
  59 specifies the size of that buffer.
  60 .PP
  61 The
  62 .I linux_dirent
  63 structure is declared as follows:
  64 .PP
  65 .in +4n
  66 .nf
  67 struct linux_dirent {
  68     unsigned long  d_ino;     /* Inode number */
  69     unsigned long  d_off;     /* Offset to next \fIlinux_dirent\fP */
  70     unsigned short d_reclen;  /* Length of this \fIlinux_dirent\fP */
  71     char           d_name[];  /* Filename (null-terminated) */
  72                       /* length is actually (d_reclen \- 2 \-
  73                          offsetof(struct linux_dirent, d_name)) */
  74     /*
  75     char           pad;       // Zero padding byte
  76     char           d_type;    // File type (only since Linux
  77                               // 2.6.4); offset is (d_reclen \- 1)
  78     */
  79
  80 }
  81 .fi
  82 .in
  83 .PP
  84 .I d_ino
  85 is an inode number.
  86 .I d_off
  87 is the distance from the start of the directory to the start of the next
  88 .IR linux_dirent .
  89 .I d_reclen
  90 is the size of this entire
  91 .IR linux_dirent .
  92 .I d_name
  93 is a null-terminated filename.
  94
  95 .I d_type
  96 is a byte at the end of the structure that indicates the file type.
  97 It contains one of the following values (defined in
  98 .IR <dirent.h> ):
  99 .TP 12
 100 .B DT_BLK
 101 This is a block device.
 102 .TP
 103 .B DT_CHR
 104 This is a character device.
 105 .TP
 106 .B DT_DIR
 107 This is a directory.
 108 .TP
 109 .B DT_FIFO
 110 This is a named pipe (FIFO).
 111 .TP
 112 .B DT_LNK
 113 This is a symbolic link.
 114 .TP
 115 .B DT_REG
 116 This is a regular file.
 117 .TP
 118 .B DT_SOCK
 119 This is a UNIX domain socket.
 120 .TP
 121 .B DT_UNKNOWN
 122 The file type is unknown.
 123 .PP
 124 The
 125 .I d_type
 126 field is implemented since Linux 2.6.4.
 127 It occupies a space that was previously a zero-filled padding byte in the
 128 .IR linux_dirent
 129 structure.
 130 Thus, on kernels before 2.6.3,
 131 attempting to access this field always provides the value 0
 132 .RB ( DT_UNKNOWN ).
 133 .PP
 134 Currently,
 135 .\" kernel 2.6.27
 136 .\" The same sentence is in readdir.2
 137 only some filesystems (among them: Btrfs, ext2, ext3, and ext4)
 138 have full support for returning the file type in
 139 .IR d_type .
 140 All applications must properly handle a return of
 141 .BR DT_UNKNOWN .
 142 .SH RETURN VALUE
 143 On success, the number of bytes read is returned.
 144 On end of directory, 0 is returned.
 145 On error, \-1 is returned, and
 146 .I errno
 147 is set appropriately.
 148 .SH ERRORS
 149 .TP
 150 .B EBADF
 151 Invalid file descriptor
 152 .IR fd .
 153 .TP
 154 .B EFAULT
 155 Argument points outside the calling process's address space.
 156 .TP
 157 .B EINVAL
 158 Result buffer is too small.
 159 .TP
 160 .B ENOENT
 161 No such directory.
 162 .TP
 163 .B ENOTDIR
 164 File descriptor does not refer to a directory.
 165 .SH CONFORMING TO
 166 SVr4.
 167 .\" SVr4 documents additional ENOLINK, EIO error conditions.
 168 .SH NOTES
 169 Glibc does not provide a wrapper for this system call; call it using
 170 .BR syscall (2).
 171 You will need to define the
 172 .I linux_dirent
 173 structure yourself.
 174 However, you probably want to use
 175 .BR readdir (3)
 176 instead.
 177
 178 This call supersedes
 179 .BR readdir (2).
 180
 181 The original Linux
 182 .BR getdents ()
 183 system call did not handle large filesystems and large file offsets.
 184 Consequently, Linux 2.4 added
 185 .BR getdents64 (),
 186 with wider types for the
 187 .I d_ino
 188 and
 189 .I d_off
 190 fields employed in the
 191 .IR linux_dirent
 192 structure.
 193 .SH EXAMPLE
 194 .\" FIXME The example program needs to be revised, since it uses the older
 195 .\" getdents() system call and the structure with smaller field widths.
 196 The program below demonstrates the use of
 197 .BR getdents ().
 198 The following output shows an example of what we see when running this
 199 program on an ext2 directory:
 200
 201 .in +4n
 202 .nf
 203 .RB "$" " ./a.out /testfs/"
 204 --------------- nread=120 ---------------
 205 inode#    file type  d_reclen  d_off   d_name
 206        2  directory    16         12  .
 207        2  directory    16         24  ..
 208       11  directory    24         44  lost+found
 209       12  regular      16         56  a
 210   228929  directory    16         68  sub
 211    16353  directory    16         80  sub2
 212   130817  directory    16       4096  sub3
 213 .fi
 214 .in
 215 .SS Program source
 216 \&
 217 .nf
 218 #define _GNU_SOURCE
 219 #include <dirent.h>     /* Defines DT_* constants */
 220 #include <fcntl.h>
 221 #include <stdio.h>
 222 #include <unistd.h>
 223 #include <stdlib.h>
 224 #include <sys/stat.h>
 225 #include <sys/syscall.h>
 226
 227 #define handle_error(msg) \\
 228         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 229
 230 struct linux_dirent {
 231     long           d_ino;
 232     off_t          d_off;
 233     unsigned short d_reclen;
 234     char           d_name[];
 235 };
 236
 237 #define BUF_SIZE 1024
 238
 239 int
 240 main(int argc, char *argv[])
 241 {
 242     int fd, nread;
 243     char buf[BUF_SIZE];
 244     struct linux_dirent *d;
 245     int bpos;
 246     char d_type;
 247
 248     fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY);
 249     if (fd == \-1)
 250         handle_error("open");
 251
 252     for ( ; ; ) {
 253         nread = syscall(SYS_getdents, fd, buf, BUF_SIZE);
 254         if (nread == \-1)
 255             handle_error("getdents");
 256
 257         if (nread == 0)
 258             break;
 259
 260         printf("\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=%d \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\\n", nread);
 261         printf("inode#    file type  d_reclen  d_off   d_name\\n");
 262         for (bpos = 0; bpos < nread;) {
 263             d = (struct linux_dirent *) (buf + bpos);
 264             printf("%8ld  ", d\->d_ino);
 265             d_type = *(buf + bpos + d\->d_reclen \- 1);
 266             printf("%\-10s ", (d_type == DT_REG) ?  "regular" :
 267                              (d_type == DT_DIR) ?  "directory" :
 268                              (d_type == DT_FIFO) ? "FIFO" :
 269                              (d_type == DT_SOCK) ? "socket" :
 270                              (d_type == DT_LNK) ?  "symlink" :
 271                              (d_type == DT_BLK) ?  "block dev" :
 272                              (d_type == DT_CHR) ?  "char dev" : "???");
 273             printf("%4d %10lld  %s\\n", d\->d_reclen,
 274                     (long long) d\->d_off, d\->d_name);
 275             bpos += d\->d_reclen;
 276         }
 277     }
 278
 279     exit(EXIT_SUCCESS);
 280 }
 281 .fi
 282 .SH SEE ALSO
 283 .BR readdir (2),
 284 .BR readdir (3)
 285 .SH COLOPHON
 286 This page is part of release 3.79 of the Linux
 287 .I man-pages
 288 project.
 289 A description of the project,
 290 information about reporting bugs,
 291 and the latest version of this page,
 292 can be found at
 293 \%http://www.kernel.org/doc/man\-pages/.