bsd/man/man2/sendfile.2

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