2006-09-18 12:35:34 +00:00
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\"
|
|
|
|
.\" This manpage is Copyright (C) 2006 Jens Axboe
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
|
2006-09-18 12:35:34 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2006-09-18 12:35:34 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2006-09-18 12:35:34 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
2009-09-15 03:58:00 +00:00
|
|
|
.TH SPLICE 2 2009-09-15 "Linux" "Linux Programmer's Manual"
|
2006-09-18 12:35:34 +00:00
|
|
|
.SH NAME
|
|
|
|
splice \- splice data to/from a pipe
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
getresuid.2, mremap.2, poll.2, remap_file_pages.2, setresuid.2, splice.2, sync_file_range.2, syscall.2, tee.2, vmsplice.2, INFINITY.3, aio_init.3, asprintf.3, assert_perror.3, basename.3, bsd_signal.3, canonicalize_file_name.3, clog10.3, crypt.3, dl_iterate_phdr.3, dlopen.3, encrypt.3, exp10.3, fcloseall.3, fenv.3, fopencookie.3, ftw.3, getaddrinfo_a.3, getloadavg.3, getutent.3, grantpt.3, hsearch.3, lseek64.3, memmem.3, mempcpy.3, pow10.3, program_invocation_name.3, ptsname.3, putgrent.3, sched_getcpu.3, sincos.3, strchr.3, strfry.3, strnlen.3, strptime.3, strstr.3, strverscmp.3, swab.3, sysv_signal.3, tsearch.3, unlockpt.3, wcwidth.3: Add reference to feature_test_macros(7)
Some pages simply list feature test macro requirements in
the form:
#define #GNU_SOURCE
#include <someheader.h>
For these pages, add a "See feature_test_macros(7)" comment
on the "#define" line.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-31 04:31:47 +00:00
|
|
|
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
2006-09-18 12:35:34 +00:00
|
|
|
.B #include <fcntl.h>
|
|
|
|
|
2009-09-15 03:58:00 +00:00
|
|
|
.BI "ssize_t splice(int " fd_in ", loff_t *" off_in ", int " fd_out ,
|
|
|
|
.BI " loff_t *" off_out ", size_t " len \
|
2006-09-18 12:35:34 +00:00
|
|
|
", unsigned int " flags );
|
2009-09-15 03:58:00 +00:00
|
|
|
.\" Return type was long before glibc 2.7
|
2006-09-18 12:35:34 +00:00
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.BR splice ()
|
2007-04-12 22:42:49 +00:00
|
|
|
moves data between two file descriptors
|
2006-09-18 12:35:34 +00:00
|
|
|
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 ,
|
2007-04-12 22:42:49 +00:00
|
|
|
where one of the descriptors must refer to a pipe.
|
2006-09-18 12:35:34 +00:00
|
|
|
|
|
|
|
If
|
2007-03-18 06:20:17 +00:00
|
|
|
.I fd_in
|
2006-09-18 12:35:34 +00:00
|
|
|
refers to a pipe, then
|
2007-04-12 22:42:49 +00:00
|
|
|
.I off_in
|
2006-09-18 12:35:34 +00:00
|
|
|
must be NULL.
|
|
|
|
If
|
2007-04-12 22:42:49 +00:00
|
|
|
.I fd_in
|
2006-09-18 12:35:34 +00:00
|
|
|
does not refer to a pipe and
|
2007-03-18 06:20:17 +00:00
|
|
|
.I off_in
|
2007-04-12 22:42:49 +00:00
|
|
|
is NULL, then bytes are read from
|
2007-03-18 06:20:17 +00:00
|
|
|
.I fd_in
|
2006-09-18 12:35:34 +00:00
|
|
|
starting from the current file offset,
|
|
|
|
and the current file offset is adjusted appropriately.
|
|
|
|
If
|
2007-04-12 22:42:49 +00:00
|
|
|
.I fd_in
|
2006-09-18 12:35:34 +00:00
|
|
|
does not refer to a pipe and
|
2007-03-18 06:20:17 +00:00
|
|
|
.I off_in
|
2007-04-12 22:42:49 +00:00
|
|
|
is not NULL, then
|
2007-03-18 06:20:17 +00:00
|
|
|
.I off_in
|
2006-09-18 12:35:34 +00:00
|
|
|
must point to a buffer which specifies the starting
|
|
|
|
offset from which bytes will be read from
|
2007-03-18 06:20:17 +00:00
|
|
|
.IR fd_in ;
|
2006-09-18 12:35:34 +00:00
|
|
|
in this case, the current file offset of
|
2007-09-20 16:26:31 +00:00
|
|
|
.I fd_in
|
2006-09-18 12:35:34 +00:00
|
|
|
is not changed.
|
|
|
|
Analogous statements apply for
|
2007-11-17 05:18:32 +00:00
|
|
|
.I fd_out
|
2006-09-18 12:35:34 +00:00
|
|
|
and
|
2007-03-18 06:20:17 +00:00
|
|
|
.IR off_out .
|
2006-09-18 12:35:34 +00:00
|
|
|
|
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
Attempt to move pages instead of copying.
|
2006-09-18 12:35:34 +00:00
|
|
|
This is only a hint to the kernel:
|
2007-04-12 22:42:49 +00:00
|
|
|
pages may still be copied if the kernel cannot move the
|
2006-09-18 12:35:34 +00:00
|
|
|
pages from the pipe, or if
|
|
|
|
the pipe buffers don't refer to full pages.
|
2008-09-26 05:31:14 +00:00
|
|
|
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.
|
2006-09-18 12:35:34 +00:00
|
|
|
.TP
|
|
|
|
.B SPLICE_F_NONBLOCK
|
|
|
|
Do not block on I/O.
|
accept.2, connect.2, eventfd.2, flock.2, open.2, posix_fadvise.2, read.2, recv.2, sched_setscheduler.2, select_tut.2, send.2, signalfd.2, splice.2, timerfd_create.2, write.2, flockfile.3, mkfifo.3, mq_notify.3, mq_open.3, pthread_tryjoin_np.3, scanf.3, random.4, ddp.7, epoll.7, fifo.7, ip.7, pipe.7, socket.7, spufs.7: Global fix: s/non-blocking/nonblocking/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:43:10 +00:00
|
|
|
This makes the splice pipe operations nonblocking, but
|
2006-09-18 12:35:34 +00:00
|
|
|
.BR splice ()
|
|
|
|
may nevertheless block because the file descriptors that
|
|
|
|
are spliced to/from may block (unless they have the
|
2007-09-20 16:26:31 +00:00
|
|
|
.B O_NONBLOCK
|
2006-09-18 12:35:34 +00:00
|
|
|
flag set).
|
|
|
|
.TP
|
|
|
|
.B SPLICE_F_MORE
|
|
|
|
More data will be coming in a subsequent splice.
|
|
|
|
This is a helpful hint when
|
2007-04-12 22:42:49 +00:00
|
|
|
the
|
2006-09-18 12:35:34 +00:00
|
|
|
.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
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2006-09-18 12:35:34 +00:00
|
|
|
.IR fd_in .
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
On error,
|
2006-09-18 12:35:34 +00:00
|
|
|
.BR splice ()
|
|
|
|
returns \-1 and
|
|
|
|
.I errno
|
|
|
|
is set to indicate the error.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
2007-04-12 22:42:49 +00:00
|
|
|
One or both file descriptors are not valid,
|
2006-09-18 12:35:34 +00:00
|
|
|
or do not have proper read-write mode.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
Target file system doesn't support splicing;
|
2009-02-06 19:12:01 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
neither of the descriptors refers to a pipe; or
|
accept.2, access.2, acct.2, clock_nanosleep.2, mbind.2, mincore.2, remap_file_pages.2, sched_setscheduler.2, set_mempolicy.2, splice.2, stat.2, syslog.2, timer_create.2, timerfd_create.2, truncate.2, fenv.3, ferror.3, fflush.3, fgetwc.3, fgetws.3, flockfile.3, fputwc.3, fputws.3, fread.3, getopt.3, gets.3, getwchar.3, glob.3, iconv.3, longjmp.3, pow.3, printf.3, puts.3, putwchar.3, regex.3, rpc.3, scanf.3, setjmp.3, termios.3, unlocked_stdio.3, wcswidth.3, hd.4, rtc.4, st.4, core.5, dir_colors.5, elf.5, proc.5, arp.7, ascii.7, boot.7, bootparam.7, charsets.7, futex.7, ip.7, iso_8859-11.7, man-pages.7, man.7, mdoc.samples.7, path_resolution.7, pipe.7, posixoptions.7, unicode.7, unix.7, uri.7, utf-8.7, ld.so.8: s/non-/non/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 17:20:12 +00:00
|
|
|
offset given for nonseekable device.
|
2006-09-18 12:35:34 +00:00
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
Out of memory.
|
|
|
|
.TP
|
|
|
|
.B ESPIPE
|
2007-04-12 22:42:49 +00:00
|
|
|
Either
|
2006-09-18 12:35:34 +00:00
|
|
|
.I off_in
|
2007-04-12 22:42:49 +00:00
|
|
|
or
|
2006-09-18 12:35:34 +00:00
|
|
|
.I off_out
|
|
|
|
was not NULL, but the corresponding file descriptor refers to a pipe.
|
2007-05-16 04:39:23 +00:00
|
|
|
.SH VERSIONS
|
2006-09-18 12:35:34 +00:00
|
|
|
The
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR splice ()
|
2007-05-29 04:36:42 +00:00
|
|
|
system call first appeared in Linux 2.6.17.
|
2007-05-18 16:30:46 +00:00
|
|
|
.SH "CONFORMING TO"
|
2007-12-25 21:28:09 +00:00
|
|
|
This system call is Linux-specific.
|
2006-09-18 12:35:34 +00:00
|
|
|
.SH NOTES
|
|
|
|
The three system calls
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR splice (),
|
2006-09-18 12:35:34 +00:00
|
|
|
.BR vmsplice (2),
|
|
|
|
and
|
2007-11-17 05:18:32 +00:00
|
|
|
.BR tee (2),
|
2007-04-12 22:42:49 +00:00
|
|
|
provide userspace programs with full control over an arbitrary
|
2006-09-18 12:35:34 +00:00
|
|
|
kernel buffer, implemented within the kernel using the same type
|
2007-04-12 22:42:49 +00:00
|
|
|
of buffer that is used for a pipe.
|
2006-09-18 12:35:34 +00:00
|
|
|
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
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR tee (2)
|
2006-09-18 12:35:34 +00:00
|
|
|
"copies" the data from one buffer to another.
|
|
|
|
.TP
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR vmsplice (2)
|
2006-09-18 12:35:34 +00:00
|
|
|
"copies" data from user space into the buffer.
|
|
|
|
.PP
|
|
|
|
Though we talk of copying, actual copies are generally avoided.
|
2007-04-12 22:42:49 +00:00
|
|
|
The kernel does this by implementing a pipe buffer as a set
|
2006-09-18 12:35:34 +00:00
|
|
|
of reference-counted pointers to pages of kernel memory.
|
2007-04-12 22:42:49 +00:00
|
|
|
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:
|
2006-09-18 12:35:34 +00:00
|
|
|
only pointers are copied, not the pages of the buffer.
|
|
|
|
.\"
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" 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
|
2006-09-18 12:35:34 +00:00
|
|
|
.\" you do? You can:
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2006-09-18 12:35:34 +00:00
|
|
|
.\" - 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
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" video input will just DMA directly into memory, and splice will just
|
2006-09-18 12:35:34 +00:00
|
|
|
.\" 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")
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" - splice the other end to a real-time video decoder window for your
|
2006-09-18 12:35:34 +00:00
|
|
|
.\" real-time viewing pleasure.
|
|
|
|
.\"
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" 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
|
2007-12-22 22:43:42 +00:00
|
|
|
.\" users - for things like logging etc.).
|
2006-09-18 12:35:34 +00:00
|
|
|
.\"
|
|
|
|
.SH EXAMPLE
|
|
|
|
See
|
|
|
|
.BR tee (2).
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR sendfile (2),
|
2007-01-28 20:00:24 +00:00
|
|
|
.BR tee (2),
|
getresuid.2, intro.2, mremap.2, open.2, poll.2, posix_fadvise.2, pread.2, remap_file_pages.2, setresuid.2, signal.2, splice.2, sync_file_range.2, tee.2, vmsplice.2, INFINITY.3, asprintf.3, assert_perror.3, basename.3, bsd_signal.3, canonicalize_file_name.3, clog10.3, crypt.3, dl_iterate_phdr.3, dlopen.3, dprintf.3, encrypt.3, exp10.3, fcloseall.3, fenv.3, ffs.3, fmemopen.3, fopencookie.3, ftw.3, getdate.3, getline.3, getloadavg.3, getopt.3, getsubopt.3, getutent.3, grantpt.3, hsearch.3, intro.3, lseek64.3, memmem.3, mempcpy.3, mq_receive.3, mq_send.3, posix_fallocate.3, pow10.3, program_invocation_name.3, ptsname.3, putgrent.3, readdir.3, sigset.3, sincos.3, stpcpy.3, stpncpy.3, strchr.3, strfry.3, strnlen.3, strptime.3, strsignal.3, strstr.3, strverscmp.3, swab.3, sysv_signal.3, tsearch.3, unlocked_stdio.3, unlockpt.3, wcpcpy.3, wcpncpy.3, wcsdup.3, wcwidth.3: SEE ALSO: Remove redundant reference to feature_test_macros(7)
Reported-by: Florian Lehmann <flo.lehmann@googlemail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-31 05:05:22 +00:00
|
|
|
.BR vmsplice (2)
|