mbuffer.1.in

.TH "mbuffer" "1" "@PACKAGE_VERSION@" "Thomas Maier-Komor" "console utility"
.SH "NAME"
mbuffer \- measuring buffer
.SH "SYNTAX"
.LP 
mbuffer [\fIoptions\fP]
.SH "DESCRIPTION"
.LP 
mbuffer buffers I/O operations and displays the throughput rate. It is
multi-threaded, supports network connections, and offers more options
than the standard buffer.
.SH "OPTIONS"
.LP 
.TP
\fB\-i\fR <\fIfilename\fP>
Use \fIfilename\fP as input instead of the standard input (needs to be
given for multi volume support). If \fIfilename\fP is \-, input is read
from standard input.
.TP
\fB\-I\fR <\fIport\fP>
Use network port \fIport\fP as input instead of the standard input. If
given a hostname and a port in the form hostname:port, the first interface
with the IP of hostname will be used.
.TP
\fB\-o\fR <\fIfilename\fP>
Use \fIfilename\fP as output instead of the standard output (needs to be
given for multi volume support, will enable use of sendfile if
available). If \fIfilename\fP is \-, output is written to standard
output. The option \-o can be passed multiple times to specify multiple
outputs.
.TP
\fB\-O\fR <\fIhostname:port\fP>
Write output to \fIhostname:port\fP instead of the standard output (will
enable use of sendfile if available). This option can be used multiple
times to send data to multiple machines.
.TP
\fB\-b\fR <\fInum\fP>
Use \fInum\fP blocks for buffer (default 256).
.TP
\fB\-s\fR <\fIsize\fP>
Use blocks of \fIsize\fP bytes for buffer (default pagesize of system).
.TP
\fB\-m\fR <\fIsize\fP>
Use a total of \fIsize\fP bytes for buffer (default 2MB) \- size can be
set with a trailing character (b and B for Byte, k for kByte, M for
MByte, G for Gigabyte, and with % for a percentage of total physical 
memory).
.TP 
\fB\-L\fR
Lock buffer in memory \- this option is not available for file-based
buffers and requires mbuffer to be set-UID root (use with care).
.TP 
\fB\-n\fR <\fInum\fP>
\fInum\fP volumes in input device (requires use of option \-i for input
device specification, pass 0 as argument if mbuffer should prompt for every
new volume)
.TP 
\fB\-t\fR
use a memory-mapped temporary file as buffer (use with huge buffers)
.TP 
\fB\-T\fR <\fIfile\fP>
as \-t but use \fIfile\fP instead
.TP 
\fB\-d\fR
use block-size of device for output (needed for some devices, slows output down)
.TP 
\fB\-D\fR <\fIsize\fP>
assume an output volume of \fIsize\fP bytes (default infinite) after which
a volume change will be initiated. Small values are useful for the timely
testing of multi-volume runs; accurate values if your device doesn't properly
signal end of media. Size can be set with a trailing character (b and B
for Byte, k for kByte, M for MByte, or G for Gigabyte)
.TP 
\fB\-P\fR <\fInum\fP>
start writing after the buffer has been filled to \fInum\fP% (default 0 \- start at once)
.TP 
\fB\-p\fR <\fInum\fP>
start reading after the buffer has dropped below fill-ratio of \fInum\fP% (default 100 \- start at once)
.TP 
\fB\-l\fR <\fIfile\fP>
log messages to \fIfile\fP instead of standard error output
.TP 
\fB\-u\fR <\fInum\fP>
pause \fInum\fP microseconds after each write \- might increase performance on some drives with very low performance (< 1 MB/sec)
.TP 
\fB\-r\fR <\fIrate\fP>
Set the maximum read rate to <\fIrate\fP>. <\fIrate\fP> can be given in
either Bytes, kBytes, MBytes, or GBytes per second. To do so, use an appropriate
suffix (i.e. k,M,G). This option is useful if you have a tape that is
capable of transferring data faster than the host can handle it. In this
case you can use this option to limit the transfer rate and keep the
tape running. Be aware that this is both good for your tape drive, and
enhances overall performance, by avoiding tape screwing.
.TP 
\fB\-R\fR <\fIrate\fP>
Same as above only for setting the transfer limit for the writer.
.TP 
\fB\-A\fR <\fIcmd\fP>
the device used is an autoloader which uses \fIcmd\fP to load the next
volume. Pass <\fI/bin/false\fP> as an autoload command to suppress the
warning message that appears when run without controlling terminal (e.g.
via cron). Like this the autoload will fail and mbuffer will terminate
with an error message when reaching the end of the tape.
.TP 
\fB\-a\fR <\fItime\fP>
the device used is an autoloader which takes \fItime\fP seconds to load a new tape
.TP 
\fB\-f\fR
overwrite output file if it exists already
.TP 
\fB\-c\fR
write with synchronous data integrity support \- This option forces all
writes to complete before continuing. This enables errors to be reported
earlier and more precisely, but might decrease performance. Especially
systems with high level of data integrity support suffer a huge
performance hit. Others might seem to be unaffected, but just neglect
support for full synchronous data integrity.
.TP 
\fB\-v\fR <\fInum\fP>
set verbose level to \fInum\fP. Valid values are 0..6 (0 = none, 1 =
errors, 2 = warnings, 4 = information messages, 5 = debugging messages, 6 =
I/O debugging). Higher values include lower values messages.
.TP 
\fB\-q\fR
quiet \- do not display the status on the standard error output
.TP 
\fB\-Q\fR
quiet \- do not log the status in the log file
.TP 
\fB\-\-direct\fR
Use O_DIRECT to open file descriptors. This option is not available on
all systems. It tells the OS to bypass the page cache to improve
performance when reading and writing. On Solaris this is an auto-magic
option that is enabled if it is supported for the relevant file. Be
aware that this option might lead to read/write failures, if the buffer
isn't properly aligned for direct I/O. Additionally, open might fail
with EINVAL (i.e. invalid argument) if the named file does not support
O_DIRECT.
.TP 
\fB\-\-append\fR
Open next output file given via option \-o in append mode.
.TP 
\fB\-\-truncate\fR
Truncate next output file given via option \-o when opening it.
.TP 
\fB\-6\fR
Force IPv6 mode for the following network I/O options on command line.
\fB\-4\fR
Force IPv4 mode for the following network I/O options on command line.
\fB\-0\fR
Choose IPv4/IPv6 mode on demand.
.TP 
\fB\-h, \-\-help\fR
Output help information and exit.
.TP 
\fB\-H, \-\-md5\fR
Generate a MD5 hash of transferred data.
.TP 
\fB\-H, \-\-pid\fR
Print PID of current process. This option can help you to figure out
which instance of mbuffer to kill, if multiple are running and one is
hanging due to a network issue. Printing of the PID can also be
triggered by adding "printpid = 1" to your .mbuffer.rc file.
.TP 
\fB\-V, \-\-version\fR
Output version information and exit.
.TP 
\fB\-W\fR <\fItimeout\fP>
Activates a watchdog that gets triggered every \fItimeout\fP seconds and
checks weather I/O activity has stalled. If either channel has stalled
for a complete period, the watchdog writes an error message and
terminates mbuffer via SIGINT. Be aware that the watchdog is unaware of
tape-change activities. So choose the watchdog timeout greater that the
worst-case tape-change time.
.SH "DEFAULT VALUES"
The default values for following options can be set as \fIkey = value\fP pairs
in the ~/.mbuffer.rc file:
.br
\fIblocksize\fP: block size (option \-s)
.br
\fItimeout\fP: watchdog timeout (option \-W)
.br
\fItotalmem\fP: total buffer size (option \-m)
.br
\fImaxreadspeed\fP: maximum read speed (option \-r)
.br
\fImaxwritespeed\fP: maximum write speed (option \-R)
.br
\fIstartwrite\fP: threshold for start writing (option \-P)
.br
\fIstartread\fP: threshold for start reading (option \-p)
.br
\fIpause\fP: pause after writing a block (option \-u)
.br
\fInumblocks\fP: number of blocks in buffer (option \-b)
.br
\fImemlock\fP: lock buffer in memory (option \-L)
.br
\fIshowstatus\fP: print transfer status on console (option \-q)
.br
\fIlogstatus\fP: write transfer status to logfile (option \-Q)
.br
\fItcpbuffer\fP: TCP buffer size (option \-\-tcpbuffer)
.br


.SH "ENVIRONMENT VARIABLES"
If TMPDIR is set, mbuffer allocates storage for file-based buffers in this
directory\&. If TMPDIR is unset, \fI/var/tmp\fR will be used\&.
.SH "FILES"
.LP 
\fI@prefix@/bin/mbuffer\fP 
.br 
\fI/var/tmp/mbuffer-*\fP 
.br 
\fI~/.mbuffer.rc\fP 
.SH "EXAMPLES"
.LP 
To run this program with the default options just type:
.LP 
mbuffer
.LP 
.LP 
Using mbuffer to do a backup with tar to the default tape device. Options for this example: memory-mapped temporary file with a size of 10 Megabytes, start after 80% of the buffer have been filled.
.LP 
tar cf \- mydirectory | gzip | mbuffer \-t \-m 10M \-P 80 \-f \-o $TAPE
.LP 
.LP 
Using mbuffer with 3 tapes for input and extracting the contents in the current work directory:
.LP 
mbuffer \-n 3 \-i $TAPE | gzip \-dc | tar xf \-
.LP 
.LP 
Using mbuffer to write to multiple tape volumes:
.LP 
tar cf \- /usr | mbuffer \-f \-o $TAPE
.LP 
.LP 
Write to multiple tapes and erase every tape before writing:
.LP 
tar cf \- /usr | mbuffer \-A "echo next tape; read a < /dev/tty; mt erase $TAPE" \-f \-o $TAPE
.LP
.LP
Making a backup via network:
.LP 
\fItape server: \fPmbuffer \-I 8000 \-f \-o $TAPE
.LP 
\fIbackup client: \fPtar zcf \- /home | mbuffer \-O tapeserver:8000
.LP
.LP
Distributing a directory tree to multiple machines:
.LP
\fImaster: \fPtar cf \- /tree_to_clone | mbuffer \-O clone0:8000 \-O clone1:8000
.LP
\fIclones: \fPmbuffer \-I master:8000 | tar xf \-
.SH "EXITCODE"
.LP
mbuffer return 0 upon success. Any kind of failure will yield a non-zero
exit code.
.SH "AUTHORS"
.LP 
Thomas Maier\-Komor <thomas@maier\-komor.de>
.SH "DONATIONS"
.LP
If you like this software, and use it for production purposes in your
company, please consider making a donation to support this work. 
You can donate directly via PayPal to the author's e-mail address
(thomas@maier\-komor.de).
.SH "HOMEPAGE"
.LP
http://www.maier\-komor.de/mbuffer.html
.SH "LICENSE"
.LP
This software is published under GNU General Public License V3. See file
LICENSE for details.
.SH "SEE ALSO"
.LP 
buffer(1)