Merging upstream version 6.8.

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

1 files changed, 304 insertions, 0 deletions

diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
new file mode 100644
index 0000000..887dde8
--- /dev/null
+++ b/man/man3/readdir.3
@@ -0,0 +1,304 @@
+'\" t
+.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
+.\" and Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\"     Linux libc source code
+.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\"     386BSD man pages
+.\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl)
+.\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl)
+.\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>, mtk:
+.\"     Rework discussion of nonstandard structure fields.
+.\"
+.TH readdir 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+readdir \- read a directory
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <dirent.h>
+.P
+.BI "struct dirent *readdir(DIR *" dirp );
+.fi
+.SH DESCRIPTION
+The
+.BR readdir ()
+function returns a pointer to a \fIdirent\fP structure
+representing the next directory entry in the directory stream pointed
+to by \fIdirp\fP.
+It returns NULL on reaching the end of the directory stream or if
+an error occurred.
+.P
+In the glibc implementation, the
+.I dirent
+structure is defined as follows:
+.P
+.in +4n
+.EX
+struct dirent {
+    ino_t          d_ino;       /* Inode number */
+    off_t          d_off;       /* Not an offset; see below */
+    unsigned short d_reclen;    /* Length of this record */
+    unsigned char  d_type;      /* Type of file; not supported
+                                   by all filesystem types */
+    char           d_name[256]; /* Null\-terminated filename */
+};
+.EE
+.in
+.P
+The only fields in the
+.I dirent
+structure that are mandated by POSIX.1 are
+.I d_name
+and
+.IR d_ino .
+The other fields are unstandardized, and not present on all systems;
+see NOTES below for some further details.
+.P
+The fields of the
+.I dirent
+structure are as follows:
+.TP
+.I d_ino
+This is the inode number of the file.
+.TP
+.I d_off
+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).
+.TP
+.I d_reclen
+This is the size (in bytes) of the returned record.
+This may not match the size of the structure definition shown above;
+see NOTES.
+.TP
+.I d_type
+This field contains a value indicating the file type,
+making it possible to avoid the expense of calling
+.BR lstat (2)
+if further actions depend on the type of the file.
+.IP
+When a suitable feature test macro is defined
+.RB ( _DEFAULT_SOURCE
+since glibc 2.19, or
+.B _BSD_SOURCE
+on glibc 2.19 and earlier),
+glibc defines the following macro constants for the value returned in
+.IR d_type :
+.RS
+.TP 12
+.B DT_BLK
+This is a block device.
+.TP
+.B DT_CHR
+This is a character device.
+.TP
+.B DT_DIR
+This is a directory.
+.TP
+.B DT_FIFO
+This is a named pipe (FIFO).
+.TP
+.B DT_LNK
+This is a symbolic link.
+.TP
+.B DT_REG
+This is a regular file.
+.TP
+.B DT_SOCK
+This is a UNIX domain socket.
+.TP
+.B DT_UNKNOWN
+The file type could not be determined.
+.RE
+.IP
+Currently,
+.\" kernel 2.6.27
+.\" The same sentence is in getdents.2
+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 .
+.TP
+.I d_name
+This field contains the null terminated filename.
+.IR "See NOTES" .
+.P
+The data returned by
+.BR readdir ()
+may be overwritten by subsequent calls to
+.BR readdir ()
+for the same directory stream.
+.SH RETURN VALUE
+On success,
+.BR readdir ()
+returns a pointer to a
+.I dirent
+structure.
+(This structure may be statically allocated; do not attempt to
+.BR free (3)
+it.)
+.P
+If the end of the directory stream is reached, NULL is returned and
+.I errno
+is not changed.
+If an error occurs, NULL is returned and
+.I errno
+is set to indicate the error.
+To distinguish end of stream from an error, set
+.I errno
+to zero before calling
+.BR readdir ()
+and then check the value of
+.I errno
+if NULL is returned.
+.SH ERRORS
+.TP
+.B EBADF
+Invalid directory stream descriptor \fIdirp\fP.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR readdir ()
+T}	Thread safety	MT-Unsafe race:dirstream
+.TE
+.P
+In the current POSIX.1 specification (POSIX.1-2008),
+.BR readdir ()
+is not required to be thread-safe.
+However, in modern implementations (including the glibc implementation),
+concurrent calls to
+.BR readdir ()
+that specify different directory streams are thread-safe.
+In cases where multiple threads must read from the same directory stream,
+using
+.BR readdir ()
+with external synchronization is still preferable to the use of the deprecated
+.BR readdir_r (3)
+function.
+It is expected that a future version of POSIX.1
+.\" FIXME .
+.\" http://www.austingroupbugs.net/view.php?id=696
+will require that
+.BR readdir ()
+be thread-safe when concurrently employed on different directory streams.
+.SH VERSIONS
+Only the fields
+.I d_name
+and (as an XSI extension)
+.I d_ino
+are specified in POSIX.1.
+.\" POSIX.1-2001, POSIX.1-2008
+Other than Linux, the
+.I d_type
+field is available mainly only on BSD systems.
+The remaining fields are available on many, but not all systems.
+Under glibc,
+programs can check for the availability of the fields not defined
+in POSIX.1 by testing whether the macros
+.BR _DIRENT_HAVE_D_NAMLEN ,
+.BR _DIRENT_HAVE_D_RECLEN ,
+.BR _DIRENT_HAVE_D_OFF ,
+or
+.B _DIRENT_HAVE_D_TYPE
+are defined.
+.\"
+.SS The d_name field
+The
+.I dirent
+structure definition shown above is taken from the glibc headers,
+and shows the
+.I d_name
+field with a fixed size.
+.P
+.IR Warning :
+applications should avoid any dependence on the size of the
+.I d_name
+field.
+POSIX defines it as
+.IR "char\ d_name[]",
+a character array of unspecified size, with at most
+.B NAME_MAX
+characters preceding the terminating null byte (\[aq]\e0\[aq]).
+.P
+POSIX.1 explicitly notes that this field should not be used as an lvalue.
+The standard also notes that the use of
+.I sizeof(d_name)
+is incorrect; use
+.I strlen(d_name)
+instead.
+(On some systems, this field is defined as
+.IR char\~d_name[1] !)
+By implication, the use
+.I sizeof(struct dirent)
+to capture the size of the record including the size of
+.I d_name
+is also incorrect.
+.P
+Note that while the call
+.P
+.in +4n
+.EX
+fpathconf(fd, _PC_NAME_MAX)
+.EE
+.in
+.P
+returns the value 255 for most filesystems,
+on some filesystems (e.g., CIFS, Windows SMB servers),
+the null-terminated filename that is (correctly) returned in
+.I d_name
+can actually exceed this size.
+In such cases, the
+.I d_reclen
+field will contain a value that exceeds the size of the glibc
+.I dirent
+structure shown above.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4, 4.3BSD.
+.SH NOTES
+A directory stream is opened using
+.BR opendir (3).
+.P
+The order in which filenames are read by successive calls to
+.BR readdir ()
+depends on the filesystem implementation;
+it is unlikely that the names will be sorted in any fashion.
+.SH SEE ALSO
+.BR getdents (2),
+.BR read (2),
+.BR closedir (3),
+.BR dirfd (3),
+.BR ftw (3),
+.BR offsetof (3),
+.BR opendir (3),
+.BR readdir_r (3),
+.BR rewinddir (3),
+.BR scandir (3),
+.BR seekdir (3),
+.BR telldir (3)