From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man2/vmsplice.2 | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 man2/vmsplice.2 (limited to 'man2/vmsplice.2') diff --git a/man2/vmsplice.2 b/man2/vmsplice.2 new file mode 100644 index 0000000..4520b8a --- /dev/null +++ b/man2/vmsplice.2 @@ -0,0 +1,162 @@ +.\" This manpage is Copyright (C) 2006 Jens Axboe +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH vmsplice 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +vmsplice \- splice user pages to/from a pipe +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov , +.BI " size_t " nr_segs ", unsigned int " flags ); +.fi +.\" Return type was long before glibc 2.7 +.SH DESCRIPTION +.\" Linus: vmsplice() system call to basically do a "write to +.\" the buffer", but using the reference counting and VM traversal +.\" to actually fill the buffer. This means that the user needs to +.\" be careful not to reuse the user-space buffer it spliced into +.\" the kernel-space one (contrast this to "write()", which copies +.\" the actual data, and you can thus reuse the buffer immediately +.\" after a successful write), but that is often easy to do. +If +.I fd +is opened for writing, the +.BR vmsplice () +system call maps +.I nr_segs +ranges of user memory described by +.I iov +into a pipe. +If +.I fd +is opened for reading, +.\" Since Linux 2.6.23 +.\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7 +the +.BR vmsplice () +system call fills +.I nr_segs +ranges of user memory described by +.I iov +from a pipe. +The file descriptor +.I fd +must refer to a pipe. +.PP +The pointer +.I iov +points to an array of +.I iovec +structures as described in +.BR iovec (3type). +.PP +The +.I flags +argument is a bit mask that is composed by ORing together +zero or more of the following values: +.TP +.B SPLICE_F_MOVE +Unused for +.BR vmsplice (); +see +.BR splice (2). +.TP +.B SPLICE_F_NONBLOCK +.\" Not used for vmsplice +.\" May be in the future -- therefore EAGAIN +Do not block on I/O; see +.BR splice (2) +for further details. +.TP +.B SPLICE_F_MORE +Currently has no effect for +.BR vmsplice (), +but may be implemented in the future; see +.BR splice (2). +.TP +.B SPLICE_F_GIFT +The user pages are a gift to the kernel. +The application may not modify this memory ever, +.\" FIXME . Explain the following line in a little more detail: +otherwise the page cache and on-disk data may differ. +Gifting pages to the kernel means that a subsequent +.BR splice (2) +.B SPLICE_F_MOVE +can successfully move the pages; +if this flag is not specified, then a subsequent +.BR splice (2) +.B SPLICE_F_MOVE +must copy the pages. +Data must also be properly page aligned, both in memory and length. +.\" FIXME +.\" It looks like the page-alignment requirement went away with +.\" commit bd1a68b59c8e3bce45fb76632c64e1e063c3962d +.\" +.\" .... if we expect to later SPLICE_F_MOVE to the cache. +.SH RETURN VALUE +Upon successful completion, +.BR vmsplice () +returns the number of bytes transferred to the pipe. +On error, +.BR vmsplice () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.B SPLICE_F_NONBLOCK +was specified in +.IR flags , +and the operation would block. +.TP +.B EBADF +.I fd +either not valid, or doesn't refer to a pipe. +.TP +.B EINVAL +.I nr_segs +is greater than +.BR IOV_MAX ; +or memory not aligned if +.B SPLICE_F_GIFT +set. +.TP +.B ENOMEM +Out of memory. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.17, +glibc 2.5. +.SH NOTES +.BR vmsplice () +follows the other vectorized read/write type functions when it comes to +limitations on the number of segments being passed in. +This limit is +.B IOV_MAX +as defined in +.IR . +Currently, +.\" UIO_MAXIOV in kernel source +this limit is 1024. +.PP +.\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7 +.BR vmsplice () +really supports true splicing only from user memory to a pipe. +In the opposite direction, it actually just copies the data to user space. +But this makes the interface nice and symmetric and enables people to build on +.BR vmsplice () +with room for future improvement in performance. +.SH SEE ALSO +.BR splice (2), +.BR tee (2), +.BR pipe (7) -- cgit v1.2.3