table of contents
other sections
SENDFILE(2) | System Calls Manual | SENDFILE(2) |
NAME¶
sendfile
—
send a file to a socket
LIBRARY¶
Standard C Library (libc, -lc)SYNOPSIS¶
#include
<sys/types.h>
#include
<sys/socket.h>
#include
<sys/uio.h>
int
sendfile
(int
fd, int s,
off_t offset,
size_t nbytes,
struct sf_hdtr *hdtr,
off_t *sbytes, int
flags);
DESCRIPTION¶
Thesendfile
() system call sends a regular
file specified by descriptor fd out a stream
socket specified by descriptor s.
The offset argument specifies where to begin in
the file. Should offset fall beyond the end
of file, the system will return success and report 0 bytes sent as described
below. The nbytes argument specifies how many
bytes of the file should be sent, with 0 having the special meaning of send
until the end of file has been reached.
An optional header and/or trailer can be sent before and after the file data by
specifying a pointer to a struct sf_hdtr,
which has the following structure:
struct sf_hdtr { struct iovec *headers; /* pointer to header iovecs */ int hdr_cnt; /* number of header iovecs */ struct iovec *trailers; /* pointer to trailer iovecs */ int trl_cnt; /* number of trailer iovecs */ };
NULL
, point to arrays of
struct iovec structures. See the
writev
() system call for information on the
iovec structure. The number of iovecs in these arrays is specified by
hdr_cnt and
trl_cnt.
If non-NULL
, the system will write the total
number of bytes sent on the socket to the variable pointed to by
sbytes.
The flags argument is a bitmap of these values:
SF_NODISKIO
. This flag causes anysendfile
() call which would block on disk I/O to instead returnEBUSY
. Busy servers may benefit by transferring requests that would block to a separate I/O worker thread.SF_MNOWAIT
. Do not wait for some kernel resource to become available, in particular, mbuf and sf_buf. The flag does not make thesendfile
() syscall truly non-blocking, since other resources are still allocated in a blocking fashion.SF_SYNC
.sendfile
sleeps until the network stack no longer references the VM pages of the file, making subsequent modifications to it safe. Please note that this is not a guarantee that the data has actually been sent.
sendfile
() may send fewer bytes than
requested. In this case, the number of bytes successfully written is returned
in *sbytes (if specified), and the error
EAGAIN
is returned.
IMPLEMENTATION NOTES¶
The FreeBSD implementation ofsendfile
() is "zero-copy",
meaning that it has been optimized so that copying of the file data is
avoided.
TUNING¶
On some architectures, this system call internally uses a specialsendfile
() buffer
(struct sf_buf) to handle sending file data
to the client. If the sending socket is blocking, and there are not enough
sendfile
() buffers available,
sendfile
() will block and report a state of
“sfbufa
”. If the sending socket is
non-blocking and there are not enough
sendfile
() buffers available, the call will
block and wait for the necessary buffers to become available before finishing
the call.
The number of sf_buf's allocated should be
proportional to the number of nmbclusters used to send data to a client via
sendfile
(). Tune accordingly to avoid
blocking! Busy installations that make extensive use of
sendfile
() may want to increase these
values to be inline with their
kern.ipc.nmbclusters (see
tuning(7) for details).
The number of sendfile
() buffers available is
determined at boot time by either the
kern.ipc.nsfbufs
loader.conf(5) variable or the
NSFBUFS
kernel configuration tunable. The
number of sendfile
() buffers scales with
kern.maxusers. The
kern.ipc.nsfbufsused and
kern.ipc.nsfbufspeak read-only
sysctl(8) variables show current and peak
sendfile
() buffers usage respectively.
These values may also be viewed through
netstat
-m
.
If a value of zero is reported for
kern.ipc.nsfbufs, your architecture does not
need to use sendfile
() buffers because
their task can be efficiently performed by the generic virtual memory
structures.
RETURN VALUES¶
Thesendfile
() function returns the
value 0 if successful; otherwise the value -1 is returned and
the global variable errno is set to indicate
the error.
ERRORS¶
- [
EAGAIN
] - The socket is marked for non-blocking I/O and not all data was sent due to the socket buffer being filled. If specified, the number of bytes successfully sent will be returned in *sbytes.
- [
EBADF
] - The fd argument is not a valid file descriptor.
- [
EBADF
] - The s argument is not a valid socket descriptor.
- [
EBUSY
] - Completing the entire transfer would have required disk I/O, so it was
aborted. Partial data may have been sent. (This error can only occur when
SF_NODISKIO
is specified.) - [
EFAULT
] - An invalid address was specified for an argument.
- [
EINTR
] - A signal interrupted
sendfile
() before it could be completed. If specified, the number of bytes successfully sent will be returned in *sbytes. - [
EINVAL
] - The fd argument is not a regular file.
- [
EINVAL
] - The s argument is not a SOCK_STREAM type socket.
- [
EINVAL
] - The offset argument is negative.
- [
EIO
] - An error occurred while reading from fd.
- [
ENOBUFS
] - The system was unable to allocate an internal buffer.
- [
ENOTCONN
] - The s argument points to an unconnected socket.
- [
ENOTSOCK
] - The s argument is not a socket.
- [
EOPNOTSUPP
] - The file system for descriptor fd does
not support
sendfile
(). - [
EPIPE
] - The socket peer has closed the connection.
SEE ALSO¶
netstat(1), open(2), send(2), socket(2), writev(2), tuning(7) K. Elmeleegy, A. Chanda, A. L. Cox, and W. Zwaenepoel, A Portable Kernel Abstraction for Low-Overhead Ephemeral Mapping Management, The Proceedings of the 2005 USENIX Annual Technical Conference, pp 223-236, 2005.HISTORY¶
Thesendfile
() system call first appeared in
FreeBSD 3.0. This manual page first appeared in
FreeBSD 3.1.
AUTHORS¶
Thesendfile
() system call and this manual
page were written by David G. Lawrence
⟨dg@dglawrence.com⟩.January 7, 2010 | Debian |