1 .\" This man page is Copyright (C) 1998 Pawel Krawczyk.
3 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
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.
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
14 .\" updated description of in_fd and out_fd for 2.6
15 .\" Various wording and formatting changes
17 .\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements
19 .TH SENDFILE 2 (date) "Linux man-pages (unreleased)"
21 sendfile \- transfer data between file descriptors
24 .RI ( libc ", " \-lc )
27 .B #include <sys/sendfile.h>
29 .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
30 offset ", size_t" " count" );
31 .\" The below is too ugly. Comments about glibc versions belong
32 .\" in the notes, not in the header.
34 .\" .B #include <features.h>
35 .\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
36 .\" .B #include <sys/sendfile.h>
38 .\" .B #include <sys/types.h>
39 .\" .B /* No system prototype before glibc 2.1. */
40 .\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
41 .\" offset ", size_t" " count" )
47 copies data between one file descriptor and another.
48 Because this copying is done within the kernel,
50 is more efficient than the combination of
54 which would require transferring data to and from user space.
57 should be a file descriptor opened for reading and
59 should be a descriptor opened for writing.
63 is not NULL, then it points
64 to a variable holding the file offset from which
66 will start reading data from
70 returns, this variable
71 will be set to the offset of the byte following the last byte that was read.
76 does not modify the file offset of
78 otherwise the file offset is adjusted to reflect
79 the number of bytes read from
84 is NULL, then data will be read from
86 starting at the file offset,
87 and the file offset will be updated by the call.
90 is the number of bytes to copy between the file descriptors.
94 argument must correspond to a file which supports
97 (i.e., it cannot be a socket).
99 In Linux kernels before 2.6.33,
101 must refer to a socket.
102 Since Linux 2.6.33 it can be any file.
103 If it is a regular file, then
105 changes the file offset appropriately.
107 If the transfer was successful, the number of bytes written to
110 Note that a successful call to
112 may write fewer bytes than requested;
113 the caller should be prepared to retry the call if there were unsent bytes.
116 On error, \-1 is returned, and
118 is set to indicate the error.
122 Nonblocking I/O has been selected using
124 and the write would block.
127 The input file was not opened for reading or the output file
128 was not opened for writing.
134 Descriptor is not valid or locked, or an
136 operation is not available for
147 This is not currently supported by
151 Unspecified error while reading from
155 Insufficient memory to read from
160 is too large, the operation would result in exceeding the maximum size of either
161 the input file or the output file.
165 is not NULL but the input file is not seekable.
168 first appeared in Linux 2.2.
171 is present since glibc 2.1.
173 Not specified in POSIX.1-2001, nor in other standards.
175 Other UNIX systems implement
177 with different semantics and prototypes.
178 It should not be used in portable programs.
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.)
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
194 to minimize the number of packets and to tune performance.
196 In Linux 2.4 and earlier,
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.
204 system call was not designed to handle large file offsets.
205 Consequently, Linux 2.4 added
207 with a wider type for the
212 wrapper function transparently deals with the kernel differences.
214 Applications may wish to fall back to
215 .BR read (2)/ write (2)
225 refers to a socket or pipe with zero-copy support, callers must ensure the
226 transferred portions of the file referred to by
228 remain unmodified until the reader on the other end of
230 has consumed the transferred data.
234 call supports transferring data between arbitrary file descriptors
235 provided one (or both) of them is a pipe.
237 .BR copy_file_range (2),