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 2004-12-17 "Linux Man Page" "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 .I count
  81 is the number of bytes to copy between the file descriptors.
  82
  83 Presently (Linux 2.6.9):
  84 .IR in_fd ,
  85 must correspond to a file which supports
  86 .BR mmap ()-like
  87 operations
  88 (i.e., it cannot be a socket);
  89 and
  90 .I out_fd
  91 must refer to a socket.
  92
  93 Applications may wish to fall back to
  94 .BR read (2)/ write (2)
  95 in the case where
  96 .BR sendfile ()
  97 fails with EINVAL or ENOSYS.
  98 .SH NOTES
  99 If you plan to use
 100 .BR sendfile ()
 101 for sending files to a TCP socket, but need
 102 to send some header data in front of the file contents, you will find
 103 it useful to employ the
 104 .B TCP_CORK
 105 option, described in
 106 .BR tcp (7),
 107 to minimize the number of packets and to tune performance.
 108
 109 In Linux 2.4 and earlier,
 110 .I out_fd
 111 could refer to a regular file, and
 112 .BR sendfile ()
 113 changed the current offset of that file.
 114 .SH "RETURN VALUE"
 115 If the transfer was successful, the number of bytes written to
 116 .I out_fd
 117 is returned.  On error, \-1 is returned, and
 118 .I errno
 119 is set appropriately.
 120 .SH ERRORS
 121 .TP
 122 .B EAGAIN
 123 Non-blocking 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 ()-like
 137 operation is not available for
 138 .IR in_fd .
 139 .TP
 140 .B EIO
 141 Unspecified error while reading from
 142 .IR in_fd .
 143 .TP
 144 .B ENOMEM
 145 Insufficient memory to read from
 146 .IR in_fd .
 147 .SH VERSIONS
 148 .BR sendfile ()
 149 is a new feature in Linux 2.2.
 150 The include file <sys/sendfile.h> is present since glibc2.1.
 151 .SH "CONFORMING TO"
 152 Not specified in POSIX.1-2001, or other standards.
 153
 154 Other Unix systems implement
 155 .BR sendfile ()
 156 with different semantics and prototypes.
 157 It should not be used in portable programs.
 158 .SH "SEE ALSO"
 159 .BR open (2),
 160 .BR mmap (2),
 161 .BR socket (2)