1.\" Copyright (c) 2003, David G. Lawrence 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$ 27.\" 28.Dd October 31, 2005 29.Dt SENDFILE 2 30.Os 31.Sh NAME 32.Nm sendfile 33.Nd send a file to a socket 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/types.h 38.In sys/socket.h 39.In sys/uio.h 40.Ft int 41.Fo sendfile 42.Fa "int fd" "int s" "off_t offset" "size_t nbytes" 43.Fa "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags" 44.Fc 45.Sh DESCRIPTION 46The 47.Fn sendfile 48system call 49sends a regular file specified by descriptor 50.Fa fd 51out a stream socket specified by descriptor 52.Fa s . 53.Pp 54The 55.Fa offset 56argument specifies where to begin in the file. 57Should 58.Fa offset 59fall beyond the end of file, the system will return 60success and report 0 bytes sent as described below. 61The 62.Fa nbytes 63argument specifies how many bytes of the file should be sent, with 0 having the special 64meaning of send until the end of file has been reached. 65.Pp 66An optional header and/or trailer can be sent before and after the file data by specifying 67a pointer to a 68.Vt "struct sf_hdtr" , 69which has the following structure: 70.Pp 71.Bd -literal -offset indent -compact 72struct sf_hdtr { 73 struct iovec *headers; /* pointer to header iovecs */ 74 int hdr_cnt; /* number of header iovecs */ 75 struct iovec *trailers; /* pointer to trailer iovecs */ 76 int trl_cnt; /* number of trailer iovecs */ 77}; 78.Ed 79.Pp 80The 81.Fa headers 82and 83.Fa trailers 84pointers, if 85.Pf non- Dv NULL , 86point to arrays of 87.Vt "struct iovec" 88structures. 89See the 90.Fn writev 91system call for information on the iovec structure. 92The number of iovecs in these 93arrays is specified by 94.Fa hdr_cnt 95and 96.Fa trl_cnt . 97.Pp 98If 99.Pf non- Dv NULL , 100the system will write the total number of bytes sent on the socket to the 101variable pointed to by 102.Fa sbytes . 103.Pp 104The 105.Fa flags 106argument has one possible value: 107.Dv SF_NODISKIO . 108This flag causes any 109.Fn sendfile 110call which would block on disk I/O to instead 111return 112.Er EBUSY . 113Busy servers may benefit by transferring requests that would 114block to a separate I/O worker thread. 115.Pp 116When using a socket marked for non-blocking I/O, 117.Fn sendfile 118may send fewer bytes than requested. 119In this case, the number of bytes successfully 120written is returned in 121.Fa *sbytes 122(if specified), 123and the error 124.Er EAGAIN 125is returned. 126.Sh IMPLEMENTATION NOTES 127The 128.Fx 129implementation of 130.Fn sendfile 131is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided. 132.Sh TUNING 133Internally, this system call uses a special 134.Fn sendfile 135buffer 136.Pq Vt "struct sf_buf" 137to handle sending file data to the client. 138If the sending socket is 139blocking, and there are not enough 140.Fn sendfile 141buffers available, 142.Fn sendfile 143will block and report a state of 144.Dq Li sfbufa . 145If the sending socket is non-blocking and there are not enough 146.Fn sendfile 147buffers available, the call will block and wait for the 148necessary buffers to become available before finishing the call. 149.Pp 150The number of 151.Vt sf_buf Ns 's 152allocated should be proportional to the number of nmbclusters used to 153send data to a client via 154.Fn sendfile . 155Tune accordingly to avoid blocking! 156Busy installations that make extensive use of 157.Fn sendfile 158may want to increase these values to be inline with their 159.Va kern.ipc.nmbclusters 160(see 161.Xr tuning 7 162for details). 163.Pp 164The number of 165.Fn sendfile 166buffers available is determined at boot time by either the 167.Va kern.ipc.nsfbufs 168.Xr loader.conf 5 169variable or the 170.Dv NSFBUFS 171kernel configuration tunable. 172The number of 173.Fn sendfile 174buffers scales with 175.Va kern.maxusers . 176The 177.Va kern.ipc.nsfbufsused 178and 179.Va kern.ipc.nsfbufspeak 180read-only 181.Xr sysctl 8 182variables show current and peak 183.Fn sendfile 184buffers usage respectively. 185These values may also be viewed through 186.Nm netstat Fl m . 187.Sh RETURN VALUES 188.Rv -std sendfile 189.Sh ERRORS 190.Bl -tag -width Er 191.It Bq Er EAGAIN 192The socket is marked for non-blocking I/O and not all data was sent due to 193the socket buffer being filled. 194If specified, the number of bytes successfully sent will be returned in 195.Fa *sbytes . 196.It Bq Er EBADF 197The 198.Fa fd 199argument 200is not a valid file descriptor. 201.It Bq Er EBADF 202The 203.Fa s 204argument 205is not a valid socket descriptor. 206.It Bq Er EBUSY 207Completing the entire transfer would have required disk I/O, so 208it was aborted. 209Partial data may have been sent. 210(This error can only occur when 211.Dv SF_NODISKIO 212is specified.) 213.It Bq Er EFAULT 214An invalid address was specified for an argument. 215.It Bq Er EINTR 216A signal interrupted 217.Fn sendfile 218before it could be completed. 219If specified, the number 220of bytes successfully sent will be returned in 221.Fa *sbytes . 222.It Bq Er EINVAL 223The 224.Fa fd 225argument 226is not a regular file. 227.It Bq Er EINVAL 228The 229.Fa s 230argument 231is not a SOCK_STREAM type socket. 232.It Bq Er EINVAL 233The 234.Fa offset 235argument 236is negative. 237.It Bq Er EIO 238An error occurred while reading from 239.Fa fd . 240.It Bq Er ENOTCONN 241The 242.Fa s 243argument 244points to an unconnected socket. 245.It Bq Er ENOTSOCK 246The 247.Fa s 248argument 249is not a socket. 250.It Bq Er EOPNOTSUPP 251The file system for descriptor 252.Fa fd 253does not support 254.Fn sendfile . 255.It Bq Er EPIPE 256The socket peer has closed the connection. 257.El 258.Sh SEE ALSO 259.Xr netstat 1 , 260.Xr open 2 , 261.Xr send 2 , 262.Xr socket 2 , 263.Xr writev 2 , 264.Xr tuning 7 265.Sh HISTORY 266The 267.Fn sendfile 268system call 269first appeared in 270.Fx 3.0 . 271This manual page first appeared in 272.Fx 3.1 . 273.Sh AUTHORS 274The 275.Fn sendfile 276system call 277and this manual page were written by 278.An David G. Lawrence Aq [email protected] . 279