Provided by: mbuffer_20110119-2_i386 bug

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)