cpipe man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

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  buffer.
       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 com‐
       municating 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.1			      cpipe(1)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net