summaryrefslogtreecommitdiffstats
path: root/man2/sendfile.2
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man2/sendfile.241
1 files changed, 25 insertions, 16 deletions
diff --git a/man2/sendfile.2 b/man2/sendfile.2
index d9c3451..e013fa6 100644
--- a/man2/sendfile.2
+++ b/man2/sendfile.2
@@ -11,7 +11,7 @@
.\"
.\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements
.\"
-.TH sendfile 2 2023-07-15 "Linux man-pages 6.05.01"
+.TH sendfile 2 2023-12-21 "Linux man-pages 6.7"
.SH NAME
sendfile \- transfer data between file descriptors
.SH LIBRARY
@@ -20,7 +20,7 @@ Standard C library
.SH SYNOPSIS
.nf
.B #include <sys/sendfile.h>
-.PP
+.P
.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", \
off_t *_Nullable " offset ,
.BI " size_t" " count" );
@@ -48,12 +48,12 @@ is more efficient than the combination of
and
.BR write (2),
which would require transferring data to and from user space.
-.PP
+.P
.I in_fd
should be a file descriptor opened for reading and
.I out_fd
should be a descriptor opened for writing.
-.PP
+.P
If
.I offset
is not NULL, then it points
@@ -74,29 +74,38 @@ does not modify the file offset of
otherwise the file offset is adjusted to reflect
the number of bytes read from
.IR in_fd .
-.PP
+.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.
-.PP
+.P
.I count
is the number of bytes to copy between the file descriptors.
-.PP
+.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).
-.PP
+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 is a regular file, then
+If it's seekable, then
.BR sendfile ()
changes the file offset appropriately.
.SH RETURN VALUE
@@ -108,7 +117,7 @@ Note that a successful call to
may write fewer bytes than requested;
the caller should be prepared to retry the call if there were unsent bytes.
See also NOTES.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
@@ -169,13 +178,13 @@ None.
.SH HISTORY
Linux 2.2,
glibc 2.1.
-.PP
+.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.
-.PP
+.P
The original Linux
.BR sendfile ()
system call was not designed to handle large file offsets.
@@ -193,7 +202,7 @@ 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.)
-.PP
+.P
If you plan to use
.BR sendfile ()
for sending files to a TCP socket, but need
@@ -203,7 +212,7 @@ it useful to employ the
option, described in
.BR tcp (7),
to minimize the number of packets and to tune performance.
-.PP
+.P
Applications may wish to fall back to
.BR read (2)
and
@@ -214,7 +223,7 @@ fails with
.B EINVAL
or
.BR ENOSYS .
-.PP
+.P
If
.I out_fd
refers to a socket or pipe with zero-copy support, callers must ensure the
@@ -223,7 +232,7 @@ transferred portions of the file referred to by
remain unmodified until the reader on the other end of
.I out_fd
has consumed the transferred data.
-.PP
+.P
The Linux-specific
.BR splice (2)
call supports transferring data between arbitrary file descriptors