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 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH VMSPLICE 2 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 vmsplice \- splice user pages to/from a pipe
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  15 .B #include <fcntl.h>
  16 .PP
  17 .BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov ,
  18 .BI "                 size_t " nr_segs ", unsigned int " flags );
  19 .fi
  20 .\" Return type was long before glibc 2.7
  21 .SH DESCRIPTION
  22 .\" Linus: vmsplice() system call to basically do a "write to
  23 .\" the buffer", but using the reference counting and VM traversal
  24 .\" to actually fill the buffer. This means that the user needs to
  25 .\" be careful not to reuse the user-space buffer it spliced into
  26 .\" the kernel-space one (contrast this to "write()", which copies
  27 .\" the actual data, and you can thus reuse the buffer immediately
  28 .\" after a successful write), but that is often easy to do.
  29 If
  30 .I fd
  31 is opened for writing, the
  32 .BR vmsplice ()
  33 system call maps
  34 .I nr_segs
  35 ranges of user memory described by
  36 .I iov
  37 into a pipe.
  38 If
  39 .I fd
  40 is opened for reading,
  41 .\" Since Linux 2.6.23
  42 .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
  43 the
  44 .BR vmsplice ()
  45 system call fills
  46 .I nr_segs
  47 ranges of user memory described by
  48 .I iov
  49 from a pipe.
  50 The file descriptor
  51 .I fd
  52 must refer to a pipe.
  53 .PP
  54 The pointer
  55 .I iov
  56 points to an array of
  57 .I iovec
  58 structures as described in
  59 .BR iovec (3type).
  60 .PP
  61 The
  62 .I flags
  63 argument is a bit mask that is composed by ORing together
  64 zero or more of the following values:
  65 .TP
  66 .B SPLICE_F_MOVE
  67 Unused for
  68 .BR vmsplice ();
  69 see
  70 .BR splice (2).
  71 .TP
  72 .B SPLICE_F_NONBLOCK
  73 .\" Not used for vmsplice
  74 .\" May be in the future -- therefore EAGAIN
  75 Do not block on I/O; see
  76 .BR splice (2)
  77 for further details.
  78 .TP
  79 .B SPLICE_F_MORE
  80 Currently has no effect for
  81 .BR vmsplice (),
  82 but may be implemented in the future; see
  83 .BR splice (2).
  84 .TP
  85 .B SPLICE_F_GIFT
  86 The user pages are a gift to the kernel.
  87 The application may not modify this memory ever,
  88 .\" FIXME . Explain the following line in a little more detail:
  89 otherwise the page cache and on-disk data may differ.
  90 Gifting pages to the kernel means that a subsequent
  91 .BR splice (2)
  92 .B SPLICE_F_MOVE
  93 can successfully move the pages;
  94 if this flag is not specified, then a subsequent
  95 .BR splice (2)
  96 .B SPLICE_F_MOVE
  97 must copy the pages.
  98 Data must also be properly page aligned, both in memory and length.
  99 .\" FIXME
 100 .\" It looks like the page-alignment requirement went away with
 101 .\" commit bd1a68b59c8e3bce45fb76632c64e1e063c3962d
 102 .\"
 103 .\" .... if we expect to later SPLICE_F_MOVE to the cache.
 104 .SH RETURN VALUE
 105 Upon successful completion,
 106 .BR vmsplice ()
 107 returns the number of bytes transferred to the pipe.
 108 On error,
 109 .BR vmsplice ()
 110 returns \-1 and
 111 .I errno
 112 is set to indicate the error.
 113 .SH ERRORS
 114 .TP
 115 .B EAGAIN
 116 .B SPLICE_F_NONBLOCK
 117 was specified in
 118 .IR flags ,
 119 and the operation would block.
 120 .TP
 121 .B EBADF
 122 .I fd
 123 either not valid, or doesn't refer to a pipe.
 124 .TP
 125 .B EINVAL
 126 .I nr_segs
 127 is greater than
 128 .BR IOV_MAX ;
 129 or memory not aligned if
 130 .B SPLICE_F_GIFT
 131 set.
 132 .TP
 133 .B ENOMEM
 134 Out of memory.
 135 .SH VERSIONS
 136 The
 137 .BR vmsplice ()
 138 system call first appeared in Linux 2.6.17;
 139 library support was added to glibc in version 2.5.
 140 .SH STANDARDS
 141 This system call is Linux-specific.
 142 .SH NOTES
 143 .BR vmsplice ()
 144 follows the other vectorized read/write type functions when it comes to
 145 limitations on the number of segments being passed in.
 146 This limit is
 147 .B IOV_MAX
 148 as defined in
 149 .IR <limits.h> .
 150 Currently,
 151 .\" UIO_MAXIOV in kernel source
 152 this limit is 1024.
 153 .PP
 154 .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
 155 .BR vmsplice ()
 156 really supports true splicing only from user memory to a pipe.
 157 In the opposite direction, it actually just copies the data to user space.
 158 But this makes the interface nice and symmetric and enables people to build on
 159 .BR vmsplice ()
 160 with room for future improvement in performance.
 161 .SH SEE ALSO
 162 .BR splice (2),
 163 .BR tee (2),
 164 .BR pipe (7)