vmsplice.2

   1 .TH vmsplice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
   2 .SH NAME
   3 vmsplice \- splice user pages into a pipe
   4 .SH SYNOPSIS
   5 .B #include <sys/uio.h>
   6
   7 .B long vmsplice(int fd, const struct iovec *iov, unsigned long nr_segs, unsigned ing flags);
   8
   9 .SH DESCRIPTION
  10 The
  11 .BR vmsplice ()
  12 function maps
  13 .I nr_segs
  14 range(s) of
  15 .I iov
  16 described user memory into a pipe. The
  17 .I fd must refer to a pipe.
  18
  19 The pointer
  20 .I iov
  21 points to an array of
  22 .I struct iovec
  23 entries as defined in
  24 .IR <sys/uio.h> :
  25
  26 .nf
  27   struct iovec {
  28         void *iov_base;         /* Starting address */
  29         size_t iov_len;         /* Number of bytes */
  30   };
  31 .fi
  32
  33 The
  34 .I flags
  35 argument is a series of modifier flags. Only
  36 .B SPLICE_F_NONBLOCK
  37 and
  38 .B SPLICE_F_GIFT
  39 really apply to
  40 .BR vmsplice ()
  41 , the but the scope is shared with
  42 .BR splice (2).
  43
  44 .TP 1.9i
  45 .B SPLICE_F_MOVE
  46 See
  47 .BR splice (2).
  48 .TP
  49 .B SPLICE_F_NONBLOCK
  50 Do not block on io.
  51 .TP
  52 .B SPLICE_F_MORE
  53 More data will be coming in a subsequent splice.
  54 .TP
  55 .B SPLICE_F_GIFT
  56 The user pages are a gift to the kernel. The application may not reuse this
  57 memory ever, or page cache and on disk data may differ. Data must also be
  58 properly page aligned, both in memory and length.
  59
  60 .SH RETURN VALUE
  61 Upon successful completion,
  62 .BR vmsplice ()
  63 shall return the number of bytes spliced to the pipe. Otherwise, it shall
  64 return a value of -1 and
  65 .I errno
  66 shall be set to indicate an error.
  67
  68 .SH ERRORS
  69 .TP 1.1i
  70 .B EBADF
  71 .I fd
  72 either not valid, or doesn't refer to a pipe.
  73 .TP
  74 .B EINVAL
  75 .I nr_segs
  76 not valid, memory not aligned if
  77 .I SPLICE_F_GIFT
  78 set.
  79 .TP
  80 .B ENOMEM
  81 Ran out of memory.
  82
  83 .SH NOTES
  84 .BR vmsplice ()
  85 follows the other vectorized read/write type functions when it comes to
  86 limitations on number of segments being passed in. This limit is
  87 .B IOV_MAX
  88 as defined in
  89 .IR <limits.h> .
  90 At the time of this writing, that limit is 1024.
  91
  92 .SH HISTORY
  93 The
  94 .BR vmsplice (2)
  95 system call first appeared in Linux-2.6.17.
  96
  97 .SH SEE ALSO
  98 .BR splice (2),
  99 .BR tee (2)
 100
 101 .SH AUTHORS
 102 Jens Axboe <axboe@kernel.dk>