Adding upstream version 6.8.upstream/6.8upstream

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

1 files changed, 245 insertions, 0 deletions

diff --git a/man/man2/sendfile.2 b/man/man2/sendfile.2
new file mode 100644
index 0000000..cc691fc
--- /dev/null
+++ b/man/man2/sendfile.2
@@ -0,0 +1,245 @@
+.\" SPDX-License-Identifier: Linux-man-pages-1-para
+.\"
+.\" This man page is Copyright (C) 1998 Pawel Krawczyk.
+.\"
+.\" $Id: sendfile.2,v 1.5 1999/05/18 11:54:11 freitag Exp $
+.\" 2000-11-19 bert hubert <ahu@ds9a.nl>: in_fd cannot be socket
+.\"
+.\" 2004-12-17, mtk
+.\"	updated description of in_fd and out_fd for 2.6
+.\"	Various wording and formatting changes
+.\"
+.\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements
+.\"
+.TH sendfile 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+sendfile \- transfer data between file descriptors
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/sendfile.h>
+.P
+.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", \
+off_t *_Nullable " offset ,
+.BI "                 size_t" " count" );
+.\" The below is too ugly. Comments about glibc versions belong
+.\" in the notes, not in the header.
+.\"
+.\" .B #include <features.h>
+.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
+.\" .B #include <sys/sendfile.h>
+.\" #else
+.\" .B #include <sys/types.h>
+.\" .B /* No system prototype before glibc 2.1. */
+.\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
+.\"                       offset ", size_t" " count" )
+.\" .B #endif
+.\"
+.fi
+.SH DESCRIPTION
+.BR sendfile ()
+copies data between one file descriptor and another.
+Because this copying is done within the kernel,
+.BR sendfile ()
+is more efficient than the combination of
+.BR read (2)
+and
+.BR write (2),
+which would require transferring data to and from user space.
+.P
+.I in_fd
+should be a file descriptor opened for reading and
+.I out_fd
+should be a descriptor opened for writing.
+.P
+If
+.I offset
+is not NULL, then it points
+to a variable holding the file offset from which
+.BR sendfile ()
+will start reading data from
+.IR in_fd .
+When
+.BR sendfile ()
+returns, this variable
+will be set to the offset of the byte following the last byte that was read.
+If
+.I offset
+is not NULL, then
+.BR sendfile ()
+does not modify the file offset of
+.IR in_fd ;
+otherwise the file offset is adjusted to reflect
+the number of bytes read from
+.IR in_fd .
+.P
+If
+.I offset
+is NULL, then data will be read from
+.I in_fd
+starting at the file offset,
+and the file offset will be updated by the call.
+.P
+.I count
+is the number of bytes to copy between the file descriptors.
+.P
+The
+.I in_fd
+argument must correspond to a file which supports
+.BR mmap (2)-like
+operations
+(i.e., it cannot be a socket).
+Except since Linux 5.12
+.\" commit b964bf53e540262f2d12672b3cca10842c0172e7
+and if
+.I out_fd
+is a pipe, in which case
+.BR sendfile ()
+desugars to a
+.BR splice (2)
+and its restrictions apply.
+.P
+Before Linux 2.6.33,
+.I out_fd
+must refer to a socket.
+Since Linux 2.6.33 it can be any file.
+If it's seekable, then
+.BR sendfile ()
+changes the file offset appropriately.
+.SH RETURN VALUE
+If the transfer was successful, the number of bytes written to
+.I out_fd
+is returned.
+Note that a successful call to
+.BR sendfile ()
+may write fewer bytes than requested;
+the caller should be prepared to retry the call if there were unsent bytes.
+See also NOTES.
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+Nonblocking I/O has been selected using
+.B O_NONBLOCK
+and the write would block.
+.TP
+.B EBADF
+The input file was not opened for reading or the output file
+was not opened for writing.
+.TP
+.B EFAULT
+Bad address.
+.TP
+.B EINVAL
+Descriptor is not valid or locked, or an
+.BR mmap (2)-like
+operation is not available for
+.IR in_fd ,
+or
+.I count
+is negative.
+.TP
+.B EINVAL
+.I out_fd
+has the
+.B O_APPEND
+flag set.
+This is not currently supported by
+.BR sendfile ().
+.TP
+.B EIO
+Unspecified error while reading from
+.IR in_fd .
+.TP
+.B ENOMEM
+Insufficient memory to read from
+.IR in_fd .
+.TP
+.B EOVERFLOW
+.I count
+is too large, the operation would result in exceeding the maximum size of either
+the input file or the output file.
+.TP
+.B ESPIPE
+.I offset
+is not NULL but the input file is not seekable.
+.SH VERSIONS
+Other UNIX systems implement
+.BR sendfile ()
+with different semantics and prototypes.
+It should not be used in portable programs.
+.SH STANDARDS
+None.
+.SH HISTORY
+Linux 2.2,
+glibc 2.1.
+.P
+In Linux 2.4 and earlier,
+.I out_fd
+could also refer to a regular file;
+this possibility went away in the Linux 2.6.x kernel series,
+but was restored in Linux 2.6.33.
+.P
+The original Linux
+.BR sendfile ()
+system call was not designed to handle large file offsets.
+Consequently, Linux 2.4 added
+.BR sendfile64 (),
+with a wider type for the
+.I offset
+argument.
+The glibc
+.BR sendfile ()
+wrapper function transparently deals with the kernel differences.
+.SH NOTES
+.BR sendfile ()
+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
+If you plan to use
+.BR sendfile ()
+for sending files to a TCP socket, but need
+to send some header data in front of the file contents, you will find
+it useful to employ the
+.B TCP_CORK
+option, described in
+.BR tcp (7),
+to minimize the number of packets and to tune performance.
+.P
+Applications may wish to fall back to
+.BR read (2)
+and
+.BR write (2)
+in the case where
+.BR sendfile ()
+fails with
+.B EINVAL
+or
+.BR ENOSYS .
+.P
+If
+.I out_fd
+refers to a socket or pipe with zero-copy support, callers must ensure the
+transferred portions of the file referred to by
+.I in_fd
+remain unmodified until the reader on the other end of
+.I out_fd
+has consumed the transferred data.
+.P
+The Linux-specific
+.BR splice (2)
+call supports transferring data between arbitrary file descriptors
+provided one (or both) of them is a pipe.
+.SH SEE ALSO
+.BR copy_file_range (2),
+.BR mmap (2),
+.BR open (2),
+.BR socket (2),
+.BR splice (2)