]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This man page is Copyright (C) 1998 Pawel Krawczyk. |
2297bf0e | 2 | .\" |
00acdba1 | 3 | .\" %%%LICENSE_START(VERBATIM_ONE_PARA) |
fea681da MK |
4 | .\" Permission is granted to distribute possibly modified copies |
5 | .\" of this page provided the header is included verbatim, | |
6 | .\" and in case of nontrivial modification author and date | |
7 | .\" of the modification is added to the header. | |
8ff7380d | 8 | .\" %%%LICENSE_END |
7822805d | 9 | .\" |
fea681da MK |
10 | .\" $Id: sendfile.2,v 1.5 1999/05/18 11:54:11 freitag Exp $ |
11 | .\" 2000-11-19 bert hubert <ahu@ds9a.nl>: in_fd cannot be socket | |
cf257cc5 MK |
12 | .\" |
13 | .\" 2004-12-17, mtk | |
14 | .\" updated description of in_fd and out_fd for 2.6 | |
15 | .\" Various wording and formatting changes | |
16 | .\" | |
9fe9d301 MK |
17 | .\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements |
18 | .\" | |
4c1c5274 | 19 | .TH sendfile 2 (date) "Linux man-pages (unreleased)" |
fea681da MK |
20 | .SH NAME |
21 | sendfile \- transfer data between file descriptors | |
d178fd87 AC |
22 | .SH LIBRARY |
23 | Standard C library | |
8fc3b2cf | 24 | .RI ( libc ", " \-lc ) |
fea681da | 25 | .SH SYNOPSIS |
c7db92b9 | 26 | .nf |
fea681da | 27 | .B #include <sys/sendfile.h> |
68e4db0a | 28 | .PP |
9fe9d301 MK |
29 | .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \ |
30 | offset ", size_t" " count" ); | |
fea681da MK |
31 | .\" The below is too ugly. Comments about glibc versions belong |
32 | .\" in the notes, not in the header. | |
33 | .\" | |
34 | .\" .B #include <features.h> | |
c13182ef | 35 | .\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2 |
fea681da | 36 | .\" .B #include <sys/sendfile.h> |
fea681da | 37 | .\" #else |
fea681da | 38 | .\" .B #include <sys/types.h> |
c13182ef | 39 | .\" .B /* No system prototype before glibc 2.1. */ |
9fe9d301 MK |
40 | .\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \ |
41 | .\" offset ", size_t" " count" ) | |
fea681da MK |
42 | .\" .B #endif |
43 | .\" | |
c7db92b9 | 44 | .fi |
fea681da | 45 | .SH DESCRIPTION |
cf257cc5 MK |
46 | .BR sendfile () |
47 | copies data between one file descriptor and another. | |
48 | Because this copying is done within the kernel, | |
49 | .BR sendfile () | |
50 | is more efficient than the combination of | |
51 | .BR read (2) | |
52 | and | |
53 | .BR write (2), | |
54 | which would require transferring data to and from user space. | |
efeece04 | 55 | .PP |
fea681da MK |
56 | .I in_fd |
57 | should be a file descriptor opened for reading and | |
58 | .I out_fd | |
59 | should be a descriptor opened for writing. | |
efeece04 | 60 | .PP |
c13182ef | 61 | If |
fea681da | 62 | .I offset |
db04da1f MK |
63 | is not NULL, then it points |
64 | to a variable holding the file offset from which | |
fea681da | 65 | .BR sendfile () |
cf257cc5 MK |
66 | will start reading data from |
67 | .IR in_fd . | |
c13182ef | 68 | When |
fea681da MK |
69 | .BR sendfile () |
70 | returns, this variable | |
71 | will be set to the offset of the byte following the last byte that was read. | |
db04da1f MK |
72 | If |
73 | .I offset | |
74 | is not NULL, then | |
fea681da | 75 | .BR sendfile () |
c72249c5 | 76 | does not modify the file offset of |
db04da1f | 77 | .IR in_fd ; |
c72249c5 | 78 | otherwise the file offset is adjusted to reflect |
db04da1f | 79 | the number of bytes read from |
cf257cc5 | 80 | .IR in_fd . |
efeece04 | 81 | .PP |
5227ef33 MK |
82 | If |
83 | .I offset | |
84 | is NULL, then data will be read from | |
1ae6b2c7 | 85 | .I in_fd |
c72249c5 | 86 | starting at the file offset, |
5227ef33 | 87 | and the file offset will be updated by the call. |
efeece04 | 88 | .PP |
cf257cc5 MK |
89 | .I count |
90 | is the number of bytes to copy between the file descriptors. | |
efeece04 | 91 | .PP |
6cce8340 | 92 | The |
1ae6b2c7 | 93 | .I in_fd |
6cce8340 | 94 | argument must correspond to a file which supports |
0bfa087b | 95 | .BR mmap (2)-like |
1e321034 | 96 | operations |
fe0ed23f | 97 | (i.e., it cannot be a socket). |
efeece04 | 98 | .PP |
fe0ed23f | 99 | In Linux kernels before 2.6.33, |
cf257cc5 MK |
100 | .I out_fd |
101 | must refer to a socket. | |
fe0ed23f AF |
102 | Since Linux 2.6.33 it can be any file. |
103 | If it is a regular file, then | |
b18e759d | 104 | .BR sendfile () |
1293f354 | 105 | changes the file offset appropriately. |
47297adb | 106 | .SH RETURN VALUE |
fea681da MK |
107 | If the transfer was successful, the number of bytes written to |
108 | .I out_fd | |
c13182ef | 109 | is returned. |
3f4ed032 MK |
110 | Note that a successful call to |
111 | .BR sendfile () | |
112 | may write fewer bytes than requested; | |
113 | the caller should be prepared to retry the call if there were unsent bytes. | |
77548009 | 114 | See also NOTES. |
efeece04 | 115 | .PP |
c13182ef | 116 | On error, \-1 is returned, and |
fea681da | 117 | .I errno |
f6a4078b | 118 | is set to indicate the error. |
fea681da MK |
119 | .SH ERRORS |
120 | .TP | |
121 | .B EAGAIN | |
44732c9c | 122 | Nonblocking I/O has been selected using |
fea681da MK |
123 | .B O_NONBLOCK |
124 | and the write would block. | |
125 | .TP | |
126 | .B EBADF | |
127 | The input file was not opened for reading or the output file | |
128 | was not opened for writing. | |
129 | .TP | |
130 | .B EFAULT | |
131 | Bad address. | |
132 | .TP | |
133 | .B EINVAL | |
c13182ef | 134 | Descriptor is not valid or locked, or an |
0bfa087b | 135 | .BR mmap (2)-like |
9fe9d301 | 136 | operation is not available for |
4975d6af LG |
137 | .IR in_fd , |
138 | or | |
139 | .I count | |
140 | is negative. | |
fea681da | 141 | .TP |
2a342fcf MK |
142 | .B EINVAL |
143 | .I out_fd | |
d4984160 | 144 | has the |
2a342fcf MK |
145 | .B O_APPEND |
146 | flag set. | |
147 | This is not currently supported by | |
148 | .BR sendfile (). | |
149 | .TP | |
fea681da MK |
150 | .B EIO |
151 | Unspecified error while reading from | |
152 | .IR in_fd . | |
153 | .TP | |
154 | .B ENOMEM | |
155 | Insufficient memory to read from | |
156 | .IR in_fd . | |
4975d6af LG |
157 | .TP |
158 | .B EOVERFLOW | |
159 | .I count | |
160 | is too large, the operation would result in exceeding the maximum size of either | |
161 | the input file or the output file. | |
162 | .TP | |
163 | .B ESPIPE | |
164 | .I offset | |
10e29c05 | 165 | is not NULL but the input file is not seekable. |
fea681da | 166 | .SH VERSIONS |
cf257cc5 | 167 | .BR sendfile () |
4a38acf2 | 168 | first appeared in Linux 2.2. |
a9a13a50 MK |
169 | The include file |
170 | .I <sys/sendfile.h> | |
171 | is present since glibc 2.1. | |
3113c7f3 | 172 | .SH STANDARDS |
f5f05a7b | 173 | Not specified in POSIX.1-2001, nor in other standards. |
efeece04 | 174 | .PP |
008f1ecc | 175 | Other UNIX systems implement |
cf257cc5 | 176 | .BR sendfile () |
c13182ef | 177 | with different semantics and prototypes. |
db04da1f | 178 | It should not be used in portable programs. |
2b2581ee | 179 | .SH NOTES |
77548009 MK |
180 | .BR sendfile () |
181 | will transfer at most 0x7ffff000 (2,147,479,552) bytes, | |
182 | returning the number of bytes actually transferred. | |
183 | .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 | |
184 | (This is true on both 32-bit and 64-bit systems.) | |
efeece04 | 185 | .PP |
2b2581ee MK |
186 | If you plan to use |
187 | .BR sendfile () | |
188 | for sending files to a TCP socket, but need | |
189 | to send some header data in front of the file contents, you will find | |
190 | it useful to employ the | |
191 | .B TCP_CORK | |
192 | option, described in | |
193 | .BR tcp (7), | |
194 | to minimize the number of packets and to tune performance. | |
efeece04 | 195 | .PP |
2b2581ee MK |
196 | In Linux 2.4 and earlier, |
197 | .I out_fd | |
9e8a61e6 MK |
198 | could also refer to a regular file; |
199 | this possibility went away in the Linux 2.6.x kernel series, | |
200 | but was restored in Linux 2.6.33. | |
efeece04 | 201 | .PP |
33cf6d36 MK |
202 | The original Linux |
203 | .BR sendfile () | |
204 | system call was not designed to handle large file offsets. | |
205 | Consequently, Linux 2.4 added | |
206 | .BR sendfile64 (), | |
207 | with a wider type for the | |
208 | .I offset | |
209 | argument. | |
210 | The glibc | |
211 | .BR sendfile () | |
212 | wrapper function transparently deals with the kernel differences. | |
efeece04 | 213 | .PP |
bb0fed2e MK |
214 | Applications may wish to fall back to |
215 | .BR read (2)/ write (2) | |
216 | in the case where | |
217 | .BR sendfile () | |
218 | fails with | |
219 | .B EINVAL | |
220 | or | |
221 | .BR ENOSYS . | |
efeece04 | 222 | .PP |
7b6a3299 EW |
223 | If |
224 | .I out_fd | |
225 | refers to a socket or pipe with zero-copy support, callers must ensure the | |
226 | transferred portions of the file referred to by | |
227 | .I in_fd | |
228 | remain unmodified until the reader on the other end of | |
229 | .I out_fd | |
230 | has consumed the transferred data. | |
efeece04 | 231 | .PP |
866ed736 TD |
232 | The Linux-specific |
233 | .BR splice (2) | |
69fff559 AS |
234 | call supports transferring data between arbitrary file descriptors |
235 | provided one (or both) of them is a pipe. | |
47297adb | 236 | .SH SEE ALSO |
9876bc24 | 237 | .BR copy_file_range (2), |
9fe9d301 | 238 | .BR mmap (2), |
bddd0b2e | 239 | .BR open (2), |
8231ec7d MK |
240 | .BR socket (2), |
241 | .BR splice (2) |