mirror of https://github.com/mkerrisk/man-pages
153 lines
3.8 KiB
Groff
153 lines
3.8 KiB
Groff
.\" This man page is Copyright (C) 1998 Pawel Krawczyk.
|
|
.\" 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.
|
|
.\" $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 2004-12-17 "Linux Man Page" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
sendfile \- transfer data between file descriptors
|
|
.SH SYNOPSIS
|
|
.B #include <sys/sendfile.h>
|
|
.sp
|
|
.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.
|
|
|
|
.I in_fd
|
|
should be a file descriptor opened for reading and
|
|
.I out_fd
|
|
should be a descriptor opened for writing.
|
|
|
|
.I offset
|
|
is a pointer 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.
|
|
.BR sendfile ()
|
|
does not modify the current file offset of
|
|
.IR in_fd .
|
|
|
|
.I count
|
|
is the number of bytes to copy between the file descriptors.
|
|
|
|
Presently (Linux 2.6.9):
|
|
.IR in_fd ,
|
|
must correspond to a file which supports
|
|
.BR mmap ()-like
|
|
operations
|
|
(i.e., it cannot be a socket);
|
|
and
|
|
.I out_fd
|
|
must refer to a socket.
|
|
|
|
Applications may wish to fall back to
|
|
.BR read (2)/ write (2)
|
|
in the case where
|
|
.BR sendfile ()
|
|
fails with EINVAL or ENOSYS.
|
|
.SH NOTES
|
|
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.
|
|
|
|
In Linux 2.4 and earlier,
|
|
.I out_fd
|
|
could refer to a regular file, and
|
|
.BR sendfile ()
|
|
changed the current offset of that file.
|
|
.SH "RETURN VALUE"
|
|
If the transfer was successful, the number of bytes written to
|
|
.I out_fd
|
|
is returned. On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EAGAIN
|
|
Non-blocking 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 ()-like
|
|
operation is not available for
|
|
.IR in_fd .
|
|
.TP
|
|
.B EIO
|
|
Unspecified error while reading from
|
|
.IR in_fd .
|
|
.TP
|
|
.B ENOMEM
|
|
Insufficient memory to read from
|
|
.IR in_fd .
|
|
.SH VERSIONS
|
|
.BR sendfile ()
|
|
is a new feature in Linux 2.2.
|
|
The include file <sys/sendfile.h> is present since glibc2.1.
|
|
|
|
Other Unixes implement
|
|
.BR sendfile ()
|
|
with different semantics and prototypes. It should
|
|
not be used in portable programs.
|
|
.SH "SEE ALSO"
|
|
.BR open (2),
|
|
.BR mmap (2),
|
|
.BR socket (2)
|