splice.2

   1 .TH splice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
   2 .SH NAME
   3 splice \- splice data to/from a pipe.
   4 .SH SYNOPSIS
   5 .B #include <sys/splice.h>
   6
   7 .B long splice(int fd_in, loff_t *off_in, int fd_out, loff_t *off_out, size_t bytes, unsigned int flags);
   8
   9 .SH DESCRIPTION
  10 The act of splicing can be seen as a way to connect two ends of a rope
  11 through a kernel buffer, where that buffer is implemented as a pipe. It
  12 provides a means to move data around without copying it to/from kernel/user
  13 address space, basically a random kernel buffer that the user has full
  14 control over.
  15
  16 The
  17 .BR splice ()
  18 function splices
  19 .I bytes
  20 of  data between file descriptor
  21 .I fd_in
  22 and
  23 .IR fd_out ,
  24 where one of the descriptors must refer to a pipe. The
  25 .I flags
  26 argument is a series of modifier flags:
  27
  28 .TP 1.9i
  29 .B SPLICE_F_MOVE
  30 Attempt to move pages instead of copying. This is only a hint to the kernel,
  31 pages may still be copied if we fail in stealing it out of the pipe or if
  32 the pipe buffers don't refer to full pages.
  33 .TP
  34 .B SPLICE_F_NONBLOCK
  35 Do not block on io.
  36 .TP
  37 .B SPLICE_F_MORE
  38 More data will be coming in a subsequent splice. This is a helpful hint when
  39 the output descriptor refers to a socket, see also
  40 .B MSG_MORE
  41 (see
  42 .BR send (2)
  43 and
  44 .B TCP_CORK
  45 .BR tcp (7))
  46 .TP
  47 .B SPLICE_F_GIFT
  48 See
  49 .BR vmsplice (2).
  50
  51 .SH RETURN VALUE
  52 Upon successful completion,
  53 .BR splice ()
  54 shall return the number of bytes
  55 spliced to or from the pipe. Otherwise, it shall return a value of -1 and
  56 .I errno
  57 shall be set to indicate an error.
  58
  59 .SH ERRORS
  60 .TP 1.1i
  61 .B EBADF
  62 File descriptors either not valid, or do not have proper rw permission.
  63 .TP
  64 .B EINVAL
  65 Target file system doesn't support splicing, none of the descriptors refer
  66 to a pipe or offset given for non-seekable device.
  67 .TP
  68 .B ENOMEM
  69 Ran out of memory.
  70
  71 .SH HISTORY
  72 The
  73 .BR splice (2)
  74 system call first appeared in Linux-2.6.17.
  75
  76 .SH SEE ALSO
  77 .BR splice (2),
  78 .BR tee (2)
  79
  80 .SH AUTHORS
  81 Jens Axboe <axboe@kernel.dk>