man2/vmsplice.2

   1 .\" This manpage is Copyright (C) 2006 Jens Axboe
   2 .\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH VMSPLICE 2 2017-09-15 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 vmsplice \- splice user pages to/from a pipe
  29 .SH SYNOPSIS
  30 .nf
  31 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  32 .B #include <fcntl.h>
  33 .B #include <sys/uio.h>
  34 .PP
  35 .BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov ,
  36 .BI "                 unsigned long " nr_segs ", unsigned int " flags );
  37 .fi
  38 .\" Return type was long before glibc 2.7
  39 .SH DESCRIPTION
  40 .\" Linus: vmsplice() system call to basically do a "write to
  41 .\" the buffer", but using the reference counting and VM traversal
  42 .\" to actually fill the buffer. This means that the user needs to
  43 .\" be careful not to reuse the user-space buffer it spliced into
  44 .\" the kernel-space one (contrast this to "write()", which copies
  45 .\" the actual data, and you can thus reuse the buffer immediately
  46 .\" after a successful write), but that is often easy to do.
  47 If
  48 .I fd
  49 is opened for writing, the
  50 .BR vmsplice ()
  51 system call maps
  52 .I nr_segs
  53 ranges of user memory described by
  54 .I iov
  55 into a pipe.
  56 If
  57 .I fd
  58 is opened for reading,
  59 .\" Since Linux 2.6.23
  60 .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
  61 the
  62 .BR vmsplice ()
  63 system call fills
  64 .I nr_segs
  65 ranges of user memory described by
  66 .I iov
  67 from a pipe.
  68 The file descriptor
  69 .I fd
  70 must refer to a pipe.
  71 .PP
  72 The pointer
  73 .I iov
  74 points to an array of
  75 .I iovec
  76 structures as defined in
  77 .IR <sys/uio.h> :
  78 .PP
  79 .in +4n
  80 .EX
  81 struct iovec {
  82     void  *iov_base;        /* Starting address */
  83     size_t iov_len;         /* Number of bytes */
  84 };
  85 .EE
  86 .in
  87 .PP
  88 The
  89 .I flags
  90 argument is a bit mask that is composed by ORing together
  91 zero or more of the following values:
  92 .TP
  93 .B SPLICE_F_MOVE
  94 Unused for
  95 .BR vmsplice ();
  96 see
  97 .BR splice (2).
  98 .TP
  99 .B SPLICE_F_NONBLOCK
 100 .\" Not used for vmsplice
 101 .\" May be in the future -- therefore EAGAIN
 102 Do not block on I/O; see
 103 .BR splice (2)
 104 for further details.
 105 .TP
 106 .B SPLICE_F_MORE
 107 Currently has no effect for
 108 .BR vmsplice (),
 109 but may be implemented in the future; see
 110 .BR splice (2).
 111 .TP
 112 .B SPLICE_F_GIFT
 113 The user pages are a gift to the kernel.
 114 The application may not modify this memory ever,
 115 .\" FIXME . Explain the following line in a little more detail:
 116 otherwise the page cache and on-disk data may differ.
 117 Gifting pages to the kernel means that a subsequent
 118 .BR splice (2)
 119 .B SPLICE_F_MOVE
 120 can successfully move the pages;
 121 if this flag is not specified, then a subsequent
 122 .BR splice (2)
 123 .B SPLICE_F_MOVE
 124 must copy the pages.
 125 Data must also be properly page aligned, both in memory and length.
 126 .\" FIXME
 127 .\" It looks like the page-alignment requirement went away with
 128 .\" commit bd1a68b59c8e3bce45fb76632c64e1e063c3962d
 129 .\"
 130 .\" .... if we expect to later SPLICE_F_MOVE to the cache.
 131 .SH RETURN VALUE
 132 Upon successful completion,
 133 .BR vmsplice ()
 134 returns the number of bytes transferred to the pipe.
 135 On error,
 136 .BR vmsplice ()
 137 returns \-1 and
 138 .I errno
 139 is set to indicate the error.
 140 .SH ERRORS
 141 .TP
 142 .B EAGAIN
 143 .B SPLICE_F_NONBLOCK
 144 was specified in
 145 .IR flags ,
 146 and the operation would block.
 147 .TP
 148 .B EBADF
 149 .I fd
 150 either not valid, or doesn't refer to a pipe.
 151 .TP
 152 .B EINVAL
 153 .I nr_segs
 154 is greater than
 155 .BR IOV_MAX ;
 156 or memory not aligned if
 157 .B SPLICE_F_GIFT
 158 set.
 159 .TP
 160 .B ENOMEM
 161 Out of memory.
 162 .SH VERSIONS
 163 The
 164 .BR vmsplice ()
 165 system call first appeared in Linux 2.6.17;
 166 library support was added to glibc in version 2.5.
 167 .SH CONFORMING TO
 168 This system call is Linux-specific.
 169 .SH NOTES
 170 .BR vmsplice ()
 171 follows the other vectorized read/write type functions when it comes to
 172 limitations on the number of segments being passed in.
 173 This limit is
 174 .B IOV_MAX
 175 as defined in
 176 .IR <limits.h> .
 177 Currently,
 178 .\" UIO_MAXIOV in kernel source
 179 this limit is 1024.
 180 .PP
 181 .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
 182 .BR vmsplice ()
 183 really supports true splicing only from user memory to a pipe.
 184 In the opposite direction, it actually just copies the data to userspace.
 185 But this makes the interface nice and symmetric and enables people to build on
 186 .BR vmsplice ()
 187 with room for future improvement in performance.
 188 .SH SEE ALSO
 189 .BR splice (2),
 190 .BR tee (2),
 191 .BR pipe (7)