1PV(1) User Manuals PV(1)
2
3
4
6 pv - monitor the progress of data through a pipe
7
9 pv [OPTION] [FILE]...
10 pv [-h|-V]
11
12
13
15 pv allows a user to see the progress of data through a pipeline, by
16 giving information such as time elapsed, percentage completed (with
17 progress bar), current throughput rate, total data transferred, and
18 ETA.
19
20 To use it, insert it in a pipeline between two processes, with the
21 appropriate options. Its standard input will be passed through to its
22 standard output and progress will be shown on standard error.
23
24 pv will copy each supplied FILE in turn to standard output (- means
25 standard input), or if no FILEs are specified just standard input is
26 copied. This is the same behaviour as cat(1).
27
28 A simple example to watch how quickly a file is transferred using
29 nc(1):
30
31 pv file | nc -w 1 somewhere.com 3000
32
33 A similar example, transferring a file from another process and passing
34 the expected size to pv:
35
36 cat file | pv -s 12345 | nc -w 1 somewhere.com 3000
37
38 A more complicated example using numeric output to feed into the dia‐
39 log(1) program for a full-screen progress display:
40
41 (tar cf - . \
42 | pv -n -s `du -sb . | awk '{print $1}'` \
43 | gzip -9 > out.tgz) 2>&1 \
44 | dialog --gauge 'Progress' 7 70
45
46 Frequent use of this third form is not recommended as it may cause the
47 programmer to overheat.
48
49
50
52 pv takes many options, which are divided into display switches, output
53 modifiers, and general options.
54
55
56
58 If no display switches are specified, pv behaves as if -p, -t, -e, -r,
59 and -b had been given (i.e. everything is switched on). Otherwise, only
60 those display types that are explicitly switched on will be shown.
61
62 -p, --progress
63 Turn the progress bar on. If standard input is not a file and
64 no size was given (with the -s modifier), the progress bar can‐
65 not indicate how close to completion the transfer is, so it will
66 just move left and right to indicate that data is moving.
67
68 -t, --timer
69 Turn the timer on. This will display the total elapsed time
70 that pv has been running for.
71
72 -e, --eta
73 Turn the ETA timer on. This will attempt to guess, based on
74 previous transfer rates and the total data size, how long it
75 will be before completion. This option will have no effect if
76 the total data size cannot be determined.
77
78 -r, --rate
79 Turn the rate counter on. This will display the current rate of
80 data transfer.
81
82 -b, --bytes
83 Turn the total byte counter on. This will display the total
84 amount of data transferred so far.
85
86 -n, --numeric
87 Numeric output. Instead of giving a visual indication of
88 progress, pv will give an integer percentage, one per line, on
89 standard error, suitable for piping (via convoluted redirection)
90 into dialog(1). Note that -f is not required if -n is being
91 used.
92
93 -q, --quiet
94 No output. Useful if the -L option is being used on its own to
95 just limit the transfer rate of a pipe.
96
97
98
100 -W, --wait
101 Wait until the first byte has been transferred before showing
102 any progress information or calculating any ETAs. Useful if the
103 program you are piping to or from requires extra information
104 before it starts, eg piping data into gpg(1) or mcrypt(1) which
105 require a passphrase before data can be processed.
106
107 -s SIZE, --size SIZE
108 Assume the total amount of data to be transferred is SIZE bytes
109 when calculating percentages and ETAs. The same suffixes of
110 "k", "m" etc can be used as with -L.
111
112 -l, --line-mode
113 Instead of counting bytes, count lines (newline characters). The
114 progress bar will only move when a new line is found, and the
115 value passed to the -s option will be interpreted as a line
116 count.
117
118 -i SEC, --interval SEC
119 Wait SEC seconds between updates. The default is to update
120 every second. Note that this can be a decimal such as 0.1.
121
122 -w WIDTH, --width WIDTH
123 Assume the terminal is WIDTH characters wide, instead of trying
124 to work it out (or assuming 80 if it cannot be guessed).
125
126 -H HEIGHT, --height HEIGHT
127 Assume the terminal is HEIGHT rows high, instead of trying to
128 work it out (or assuming 25 if it cannot be guessed).
129
130 -N NAME, --name NAME
131 Prefix the output information with NAME. Useful in conjunction
132 with -c if you have a complicated pipeline and you want to be
133 able to tell different parts of it apart.
134
135 -f, --force
136 Force output. Normally, pv will not output any visual display
137 if standard error is not a terminal. This option forces it to
138 do so.
139
140 -c, --cursor
141 Use cursor positioning escape sequences instead of just using
142 carriage returns. This is useful in conjunction with -N (name)
143 if you are using multiple pv invocations in a single, long,
144 pipeline.
145
146
147
149 -L RATE, --rate-limit RATE
150 Limit the transfer to a maximum of RATE bytes per second. A
151 suffix of "k", "m", "g", or "t" can be added to denote kilobytes
152 (*1024), megabytes, and so on.
153
154 -B BYTES, --buffer-size BYTES
155 Use a transfer buffer size of BYTES bytes. A suffix of "k",
156 "m", "g", or "t" can be added to denote kilobytes (*1024),
157 megabytes, and so on. The default buffer size is the block size
158 of the input file's filesystem multiplied by 32 (512kb max), or
159 400kb if the block size cannot be determined.
160
161 -R PID, --remote PID
162 If PID is an instance of pv that is already running, -R PID will
163 cause that instance to act as though it had been given this
164 instance's command line instead. For example, if pv -L 123k is
165 running with process ID 9876, then running pv -R 9876 -L 321k
166 will cause it to start using a rate limit of 321k instead of
167 123k. Note that some options cannot be changed while running,
168 such as -c, -l, and -f.
169
170
171
173 -h, --help
174 Print a usage message on standard output and exit successfully.
175
176 -V, --version
177 Print version information on standard output and exit success‐
178 fully.
179
180
181
183 Andrew Wood <andrew.wood@ivarch.com>
184 http://www.ivarch.com/
185
186 Kevin Coyner <kcoyner@debian.org>
187 (Debian package maintainer)
188
189 Jakub Hrozek <jhrozek@redhat.com>
190 (Fedora package maintainer)
191
192 Cedric Delfosse <cedric@debian.org>
193 (previous Debian package maintainer)
194
195 Eduardo Aguiar <eduardo.oliveira@sondabrasil.com.br>
196 (provided Portuguese [Brazilian] translation)
197
198 Stephane Lacasse <tecknojunky@tecknojunky.com>
199 (provided French translation)
200 http://www.tecknojunky.com/
201
202 Marcos Kreinacke <public@kreinacke.com>
203 (provided German translation)
204
205 Bartosz Fenski <fenio@o2.pl>
206 (provided Polish translation, along with Krystian Zubel)
207 http://skawina.eu.org/
208
209 Joshua Jensen
210 (reported RPM installation bug)
211
212 Boris Folgmann
213 (reported cursor handling bug)
214 http://www.folgmann.com/en/
215
216 Mathias Gumz
217 (reported NLS bug)
218
219 Daniel Roethlisberger
220 (submitted patch to use lockfiles for -c if terminal locking fails)
221
222 Adam Buchbinder
223 (lots of help with a Cygwin port of -c)
224
225 Mark Tomich
226 (suggested -B option)
227 http://metuchen.dyndns.org
228
229 Gert Menke
230 (reported bug when piping to dd with a large input buffer size)
231
232 Ville Herva <Ville.Herva@iki.fi>
233 (informative bug report about rate limiting performance)
234
235 Elias Pipping
236 (patch to compile properly on Darwin 9)
237
238 Patrick Collison
239 (similar patch for OS X)
240
241 Boris Lohner
242 (reported problem that -L does not complain if given non-numeric value)
243
244 Laszlo Ersek
245 (reported shared memory leak on SIGINT with -c)
246 http://phptest11.atw.hu/
247
248
249
251 If you find any bugs, please contact the primary author, either by
252 email or by using the contact form on the web site.
253
254
255
257 cat(1), dialog(1)
258
259
260
262 This is free software, distributed under the ARTISTIC 2.0 license.
263
264
265
266Linux March 2008 PV(1)