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 VMSPLICE 2 2009-09-15 "Linux" "Linux Programmer's Manual"
|
2006-09-18 12:35:34 +00:00
|
|
|
.SH NAME
|
|
|
|
vmsplice \- splice user pages into 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>
|
|
|
|
.B #include <sys/uio.h>
|
|
|
|
|
2009-09-15 03:58:00 +00:00
|
|
|
.BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov ,
|
|
|
|
.BI " unsigned long " nr_segs ", unsigned int " flags );
|
2006-09-18 12:35:34 +00:00
|
|
|
.fi
|
2009-09-15 03:58:00 +00:00
|
|
|
.\" Return type was long before glibc 2.7
|
2006-09-18 12:35:34 +00:00
|
|
|
.SH DESCRIPTION
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" Linus: vmsplice() system call to basically do a "write to
|
|
|
|
.\" the buffer", but using the reference counting and VM traversal
|
|
|
|
.\" to actually fill the buffer. This means that the user needs to
|
close.2, epoll_create.2, epoll_ctl.2, fcntl.2, madvise.2, mmap.2, mremap.2, select_tut.2, setgid.2, setuid.2, syscalls.2, vmsplice.2, dlopen.3, fts.3, getpw.3, stdio.3, fd.4, initrd.4, random.4, sd.4, bootparam.7, capabilities.7, cpuset.7, epoll.7, inotify.7, man.7, socket.7, x25.7: Global fix: s/re-/re/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "re-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 17:45:23 +00:00
|
|
|
.\" be careful not to reuse the user-space buffer it spliced into
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" the kernel-space one (contrast this to "write()", which copies
|
close.2, epoll_create.2, epoll_ctl.2, fcntl.2, madvise.2, mmap.2, mremap.2, select_tut.2, setgid.2, setuid.2, syscalls.2, vmsplice.2, dlopen.3, fts.3, getpw.3, stdio.3, fd.4, initrd.4, random.4, sd.4, bootparam.7, capabilities.7, cpuset.7, epoll.7, inotify.7, man.7, socket.7, x25.7: Global fix: s/re-/re/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "re-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 17:45:23 +00:00
|
|
|
.\" the actual data, and you can thus reuse the buffer immediately
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" after a successful write), but that is often easy to do.
|
2006-09-18 12:35:34 +00:00
|
|
|
The
|
|
|
|
.BR vmsplice ()
|
|
|
|
system call maps
|
|
|
|
.I nr_segs
|
|
|
|
ranges of user memory described by
|
|
|
|
.I iov
|
2007-04-12 22:42:49 +00:00
|
|
|
into a pipe.
|
2006-09-18 12:35:34 +00:00
|
|
|
The file descriptor
|
2007-04-12 22:42:49 +00:00
|
|
|
.I fd
|
2006-09-18 12:35:34 +00:00
|
|
|
must refer to a pipe.
|
|
|
|
|
|
|
|
The pointer
|
|
|
|
.I iov
|
|
|
|
points to an array of
|
|
|
|
.I iovec
|
|
|
|
structures as defined in
|
|
|
|
.IR <sys/uio.h> :
|
|
|
|
|
2007-12-19 05:53:30 +00:00
|
|
|
.in +4n
|
2006-09-18 12:35:34 +00:00
|
|
|
.nf
|
|
|
|
struct iovec {
|
|
|
|
void *iov_base; /* Starting address */
|
|
|
|
size_t iov_len; /* Number of bytes */
|
|
|
|
};
|
2007-12-19 05:53:30 +00:00
|
|
|
.in
|
2006-09-18 12:35:34 +00:00
|
|
|
.fi
|
|
|
|
|
|
|
|
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
|
|
|
|
Unused for
|
|
|
|
.BR vmsplice ();
|
|
|
|
see
|
|
|
|
.BR splice (2).
|
|
|
|
.TP
|
|
|
|
.B SPLICE_F_NONBLOCK
|
|
|
|
.\" Not used for vmsplice
|
|
|
|
.\" May be in the future -- therefore EAGAIN
|
2007-04-12 22:42:49 +00:00
|
|
|
Do not block on I/O; see
|
|
|
|
.BR splice (2)
|
2006-09-18 12:35:34 +00:00
|
|
|
for further details.
|
|
|
|
.TP
|
|
|
|
.B SPLICE_F_MORE
|
2007-04-12 22:42:49 +00:00
|
|
|
Currently has no effect for
|
2006-09-18 12:35:34 +00:00
|
|
|
.BR vmsplice (),
|
|
|
|
but may be implemented in the future; see
|
|
|
|
.BR splice (2).
|
|
|
|
.TP
|
|
|
|
.B SPLICE_F_GIFT
|
2007-04-12 22:42:49 +00:00
|
|
|
The user pages are a gift to the kernel.
|
|
|
|
The application may not modify this memory ever,
|
2006-09-18 12:35:34 +00:00
|
|
|
.\" FIXME Explain the following line in a little more detail:
|
2007-04-12 22:42:49 +00:00
|
|
|
or page cache and on-disk data may differ.
|
2006-09-18 12:35:34 +00:00
|
|
|
Gifting pages to the kernel means that a subsequent
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR splice (2)
|
2006-09-18 12:35:34 +00:00
|
|
|
.B SPLICE_F_MOVE
|
|
|
|
can successfully move the pages;
|
|
|
|
if this flag is not specified, then a subsequent
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR splice (2)
|
2006-09-18 12:35:34 +00:00
|
|
|
.B SPLICE_F_MOVE
|
|
|
|
must copy the pages.
|
|
|
|
Data must also be properly page aligned, both in memory and length.
|
|
|
|
.\" .... if we expect to later SPLICE_F_MOVE to the cache.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
Upon successful completion,
|
|
|
|
.BR vmsplice ()
|
2007-04-12 22:42:49 +00:00
|
|
|
returns the number of bytes transferred to the pipe.
|
|
|
|
On error,
|
2007-05-12 00:47:22 +00:00
|
|
|
.BR vmsplice ()
|
2006-09-18 12:35:34 +00:00
|
|
|
returns \-1 and
|
|
|
|
.I errno
|
|
|
|
is set to indicate the error.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
|
|
|
.I fd
|
|
|
|
either not valid, or doesn't refer to a pipe.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I nr_segs
|
|
|
|
is 0 or greater than
|
2007-09-04 06:30:39 +00:00
|
|
|
.BR IOV_MAX ;
|
2006-09-18 12:35:34 +00:00
|
|
|
or memory not aligned if
|
|
|
|
.B SPLICE_F_GIFT
|
|
|
|
set.
|
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
Out of memory.
|
2007-05-18 16:30:46 +00:00
|
|
|
.SH VERSIONS
|
|
|
|
The
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR vmsplice ()
|
2007-05-29 04:37:56 +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
|
|
|
|
.BR vmsplice ()
|
|
|
|
follows the other vectorized read/write type functions when it comes to
|
2007-04-12 22:42:49 +00:00
|
|
|
limitations on number of segments being passed in.
|
2006-09-18 12:35:34 +00:00
|
|
|
This limit is
|
|
|
|
.B IOV_MAX
|
|
|
|
as defined in
|
|
|
|
.IR <limits.h> .
|
|
|
|
At the time of this writing, that limit is 1024.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR splice (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 tee (2)
|