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  2019-03-06 "" "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 appropriately.
 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 .TS
 195 allbox;
 196 lb lb lb
 197 l l l.
 198 Interface       Attribute       Value
 199 T{
 200 .BR readdir ()
 201 T}      Thread safety   MT-Unsafe race:dirstream
 202 .TE
 203 .sp 1
 204 .PP
 205 In the current POSIX.1 specification (POSIX.1-2008),
 206 .BR readdir ()
 207 is not required to be thread-safe.
 208 However, in modern implementations (including the glibc implementation),
 209 concurrent calls to
 210 .BR readdir ()
 211 that specify different directory streams are thread-safe.
 212 In cases where multiple threads must read from the same directory stream,
 213 using
 214 .BR readdir ()
 215 with external synchronization is still preferable to the use of the deprecated
 216 .BR readdir_r (3)
 217 function.
 218 It is expected that a future version of POSIX.1
 219 .\" FIXME .
 220 .\" http://www.austingroupbugs.net/view.php?id=696
 221 will require that
 222 .BR readdir ()
 223 be thread-safe when concurrently employed on different directory streams.
 224 .SH CONFORMING TO
 225 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 226 .SH NOTES
 227 A directory stream is opened using
 228 .BR opendir (3).
 229 .PP
 230 The order in which filenames are read by successive calls to
 231 .BR readdir ()
 232 depends on the filesystem implementation;
 233 it is unlikely that the names will be sorted in any fashion.
 234 .PP
 235 Only the fields
 236 .I d_name
 237 and (as an XSI extension)
 238 .I d_ino
 239 are specified in POSIX.1.
 240 .\" POSIX.1-2001, POSIX.1-2008
 241 Other than Linux, the
 242 .I d_type
 243 field is available mainly only on BSD systems.
 244 The remaining fields are available on many, but not all systems.
 245 Under glibc,
 246 programs can check for the availability of the fields not defined
 247 in POSIX.1 by testing whether the macros
 248 .BR _DIRENT_HAVE_D_NAMLEN ,
 249 .BR _DIRENT_HAVE_D_RECLEN ,
 250 .BR _DIRENT_HAVE_D_OFF ,
 251 or
 252 .B _DIRENT_HAVE_D_TYPE
 253 are defined.
 254 .\"
 255 .SS The d_name field
 256 The
 257 .I dirent
 258 structure definition shown above is taken from the glibc headers,
 259 and shows the
 260 .I d_name
 261 field with a fixed size.
 262 .PP
 263 .IR Warning :
 264 applications should avoid any dependence on the size of the
 265 .I d_name
 266 field.
 267 POSIX defines it as
 268 .IR "char\ d_name[]",
 269 a character array of unspecified size, with at most
 270 .B NAME_MAX
 271 characters preceding the terminating null byte (\(aq\e0\(aq).
 272 .PP
 273 POSIX.1 explicitly notes that this field should not be used as an lvalue.
 274 The standard also notes that the use of
 275 .I sizeof(d_name)
 276 is incorrect; use
 277 .IR strlen(d_name)
 278 instead.
 279 (On some systems, this field is defined as
 280 .IR char\ d_name[1] !)
 281 By implication, the use
 282 .IR "sizeof(struct dirent)"
 283 to capture the size of the record including the size of
 284 .IR d_name
 285 is also incorrect.
 286 .PP
 287 Note that while the call
 288 .PP
 289     fpathconf(fd, _PC_NAME_MAX)
 290 .PP
 291 returns the value 255 for most filesystems,
 292 on some filesystems (e.g., CIFS, Windows SMB servers),
 293 the null-terminated filename that is (correctly) returned in
 294 .I d_name
 295 can actually exceed this size.
 296 In such cases, the
 297 .I d_reclen
 298 field will contain a value that exceeds the size of the glibc
 299 .I dirent
 300 structure shown above.
 301 .SH SEE ALSO
 302 .BR getdents (2),
 303 .BR read (2),
 304 .BR closedir (3),
 305 .BR dirfd (3),
 306 .BR ftw (3),
 307 .BR offsetof (3),
 308 .BR opendir (3),
 309 .BR readdir_r (3),
 310 .BR rewinddir (3),
 311 .BR scandir (3),
 312 .BR seekdir (3),
 313 .BR telldir (3)