original/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 2011-09-14 "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 .sp
  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
  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
  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 current file offset of
  79 .IR in_fd ;
  80 otherwise the current file offset is adjusted to reflect
  81 the number of bytes read from
  82 .IR in_fd .
  83
  84 If
  85 .I offset
  86 is NULL, then data will be read from
  87 .IR in_fd
  88 starting at the current file offset,
  89 and the file offset will be updated by the call.
  90
  91 .I count
  92 is the number of bytes to copy between the file descriptors.
  93
  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
 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 On error, \-1 is returned, and
 113 .I errno
 114 is set appropriately.
 115 .SH ERRORS
 116 .TP
 117 .B EAGAIN
 118 Nonblocking I/O has been selected using
 119 .B O_NONBLOCK
 120 and the write would block.
 121 .TP
 122 .B EBADF
 123 The input file was not opened for reading or the output file
 124 was not opened for writing.
 125 .TP
 126 .B EFAULT
 127 Bad address.
 128 .TP
 129 .B EINVAL
 130 Descriptor is not valid or locked, or an
 131 .BR mmap (2)-like
 132 operation is not available for
 133 .IR in_fd .
 134 .TP
 135 .B EIO
 136 Unspecified error while reading from
 137 .IR in_fd .
 138 .TP
 139 .B ENOMEM
 140 Insufficient memory to read from
 141 .IR in_fd .
 142 .SH VERSIONS
 143 .BR sendfile ()
 144 is a new feature in Linux 2.2.
 145 The include file
 146 .I <sys/sendfile.h>
 147 is present since glibc 2.1.
 148 .SH CONFORMING TO
 149 Not specified in POSIX.1-2001, or other standards.
 150
 151 Other UNIX systems implement
 152 .BR sendfile ()
 153 with different semantics and prototypes.
 154 It should not be used in portable programs.
 155 .SH NOTES
 156 If you plan to use
 157 .BR sendfile ()
 158 for sending files to a TCP socket, but need
 159 to send some header data in front of the file contents, you will find
 160 it useful to employ the
 161 .B TCP_CORK
 162 option, described in
 163 .BR tcp (7),
 164 to minimize the number of packets and to tune performance.
 165
 166 In Linux 2.4 and earlier,
 167 .I out_fd
 168 could also refer to a regular file, and
 169 .BR sendfile ()
 170 changed the current offset of that file.
 171
 172 The original Linux
 173 .BR sendfile ()
 174 system call was not designed to handle large file offsets.
 175 Consequently, Linux 2.4 added
 176 .BR sendfile64 (),
 177 with a wider type for the
 178 .I offset
 179 argument.
 180 The glibc
 181 .BR sendfile ()
 182 wrapper function transparently deals with the kernel differences.
 183
 184 Applications may wish to fall back to
 185 .BR read (2)/ write (2)
 186 in the case where
 187 .BR sendfile ()
 188 fails with
 189 .B EINVAL
 190 or
 191 .BR ENOSYS .
 192
 193 The Linux-specific
 194 .BR splice (2)
 195 call supports transferring data between arbitrary files
 196 (e.g., a pair of sockets).
 197 .SH SEE ALSO
 198 .BR mmap (2),
 199 .BR open (2),
 200 .BR socket (2),
 201 .BR splice (2)
 202
 203 .SH COLOPHON
 204 This page is part of release 3.65 of the Linux
 205 .I man-pages
 206 project.
 207 A description of the project,
 208 and information about reporting bugs,
 209 can be found at
 210 \%http://www.kernel.org/doc/man\-pages/.