Merging upstream version 6.8.

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

1 files changed, 245 insertions, 0 deletions

diff --git a/man/man2/read.2 b/man/man2/read.2
new file mode 100644
index 0000000..dae8942
--- /dev/null
+++ b/man/man2/read.2
@@ -0,0 +1,245 @@
+.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
+.\"  and Copyright (C) 1993 Michael Haardt, Ian Jackson.
+.\"  and Copyright (C) 2009-2015 Michael Kerrisk, <mtk.manpages.gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Sat Jul 24 00:06:00 1993 by Rik Faith <faith@cs.unc.edu>
+.\" Modified Wed Jan 17 16:02:32 1996 by Michael Haardt
+.\"   <michael@cantor.informatik.rwth-aachen.de>
+.\" Modified Thu Apr 11 19:26:35 1996 by Andries Brouwer <aeb@cwi.nl>
+.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer <aeb@cwi.nl>
+.\" Modified Fri Jan 31 16:47:33 1997 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified Sat Jul 12 20:45:39 1997 by Michael Haardt
+.\"   <michael@cantor.informatik.rwth-aachen.de>
+.\"
+.TH read 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+read \- read from a file descriptor
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "ssize_t read(int " fd ", void " buf [. count "], size_t " count );
+.fi
+.SH DESCRIPTION
+.BR read ()
+attempts to read up to
+.I count
+bytes from file descriptor
+.I fd
+into the buffer starting at
+.IR buf .
+.P
+On files that support seeking,
+the read operation commences at the file offset,
+and the file offset is incremented by the number of bytes read.
+If the file offset is at or past the end of file,
+no bytes are read, and
+.BR read ()
+returns zero.
+.P
+If
+.I count
+is zero,
+.BR read ()
+.I may
+detect the errors described below.
+In the absence of any errors,
+or if
+.BR read ()
+does not check for errors, a
+.BR read ()
+with a
+.I count
+of 0 returns zero and has no other effects.
+.P
+According to POSIX.1, if
+.I count
+is greater than
+.BR SSIZE_MAX ,
+the result is implementation-defined;
+see NOTES for the upper limit on Linux.
+.SH RETURN VALUE
+On success, the number of bytes read is returned (zero indicates end of
+file), and the file position is advanced by this number.
+It is not an error if this number is smaller than the number of bytes
+requested; this may happen for example because fewer bytes are actually
+available right now (maybe because we were close to end-of-file, or
+because we are reading from a pipe, or from a terminal), or because
+.BR read ()
+was interrupted by a signal.
+See also NOTES.
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+In this case, it is left unspecified whether
+the file position (if any) changes.
+.SH ERRORS
+.TP
+.B EAGAIN
+The file descriptor
+.I fd
+refers to a file other than a socket and has been marked nonblocking
+.RB ( O_NONBLOCK ),
+and the read would block.
+See
+.BR open (2)
+for further details on the
+.B O_NONBLOCK
+flag.
+.TP
+.BR EAGAIN " or " EWOULDBLOCK
+.\" Actually EAGAIN on Linux
+The file descriptor
+.I fd
+refers to a socket and has been marked nonblocking
+.RB ( O_NONBLOCK ),
+and the read would block.
+POSIX.1-2001 allows either error to be returned for this case,
+and does not require these constants to have the same value,
+so a portable application should check for both possibilities.
+.TP
+.B EBADF
+.I fd
+is not a valid file descriptor or is not open for reading.
+.TP
+.B EFAULT
+.I buf
+is outside your accessible address space.
+.TP
+.B EINTR
+The call was interrupted by a signal before any data was read; see
+.BR signal (7).
+.TP
+.B EINVAL
+.I fd
+is attached to an object which is unsuitable for reading;
+or the file was opened with the
+.B O_DIRECT
+flag, and either the address specified in
+.IR buf ,
+the value specified in
+.IR count ,
+or the file offset is not suitably aligned.
+.TP
+.B EINVAL
+.I fd
+was created via a call to
+.BR timerfd_create (2)
+and the wrong size buffer was given to
+.BR read ();
+see
+.BR timerfd_create (2)
+for further information.
+.TP
+.B EIO
+I/O error.
+This will happen for example when the process is in a
+background process group, tries to read from its controlling terminal,
+and either it is ignoring or blocking
+.B SIGTTIN
+or its process group
+is orphaned.
+It may also occur when there is a low-level I/O error
+while reading from a disk or tape.
+A further possible cause of
+.B EIO
+on networked filesystems is when an advisory lock had been taken
+out on the file descriptor and this lock has been lost.
+See the
+.I "Lost locks"
+section of
+.BR fcntl (2)
+for further details.
+.TP
+.B EISDIR
+.I fd
+refers to a directory.
+.P
+Other errors may occur, depending on the object connected to
+.IR fd .
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+SVr4, 4.3BSD, POSIX.1-2001.
+.SH NOTES
+On Linux,
+.BR read ()
+(and similar system calls) will transfer at most
+0x7ffff000 (2,147,479,552) bytes,
+returning the number of bytes actually transferred.
+.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
+(This is true on both 32-bit and 64-bit systems.)
+.P
+On NFS filesystems, reading small amounts of data will update the
+timestamp only the first time, subsequent calls may not do so.
+This is caused
+by client side attribute caching, because most if not all NFS clients
+leave
+.I st_atime
+(last file access time)
+updates to the server, and client side reads satisfied from the
+client's cache will not cause
+.I st_atime
+updates on the server as there are no
+server-side reads.
+UNIX semantics can be obtained by disabling client-side attribute caching,
+but in most situations this will substantially
+increase server load and decrease performance.
+.SH BUGS
+According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
+("Thread Interactions with Regular File Operations"):
+.P
+.RS 4
+All of the following functions shall be atomic with respect to
+each other in the effects specified in POSIX.1-2008 when they
+operate on regular files or symbolic links: ...
+.RE
+.P
+Among the APIs subsequently listed are
+.BR read ()
+and
+.BR readv (2).
+And among the effects that should be atomic across threads (and processes)
+are updates of the file offset.
+However, before Linux 3.14,
+this was not the case: if two processes that share
+an open file description (see
+.BR open (2))
+perform a
+.BR read ()
+(or
+.BR readv (2))
+at the same time, then the I/O operations were not atomic
+with respect to updating the file offset,
+with the result that the reads in the two processes
+might (incorrectly) overlap in the blocks of data that they obtained.
+This problem was fixed in Linux 3.14.
+.\" http://thread.gmane.org/gmane.linux.kernel/1649458
+.\"    From: Michael Kerrisk (man-pages <mtk.manpages <at> gmail.com>
+.\"    Subject: Update of file offset on write() etc. is non-atomic with I/O
+.\"    Date: 2014-02-17 15:41:37 GMT
+.\"    Newsgroups: gmane.linux.kernel, gmane.linux.file-systems
+.\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4
+.\"    Author: Linus Torvalds <torvalds@linux-foundation.org>
+.\"    Date:   Mon Mar 3 09:36:58 2014 -0800
+.\"
+.\"        vfs: atomic f_pos accesses as per POSIX
+.SH SEE ALSO
+.BR close (2),
+.BR fcntl (2),
+.BR ioctl (2),
+.BR lseek (2),
+.BR open (2),
+.BR pread (2),
+.BR readdir (2),
+.BR readlink (2),
+.BR readv (2),
+.BR select (2),
+.BR write (2),
+.BR fread (3)