1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
.\" clig manual page template
.\" (C) 1995-2001 Harald Kirsch (kirschh@lionbioscience.com)
.\"
.\" This file was generated by
.\" clig -- command line interface generator
.\"
.\"
.\" Clig will always edit the lines between pairs of `cligPart ...',
.\" but will not complain, if a pair is missing. So, if you want to
.\" make up a certain part of the manual page by hand rather than have
.\" it edited by clig, remove the respective pair of cligPart-lines.
.\"
.\" cligPart TITLE
.TH "cpipe" 1 "3.0.1" "Clig-manuals" "Programmer's Manual"
.\" cligPart TITLE end
.\" cligPart NAME
.SH NAME
cpipe \- copy stdin to stdout while counting bytes and reporting progress
.\" cligPart NAME end
.\" cligPart SYNOPSIS
.SH SYNOPSIS
.B cpipe
[-b bsize]
[-vt]
[-vr]
[-vw]
[-ngr]
[-s speed]
[-p prefix]
.\" cligPart SYNOPSIS end
.\" cligPart OPTIONS
.SH OPTIONS
.IP -b
buffer size in kB,
.br
1 Int value between 1 and oo.
.br
Default: `128'
.IP -vt
show throughput.
.IP -vr
show read-times.
.IP -vw
show write-times.
.IP -ngr
non-greedy read. Don't enforce a full buffer
on read before starting to write.
.IP -s
throughput speed limit in kB/s,
.br
1 Double value between 1 and oo.
.IP -p
optional prefix to each printed line,
.br
1 String value
.\" cligPart OPTIONS end
.\" cligPart DESCRIPTION
.SH DESCRIPTION
.B 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
.BI -v x
options is given, statistics of average throughput and the total
amount of bytes copied are printed to the standard error output.
.SS Non Greedy Read
Normally, cpipe does its best to totally fill its buffer (option
.BR -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
.BR -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.
.SS Limiting Throughput
If a throughput limit is specified with option
.BR -s ,
.B cpipe
calls
.BR 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
.BR -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.
.SH EXAMPLE
The command
.nf
tar cCf / - usr | cpipe -vr -vw -vt > /dev/null
.fi
results in an output like
.nf
...
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
...
.fi
The
.I 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
.I second column
shows the result of dividing the buffer size (128kB by default) by the
times in the first column.
The
.I "third column"
contains the average over all measured values from the start of the
program.
Finally, the
.I "last column"
shows the total number of bytes transferred, which is of course the
same for reading and writing.
.SH 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.
.SH 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.
.SH AUTHOR
Bug reports, beer and postcards go to
.IR pifpafpuf@gmx.de .
New versions will show up on
.br
.IR http://cpipe.berlios.de/ .
.\" cligPart DESCRIPTION end
|
