Commit | Line | Data |
---|---|---|
8d2541ed JA |
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 | |
8736f97c | 39 | Conceptually, |
8d2541ed | 40 | .BR tee () |
8736f97c JA |
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. | |
8d2541ed JA |
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 | |
8d2541ed | 56 | .B EINVAL |
5d79a465 JA |
57 | .I fd_in |
58 | and | |
59 | .I fd_out | |
60 | do not both refer to a pipe. | |
8736f97c JA |
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 | |
5d79a465 JA |
109 | |
110 | .SH HISTORY | |
111 | The | |
112 | .BR tee (2) | |
113 | system call first appeared in Linux-2.6.17. | |
8d2541ed JA |
114 | |
115 | .SH SEE ALSO | |
116 | .BR splice (2), | |
117 | .BR vmsplice (2) | |
118 | ||
119 | .SH AUTHORS | |
120 | Jens Axboe <axboe@suse.de> |