[PATCH] vmsplice: first attempt at man page

diff --git a/vmsplice.2 b/vmsplice.2
new file mode 100644 (file)
index 0000000..a80cebf
--- /dev/null
+++ b/vmsplice.2
@@ -0,0 +1,62 @@
+.TH vmsplice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
+.SH NAME
+vmsplice \- splice user pages into a pipe
+.SH SYNOPSIS
+.B #include <sys/uio.h>
+
+.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 pointer \fIiov\fR points to an array of \fIstruct iovec\fR entries as
+defined in \fI<sys/uio.h>\fR:
+
+.nf
+  struct iovec {
+       void *iov_base;         /* Starting address */
+       size_t iov_len;         /* Number of bytes */
+  };
+.fi
+
+The \fIflags\fR 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().
+
+.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.
+.TP
+.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.
+
+.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
+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
+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<limits.h>\fR. At the time of this writing,
+that limit is 1024.
+
+.SH AUTHORS
+Jens Axboe <axboe@suse.de>