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