BUFFER(1)						      General Commands Manual							 BUFFER(1)

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  continu-
       ously  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 dif-
       ferent combinations of options.	In particular running a buffer at both ends of the pipe can provide a substantial increase (see last exam-
       ple 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 num-
       ber 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)