Debian Codegraph @

upstream/debian-unstable/man2/sendfile.2

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