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 argument indicates the maximum number of bytes in the header and/or file to be sent.
 110 It does not control the trailer; if a trailer exists, all of it will be sent.
 111 If the value of
 112 .Fa len
 113 argument is 0, all of the header and/or file will be sent before the entire trailer is sent.
 114 On return, the
 115 .Fa len
 116 argument specifies the total number of bytes sent.
 117 .Pp
 118 The
 119 .Fa flags
 120 parameter is reserved for future expansion and must be set to 0. Any other value
 121 will cause
 122 .Fn sendfile
 123 to return
 124 .Er EINVAL .
 125 .Pp
 126 When using a socket marked for non-blocking I/O,
 127 .Fn sendfile
 128 may send fewer bytes than requested.
 129 In this case, the number of bytes successfully
 130 sent is returned in the via the
 131 .Fa len
 132 parameters and the error
 133 .Er EAGAIN
 134 is returned.
 135 .Pp
 136 When a signal causes
 137 .Fn sendfile
 138 to return the error
 139 .Er EINTR ,
 140 the
 141 .Fa len
 142 argument may return 0 without necessarily meaning the end of file has been reached
 143 as the signal may have been caught before any data was sent.
 144 .Sh IMPLEMENTATION NOTES
 145 The
 146 Mac OS X
 147 implementation of
 148 .Fn sendfile
 149 uses 64 bits types for size and offset parameters so there is no need for
 150 a 64 bits version
 151 .Fn sendfile64
 152 as found on some other operating systems.
 153 .Sh RETURN VALUES
 154 .Rv -std sendfile
 155 .Pp
 156 The number of bytes sent is returned via the parameter
 157 .Fa len .
 158 A value of 0 means the end of the file specified by descriptor
 159 .Fa fd
 160 has been reached or that the value passed in
 161 .Fa offset
 162 falls beyond the end of file.
 163 .Sh ERRORS
 164 .Bl -tag -width Er
 165 .It Bq Er EAGAIN
 166 The socket is marked for non-blocking I/O and not all data was sent due to
 167 the socket buffer being full.
 168 If specified, the number of bytes successfully sent will be returned in
 169 .Fa *len .
 170 .It Bq Er EBADF
 171 The
 172 .Fa fd
 173 argument
 174 is not a valid file descriptor.
 175 .It Bq Er ENOTSUP
 176 The
 177 .Fa fd
 178 argument
 179 does not refer to a regular file.
 180 .It Bq Er EBADF
 181 The
 182 .Fa s
 183 argument
 184 is not a valid socket descriptor.
 185 .It Bq Er ENOTSOCK
 186 The
 187 .Fa s
 188 argument
 189 does not refer stream oriented socket.
 190 .It Bq Er EFAULT
 191 An invalid address was specified for an argument.
 192 .It Bq Er EINTR
 193 A signal interrupted
 194 .Fn sendfile
 195 before it could be completed.
 196 If specified, the number
 197 of bytes successfully sent will be returned in
 198 .Fa *len .
 199 .It Bq Er EINVAL
 200 The
 201 .Fa offset
 202 argument
 203 is negative.
 204 .It Bq Er EINVAL
 205 The
 206 .Fa len
 207 argument
 208 is NULL.
 209 .It Bq Er EINVAL
 210 The
 211 .Fa flags
 212 argument
 213 is not set to 0.
 214 .It Bq Er EIO
 215 An error occurred while reading from
 216 .Fa fd .
 217 .It Bq Er ENOTCONN
 218 The
 219 .Fa s
 220 argument
 221 points to an unconnected socket.
 222 .It Bq Er ENOTSOCK
 223 The
 224 .Fa s
 225 argument
 226 is not a socket.
 227 .It Bq Er EOPNOTSUPP
 228 The file system for descriptor
 229 .Fa fd
 230 does not support
 231 .Fn sendfile .
 232 .It Bq Er EPIPE
 233 The 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
 241 The
 242 .Fn sendfile
 243 system call
 244 first appeared in
 245 Darwin 9.0 (Mac OS X version 10.5) .
 246 .Sh AUTHORS
 247 This manual page is based on the FreeBSD version written by
 248 .An David G. Lawrence Aq dg@dglawrence.com