diff options
Diffstat (limited to 'man2/sendfile.2')
| -rw-r--r-- | man2/sendfile.2 | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/man2/sendfile.2 b/man2/sendfile.2 new file mode 100644 index 0000000..d9c3451 --- /dev/null +++ b/man2/sendfile.2 @@ -0,0 +1,236 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1998 Pawel Krawczyk. +.\" +.\" $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 2023-07-15 "Linux man-pages 6.05.01" +.SH NAME +sendfile \- transfer data between file descriptors +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/sendfile.h> +.PP +.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", \ +off_t *_Nullable " offset , +.BI " size_t" " count" ); +.\" The below is too ugly. Comments about glibc versions belong +.\" in the notes, not in the header. +.\" +.\" .B #include <features.h> +.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2 +.\" .B #include <sys/sendfile.h> +.\" #else +.\" .B #include <sys/types.h> +.\" .B /* No system prototype before glibc 2.1. */ +.\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \ +.\" offset ", size_t" " count" ) +.\" .B #endif +.\" +.fi +.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. +.PP +.I in_fd +should be a file descriptor opened for reading and +.I out_fd +should be a descriptor opened for writing. +.PP +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 file offset of +.IR in_fd ; +otherwise the file offset is adjusted to reflect +the number of bytes read from +.IR in_fd . +.PP +If +.I offset +is NULL, then data will be read from +.I in_fd +starting at the file offset, +and the file offset will be updated by the call. +.PP +.I count +is the number of bytes to copy between the file descriptors. +.PP +The +.I in_fd +argument must correspond to a file which supports +.BR mmap (2)-like +operations +(i.e., it cannot be a socket). +.PP +Before Linux 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. +Note that a successful call to +.BR sendfile () +may write fewer bytes than requested; +the caller should be prepared to retry the call if there were unsent bytes. +See also NOTES. +.PP +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.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 , +or +.I count +is negative. +.TP +.B EINVAL +.I out_fd +has the +.B O_APPEND +flag set. +This is not currently supported by +.BR sendfile (). +.TP +.B EIO +Unspecified error while reading from +.IR in_fd . +.TP +.B ENOMEM +Insufficient memory to read from +.IR in_fd . +.TP +.B EOVERFLOW +.I count +is too large, the operation would result in exceeding the maximum size of either +the input file or the output file. +.TP +.B ESPIPE +.I offset +is not NULL but the input file is not seekable. +.SH VERSIONS +Other UNIX systems implement +.BR sendfile () +with different semantics and prototypes. +It should not be used in portable programs. +.SH STANDARDS +None. +.SH HISTORY +Linux 2.2, +glibc 2.1. +.PP +In Linux 2.4 and earlier, +.I out_fd +could also refer to a regular file; +this possibility went away in the Linux 2.6.x kernel series, +but was restored in Linux 2.6.33. +.PP +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. +.SH NOTES +.BR sendfile () +will transfer at most 0x7ffff000 (2,147,479,552) bytes, +returning the number of bytes actually transferred. +.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 +(This is true on both 32-bit and 64-bit systems.) +.PP +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. +.PP +Applications may wish to fall back to +.BR read (2) +and +.BR write (2) +in the case where +.BR sendfile () +fails with +.B EINVAL +or +.BR ENOSYS . +.PP +If +.I out_fd +refers to a socket or pipe with zero-copy support, callers must ensure the +transferred portions of the file referred to by +.I in_fd +remain unmodified until the reader on the other end of +.I out_fd +has consumed the transferred data. +.PP +The Linux-specific +.BR splice (2) +call supports transferring data between arbitrary file descriptors +provided one (or both) of them is a pipe. +.SH SEE ALSO +.BR copy_file_range (2), +.BR mmap (2), +.BR open (2), +.BR socket (2), +.BR splice (2) |