+++ /dev/null
-.\" This manpage is Copyright (C) 2006 Jens Axboe
-.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" 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.
-.\" %%%LICENSE_END
-.\"
-.TH SPLICE 2 2014-12-31 "Linux" "Linux Programmer's Manual"
-.SH NAME
-splice \- splice data to/from a pipe
-.SH SYNOPSIS
-.nf
-.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
-.B #include <fcntl.h>
-
-.BI "ssize_t splice(int " fd_in ", loff_t *" off_in ", int " fd_out ,
-.BI " loff_t *" off_out ", size_t " len \
-", unsigned int " flags );
-.\" Return type was long before glibc 2.7
-.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.
-
-The following semantics apply for
-.I fd_in
-and
-.IR off_in :
-.IP * 3
-If
-.I fd_in
-refers to a pipe, then
-.I off_in
-must be NULL.
-.IP *
-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.
-.IP *
-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
-.I fd_in
-is not changed.
-.PP
-Analogous statements apply for
-.I fd_out
-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.
-The initial implementation of this flag was buggy:
-therefore starting in Linux 2.6.21 it is a no-op
-(but is still permitted in a
-.BR splice ()
-call);
-in the future, a correct implementation may be restored.
-.TP
-.B SPLICE_F_NONBLOCK
-Do not block on I/O.
-This makes the splice pipe operations nonblocking, but
-.BR splice ()
-may nevertheless block because the file descriptors that
-are spliced to/from may block (unless they have the
-.B 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 EAGAIN
-.B SPLICE_F_NONBLOCK
-was specified in
-.IR flags ,
-and the operation would block.
-.TP
-.B EBADF
-One or both file descriptors are not valid,
-or do not have proper read-write mode.
-.TP
-.B EINVAL
-Target filesystem doesn't support splicing;
-target file is opened in append mode;
-.\" The append-mode error is given since 2.6.27; in earlier kernels,
-.\" splice() in append mode was broken
-neither of the descriptors refers to a pipe; or
-offset given for nonseekable 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 ()
-system call first appeared in Linux 2.6.17;
-library support was added to glibc in version 2.5.
-.SH CONFORMING TO
-This system call is Linux-specific.
-.SH NOTES
-The three system calls
-.BR splice (),
-.BR vmsplice (2),
-and
-.BR tee (2),
-provide user-space 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 tee (2),
-.BR vmsplice (2)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
