NAME¶
mbuffer - measuring buffer
SYNTAX¶
mbuffer [
options]
DESCRIPTION¶
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.
OPTIONS¶
- -i <filename>
- Use filename as input instead of the standard input
(needs to be given for multi volume support). If filename is -,
input is read from standard input.
- -I <port>
- Use network port port 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.
- -o <filename>
- Use filename as output instead of the standard
output (needs to be given for multi volume support, will enable use of
sendfile if available). If filename is -, output is written to
standard output. The option -o can be passed multiple times to specify
multiple outputs.
- -O <hostname:port>
- Write output to hostname:port 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.
- -b <num>
- Use num blocks for buffer (default 256).
- -s <size>
- Use blocks of size bytes for buffer (default
pagesize of system).
- -m <size>
- Use a total of size 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).
- -L
- Lock buffer in memory - this option is not available for
file-based buffers and requires mbuffer to be set-UID root (use with
care).
- -n <num>
- num volumes in input device (requires use of option
-i for input device specification) [currently multi volume support is
EXPERIMENTAL]
- -t
- use a memory-mapped temporary file as buffer (use with huge
buffers)
- -T <file>
- as -t but use file instead
- -d
- use block-size of device for output (needed for some
devices, slows output down)
- -D <size>
- assume an output volume of size 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)
- -P <num>
- start writing after the buffer has been filled to
num% (default 0 - start at once)
- -p <num>
- start reading after the buffer has dropped below fill-ratio
of num% (default 100 - start at once)
- -l <file>
- log messages to file instead of standard error
output
- -u <num>
- pause num microseconds after each write - might
increase performance on some drives with very low performance (< 1
MB/sec)
- -r <rate>
- Set the maximum read rate to <rate>.
<rate> 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.
- -R <rate>
- Same as above only for setting the transfer limit for the
writer.
- -A <cmd>
- the device used is an autoloader which uses cmd to
load the next volume
- -a <time>
- the device used is an autoloader which takes time
seconds to load a new tape
- -f
- overwrite output file if it exists already
- -c
- 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.
- -v <num>
- set verbose level to num. 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.
- -q
- quiet - do not display the status on the standard error
output --direct 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.
- -6
- Force IPv6 mode for the following network I/O options on
command line. -4 Force IPv4 mode for the following network I/O
options on command line. -0 Choose IPv4/IPv6 mode on demand.
- -h, --help
- Output help information and exit.
- -H, --md5
- Generate a MD5 hash of transferred data.
- -V, --version
- Output version information and exit.
ENVIRONMENT VARIABLES¶
If TMPDIR is set, mbuffer allocates storage for file-based buffers in this
directory. If TMPDIR is unset,
/var/tmp will be used.
FILES¶
/usr/bin/mbuffer
/var/tmp/mbuffer-*
EXAMPLES¶
To run this program with the default options just type:
mbuffer
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.
tar cf - mydirectory | gzip | mbuffer -t -m 10M -P 80 -f -o $TAPE
Using mbuffer with 3 tapes for input and extracting the contents in the current
work directory:
mbuffer -n 3 -i $TAPE | gzip -dc | tar xf -
Using mbuffer to write to multiple tape volumes:
tar cf - /usr | mbuffer -f -o $TAPE
Write to multiple tapes and erase every tape before writing:
tar cf - /usr | mbuffer -A "echo next tape; read a < /dev/tty; mt erase
$TAPE" -f -o $TAPE
Making a backup via network:
tape server: mbuffer -I 8000 -f -o $TAPE
backup client: tar zcf - /home | mbuffer -O tapeserver:8000
Distributing a directory tree to multiple machines:
master: tar cf - /tree_to_clone | mbuffer -O clone0:8000 -O clone1:8000
clones: mbuffer -I master:8000 | tar xf -
EXITCODE¶
mbuffer return 0 upon success. Any kind of failure will yield a non-zero exit
code.
AUTHORS¶
Thomas Maier-Komor <thomas@maier-komor.de>
DONATIONS¶
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).
HOMEPAGE¶
http://www.maier-komor.de/mbuffer.html
LICENSE¶
This software is published under GNU General Public License V3. See file LICENSE
for details.
SEE ALSO¶
buffer(1)