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 .I offset
  60 is a pointer to a variable holding the file offset from
  61 which
  62 .BR sendfile ()
  63 will start reading data from
  64 .IR in_fd .
  65 When
  66 .BR sendfile ()
  67 returns, this variable
  68 will be set to the offset of the byte following the last byte that was read.
  69 .BR sendfile ()
  70 does not modify the current file offset of
  71 .IR in_fd .
  72
  73 .I count
  74 is the number of bytes to copy between the file descriptors.
  75
  76 Presently (Linux 2.6.9):
  77 .IR in_fd ,
  78 must correspond to a file which supports mmap()-like operations
  79 (i.e., it cannot be a socket);
  80 and
  81 .I out_fd
  82 must refer to a socket.
  83
  84 Applications may wish to fall back to
  85 .BR read (2)/ write (2)
  86 in the case where
  87 .BR sendfile ()
  88 fails with EINVAL or ENOSYS.
  89 .SH NOTES
  90 If you plan to use sendfile for sending files to a TCP socket, but need
  91 to send some header data in front of the file contents, you will find
  92 it useful to employ the
  93 .B TCP_CORK
  94 option, described in
  95 .BR tcp (7),
  96 to minimize the number of packets and to tune performance.
  97
  98 In Linux 2.4 and earlier,
  99 .I out_fd
 100 could refer to a regular file, and
 101 .BR sendfile ()
 102 changed the current offset of that file.
 103 .SH "RETURN VALUE"
 104 If the transfer was successful, the number of bytes written to
 105 .I out_fd
 106 is returned.  On error, \-1 is returned, and
 107 .I errno
 108 is set appropriately.
 109 .SH ERRORS
 110 .TP
 111 .B EAGAIN
 112 Non-blocking I/O has been selected using
 113 .B O_NONBLOCK
 114 and the write would block.
 115 .TP
 116 .B EBADF
 117 The input file was not opened for reading or the output file
 118 was not opened for writing.
 119 .TP
 120 .B EFAULT
 121 Bad address.
 122 .TP
 123 .B EINVAL
 124 Descriptor is not valid or locked, or an mmap()-like
 125 operation is not available for
 126 .IR in_fd .
 127 .TP
 128 .B EIO
 129 Unspecified error while reading from
 130 .IR in_fd .
 131 .TP
 132 .B ENOMEM
 133 Insufficient memory to read from
 134 .IR in_fd .
 135 .SH VERSIONS
 136 .BR sendfile ()
 137 is a new feature in Linux 2.2.
 138 The include file <sys/sendfile.h> is present since glibc2.1.
 139
 140 Other Unixes implement
 141 .BR sendfile ()
 142 with different semantics and prototypes. It should
 143 not be used in portable programs.
 144 .SH "SEE ALSO"
 145 .BR open (2),
 146 .BR mmap (2),
 147 .BR socket (2)