diff options
| author | Alejandro Colomar <alx@kernel.org> | 2024-04-26 15:06:49 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2024-05-02 01:24:19 +0200 |
| commit | dcde2f70372b49ec43efc5db864c9ff585d0a2dd (patch) | |
| tree | 78b9b7425130e4a5858e4c01a524d802423879ed /man/man2/vmsplice.2 | |
| parent | 12aca537ce78a41bbcdaf485209691e10f8002d7 (diff) | |
| download | man-pages-dcde2f70372b49ec43efc5db864c9ff585d0a2dd.tar.gz | |
man/, share/mk/: Move man*/ to man/
This is a scripted change:
$ mkdir man/;
$ mv man* man/;
$ ln -st . man/man*;
$ find share/mk/ -type f \
| xargs grep -l '^MANDIR *:=' \
| xargs sed -i '/^MANDIR *:=/s,$,/man,';
$ find share/mk/dist/ -type f \
| xargs grep -l man \
| xargs sed -i 's,man%,man/%,g';
Link: <https://lore.kernel.org/linux-man/YxcV4h+Xn7cd6+q2@pevik/T/>
Cc: Petr Vorel <pvorel@suse.cz>
Cc: Jakub Wilk <jwilk@jwilk.net>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Diffstat (limited to 'man/man2/vmsplice.2')
| -rw-r--r-- | man/man2/vmsplice.2 | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/man/man2/vmsplice.2 b/man/man2/vmsplice.2 new file mode 100644 index 0000000000..819465b235 --- /dev/null +++ b/man/man2/vmsplice.2 @@ -0,0 +1,162 @@ +.\" This manpage is Copyright (C) 2006 Jens Axboe +.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH vmsplice 2 (date) "Linux man-pages (unreleased)" +.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 <fcntl.h> +.P +.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. +.P +The pointer +.I iov +points to an array of +.I iovec +structures as described in +.BR iovec (3type). +.P +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 <limits.h> . +Currently, +.\" UIO_MAXIOV in kernel source +this limit is 1024. +.P +.\" 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) |