mirror of https://github.com/mkerrisk/man-pages
245 lines
5.8 KiB
Groff
245 lines
5.8 KiB
Groff
.\" This man page is Copyright (C) 1998 Pawel Krawczyk.
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM_ONE_PARA)
|
|
.\" Permission is granted to distribute possibly modified copies
|
|
.\" of this page provided the header is included verbatim,
|
|
.\" and in case of nontrivial modification author and date
|
|
.\" of the modification is added to the header.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" $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 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
sendfile \- transfer data between file descriptors
|
|
.SH SYNOPSIS
|
|
.B #include <sys/sendfile.h>
|
|
.PP
|
|
.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
|
|
offset ", size_t" " count" );
|
|
.\" The below is too ugly. Comments about glibc versions belong
|
|
.\" in the notes, not in the header.
|
|
.\"
|
|
.\" .B #include <features.h>
|
|
.\" .br
|
|
.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
|
|
.\" .br
|
|
.\" .B #include <sys/sendfile.h>
|
|
.\" .br
|
|
.\" #else
|
|
.\" .br
|
|
.\" .B #include <sys/types.h>
|
|
.\" .br
|
|
.\" .B /* No system prototype before glibc 2.1. */
|
|
.\" .br
|
|
.\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
|
|
.\" offset ", size_t" " count" )
|
|
.\" .br
|
|
.\" .B #endif
|
|
.\"
|
|
.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.
|
|
.PP
|
|
.I in_fd
|
|
should be a file descriptor opened for reading and
|
|
.I out_fd
|
|
should be a descriptor opened for writing.
|
|
.PP
|
|
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 .
|
|
.PP
|
|
If
|
|
.I offset
|
|
is NULL, then data will be read from
|
|
.IR in_fd
|
|
starting at the file offset,
|
|
and the file offset will be updated by the call.
|
|
.PP
|
|
.I count
|
|
is the number of bytes to copy between the file descriptors.
|
|
.PP
|
|
The
|
|
.IR in_fd
|
|
argument must correspond to a file which supports
|
|
.BR mmap (2)-like
|
|
operations
|
|
(i.e., it cannot be a socket).
|
|
.PP
|
|
In Linux kernels before 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
|
|
.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.
|
|
.PP
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.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
|
|
.BR seek (2)-able.
|
|
.SH VERSIONS
|
|
.BR sendfile ()
|
|
first appeared in Linux 2.2.
|
|
The include file
|
|
.I <sys/sendfile.h>
|
|
is present since glibc 2.1.
|
|
.SH CONFORMING TO
|
|
Not specified in POSIX.1-2001, nor in other standards.
|
|
.PP
|
|
Other UNIX systems implement
|
|
.BR sendfile ()
|
|
with different semantics and prototypes.
|
|
It should not be used in portable programs.
|
|
.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.)
|
|
.PP
|
|
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.
|
|
.PP
|
|
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
|
|
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.
|
|
.PP
|
|
Applications may wish to fall back to
|
|
.BR read (2)/ write (2)
|
|
in the case where
|
|
.BR sendfile ()
|
|
fails with
|
|
.B EINVAL
|
|
or
|
|
.BR ENOSYS .
|
|
.PP
|
|
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.
|
|
.PP
|
|
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)
|