[splice.git] / tee.2

.TH tee 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
.SH NAME
tee \- duplicating pipe content.
.SH SYNOPSIS
.B #include <sys/splice.h>

.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
Conceptually,
.BR tee ()
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,
.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 EINVAL
.I fd_in
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
.BR tee (2)
system call first appeared in Linux-2.6.17.

.SH SEE ALSO
.BR splice (2),
.BR vmsplice (2)

.SH AUTHORS
Jens Axboe <axboe@kernel.dk>
Commit	Line	Data
	1	.TH tee 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
	2	.SH NAME
	3	tee \- duplicating pipe content.
	4	.SH SYNOPSIS
	5	.B #include <sys/splice.h>
	6
	7	.B long tee(int fd_in, int fd_out, size_t bytes, unsigned int flags);
	8
	9	.SH DESCRIPTION
	10	.BR tee ()
	11	duplicates at most
	12	.I bytes
	13	of content from pipe
	14	.I fd_in
	15	to pipe
	16	.IR fd_out .
	17	.I flags
	18	is a series of modifier flags, which share the name space with
	19	.BR splice (2)
	20	and
	21	.BR vmsplice (2):
	22
	23	.TP 1.9i
	24	.B SPLICE_F_MOVE
	25	See
	26	.BR splice (2)
	27	.TP
	28	.B SPLICE_F_NONBLOCK
	29	Do not block on io.
	30	.TP
	31	.B SPLICE_F_MORE
	32	More data will be coming in a subsequent splice.
	33	.TP
	34	.B SPLICE_F_GIFT
	35	See
	36	.BR vmsplice (2)
	37
	38	.PP
	39	Conceptually,
	40	.BR tee ()
	41	copies the data between the two pipes, in reality no real data copying
	42	takes place though. Under the covers,
	43	.BR tee ()
	44	assigns data in the output by merely grabbing a reference to the input.
	45
	46	.SH RETURN VALUE
	47	Upon successful completion,
	48	.BR tee ()
	49	shall return the number of bytes that was duplicated between the input
	50	and output. Otherwise, it shall return a value of -1 and
	51	.I errno
	52	shall be set to indicate an error.
	53
	54	.SH ERRORS
	55	.TP 1.1i
	56	.B EINVAL
	57	.I fd_in
	58	and
	59	.I fd_out
	60	do not both refer to a pipe.
	61	.TP
	62	.B ENOMEM
	63	Ran out of memory.
	64
	65	.SH EXAMPLE
	66	The following example implements a basic
	67	.BR tee (1)
	68	program using the
	69	.BR tee (2)
	70	system call. To keep it simple, it has no real error handling.
	71
	72	.nf
	73	#include <stdio.h>
	74	#include <unistd.h>
	75	#include <fcntl.h>
	76	#include <sys/splice.h>
	77
	78	int fd = open(filename, O_WRONLY \| O_CREAT \| O_TRUNC, 0644);
	79
	80	do {
	81	/*
	82	* tee stdin to stdout.
	83	*/
	84	int len = tee(STDIN_FILENO, STDOUT_FILENO, INT_MAX, SPLICE_F_NONBLOCK);
	85
	86	if (len < 0) {
	87	if (errno == EAGAIN)
	88	continue;
	89	perror("tee");
	90	break;
	91	} else if (!len)
	92	break;
	93
	94	/*
	95	* Consume stdin by splicing it to a file.
	96	*/
	97	while (len) {
	98	int slen = splice(STDIN_FILENO, NULL, fd, NULL, len, SPLICE_F_MOVE);
	99	if (slen < 0) {
	100	perror("splice");
	101	break;
	102	}
	103	len -= slen;
	104	}
	105	} while (1);
	106
	107	close(fd);
	108	.fi
	109
	110	.SH HISTORY
	111	The
	112	.BR tee (2)
	113	system call first appeared in Linux-2.6.17.
	114
	115	.SH SEE ALSO
	116	.BR splice (2),
	117	.BR vmsplice (2)
	118
	119	.SH AUTHORS
	120	Jens Axboe <axboe@kernel.dk>