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 ().
  43
  44 .TP 1.9i
  45 .B SPLICE_F_MOVE
  46 Attempt to move pages instead of copying.
  47 .TP
  48 .B SPLICE_F_NONBLOCK
  49 Do not block on io.
  50 .TP
  51 .B SPLICE_F_MORE
  52 More data will be coming in a subsequent splice.
  53 .TP
  54 .B SPLICE_F_GIFT
  55 The user pages are a gift to the kernel. The application may not reuse this
  56 memory ever, or page cache and on disk data may differ. Data must also be
  57 properly page aligned, both in memory and length.
  58
  59 .SH RETURN VALUE
  60 Upon successful completion,
  61 .BR vmsplice ()
  62 shall return the number of bytes spliced to the pipe. Otherwise, it shall
  63 return a value of -1 and
  64 .I errno
  65 shall be set to indicate an error.
  66
  67 .SH ERRORS
  68 .TP 1.1i
  69 .B EBADF
  70 .I fd
  71 either not valid, or doesn't refer to a pipe.
  72 .TP
  73 .B EINVAL
  74 .I nr_segs
  75 not valid, memory not aligned if
  76 .I SPLICE_F_GIFT
  77 set.
  78
  79 .SH NOTES
  80 .BR vmsplice ()
  81 follows the other vectorized read/write type functions when it comes to
  82 limitations on number of segments being passed in. This limit is
  83 .B IOV_MAX
  84 as defined in
  85 .IR <limits.h> .
  86 At the time of this writing, that limit is 1024.
  87
  88 .SH HISTORY
  89 The
  90 .BR vmsplice (2)
  91 system call first appeared in Linux-2.6.17.
  92
  93 .SH SEE ALSO
  94 .BR splice (2),
  95 .BR tee (2)
  96
  97 .SH AUTHORS
  98 Jens Axboe <axboe@suse.de>