vmsplice(2)

1vmsplice(2)                   System Calls Manual                  vmsplice(2)
2
3
4

NAME

6       vmsplice - splice user pages to/from a pipe
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #define _GNU_SOURCE         /* See feature_test_macros(7) */
13       #include <fcntl.h>
14
15       ssize_t vmsplice(int fd, const struct iovec *iov,
16                        size_t nr_segs, unsigned int flags);
17

DESCRIPTION

19       If  fd  is  opened for writing, the vmsplice() system call maps nr_segs
20       ranges of user memory described by iov into a pipe.  If  fd  is  opened
21       for  reading,  the  vmsplice() system call fills nr_segs ranges of user
22       memory described by iov from a pipe.  The file descriptor fd must refer
23       to a pipe.
24
25       The  pointer iov points to an array of iovec structures as described in
26       iovec(3type).
27
28       The flags argument is a bit mask that is  composed  by  ORing  together
29       zero or more of the following values:
30
31       SPLICE_F_MOVE
32              Unused for vmsplice(); see splice(2).
33
34       SPLICE_F_NONBLOCK
35              Do not block on I/O; see splice(2) for further details.
36
37       SPLICE_F_MORE
38              Currently  has  no effect for vmsplice(), but may be implemented
39              in the future; see splice(2).
40
41       SPLICE_F_GIFT
42              The user pages are a gift to the kernel.   The  application  may
43              not  modify  this  memory ever, otherwise the page cache and on-
44              disk data may differ.  Gifting pages to the kernel means that  a
45              subsequent  splice(2)  SPLICE_F_MOVE  can  successfully move the
46              pages;  if  this  flag  is  not  specified,  then  a  subsequent
47              splice(2)  SPLICE_F_MOVE must copy the pages.  Data must also be
48              properly page aligned, both in memory and length.
49

RETURN VALUE

51       Upon successful completion, vmsplice()  returns  the  number  of  bytes
52       transferred  to the pipe.  On error, vmsplice() returns -1 and errno is
53       set to indicate the error.
54

ERRORS

56       EAGAIN SPLICE_F_NONBLOCK was specified  in  flags,  and  the  operation
57              would block.
58
59       EBADF  fd either not valid, or doesn't refer to a pipe.
60
61       EINVAL nr_segs  is  greater  than  IOV_MAX;  or  memory  not aligned if
62              SPLICE_F_GIFT set.
63
64       ENOMEM Out of memory.
65

STANDARDS

67       Linux.
68

HISTORY

70       Linux 2.6.17, glibc 2.5.
71

NOTES

73       vmsplice() follows the other vectorized read/write type functions  when
74       it  comes  to  limitations  on  the number of segments being passed in.
75       This limit is IOV_MAX as defined in <limits.h>.  Currently, this  limit
76       is 1024.
77
78       vmsplice()  really  supports  true  splicing only from user memory to a
79       pipe.  In the opposite direction, it actually just copies the  data  to
80       user  space.   But  this makes the interface nice and symmetric and en‐
81       ables people to build on vmsplice() with room for future improvement in
82       performance.
83