mirror of https://github.com/mkerrisk/man-pages
220 lines
6.3 KiB
Groff
220 lines
6.3 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" This manpage is Copyright (C) 2006 Jens Axboe
|
|
.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.TH SPLICE 2 2006-04-28 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
splice \- splice data to/from a pipe
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #define _GNU_SOURCE
|
|
.B #include <fcntl.h>
|
|
|
|
.BI "long splice(int " fd_in ", off_t *" off_in ", int " fd_out ,
|
|
.BI " off_t *" off_out ", size_t " len \
|
|
", unsigned int " flags );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.BR splice ()
|
|
moves data between two file descriptors
|
|
without copying between kernel address space and user address space.
|
|
It transfers up to
|
|
.I len
|
|
bytes of data from the file descriptor
|
|
.I fd_in
|
|
to the file descriptor
|
|
.IR fd_out ,
|
|
where one of the descriptors must refer to a pipe.
|
|
|
|
If
|
|
.I fd_in
|
|
refers to a pipe, then
|
|
.I off_in
|
|
must be NULL.
|
|
If
|
|
.I fd_in
|
|
does not refer to a pipe and
|
|
.I off_in
|
|
is NULL, then bytes are read from
|
|
.I fd_in
|
|
starting from the current file offset,
|
|
and the current file offset is adjusted appropriately.
|
|
If
|
|
.I fd_in
|
|
does not refer to a pipe and
|
|
.I off_in
|
|
is not NULL, then
|
|
.I off_in
|
|
must point to a buffer which specifies the starting
|
|
offset from which bytes will be read from
|
|
.IR fd_in ;
|
|
in this case, the current file offset of
|
|
.IR fd_in
|
|
is not changed.
|
|
Analogous statements apply for
|
|
.I out_fd
|
|
and
|
|
.IR off_out .
|
|
|
|
The
|
|
.I flags
|
|
argument is a bit mask that is composed by ORing together
|
|
zero or more of the following values:
|
|
.TP 1.9i
|
|
.B SPLICE_F_MOVE
|
|
Attempt to move pages instead of copying.
|
|
This is only a hint to the kernel:
|
|
pages may still be copied if the kernel cannot move the
|
|
pages from the pipe, or if
|
|
the pipe buffers don't refer to full pages.
|
|
.TP
|
|
.B SPLICE_F_NONBLOCK
|
|
Do not block on I/O.
|
|
This makes the splice pipe operations non-blocking, but
|
|
.BR splice ()
|
|
may nevertheless block because the file descriptors that
|
|
are spliced to/from may block (unless they have the
|
|
.BR O_NONBLOCK
|
|
flag set).
|
|
.TP
|
|
.B SPLICE_F_MORE
|
|
More data will be coming in a subsequent splice.
|
|
This is a helpful hint when
|
|
the
|
|
.I fd_out
|
|
refers to a socket (see also the description of
|
|
.B MSG_MORE
|
|
in
|
|
.BR send (2),
|
|
and the description of
|
|
.B TCP_CORK
|
|
in
|
|
.BR tcp (7))
|
|
.TP
|
|
.B SPLICE_F_GIFT
|
|
Unused for
|
|
.BR splice ();
|
|
see
|
|
.BR vmsplice (2).
|
|
.SH RETURN VALUE
|
|
Upon successful completion,
|
|
.BR splice ()
|
|
returns the number of bytes
|
|
spliced to or from the pipe.
|
|
A return value of 0 means that there was no data to transfer,
|
|
and it would not make sense to block, because there are no
|
|
writers connected to the write end of the pipe referred to by
|
|
.IR fd_in .
|
|
|
|
On error,
|
|
.BR splice ()
|
|
returns \-1 and
|
|
.I errno
|
|
is set to indicate the error.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EBADF
|
|
One or both file descriptors are not valid,
|
|
or do not have proper read-write mode.
|
|
.TP
|
|
.B EINVAL
|
|
Target file system doesn't support splicing;
|
|
neither of the descriptors refers to a pipe; or
|
|
offset given for non-seekable device.
|
|
.TP
|
|
.B ENOMEM
|
|
Out of memory.
|
|
.TP
|
|
.B ESPIPE
|
|
Either
|
|
.I off_in
|
|
or
|
|
.I off_out
|
|
was not NULL, but the corresponding file descriptor refers to a pipe.
|
|
.SH VERSIONS
|
|
The
|
|
.BR splice (2)
|
|
system call first appeared in Linux 2.6.17.
|
|
.SH "CONFORMING TO"
|
|
This system call is Linux specific.
|
|
.SH NOTES
|
|
The three system calls
|
|
.BR splice (2),
|
|
.BR vmsplice (2),
|
|
and
|
|
.BR tee (2)),
|
|
provide userspace programs with full control over an arbitrary
|
|
kernel buffer, implemented within the kernel using the same type
|
|
of buffer that is used for a pipe.
|
|
In overview, these system calls perform the following tasks:
|
|
.TP 1.2i
|
|
.BR splice ()
|
|
moves data from the buffer to an arbitrary file descriptor, or vice versa,
|
|
or from one buffer to another.
|
|
.TP
|
|
.BR tee (2)
|
|
"copies" the data from one buffer to another.
|
|
.TP
|
|
.BR vmsplice (2)
|
|
"copies" data from user space into the buffer.
|
|
.PP
|
|
Though we talk of copying, actual copies are generally avoided.
|
|
The kernel does this by implementing a pipe buffer as a set
|
|
of reference-counted pointers to pages of kernel memory.
|
|
The kernel creates "copies" of pages in a buffer by creating new
|
|
pointers (for the output buffer) referring to the pages,
|
|
and increasing the reference counts for the pages:
|
|
only pointers are copied, not the pages of the buffer.
|
|
.\"
|
|
.\" Linus: Now, imagine using the above in a media server, for example.
|
|
.\" Let's say that a year or two has passed, so that the video drivers
|
|
.\" have been updated to be able to do the splice thing, and what can
|
|
.\" you do? You can:
|
|
.\"
|
|
.\" - splice from the (mpeg or whatever - let's just assume that the video
|
|
.\" input is either digital or does the encoding on its own - like they
|
|
.\" pretty much all do) video input into a pipe (remember: no copies - the
|
|
.\" video input will just DMA directly into memory, and splice will just
|
|
.\" set up the pages in the pipe buffer)
|
|
.\" - tee that pipe to split it up
|
|
.\" - splice one end to a file (ie "save the compressed stream to disk")
|
|
.\" - splice the other end to a real-time video decoder window for your
|
|
.\" real-time viewing pleasure.
|
|
.\"
|
|
.\" Linus: Now, the advantage of splice()/tee() is that you can
|
|
.\" do zero-copy movement of data, and unlike sendfile() you can
|
|
.\" do it on _arbitrary_ data (and, as shown by "tee()", it's more
|
|
.\" than just sending the data to somebody else: you can duplicate
|
|
.\" the data and choose to forward it to two or more different
|
|
.\" users - for things like logging etc).
|
|
.\"
|
|
.SH EXAMPLE
|
|
See
|
|
.BR tee (2).
|
|
.SH SEE ALSO
|
|
.BR sendfile (2),
|
|
.BR splice (2),
|
|
.BR tee (2),
|
|
.BR feature_test_macros (7)
|