bstream(1)

NAME
     bstream - many buffered filter

SYNOPSIS
     bstream [-n bufs] [-b size] [-ltrvd] [-s count] [-i file] [-o file]

DESCRIPTION
     This command is a filter which buffers input from the input file and
     writes it to the output file.  The command is especially useful for
     reading from or writing to streaming tape drives, where bstream can be
     used as a speed matching program to keep the tape streaming as much as
     possible.

     If input or output files are not specified, then bstream simply copies
     the standard input to the standard output through multiple buffers.  A
     tape can be written to or read from in this manner, but bstream will not
     be able to handle multiple tape copies.  If multiple tapes are involved,
     explicitly specifying the tape device via the -i or -o options will
     enable bstream to recover from end of medium indications and request a
     new tape.

OPTIONS
     The following options are supported:

     -b size   specifies the size of buffer to use.  The default size is 64K
               bytes, however any size up to the maximum allowable shared
               memory segment size for the system is allowed.

     -n cnt    Sets the number of buffers to use.  A minimum of two is
               enforced, while the maximum is limited by the number of shared
               memory segments which a process may be attached to
               simultaneously.  More than two buffers can improve performance
               and make the tape more likely to stream.  The default value is
               set to four.

     -l        Attempt to lock the shared memory buffers into physical memory.
               This will not be possible unless the command is run by the
               superuser.

     -t        Attempt to lock program image and stack in physical memory.
               This will not be possible unless the command is run by the
               super user.  The nice value of the bstream process is also
               decreased, increasing its scheduling priority.

     -r        Report a summary of the byte throughput achieved by bstream for
               the entire transfer as well as for each individual tape if
               multiple tapes are involved.

     -v        Reports each i/o that is done (very verbose).
     -d        Reports very verbose debugging information.

     -s count  Report a summary of the byte throughput achieved by bstream
               every count buffers, for both input and output.

     -i file   Specify the input file as an explicit filename, allowing
               recovery from end-of-medium conditions on tapes.  The user will
               be prompted for a new tape.

     -o file   Specify the output file as an explicit filename, allowing
               recovery from end-of-medium conditions on tapes.  The user will
               be prompted for a new tape.

     To copy a filesystem onto multiple tapes:

          tar cf - * | bstream -o/dev/tape

     Recovering an image from tape is just as easy:

          bstream -i/dev/tape | tar xf -


     There is a subtle issue involving tapes that should be understood when
     using bstream with a tape device.  Usually, a tape device requires that
     the tape be written in even multiples of the block size.  When bstream is
     used as a streaming filter (see the above examples) this is not a
     problem, since both tar(1) and cpio(1) block the output on natural tape
     boundaries.  To protect the user, bstream will round the final write to
     tape up to the nearest tape blocksize boundary, fill the residual of the
     last block with zeros, and print a warning message if rounding up was
     needed.  bstream should always be used with a formatter program such as
     tar or cpio when writing to a tape device, since rounding up and filling
     may have unpredictable effects on programs expecting a simple byte
     stream.  No rounding or filling is done when output is not directed to a
     tape device.

NOTES
     bstream runs only on Silicon Graphics 4D series workstations.  On an
     unloaded 4D60, bstream can stream the tape 70 to 80% of the time,
     achieving byte transfer rates around 70K bytes per second.