From: Jens Axboe Date: Sun, 30 Apr 2006 12:28:12 +0000 (+0200) Subject: [PATCH man page update (added splice and tee) X-Git-Url: https://git.kernel.dk/?a=commitdiff_plain;h=8d2541ed14a44d95101cf86dcb3e56b79b782a7c;p=splice.git [PATCH man page update (added splice and tee) --- diff --git a/splice.2 b/splice.2 new file mode 100644 index 0000000..90b3968 --- /dev/null +++ b/splice.2 @@ -0,0 +1,71 @@ +.TH splice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual" +.SH NAME +splice \- splice data to/from a pipe. +.SH SYNOPSIS +.B #include + +.B long splice(int fd_in, loff_t *off_in, int fd_out, loff_t *off_out, size_t bytes, unsigned int flags); + +.SH DESCRIPTION +The act of splicing can be seen as a way to connect two ends of a rope +through a kernel buffer, where that buffer is implemented as a pipe. It +provides a means to move data around without copying it to/from kernel/user +address space. + +The +.BR splice () +function splices +.I bytes +of data between file descriptor +.I fd_in +and +.IR fd_out , +where one of the descriptors must refer to a pipe. The +.I flags +argument is a series of modifier flags: + +.TP 1.9i +.B SPLICE_F_MOVE +Attempt to move pages instead of copying. +.TP +.B SPLICE_F_NONBLOCK +Do not block on io. +.TP +.B SPLICE_F_MORE +More data will be coming in a subsequent splice. This is a helpful hint when +the output descriptor refers to a socket, see also +.B MSG_MORE +(see +.BR send (2) +and +.B TCP_CORK +.BR tcp (7)) +.TP +.B SPLICE_F_GIFT +See +.BR vmsplice (2). + +.SH RETURN VALUE +Upon successful completion, +.BR splice () +shall return the number of bytes +spliced to or from the pipe. Otherwise, it shall return a value of -1 and +.I errno +shall be set to indicate an error. + +.SH ERRORS +.TP 1.1i +.B EBADF +.I fd +either not valid, or none of the descriptors refer to a pipe. +.TP +.B EINVAL +Target file system doesn't support splicing, none of the descriptors refer +to a pipe or offset given for non-seekable device. + +.SH SEE ALSO +.BR splice (2), +.BR tee (2) + +.SH AUTHORS +Jens Axboe diff --git a/tee.2 b/tee.2 new file mode 100644 index 0000000..ce7f54e --- /dev/null +++ b/tee.2 @@ -0,0 +1,66 @@ +.TH tee 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual" +.SH NAME +tee \- duplicating pipe content. +.SH SYNOPSIS +.B #include + +.B long tee(int fd_in, int fd_out, size_t bytes, unsigned int flags); + +.SH DESCRIPTION +.BR tee () +duplicates at most +.I bytes +of content from pipe +.I fd_in +to pipe +.IR fd_out . +.I flags +is a series of modifier flags, which share the name space with +.BR splice (2) +and +.BR vmsplice (2): + +.TP 1.9i +.B SPLICE_F_MOVE +See +.BR splice (2) +.TP +.B SPLICE_F_NONBLOCK +Do not block on io. +.TP +.B SPLICE_F_MORE +More data will be coming in a subsequent splice. +.TP +.B SPLICE_F_GIFT +See +.BR vmsplice (2) + +.PP +.BR tee () +doesn't copy any data around, it simply references the input data and +links it to the output pipe. + +.SH RETURN VALUE +Upon successful completion, +.BR tee () +shall return the number of bytes that was duplicated between the input +and output. Otherwise, it shall return a value of -1 and +.I errno +shall be set to indicate an error. + +.SH ERRORS +.TP 1.1i +.B EBADF +.I fd +either not valid, or none of the descriptors refer to a pipe. +.TP +.B EINVAL +Target file system doesn't support splicing, none of the descriptors refer +to a pipe or offset given for non-seekable device. + +.SH SEE ALSO +.BR splice (2), +.BR vmsplice (2) + +.SH AUTHORS +Jens Axboe diff --git a/vmsplice.2 b/vmsplice.2 index a80cebf..7662f55 100644 --- a/vmsplice.2 +++ b/vmsplice.2 @@ -7,10 +7,21 @@ vmsplice \- splice user pages into a pipe .B long vmsplice(int fd, const struct iovec *iov, unsigned long nr_segs, unsigned ing flags); .SH DESCRIPTION -The \fIvmsplice\fR() function maps \fInr_segs\fR range(s) of \fIiov\fR described user memory into a pipe. The \fIfd\fR must refer to a pipe. +The +.BR vmsplice () +function maps +.I nr_segs +range(s) of +.I iov +described user memory into a pipe. The +.I fd must refer to a pipe. -The pointer \fIiov\fR points to an array of \fIstruct iovec\fR entries as -defined in \fI\fR: +The pointer +.I iov +points to an array of +.I struct iovec +entries as defined in +.IR : .nf struct iovec { @@ -19,12 +30,16 @@ defined in \fI\fR: }; .fi -The \fIflags\fR argument is a series of modifier flags. Only +The +.I flags +argument is a series of modifier flags. Only .B SPLICE_F_NONBLOCK and .B SPLICE_F_GIFT -really apply to \fIvmsplice\fR(), the but the scope is shared with -\fBsplice\fR(). +really apply to +.BR vmsplice () +, the but the scope is shared with +.BR splice (). .TP 1.9i .B SPLICE_F_MOVE @@ -39,24 +54,40 @@ More data will be coming in a subsequent splice. .B SPLICE_F_GIFT The user pages are a gift to the kernel. The application may not reuse this memory ever, or page cache and on disk data may differ. Data must also be -properly page aligned. +properly page aligned, both in memory and length. .SH RETURN VALUE -Upon successful completion, \fIvmsplice\fR() shall return the number of bytes -spliced to the pipe. Otherwise, it shall return a value of -1 and \fIerrno\fR +Upon successful completion, +.BR vmsplice () +shall return the number of bytes spliced to the pipe. Otherwise, it shall +return a value of -1 and +.I errno shall be set to indicate an error. .SH ERRORS -.B EBADF \fIfd\fR either not valid, or doesn't refer to a pipe. -.TP 7 -.B EINVAL \fInr_segs\fR not valid, memory not aligned if \fISPLICE_F_GIFT\fR +.TP 1.1i +.B EBADF +.I fd +either not valid, or doesn't refer to a pipe. +.TP +.B EINVAL +.I nr_segs +not valid, memory not aligned if +.I SPLICE_F_GIFT set. .SH NOTES -\fIvmsplice\fR() follows the other vectorized read/write type functions when -it comes to limitations on number of segments being passed in. This limit -is \fBIOV_MAX\fR as defined in \fI\fR. At the time of this writing, -that limit is 1024. +.BR vmsplice () +follows the other vectorized read/write type functions when it comes to +limitations on number of segments being passed in. This limit is +.B IOV_MAX +as defined in +.IR . +At the time of this writing, that limit is 1024. + +.SH SEE ALSO +.BR splice (2), +.BR tee (2) .SH AUTHORS Jens Axboe