.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" References consulted:
.\" Linux libc source code
.\" Rework discussion of nonstandard structure fields.
.\" 2008-09-11, mtk, Document readdir_r().
.\"
-.TH READDIR 3 2010-09-10 "" "Linux Programmer's Manual"
+.TH READDIR 3 2013-06-21 "" "Linux Programmer's Manual"
.SH NAME
readdir, readdir_r \- read a directory
.SH SYNOPSIS
.nf
struct dirent {
ino_t d_ino; /* inode number */
- off_t d_off; /* offset to the next dirent */
+ off_t d_off; /* not an offset; see NOTES */
unsigned short d_reclen; /* length of this record */
unsigned char d_type; /* type of file; not supported
- by all file system types */
+ by all filesystem types */
char d_name[256]; /* filename */
};
.fi
.IR d_name [],
of unspecified size, with at most
.B NAME_MAX
-characters preceding the terminating null byte;
+characters preceding the terminating null byte (\(aq\\0\(aq);
and (as an XSI extension)
.IR d_ino .
The other fields are unstandardized, and not present on all systems;
if the end of the directory stream was encountered,
then NULL is instead returned in
.IR *result .
-.SH "RETURN VALUE"
+.SH RETURN VALUE
On success,
.BR readdir ()
returns a pointer to a
.TP
.B EBADF
Invalid directory stream descriptor \fIdirp\fP.
-.SH "CONFORMING TO"
+.SH ATTRIBUTES
+.SS Multithreading (see pthreads(7))
+The
+.BR readdir ()
+function is not thread-safe.
+.LP
+The
+.BR readdir_r ()
+function is thread-safe.
+.SH CONFORMING TO
SVr4, 4.3BSD, POSIX.1-2001.
.SH NOTES
Only the fields
.B _DIRENT_HAVE_D_TYPE
are defined.
+The value returned in
+.I d_off
+is the same as would be returned by calling
+.BR telldir (3)
+at the current position in the directory stream.
+Be aware that despite its type and name, the
+.I d_off
+field is seldom any kind of directory offset on modern filesystems.
+.\" https://lwn.net/Articles/544298/
+Applications should treat this field as an opaque value,
+making no assumptions about its contents; see also
+.BR telldir (3).
+
Other than Linux, the
.I d_type
field is available mainly only on BSD systems.
Currently,
.\" kernel 2.6.27
.\" The same sentence is in getdents.2
-only some file systems (among them: Btrfs, ext2, ext3, and ext4)
-have full support returning the file type in
+only some filesystems (among them: Btrfs, ext2, ext3, and ext4)
+have full support for returning the file type in
.IR d_type .
All applications must properly handle a return of
.BR DT_UNKNOWN .
.in +4n
.nf
-len = offsetof(struct dirent, d_name) +
- pathconf(dirpath, _PC_NAME_MAX) + 1
+name_max = pathconf(dirpath, _PC_NAME_MAX);
+if (name_max == \-1) /* Limit not defined, or error */
+ name_max = 255; /* Take a guess */
+len = offsetof(struct dirent, d_name) + name_max + 1;
entryp = malloc(len);
.fi
.I d_name
is the last field in a
.IR "struct dirent" .)
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR getdents (2),
.BR read (2),
.BR closedir (3),
.BR scandir (3),
.BR seekdir (3),
.BR telldir (3)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.