LDP: Update original to LDP v3.79

[linuxjm/LDP_man-pages.git] / original / man3 / readdir.3

diff --git a/original/man3/readdir.3 b/original/man3/readdir.3
index 90499a6..5642c4d 100644 (file)
--- a/original/man3/readdir.3
+++ b/original/man3/readdir.3
@@ -1,5 +1,6 @@
 .\" 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.
@@ -19,6 +20,7 @@
 .\"
 .\" 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
@@ -31,7 +33,7 @@
 .\"     Rework discussion of nonstandard structure fields.
 .\" 2008-09-11, mtk, Document readdir_r().
 .\"
-.TH READDIR 3  2009-07-04 "" "Linux Programmer's Manual"
+.TH READDIR 3  2013-06-21 "" "Linux Programmer's Manual"
 .SH NAME
 readdir, readdir_r \- read a directory
 .SH SYNOPSIS
@@ -51,8 +53,10 @@ Feature Test Macro Requirements for glibc (see
 .in
 .sp
 .BR readdir_r ():
+.RS 4
 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE ||
 _SVID_SOURCE || _POSIX_SOURCE
+.RE
 .ad b
 .SH DESCRIPTION
 The
@@ -71,10 +75,10 @@ structure is defined as follows:
 .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
@@ -86,7 +90,7 @@ structure that are mandated by POSIX.1 are:
 .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;
@@ -112,7 +116,7 @@ A pointer to the returned item is placed in
 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
@@ -131,7 +135,7 @@ is set appropriately.
 The
 .BR readdir_r ()
 function returns 0 on success.
-On error, it returns a positive error number.
+On error, it returns a positive error number (listed under ERRORS).
 If the end of the directory stream is reached,
 .BR readdir_r ()
 returns 0, and returns NULL in
@@ -140,7 +144,16 @@ returns 0, and returns NULL in
 .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
@@ -159,6 +172,19 @@ or
 .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.
@@ -191,7 +217,7 @@ This is a symbolic link.
 This is a regular file.
 .TP
 .B DT_SOCK
-This is a Unix domain socket.
+This is a UNIX domain socket.
 .TP
 .B DT_UNKNOWN
 The file type is unknown.
@@ -206,8 +232,8 @@ is returned in
 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 .
@@ -224,8 +250,10 @@ as follows:
 .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
@@ -234,7 +262,7 @@ entryp = malloc(len);
 .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),
@@ -245,5 +273,13 @@ is the last field in a
 .BR rewinddir (3),
 .BR scandir (3),
 .BR seekdir (3),
-.BR telldir (3),
-.BR feature_test_macros (7)
+.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/.