Debian Codegraph @

upstream/debian-unstable/man2/tee.2

raw
1 .\" Copyright 2006, Jens Axboe <[email protected]>
2 .\" Copyright 2006, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH tee 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 tee \- duplicating pipe content
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
16 .B #include <fcntl.h>
17 .P
18 .BI "ssize_t tee(int " fd_in ", int " fd_out ", size_t " size \
19 ", unsigned int " flags );
20 .fi
21 .\" Return type was long before glibc 2.7
22 .SH DESCRIPTION
23 .\" Example programs http://brick.kernel.dk/snaps
24 .\"
25 .\"
26 .\" add a "tee(in, out1, out2)" system call that duplicates the pages
27 .\" (again, incrementing their reference count, not copying the data) from
28 .\" one pipe to two other pipes.
29 .BR tee ()
30 duplicates up to
31 .I size
32 bytes of data from the pipe referred to by the file descriptor
33 .I fd_in
34 to the pipe referred to by the file descriptor
35 .IR fd_out .
36 It does not consume the data that is duplicated from
37 .IR fd_in ;
38 therefore, that data can be copied by a subsequent
39 .BR splice (2).
40 .P
41 .I flags
42 is a bit mask that is composed by ORing together
43 zero or more of the following values:
44 .TP 1.9i
45 .B SPLICE_F_MOVE
46 Currently has no effect for
47 .BR tee ();
48 see
49 .BR splice (2).
50 .TP
51 .B SPLICE_F_NONBLOCK
52 Do not block on I/O;
53 see
54 .BR splice (2)
55 for further details.
56 .TP
57 .B SPLICE_F_MORE
58 Currently has no effect for
59 .BR tee (),
60 but may be implemented in the future;
61 see
62 .BR splice (2).
63 .TP
64 .B SPLICE_F_GIFT
65 Unused for
66 .BR tee ();
67 see
68 .BR vmsplice (2).
69 .SH RETURN VALUE
70 Upon successful completion,
71 .BR tee ()
72 returns the number of bytes that were duplicated between the input
73 and output.
74 A return value of 0 means that there was no data to transfer,
75 and it would not make sense to block, because there are no
76 writers connected to the write end of the pipe referred to by
77 .IR fd_in .
78 .P
79 On error,
80 .BR tee ()
81 returns \-1 and
82 .I errno
83 is set to indicate the error.
84 .SH ERRORS
85 .TP
86 .B EAGAIN
87 .B SPLICE_F_NONBLOCK
88 was specified in
89 .I flags
90 or one of the file descriptors had been marked as nonblocking
91 .RB ( O_NONBLOCK ) ,
92 and the operation would block.
93 .TP
94 .B EINVAL
95 .I fd_in
96 or
97 .I fd_out
98 does not refer to a pipe;
99 or
100 .I fd_in
101 and
102 .I fd_out
103 refer to the same pipe.
104 .TP
105 .B ENOMEM
106 Out of memory.
107 .SH STANDARDS
108 Linux.
109 .SH HISTORY
110 Linux 2.6.17,
111 glibc 2.5.
112 .SH NOTES
113 Conceptually,
114 .BR tee ()
115 copies the data between the two pipes.
116 In reality no real data copying takes place though:
117 under the covers,
118 .BR tee ()
119 assigns data to the output by merely grabbing
120 a reference to the input.
121 .SH EXAMPLES
122 The example below implements a basic
123 .BR tee (1)
124 program using the
125 .BR tee ()
126 system call.
127 Here is an example of its use:
128 .P
129 .in +4n
130 .EX
131 .RB $ " date | ./a.out out.log | cat" ;
132 Tue Oct 28 10:06:00 CET 2014
133 .RB $ " cat out.log" ;
134 Tue Oct 28 10:06:00 CET 2014
135 .EE
136 .in
137 .SS Program source
138 \&
139 .\" SRC BEGIN (tee.c)
140 .EX
141 #define _GNU_SOURCE
142 #include <errno.h>
143 #include <fcntl.h>
144 #include <limits.h>
145 #include <stdio.h>
146 #include <stdlib.h>
147 #include <sys/types.h>
148 #include <unistd.h>
149 \&
150 int
151 main(int argc, char *argv[])
152 {
153 int fd;
154 ssize_t size, ssize;
155 \&
156 if (argc != 2) {
157 fprintf(stderr, "Usage: %s <file>\[rs]n", argv[0]);
158 exit(EXIT_FAILURE);
159 }
160 \&
161 fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);
162 if (fd == \-1) {
163 perror("open");
164 exit(EXIT_FAILURE);
165 }
166 \&
167 for (;;) {
168 /*
169 * tee stdin to stdout.
170 */
171 size = tee(STDIN_FILENO, STDOUT_FILENO,
172 INT_MAX, SPLICE_F_NONBLOCK);
173 if (size < 0) {
174 if (errno == EAGAIN)
175 continue;
176 perror("tee");
177 exit(EXIT_FAILURE);
178 }
179 if (size == 0)
180 break;
181 \&
182 /*
183 * Consume stdin by splicing it to a file.
184 */
185 while (size > 0) {
186 ssize = splice(STDIN_FILENO, NULL, fd, NULL,
187 size, SPLICE_F_MOVE);
188 if (ssize < 0) {
189 perror("splice");
190 exit(EXIT_FAILURE);
191 }
192 size \-= ssize;
193 }
194 }
195 \&
196 close(fd);
197 exit(EXIT_SUCCESS);
198 }
199 .EE
200 .\" SRC END
201 .SH SEE ALSO
202 .BR splice (2),
203 .BR vmsplice (2),
204 .BR pipe (7)