-
Notifications
You must be signed in to change notification settings - Fork 0
/
sendfile64.html
328 lines (239 loc) · 8.95 KB
/
sendfile64.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:26:48 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>SENDFILE</title>
</head>
<body>
<h1 align="center">SENDFILE</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#VERSIONS">VERSIONS</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">sendfile -
transfer data between file descriptors</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<sys/sendfile.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>ssize_t
sendfile(int</b> <i>out_fd</i><b>, int</b> <i>in_fd</i><b>,
off_t *</b><i>offset</i><b>, size_t</b>
<i>count</i><b>);</b></p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>sendfile</b>()
copies data between one file descriptor and another. Because
this copying is done within the kernel, <b>sendfile</b>() is
more efficient than the combination of <b>read</b>(2) and
<b>write</b>(2), which would require transferring data to
and from user space.</p>
<p style="margin-left:11%; margin-top: 1em"><i>in_fd</i>
should be a file descriptor opened for reading and
<i>out_fd</i> should be a descriptor opened for writing.</p>
<p style="margin-left:11%; margin-top: 1em">If
<i>offset</i> is not NULL, then it points to a variable
holding the file offset from which <b>sendfile</b>() will
start reading data from <i>in_fd</i>. When <b>sendfile</b>()
returns, this variable will be set to the offset of the byte
following the last byte that was read. If <i>offset</i> is
not NULL, then <b>sendfile</b>() does not modify the file
offset of <i>in_fd</i>; otherwise the file offset is
adjusted to reflect the number of bytes read from
<i>in_fd</i>.</p>
<p style="margin-left:11%; margin-top: 1em">If
<i>offset</i> is NULL, then data will be read from
<i>in_fd</i> starting at the file offset, and the file
offset will be updated by the call.</p>
<p style="margin-left:11%; margin-top: 1em"><i>count</i> is
the number of bytes to copy between the file
descriptors.</p>
<p style="margin-left:11%; margin-top: 1em">The
<i>in_fd</i> argument must correspond to a file which
supports <b>mmap</b>(2)-like operations (i.e., it cannot be
a socket).</p>
<p style="margin-left:11%; margin-top: 1em">In Linux
kernels before 2.6.33, <i>out_fd</i> must refer to a socket.
Since Linux 2.6.33 it can be any file. If it is a regular
file, then <b>sendfile</b>() changes the file offset
appropriately.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">If the transfer
was successful, the number of bytes written to <i>out_fd</i>
is returned. Note that a successful call to
<b>sendfile</b>() may write fewer bytes than requested; the
caller should be prepared to retry the call if there were
unsent bytes. See also NOTES.</p>
<p style="margin-left:11%; margin-top: 1em">On error, -1 is
returned, and <i>errno</i> is set appropriately.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p style="margin-top: 1em"><b>EAGAIN</b></p></td>
<td width="2%"></td>
<td width="78%">
<p style="margin-top: 1em">Nonblocking I/O has been
selected using <b>O_NONBLOCK</b> and the write would
block.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EBADF</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The input file was not opened for reading or the output
file was not opened for writing.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EFAULT</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>Bad address.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>Descriptor is not valid or locked, or an
<b>mmap</b>(2)-like operation is not available for
<i>in_fd</i>, or <i>count</i> is negative.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><i>out_fd</i> has the <b>O_APPEND</b> flag set. This is
not currently supported by <b>sendfile</b>().</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EIO</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>Unspecified error while reading from <i>in_fd</i>.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>ENOMEM</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>Insufficient memory to read from <i>in_fd</i>.</p></td></tr>
</table>
<p style="margin-left:11%;"><b>EOVERFLOW</b></p>
<p style="margin-left:22%;"><i>count</i> is too large, the
operation would result in exceeding the maximum size of
either the input file or the output file.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>ESPIPE</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><i>offset</i> is not NULL but the input file is not
<b>seek</b>(2)-able.</p> </td></tr>
</table>
<h2>VERSIONS
<a name="VERSIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>sendfile</b>()
first appeared in Linux 2.2. The include file
<i><sys/sendfile.h></i> is present since glibc
2.1.</p>
<h2>CONFORMING TO
<a name="CONFORMING TO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Not specified
in POSIX.1-2001, nor in other standards.</p>
<p style="margin-left:11%; margin-top: 1em">Other UNIX
systems implement <b>sendfile</b>() with different semantics
and prototypes. It should not be used in portable
programs.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>sendfile</b>()
will transfer at most 0x7ffff000 (2,147,479,552) bytes,
returning the number of bytes actually transferred. (This is
true on both 32-bit and 64-bit systems.)</p>
<p style="margin-left:11%; margin-top: 1em">If you plan to
use <b>sendfile</b>() for sending files to a TCP socket, but
need to send some header data in front of the file contents,
you will find it useful to employ the <b>TCP_CORK</b>
option, described in <b>tcp</b>(7), to minimize the number
of packets and to tune performance.</p>
<p style="margin-left:11%; margin-top: 1em">In Linux 2.4
and earlier, <i>out_fd</i> could also refer to a regular
file; this possibility went away in the Linux 2.6.x kernel
series, but was restored in Linux 2.6.33.</p>
<p style="margin-left:11%; margin-top: 1em">The original
Linux <b>sendfile</b>() system call was not designed to
handle large file offsets. Consequently, Linux 2.4 added
<b>sendfile64</b>(), with a wider type for the <i>offset</i>
argument. The glibc <b>sendfile</b>() wrapper function
transparently deals with the kernel differences.</p>
<p style="margin-left:11%; margin-top: 1em">Applications
may wish to fall back to <b>read</b>(2)/<b>write</b>(2) in
the case where <b>sendfile</b>() fails with <b>EINVAL</b> or
<b>ENOSYS</b>.</p>
<p style="margin-left:11%; margin-top: 1em">If
<i>out_fd</i> refers to a socket or pipe with zero-copy
support, callers must ensure the transferred portions of the
file referred to by <i>in_fd</i> remain unmodified until the
reader on the other end of <i>out_fd</i> has consumed the
transferred data.</p>
<p style="margin-left:11%; margin-top: 1em">The
Linux-specific <b>splice</b>(2) call supports transferring
data between arbitrary file descriptors provided one (or
both) of them is a pipe.</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>copy_file_range</b>(2),
<b>mmap</b>(2), <b>open</b>(2), <b>socket</b>(2),
<b>splice</b>(2)</p>
<h2>COLOPHON
<a name="COLOPHON"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This page is
part of release 5.02 of the Linux <i>man-pages</i> project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.</p>
<hr>
</body>
</html>