original/man2/sendfile.2

   1 .\" This man page is Copyright (C) 1998 Pawel Krawczyk.
   2 .\" Permission is granted to distribute possibly modified copies
   3 .\" of this page provided the header is included verbatim,
   4 .\" and in case of nontrivial modification author and date
   5 .\" of the modification is added to the header.
   6 .\" $Id: sendfile.2,v 1.5 1999/05/18 11:54:11 freitag Exp $
   7 .\" 2000-11-19 bert hubert <ahu@ds9a.nl>: in_fd cannot be socket
   8 .\"
   9 .\" 2004-12-17, mtk
  10 .\"     updated description of in_fd and out_fd for 2.6
  11 .\"     Various wording and formatting changes
  12 .\"
  13 .\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements
  14 .\"
  15 .TH SENDFILE 2 2011-09-14 "Linux" "Linux Programmer's Manual"
  16 .SH NAME
  17 sendfile \- transfer data between file descriptors
  18 .SH SYNOPSIS
  19 .B #include <sys/sendfile.h>
  20 .sp
  21 .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
  22                       offset ", size_t" " count" );
  23 .\" The below is too ugly. Comments about glibc versions belong
  24 .\" in the notes, not in the header.
  25 .\"
  26 .\" .B #include <features.h>
  27 .\" .br
  28 .\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
  29 .\" .br
  30 .\" .B #include <sys/sendfile.h>
  31 .\" .br
  32 .\" #else
  33 .\" .br
  34 .\" .B #include <sys/types.h>
  35 .\" .br
  36 .\" .B /* No system prototype before glibc 2.1. */
  37 .\" .br
  38 .\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
  39 .\"                       offset ", size_t" " count" )
  40 .\" .br
  41 .\" .B #endif
  42 .\"
  43 .SH DESCRIPTION
  44 .BR sendfile ()
  45 copies data between one file descriptor and another.
  46 Because this copying is done within the kernel,
  47 .BR sendfile ()
  48 is more efficient than the combination of
  49 .BR read (2)
  50 and
  51 .BR write (2),
  52 which would require transferring data to and from user space.
  53
  54 .I in_fd
  55 should be a file descriptor opened for reading and
  56 .I out_fd
  57 should be a descriptor opened for writing.
  58
  59 If
  60 .I offset
  61 is not NULL, then it points
  62 to a variable holding the file offset from which
  63 .BR sendfile ()
  64 will start reading data from
  65 .IR in_fd .
  66 When
  67 .BR sendfile ()
  68 returns, this variable
  69 will be set to the offset of the byte following the last byte that was read.
  70 If
  71 .I offset
  72 is not NULL, then
  73 .BR sendfile ()
  74 does not modify the current file offset of
  75 .IR in_fd ;
  76 otherwise the current file offset is adjusted to reflect
  77 the number of bytes read from
  78 .IR in_fd .
  79
  80 If
  81 .I offset
  82 is NULL, then data will be read from
  83 .IR in_fd
  84 starting at the current file offset,
  85 and the file offset will be updated by the call.
  86
  87 .I count
  88 is the number of bytes to copy between the file descriptors.
  89
  90 The
  91 .IR in_fd
  92 argument must correspond to a file which supports
  93 .BR mmap (2)-like
  94 operations
  95 (i.e., it cannot be a socket).
  96
  97 In Linux kernels before 2.6.33,
  98 .I out_fd
  99 must refer to a socket.
 100 Since Linux 2.6.33 it can be any file.
 101 If it is a regular file, then
 102 .BR sendfile ()
 103 changes the file offset appropriately.
 104 .SH "RETURN VALUE"
 105 If the transfer was successful, the number of bytes written to
 106 .I out_fd
 107 is returned.
 108 On error, \-1 is returned, and
 109 .I errno
 110 is set appropriately.
 111 .SH ERRORS
 112 .TP
 113 .B EAGAIN
 114 Nonblocking I/O has been selected using
 115 .B O_NONBLOCK
 116 and the write would block.
 117 .TP
 118 .B EBADF
 119 The input file was not opened for reading or the output file
 120 was not opened for writing.
 121 .TP
 122 .B EFAULT
 123 Bad address.
 124 .TP
 125 .B EINVAL
 126 Descriptor is not valid or locked, or an
 127 .BR mmap (2)-like
 128 operation is not available for
 129 .IR in_fd .
 130 .TP
 131 .B EIO
 132 Unspecified error while reading from
 133 .IR in_fd .
 134 .TP
 135 .B ENOMEM
 136 Insufficient memory to read from
 137 .IR in_fd .
 138 .SH VERSIONS
 139 .BR sendfile ()
 140 is a new feature in Linux 2.2.
 141 The include file
 142 .I <sys/sendfile.h>
 143 is present since glibc 2.1.
 144 .SH "CONFORMING TO"
 145 Not specified in POSIX.1-2001, or other standards.
 146
 147 Other UNIX systems implement
 148 .BR sendfile ()
 149 with different semantics and prototypes.
 150 It should not be used in portable programs.
 151 .SH NOTES
 152 If you plan to use
 153 .BR sendfile ()
 154 for sending files to a TCP socket, but need
 155 to send some header data in front of the file contents, you will find
 156 it useful to employ the
 157 .B TCP_CORK
 158 option, described in
 159 .BR tcp (7),
 160 to minimize the number of packets and to tune performance.
 161
 162 In Linux 2.4 and earlier,
 163 .I out_fd
 164 could also refer to a regular file, and
 165 .BR sendfile ()
 166 changed the current offset of that file.
 167
 168 The original Linux
 169 .BR sendfile ()
 170 system call was not designed to handle large file offsets.
 171 Consequently, Linux 2.4 added
 172 .BR sendfile64 (),
 173 with a wider type for the
 174 .I offset
 175 argument.
 176 The glibc
 177 .BR sendfile ()
 178 wrapper function transparently deals with the kernel differences.
 179
 180 Applications may wish to fall back to
 181 .BR read (2)/ write (2)
 182 in the case where
 183 .BR sendfile ()
 184 fails with
 185 .B EINVAL
 186 or
 187 .BR ENOSYS .
 188
 189 The Linux-specific
 190 .BR splice (2)
 191 call supports transferring data between arbitrary files
 192 (e.g., a pair of sockets).
 193 .SH "SEE ALSO"
 194 .BR mmap (2),
 195 .BR open (2),
 196 .BR socket (2),
 197 .BR splice (2)
 198