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.\" 27.Dd March 31, 2006 28.Dt SENDFILE 2 29.Os "Mac OS X" 30.Sh NAME 31.Nm sendfile 32.Nd send a file to a socket 33.Sh SYNOPSIS 34.In sys/types.h 35.In sys/socket.h 36.In sys/uio.h 37.Ft int 38.Fo sendfile 39.Fa "int fd" "int s" "off_t offset" "off_t *len" 40.Fa "struct sf_hdtr *hdtr" "int flags" 41.Fc 42.Sh DESCRIPTION 43The 44.Fn sendfile 45system call 46sends a regular file specified by descriptor 47.Fa fd 48out a stream socket specified by descriptor 49.Fa s . 50.Pp 51The 52.Fa offset 53argument specifies where to begin in the file. 54Should 55.Fa offset 56fall beyond the end of file, the system will return 57success and report 0 bytes sent as described below. 58.Pp 59The 60.Fa len 61argument is a value-result parameter, that specifies how many bytes 62of the file should be sent and/or how many bytes have been sent. 63Initially the value pointed to by the 64.Fa len 65argument specifies how many bytes should be sent with 0 having the special 66meaning to send until the end of file has been reached. 67On return the value pointed to by the 68.Fa len 69argument indicates how many bytes have been sent, except when a header or 70trailer is specified as shown below. 71The 72.Fa len 73pointer may not be NULL. 74.Pp 75An optional header and/or trailer can be sent before and after the file data by 76specifying a pointer to a 77.Vt "struct sf_hdtr" , 78which has the following structure: 79.Pp 80.Bd -literal -offset indent -compact 81struct sf_hdtr { 82 struct iovec *headers; /* pointer to header iovecs */ 83 int hdr_cnt; /* number of header iovecs */ 84 struct iovec *trailers; /* pointer to trailer iovecs */ 85 int trl_cnt; /* number of trailer iovecs */ 86}; 87.Ed 88.Pp 89The 90.Fa headers 91and 92.Fa trailers 93pointers, if 94.Pf non- Dv NULL , 95point to arrays of 96.Vt "struct iovec" 97structures. 98See the 99.Fn writev 100system call for information on the iovec structure. 101The number of iovecs in these 102arrays is specified by 103.Fa hdr_cnt 104and 105.Fa trl_cnt . 106.Pp 107When a header or trailer is specified, the value of 108.Fa len 109argument indicates the maximum number of bytes in the header and/or file to be sent. 110It does not control the trailer; if a trailer exists, all of it will be sent. 111If the value of 112.Fa len 113argument is 0, all of the header and/or file will be sent before the entire trailer is sent. 114On return, the 115.Fa len 116argument specifies the total number of bytes sent. 117.Pp 118The 119.Fa flags 120parameter is reserved for future expansion and must be set to 0. Any other value 121will cause 122.Fn sendfile 123to return 124.Er EINVAL . 125.Pp 126When using a socket marked for non-blocking I/O, 127.Fn sendfile 128may send fewer bytes than requested. 129In this case, the number of bytes successfully 130sent is returned in the via the 131.Fa len 132parameters and the error 133.Er EAGAIN 134is returned. 135.Pp 136When a signal causes 137.Fn sendfile 138to return the error 139.Er EINTR , 140the 141.Fa len 142argument may return 0 without necessarily meaning the end of file has been reached 143as the signal may have been caught before any data was sent. 144.Sh IMPLEMENTATION NOTES 145The 146Mac OS X 147implementation of 148.Fn sendfile 149uses 64 bits types for size and offset parameters so there is no need for 150a 64 bits version 151.Fn sendfile64 152as found on some other operating systems. 153.Sh RETURN VALUES 154.Rv -std sendfile 155.Pp 156The number of bytes sent is returned via the parameter 157.Fa len . 158A value of 0 means the end of the file specified by descriptor 159.Fa fd 160has been reached or that the value passed in 161.Fa offset 162falls beyond the end of file. 163.Sh ERRORS 164.Bl -tag -width Er 165.It Bq Er EAGAIN 166The socket is marked for non-blocking I/O and not all data was sent due to 167the socket buffer being full. 168If specified, the number of bytes successfully sent will be returned in 169.Fa *len . 170.It Bq Er EBADF 171The 172.Fa fd 173argument 174is not a valid file descriptor. 175.It Bq Er ENOTSUP 176The 177.Fa fd 178argument 179does not refer to a regular file. 180.It Bq Er EBADF 181The 182.Fa s 183argument 184is not a valid socket descriptor. 185.It Bq Er ENOTSOCK 186The 187.Fa s 188argument 189does not refer stream oriented socket. 190.It Bq Er EFAULT 191An invalid address was specified for an argument. 192.It Bq Er EINTR 193A signal interrupted 194.Fn sendfile 195before it could be completed. 196If specified, the number 197of bytes successfully sent will be returned in 198.Fa *len . 199.It Bq Er EINVAL 200The 201.Fa offset 202argument 203is negative. 204.It Bq Er EINVAL 205The 206.Fa len 207argument 208is NULL. 209.It Bq Er EINVAL 210The 211.Fa flags 212argument 213is not set to 0. 214.It Bq Er EIO 215An error occurred while reading from 216.Fa fd . 217.It Bq Er ENOTCONN 218The 219.Fa s 220argument 221points to an unconnected socket. 222.It Bq Er ENOTSOCK 223The 224.Fa s 225argument 226is not a socket. 227.It Bq Er EOPNOTSUPP 228The file system for descriptor 229.Fa fd 230does not support 231.Fn sendfile . 232.It Bq Er EPIPE 233The socket peer has closed the connection. 234.El 235.Sh SEE ALSO 236.Xr open 2 , 237.Xr send 2 , 238.Xr socket 2 , 239.Xr writev 2 240.Sh HISTORY 241The 242.Fn sendfile 243system call 244first appeared in 245Darwin 9.0 (Mac OS X version 10.5) . 246.Sh AUTHORS 247This manual page is based on the FreeBSD version written by 248.An David G. Lawrence Aq [email protected] 249