144 lines
4.0 KiB
Groff
144 lines
4.0 KiB
Groff
.TH bstream 1 LOCAL
|
|
.SH NAME
|
|
bstream \- many buffered filter
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\f3bstream\f1 [\f3-n\f1 bufs] [\f3-b\f1 size] \c
|
|
[\f3-ltrvd\f1] [\f3-s\f1 count] [\f3-i\f1 file] \c
|
|
[\f3-o\f1 file]
|
|
.fi
|
|
.SH 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.
|
|
.PP
|
|
If input or output files are not specified, then
|
|
.I 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
|
|
.I bstream
|
|
will not be able to handle multiple tape copies.
|
|
If multiple tapes are involved, explicitly specifying the tape
|
|
device via the
|
|
.B \-i
|
|
or
|
|
.B \-o
|
|
options will enable
|
|
.I bstream
|
|
to recover from end of medium indications and request a new tape.
|
|
.SH OPTIONS
|
|
The following options are supported:
|
|
.TP 10
|
|
.BI \-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.
|
|
.TP 10
|
|
.BI \-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.
|
|
.TP 10
|
|
.B \-l
|
|
Attempt to lock the shared memory buffers into physical
|
|
memory.
|
|
This will not be possible unless the command is run by the superuser.
|
|
.TP 10
|
|
.B \-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
|
|
.I bstream
|
|
process is also decreased, increasing its scheduling priority.
|
|
.TP 10
|
|
.B \-r
|
|
Report a summary of the byte throughput achieved by
|
|
.I bstream
|
|
for the entire transfer as well as for each individual tape if
|
|
multiple tapes are involved.
|
|
.TP 10
|
|
.B \-v
|
|
Reports each i/o that is done (very verbose).
|
|
.TP 10
|
|
.B \-d
|
|
Reports very verbose debugging information.
|
|
.TP 10
|
|
.BI \-s " count"
|
|
Report a summary of the byte throughput achieved by
|
|
.I bstream
|
|
every
|
|
.I count
|
|
buffers, for both input and output.
|
|
.TP 10
|
|
.BI \-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.
|
|
.TP 10
|
|
.BI \-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.
|
|
.TP 10
|
|
.SH EXAMPLES
|
|
To copy a filesystem onto multiple tapes:
|
|
.RS 5
|
|
.nf
|
|
.sp .8v
|
|
.B "tar cf - * | bstream -o/dev/tape"
|
|
.sp .8v
|
|
.fi
|
|
.RE
|
|
Recovering an image from tape is just as easy:
|
|
.RS 5
|
|
.nf
|
|
.sp .8v
|
|
.B "bstream -i/dev/tape | tar xf -"
|
|
.sp .8v
|
|
.fi
|
|
.RE
|
|
.P
|
|
There is a subtle issue involving tapes that should be understood when
|
|
using
|
|
.I bstream
|
|
with a tape device.
|
|
Usually, a tape device requires that the tape be written in even
|
|
multiples of the block size.
|
|
When
|
|
.I bstream
|
|
is used as a streaming filter (see the above examples) this is not a problem,
|
|
since both
|
|
.IR tar ( 1 )
|
|
and
|
|
.IR cpio ( 1 )
|
|
block the output on natural tape boundaries.
|
|
To protect the user,
|
|
.I 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.
|
|
.I bstream
|
|
should always be used with a formatter program such as
|
|
.I tar
|
|
or
|
|
.I 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.
|
|
.SH NOTES
|
|
.I bstream
|
|
runs only on Silicon Graphics 4D series workstations.
|
|
On an unloaded 4D60,
|
|
.I bstream
|
|
can stream the tape 70 to 80% of the time, achieving byte transfer rates
|
|
around 70K bytes per second.
|
|
'\".SH AUTHOR
|
|
'\"J. M. Barton
|