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