From 3af6d22bb3850ab2bac67287e3a3d3b0e32868e5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:41:07 +0200 Subject: Merging upstream version 6.7. Signed-off-by: Daniel Baumann --- man2/getdents.2 | 46 +++++++++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 21 deletions(-) (limited to 'man2/getdents.2') 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 .\" -.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 " " /* Definition of " SYS_* " constants */" .B #include -.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 -.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/" -- cgit v1.2.3