cpipe(1)							Programmer's Manual							  cpipe(1)

NAME

       cpipe - copy stdin to stdout while counting bytes and reporting progress

SYNOPSIS

       cpipe [-b bsize] [-vt] [-vr] [-vw] [-ngr] [-s speed]

OPTIONS

       -b     buffer size in kB,
	      1 Int value between 1 and oo.
	      Default: `128'

       -vt    show throughput.

       -vr    show read-times.

       -vw    show write-times.

       -ngr   non-greedy read. Don't enforce a full buffer on read before starting to write.

       -s     throughput speed limit in kB/s,
	      1 Double value between 1 and oo.

DESCRIPTION

       Cpipe  copies  its standard input to its standard output while measuring the time it takes to read an input buffer and write an output buf-
       fer. If one or more of the -vx options is given, statistics of average throughput and the total amount of bytes copied are printed  to  the
       standard error output.

   Non Greedy Read
       Normally, cpipe does its best to totally fill its buffer (option -b) before it starts writing. In some situations however, e.g. if you talk
       to an interactive program via cpipe, this deadlocks the communication: said program waits for input which it will never	see,  because  the
       input is stuck in cpipe's buffer. But cpipe itself will not see more input before the program does not respond.

       To  get	around	this,  try using -ngr.	When issuing a read call, cpipe is then satisfied as soon as it gets at least one byte. Instead of
       filling the buffer, it stops reading and writes whatever it got to the output. Note, however, that the throughput measurements will be less
       exact  if  the  number  of bytes transferred in one read/write pair becomes small, because cpipe will spent relatively more time working on
       every byte.

   Limiting Throughput
       If a throughput limit is specified with option -s, cpipe calls usleep(3) in between copying buffers,  thereby  artificially  extending  the
       duration  of  a	read/write-cycle.  Since  on most systems there is a certain minimum time usleep() sleeps, e.g. 0.01s, it is impossible to
       reach high limits with a small buffer size. In this case increasing the buffer size (option -b) might help. However, keep in mind that this
       limits the throughput only on the average. Every single buffer is copied as fast as possible.

EXAMPLE

       The command
	 tar cCf / - usr | cpipe -vr -vw -vt > /dev/null
       results in an output like
	 ...
	   in:	19.541ms at    6.4MB/s (   4.7MB/s avg)    2.0MB
	  out:	 0.004ms at   30.5GB/s (  27.1GB/s avg)    2.0MB
	 thru:	19.865ms at    6.3MB/s (   4.6MB/s avg)    2.0MB
	 ...
       The  first column shows the times it takes to handle one buffer of data (128kB by default).  The read-call took 19.541ms, the write-call to
       /dev/null took just 0.004ms and from the start of the read to the end of write, it took 19.865ms.

       The second column shows the result of dividing the buffer size (128kB by default) by the times in the first column.

       The third column contains the average over all measured values from the start of the program.

       Finally, the last column shows the total number of bytes transferred, which is of course the same for reading and writing.

BUGS

       This program uses precious processor cycles. Consequently the measured times will be different from the transfer rates possible without it.

       Instead of just non-greedy reading, full non-blocking I/O and use of select(2) should be used to make sure that	no  deadlocks  occur  when
       communicating with interactive programs.

CREDITS

       Peter Astrand <astrand@lysator.liu.se> recommended the speed limit.

       Ivo De Decker <ivo@zeus.rug.ac.be> asked for deadlock prevention, which is (hopefully) sufficiently covered by the non-greedy read.

AUTHOR

       Bug reports, beer and postcards go to pifpafpuf@gmx.de.	New versions will show up on
       http://cpipe.berlios.de/.

Clig-manuals							       3.0.0								  cpipe(1)