tee.2

   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>