original/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 2012-05-04 "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
  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
  57 .I flags
  58 is a series of modifier flags, which share the name space with
  59 .BR splice (2)
  60 and
  61 .BR vmsplice (2):
  62 .TP 1.9i
  63 .B SPLICE_F_MOVE
  64 Currently has no effect for
  65 .BR tee ();
  66 see
  67 .BR splice (2).
  68 .TP
  69 .B SPLICE_F_NONBLOCK
  70 Do not block on I/O; see
  71 .BR splice (2)
  72 for further details.
  73 .TP
  74 .B SPLICE_F_MORE
  75 Currently has no effect for
  76 .BR tee (),
  77 but may be implemented in the future; see
  78 .BR splice (2).
  79 .TP
  80 .B SPLICE_F_GIFT
  81 Unused for
  82 .BR tee ();
  83 see
  84 .BR vmsplice (2).
  85 .SH RETURN VALUE
  86 Upon successful completion,
  87 .BR tee ()
  88 returns the number of bytes that were duplicated between the input
  89 and output.
  90 A return value of 0 means that there was no data to transfer,
  91 and it would not make sense to block, because there are no
  92 writers connected to the write end of the pipe referred to by
  93 .IR fd_in .
  94
  95 On error,
  96 .BR tee ()
  97 returns \-1 and
  98 .I errno
  99 is set to indicate the error.
 100 .SH ERRORS
 101 .TP
 102 .B EINVAL
 103 .I fd_in
 104 or
 105 .I fd_out
 106 does not refer to a pipe; or
 107 .I fd_in
 108 and
 109 .I fd_out
 110 refer to the same pipe.
 111 .TP
 112 .B ENOMEM
 113 Out of memory.
 114 .SH VERSIONS
 115 The
 116 .BR tee ()
 117 system call first appeared in Linux 2.6.17;
 118 library support was added to glibc in version 2.5.
 119 .SH CONFORMING TO
 120 This system call is Linux-specific.
 121 .SH NOTES
 122 Conceptually,
 123 .BR tee ()
 124 copies the data between the two pipes.
 125 In reality no real data copying takes place though:
 126 under the covers,
 127 .BR tee ()
 128 assigns data in the output by merely grabbing
 129 a reference to the input.
 130 .SH EXAMPLE
 131 The following example implements a basic
 132 .BR tee (1)
 133 program using the
 134 .BR tee ()
 135 system call.
 136 .nf
 137
 138 #define _GNU_SOURCE
 139 #include <fcntl.h>
 140 #include <stdio.h>
 141 #include <stdlib.h>
 142 #include <unistd.h>
 143 #include <errno.h>
 144 #include <limits.h>
 145
 146 int
 147 main(int argc, char *argv[])
 148 {
 149     int fd;
 150     int len, slen;
 151
 152     if (argc != 2) {
 153         fprintf(stderr, "Usage: %s <file>\\n", argv[0]);
 154         exit(EXIT_FAILURE);
 155     }
 156
 157     fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);
 158     if (fd == \-1) {
 159         perror("open");
 160         exit(EXIT_FAILURE);
 161     }
 162
 163     do {
 164         /*
 165          * tee stdin to stdout.
 166          */
 167         len = tee(STDIN_FILENO, STDOUT_FILENO,
 168                   INT_MAX, SPLICE_F_NONBLOCK);
 169
 170         if (len < 0) {
 171             if (errno == EAGAIN)
 172                 continue;
 173             perror("tee");
 174             exit(EXIT_FAILURE);
 175         } else
 176             if (len == 0)
 177                 break;
 178
 179         /*
 180          * Consume stdin by splicing it to a file.
 181          */
 182         while (len > 0) {
 183             slen = splice(STDIN_FILENO, NULL, fd, NULL,
 184                           len, SPLICE_F_MOVE);
 185             if (slen < 0) {
 186                 perror("splice");
 187                 break;
 188             }
 189             len \-= slen;
 190         }
 191     } while (1);
 192
 193     close(fd);
 194     exit(EXIT_SUCCESS);
 195 }
 196 .fi
 197 .SH SEE ALSO
 198 .BR splice (2),
 199 .BR vmsplice (2)
 200 .SH COLOPHON
 201 This page is part of release 3.68 of the Linux
 202 .I man-pages
 203 project.
 204 A description of the project,
 205 information about reporting bugs,
 206 and the latest version of this page,
 207 can be found at
 208 \%http://www.kernel.org/doc/man\-pages/.