1cpipe(1)                      Programmer's Manual                     cpipe(1)
2
3
4

NAME

6       cpipe  -  copy  stdin  to  stdout  while  counting  bytes and reporting
7       progress
8
9

SYNOPSIS

11       cpipe [-b bsize] [-vt] [-vr] [-vw] [-ngr] [-s speed]
12
13
14

OPTIONS

16       -b     buffer size in kB,
17              1 Int value between 1 and oo.
18              Default: `128'
19
20       -vt    show throughput.
21
22       -vr    show read-times.
23
24       -vw    show write-times.
25
26       -ngr   non-greedy read. Don't enforce a  full  buffer  on  read  before
27              starting to write.
28
29       -s     throughput speed limit in kB/s,
30              1 Double value between 1 and oo.
31
32

DESCRIPTION

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
40
41   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
49       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
56
57
58   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
68

EXAMPLE

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
83       The  second  column shows the result of dividing the buffer size (128kB
84       by default) by the times in the first column.
85
86       The third column contains the average over all measured values from the
87       start of the program.
88
89       Finally,  the  last column shows the total number of bytes transferred,
90       which is of course the same for reading and writing.
91
92
93

BUGS

95       This program uses precious processor cycles. Consequently the  measured
96       times will be different from the transfer rates possible without it.
97
98       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
102
103

CREDITS

105       Peter Astrand <astrand@lysator.liu.se> recommended the speed limit.
106
107       Ivo De Decker <ivo@zeus.rug.ac.be> asked for deadlock prevention, which
108       is (hopefully) sufficiently covered by the non-greedy read.
109
110

AUTHOR

112       Bug reports, beer and postcards go to pifpafpuf@gmx.de.   New  versions
113       will show up on
114       http://cpipe.berlios.de/.
115
116
117
118
119
120Clig-manuals                         3.0.0                            cpipe(1)
Impressum