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@gmx.net>
   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 2.6.17" "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 NOTES
 114 Conceptually,
 115 .BR tee ()
 116 copies the data between the two pipes.
 117 In reality no real data copying takes place though:
 118 under the covers,
 119 .BR tee ()
 120 assigns data in the output by merely grabbing
 121 a reference to the input.
 122 .SH EXAMPLE
 123 The following example implements a basic
 124 .BR tee (1)
 125 program using the
 126 .BR tee (2)
 127 system call.
 128 .nf
 129
 130 #define _GNU_SOURCE
 131 #include <fcntl.h>
 132 #include <stdio.h>
 133 #include <stdlib.h>
 134 #include <unistd.h>
 135 #include <assert.h>
 136 #include <errno.h>
 137 #include <limits.h>
 138
 139 int
 140 main(int argc, char *argv[])
 141 {
 142     int fd;
 143     int len, slen;
 144
 145     assert(argc == 2);
 146
 147     fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);
 148     if (fd == -1) {
 149         perror("open");
 150         exit(EXIT_FAILURE);
 151     }
 152
 153     do {
 154         /*
 155          * tee stdin to stdout.
 156          */
 157         len = tee(STDIN_FILENO, STDOUT_FILENO,
 158                   INT_MAX, SPLICE_F_NONBLOCK);
 159
 160         if (len < 0) {
 161             if (errno == EAGAIN)
 162                 continue;
 163             perror("tee");
 164             exit(EXIT_FAILURE);
 165         } else
 166             if (len == 0)
 167                 break;
 168
 169         /*
 170          * Consume stdin by splicing it to a file.
 171          */
 172         while (len > 0) {
 173             slen = splice(STDIN_FILENO, NULL, fd, NULL,
 174                           len, SPLICE_F_MOVE);
 175             if (slen < 0) {
 176                 perror("splice");
 177                 break;
 178             }
 179             len -= slen;
 180         }
 181     } while (1);
 182
 183     close(fd);
 184     exit(EXIT_SUCCESS);
 185 }
 186 .fi
 187 .SH HISTORY
 188 The
 189 .BR tee (2)
 190 system call first appeared in Linux-2.6.17.
 191 .SH "CONFORMING TO"
 192 This system call is Linux specific.
 193 .SH SEE ALSO
 194 .BR splice (2),
 195 .BR vmsplice (2)