| .\" This man page is Copyright (C) 1998 Pawel Krawczyk. |
| .\" Permission is granted to distribute possibly modified copies |
| .\" of this page provided the header is included verbatim, |
| .\" and in case of nontrivial modification author and date |
| .\" of the modification is added to the header. |
| .\" $Id: sendfile.2,v 1.5 1999/05/18 11:54:11 freitag Exp $ |
| .\" 2000-11-19 bert hubert <ahu@ds9a.nl>: in_fd cannot be socket |
| .\" |
| .\" 2004-12-17, mtk |
| .\" updated description of in_fd and out_fd for 2.6 |
| .\" Various wording and formatting changes |
| .\" |
| .\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements |
| .\" |
| .TH SENDFILE 2 2011-09-14 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| sendfile \- transfer data between file descriptors |
| .SH SYNOPSIS |
| .B #include <sys/sendfile.h> |
| .sp |
| .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \ |
| offset ", size_t" " count" ); |
| .\" The below is too ugly. Comments about glibc versions belong |
| .\" in the notes, not in the header. |
| .\" |
| .\" .B #include <features.h> |
| .\" .br |
| .\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2 |
| .\" .br |
| .\" .B #include <sys/sendfile.h> |
| .\" .br |
| .\" #else |
| .\" .br |
| .\" .B #include <sys/types.h> |
| .\" .br |
| .\" .B /* No system prototype before glibc 2.1. */ |
| .\" .br |
| .\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \ |
| .\" offset ", size_t" " count" ) |
| .\" .br |
| .\" .B #endif |
| .\" |
| .SH DESCRIPTION |
| .BR sendfile () |
| copies data between one file descriptor and another. |
| Because this copying is done within the kernel, |
| .BR sendfile () |
| is more efficient than the combination of |
| .BR read (2) |
| and |
| .BR write (2), |
| which would require transferring data to and from user space. |
| |
| .I in_fd |
| should be a file descriptor opened for reading and |
| .I out_fd |
| should be a descriptor opened for writing. |
| |
| If |
| .I offset |
| is not NULL, then it points |
| to a variable holding the file offset from which |
| .BR sendfile () |
| will start reading data from |
| .IR in_fd . |
| When |
| .BR sendfile () |
| returns, this variable |
| will be set to the offset of the byte following the last byte that was read. |
| If |
| .I offset |
| is not NULL, then |
| .BR sendfile () |
| does not modify the current file offset of |
| .IR in_fd ; |
| otherwise the current file offset is adjusted to reflect |
| the number of bytes read from |
| .IR in_fd . |
| |
| If |
| .I offset |
| is NULL, then data will be read from |
| .IR in_fd |
| starting at the current file offset, |
| and the file offset will be updated by the call. |
| |
| .I count |
| is the number of bytes to copy between the file descriptors. |
| |
| The |
| .IR in_fd |
| argument must correspond to a file which supports |
| .BR mmap (2)-like |
| operations |
| (i.e., it cannot be a socket). |
| |
| In Linux kernels before 2.6.33, |
| .I out_fd |
| must refer to a socket. |
| Since Linux 2.6.33 it can be any file. |
| If it is a regular file, then |
| .BR sendfile () |
| changes the file offset appropriately. |
| .SH "RETURN VALUE" |
| If the transfer was successful, the number of bytes written to |
| .I out_fd |
| is returned. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .TP |
| .B EAGAIN |
| Nonblocking I/O has been selected using |
| .B O_NONBLOCK |
| and the write would block. |
| .TP |
| .B EBADF |
| The input file was not opened for reading or the output file |
| was not opened for writing. |
| .TP |
| .B EFAULT |
| Bad address. |
| .TP |
| .B EINVAL |
| Descriptor is not valid or locked, or an |
| .BR mmap (2)-like |
| operation is not available for |
| .IR in_fd . |
| .TP |
| .B EIO |
| Unspecified error while reading from |
| .IR in_fd . |
| .TP |
| .B ENOMEM |
| Insufficient memory to read from |
| .IR in_fd . |
| .SH VERSIONS |
| .BR sendfile () |
| is a new feature in Linux 2.2. |
| The include file |
| .I <sys/sendfile.h> |
| is present since glibc 2.1. |
| .SH "CONFORMING TO" |
| Not specified in POSIX.1-2001, or other standards. |
| |
| Other UNIX systems implement |
| .BR sendfile () |
| with different semantics and prototypes. |
| It should not be used in portable programs. |
| .SH NOTES |
| If you plan to use |
| .BR sendfile () |
| for sending files to a TCP socket, but need |
| to send some header data in front of the file contents, you will find |
| it useful to employ the |
| .B TCP_CORK |
| option, described in |
| .BR tcp (7), |
| to minimize the number of packets and to tune performance. |
| |
| In Linux 2.4 and earlier, |
| .I out_fd |
| could also refer to a regular file, and |
| .BR sendfile () |
| changed the current offset of that file. |
| |
| The original Linux |
| .BR sendfile () |
| system call was not designed to handle large file offsets. |
| Consequently, Linux 2.4 added |
| .BR sendfile64 (), |
| with a wider type for the |
| .I offset |
| argument. |
| The glibc |
| .BR sendfile () |
| wrapper function transparently deals with the kernel differences. |
| |
| Applications may wish to fall back to |
| .BR read (2)/ write (2) |
| in the case where |
| .BR sendfile () |
| fails with |
| .B EINVAL |
| or |
| .BR ENOSYS . |
| |
| The Linux-specific |
| .BR splice (2) |
| call supports transferring data between arbitrary files |
| (e.g., a pair of sockets). |
| .SH "SEE ALSO" |
| .BR mmap (2), |
| .BR open (2), |
| .BR socket (2), |
| .BR splice (2) |
| |