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