VMSPLICE
Section: Linux Programmer's Manual (2)
Updated: 2017-09-15
Index
Return to Main Contents
NAME
vmsplice - splice user pages into a pipe
SYNOPSIS
#define _GNU_SOURCE /* See feature_test_macros(7) */
#include <fcntl.h>
#include <sys/uio.h>
ssize_t vmsplice(int fd, const struct iovec *iov,
unsigned long nr_segs, unsigned int flags);
DESCRIPTION
The
vmsplice()
system call maps
nr_segs
ranges of user memory described by
iov
into a pipe.
The file descriptor
fd
must refer to a pipe.
The pointer
iov
points to an array of
iovec
structures as defined in
<sys/uio.h>:
struct iovec {
void *iov_base; /* Starting address */
size_t iov_len; /* Number of bytes */
};
The
flags
argument is a bit mask that is composed by ORing together
zero or more of the following values:
-
- SPLICE_F_MOVE
-
Unused for
vmsplice();
see
splice(2).
- SPLICE_F_NONBLOCK
-
Do not block on I/O; see
splice(2)
for further details.
- SPLICE_F_MORE
-
Currently has no effect for
vmsplice(),
but may be implemented in the future; see
splice(2).
- SPLICE_F_GIFT
-
The user pages are a gift to the kernel.
The application may not modify this memory ever,
otherwise the page cache and on-disk data may differ.
Gifting pages to the kernel means that a subsequent
splice(2)
SPLICE_F_MOVE
can successfully move the pages;
if this flag is not specified, then a subsequent
splice(2)
SPLICE_F_MOVE
must copy the pages.
Data must also be properly page aligned, both in memory and length.
RETURN VALUE
Upon successful completion,
vmsplice()
returns the number of bytes transferred to the pipe.
On error,
vmsplice()
returns -1 and
errno
is set to indicate the error.
ERRORS
- EAGAIN
-
SPLICE_F_NONBLOCK
was specified in
flags,
and the operation would block.
- EBADF
-
fd
either not valid, or doesn't refer to a pipe.
- EINVAL
-
nr_segs
is greater than
IOV_MAX;
or memory not aligned if
SPLICE_F_GIFT
set.
- ENOMEM
-
Out of memory.
VERSIONS
The
vmsplice()
system call first appeared in Linux 2.6.17;
library support was added to glibc in version 2.5.
CONFORMING TO
This system call is Linux-specific.
NOTES
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
IOV_MAX
as defined in
<limits.h>.
Currently,
this limit is 1024.
SEE ALSO
splice(2),
tee(2),
pipe(7)
COLOPHON
This page is part of release 4.13 of the Linux
man-pages
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
https://www.kernel.org/doc/man-pages/.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUE
-
- ERRORS
-
- VERSIONS
-
- CONFORMING TO
-
- NOTES
-
- SEE ALSO
-
- COLOPHON
-
|
|
- Running on 
-
:
: 