man2/tee.2

   1 .\" This manpage is Copyright (C) 2006 Jens Axboe
   2 .\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH TEE 2 2019-03-06 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 tee \- duplicating pipe content
  29 .SH SYNOPSIS
  30 .nf
  31 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  32 .B #include <fcntl.h>
  33 .PP
  34 .BI "ssize_t tee(int " fd_in ", int " fd_out ", size_t " len \
  35 ", unsigned int " flags );
  36 .fi
  37 .\" Return type was long before glibc 2.7
  38 .SH DESCRIPTION
  39 .\" Example programs http://brick.kernel.dk/snaps
  40 .\"
  41 .\"
  42 .\" add a "tee(in, out1, out2)" system call that duplicates the pages
  43 .\" (again, incrementing their reference count, not copying the data) from
  44 .\" one pipe to two other pipes.
  45 .BR tee ()
  46 duplicates up to
  47 .I len
  48 bytes of data from the pipe referred to by the file descriptor
  49 .I fd_in
  50 to the pipe referred to by the file descriptor
  51 .IR fd_out .
  52 It does not consume the data that is duplicated from
  53 .IR fd_in ;
  54 therefore, that data can be copied by a subsequent
  55 .BR splice (2).
  56 .PP
  57 .I flags
  58 is a bit mask that is composed by ORing together
  59 zero or more of the following values:
  60 .TP 1.9i
  61 .B SPLICE_F_MOVE
  62 Currently has no effect for
  63 .BR tee ();
  64 see
  65 .BR splice (2).
  66 .TP
  67 .B SPLICE_F_NONBLOCK
  68 Do not block on I/O; see
  69 .BR splice (2)
  70 for further details.
  71 .TP
  72 .B SPLICE_F_MORE
  73 Currently has no effect for
  74 .BR tee (),
  75 but may be implemented in the future; see
  76 .BR splice (2).
  77 .TP
  78 .B SPLICE_F_GIFT
  79 Unused for
  80 .BR tee ();
  81 see
  82 .BR vmsplice (2).
  83 .SH RETURN VALUE
  84 Upon successful completion,
  85 .BR tee ()
  86 returns the number of bytes that were duplicated between the input
  87 and output.
  88 A return value of 0 means that there was no data to transfer,
  89 and it would not make sense to block, because there are no
  90 writers connected to the write end of the pipe referred to by
  91 .IR fd_in .
  92 .PP
  93 On error,
  94 .BR tee ()
  95 returns \-1 and
  96 .I errno
  97 is set to indicate the error.
  98 .SH ERRORS
  99 .TP
 100 .B EAGAIN
 101 .B SPLICE_F_NONBLOCK
 102 was specified in
 103 .IR flags ,
 104 and the operation would block.
 105 .TP
 106 .B EINVAL
 107 .I fd_in
 108 or
 109 .I fd_out
 110 does not refer to a pipe; or
 111 .I fd_in
 112 and
 113 .I fd_out
 114 refer to the same pipe.
 115 .TP
 116 .B ENOMEM
 117 Out of memory.
 118 .SH VERSIONS
 119 The
 120 .BR tee ()
 121 system call first appeared in Linux 2.6.17;
 122 library support was added to glibc in version 2.5.
 123 .SH CONFORMING TO
 124 This system call is Linux-specific.
 125 .SH NOTES
 126 Conceptually,
 127 .BR tee ()
 128 copies the data between the two pipes.
 129 In reality no real data copying takes place though:
 130 under the covers,
 131 .BR tee ()
 132 assigns data to the output by merely grabbing
 133 a reference to the input.
 134 .SH EXAMPLE
 135 The example below implements a basic
 136 .BR tee (1)
 137 program using the
 138 .BR tee ()
 139 system call.
 140 Here is an example of its use:
 141 .PP
 142 .in +4n
 143 .EX
 144 $ \fBdate |./a.out out.log | cat\fP
 145 Tue Oct 28 10:06:00 CET 2014
 146 $ \fBcat out.log\fP
 147 Tue Oct 28 10:06:00 CET 2014
 148 .EE
 149 .in
 150 .SS Program source
 151 \&
 152 .EX
 153 #define _GNU_SOURCE
 154 #include <fcntl.h>
 155 #include <stdio.h>
 156 #include <stdlib.h>
 157 #include <unistd.h>
 158 #include <errno.h>
 159 #include <limits.h>
 160
 161 int
 162 main(int argc, char *argv[])
 163 {
 164     int fd;
 165     int len, slen;
 166
 167     if (argc != 2) {
 168         fprintf(stderr, "Usage: %s <file>\en", argv[0]);
 169         exit(EXIT_FAILURE);
 170     }
 171
 172     fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);
 173     if (fd == \-1) {
 174         perror("open");
 175         exit(EXIT_FAILURE);
 176     }
 177
 178     do {
 179         /*
 180          * tee stdin to stdout.
 181          */
 182         len = tee(STDIN_FILENO, STDOUT_FILENO,
 183                   INT_MAX, SPLICE_F_NONBLOCK);
 184
 185         if (len < 0) {
 186             if (errno == EAGAIN)
 187                 continue;
 188             perror("tee");
 189             exit(EXIT_FAILURE);
 190         } else
 191             if (len == 0)
 192                 break;
 193
 194         /*
 195          * Consume stdin by splicing it to a file.
 196          */
 197         while (len > 0) {
 198             slen = splice(STDIN_FILENO, NULL, fd, NULL,
 199                           len, SPLICE_F_MOVE);
 200             if (slen < 0) {
 201                 perror("splice");
 202                 break;
 203             }
 204             len \-= slen;
 205         }
 206     } while (1);
 207
 208     close(fd);
 209     exit(EXIT_SUCCESS);
 210 }
 211 .EE
 212 .SH SEE ALSO
 213 .BR splice (2),
 214 .BR vmsplice (2),
 215 .BR pipe (7)