man2/sendfile.2

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