Merging upstream version 6.7.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 25 insertions, 21 deletions

diff --git a/man2/getdents.2 b/man2/getdents.2
index 604a6ef..728d4d7 100644
--- a/man2/getdents.2
+++ b/man2/getdents.2
@@ -8,7 +8,7 @@
 .\"   Derived from 'readdir.2'.
 .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
 .\"
-.TH getdents 2 2023-05-03 "Linux man-pages 6.05.01"
+.TH getdents 2 2024-02-25 "Linux man-pages 6.7"
 .SH NAME
 getdents, getdents64 \- get directory entries
 .SH LIBRARY
@@ -18,23 +18,23 @@ Standard C library
 .nf
 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
-.PP
+.P
 .BI "long syscall(SYS_getdents, unsigned int " fd \
 ", struct linux_dirent *" dirp ,
 .BI "             unsigned int " count );
-.PP
+.P
 .BR "#define _GNU_SOURCE" "           /* See feature_test_macros(7) */"
 .B #include <dirent.h>
-.PP
+.P
 .BI "ssize_t getdents64(int " fd ", void " dirp [. count "], size_t " count );
 .fi
-.PP
+.P
 .IR Note :
 glibc provides no wrapper for
 .BR getdents (),
 necessitating the use of
 .BR syscall (2).
-.PP
+.P
 .IR Note :
 There is no definition of
 .I struct linux_dirent
@@ -58,16 +58,16 @@ into the buffer pointed to by
 The argument
 .I count
 specifies the size of that buffer.
-.PP
+.P
 The
 .I linux_dirent
 structure is declared as follows:
-.PP
+.P
 .in +4n
 .EX
 struct linux_dirent {
     unsigned long  d_ino;     /* Inode number */
-    unsigned long  d_off;     /* Offset to next \fIlinux_dirent\fP */
+    unsigned long  d_off;     /* Not an offset; see below */
     unsigned short d_reclen;  /* Length of this \fIlinux_dirent\fP */
     char           d_name[];  /* Filename (null\-terminated) */
                       /* length is actually (d_reclen \- 2 \-
@@ -80,18 +80,22 @@ struct linux_dirent {
 }
 .EE
 .in
-.PP
+.P
 .I d_ino
 is an inode number.
 .I d_off
-is the distance from the start of the directory to the start of the next
-.IR linux_dirent .
+is a filesystem-specific value with no specific meaning to user space,
+though on older filesystems it used to be
+the distance from the start of the directory to the start of the next
+.IR linux_dirent ;
+see
+.BR readdir (3) .
 .I d_reclen
 is the size of this entire
 .IR linux_dirent .
 .I d_name
 is a null-terminated filename.
-.PP
+.P
 .I d_type
 is a byte at the end of the structure that indicates the file type.
 It contains one of the following values (defined in
@@ -120,7 +124,7 @@ This is a UNIX domain socket.
 .TP
 .B DT_UNKNOWN
 The file type is unknown.
-.PP
+.P
 The
 .I d_type
 field is implemented since Linux 2.6.4.
@@ -130,7 +134,7 @@ structure.
 Thus, on kernels up to and including Linux 2.6.3,
 attempting to access this field always provides the value 0
 .RB ( DT_UNKNOWN ).
-.PP
+.P
 Currently,
 .\" kernel 2.6.27
 .\" The same sentence is in readdir.2
@@ -155,19 +159,19 @@ In addition,
 supports an explicit
 .I d_type
 field.
-.PP
+.P
 The
 .BR getdents64 ()
 system call is like
 .BR getdents (),
 except that its second argument is a pointer to a buffer containing
 structures of the following type:
-.PP
+.P
 .in +4n
 .EX
 struct linux_dirent64 {
     ino64_t        d_ino;    /* 64\-bit inode number */
-    off64_t        d_off;    /* 64\-bit offset to next structure */
+    off64_t        d_off;    /* Not an offset; see getdents() */
     unsigned short d_reclen; /* Size of this dirent */
     unsigned char  d_type;   /* File type */
     char           d_name[]; /* Filename (null\-terminated) */
@@ -217,11 +221,11 @@ In that case you will need to define the
 or
 .I linux_dirent64
 structure yourself.
-.PP
+.P
 Probably, you want to use
 .BR readdir (3)
 instead of these system calls.
-.PP
+.P
 These calls supersede
 .BR readdir (2).
 .SH EXAMPLES
@@ -231,7 +235,7 @@ The program below demonstrates the use of
 .BR getdents ().
 The following output shows an example of what we see when running this
 program on an ext2 directory:
-.PP
+.P
 .in +4n
 .EX
 .RB "$" " ./a.out /testfs/"