man3/readdir.3

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