1PV(1) User Manuals PV(1)
2
6 pv - monitor the progress of data through a pipe
7
9 pv [OPTION] [FILE]...
10 pv [-h|-V]
11
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 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 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 A simple example to watch how quickly a file is transferred using
29 nc(1):
30 pv file | nc -w 1 somewhere.com 3000
32 A similar example, transferring a file from another process and passing
34 the expected size to pv:
35 cat file | pv -s 12345 | nc -w 1 somewhere.com 3000
37 A more complicated example using numeric output to feed into the dia‐
39 log(1) program for a full-screen progress display:
40 (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 Frequent use of this third form is not recommended as it may cause the
47 programmer to overheat.
48
52 pv takes many options, which are divided into display switches, output
53 modifiers, and general options.
54
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 -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 -t, --timer
69 Turn the timer on. This will display the total elapsed time
70 that pv has been running for.
71 -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 -r, --rate
79 Turn the rate counter on. This will display the current rate of
80 data transfer.
81 -b, --bytes
83 Turn the total byte counter on. This will display the total
84 amount of data transferred so far.
85 -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 -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
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 -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 -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 -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 -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 -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 -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 -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 -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
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 -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 -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
173 -h, --help
174 Print a usage message on standard output and exit successfully.
175 -V, --version
177 Print version information on standard output and exit success‐
178 fully.
179
183 Andrew Wood <andrew.wood@ivarch.com>
184 http://www.ivarch.com/
185 Kevin Coyner <kcoyner@debian.org>
187 (Debian package maintainer)
188 Jakub Hrozek <jhrozek@redhat.com>
190 (Fedora package maintainer)
191 Cedric Delfosse <cedric@debian.org>
193 (previous Debian package maintainer)
194 Eduardo Aguiar <eduardo.oliveira@sondabrasil.com.br>
196 (provided Portuguese [Brazilian] translation)
197 Stephane Lacasse <tecknojunky@tecknojunky.com>
199 (provided French translation)
200 http://www.tecknojunky.com/
201 Marcos Kreinacke <public@kreinacke.com>
203 (provided German translation)
204 Bartosz Fenski <fenio@o2.pl>
206 (provided Polish translation, along with Krystian Zubel)
207 http://skawina.eu.org/
208 Joshua Jensen
210 (reported RPM installation bug)
211 Boris Folgmann
213 (reported cursor handling bug)
214 http://www.folgmann.com/en/
215 Mathias Gumz
217 (reported NLS bug)
218 Daniel Roethlisberger
220 (submitted patch to use lockfiles for -c if terminal locking fails)
221 Adam Buchbinder
223 (lots of help with a Cygwin port of -c)
224 Mark Tomich
226 (suggested -B option)
227 http://metuchen.dyndns.org
228 Gert Menke
230 (reported bug when piping to dd with a large input buffer size)
231 Ville Herva <Ville.Herva@iki.fi>
233 (informative bug report about rate limiting performance)
234
238 If you find any bugs, please contact the primary author, either by
239 email or by using the contact form on the web site.
240
244 cat(1), dialog(1)
245
249 This is free software, distributed under the ARTISTIC 2.0 license.
250Linux August 2007 PV(1)