|
Packit |
7cfc04 |
.\" This man page is Copyright (C) 1998 Pawel Krawczyk.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM_ONE_PARA)
|
|
Packit |
7cfc04 |
.\" Permission is granted to distribute possibly modified copies
|
|
Packit |
7cfc04 |
.\" of this page provided the header is included verbatim,
|
|
Packit |
7cfc04 |
.\" and in case of nontrivial modification author and date
|
|
Packit |
7cfc04 |
.\" of the modification is added to the header.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" $Id: sendfile.2,v 1.5 1999/05/18 11:54:11 freitag Exp $
|
|
Packit |
7cfc04 |
.\" 2000-11-19 bert hubert <ahu@ds9a.nl>: in_fd cannot be socket
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" 2004-12-17, mtk
|
|
Packit |
7cfc04 |
.\" updated description of in_fd and out_fd for 2.6
|
|
Packit |
7cfc04 |
.\" Various wording and formatting changes
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH SENDFILE 2 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
sendfile \- transfer data between file descriptors
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.B #include <sys/sendfile.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
|
|
Packit |
7cfc04 |
offset ", size_t" " count" );
|
|
Packit |
7cfc04 |
.\" The below is too ugly. Comments about glibc versions belong
|
|
Packit |
7cfc04 |
.\" in the notes, not in the header.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" .B #include <features.h>
|
|
Packit |
7cfc04 |
.\" .br
|
|
Packit |
7cfc04 |
.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
|
|
Packit |
7cfc04 |
.\" .br
|
|
Packit |
7cfc04 |
.\" .B #include <sys/sendfile.h>
|
|
Packit |
7cfc04 |
.\" .br
|
|
Packit |
7cfc04 |
.\" #else
|
|
Packit |
7cfc04 |
.\" .br
|
|
Packit |
7cfc04 |
.\" .B #include <sys/types.h>
|
|
Packit |
7cfc04 |
.\" .br
|
|
Packit |
7cfc04 |
.\" .B /* No system prototype before glibc 2.1. */
|
|
Packit |
7cfc04 |
.\" .br
|
|
Packit |
7cfc04 |
.\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
|
|
Packit |
7cfc04 |
.\" offset ", size_t" " count" )
|
|
Packit |
7cfc04 |
.\" .br
|
|
Packit |
7cfc04 |
.\" .B #endif
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
copies data between one file descriptor and another.
|
|
Packit |
7cfc04 |
Because this copying is done within the kernel,
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
is more efficient than the combination of
|
|
Packit |
7cfc04 |
.BR read (2)
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR write (2),
|
|
Packit |
7cfc04 |
which would require transferring data to and from user space.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.I in_fd
|
|
Packit |
7cfc04 |
should be a file descriptor opened for reading and
|
|
Packit |
7cfc04 |
.I out_fd
|
|
Packit |
7cfc04 |
should be a descriptor opened for writing.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.I offset
|
|
Packit |
7cfc04 |
is not NULL, then it points
|
|
Packit |
7cfc04 |
to a variable holding the file offset from which
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
will start reading data from
|
|
Packit |
7cfc04 |
.IR in_fd .
|
|
Packit |
7cfc04 |
When
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
returns, this variable
|
|
Packit |
7cfc04 |
will be set to the offset of the byte following the last byte that was read.
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.I offset
|
|
Packit |
7cfc04 |
is not NULL, then
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
does not modify the file offset of
|
|
Packit |
7cfc04 |
.IR in_fd ;
|
|
Packit |
7cfc04 |
otherwise the file offset is adjusted to reflect
|
|
Packit |
7cfc04 |
the number of bytes read from
|
|
Packit |
7cfc04 |
.IR in_fd .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.I offset
|
|
Packit |
7cfc04 |
is NULL, then data will be read from
|
|
Packit |
7cfc04 |
.IR in_fd
|
|
Packit |
7cfc04 |
starting at the file offset,
|
|
Packit |
7cfc04 |
and the file offset will be updated by the call.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.I count
|
|
Packit |
7cfc04 |
is the number of bytes to copy between the file descriptors.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR in_fd
|
|
Packit |
7cfc04 |
argument must correspond to a file which supports
|
|
Packit |
7cfc04 |
.BR mmap (2)-like
|
|
Packit |
7cfc04 |
operations
|
|
Packit |
7cfc04 |
(i.e., it cannot be a socket).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
In Linux kernels before 2.6.33,
|
|
Packit |
7cfc04 |
.I out_fd
|
|
Packit |
7cfc04 |
must refer to a socket.
|
|
Packit |
7cfc04 |
Since Linux 2.6.33 it can be any file.
|
|
Packit |
7cfc04 |
If it is a regular file, then
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
changes the file offset appropriately.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
If the transfer was successful, the number of bytes written to
|
|
Packit |
7cfc04 |
.I out_fd
|
|
Packit |
7cfc04 |
is returned.
|
|
Packit |
7cfc04 |
Note that a successful call to
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
may write fewer bytes than requested;
|
|
Packit |
7cfc04 |
the caller should be prepared to retry the call if there were unsent bytes.
|
|
Packit |
7cfc04 |
See also NOTES.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
On error, \-1 is returned, and
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
is set appropriately.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EAGAIN
|
|
Packit |
7cfc04 |
Nonblocking I/O has been selected using
|
|
Packit |
7cfc04 |
.B O_NONBLOCK
|
|
Packit |
7cfc04 |
and the write would block.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EBADF
|
|
Packit |
7cfc04 |
The input file was not opened for reading or the output file
|
|
Packit |
7cfc04 |
was not opened for writing.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EFAULT
|
|
Packit |
7cfc04 |
Bad address.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
Descriptor is not valid or locked, or an
|
|
Packit |
7cfc04 |
.BR mmap (2)-like
|
|
Packit |
7cfc04 |
operation is not available for
|
|
Packit |
7cfc04 |
.IR in_fd ,
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.I count
|
|
Packit |
7cfc04 |
is negative.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
.I out_fd
|
|
Packit |
7cfc04 |
has the
|
|
Packit |
7cfc04 |
.B O_APPEND
|
|
Packit |
7cfc04 |
flag set.
|
|
Packit |
7cfc04 |
This is not currently supported by
|
|
Packit |
7cfc04 |
.BR sendfile ().
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EIO
|
|
Packit |
7cfc04 |
Unspecified error while reading from
|
|
Packit |
7cfc04 |
.IR in_fd .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOMEM
|
|
Packit |
7cfc04 |
Insufficient memory to read from
|
|
Packit |
7cfc04 |
.IR in_fd .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EOVERFLOW
|
|
Packit |
7cfc04 |
.I count
|
|
Packit |
7cfc04 |
is too large, the operation would result in exceeding the maximum size of either
|
|
Packit |
7cfc04 |
the input file or the output file.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ESPIPE
|
|
Packit |
7cfc04 |
.I offset
|
|
Packit |
7cfc04 |
is not NULL but the input file is not
|
|
Packit |
7cfc04 |
.BR seek (2)-able.
|
|
Packit |
7cfc04 |
.SH VERSIONS
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
first appeared in Linux 2.2.
|
|
Packit |
7cfc04 |
The include file
|
|
Packit |
7cfc04 |
.I <sys/sendfile.h>
|
|
Packit |
7cfc04 |
is present since glibc 2.1.
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
Not specified in POSIX.1-2001, nor in other standards.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Other UNIX systems implement
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
with different semantics and prototypes.
|
|
Packit |
7cfc04 |
It should not be used in portable programs.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
will transfer at most 0x7ffff000 (2,147,479,552) bytes,
|
|
Packit |
7cfc04 |
returning the number of bytes actually transferred.
|
|
Packit |
7cfc04 |
.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
|
|
Packit |
7cfc04 |
(This is true on both 32-bit and 64-bit systems.)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If you plan to use
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
for sending files to a TCP socket, but need
|
|
Packit |
7cfc04 |
to send some header data in front of the file contents, you will find
|
|
Packit |
7cfc04 |
it useful to employ the
|
|
Packit |
7cfc04 |
.B TCP_CORK
|
|
Packit |
7cfc04 |
option, described in
|
|
Packit |
7cfc04 |
.BR tcp (7),
|
|
Packit |
7cfc04 |
to minimize the number of packets and to tune performance.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
In Linux 2.4 and earlier,
|
|
Packit |
7cfc04 |
.I out_fd
|
|
Packit |
7cfc04 |
could also refer to a regular file;
|
|
Packit |
7cfc04 |
this possibility went away in the Linux 2.6.x kernel series,
|
|
Packit |
7cfc04 |
but was restored in Linux 2.6.33.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The original Linux
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
system call was not designed to handle large file offsets.
|
|
Packit |
7cfc04 |
Consequently, Linux 2.4 added
|
|
Packit |
7cfc04 |
.BR sendfile64 (),
|
|
Packit |
7cfc04 |
with a wider type for the
|
|
Packit |
7cfc04 |
.I offset
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
The glibc
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
wrapper function transparently deals with the kernel differences.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Applications may wish to fall back to
|
|
Packit |
7cfc04 |
.BR read (2)/ write (2)
|
|
Packit |
7cfc04 |
in the case where
|
|
Packit |
7cfc04 |
.BR sendfile ()
|
|
Packit |
7cfc04 |
fails with
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR ENOSYS .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.I out_fd
|
|
Packit |
7cfc04 |
refers to a socket or pipe with zero-copy support, callers must ensure the
|
|
Packit |
7cfc04 |
transferred portions of the file referred to by
|
|
Packit |
7cfc04 |
.I in_fd
|
|
Packit |
7cfc04 |
remain unmodified until the reader on the other end of
|
|
Packit |
7cfc04 |
.I out_fd
|
|
Packit |
7cfc04 |
has consumed the transferred data.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The Linux-specific
|
|
Packit |
7cfc04 |
.BR splice (2)
|
|
Packit |
7cfc04 |
call supports transferring data between arbitrary file descriptors
|
|
Packit |
7cfc04 |
provided one (or both) of them is a pipe.
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR copy_file_range (2),
|
|
Packit |
7cfc04 |
.BR mmap (2),
|
|
Packit |
7cfc04 |
.BR open (2),
|
|
Packit |
7cfc04 |
.BR socket (2),
|
|
Packit |
7cfc04 |
.BR splice (2)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|