diff options
Diffstat (limited to 'man2/sendfile.2')
-rw-r--r-- | man2/sendfile.2 | 245 |
1 files changed, 0 insertions, 245 deletions
diff --git a/man2/sendfile.2 b/man2/sendfile.2 deleted file mode 100644 index e013fa6..0000000 --- a/man2/sendfile.2 +++ /dev/null @@ -1,245 +0,0 @@ -.\" 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-12-21 "Linux man-pages 6.7" -.SH NAME -sendfile \- transfer data between file descriptors -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <sys/sendfile.h> -.P -.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. -.P -.I in_fd -should be a file descriptor opened for reading and -.I out_fd -should be a descriptor opened for writing. -.P -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 . -.P -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. -.P -.I count -is the number of bytes to copy between the file descriptors. -.P -The -.I in_fd -argument must correspond to a file which supports -.BR mmap (2)-like -operations -(i.e., it cannot be a socket). -Except since Linux 5.12 -.\" commit b964bf53e540262f2d12672b3cca10842c0172e7 -and if -.I out_fd -is a pipe, in which case -.BR sendfile () -desugars to a -.BR splice (2) -and its restrictions apply. -.P -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's seekable, 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. -.P -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. -.P -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. -.P -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.) -.P -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. -.P -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 . -.P -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. -.P -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) |