NAME
vmsplice - splice user pages into a pipe
SYNOPSIS
#define _GNU_SOURCE
#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, or 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
EBADF | fd either not valid, or doesnt refer to a pipe. |
EINVAL | nr_segs is 0 or 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.
CONFORMING TO
This system call is Linux-specific.
NOTES
vmsplice() follows the other vectorized read/write type functions when it comes to limitations on number of segments being passed in. This limit is IOV_MAX as defined in <limits.h>. At the time of this writing, that limit is 1024.
SEE ALSO
splice(2), tee(2), feature_test_macros(7)
COLOPHON
This page is part of release 3.23 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.