TEE(1)                                                                  TEE(1)



NAME
       Tee - advanced pipe fitting

SYNOPSIS
       Tee [-aiv] [+spigots] [-b blocksize] [-Rring] [files]
       Tee -h
       Tee -V

DESCRIPTION
       When  a stream needs to be diverted to more than one destination a sim-
       ple redirection won't do.  Tee duplicates a stream standard  output  as
       well as to one or more files.

       The  simple  case allows the data passing through a pipe to be recorded
       in a log file:
       (This is not a replacement for the system logger, by the way.)

       The files may be filenames or shell commands when prefixed  by  a  pipe
       (|).  The process style is intended for use with remote shell and dd to
       copy tapes and such.

       A more advanced application might save the first and last  lines  of  a
       sort output for later inspection:

       A third style mocks the shell redirection duplication form allowing Tee
       to leverage already open files.  For example  to  duplicate  stdout  to
       stderr in a pipeline one would:

OPTIONS
       +spigots
              Given enough destination files Tee must fork copies of itself to
              open all the requisite file descriptors.  This integer specifies
              a  lower  limit  than  the system maximum to tune Tee's usage of
              file descriptors per process.

       -a
              Append to each file in the list.  The may be specified for  each
              file  with by prefixing >> to the filename (which must be quoted
              from the shell).  An explicit prefix of > turns this option  off
              for any file specified, if it is set globally.

       -b blocksize
              Set  the blocksize for the transfer.  This only matters (for the
              most part) for transactions with device files  or  pipe  fitting
              with dd(1).  This does take all the common suffixes.

              The  default block size is small to speed output to terminal (or
              other interactive) devices.  Larger transfer sizes  save  system
              calls  but lead to surges in terminal output that make it impos-
              sible to read anything (as all the output comes out at  the  end
              of the process).  Set a larger blocksize for bulk payloads (viz.
              128k and 1m work well).

       -h
              Print only a brief help message.

       -i
              Ignore interrupts.

       -Rring
              This forces Tee to fork(2) multiple  worker  process  that  each
              buffer  blocksize  chunks  of the input stream, then write their
              chunk to each output stream.  Commonly  -R2  is  called  "double
              buffering".  Note that the specification must abut the option.

       -v
              Trace progress on stderr.  A period (.) is output for each block
              fully transferred.  A newline is output after  each  72  blocks.
              In  the  case where more than one process is needed to honor all
              the destination files the last Tee in the pump will be the orig-
              inal process and the one to output all the trace information.

       -V
              Show only the stander version banner.

EXAMPLES
       dd if=/dev/rmt/0h bs=20b | Tee -b 20b /dev/rmt/1h >/dev/rmt/2h
              Copy the tar tape on the zero tape drive to both tape 1 and tape
              2 in high density mode.   Note  that  one  destination  tape  is
              opened by Tee, the other is stdout.

       finger | Tee '|wc -l'
              Output  the finger table followed by the number of lines in that
              output.

       Tee '|awk "BEGIN {sum=0;} {sum += \$1;} END {print sum;}"' <numbers
              Output a list of numbers and their sum.

       dd if=/dev/zero count=512 bs=8k | Tee -b 8k F1 F2 F3 F4 F5 F6 F7 >F8
              Build 8 4Meg files of zeros.  This might make a good disk timing
              test.

       dd if=/dev/zero count=512 bs=8k | Tee -R4 -b 8k F1 F2 F3 F4 F5 F6 F7 >F8
              Same  a  above, but use quad-buffer logic to keep 4 CPUs busy to
              build the files.

       mkiso... | Tee  '|ssh h1 cat >fs.iso' '|ssh h2 cat >fs.iso' >fs.iso
              Create a large ISO filesystem send it to 2 other hosts (h1,  h2)
              and keep a local copy in "fs.iso".

       Tee -b 19827608\? -V
              Output  the  table  of  common byte multipliers with the version
              information.

       Tee -R -V
              Output version information as well as the default for  the  ring
              specification.

       source | Tee -R2 | destination
              Double  buffer  the output of source to destination.  This some-
              times helps with overall throughput when both the input and out-
              put  processes  have uneven transaction times (viz. tape devices
              or processes that block at odd times).

       source | Tee '>>../common/log' last.run | ...
              Use the explicit append notation to append to a common log  file
              and record what we appended in a local file.

       source | Tee -a ../common/log '>last.run' | ...
              Same a the above, but invert the exception logic.

BUGS
       It  is marginally more clever to reach out with ssh -n to read a remote
       tape than it is to push from the source  machine  due  to  the  network
       overhead.

       Tee  could handle the splitting of long files lists better: in the case
       where we have to build 5 processes we might split the load between  the
       processes more evenly (rather then 4 fulls and the last one with 1 or 2
       destinations).

       It might be argued that -R should be spelled -P to make  it  look  more
       like other "ksb tools".  But it is too late now.

       A  threaded  version of this would be more clever, but single character
       I/O to (from) a pipe is almost free.  Still, user level mutext would be
       better.

AUTHOR
       Kevin S Braunsdorf
       NonPlayer Character Guild
       k-s-b at no-spam-me removed npcguild.org

HTML
       See the explode module pipering.html in /usr/local/lib/explode.

SEE ALSO
       sh(1), dd(1), wc(1), ssh(1), logger(1), awk(1), finger(1)



                                     LOCAL                              TEE(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | BUGS | AUTHOR | HTML | SEE ALSO