man2/readdir.2

   1 .\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl>
   6 .\" Modified 22 July 1995 by Michael Chastain <mec@duracef.shout.net>:
   7 .\"   In 1.3.X, returns only one entry each time; return value is different.
   8 .\" Modified 2004-12-01, mtk, fixed headers listed in SYNOPSIS
   9 .\"
  10 .TH READDIR 2  2021-03-22 "Linux" "Linux Programmer's Manual"
  11 .SH NAME
  12 readdir \- read directory entry
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  19 .B #include <unistd.h>
  20 .PP
  21 .BI "int syscall(SYS_readdir, unsigned int " fd ,
  22 .BI "            struct old_linux_dirent *" dirp ", unsigned int " count );
  23 .fi
  24 .PP
  25 .IR Note :
  26 There is no definition of
  27 .BR "struct old_linux_dirent" ;
  28 see NOTES.
  29 .SH DESCRIPTION
  30 This is not the function you are interested in.
  31 Look at
  32 .BR readdir (3)
  33 for the POSIX conforming C library interface.
  34 This page documents the bare kernel system call interface,
  35 which is superseded by
  36 .BR getdents (2).
  37 .PP
  38 .BR readdir ()
  39 reads one
  40 .I old_linux_dirent
  41 structure from the directory
  42 referred to by the file descriptor
  43 .I fd
  44 into the buffer pointed to by
  45 .IR dirp .
  46 The argument
  47 .I count
  48 is ignored; at most one
  49 .I old_linux_dirent
  50 structure is read.
  51 .PP
  52 The
  53 .I old_linux_dirent
  54 structure is declared (privately in Linux kernel file
  55 .BR fs/readdir.c )
  56 as follows:
  57 .PP
  58 .in +4n
  59 .EX
  60 struct old_linux_dirent {
  61     unsigned long d_ino;     /* inode number */
  62     unsigned long d_offset;  /* offset to this \fIold_linux_dirent\fP */
  63     unsigned short d_namlen; /* length of this \fId_name\fP */
  64     char  d_name[1];         /* filename (null\-terminated) */
  65 }
  66 .EE
  67 .in
  68 .PP
  69 .I d_ino
  70 is an inode number.
  71 .I d_offset
  72 is the distance from the start of the directory to this
  73 .IR old_linux_dirent .
  74 .I d_reclen
  75 is the size of
  76 .IR d_name ,
  77 not counting the terminating null byte (\(aq\e0\(aq).
  78 .I d_name
  79 is a null-terminated filename.
  80 .SH RETURN VALUE
  81 On success, 1 is returned.
  82 On end of directory, 0 is returned.
  83 On error, \-1 is returned, and
  84 .I errno
  85 is set to indicate the error.
  86 .SH ERRORS
  87 .TP
  88 .B EBADF
  89 Invalid file descriptor
  90 .IR fd .
  91 .TP
  92 .B EFAULT
  93 Argument points outside the calling process's address space.
  94 .TP
  95 .B EINVAL
  96 Result buffer is too small.
  97 .TP
  98 .B ENOENT
  99 No such directory.
 100 .TP
 101 .B ENOTDIR
 102 File descriptor does not refer to a directory.
 103 .SH STANDARDS
 104 This system call is Linux-specific.
 105 .SH NOTES
 106 You will need to define the
 107 .I old_linux_dirent
 108 structure yourself.
 109 However, probably you should use
 110 .BR readdir (3)
 111 instead.
 112 .PP
 113 This system call does not exist on x86-64.
 114 .SH SEE ALSO
 115 .BR getdents (2),
 116 .BR readdir (3)