1.\" Copyright (c) 1998, David Greenman 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice unmodified, this list of conditions, and the following 9.\" disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD: src/lib/libc/sys/sendfile.2,v 1.6.2.6 2001/12/14 18:34:01 ru Exp $ 27.\" $DragonFly: src/lib/libc/sys/sendfile.2,v 1.3 2004/03/11 12:28:51 hmp Exp $ 28.\" 29.Dd November 5, 1998 30.Dt SENDFILE 2 31.Os 32.Sh NAME 33.Nm sendfile 34.Nd send a file to a socket 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In sys/types.h 39.In sys/socket.h 40.In sys/uio.h 41.Ft int 42.Fn sendfile "int fd" "int s" "off_t offset" "size_t nbytes" "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags" 43.Sh DESCRIPTION 44.Fn Sendfile 45sends a regular file specified by descriptor 46.Fa fd 47out a stream socket specified by descriptor 48.Fa s . 49.Pp 50The 51.Fa offset 52argument specifies where to begin in the file. 53The 54.Fa nbytes 55argument specifies how many bytes of the file should be sent, with 0 having the special 56meaning of send until the end of file has been reached. 57.Pp 58An optional header and/or trailer can be sent before and after the file data by specifying 59a pointer to a struct sf_hdtr, which has the following structure: 60.Pp 61.Bd -literal -offset indent -compact 62struct sf_hdtr { 63 struct iovec *headers; /* pointer to header iovecs */ 64 int hdr_cnt; /* number of header iovecs */ 65 struct iovec *trailers; /* pointer to trailer iovecs */ 66 int trl_cnt; /* number of trailer iovecs */ 67}; 68.Ed 69.Pp 70The 71.Fa headers 72and 73.Fa trailers 74pointers, if non-NULL, point to arrays of struct iovec structures. 75See the 76.Fn writev 77system call for information on the iovec structure. 78The number of iovecs in these 79arrays is specified by 80.Fa hdr_cnt 81and 82.Fa trl_cnt . 83.Pp 84If non-NULL, the system will write the total number of bytes sent on the socket to the 85variable pointed to by 86.Fa sbytes . 87.Pp 88The 89.Fa flags 90argument is currently undefined and should be specified as 0. 91.Pp 92When using a socket marked for non-blocking I/O, 93.Fn sendfile 94may send fewer bytes than requested. 95In this case, the number of bytes successfully 96written is returned in 97.Fa *sbytes 98(if specified), 99and the error 100.Er EAGAIN 101is returned. 102.Sh IMPLEMENTATION NOTES 103The 104.Dx 105implementation of 106.Fn sendfile 107is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided. 108.Sh RETURN VALUES 109.Rv -std sendfile 110.Sh ERRORS 111.Bl -tag -width Er 112.It Bq Er EBADF 113.Fa fd 114is not a valid file descriptor. 115.It Bq Er EBADF 116.Fa s 117is not a valid socket descriptor. 118.It Bq Er ENOTSOCK 119.Fa s 120is not a socket. 121.It Bq Er EINVAL 122.Fa fd 123is not a regular file. 124.It Bq Er EINVAL 125.Fa s 126is not a SOCK_STREAM type socket. 127.It Bq Er EINVAL 128.Fa offset 129is negative or out of range. 130.It Bq Er ENOTCONN 131.Fa s 132points to an unconnected socket. 133.It Bq Er EPIPE 134The socket peer has closed the connection. 135.It Bq Er EIO 136An error occurred while reading from 137.Fa fd . 138.It Bq Er EFAULT 139An invalid address was specified for a parameter. 140.It Bq Er EAGAIN 141The socket is marked for non-blocking I/O and not all data was sent due to the socket buffer being filled. 142If specified, the number of bytes successfully sent will be returned in 143.Fa *sbytes . 144.El 145.Sh SEE ALSO 146.Xr open 2 , 147.Xr send 2 , 148.Xr socket 2 , 149.Xr writev 2 150.Sh HISTORY 151.Fn sendfile 152first appeared in 153.Fx 3.0 . 154This manual page first appeared in 155.Fx 3.1 . 156.Sh AUTHORS 157.Fn sendfile 158and this manual page were written by 159.An David Greenman Aq dg@root.com . 160