man3/readdir.3

   1 .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu)
  11 .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl)
  12 .\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl)
  13 .\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>, mtk:
  14 .\"     Rework discussion of nonstandard structure fields.
  15 .\"
  16 .TH READDIR 3 2021-03-22 "Linux man-pages (unreleased)"
  17 .SH NAME
  18 readdir \- read a directory
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <dirent.h>
  25 .PP
  26 .BI "struct dirent *readdir(DIR *" dirp );
  27 .fi
  28 .SH DESCRIPTION
  29 The
  30 .BR readdir ()
  31 function returns a pointer to a \fIdirent\fP structure
  32 representing the next directory entry in the directory stream pointed
  33 to by \fIdirp\fP.
  34 It returns NULL on reaching the end of the directory stream or if
  35 an error occurred.
  36 .PP
  37 In the glibc implementation, the
  38 .I dirent
  39 structure is defined as follows:
  40 .PP
  41 .in +4n
  42 .EX
  43 struct dirent {
  44     ino_t          d_ino;       /* Inode number */
  45     off_t          d_off;       /* Not an offset; see below */
  46     unsigned short d_reclen;    /* Length of this record */
  47     unsigned char  d_type;      /* Type of file; not supported
  48                                    by all filesystem types */
  49     char           d_name[256]; /* Null\-terminated filename */
  50 };
  51 .EE
  52 .in
  53 .PP
  54 The only fields in the
  55 .I dirent
  56 structure that are mandated by POSIX.1 are
  57 .I d_name
  58 and
  59 .IR d_ino .
  60 The other fields are unstandardized, and not present on all systems;
  61 see NOTES below for some further details.
  62 .PP
  63 The fields of the
  64 .I dirent
  65 structure are as follows:
  66 .TP
  67 .I d_ino
  68 This is the inode number of the file.
  69 .TP
  70 .I d_off
  71 The value returned in
  72 .I d_off
  73 is the same as would be returned by calling
  74 .BR telldir (3)
  75 at the current position in the directory stream.
  76 Be aware that despite its type and name, the
  77 .I d_off
  78 field is seldom any kind of directory offset on modern filesystems.
  79 .\" https://lwn.net/Articles/544298/
  80 Applications should treat this field as an opaque value,
  81 making no assumptions about its contents; see also
  82 .BR telldir (3).
  83 .TP
  84 .I d_reclen
  85 This is the size (in bytes) of the returned record.
  86 This may not match the size of the structure definition shown above;
  87 see NOTES.
  88 .TP
  89 .I d_type
  90 This field contains a value indicating the file type,
  91 making it possible to avoid the expense of calling
  92 .BR lstat (2)
  93 if further actions depend on the type of the file.
  94 .IP
  95 When a suitable feature test macro is defined
  96 .RB ( _DEFAULT_SOURCE
  97 on glibc versions since 2.19, or
  98 .B _BSD_SOURCE
  99 on glibc versions 2.19 and earlier),
 100 glibc defines the following macro constants for the value returned in
 101 .IR d_type :
 102 .RS
 103 .TP 12
 104 .B DT_BLK
 105 This is a block device.
 106 .TP
 107 .B DT_CHR
 108 This is a character device.
 109 .TP
 110 .B DT_DIR
 111 This is a directory.
 112 .TP
 113 .B DT_FIFO
 114 This is a named pipe (FIFO).
 115 .TP
 116 .B DT_LNK
 117 This is a symbolic link.
 118 .TP
 119 .B DT_REG
 120 This is a regular file.
 121 .TP
 122 .B DT_SOCK
 123 This is a UNIX domain socket.
 124 .TP
 125 .B DT_UNKNOWN
 126 The file type could not be determined.
 127 .RE
 128 .IP
 129 Currently,
 130 .\" kernel 2.6.27
 131 .\" The same sentence is in getdents.2
 132 only some filesystems (among them: Btrfs, ext2, ext3, and ext4)
 133 have full support for returning the file type in
 134 .IR d_type .
 135 All applications must properly handle a return of
 136 .BR DT_UNKNOWN .
 137 .TP
 138 .I d_name
 139 This field contains the null terminated filename.
 140 .IR "See NOTES" .
 141 .PP
 142 The data returned by
 143 .BR readdir ()
 144 may be overwritten by subsequent calls to
 145 .BR readdir ()
 146 for the same directory stream.
 147 .SH RETURN VALUE
 148 On success,
 149 .BR readdir ()
 150 returns a pointer to a
 151 .I dirent
 152 structure.
 153 (This structure may be statically allocated; do not attempt to
 154 .BR free (3)
 155 it.)
 156 .PP
 157 If the end of the directory stream is reached, NULL is returned and
 158 .I errno
 159 is not changed.
 160 If an error occurs, NULL is returned and
 161 .I errno
 162 is set to indicate the error.
 163 To distinguish end of stream from an error, set
 164 .I errno
 165 to zero before calling
 166 .BR readdir ()
 167 and then check the value of
 168 .I errno
 169 if NULL is returned.
 170 .SH ERRORS
 171 .TP
 172 .B EBADF
 173 Invalid directory stream descriptor \fIdirp\fP.
 174 .SH ATTRIBUTES
 175 For an explanation of the terms used in this section, see
 176 .BR attributes (7).
 177 .ad l
 178 .nh
 179 .TS
 180 allbox;
 181 lbx lb lb
 182 l l l.
 183 Interface       Attribute       Value
 184 T{
 185 .BR readdir ()
 186 T}      Thread safety   MT-Unsafe race:dirstream
 187 .TE
 188 .hy
 189 .ad
 190 .sp 1
 191 .PP
 192 In the current POSIX.1 specification (POSIX.1-2008),
 193 .BR readdir ()
 194 is not required to be thread-safe.
 195 However, in modern implementations (including the glibc implementation),
 196 concurrent calls to
 197 .BR readdir ()
 198 that specify different directory streams are thread-safe.
 199 In cases where multiple threads must read from the same directory stream,
 200 using
 201 .BR readdir ()
 202 with external synchronization is still preferable to the use of the deprecated
 203 .BR readdir_r (3)
 204 function.
 205 It is expected that a future version of POSIX.1
 206 .\" FIXME .
 207 .\" http://www.austingroupbugs.net/view.php?id=696
 208 will require that
 209 .BR readdir ()
 210 be thread-safe when concurrently employed on different directory streams.
 211 .SH STANDARDS
 212 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 213 .SH NOTES
 214 A directory stream is opened using
 215 .BR opendir (3).
 216 .PP
 217 The order in which filenames are read by successive calls to
 218 .BR readdir ()
 219 depends on the filesystem implementation;
 220 it is unlikely that the names will be sorted in any fashion.
 221 .PP
 222 Only the fields
 223 .I d_name
 224 and (as an XSI extension)
 225 .I d_ino
 226 are specified in POSIX.1.
 227 .\" POSIX.1-2001, POSIX.1-2008
 228 Other than Linux, the
 229 .I d_type
 230 field is available mainly only on BSD systems.
 231 The remaining fields are available on many, but not all systems.
 232 Under glibc,
 233 programs can check for the availability of the fields not defined
 234 in POSIX.1 by testing whether the macros
 235 .BR _DIRENT_HAVE_D_NAMLEN ,
 236 .BR _DIRENT_HAVE_D_RECLEN ,
 237 .BR _DIRENT_HAVE_D_OFF ,
 238 or
 239 .B _DIRENT_HAVE_D_TYPE
 240 are defined.
 241 .\"
 242 .SS The d_name field
 243 The
 244 .I dirent
 245 structure definition shown above is taken from the glibc headers,
 246 and shows the
 247 .I d_name
 248 field with a fixed size.
 249 .PP
 250 .IR Warning :
 251 applications should avoid any dependence on the size of the
 252 .I d_name
 253 field.
 254 POSIX defines it as
 255 .IR "char\ d_name[]",
 256 a character array of unspecified size, with at most
 257 .B NAME_MAX
 258 characters preceding the terminating null byte (\(aq\e0\(aq).
 259 .PP
 260 POSIX.1 explicitly notes that this field should not be used as an lvalue.
 261 The standard also notes that the use of
 262 .I sizeof(d_name)
 263 is incorrect; use
 264 .I strlen(d_name)
 265 instead.
 266 (On some systems, this field is defined as
 267 .IR char\~d_name[1] !)
 268 By implication, the use
 269 .I sizeof(struct dirent)
 270 to capture the size of the record including the size of
 271 .I d_name
 272 is also incorrect.
 273 .PP
 274 Note that while the call
 275 .PP
 276 .in +4n
 277 .EX
 278 fpathconf(fd, _PC_NAME_MAX)
 279 .EE
 280 .in
 281 .PP
 282 returns the value 255 for most filesystems,
 283 on some filesystems (e.g., CIFS, Windows SMB servers),
 284 the null-terminated filename that is (correctly) returned in
 285 .I d_name
 286 can actually exceed this size.
 287 In such cases, the
 288 .I d_reclen
 289 field will contain a value that exceeds the size of the glibc
 290 .I dirent
 291 structure shown above.
 292 .SH SEE ALSO
 293 .BR getdents (2),
 294 .BR read (2),
 295 .BR closedir (3),
 296 .BR dirfd (3),
 297 .BR ftw (3),
 298 .BR offsetof (3),
 299 .BR opendir (3),
 300 .BR readdir_r (3),
 301 .BR rewinddir (3),
 302 .BR scandir (3),
 303 .BR seekdir (3),
 304 .BR telldir (3)