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 ap‐
20       propriate 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/your/disk/device > disk-image.img
48
49       Writing an image back to a disk:
50
51              pv disk-image.img > /dev/your/disk/device
52
53       Zeroing a disk:
54
55              pv < /dev/zero > /dev/your/disk/device
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.  Implies -C.
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.  Implies -C.
125
126       -F, --format FORMAT
127              Ignore the options -p, -t, -e, -r, -a, -b, -T, and -A,  and  in‐
128              stead  use the format string FORMAT to determine the output for‐
129              mat.  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 fi‐
142              nally, if --timer is also in use, then each output line is  pre‐
143              fixed  with the elapsed time so far, as a decimal number of sec‐
144              onds.
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 be‐
157              fore 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 ev‐
188              ery 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.  This can be use‐
228              ful on platforms like MacOS which perform  better  in  pipelines
229              with specific buffer sizes such as 1024.  Implies -C.
230
231       -C, --no-splice
232              Never use splice(2), even if it would normally be possible.  The
233              splice(2) system call is a more efficient  way  of  transferring
234              data  from  or  to a pipe than regular read(2) and write(2), but
235              means that the transfer buffer may not be used.   This  prevents
236              -A and -T from working, and makes -B redundant, so using -A, -T,
237              or -B automatically switches on -C.  Switching on -C results  in
238              a small loss of transfer efficiency.  (This option has no effect
239              on systems where splice(2) is unavailable).
240
241       -E, --skip-errors
242              Ignore read errors by attempting to skip past the offending sec‐
243              tions.   The  corresponding  parts  of  the  output will be null
244              bytes.  At first only a few bytes will be skipped, but if  there
245              are  many  errors in a row then the skips will move up to chunks
246              of 512.  This is intended to be similar to dd  conv=sync,noerror
247              but has not been as thoroughly tested.
248
249              Specify  -E twice to only report a read error once per file, in‐
250              stead of reporting each byte range skipped.
251
252       -S, --stop-at-size
253              If a size was specified with -s,  stop  transferring  data  once
254              that  many bytes have been written, instead of continuing to the
255              end of input.
256
257       -d PID[:FD], --watchfd PID[:FD]
258              Instead of  transferring  data,  watch  file  descriptor  FD  of
259              process  PID,  and  show its progress.  The pv process will exit
260              when FD either changes to a different file,  changes  read/write
261              mode,  or  is closed; other data transfer modifiers - and remote
262              control - may not be used with this option.
263
264              If only a PID is specified, then that process will  be  watched,
265              and  all  regular files and block devices it opens will be shown
266              with a progress bar.  The pv process will exit when process  PID
267              exits.
268
269       -R PID, --remote PID
270              If PID is an instance of pv that is already running, -R PID will
271              cause that instance to act as though it had been given this  in‐
272              stance's  command  line  instead.  For example, if pv -L 123K is
273              running with process ID 9876, then running pv -R  9876  -L  321K
274              will  cause  it to start using a rate limit of 321KiB instead of
275              123KiB.  Note that some options cannot be changed while running,
276              such as -c, -l, -f, -D, -E, and -S.
277
278

GENERAL OPTIONS

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

FORMATTING

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

COMMON SWITCHES

336       Some suggested common switch combinations:
337
338
339       pv -ptebar
340              Show a progress bar, elapsed time,  estimated  completion  time,
341              byte counter, average rate, and current rate.
342
343       pv -betlap
344              Show  a  progress  bar, elapsed time, estimated completion time,
345              line counter, and average rate, counting lines instead of bytes.
346
347       pv -t  Show only the elapsed time - useful  as  a  simple  timer,  e.g.
348              sleep 10m | pv -t.
349
350       pv -pterb
351              The  default  behaviour:  progress  bar, elapsed time, estimated
352              completion time, current rate, and byte counter.
353
354
355       On MacOS, it may be useful to specify -B 1024 in a  pipeline,  as  this
356       may improve performance.
357
358
359

EXIT STATUS

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

AUTHOR

385       Written by Andrew Wood, with patches submitted by various other people.
386       Please see the package README for a complete list of contributors.
387
388
389

KNOWN PROBLEMS

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

REPORTING BUGS

408       Report  bugs in pv to pv@ivarch.com or use the contact form linked from
409       the pv home page: <http://www.ivarch.com/programs/pv.shtml>
410
411
412

SEE ALSO

414       cat(1), dialog(1), splice(2)
415
416
417

LICENSE

419       This is free software, distributed under the ARTISTIC 2.0 license.
420
421
422
423Linux                           September 2021                           PV(1)
Impressum