tee(2) - f38

1tee(2)                        System Calls Manual                       tee(2)
2
3
4

NAME

6       tee - duplicating pipe content
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #define _GNU_SOURCE         /* See feature_test_macros(7) */
13       #include <fcntl.h>
14
15       ssize_t tee(int fd_in, int fd_out, size_t len, unsigned int flags);
16

DESCRIPTION

18       tee()  duplicates  up to len bytes of data from the pipe referred to by
19       the file descriptor fd_in to the pipe referred to by the file  descrip‐
20       tor  fd_out.   It  does  not  consume  the data that is duplicated from
21       fd_in; therefore, that data can be copied by a subsequent splice(2).
22
23       flags is a bit mask that is composed by ORing together zero or more  of
24       the following values:
25
26       SPLICE_F_MOVE      Currently has no effect for tee(); see splice(2).
27
28       SPLICE_F_NONBLOCK  Do  not  block on I/O; see splice(2) for further de‐
29                          tails.
30
31       SPLICE_F_MORE      Currently has no effect for tee(), but may be imple‐
32                          mented in the future; see splice(2).
33
34       SPLICE_F_GIFT      Unused for tee(); see vmsplice(2).
35

RETURN VALUE

37       Upon successful completion, tee() returns the number of bytes that were
38       duplicated between the input and output.  A return  value  of  0  means
39       that  there  was  no  data  to transfer, and it would not make sense to
40       block, because there are no writers connected to the write end  of  the
41       pipe referred to by fd_in.
42
43       On error, tee() returns -1 and errno is set to indicate the error.
44

ERRORS

46       EAGAIN SPLICE_F_NONBLOCK  was specified in flags or one of the file de‐
47              scriptors had been marked as nonblocking (O_NONBLOCK),  and  the
48              operation would block.
49
50       EINVAL fd_in  or  fd_out  does not refer to a pipe; or fd_in and fd_out
51              refer to the same pipe.
52
53       ENOMEM Out of memory.
54

STANDARDS

56       Linux.
57

HISTORY

59       Linux 2.6.17, glibc 2.5.
60

NOTES

62       Conceptually, tee() copies the data between the two pipes.  In  reality
63       no  real  data  copying takes place though: under the covers, tee() as‐
64       signs data to the output by merely grabbing a reference to the input.
65

EXAMPLES

67       The example below implements a basic tee(1)  program  using  the  tee()
68       system call.  Here is an example of its use:
69
70           $ date | ./a.out out.log | cat
71           Tue Oct 28 10:06:00 CET 2014
72           $ cat out.log
73           Tue Oct 28 10:06:00 CET 2014
74
75   Program source
76
77       #define _GNU_SOURCE
78       #include <errno.h>
79       #include <fcntl.h>
80       #include <limits.h>
81       #include <stdio.h>
82       #include <stdlib.h>
83       #include <unistd.h>
84
85       int
86       main(int argc, char *argv[])
87       {
88           int      fd;
89           ssize_t  len, slen;
90
91           if (argc != 2) {
92               fprintf(stderr, "Usage: %s <file>\n", argv[0]);
93               exit(EXIT_FAILURE);
94           }
95
96           fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);
97           if (fd == -1) {
98               perror("open");
99               exit(EXIT_FAILURE);
100           }
101
102           for (;;) {
103               /*
104                * tee stdin to stdout.
105                */
106               len = tee(STDIN_FILENO, STDOUT_FILENO,
107                         INT_MAX, SPLICE_F_NONBLOCK);
108               if (len < 0) {
109                   if (errno == EAGAIN)
110                       continue;
111                   perror("tee");
112                   exit(EXIT_FAILURE);
113               }
114               if (len == 0)
115                   break;
116
117               /*
118                * Consume stdin by splicing it to a file.
119                */
120               while (len > 0) {
121                   slen = splice(STDIN_FILENO, NULL, fd, NULL,
122                                 len, SPLICE_F_MOVE);
123                   if (slen < 0) {
124                       perror("splice");
125                       exit(EXIT_FAILURE);
126                   }
127                   len -= slen;
128               }
129           }
130
131           close(fd);
132           exit(EXIT_SUCCESS);
133       }
134