1PV(1)                            User Manuals                            PV(1)
2
3
4

NAME

6       pv - monitor the progress of data through a pipe
7

SYNOPSIS

9       pv [OPTION] [FILE]...
10       pv [-h|-V]
11
12
13

DESCRIPTION

15       pv  shows the progress of data through a pipeline by giving information
16       such as time elapsed, percentage completed (with progress bar), current
17       throughput rate, total data transferred, and ETA.
18
19       To  use  it,  insert  it  in a pipeline between two processes, with the
20       appropriate options.  Its standard input will be passed through to  its
21       standard output and progress will be shown on standard error.
22
23       pv  will  copy  each  supplied FILE in turn to standard output (- means
24       standard input), or if no FILEs are specified just  standard  input  is
25       copied. This is the same behaviour as cat(1).
26
27       A  simple  example  to  watch  how  quickly a file is transferred using
28       nc(1):
29
30              pv file | nc -w 1 somewhere.com 3000
31
32       A similar example, transferring a file from another process and passing
33       the expected size to pv:
34
35              cat file | pv -s 12345 | nc -w 1 somewhere.com 3000
36
37       A  more  complicated example using numeric output to feed into the dia‐
38       log(1) program for a full-screen progress display:
39
40              (tar cf - . \
41               | pv -n -s $(du -sb . | awk '{print $1}') \
42               | gzip -9 > out.tgz) 2>&1 \
43              | dialog --gauge 'Progress' 7 70
44
45       Taking an image of a disk, skipping errors:
46
47              pv -EE /dev/sda > disk-image.img
48
49       Writing an image back to a disk:
50
51              pv disk-image.img > /dev/sda
52
53       Zeroing a disk:
54
55              pv < /dev/zero > /dev/sda
56
57       Note that if the input size cannot be calculated, and the output  is  a
58       block  device,  then  the  size of the block device will be used and pv
59       will automatically stop at that size as if -S had been given.
60
61       (Linux only): Watching file descriptor  3  opened  by  another  process
62       1234:
63
64              pv -d 1234:3
65
66       (Linux only): Watching all file descriptors used by process 1234:
67
68              pv -d 1234
69
70
71

OPTIONS

73       pv  takes many options, which are divided into display switches, output
74       modifiers, and general options.
75
76
77

DISPLAY SWITCHES

79       If no display switches are specified, pv behaves as if -p, -t, -e,  -r,
80       and  -b had been given (i.e. everything except average rate is switched
81       on).  Otherwise, only those display types that are explicitly  switched
82       on will be shown.
83
84       -p, --progress
85              Turn  the  progress bar on.  If standard input is not a file and
86              no size was given (with the -s modifier), the progress bar  can‐
87              not indicate how close to completion the transfer is, so it will
88              just move left and right to indicate that data is moving.
89
90       -t, --timer
91              Turn the timer on.  This will display  the  total  elapsed  time
92              that pv has been running for.
93
94       -e, --eta
95              Turn  the  ETA  timer  on.  This will attempt to guess, based on
96              previous transfer rates and the total data  size,  how  long  it
97              will  be  before completion.  This option will have no effect if
98              the total data size cannot be determined.
99
100       -I, --fineta
101              Turn the ETA timer on, but display the estimated local  time  of
102              arrival  instead  of time left.  When the estimated time is more
103              than 6 hours in the future, the date is shown as well.
104
105       -r, --rate
106              Turn the rate counter on.  This will display the current rate of
107              data transfer.
108
109       -a, --average-rate
110              Turn the average rate counter on.  This will display the average
111              rate of data transfer so far.
112
113       -b, --bytes
114              Turn the total byte counter on.  This  will  display  the  total
115              amount of data transferred so far.
116
117       -T, --buffer-percent
118              Turn  on the transfer buffer percentage display.  This will show
119              the percentage of the transfer buffer  in  use  -  but  see  the
120              caveat under %T in the FORMATTING section below.
121
122       -A, --last-written NUM
123              Show  the  last NUM bytes written - but see the caveat under %nA
124              in the FORMATTING section below.
125
126       -F, --format FORMAT
127              Ignore the options -p, -t, -e, -r,  -a,  -b,  -T,  and  -A,  and
128              instead  use  the  format  string FORMAT to determine the output
129              format.  See the FORMATTING section below.
130
131       -n, --numeric
132              Numeric output.   Instead  of  giving  a  visual  indication  of
133              progress,  pv  will give an integer percentage, one per line, on
134              standard error, suitable for piping (via convoluted redirection)
135              into  dialog(1).   Note  that  -f is not required if -n is being
136              used.
137
138              Note that if --numeric is in use, then adding --bytes will cause
139              the  number  of bytes processed so far to be output instead of a
140              percentage; if --line-mode is also in use, then instead of bytes
141              or  a  percentage,  the  number  of lines so far is output.  And
142              finally, if --timer is also in use, then  each  output  line  is
143              prefixed  with  the  elapsed time so far, as a decimal number of
144              seconds.
145
146       -q, --quiet
147              No output.  Useful if the -L option is being used on its own  to
148              just limit the transfer rate of a pipe.
149
150
151

OUTPUT MODIFIERS

153       -W, --wait
154              Wait  until  the  first byte has been transferred before showing
155              any progress information or calculating any ETAs.  Useful if the
156              program  you  are  piping  to or from requires extra information
157              before it starts, eg piping data into gpg(1) or mcrypt(1)  which
158              require a passphrase before data can be processed.
159
160       -D, --delay-start SEC
161              Wait  until  SEC seconds have passed before showing any progress
162              information, for example in a script where you only want to show
163              a  progress bar if it starts taking a long time.  Note that this
164              can be a decimal such as 0.5.
165
166       -s SIZE, --size SIZE
167              Assume the total amount of data to be transferred is SIZE  bytes
168              when  calculating  percentages  and  ETAs.  The same suffixes of
169              "k", "m" etc can be used as with -L.
170
171              Has no effect if used with -d PID to watch all file  descriptors
172              of a process, but will work with -d PID:FD.
173
174       -l, --line-mode
175              Instead of counting bytes, count lines (newline characters). The
176              progress bar will only move when a new line is  found,  and  the
177              value  passed  to  the  -s  option will be interpreted as a line
178              count.  Note that file sizes are  not  automatically  calculated
179              when  this  option  is  used,  to avoid having to read all files
180              twice.
181
182       -0, --null
183              Count  lines  as   null   terminated.    This   option   implies
184              --line-mode.
185
186       -i SEC, --interval SEC
187              Wait  SEC  seconds  between  updates.   The default is to update
188              every second.  Note that this can be a decimal such as 0.1.
189
190       -w WIDTH, --width WIDTH
191              Assume the terminal is WIDTH characters wide, instead of  trying
192              to work it out (or assuming 80 if it cannot be guessed).
193
194       -H HEIGHT, --height HEIGHT
195              Assume  the  terminal  is HEIGHT rows high, instead of trying to
196              work it out (or assuming 25 if it cannot be guessed).
197
198       -N NAME, --name NAME
199              Prefix the output information with NAME.  Useful in  conjunction
200              with  -c  if  you have a complicated pipeline and you want to be
201              able to tell different parts of it apart.
202
203       -f, --force
204              Force output.  Normally, pv will not output any  visual  display
205              if  standard  error is not a terminal.  This option forces it to
206              do so.
207
208       -c, --cursor
209              Use cursor positioning escape sequences instead  of  just  using
210              carriage  returns.  This is useful in conjunction with -N (name)
211              if you are using multiple pv  invocations  in  a  single,  long,
212              pipeline.
213
214
215

DATA TRANSFER MODIFIERS

217       -L RATE, --rate-limit RATE
218              Limit  the  transfer  to  a maximum of RATE bytes per second.  A
219              suffix of "K", "M", "G", or "T" can be added to denote kibibytes
220              (*1024), mebibytes, and so on.
221
222       -B BYTES, --buffer-size BYTES
223              Use  a  transfer  buffer  size of BYTES bytes.  A suffix of "K",
224              "M", "G", or "T" can  be  added  to  denote  kibibytes  (*1024),
225              mebibytes, and so on.  The default buffer size is the block size
226              of the input file's filesystem multiplied by 32 (512KiB max), or
227              400KiB if the block size cannot be determined.
228
229       -C, --no-splice
230              Never use splice(2), even if it would normally be possible.  The
231              splice(2) system call is a more efficient  way  of  transferring
232              data  from  or  to a pipe than regular read(2) and write(2), but
233              means that the transfer buffer may not be used.   This  prevents
234              -A  and -T from working, so if you want to use -A or -T then you
235              will need to use -C, at the cost of a  small  loss  in  transfer
236              efficiency.   (This  option  has  no  effect  on  systems  where
237              splice(2) is unavailable).
238
239       -E, --skip-errors
240              Ignore read errors by attempting to skip past the offending sec‐
241              tions.   The  corresponding  parts  of  the  output will be null
242              bytes.  At first only a few bytes will be skipped, but if  there
243              are  many  errors in a row then the skips will move up to chunks
244              of 512.  This is intended to be similar to dd  conv=sync,noerror
245              but has not been as thoroughly tested.
246
247              Specify  -E  twice  to  only  report a read error once per file,
248              instead of reporting each byte range skipped.
249
250       -S, --stop-at-size
251              If a size was specified with -s,  stop  transferring  data  once
252              that  many bytes have been written, instead of continuing to the
253              end of input.
254
255       -d PID[:FD], --watchfd PID[:FD]
256              Instead of  transferring  data,  watch  file  descriptor  FD  of
257              process  PID,  and  show its progress.  The pv process will exit
258              when FD either changes to a different file,  changes  read/write
259              mode,  or  is closed; other data transfer modifiers - and remote
260              control - may not be used with this option.
261
262              If only a PID is specified, then that process will  be  watched,
263              and  all  regular files and block devices it opens will be shown
264              with a progress bar.  The pv process will exit when process  PID
265              exits.
266
267       -R PID, --remote PID
268              If PID is an instance of pv that is already running, -R PID will
269              cause that instance to act as though  it  had  been  given  this
270              instance's  command line instead.  For example, if pv -L 123K is
271              running with process ID 9876, then running pv -R  9876  -L  321K
272              will  cause  it to start using a rate limit of 321KiB instead of
273              123KiB.  Note that some options cannot be changed while running,
274              such as -c, -l, -f, -D, -E, and -S.
275
276

GENERAL OPTIONS

278       -P FILE, --pidfile FILE
279              Save  the  process ID of pv in FILE.  The file will be truncated
280              if it already exists, and will be removed when pv exits.   While
281              pv  is running, it will contain a single number - the process ID
282              of pv - followed by a newline.
283
284       -h, --help
285              Print a usage message on standard output and exit successfully.
286
287       -V, --version
288              Print version information on standard output and  exit  success‐
289              fully.
290
291
292

FORMATTING

294       If  the -F option is given, then the output format is determined by the
295       given format string.  Within that string, the following  sequences  can
296       be used:
297
298       %p     Progress  bar.  Expands to fill the remaining space. Should only
299              be specified once.  Equivalent to -p.
300
301       %t     Elapsed time.  Equivalent to -t.
302
303       %e     ETA as time remaining.  Equivalent to -e.
304
305       %I     ETA as local time of completion.  Equivalent to -I.
306
307       %r     Current data transfer rate.  Equivalent to -r.
308
309       %a     Average data transfer rate.  Equivalent to -a.
310
311       %b     Bytes transferred so far (or lines if -l was specified).  Equiv‐
312              alent to -b.
313
314       %T     Percentage  of  the  transfer  buffer in use.  Equivalent to -T.
315              Shows "{----}" if the transfer is  being  done  with  splice(2),
316              since splicing to or from pipes does not use the buffer.
317
318       %nA    Show  the  last  n  bytes  written  (e.g.   %16A for the last 16
319              bytes).  Shows only dots if the  transfer  is  being  done  with
320              splice(2), since splicing to or from pipes does not use the buf‐
321              fer.
322
323       %N     Name prefix given by -N.  Padded to 9  characters  with  spaces,
324              and suffixed with :.
325
326       %%     A single %.
327
328       The  format string equivalent of turning on all display switches is `%N
329       %b %T %t %r %a %p %e'.
330
331
332

COMMON SWITCHES

334       Some suggested common switch combinations:
335
336
337       pv -ptebar
338              Show a progress bar, elapsed time,  estimated  completion  time,
339              byte counter, average rate, and current rate.
340
341       pv -betlap
342              Show  a  progress  bar, elapsed time, estimated completion time,
343              line counter, and average rate, counting lines instead of bytes.
344
345       pv -t  Show only the elapsed time - useful  as  a  simple  timer,  e.g.
346              sleep 10m | pv -t.
347
348       pv -pterb
349              The  default  behaviour:  progress  bar, elapsed time, estimated
350              completion time, current rate, and byte counter.
351
352
353

EXIT STATUS

355       An exit status of 1 indicates a problem with the -R or -P options.
356
357       Any other exit status is a bitmask of the following:
358
359
360       2      One or more files could not be accessed, stat(2)ed, or opened.
361
362       4      An input file was the same as the output file.
363
364       8      Internal error with closing a file or moving to the next file.
365
366       16     There was an error while transferring  data  from  one  or  more
367              input files.
368
369       32     A signal was caught that caused an early exit.
370
371       64     Memory allocation failed.
372
373              A zero exit status indicates no problems.
374
375
376

AUTHOR

378       Written by Andrew Wood, with patches submitted by various other people.
379       Please see the package README for a complete list of contributors.
380
381
382

KNOWN PROBLEMS

384       The following problems are known to exist in pv:
385
386       *      The -c option does not work properly on Cygwin without cygserver
387              running, if started near the bottom of the screen (IPC is needed
388              to handle the terminal scrolling).  To fix this, start cygserver
389              before using pv -c.
390
391       *      The  -R option is not available on Cygwin without cygserver run‐
392              ning (SYSV IPC is needed). To fix this, start  cygserver  before
393              running  the  instance of pv you want, at runtime, to change the
394              parameters of.
395
396       If you find any other problems, please report them.
397
398
399

REPORTING BUGS

401       Report bugs in pv to pv@ivarch.com or use the contact form linked  from
402       the pv home page: <http://www.ivarch.com/programs/pv.shtml>
403
404
405

SEE ALSO

407       cat(1), dialog(1), splice(2)
408
409
410

LICENSE

412       This is free software, distributed under the ARTISTIC 2.0 license.
413
414
415
416Linux                              June 2017                             PV(1)
Impressum