1cpipe(1) Programmer's Manual cpipe(1)
2
6 cpipe - copy stdin to stdout while counting bytes and reporting
7 progress
8
11 cpipe [-b bsize] [-vt] [-vr] [-vw] [-ngr] [-s speed]
12
16 -b buffer size in kB,
17 1 Int value between 1 and oo.
18 Default: `128'
19 -vt show throughput.
21 -vr show read-times.
23 -vw show write-times.
25 -ngr non-greedy read. Don't enforce a full buffer on read before
27 starting to write.
28 -s throughput speed limit in kB/s,
30 1 Double value between 1 and oo.
31
34 Cpipe copies its standard input to its standard output while measuring
35 the time it takes to read an input buffer and write an output buffer.
36 If one or more of the -vx options is given, statistics of average
37 throughput and the total amount of bytes copied are printed to the
38 standard error output.
39 Non Greedy Read
42 Normally, cpipe does its best to totally fill its buffer (option -b)
43 before it starts writing. In some situations however, e.g. if you talk
44 to an interactive program via cpipe, this deadlocks the communication:
45 said program waits for input which it will never see, because the input
46 is stuck in cpipe's buffer. But cpipe itself will not see more input
47 before the program does not respond.
48 To get around this, try using -ngr. When issuing a read call, cpipe is
50 then satisfied as soon as it gets at least one byte. Instead of filling
51 the buffer, it stops reading and writes whatever it got to the output.
52 Note, however, that the throughput measurements will be less exact if
53 the number of bytes transferred in one read/write pair becomes small,
54 because cpipe will spent relatively more time working on every byte.
55 Limiting Throughput
59 If a throughput limit is specified with option -s, cpipe calls
60 usleep(3) in between copying buffers, thereby artificially extending
61 the duration of a read/write-cycle. Since on most systems there is a
62 certain minimum time usleep() sleeps, e.g. 0.01s, it is impossible to
63 reach high limits with a small buffer size. In this case increasing the
64 buffer size (option -b) might help. However, keep in mind that this
65 limits the throughput only on the average. Every single buffer is
66 copied as fast as possible.
67
70 The command
71 tar cCf / - usr | cpipe -vr -vw -vt > /dev/null
72 results in an output like
73 ...
74 in: 19.541ms at 6.4MB/s ( 4.7MB/s avg) 2.0MB
75 out: 0.004ms at 30.5GB/s ( 27.1GB/s avg) 2.0MB
76 thru: 19.865ms at 6.3MB/s ( 4.6MB/s avg) 2.0MB
77 ...
78 The first column shows the times it takes to handle one buffer of data
79 (128kB by default). The read-call took 19.541ms, the write-call to
80 /dev/null took just 0.004ms and from the start of the read to the end
81 of write, it took 19.865ms.
82 The second column shows the result of dividing the buffer size (128kB
84 by default) by the times in the first column.
85 The third column contains the average over all measured values from the
87 start of the program.
88 Finally, the last column shows the total number of bytes transferred,
90 which is of course the same for reading and writing.
91
95 This program uses precious processor cycles. Consequently the measured
96 times will be different from the transfer rates possible without it.
97 Instead of just non-greedy reading, full non-blocking I/O and use of
99 select(2) should be used to make sure that no deadlocks occur when com‐
100 municating with interactive programs.
101
105 Peter Astrand <astrand@lysator.liu.se> recommended the speed limit.
106 Ivo De Decker <ivo@zeus.rug.ac.be> asked for deadlock prevention, which
108 is (hopefully) sufficiently covered by the non-greedy read.
109
112 Bug reports, beer and postcards go to pifpafpuf@gmx.de. New versions
113 will show up on
114 http://cpipe.berlios.de/.
115Clig-manuals 3.0.0 cpipe(1)