(split) LDP: Update original to LDP v3.51.

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

diff --git a/original/man3/readdir.3 b/original/man3/readdir.3
index bba5b47..140b5e4 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  2010-09-10 "" "Linux Programmer's Manual"
+.TH READDIR 3  2013-03-24 "" "Linux Programmer's Manual"
 .SH NAME
 readdir, readdir_r \- read a directory
 .SH SYNOPSIS
@@ -73,7 +75,7 @@ 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 */
@@ -114,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
@@ -142,7 +144,7 @@ returns 0, and returns NULL in
 .TP
 .B EBADF
 Invalid directory stream descriptor \fIdirp\fP.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
 SVr4, 4.3BSD, POSIX.1-2001.
 .SH NOTES
 Only the fields
@@ -161,6 +163,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 file systems.
+.\" 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.
@@ -209,7 +224,7 @@ 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
+have full support for returning the file type in
 .IR d_type .
 All applications must properly handle a return of
 .BR DT_UNKNOWN .
@@ -226,8 +241,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
@@ -236,7 +253,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),
@@ -247,5 +264,4 @@ 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)