Debian Codegraph @

upstream/debian-trixie/man2/sendfile.2

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