freebsd/lib/libc/sys/sendfile.2

.\" Copyright (c) 1998, David Greenman
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice unmodified, this list of conditions, and the following
.\"    disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 5, 1998
.Dt SENDFILE 2
.Os
.Sh NAME
.Nm sendfile
.Nd send a file to a socket
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Fd #include <sys/uio.h>
.Ft int
.Fn sendfile "int fd" "int s" "off_t offset" "size_t nbytes" "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags"
.Sh DESCRIPTION
.Fn Sendfile
sends a regular file specified by descriptor
.Fa fd
out a stream socket specified by descriptor
.Fa s .
.Pp
The
.Fa offset
argument specifies where to begin in the file.
The
.Fa 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.
.Pp
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:
.Pp
.Bd -literal -offset indent -compact
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 */
};
.Ed
.Pp
The
.Fa headers
and
.Fa trailers
pointers, if non-NULL, point to arrays of struct iovec structures.
See the
.Fn writev
system call for information on the iovec structure.
The number of iovecs in these
arrays is specified by
.Fa hdr_cnt
and
.Fa trl_cnt .
.Pp
If non-NULL, the system will write the total number of bytes sent on the socket to the
variable pointed to by
.Fa sbytes .
.Pp
The
.Fa flags
argument is currently undefined and should be specified as 0.
.Pp
When using a socket marked for non-blocking I/O,
.Fn sendfile
may send fewer bytes than requested.
In this case, the number of bytes successfully
written is returned in
.Fa *sbytes
(if specified),
and the error
.Er EAGAIN
is returned.
.Sh IMPLEMENTATION NOTES
The
.Fx
implementation of
.Fn sendfile
is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided.
.Pp
In the non-threaded library
.Fn sendfile
is implemented as the
.Va sendfile
syscall.
.Pp
In the threaded library, the
.Va sendfile
syscall is assembled to
.Fn _thread_sys_sendfile
and
.Fn sendfile
is implemented as a function which locks
.Fa fd
for reading and
.Fa s
for writing, then calls
.Fn _thread_sys_sendfile .
If the call to
.Fn _thread_sys_sendfile
would block, a context switch is performed.  Before returning,
.Fn sendfile
unlocks
.Fa fd
and
.Fa s .
.Sh RETURN VALUES
.Rv -std sendfile
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EBADF
.Fa fd
is not a valid file descriptor.
.It Bq Er EBADF
.Fa s
is not a valid socket descriptor.
.It Bq Er ENOTSOCK
.Fa s
is not a socket.
.It Bq Er EINVAL
.Fa fd
is not a regular file.
.It Bq Er EINVAL
.Fa s
is not a SOCK_STREAM type socket.
.It Bq Er EINVAL
.Fa offset
is negative or out of range.
.It Bq Er ENOTCONN
.Fa s
points to an unconnected socket.
.It Bq Er EPIPE
The socket peer has closed the connection.
.It Bq Er EIO
An error occurred while reading from
.Fa fd .
.It Bq Er EFAULT
An invalid address was specified for a parameter.
.It Bq Er 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
.Fa *sbytes .
.El
.Sh SEE ALSO
.Xr open 2 ,
.Xr send 2 ,
.Xr socket 2 ,
.Xr writev 2
.Sh HISTORY
.Fn sendfile
first appeared in
.Fx 3.0 .
This manual page first appeared in
.Fx 3.1 .
.Sh AUTHORS
.Fn sendfile
and this manual page were written by
.An David Greenman Aq dg@root.com .