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 January 7, 2010 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 is a bitmap of these values: 107.Bl -item -offset indent 108.It 109.Dv SF_NODISKIO . 110This flag causes any 111.Fn sendfile 112call which would block on disk I/O to instead 113return 114.Er EBUSY . 115Busy servers may benefit by transferring requests that would 116block to a separate I/O worker thread. 117.It 118.Dv SF_MNOWAIT . 119Do not wait for some kernel resource to become available, 120in particular, 121.Vt mbuf 122and 123.Vt sf_buf . 124The flag does not make the 125.Fn sendfile 126syscall truly non-blocking, since other resources are still allocated 127in a blocking fashion. 128.It 129.Dv SF_SYNC . 130.Nm 131sleeps until the network stack no longer references the VM pages 132of the file, making subsequent modifications to it safe. 133Please note that this is not a guarantee that the data has actually 134been sent. 135.El 136.Pp 137When using a socket marked for non-blocking I/O, 138.Fn sendfile 139may send fewer bytes than requested. 140In this case, the number of bytes successfully 141written is returned in 142.Fa *sbytes 143(if specified), 144and the error 145.Er EAGAIN 146is returned. 147.Sh IMPLEMENTATION NOTES 148The 149.Fx 150implementation of 151.Fn sendfile 152is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided. 153.Sh TUNING 154On some architectures, this system call internally uses a special 155.Fn sendfile 156buffer 157.Pq Vt "struct sf_buf" 158to handle sending file data to the client. 159If the sending socket is 160blocking, and there are not enough 161.Fn sendfile 162buffers available, 163.Fn sendfile 164will block and report a state of 165.Dq Li sfbufa . 166If the sending socket is non-blocking and there are not enough 167.Fn sendfile 168buffers available, the call will block and wait for the 169necessary buffers to become available before finishing the call. 170.Pp 171The number of 172.Vt sf_buf Ns 's 173allocated should be proportional to the number of nmbclusters used to 174send data to a client via 175.Fn sendfile . 176Tune accordingly to avoid blocking! 177Busy installations that make extensive use of 178.Fn sendfile 179may want to increase these values to be inline with their 180.Va kern.ipc.nmbclusters 181(see 182.Xr tuning 7 183for details). 184.Pp 185The number of 186.Fn sendfile 187buffers available is determined at boot time by either the 188.Va kern.ipc.nsfbufs 189.Xr loader.conf 5 190variable or the 191.Dv NSFBUFS 192kernel configuration tunable. 193The number of 194.Fn sendfile 195buffers scales with 196.Va kern.maxusers . 197The 198.Va kern.ipc.nsfbufsused 199and 200.Va kern.ipc.nsfbufspeak 201read-only 202.Xr sysctl 8 203variables show current and peak 204.Fn sendfile 205buffers usage respectively. 206These values may also be viewed through 207.Nm netstat Fl m . 208.Pp 209If a value of zero is reported for 210.Va kern.ipc.nsfbufs , 211your architecture does not need to use 212.Fn sendfile 213buffers because their task can be efficiently performed 214by the generic virtual memory structures. 215.Sh RETURN VALUES 216.Rv -std sendfile 217.Sh ERRORS 218.Bl -tag -width Er 219.It Bq Er EAGAIN 220The socket is marked for non-blocking I/O and not all data was sent due to 221the socket buffer being filled. 222If specified, the number of bytes successfully sent will be returned in 223.Fa *sbytes . 224.It Bq Er EBADF 225The 226.Fa fd 227argument 228is not a valid file descriptor. 229.It Bq Er EBADF 230The 231.Fa s 232argument 233is not a valid socket descriptor. 234.It Bq Er EBUSY 235Completing the entire transfer would have required disk I/O, so 236it was aborted. 237Partial data may have been sent. 238(This error can only occur when 239.Dv SF_NODISKIO 240is specified.) 241.It Bq Er EFAULT 242An invalid address was specified for an argument. 243.It Bq Er EINTR 244A signal interrupted 245.Fn sendfile 246before it could be completed. 247If specified, the number 248of bytes successfully sent will be returned in 249.Fa *sbytes . 250.It Bq Er EINVAL 251The 252.Fa fd 253argument 254is not a regular file. 255.It Bq Er EINVAL 256The 257.Fa s 258argument 259is not a SOCK_STREAM type socket. 260.It Bq Er EINVAL 261The 262.Fa offset 263argument 264is negative. 265.It Bq Er EIO 266An error occurred while reading from 267.Fa fd . 268.It Bq Er ENOBUFS 269The system was unable to allocate an internal buffer. 270.It Bq Er ENOTCONN 271The 272.Fa s 273argument 274points to an unconnected socket. 275.It Bq Er ENOTSOCK 276The 277.Fa s 278argument 279is not a socket. 280.It Bq Er EOPNOTSUPP 281The file system for descriptor 282.Fa fd 283does not support 284.Fn sendfile . 285.It Bq Er EPIPE 286The socket peer has closed the connection. 287.El 288.Sh SEE ALSO 289.Xr netstat 1 , 290.Xr open 2 , 291.Xr send 2 , 292.Xr socket 2 , 293.Xr writev 2 , 294.Xr tuning 7 295.Rs 296.%A K. Elmeleegy 297.%A A. Chanda 298.%A A. L. Cox 299.%A W. Zwaenepoel 300.%T A Portable Kernel Abstraction for Low-Overhead Ephemeral Mapping Management 301.%J The Proceedings of the 2005 USENIX Annual Technical Conference 302.%P pp 223-236 303.%D 2005 304.Re 305.Sh HISTORY 306The 307.Fn sendfile 308system call 309first appeared in 310.Fx 3.0 . 311This manual page first appeared in 312.Fx 3.1 . 313.Sh AUTHORS 314The 315.Fn sendfile 316system call 317and this manual page were written by 318.An David G. Lawrence Aq Mt [email protected] . 319