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