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