2004-11-03 13:51:07 +00:00
|
|
|
.\" 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 15:27:42 +00:00
|
|
|
.\"
|
|
|
|
|
.\" 2004-12-17, mtk
|
|
|
|
|
.\" updated description of in_fd and out_fd for 2.6
|
|
|
|
|
.\" Various wording and formatting changes
|
|
|
|
|
.\"
|
2005-03-31 14:42:09 +00:00
|
|
|
.\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements
|
|
|
|
|
.\"
|
2011-09-14 05:47:18 +00:00
|
|
|
.TH SENDFILE 2 2011-09-14 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
|
sendfile \- transfer data between file descriptors
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
.B #include <sys/sendfile.h>
|
|
|
|
|
.sp
|
2005-03-31 14:42:09 +00:00
|
|
|
.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
|
|
|
|
|
offset ", size_t" " count" );
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" The below is too ugly. Comments about glibc versions belong
|
|
|
|
|
.\" in the notes, not in the header.
|
|
|
|
|
.\"
|
|
|
|
|
.\" .B #include <features.h>
|
|
|
|
|
.\" .br
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" .br
|
|
|
|
|
.\" .B #include <sys/sendfile.h>
|
|
|
|
|
.\" .br
|
|
|
|
|
.\" #else
|
|
|
|
|
.\" .br
|
|
|
|
|
.\" .B #include <sys/types.h>
|
|
|
|
|
.\" .br
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" .B /* No system prototype before glibc 2.1. */
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" .br
|
2005-03-31 14:42:09 +00:00
|
|
|
.\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
|
|
|
|
|
.\" offset ", size_t" " count" )
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" .br
|
|
|
|
|
.\" .B #endif
|
|
|
|
|
.\"
|
|
|
|
|
.SH DESCRIPTION
|
2004-12-17 15:27:42 +00:00
|
|
|
.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.
|
|
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
.I in_fd
|
|
|
|
|
should be a file descriptor opened for reading and
|
|
|
|
|
.I out_fd
|
|
|
|
|
should be a descriptor opened for writing.
|
2004-12-17 15:27:42 +00:00
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
If
|
2004-11-03 13:51:07 +00:00
|
|
|
.I offset
|
2006-07-10 15:48:17 +00:00
|
|
|
is not NULL, then it points
|
|
|
|
|
to a variable holding the file offset from which
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR sendfile ()
|
2004-12-17 15:27:42 +00:00
|
|
|
will start reading data from
|
|
|
|
|
.IR in_fd .
|
2007-04-12 22:42:49 +00:00
|
|
|
When
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR sendfile ()
|
|
|
|
|
returns, this variable
|
|
|
|
|
will be set to the offset of the byte following the last byte that was read.
|
2006-07-10 15:48:17 +00:00
|
|
|
If
|
|
|
|
|
.I offset
|
|
|
|
|
is not NULL, then
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR sendfile ()
|
2007-04-12 22:42:49 +00:00
|
|
|
does not modify the current file offset of
|
2006-07-10 15:48:17 +00:00
|
|
|
.IR in_fd ;
|
2007-04-12 22:42:49 +00:00
|
|
|
otherwise the current file offset is adjusted to reflect
|
2006-07-10 15:48:17 +00:00
|
|
|
the number of bytes read from
|
2004-12-17 15:27:42 +00:00
|
|
|
.IR in_fd .
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2010-02-15 04:26:45 +00:00
|
|
|
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.
|
|
|
|
|
|
2004-12-17 15:27:42 +00:00
|
|
|
.I count
|
|
|
|
|
is the number of bytes to copy between the file descriptors.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2011-09-08 21:10:02 +00:00
|
|
|
The
|
|
|
|
|
.IR in_fd
|
|
|
|
|
argument must correspond to a file which supports
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR mmap (2)-like
|
2005-10-20 15:11:10 +00:00
|
|
|
operations
|
2011-09-11 15:58:43 +00:00
|
|
|
(i.e., it cannot be a socket).
|
2011-09-11 17:28:14 +00:00
|
|
|
|
2011-09-11 15:58:43 +00:00
|
|
|
In Linux kernels before 2.6.33,
|
2004-12-17 15:27:42 +00:00
|
|
|
.I out_fd
|
|
|
|
|
must refer to a socket.
|
2011-09-11 15:58:43 +00:00
|
|
|
Since Linux 2.6.33 it can be any file.
|
|
|
|
|
If it is a regular file, then
|
2011-09-23 05:11:27 +00:00
|
|
|
.BR sendfile ()
|
2011-09-17 03:16:43 +00:00
|
|
|
changes the file offset appropriately.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
|
|
|
|
If the transfer was successful, the number of bytes written to
|
|
|
|
|
.I out_fd
|
2007-04-12 22:42:49 +00:00
|
|
|
is returned.
|
|
|
|
|
On error, \-1 is returned, and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
|
|
|
|
is set appropriately.
|
|
|
|
|
.SH ERRORS
|
|
|
|
|
.TP
|
|
|
|
|
.B EAGAIN
|
2010-01-16 17:02:43 +00:00
|
|
|
Nonblocking I/O has been selected using
|
2004-11-03 13:51:07 +00:00
|
|
|
.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
|
2007-04-12 22:42:49 +00:00
|
|
|
Descriptor is not valid or locked, or an
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR mmap (2)-like
|
2005-03-31 14:42:09 +00:00
|
|
|
operation is not available for
|
|
|
|
|
.IR in_fd .
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
|
.B EIO
|
|
|
|
|
Unspecified error while reading from
|
|
|
|
|
.IR in_fd .
|
|
|
|
|
.TP
|
|
|
|
|
.B ENOMEM
|
|
|
|
|
Insufficient memory to read from
|
|
|
|
|
.IR in_fd .
|
|
|
|
|
.SH VERSIONS
|
2004-12-17 15:27:42 +00:00
|
|
|
.BR sendfile ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is a new feature in Linux 2.2.
|
2007-12-09 08:08:53 +00:00
|
|
|
The include file
|
|
|
|
|
.I <sys/sendfile.h>
|
|
|
|
|
is present since glibc 2.1.
|
2006-08-04 12:39:17 +00:00
|
|
|
.SH "CONFORMING TO"
|
|
|
|
|
Not specified in POSIX.1-2001, or other standards.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
intro.1, time.1, accept.2, bind.2, connect.2, execve.2, flock.2, getdents.2, getpriority.2, getuid.2, intro.2, ioctl.2, mincore.2, mknod.2, personality.2, ptrace.2, read.2, recv.2, select_tut.2, send.2, sendfile.2, shmctl.2, sigaction.2, signal.2, stat.2, times.2, truncate.2, umask.2, wait.2, MB_CUR_MAX.3, MB_LEN_MAX.3, argz_add.3, btowc.3, clearenv.3, clock.3, cmsg.3, end.3, endian.3, errno.3, exit.3, fgetwc.3, fgetws.3, fopen.3, fputwc.3, fputws.3, fseek.3, fwide.3, getfsent.3, getgrnam.3, gethostid.3, getipnodebyname.3, getmntent.3, getpwnam.3, getwchar.3, grantpt.3, iconv.3, iconv_close.3, iconv_open.3, insque.3, intro.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, malloc.3, mblen.3, mbrlen.3, mbrtowc.3, mbsinit.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, mkstemp.3, mktemp.3, nl_langinfo.3, openpty.3, posix_openpt.3, printf.3, ptsname.3, putwchar.3, qecvt.3, rcmd.3, readdir.3, rexec.3, rpc.3, setnetgrent.3, shm_open.3, sigpause.3, stdin.3, stpcpy.3, strftime.3, strptime.3, syslog.3, towctrans.3, towlower.3, towupper.3, ttyslot.3, ungetwc.3, unlocked_stdio.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscasecmp.3, wcscat.3, wcschr.3, wcscmp.3, wcscpy.3, wcscspn.3, wcsdup.3, wcslen.3, wcsncasecmp.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcspbrk.3, wcsrchr.3, wcsrtombs.3, wcsspn.3, wcsstr.3, wcstok.3, wcstombs.3, wcswidth.3, wctob.3, wctomb.3, wctrans.3, wctype.3, wcwidth.3, wmemchr.3, wmemcmp.3, wmemcpy.3, wmemmove.3, wmemset.3, wprintf.3, console_ioctl.4, pts.4, elf.5, filesystems.5, hosts.5, proc.5, ttytype.5, boot.7, capabilities.7, credentials.7, epoll.7, glob.7, koi8-r.7, path_resolution.7, pty.7, signal.7, suffixes.7, time.7, unicode.7, unix.7, uri.7, utf-8.7: global fix: s/Unix/UNIX/
The man pages were rather inconsistent in the use of "Unix"
versus "UNIX". Let's go with the trademark usage.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-12 04:45:38 +00:00
|
|
|
Other UNIX systems implement
|
2004-12-17 15:27:42 +00:00
|
|
|
.BR sendfile ()
|
2007-04-12 22:42:49 +00:00
|
|
|
with different semantics and prototypes.
|
2006-07-10 15:48:17 +00:00
|
|
|
It should not be used in portable programs.
|
2007-05-19 04:30:20 +00:00
|
|
|
.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
|
2011-09-11 15:58:43 +00:00
|
|
|
could also refer to a regular file, and
|
2007-05-19 04:30:20 +00:00
|
|
|
.BR sendfile ()
|
2011-09-19 02:42:00 +00:00
|
|
|
changed the current offset of that file.
|
2010-11-21 06:10:52 +00:00
|
|
|
|
|
|
|
|
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.
|
2011-09-11 17:29:04 +00:00
|
|
|
|
|
|
|
|
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 .
|
2011-09-14 05:47:18 +00:00
|
|
|
|
|
|
|
|
The Linux-specific
|
|
|
|
|
.BR splice (2)
|
|
|
|
|
call supports transferring data between arbitrary files
|
|
|
|
|
(e.g., a pair of sockets).
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
2005-03-31 14:42:09 +00:00
|
|
|
.BR mmap (2),
|
2008-09-18 12:30:44 +00:00
|
|
|
.BR open (2),
|
2006-09-18 12:32:48 +00:00
|
|
|
.BR socket (2),
|
|
|
|
|
.BR splice (2)
|
|
|
|
|
|