Provided by: buffer_1.19-11_amd64 bug

NAME

       buffer - very fast reblocking program

SYNTAX

       buffer  [-S  size]  [-b  blocks]  [-s  size]  [-z  size]  [-m  size]  [-p  percentage] [-u
       microseconds] [-B] [-t] [-Z] [-i filename] [-o filename] [-d]

OPTIONS

       -i filename
            Use the given file as the input file.  The default is stdin.

       -o filename
            Use the given file as the output file.  The default is stdout.

       -S size
            After every chunk of this size has been written, print out how much has been  written
            so far. Also prints the total throughput.  By default this is not set.

       -s size
            Size in bytes of each block.  The default blocksize is 10k to match the normal output
            of the tar(1) program.

       -z size
            Combines the -S and -s flags.

       -b blocks
            Number of blocks to allocate to shared  memory  circular  buffer.   Defaults  to  the
            number required to fill up the shared memory requested.

       -m size
            Maximum  size of the shared memory chunk to allocate for the circular queue. Defaults
            to one megabyte.

       -p percentage
            Only start a write when the given percentage  of  the  internal  queue  is  full.   A
            percentage around 75 often proves best. Defaults to zero.

       -u microseconds
            After every write pause for this many microseconds.  Defaults to zero.  (Surprisingly
            a small sleep, 100 usecs, after each write can greatly  enhance  throughput  on  some
            drives.)

       -B   Force  each  block written to be padded out to the blocksize.  This is needed by some
            tape and cartridge drives.  Defaults to unpadded.  This only affects the  last  block
            written.

       -t   On exiting print to stderr a brief message showing the total number of bytes written.

       -Z   If reading/writing directly to a character device (like a tape drive) then after each
            gigabyte perform an lseek to the start of the file.  Use this flag with extreme care.
            It can only be used on devices where an lseek does not rewind the tape but does reset
            the kernels position flags.  It is used to allow more than 2 gigabytes to be written.

       -d   Print debug information to stderr during operation.

       Sizes are a number with an optional trailing character.   A 'b'  multiplies  the  size  by
       512, a 'k' by 1024 and an 'm' by a meg.

DESCRIPTION

       Buffer  reads  from standard input reblocking to the given blocksize and writes each block
       to standard output.

       Internally buffer is a pair of processes communicating via a large circular queue held  in
       shared memory.  The reader process only has to block when the queue is full and the writer
       process when the queue is empty.  Buffer is designed to  try  and  keep  the  writer  side
       continuously  busy  so that it can stream when writing to tape drives.  When used to write
       tapes with an intervening  network  buffer  can  result  in  a  considerable  increase  in
       throughput.

       The  default  settings  for buffer are normally good enough.  If you are a heavy tape user
       then it is worth your while trying out various  different  combinations  of  options.   In
       particular  running  a  buffer at both ends of the pipe can provide a substantial increase
       (see last example below).

EXAMPLES

       $ buffer < /etc/termcap > /dev/rst8

       $ tar cf - . | rsh somehost 'buffer > /dev/rst8'

       $ dump fu - | rsh somehost 'buffer -s 16k > /dev/nrst8'
       $ tar cf - . | buffer |
          rsh somehost 'buffer -S 500K -p 75 > /dev/rst0'

BUFFER LIMITS

       There are 2 limits in buffer affecting the maximum total buffer size: The  maximum  number
       of  blocks (2048) and the maximum size of a block (512kB). This results in a maximum total
       buffer size of 1GB.

       Note that there is also a kernel limit for the maximum size of  a  shared  memory  segment
       (used  by  buffer internally) which is typically much lower than the limits in buffer.  So
       if buffer complains about not being able to create a shared  memory  segment,  this  limit
       might have to be raised using the command sysctl kernel.shmmax=XXX (see also sysctl(1) and
       proc(5)).

BUGS

       Internally, for printing purposes, buffer counts in  terms  of  the  number  of  kilobytes
       output.   If  the  blocksize  you  use is not a whole number of kilobytes then the numbers
       printed will be inaccurate.

THANKS

       Thanks to Kevin Twidle <kpt@doc.ic.ac.uk> for a lot of early suggestions  and  patches  to
       make it work with non-tar/dump tapes to exabyte drives.

       Thanks   to  Andi  Karrer  <karrer@bernina.ethz.ch>,  Rumi  Zahir  <rumi@iis.ethz.ch>  and
       Christoph Wicki <wicki@iis.ethz.ch> for patches to make buffer work when trying  to  write
       single tape files of greater than 2 gigabytes.

COPYRIGHT

       Copyright (C) 1990, 1991 by Lee McLoughlin.

SEE ALSO

       dd(1), tar(1), rsh(1)

                                           14 May 1990                                  BUFFER(1)