mirror of https://github.com/mkerrisk/man-pages
155 lines
4.2 KiB
Groff
155 lines
4.2 KiB
Groff
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
||
|
.\"
|
||
|
.\" This manpage is Copyright (C) 2006 Jens Axboe
|
||
|
.\" and Copyright (C) 2006 Michael Kerrisk <mtk-manpages@gmx.net>
|
||
|
.\"
|
||
|
.\" Permission is granted to make and distribute verbatim copies of this
|
||
|
.\" manual provided the copyright notice and this permission notice are
|
||
|
.\" preserved on all copies.
|
||
|
.\"
|
||
|
.\" Permission is granted to copy and distribute modified versions of this
|
||
|
.\" manual under the conditions for verbatim copying, provided that the
|
||
|
.\" entire resulting derived work is distributed under the terms of a
|
||
|
.\" permission notice identical to this one.
|
||
|
.\"
|
||
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
||
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
||
|
.\" responsibility for errors or omissions, or for damages resulting from
|
||
|
.\" the use of the information contained herein. The author(s) may not
|
||
|
.\" have taken the same level of care in the production of this manual,
|
||
|
.\" which is licensed free of charge, as they might when working
|
||
|
.\" professionally.
|
||
|
.\"
|
||
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||
|
.\" the source, must acknowledge the copyright and authors of this work.
|
||
|
.\"
|
||
|
.TH vmsplice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
|
||
|
.SH NAME
|
||
|
vmsplice \- splice user pages into a pipe
|
||
|
.SH SYNOPSIS
|
||
|
.nf
|
||
|
.B #define _GNU_SOURCE
|
||
|
.B #include <fcntl.h>
|
||
|
.B #include <sys/uio.h>
|
||
|
|
||
|
.BI "long vmsplice(int " fd ", const struct iovec *" iov ,
|
||
|
.BI " unsigned long " nr_segs ", unsigned int " flags );
|
||
|
.fi
|
||
|
.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 re-use the user-space buffer it spliced into
|
||
|
.\" the kernel-space one (contrast this to "write()", which copies
|
||
|
.\" the actual data, and you can thus re-use the buffer immediately
|
||
|
.\" after a successful write), but that is often easy to do.
|
||
|
The
|
||
|
.BR vmsplice ()
|
||
|
system call maps
|
||
|
.I nr_segs
|
||
|
ranges of user memory described by
|
||
|
.I iov
|
||
|
into a pipe.
|
||
|
The file descriptor
|
||
|
.I fd
|
||
|
must refer to a pipe.
|
||
|
|
||
|
The pointer
|
||
|
.I iov
|
||
|
points to an array of
|
||
|
.I iovec
|
||
|
structures as defined in
|
||
|
.IR <sys/uio.h> :
|
||
|
|
||
|
.in +0.25i
|
||
|
.nf
|
||
|
struct iovec {
|
||
|
void *iov_base; /* Starting address */
|
||
|
size_t iov_len; /* Number of bytes */
|
||
|
};
|
||
|
.in -0.25i
|
||
|
.fi
|
||
|
|
||
|
The
|
||
|
.I flags
|
||
|
argument is a bit mask that is composed by ORing together
|
||
|
zero or more of the following values:
|
||
|
.TP 1.9i
|
||
|
.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:
|
||
|
or page cache and on-disk data may differ.
|
||
|
Gifting pages to the kernel means that a subsequent
|
||
|
.BR splice ()
|
||
|
.B SPLICE_F_MOVE
|
||
|
can successfully move the pages;
|
||
|
if this flag is not specified, then a subsequent
|
||
|
.BR splice ()
|
||
|
.B SPLICE_F_MOVE
|
||
|
must copy the pages.
|
||
|
Data must also be properly page aligned, both in memory and length.
|
||
|
.\" .... 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 vmplice ()
|
||
|
returns \-1 and
|
||
|
.I errno
|
||
|
is set to indicate the error.
|
||
|
.SH ERRORS
|
||
|
.TP
|
||
|
.B EBADF
|
||
|
.I fd
|
||
|
either not valid, or doesn't refer to a pipe.
|
||
|
.TP
|
||
|
.B EINVAL
|
||
|
.I nr_segs
|
||
|
is 0 or greater than
|
||
|
.BR IOV_MAX;
|
||
|
or memory not aligned if
|
||
|
.B SPLICE_F_GIFT
|
||
|
set.
|
||
|
.TP
|
||
|
.B ENOMEM
|
||
|
Out of memory.
|
||
|
.SH NOTES
|
||
|
.BR vmsplice ()
|
||
|
follows the other vectorized read/write type functions when it comes to
|
||
|
limitations on number of segments being passed in.
|
||
|
This limit is
|
||
|
.B IOV_MAX
|
||
|
as defined in
|
||
|
.IR <limits.h> .
|
||
|
At the time of this writing, that limit is 1024.
|
||
|
.SH HISTORY
|
||
|
The
|
||
|
.BR vmsplice (2)
|
||
|
system call first appeared in Linux-2.6.17.
|
||
|
.SH "CONFORMING TO"
|
||
|
This system call is Linux specific.
|
||
|
.SH SEE ALSO
|
||
|
.BR splice (2),
|
||
|
.BR tee (2)
|