]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man2/sendfile.2
xnu-2782.30.5.tar.gz
[apple/xnu.git] / 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