man2/tee.2

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