From 8736f97cadc4cc7fd5d4922798822e7116861b06 Mon Sep 17 00:00:00 2001
From: Jens Axboe <axboe@suse.de>
Date: Tue, 2 May 2006 09:43:30 +0200
Subject: [PATCH] [PATCH] man page update

---
 splice.2   |  8 ++++++--
 tee.2      | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 vmsplice.2 |  3 +++
 3 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/splice.2 b/splice.2
index e8a5314..ad0ac9a 100644
--- a/splice.2
+++ b/splice.2
@@ -10,7 +10,8 @@ splice \- splice data to/from a pipe.
 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.
+address space, basically a random kernel buffer that the user has full
+control over.
 
 The
 .BR splice ()
@@ -37,7 +38,7 @@ Do not block on io.
 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 
+(see
 .BR send (2)
 and
 .B TCP_CORK
@@ -63,6 +64,9 @@ File descriptors either not valid, or do not have proper rw permission.
 .B EINVAL
 Target file system doesn't support splicing, none of the descriptors refer
 to a pipe or offset given for non-seekable device.
+.TP
+.B ENOMEM
+Ran out of memory.
 
 .SH HISTORY
 The
diff --git a/tee.2 b/tee.2
index 7d806d4..6d4c348 100644
--- a/tee.2
+++ b/tee.2
@@ -36,9 +36,12 @@ See
 .BR vmsplice (2)
 
 .PP
+Conceptually,
 .BR tee ()
-doesn't copy any data around, it simply references the input data and
-links it to the output pipe.
+copies the data between the two pipes, in reality no real data copying
+takes place though. Under the covers,
+.BR tee ()
+assigns data in the output by merely grabbing a reference to the input.
 
 .SH RETURN VALUE
 Upon successful completion,
@@ -55,6 +58,54 @@ shall be set to indicate an error.
 and
 .I fd_out
 do not both refer to a pipe.
+.TP
+.B ENOMEM
+Ran out of memory.
+
+.SH EXAMPLE
+The following example implements a basic
+.BR tee (1)
+program using the
+.BR tee (2)
+system call. To keep it simple, it has no real error handling.
+
+.nf
+#include <stdio.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <sys/splice.h>
+
+int fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, 0644);
+
+do {
+	/*
+	 * tee stdin to stdout.
+	 */
+	int len = tee(STDIN_FILENO, STDOUT_FILENO, INT_MAX, SPLICE_F_NONBLOCK);
+
+	if (len < 0) {
+		if (errno == EAGAIN)
+			continue;
+		perror("tee");
+		break;
+	} else if (!len)
+		break;
+
+	/*
+	 * Consume stdin by splicing it to a file.
+	 */
+	while (len) {
+		int slen = splice(STDIN_FILENO, NULL, fd, NULL, len, SPLICE_F_MOVE);
+		if (slen < 0) {
+			perror("splice");
+			break;
+		}
+		len -= slen;
+	}
+} while (1);
+
+close(fd);
+.fi
 
 .SH HISTORY
 The
diff --git a/vmsplice.2 b/vmsplice.2
index b0f739a..01bcd14 100644
--- a/vmsplice.2
+++ b/vmsplice.2
@@ -76,6 +76,9 @@ either not valid, or doesn't refer to a pipe.
 not valid, memory not aligned if
 .I SPLICE_F_GIFT
 set.
+.TP
+.B ENOMEM
+Ran out of memory.
 
 .SH NOTES
 .BR vmsplice ()
-- 
2.25.1