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.
  14
  15 The
  16 .BR splice ()
  17 function splices
  18 .I bytes
  19 of  data between file descriptor
  20 .I fd_in
  21 and
  22 .IR fd_out ,
  23 where one of the descriptors must refer to a pipe. The
  24 .I flags
  25 argument is a series of modifier flags:
  26
  27 .TP 1.9i
  28 .B SPLICE_F_MOVE
  29 Attempt to move pages instead of copying.
  30 .TP
  31 .B SPLICE_F_NONBLOCK
  32 Do not block on io.
  33 .TP
  34 .B SPLICE_F_MORE
  35 More data will be coming in a subsequent splice. This is a helpful hint when
  36 the output descriptor refers to a socket, see also
  37 .B MSG_MORE
  38 (see
  39 .BR send (2)
  40 and
  41 .B TCP_CORK
  42 .BR tcp (7))
  43 .TP
  44 .B SPLICE_F_GIFT
  45 See
  46 .BR vmsplice (2).
  47
  48 .SH RETURN VALUE
  49 Upon successful completion,
  50 .BR splice ()
  51 shall return the number of bytes
  52 spliced to or from the pipe. Otherwise, it shall return a value of -1 and
  53 .I errno
  54 shall be set to indicate an error.
  55
  56 .SH ERRORS
  57 .TP 1.1i
  58 .B EBADF
  59 File descriptors either not valid, or do not have proper rw permission.
  60 .TP
  61 .B EINVAL
  62 Target file system doesn't support splicing, none of the descriptors refer
  63 to a pipe or offset given for non-seekable device.
  64
  65 .SH HISTORY
  66 The
  67 .BR splice (2)
  68 system call first appeared in Linux-2.6.17.
  69
  70 .SH SEE ALSO
  71 .BR splice (2),
  72 .BR tee (2)
  73
  74 .SH AUTHORS
  75 Jens Axboe <axboe@suse.de>