Rename "doc" directory to "docs" to match Debian standards.
This commit is contained in:
Andrew Wood
@@ -0,0 +1,91 @@
|
||||
The following people have contributed to this project, and their assistance
|
||||
is acknowledged and greatly appreciated:
|
||||
|
||||
* Antoine Beaupré <anarcat@debian.org> - Debian package maintainer
|
||||
* Kevin Coyner <kcoyner@debian.org> - previous Debian package maintainer
|
||||
* Cédric Delfosse <cedric@debian.org> - previous Debian package maintainer
|
||||
* Jakub Hrozek <jhrozek@redhat.com> - Fedora package maintainer
|
||||
* Eduardo Aguiar <eduardo.oliveira@sondabrasil.com.br> - provided Portuguese (Brazilian) translation
|
||||
* Stéphane Lacasse <stephane@gorfou.ca> - provided French translation
|
||||
* Marcos Kreinacke <public@kreinacke.com> - provided German translation
|
||||
* Bartosz Feński <fenio@o2.pl> <http://skawina.eu.org/> - provided Polish translation along with Krystian Zubel
|
||||
* Joshua Jensen - reported RPM installation bug
|
||||
* Boris Folgmann <http://www.folgmann.com/en/> - reported cursor handling bug
|
||||
* Mathias Gumz - reported NLS bug
|
||||
* Daniel Roethlisberger - submitted patch to use lockfiles for "`-c`" if terminal locking fails
|
||||
* Adam Buchbinder - lots of help with a Cygwin port of "`-c`"
|
||||
* Mark Tomich <http://metuchen.dyndns.org> - suggested "`-B`" option
|
||||
* Gert Menke - reported bug when piping to `dd` with a large input buffer size
|
||||
* Ville Herva <Ville.Herva@iki.fi> - informative bug report about rate limiting performance
|
||||
* Elias Pipping - patch to compile properly on Darwin 9; potential NULL deref report
|
||||
* Patrick Collison - similar patch for OS X
|
||||
* Boris Lohner - reported problem that "`-L`" does not complain if given non-numeric value
|
||||
* Sebastian Kayser - supplied testing for *SIGPIPE*, demonstrated internationalisation problem
|
||||
* Laszlo Ersek <http://phptest11.atw.hu/> - reported shared memory leak on *SIGINT* with "`-c`"
|
||||
* Phil Rutschman <http://bandgap.rsnsoft.com/> - provided a patch for fully restoring terminal state on exit
|
||||
* Henry Precheur <http://henry.precheur.org/> - reporting and suggestions for "`--rate-limit`" bug when rate is under 10
|
||||
* E. Rosten <http://mi.eng.cam.ac.uk/~er258/> - supplied patch for block buffering in line mode
|
||||
* Kjetil Torgrim Homme - reported compilation error with default *CFLAGS* on non-GCC compilers
|
||||
* Alexandre de Verteuil - reported bug in OS X build and supplied test environment to fix in
|
||||
* Martin Baum - supplied patch to return nonzero exit status if terminated by signal
|
||||
* Sam Nelson <http://www.siliconfuture.net/> - supplied patch to fix trailing slash on *DESTDIR*
|
||||
* Daniel Pape - reported Cygwin installation problem due to *DESTDIR*
|
||||
* Philipp Beckers - ported to the Syabas PopcornHour A-100 series
|
||||
* Henry Gebhard <hsggebhardt@googlemail.com> - supplied patches to improve SI prefixes and add "`--average-rate`"
|
||||
* Vladimir Kokarev, Alexander Leo - reported that exit status did not reflect file errors
|
||||
* Thomas Rachel - submitted patches for IEEE1541 (MiB suffixes), 1+e03 bug
|
||||
* Guillaume Marcais - submitted speedup patch for line mode
|
||||
* Moritz Barsnick - submitted patch for compile warning in size calculation
|
||||
* Pawel Piatek - submitted RPM and patches for AIX
|
||||
* Sami Liedes - submitted patch for "`--timer`" and "`--bytes`" with "`--numeric`"
|
||||
* Steven Willis - reported problem with "`-R`" killing non-PV remote processes
|
||||
* Vladimir Pal, Vladimir Ermakov - submitted patch which led to development of "`--format`" option
|
||||
* Peter Samuelson <peter@p12n.org> - submitted patch to calculate size if stdout is a block device
|
||||
* Miguel Diaz - much Cygwin help (and packaging), found narrow-terminal bug
|
||||
* Jim Salter <http://ubuntuwiki.net> - commissioned work on the "`--skip-errors`" option
|
||||
* Wouter Pronk - reported build problem on SCO
|
||||
* Bryan Dongray <http://www.dongrays.com> - provided patches for test scripts failing on older Red Hats
|
||||
* Zev Weiss <www.bewilderbeest.net> - provided patch to fix `splice()` not using stdin
|
||||
* Zing Shishak - provided patch for "`--null`" / "`-0`" (count null terminated lines)
|
||||
* Jacek Wielemborek <http://deetah.jogger.pl/kategorie/english> - implemented fdwatch in Python, suggested PV port; reported bug with "`-l`" and ETA / size; many other contributions
|
||||
* Kim Krecht - suggested buffer fill status and last bytes output display options
|
||||
* Cristian Ciupitu <http://ciupicri.github.io>, Josh Stone - pointed out file descriptor leak with helpful suggestions (Josh Stone initially noticed the missing close)
|
||||
* Jan Seda - found issue with `splice()` and *SPLICE_F_NONBLOCK* causing slowdown
|
||||
* André Stapf - pointed out formatting problem e.g. 13GB -> 13.1GB which should be shown 13.0GB -> 13.1GB; highlighted on-startup row swapping in "`-c`", and suggested "`--discard`"
|
||||
* Damon Harper <http://www.usrbin.ca/> - suggested "`-D`" / "`--delay-start`" option
|
||||
* Ganaël Laplanche <http://www.martymac.org> - provided patch for `lstat64()` on systems that do not support it
|
||||
* Peter Korsgaard <http://www.buildroot.net/> - provided similar patch for `lstat64()`, specifically for uClibc support; provided AIX cross-compilation patch to fix bug in "`-lc128`" check
|
||||
* Ralf Ramsauer <https://blog.ramses-pyramidenbau.de/> - reported bug which dropped transfer rate on terminal resize
|
||||
* Michiel Van Herwegen - reported and discussed bug with "`-l`" and ETA / size
|
||||
* Erkki Seppälä <http://www.inside.org/~flux/> - provided patch implementing "`-I`"
|
||||
* Eric A. Borisch - provided details of compatibility fix for "`%Lu`" in watchpid code
|
||||
* Jan Venekamp - reported MacOS buffer size interactions with pipes
|
||||
* Matt <https://github.com/lemonsqueeze/pv> - provided "rate-window" patches for rate calculation
|
||||
* [Filippo Valsorda](https://github.com/FiloSottile) - provided patch for stat64 issue on Apple Silicon
|
||||
* Matt Koscica, William Dillon - also reported stat64 issue on Apple Silicon
|
||||
* [Demitri Muna](https://github.com/demitri) - assisted with stat64 patch on Apple Silicon
|
||||
* Norman Rasmussen - suggested "`-c`" with "`-d PID:FD`", reject "`-N`" with "`-d PID`"
|
||||
* Andriy Gapon, Jonathan Elchison - reported bug where "`pv /dev/zero >/dev/null &`" stops immediately
|
||||
* Marcelo Chiesa - reported unused-result warnings when compiling PV 1.6.6
|
||||
* Jered Floyd - provided patches to improve "`--rate-limit`"
|
||||
* Christoph Biedl - provided ETA and dynamic interval patches
|
||||
* Richard Fonfara - provided German translations for "`pv --help`"
|
||||
* Johannes Gerer <http://johannesgerer.com> - suggested that "`-B`" should enable "`-C`"
|
||||
* Sam James - provided fix for number.c build issue caused by missing stddef.h
|
||||
* Jakub Wilk <jwilk@jwilk.net> - corrected README encoding
|
||||
* Frederik Eaton - reported issue with `<()` shell constructs
|
||||
* [gray](https://github.com/gray) - reported issue with "`--force`" and terminal process groups, and proposed a patch
|
||||
* [Luc Gommans](https://github.com/lgommans) / https://lgms.nl/ - provided a "momentary ETA" patch
|
||||
* [ikasty](https://github.com/ikasty) - added relative filename display to "`--watchfd`"
|
||||
* [Michael Weiß](https://github.com/quitschbo) - corrected behaviour when not attached to a terminal
|
||||
* [christoph-zededa](https://github.com/christoph-zededa) - provided OS X support for "`--watchfd`"
|
||||
* [Dave Beckett](https://github.com/dajobe) - added "`@filename`" syntax to "`--size`", and corrected an autoconf problem with stat64 on OS X
|
||||
* [Volodymyr Bychkovyak](https://github.com/vbychkoviak) - provided fix for rate limit behaviour with bursty traffic
|
||||
* [Nick Black](https://nick-black.com) - added "`--bits`" option
|
||||
* [Andrew Schulman](https://github.com/andrew-schulman) - provided reproducible example of terminal size detection issue in 1.7.17/1.7.18
|
||||
* [fuschia74](https://github.com/fuchsia74) - provided "`--enable-static`" patch for "`configure`"
|
||||
* [Wilhelm von Thiele](https://github.com/TurtleWilly) - assisted with OS X cleanups ([#73](https://codeberg.org/a-j-wood/pv/issues/73), [#74](https://codeberg.org/a-j-wood/pv/issues/74))
|
||||
* Matějů Miroslav, Ing. - suggested fix for ETA and elapsed time faults when suspending and resuming a machine ([#13](https://codeberg.org/a-j-wood/pv/issues/13))
|
||||
* Anthony DeRobertis - suggested the "`--error-skip-block`" option ([#37](https://codeberg.org/a-j-wood/pv/issues/37))
|
||||
|
||||
---
|
||||
+171
@@ -0,0 +1,171 @@
|
||||
This package is free software, and is being distributed under the terms
|
||||
of the Artistic License 2.0.
|
||||
|
||||
----------------------------------------------------------
|
||||
|
||||
Artistic License 2.0
|
||||
|
||||
Copyright (c) 2000-2006, The Perl Foundation.
|
||||
|
||||
Everyone is permitted to copy and distribute verbatim copies of this
|
||||
license document, but changing it is not allowed. Preamble
|
||||
|
||||
This license establishes the terms under which a given free software
|
||||
Package may be copied, modified, distributed, and/or redistributed. The
|
||||
intent is that the Copyright Holder maintains some artistic control
|
||||
over the development of that Package while still keeping the Package
|
||||
available as open source and free software.
|
||||
|
||||
You are always permitted to make arrangements wholly outside of this
|
||||
license directly with the Copyright Holder of a given Package. If the
|
||||
terms of this license do not permit the full use that you propose to
|
||||
make of the Package, you should contact the Copyright Holder and seek
|
||||
a different licensing arrangement. Definitions
|
||||
|
||||
"Copyright Holder" means the individual(s) or organization(s) named in
|
||||
the copyright notice for the entire Package.
|
||||
|
||||
"Contributor" means any party that has contributed code or other material
|
||||
to the Package, in accordance with the Copyright Holder's procedures.
|
||||
|
||||
"You" and "your" means any person who would like to copy, distribute,
|
||||
or modify the Package.
|
||||
|
||||
"Package" means the collection of files distributed by the Copyright
|
||||
Holder, and derivatives of that collection and/or of those files. A given
|
||||
Package may consist of either the Standard Version, or a Modified Version.
|
||||
|
||||
"Distribute" means providing a copy of the Package or making it accessible
|
||||
to anyone else, or in the case of a company or organization, to others
|
||||
outside of your company or organization.
|
||||
|
||||
"Distributor Fee" means any fee that you charge for Distributing this
|
||||
Package or providing support for this Package to another party. It does
|
||||
not mean licensing fees.
|
||||
|
||||
"Standard Version" refers to the Package if it has not been modified,
|
||||
or has been modified only in ways explicitly requested by the Copyright
|
||||
Holder.
|
||||
|
||||
"Modified Version" means the Package, if it has been changed, and such
|
||||
changes were not explicitly requested by the Copyright Holder.
|
||||
|
||||
"Original License" means this Artistic License as Distributed with the
|
||||
Standard Version of the Package, in its current version or as it may be
|
||||
modified by The Perl Foundation in the future.
|
||||
|
||||
"Source" form means the source code, documentation source, and
|
||||
configuration files for the Package.
|
||||
|
||||
"Compiled" form means the compiled bytecode, object code, binary, or any
|
||||
other form resulting from mechanical transformation or translation of
|
||||
the Source form. Permission for Use and Modification Without Distribution
|
||||
|
||||
(1) You are permitted to use the Standard Version and create and use
|
||||
Modified Versions for any purpose without restriction, provided that you
|
||||
do not Distribute the Modified Version. Permissions for Redistribution
|
||||
of the Standard Version
|
||||
|
||||
(2) You may Distribute verbatim copies of the Source form of the Standard
|
||||
Version of this Package in any medium without restriction, either gratis
|
||||
or for a Distributor Fee, provided that you duplicate all of the original
|
||||
copyright notices and associated disclaimers. At your discretion, such
|
||||
verbatim copies may or may not include a Compiled form of the Package.
|
||||
|
||||
(3) You may apply any bug fixes, portability changes, and other
|
||||
modifications made available from the Copyright Holder. The resulting
|
||||
Package will still be considered the Standard Version, and as such will
|
||||
be subject to the Original License. Distribution of Modified Versions
|
||||
of the Package as Source
|
||||
|
||||
(4) You may Distribute your Modified Version as Source (either gratis
|
||||
or for a Distributor Fee, and with or without a Compiled form of the
|
||||
Modified Version) provided that you clearly document how it differs
|
||||
from the Standard Version, including, but not limited to, documenting
|
||||
any non-standard features, executables, or modules, and provided that
|
||||
you do at least ONE of the following:
|
||||
|
||||
(a) make the Modified Version available to the Copyright Holder of the
|
||||
Standard Version, under the Original License, so that the Copyright Holder
|
||||
may include your modifications in the Standard Version.
|
||||
(b) ensure that installation of your Modified Version does not prevent the
|
||||
user installing or running the Standard Version. In addition, the Modified
|
||||
Version must bear a name that is different from the name of the Standard
|
||||
Version.
|
||||
(c) allow anyone who receives a copy of the Modified Version to make
|
||||
the Source form of the Modified Version available to others under
|
||||
(i) the Original License or
|
||||
(ii) a license that permits the licensee to freely copy, modify and
|
||||
redistribute the Modified Version using the same licensing terms that apply
|
||||
to the copy that the licensee received, and requires that the Source form of
|
||||
the Modified Version, and of any works derived from it, be made freely
|
||||
available in that license fees are prohibited but Distributor Fees are
|
||||
allowed. Distribution of Compiled Forms of the Standard Version or Modified
|
||||
Versions without the Source
|
||||
|
||||
(5) You may Distribute Compiled forms of the Standard Version without
|
||||
the Source, provided that you include complete instructions on how to
|
||||
get the Source of the Standard Version. Such instructions must be valid
|
||||
at the time of your distribution. If these instructions, at any time
|
||||
while you are carrying out such distribution, become invalid, you must
|
||||
provide new instructions on demand or cease further distribution. If
|
||||
you provide valid instructions or cease distribution within thirty days
|
||||
after you become aware that the instructions are invalid, then you do
|
||||
not forfeit any of your rights under this license.
|
||||
|
||||
(6) You may Distribute a Modified Version in Compiled form without the
|
||||
Source, provided that you comply with Section 4 with respect to the
|
||||
Source of the Modified Version. Aggregating or Linking the Package
|
||||
|
||||
(7) You may aggregate the Package (either the Standard Version or
|
||||
Modified Version) with other packages and Distribute the resulting
|
||||
aggregation provided that you do not charge a licensing fee for the
|
||||
Package. Distributor Fees are permitted, and licensing fees for other
|
||||
components in the aggregation are permitted. The terms of this license
|
||||
apply to the use and Distribution of the Standard or Modified Versions
|
||||
as included in the aggregation.
|
||||
|
||||
(8) You are permitted to link Modified and Standard Versions with other
|
||||
works, to embed the Package in a larger work of your own, or to build
|
||||
stand-alone binary or bytecode versions of applications that include the
|
||||
Package, and Distribute the result without restriction, provided the
|
||||
result does not expose a direct interface to the Package. Items That
|
||||
are Not Considered Part of a Modified Version
|
||||
|
||||
(9) Works (including, but not limited to, modules and scripts) that
|
||||
merely extend or make use of the Package, do not, by themselves, cause
|
||||
the Package to be a Modified Version. In addition, such works are not
|
||||
considered parts of the Package itself, and are not subject to the terms
|
||||
of this license. General Provisions
|
||||
|
||||
(10) Any use, modification, and distribution of the Standard or Modified
|
||||
Versions is governed by this Artistic License. By using, modifying or
|
||||
distributing the Package, you accept this license. Do not use, modify,
|
||||
or distribute the Package, if you do not accept this license.
|
||||
|
||||
(11) If your Modified Version has been derived from a Modified Version
|
||||
made by someone other than you, you are nevertheless required to ensure
|
||||
that your Modified Version complies with the requirements of this license.
|
||||
|
||||
(12) This license does not grant you the right to use any trademark,
|
||||
service mark, tradename, or logo of the Copyright Holder.
|
||||
|
||||
(13) This license includes the non-exclusive, worldwide, free-of-charge
|
||||
patent license to make, have made, use, offer to sell, sell, import
|
||||
and otherwise transfer the Package with respect to any patent claims
|
||||
licensable by the Copyright Holder that are necessarily infringed by the
|
||||
Package. If you institute patent litigation (including a cross-claim or
|
||||
counterclaim) against any party alleging that the Package constitutes
|
||||
direct or contributory patent infringement, then this Artistic License
|
||||
to you shall terminate on the date that such litigation is filed.
|
||||
|
||||
(14) Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT
|
||||
HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||
WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
|
||||
PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT
|
||||
PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER
|
||||
OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
|
||||
CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
|
||||
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
----------------------------------------------------------
|
||||
@@ -0,0 +1,127 @@
|
||||
# Notes for developers and translators
|
||||
|
||||
The following "`configure`" options will be of interest to developers and
|
||||
translators:
|
||||
|
||||
* `--enable-debugging` - build in debugging support
|
||||
* `--enable-profiling` - build in support for profiling
|
||||
|
||||
These "`make`" targets are available:
|
||||
|
||||
* `make analyse` - run _splint_ and _flawfinder_ on all C source files
|
||||
|
||||
|
||||
## Debugging and profiling support
|
||||
|
||||
When "`./configure --enable-debugging`" is used, the "`pv`" produced by
|
||||
"`make`" will support an extra option, "`--debug FILE`", which will cause
|
||||
debugging output to be written to *FILE*. This is not recommended for
|
||||
production builds due to the extra processing it introduces, and the
|
||||
potential size of the output.
|
||||
|
||||
Within the code, "`debug()`" is used in a similar way to "`printf()`". It
|
||||
will automatically include the calling function, source file, and line
|
||||
number, so they don't need to be included in the parameters. When debugging
|
||||
support is not enabled, it evaluates to a null statement.
|
||||
|
||||
This does mean that if you call "`debug()`", make sure it has no side
|
||||
effects, as they won't be present in builds without debugging support.
|
||||
|
||||
Builds produced after "`./configure --enable-profiling`" will write profile
|
||||
data when run, to be used with _gprof_. See "`man gprof`" for details.
|
||||
Please note that the memory safety checks will fail with profiling enabled.
|
||||
|
||||
|
||||
## Source code analysis
|
||||
|
||||
Running "`make analyse`" runs _splint_ and _flawfinder_ on all C sources,
|
||||
writing the output of both programs to files named "`*.e`" for each "`*.c`".
|
||||
|
||||
There are no dependency rules set up for these "`.e`" files, so if a header
|
||||
file is altered, manually remove the relevant "`.e`" files, or update the
|
||||
timestamp of the relevant "`.c`" files, before running "`make analyse`"
|
||||
again.
|
||||
|
||||
The eventual goal is for all C source files to generate zero warnings from
|
||||
either tool.
|
||||
|
||||
|
||||
## Translation notes
|
||||
|
||||
The message catalogues used to translate program messages into other
|
||||
languages are in the "`po/`" directory, named "`xx.po`", where "`xx`"
|
||||
is the ISO 639-1 2-letter language code, such as "`fr`" for French.
|
||||
|
||||
Each of these files contains lines like this:
|
||||
|
||||
#: src/pv/cursor.c:85
|
||||
msgid "failed to get terminal name"
|
||||
msgstr "erro ao ler o nome do terminal"
|
||||
|
||||
The comment line, starting "`#`", shows the source filename and line number
|
||||
at which this message can be found. The "`msgid`" is the original message
|
||||
in the program, in English. The "`msgstr`" is the translated text.
|
||||
|
||||
It is the "`msgstr`" lines which need to be updated by translators.
|
||||
|
||||
Message catalogue files should all be encoded as UTF-8.
|
||||
|
||||
_FIXME: The test below doesn't work on Debian with only en_GB installed, and
|
||||
also it looks like the compiled-in LOCALEDIR is overriding LOCPATH._
|
||||
|
||||
After making a change to a "`.po`" file, test it by compiling it and installing
|
||||
to a temporary location, like this:
|
||||
|
||||
make install DESTDIR=/tmp/yourtest
|
||||
localedef -f UTF-8 -i de_DE /tmp/yourtest/usr/local/share/locale/de_DE.UTF-8
|
||||
LOCPATH=/tmp/yourtest/usr/local/share/locale \
|
||||
LC_ALL=de_DE.UTF-8 ./pv --help
|
||||
|
||||
Replace "`--help`" with whatever is appropriate for your test. In this
|
||||
example, the language being tested is "`de`" (German), on a system which is
|
||||
running with UTF-8 support.
|
||||
|
||||
To add a new language, create the new message catalogue file under "`po/`"
|
||||
by copying "`po/pv.pot`" to "`po/xx.po`", where "`xx`" is the language code,
|
||||
and adjusting it. The "`.pot`" file is generated automatically by "`make`".
|
||||
|
||||
Next, add the language code to "`po/LINGUAS`" - this is a list of the
|
||||
2-letter codes of the supported languages.
|
||||
|
||||
Finally, run "`./config.status`" and "`make -C po update-po`".
|
||||
|
||||
When the source code is updated, running "`make -C po update-po`" will
|
||||
update the "`pv.pot`" file so that it lists where all the messages are in
|
||||
the source. It will also use _msgmerge_ to update all of the "`.po`" files
|
||||
from the updated "`pv.pot`" file. After doing this, look for missing
|
||||
translations (empty "`msgstr`" lines) or translations marked as "fuzzy", as
|
||||
these will need to be corrected by translators.
|
||||
|
||||
|
||||
## Release checklist
|
||||
|
||||
The package maintainer should run through these steps for a new release:
|
||||
|
||||
* Check for patches and bug reports at https://tracker.debian.org/pkg/pv
|
||||
* Run "`make indent; make indent indentclean update-po check`"
|
||||
* Version bump and documentation checks:
|
||||
* Update the version in `configure.ac` and `docs/NEWS.md`
|
||||
* Check that `docs/NEWS.md` is up to date
|
||||
* Check that `docs/TODO.md` is up to date
|
||||
* Check that the manual `docs/pv.1` is up to date
|
||||
* Run "`make docs/pv.1.md`" and, if using VPATH, copy the result to the source directory
|
||||
* Ensure everything has been committed to the repository
|
||||
* Run "`autoreconf`" in the source directory
|
||||
* Consistency and build checks:
|
||||
* Wipe the build directory, and run "`configure`" there
|
||||
* Run "`make distcheck`"
|
||||
* Run "`./configure && make check`" on all test systems including Cygwin, using the `tar.gz` that was just created
|
||||
* Run "`make release MAINTAINER=<signing-user>`"
|
||||
* Update the project web site:
|
||||
* Copy the release `.tar.gz`, `.txt`, and `.asc` files to the web site
|
||||
* Use "`pandoc --from markdown --to html`" to convert the TODO, news, and manual to HTML
|
||||
* Update the TODO, news, and manual on the web site
|
||||
* Update the version numbers on the web site
|
||||
* Update the package index on the web site
|
||||
* Create a new release in the repository, and apply the associated tag
|
||||
|
||||
+183
@@ -0,0 +1,183 @@
|
||||
Basic Installation
|
||||
==================
|
||||
|
||||
These are generic installation instructions.
|
||||
|
||||
The `configure' shell script attempts to guess correct values for
|
||||
various system-dependent variables used during compilation. It uses
|
||||
those values to create a `Makefile' in each directory of the package.
|
||||
It may also create one or more `.h' files containing system-dependent
|
||||
definitions. Finally, it creates a shell script `config.status' that
|
||||
you can run in the future to recreate the current configuration, a file
|
||||
`config.cache' that saves the results of its tests to speed up
|
||||
reconfiguring, and a file `config.log' containing compiler output
|
||||
(useful mainly for debugging `configure').
|
||||
|
||||
If you need to do unusual things to compile the package, please try
|
||||
to figure out how `configure' could check whether to do them, and mail
|
||||
diffs or instructions to the address given in the `README' so they can
|
||||
be considered for the next release. If at some point `config.cache'
|
||||
contains results you don't want to keep, you may remove or edit it.
|
||||
|
||||
The file `configure.in' is used to create `configure' by a program
|
||||
called `autoconf'. You only need `configure.in' if you want to change
|
||||
it or regenerate `configure' using a newer version of `autoconf'.
|
||||
|
||||
The simplest way to compile this package is:
|
||||
|
||||
1. `cd' to the directory containing the package's source code and type
|
||||
`./configure' to configure the package for your system. If you're
|
||||
using `csh' on an old version of System V, you might need to type
|
||||
`sh ./configure' instead to prevent `csh' from trying to execute
|
||||
`configure' itself.
|
||||
|
||||
Running `configure' takes awhile. While running, it prints some
|
||||
messages telling which features it is checking for.
|
||||
|
||||
2. Type `make' to compile the package.
|
||||
|
||||
3. Optionally, type `make check' to run any self-tests that come with
|
||||
the package.
|
||||
|
||||
4. Type `make install' to install the programs and any data files and
|
||||
documentation.
|
||||
|
||||
5. You can remove the program binaries and object files from the
|
||||
source code directory by typing `make clean'. To also remove the
|
||||
files that `configure' created (so you can compile the package for
|
||||
a different kind of computer), type `make distclean'. There is
|
||||
also a `make maintainer-clean' target, but that is intended mainly
|
||||
for the package's developers. If you use it, you may have to get
|
||||
all sorts of other programs in order to regenerate files that came
|
||||
with the distribution.
|
||||
|
||||
Compilers and Options
|
||||
=====================
|
||||
|
||||
Some systems require unusual options for compilation or linking that
|
||||
the `configure' script does not know about. You can give `configure'
|
||||
initial values for variables by setting them in the environment. Using
|
||||
a Bourne-compatible shell, you can do that on the command line like
|
||||
this:
|
||||
CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
|
||||
|
||||
Or on systems that have the `env' program, you can do it like this:
|
||||
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
|
||||
|
||||
Compiling For Multiple Architectures
|
||||
====================================
|
||||
|
||||
You can compile the package for more than one kind of computer at the
|
||||
same time, by placing the object files for each architecture in their
|
||||
own directory. To do this, you must use a version of `make' that
|
||||
supports the `VPATH' variable, such as GNU `make'. `cd' to the
|
||||
directory where you want the object files and executables to go and run
|
||||
the `configure' script. `configure' automatically checks for the
|
||||
source code in the directory that `configure' is in and in `..'.
|
||||
|
||||
If you have to use a `make' that does not supports the `VPATH'
|
||||
variable, you have to compile the package for one architecture at a time
|
||||
in the source code directory. After you have installed the package for
|
||||
one architecture, use `make distclean' before reconfiguring for another
|
||||
architecture.
|
||||
|
||||
Installation Names
|
||||
==================
|
||||
|
||||
By default, `make install' will install the package's files in
|
||||
`/usr/local/bin', `/usr/local/man', etc. You can specify an
|
||||
installation prefix other than `/usr/local' by giving `configure' the
|
||||
option `--prefix=PATH'.
|
||||
|
||||
You can specify separate installation prefixes for
|
||||
architecture-specific files and architecture-independent files. If you
|
||||
give `configure' the option `--exec-prefix=PATH', the package will use
|
||||
PATH as the prefix for installing programs and libraries.
|
||||
Documentation and other data files will still use the regular prefix.
|
||||
|
||||
In addition, if you use an unusual directory layout you can give
|
||||
options like `--bindir=PATH' to specify different values for particular
|
||||
kinds of files. Run `configure --help' for a list of the directories
|
||||
you can set and what kinds of files go in them.
|
||||
|
||||
If the package supports it, you can cause programs to be installed
|
||||
with an extra prefix or suffix on their names by giving `configure' the
|
||||
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
|
||||
|
||||
Optional Features
|
||||
=================
|
||||
|
||||
Some packages pay attention to `--enable-FEATURE' options to
|
||||
`configure', where FEATURE indicates an optional part of the package.
|
||||
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
|
||||
is something like `gnu-as' or `x' (for the X Window System). The
|
||||
`README' should mention any `--enable-' and `--with-' options that the
|
||||
package recognizes.
|
||||
|
||||
For packages that use the X Window System, `configure' can usually
|
||||
find the X include and library files automatically, but if it doesn't,
|
||||
you can use the `configure' options `--x-includes=DIR' and
|
||||
`--x-libraries=DIR' to specify their locations.
|
||||
|
||||
Specifying the System Type
|
||||
==========================
|
||||
|
||||
There may be some features `configure' can not figure out
|
||||
automatically, but needs to determine by the type of host the package
|
||||
will run on. Usually `configure' can figure that out, but if it prints
|
||||
a message saying it can not guess the host type, give it the
|
||||
`--host=TYPE' option. TYPE can either be a short name for the system
|
||||
type, such as `sun4', or a canonical name with three fields:
|
||||
CPU-COMPANY-SYSTEM
|
||||
|
||||
See the file `config.sub' for the possible values of each field. If
|
||||
`config.sub' isn't included in this package, then this package doesn't
|
||||
need to know the host type.
|
||||
|
||||
If you are building compiler tools for cross-compiling, you can also
|
||||
use the `--target=TYPE' option to select the type of system they will
|
||||
produce code for and the `--build=TYPE' option to select the type of
|
||||
system on which you are compiling the package.
|
||||
|
||||
Sharing Defaults
|
||||
================
|
||||
|
||||
If you want to set default values for `configure' scripts to share,
|
||||
you can create a site shell script called `config.site' that gives
|
||||
default values for variables like `CC', `cache_file', and `prefix'.
|
||||
`configure' looks for `PREFIX/share/config.site' if it exists, then
|
||||
`PREFIX/etc/config.site' if it exists. Or, you can set the
|
||||
`CONFIG_SITE' environment variable to the location of the site script.
|
||||
A warning: not all `configure' scripts look for a site script.
|
||||
|
||||
Operation Controls
|
||||
==================
|
||||
|
||||
`configure' recognizes the following options to control how it
|
||||
operates.
|
||||
|
||||
`--cache-file=FILE'
|
||||
Use and save the results of the tests in FILE instead of
|
||||
`./config.cache'. Set FILE to `/dev/null' to disable caching, for
|
||||
debugging `configure'.
|
||||
|
||||
`--help'
|
||||
Print a summary of the options to `configure', and exit.
|
||||
|
||||
`--quiet'
|
||||
`--silent'
|
||||
`-q'
|
||||
Do not print messages saying which checks are being made. To
|
||||
suppress all normal output, redirect it to `/dev/null' (any error
|
||||
messages will still be shown).
|
||||
|
||||
`--srcdir=DIR'
|
||||
Look for the package's source code in directory DIR. Usually
|
||||
`configure' can determine that directory automatically.
|
||||
|
||||
`--version'
|
||||
Print the version of Autoconf used to generate the `configure'
|
||||
script, and exit.
|
||||
|
||||
`configure' also accepts some other, not widely useful, options.
|
||||
|
||||
+451
@@ -0,0 +1,451 @@
|
||||
0.0.20230902-UNRELEASED
|
||||
|
||||
* feature: new "`--discard`" option to discard input as if writing to */dev/null* ([#42](https://codeberg.org/a-j-wood/pv/issues/42))
|
||||
* feature: use `posix_fadvise()` like `cat`(1) does, to improve efficiency ([#39](https://codeberg.org/a-j-wood/pv/issues/39))
|
||||
* feature: new "`--enable-static`" option to "`configure`" for static builds ([#75](https://codeberg.org/a-j-wood/pv/pull/75))
|
||||
* feature: new "`--error-skip-block`" option to make "`--skip-errors`" skip whole blocks ([#37](https://codeberg.org/a-j-wood/pv/issues/37))
|
||||
* security: with "`--pidfile`", write to a temporary file and rename it into place, to improve security
|
||||
* security: keep self-contained copies of name and format string in PV internal state for memory safety
|
||||
* fix: only report errors about missing files when starting to transfer from them, not while calculating size, and behave more like `cat`(1) by skipping them and moving on
|
||||
* fix: auto-calculate total line count with "`--line-mode`" when all inputs are regular files
|
||||
* fix: use `clock_gettime()` in ETA calculation to cope with machine suspend/resume ([#13](https://codeberg.org/a-j-wood/pv/issues/13))
|
||||
* fix: if "`--width`" or "`--height`" were provided, do not change them when the window size changes ([#36](https://codeberg.org/a-j-wood/pv/issues/36))
|
||||
* fix: when a file descriptor position in "`--watchfd`" moves backwards, show the rate using the correct prefix ([#41](https://codeberg.org/a-j-wood/pv/issues/41))
|
||||
* fix: rewrite terminal state save/restore so state is not intermittently garbled on exit when using "`--cursor`" ([#20](https://codeberg.org/a-j-wood/pv/issues/20)), ([#24](https://codeberg.org/a-j-wood/pv/issues/24))
|
||||
* cleanup: switched the build system to GNU Automake
|
||||
* cleanup: added a test for terminal width detection to "`make check`"
|
||||
* cleanup: added a test to "`make check`" to ensure that "`make install`" installs everything expected
|
||||
* cleanup: replaced *AC_HEADER_TIOCGWINSZ* with *AC_CHECK_HEADERS(sys/ioctl.h)* for better MacOS compatibility ([#74](https://codeberg.org/a-j-wood/pv/issues/74))
|
||||
* cleanup: with "`--sync`", call `fsync()` instead of `fdatasync()` on incapable systems ([#73](https://codeberg.org/a-j-wood/pv/issues/73))
|
||||
* cleanup: replaced the test harness with the one native to GNU Automake
|
||||
* cleanup: the manual is now a static file instead of needing to be built with "`configure`"
|
||||
* dropped: dropped support for "`--enable-static-nls`"
|
||||
* dropped: removed the Linux Software Map file, as the LSM project appears to be long dead
|
||||
* dropped: will no longer publish to SourceForge as it has a chequered history and is unnecessary
|
||||
* dropped: removed project from GitHub and moved to Codeberg - see "[Give Up GitHub](https://giveupgithub.org/)"
|
||||
|
||||
1.7.24 - 30 July 2023
|
||||
|
||||
* fix: correct terminal size detection, broken in 1.7.17 by the configuration script rewrite ([#72](https://codeberg.org/a-j-wood/pv/issues/72))
|
||||
* security: removed *DEBUG* environment variable in debug mode, added "`--debug`" instead
|
||||
* cleanup: added "`make analyse`" to run "`splint`" and "`flawfinder`" on all source files
|
||||
* cleanup: corrected detection of boolean capability
|
||||
* cleanup: word wrapping of "`--help`" output is now multi-byte locale aware
|
||||
* cleanup: adjusted "`indent`" rules to line length of 120 and reformatted code
|
||||
|
||||
1.7.18 - 28 July 2023
|
||||
|
||||
* fix: language file installation had been broken by the configuration script rewrite
|
||||
|
||||
1.7.17 - 27 July 2023
|
||||
|
||||
* feature: new "`--sync`" option to flush cache to disk after every write (related to [#6](https://codeberg.org/a-j-wood/pv/issues/6), to improve accuracy when writing to slow disks)
|
||||
* feature: new "`--direct-io`" option to bypass cache - implements [#29 "Option to enable *O_DIRECT*"](https://codeberg.org/a-j-wood/pv/issues/29) - requested by Romain Kang, Jacek Wielemborek
|
||||
* fix: correct byte prefix size to 2 spaces in rate display, so progress display size remains constant at low transfer rates
|
||||
* cleanup: rewrote `configure.in` as per suggestions in newer "`autoconf`" manuals
|
||||
* cleanup: replaced `header.in` with one generated by "`autoheader`", moving custom logic to a separate header file "`config-aux.h`"
|
||||
* cleanup: added copyright notice to all source files as per GNU standards
|
||||
* cleanup: changed "`--version`" output to conform to GNU standards
|
||||
* cleanup: replaced backticks with `$()` in all shell scripts that did not come from elsewhere, as backticks are deprecated and harder to read
|
||||
* cleanup: improved the output formatting of "`make test`"
|
||||
* cleanup: extended the "`make test`" mechanism to allow certain tests to be skipped on platforms that cannot support them
|
||||
* cleanup: skip the "pipe" test (for *SIGPIPE*) if GNU "`head`" is not available, so that "`make test`" on stock OpenBSD 7.3 works
|
||||
* cleanup: added a lot more tests to "`make test`"
|
||||
* cleanup: replace all calls to `sprintf()` and `snprintf()` with a new wrapper function `pv_snprintf()` to improve security and compatibility
|
||||
* cleanup: replace all calls to `strcat()` with a wrapper `pv_strlcat()` to improve security and compatibility
|
||||
* cleanup: replace all `write()` calls to the terminal with a wrapper `pv_write_retry()` for consistency
|
||||
* cleanup: tidy up and fix compilation warning in "`--watchfd`" code
|
||||
* cleanup: rewrote all local shell scripts to pass analysis by [ShellCheck](https://www.shellcheck.net)
|
||||
|
||||
1.7.0 - 17 July 2023
|
||||
|
||||
* dropped: support for Red Hat Enterprise Linux and its derivatives has been dropped; removed the RPM spec file, and will no longer build binaries
|
||||
* feature: the "`--size`" option now accepts "`@filename`" to use the size of another file (pull request [#57](https://codeberg.org/a-j-wood/pv/pull/57) supplied by [Dave Beckett](https://github.com/dajobe))
|
||||
* feature: the "`--watchfd`" option is now available on OS X (pull request [#60](https://codeberg.org/a-j-wood/pv/pull/60) supplied by [christoph-zededa](https://github.com/christoph-zededa))
|
||||
* feature: new "`--bits`" option to show bit count instead of byte count (adapted from pull request [#63](https://codeberg.org/a-j-wood/pv/pull/63) supplied by [Nick Black](https://nick-black.com))
|
||||
* feature: new "`--average-rate-window`" option, to set the window over which the average rate is calculated, also used for ETA (modified from pull request [#65](https://codeberg.org/a-j-wood/pv/pull/65) supplied by [lemonsqueeze](https://github.com/lemonsqueeze))
|
||||
* feature: the "`--watchfd`" option will now show relative filenames, if they are under the current directory (pull request [#66](https://codeberg.org/a-j-wood/pv/pull/66) supplied by [ikasty](https://github.com/ikasty))
|
||||
* fix: correction to `pv_in_foreground()` to behave as its comment block says it should, when not on a terminal - corrects [#19 "No output in Arch Linux initcpio after 1.6.6"](https://codeberg.org/a-j-wood/pv/issues/19), [#31 "No output written from inside zsh <() construct"](https://codeberg.org/a-j-wood/pv/issues/31), [#55 "pv Stopped Working in the Background"](https://codeberg.org/a-j-wood/pv/issues/55) (pull request [#64](https://codeberg.org/a-j-wood/pv/pull/64) supplied by [Michael Weiß](https://github.com/quitschbo))
|
||||
* fix: workaround for OS X 11 behaviour in configure script regarding stat64 at compile time (pull request [#57](https://codeberg.org/a-j-wood/pv/pull/57) supplied by [Dave Beckett](https://github.com/dajobe))
|
||||
* fix: workaround for macOS equivalence of stat to stat64 - patches from [Filippo Valsorda](https://github.com/FiloSottile) and [Demitri Muna](https://github.com/demitri), correcting [#33 "Fix compilation problems due to `stat64()` on Apple Silicon"](https://codeberg.org/a-j-wood/pv/issues/33)
|
||||
* fix: add burst rate limit to transfer, so rate limits are not broken by bursty traffic (pull request [#62](https://codeberg.org/a-j-wood/pv/pull/62) supplied by [Volodymyr Bychkovyak](https://github.com/vbychkoviak))
|
||||
* fix: corrected "`--force`" option so it will still output progress when not in the same process group as the owner of the terminal - corrects [#23 "No output with "`-f`" when run in background after 1.6.6"](https://codeberg.org/a-j-wood/pv/issues/23) and helps to correct [#31 "No output written from inside zsh <() construct"](https://codeberg.org/a-j-wood/pv/issues/31)
|
||||
* fix: corrected elapsed time display to show as D:HH:MM:SS after 1 day, like the ETA does - corrects [#16 "Show days in same format in ETA as in elapsed time"](https://codeberg.org/a-j-wood/pv/issues/16)
|
||||
* fix: corrected bug where percentages went down after 100% when in "`--numeric`" mode with a "`--size`" that was too small - corrects [#26 "Correct "`-n`" behaviour when going past 100% of "`-s`" size"](https://codeberg.org/a-j-wood/pv/issues/26)
|
||||
* i18n: recoded Polish translation file to UTF-8
|
||||
* i18n: removed inaccurate fuzzy translation matches
|
||||
* docs: moved all open issues into GitHub and updated the TODO list
|
||||
* docs: renamed README to README.md and altered it to Markdown format
|
||||
* docs: moved contributors from the README to docs/ACKNOWLEDGEMENTS.md
|
||||
* docs: moved TODO to TODO.md and altered it to Markdown format
|
||||
* docs: moved NEWS to NEWS.md, converted it to UTF-8, and altered it to Markdown format
|
||||
|
||||
1.6.20 - 12 September 2021
|
||||
|
||||
* fix: add missing `stddef.h` include to `number.c` (Sam James)
|
||||
|
||||
1.6.19 - 5 September 2021
|
||||
|
||||
* fix: starting pv in the background no longer immediately stops unless the transfer is to/from the terminal (Andriy Gapon, Jonathan Elchison)
|
||||
* fix: using "`-B`", "`-A`", or "`-T`" now switches on "`-C`" implicitly (Johannes Gerer, André Stapf)
|
||||
* fix: AIX build fixes (Peter Korsgaard)
|
||||
* i18n: updated German "`--help`" translations (Richard Fonfara)
|
||||
* i18n: switched to UTF-8 encoding, added missing translations (de,fr,pt)
|
||||
* docs: new "common switches" manual section (Jacek Wielemborek)
|
||||
* docs: use placeholder instead of `/dev/sda` in the manual (Pranav Peshwe)
|
||||
* docs: mention MacOS pipes and "`-B 1024`" in the manual (Jan Venekamp)
|
||||
* docs: correct shell in `autoconf/scripts/index.sh` (Juan Picca)
|
||||
* cleanup: various compiler warnings cleaned up
|
||||
|
||||
Full changelog is below:
|
||||
* (r181) added common switches section to manual (Jacek Wielemborek)
|
||||
* (r184) use placeholder instead of /dev/sda in the manual (Pranav Peshwe)
|
||||
* (r185) replace ash with sh in autoconf/scripts/index.sh (Juan Picca)
|
||||
* (r185) added note to manual about "`-B 1024`" in MacOS pipes (Jan Venekamp)
|
||||
* (r185) fix AIX config check when the CWD contains "yes" (Peter Korsgaard)
|
||||
* (r189) (#1556) updated German "`--help`" translations (Richard Fonfara)
|
||||
* (r189) updated missing German translations and changed to UTF-8 encoding
|
||||
* (r191) updated missing French translations and changed to UTF-8 encoding
|
||||
* (r193) updated missing Portuguese translations, changed to UTF-8 encoding
|
||||
* (r196) (#1563) using "`-B`", "`-A`", or "`-T`" now switches on "`-C`" implicitly (Johannes Gerer, André Stapf)
|
||||
* (r199) fixed numerous compiler warnings in newer GCC versions
|
||||
* (r200,205) fixed bug where "`pv /dev/zero >/dev/null &`" stopped immediately (Jonathan Elchison, Andriy Gapon)
|
||||
* (r203,205) marked unused arguments with GCC unused attribute, started using boolean data type for flags, corrected more compiler warnings
|
||||
|
||||
1.6.6 - 30 June 2017
|
||||
|
||||
* (r161) use `%llu` instead of `%Lu` for better compatibility (Eric A. Borisch)
|
||||
* (r162) (#1532) fix target buffer size ("`-B`") being ignored (AndCycle, Ilya Basin, Antoine Beaupré)
|
||||
* (r164) cap read/write sizes, and check elapsed time during read/write cycles, to avoid display hangs with large buffers or slow media; also remove `select()` call from repeated_write function as it slows the transfer down and the wrapping `alarm()` means it is unnecessary
|
||||
* (r169) (#1477) use alternate form for transfer counter, such that 13GB is shown as 13.0GB so it's the same width as 13.1GB (André Stapf)
|
||||
* (r171) cleanup: units corrections in man page, of the form kb -> KiB
|
||||
* (r175) report error in "`-d`" if process fd directory is unreadable, or if process disappears before we start the main loop (Jacek Wielemborek)
|
||||
|
||||
1.6.0 - 15 March 2015
|
||||
|
||||
* fix lstat64 support when unavailable - separate patches supplied by Ganael Laplanche and Peter Korsgaard
|
||||
* (#1506) new option "`-D`" / "`--delay-start`" to only show bar after N seconds (Damon Harper)
|
||||
* new option "`--fineta`" / "`-I`" to show ETA as time of day rather than time remaining - patch supplied by Erkki Seppälä (r147)
|
||||
* (#1509) change ETA ("`--eta`" / "`-e`") so that days are given if the hours remaining are 24 or more (Jacek Wielemborek)
|
||||
* (#1499) repeat read and write attempts on partial buffer fill/empty to work around post-signal transfer rate drop reported by Ralf Ramsauer
|
||||
* (#1507) do not try to calculate total size in line mode, due to bug reported by Jacek Wielemborek and Michiel Van Herwegen
|
||||
* cleanup: removed defunct RATS comments and unnecessary copyright notices
|
||||
* clean up displayed lines when using "`--watchfd PID`", when PID exits
|
||||
* output errors on a new line to avoid overwriting transfer bar
|
||||
|
||||
1.5.7 - 26 August 2014
|
||||
|
||||
* show KiB instead of incorrect kiB (Debian bug #706175)
|
||||
* (#1284) do not gzip man page, for non-Linux OSes (Bob Friesenhahn)
|
||||
* work around "awk" bug in `tests/016-numeric-timer` in decimal "," locales
|
||||
* fix "`make rpm`" and "`make srpm`", extend "`make release`" to sign releases
|
||||
|
||||
1.5.3 - 4 May 2014
|
||||
|
||||
* remove *SPLICE_F_NONBLOCK* to fix problem with slow `splice()` (Jan Seda)
|
||||
|
||||
1.5.2 - 10 February 2014
|
||||
|
||||
* allow "`--watchfd`" to look at block devices
|
||||
* let "`--watchfd PID:FD`" work with "`--size N`"
|
||||
* moved contributors out of the manual as the list was too long (NB everyone is still listed in the README and always will be)
|
||||
|
||||
1.5.1 - 23 January 2014
|
||||
|
||||
* new option "`--watchfd`" - suggested by Jacek Wielemborek and "fdwatch"
|
||||
* use non-block flag with `splice()`
|
||||
* new display option "`--buffer-percent`", suggested by Kim Krecht
|
||||
* new display option "`--last-written`", suggested by Kim Krecht
|
||||
* new transfer option "`--no-splice`"
|
||||
* fix for minor bug which dropped display elements after one empty one
|
||||
* fix for single fd leak on exit (Cristian Ciupitu)
|
||||
|
||||
1.4.12 - 5 August 2013
|
||||
|
||||
* new option "`--null`" - patch supplied by Zing Shishak
|
||||
* AIX build fix (add "`-lc128`") - with help from Pawel Piatek
|
||||
* AIX "`-c`" fixes - with help from Pawel Piatek
|
||||
* SCO build fix (`po2table.sh`) - reported by Wouter Pronk
|
||||
* test scripts fix for older distributions - patch from Bryan Dongray
|
||||
* fix for `splice()` not using stdin - patch from Zev Weiss
|
||||
|
||||
1.4.6 - 22 January 2013
|
||||
|
||||
* added patch from Pawel Piatek to omit *O_NOFOLLOW* in AIX
|
||||
|
||||
1.4.5 - 10 January 2013
|
||||
|
||||
* updated manual page to show known problem with "`-R`" on Cygwin
|
||||
|
||||
1.4.4 - 11 December 2012
|
||||
|
||||
* added debugging, see "`pv -h`" when `configure` is run with "`--enable-debugging`"
|
||||
* rewrote cursor positioning code used when IPC is unavailable (Cygwin)
|
||||
* fixed cursor positioning cursor read answerback problem (Cygwin/Solaris)
|
||||
* fixed bug causing crash when progress displayed with too-small terminal
|
||||
|
||||
1.4.0 - 6 December 2012
|
||||
|
||||
* new option "`--skip-errors`" commissioned by Jim Salter
|
||||
* if stdout is a block device, and we don't know the total size, use the size of that block device as the total (Peter Samuelson)
|
||||
* new option "`--stop-at-size`" to stop after "`--size`" bytes
|
||||
* report correct filename on read errors
|
||||
* fix use-after-free bug in remote PID cleanup code
|
||||
* refactored large chunks of code to make it more readable and to replace most static variables with a state structure
|
||||
|
||||
1.3.9 - 5 November 2012
|
||||
|
||||
* allow "`--format`" parameters to be sent with "`--remote`"
|
||||
* configure option "`--disable-ipc`"
|
||||
* added tests for "`--numeric`" with "`--timer`" and "`--bytes`"
|
||||
* added tests for "`--remote`"
|
||||
|
||||
1.3.8 - 29 October 2012
|
||||
|
||||
* new "`--pidfile`" option to save process ID to a file
|
||||
* integrated patch for "`--numeric`" with "`--timer`" and "`--bytes`" (Sami Liedes)
|
||||
* removed signalling from "`--remote`" to prevent accidental process kills
|
||||
* new "`--format`" option (originally Vladimir Pal / Vladimir Ermakov)
|
||||
|
||||
1.3.4 - 27 June 2012
|
||||
|
||||
* new "`--disable-splice`" configure script option
|
||||
* fixed line mode size count with multiple files (Moritz Barsnick)
|
||||
* fixes for AIX core dumps (Pawel Piatek)
|
||||
|
||||
1.3.1 - 9 June 2012
|
||||
|
||||
* do not use `splice()` if the write buffer is not empty (Thomas Rachel)
|
||||
* added test 15 (pipe transfers), and new test script
|
||||
|
||||
1.3.0 - 5 June 2012
|
||||
|
||||
* added Tiger build patch from Olle Jonsson
|
||||
* fix 1024-boundary display garble (Debian bug #586763)
|
||||
* use `splice`(2) where available (Debian bug #601683)
|
||||
* added known bugs section of the manual page
|
||||
* fixed average rate test, 12 (Andrew Macheret)
|
||||
* use IEEE1541 units (Thomas Rachel)
|
||||
* bug with rate limit under 10 fixed (Henry Precheur)
|
||||
* speed up PV line mode (patch: Guillaume Marcais)
|
||||
* remove `LD=ld` from `vars.mk` to fix cross-compilation (paintitgray/PV#1291)
|
||||
|
||||
1.2.0 - 14 December 2010
|
||||
|
||||
* integrated improved SI prefixes and "`--average-rate`" (Henry Gebhardt)
|
||||
* return nonzero if exiting due to *SIGTERM* (Martin Baum)
|
||||
* patch from Phil Rutschman to restore terminal properly on exit
|
||||
* fix i18n especially for "`--help`" (Sebastian Kayser)
|
||||
* refactored `pv_display`
|
||||
* we now have a coherent, documented, exit status
|
||||
* modified pipe test and new cksum test from Sebastian Kayser
|
||||
* default *CFLAGS* to just "`-O`" for non-GCC (Kjetil Torgrim Homme)
|
||||
* LFS compile fix for OS X 10.4 (Alexandre de Verteuil)
|
||||
* remove *DESTDIR* `/` suffix (Sam Nelson, Daniel Pape)
|
||||
* fixed potential NULL deref in transfer (Elias Pipping / LLVM/Clang)
|
||||
|
||||
1.1.4 - 6 March 2008
|
||||
|
||||
* patch from Elias Pipping correcting compilation failure on Darwin 9
|
||||
* patch from Patrick Collison correcting similar problems on OS X
|
||||
* trap *SIGINT* / *SIGHUP* / *SIGTERM* so we clean up IPCs on exit (Laszlo Ersek)
|
||||
* abort if numeric option, eg "`-L`", has non-numeric value (Boris Lohner)
|
||||
|
||||
1.1.0 - 30 August 2007
|
||||
|
||||
* new option "`--remote`" ("`-R`") to control an already-running process
|
||||
* new option "`--line-mode`" ("`-l`") to count lines instead of bytes
|
||||
* fix for "`-L`" to be less resource intensive
|
||||
* fix for input/output equivalence check on Mac OS X
|
||||
* fix for size calculation in pipelines on Mac OS X
|
||||
* fixed "`make uninstall`"
|
||||
* removed "`/debian`" directory at request of new Debian maintainer
|
||||
|
||||
1.0.1 - 4 August 2007
|
||||
|
||||
* licensing change from Artistic to Artistic 2.0
|
||||
* removed the "`-l`" / "`--license`" option
|
||||
|
||||
1.0.0 - 2 August 2007
|
||||
|
||||
* act more like "`cat`" - just skip unreadable files, don't abort
|
||||
* removed text version of manual page, and obsolete Info file generation
|
||||
* code cleanup and separation of PV internals from CLI front-end
|
||||
|
||||
0.9.9 - 5 February 2007
|
||||
|
||||
* new option "`--buffer-size`" ("`-B`") suggested by Mark Tomich
|
||||
* build fix: HP/UX largefile compile fix from Timo Savinen
|
||||
* maintain better buffer filling during transfers
|
||||
* workaround: "`pv /dev/zero | dd bs=1M count=1k`" bug (reported by Gert Menke)
|
||||
* dropped support for the Texinfo manual
|
||||
|
||||
0.9.6 - 27 February 2006
|
||||
|
||||
* bugfix: `key_t` incompatibility with Cygwin
|
||||
* bugfix: interval ("`-i`") parameter parses numbers after decimal point
|
||||
* build fix: use static NLS if `msgfmt` is unavailable
|
||||
* on the final update, blank out the now-zero ETA
|
||||
|
||||
0.9.2 - 1 September 2005
|
||||
|
||||
* Daniel Roethlisberger patch: use lockfiles if terminal locking fails
|
||||
|
||||
0.9.1 - 16 June 2005
|
||||
|
||||
* minor RPM spec file fix for Fedora Core 4
|
||||
|
||||
0.9.0 - 15 November 2004
|
||||
|
||||
* minor NLS bugfix
|
||||
|
||||
0.8.9 - 6 November 2004
|
||||
|
||||
* decimal values now accepted for rate and size, eg "`-L 1.23M`"
|
||||
* code cleanup
|
||||
* developers: "`make help`" now lists Makefile targets
|
||||
|
||||
0.8.6 - 29 June 2004
|
||||
|
||||
* use `uu_lock()` for terminal locking on FreeBSD
|
||||
|
||||
0.8.5 - 2 May 2004
|
||||
|
||||
* cursor positioning ("`-c`") reliability improved on systems with IPC
|
||||
* minor fix: made test 005 more reliable
|
||||
* new option "`--height`" ("`-H`")
|
||||
|
||||
0.8.2 - 24 April 2004
|
||||
|
||||
* allow k,m,g,t suffixes on numbers
|
||||
* added "`srpm`" and "`release`" Makefile targets
|
||||
|
||||
0.8.1 - 19 April 2004
|
||||
|
||||
* bugfix in cursor positioning ("`-c`")
|
||||
|
||||
0.8.0 - 12 February 2004
|
||||
|
||||
* replaced GNU getopt with my library code
|
||||
* replaced GNU gettext with my very minimal replacement
|
||||
* use *DESTDIR* instead of *RPM_BUILD_ROOT* for optional installation prefix
|
||||
* looked for flaws using RATS, cleaned up code
|
||||
|
||||
0.7.0 - 8 February 2004
|
||||
|
||||
* display buffer management fixes (thanks Cédric Delfosse)
|
||||
* replaced "`--enable-debug`" with "`--enable-debugging`" and "`--enable-profiling`"
|
||||
|
||||
0.6.4 - 14 January 2004
|
||||
|
||||
* fixed minor bug in RPM installation
|
||||
* bugfix in "`make index`" (only of interest to developers)
|
||||
|
||||
0.6.3 - 22 December 2003
|
||||
|
||||
* fixed transient bug that reported "resource unavailable" occasionally
|
||||
|
||||
0.6.2 - 6 August 2003
|
||||
|
||||
* block devices now have their size read correctly, so "`pv /dev/hda1`" works
|
||||
* minor code cleanups (mainly removal of CVS "Id" tags)
|
||||
|
||||
0.6.0 - 3 August 2003
|
||||
|
||||
* doing *^Z* then "`bg`" then "`fg`" now continues displaying
|
||||
|
||||
0.5.9 - 23 July 2003
|
||||
|
||||
* fix for test 007 when not in C locale
|
||||
* fix for build process to use *CPPFLAGS*
|
||||
* fix for build process to use correct i18n libraries
|
||||
* fix for build process - more portable sed in dependency generator
|
||||
* fix for install process - remember to `mkinstalldirs` before installing
|
||||
* fixes for building on Mac OS X
|
||||
|
||||
0.5.3 - 4 May 2003
|
||||
|
||||
* added Polish translation thanks to Bartosz Feński <fenio@o2.pl> <http://skawina.eu.org/> and Krystian Zubel
|
||||
* moved `doc/debian` to `./debian` at insistence of common sense
|
||||
* minor Solaris 8 compatibility fixes
|
||||
* seems to compile and test OK on Mac OS X
|
||||
|
||||
0.5.0 - 15 April 2003
|
||||
|
||||
* added French translation thanks to Stéphane Lacasse <stephane@gorfou.ca>
|
||||
* added German translation thanks to Marcos Kreinacke <public@kreinacke.com>
|
||||
* switched LGPL reference from "Library" to "Lesser"
|
||||
|
||||
0.4.9 - 18 February 2003
|
||||
|
||||
* support for >2GB files added where available (Debian bug #180986)
|
||||
* added `doc/debian` dir (from Cédric Delfosse)
|
||||
* added "`make rpm`" and "`make deb`" targets to build RPM and Debian packages
|
||||
* added a "`make pv-static`" rule to build a statically linked version
|
||||
|
||||
0.4.5 - 13 December 2002
|
||||
|
||||
* added Portuguese (Brazilian) translation thanks to Eduardo Aguiar
|
||||
|
||||
0.4.4 - 7 December 2002
|
||||
|
||||
* pause/resume support - don't count time while stopped
|
||||
* stop output when resumed in the background
|
||||
* terminal size change support
|
||||
* bugfix: "`<=>`" indicator no longer sticks at right hand edge
|
||||
|
||||
0.4.0 - 27 November 2002
|
||||
|
||||
* allow decimal interval values, eg 0.1, 0.5, etc
|
||||
* some simple tests added ("`make check`")
|
||||
* smoother throughput limiting ("`--rate-limit`"), now done in 0.1sec chunks
|
||||
* bounds-check interval values ("`-i`") - max update interval now 10 minutes
|
||||
* more reliable non-blocking output to keep display updated
|
||||
* no longer rely on `atoll()`
|
||||
* don't output final blank line if "`--numeric`"
|
||||
* use `fcntl()` instead of `flock()` for Solaris compatibility
|
||||
|
||||
0.3.0 - 25 November 2002
|
||||
|
||||
* handle broken output pipe gracefully
|
||||
* continue updating display even when output pipe is blocking
|
||||
|
||||
0.2.6 - 21 October 2002
|
||||
|
||||
* we now ignore *EINTR* on `select()`
|
||||
* variable-size buffer (still need to add code to change size)
|
||||
* added (tentative) support for internationalisation
|
||||
* removed superfluous "`--no-progress`", etc options
|
||||
* optimised transfer by using bigger buffers, based on `st_blksize`
|
||||
* added "`--wait`" option to wait until transfer begins before showing progress
|
||||
* added "`--rate-limit`" option to limit rate to a maximum throughput
|
||||
* added "`--quiet`" option (no output at all) to be used with "`--rate-limit`"
|
||||
|
||||
0.2.5 - 23 July 2002
|
||||
|
||||
* added *[FILE]...* arguments, like "`cat`"
|
||||
* function separation in code
|
||||
* some bug fixes related to numeric overflow
|
||||
|
||||
0.2.3 - 19 July 2002
|
||||
|
||||
* Texinfo manual written, man page updated
|
||||
* byte counter added
|
||||
|
||||
0.2.0 - 18 July 2002
|
||||
|
||||
* ETA counter added
|
||||
* screen width estimation added
|
||||
* progress bar added
|
||||
|
||||
0.1.0 - 17 July 2002
|
||||
|
||||
* main loop created
|
||||
* rate counter added
|
||||
* elapsed time counter added
|
||||
* percentage calculation added
|
||||
|
||||
0.0.1 - 16 July 2002
|
||||
|
||||
* package created
|
||||
* first draft of man page written
|
||||
@@ -0,0 +1,38 @@
|
||||
Things still to do. (#n) indicates the issue tracker number.
|
||||
|
||||
Bugs
|
||||
----
|
||||
|
||||
* ([#34](https://codeberg.org/a-j-wood/pv/issues/34)) Continue timer even if input or output is blocking (Martin Probst - Jun 2017)
|
||||
|
||||
Feature requests
|
||||
----------------
|
||||
|
||||
* ([#3](https://codeberg.org/a-j-wood/pv/issues/3)) Option ("`-x`"?) to use xterm title line for status (Joachim Haga)
|
||||
* ([#4](https://codeberg.org/a-j-wood/pv/issues/4)) Option for process title (Martin Sarsale) as "`pv - name:FooProcess -xyz - transferred: 1.3GB - 500KB/s - running: 10:15:30s`"
|
||||
* ([#6](https://codeberg.org/a-j-wood/pv/issues/6)) Look at effect of *O_SYNC* or `fsync` on performance; update counters during buffer flush
|
||||
* ([#9](https://codeberg.org/a-j-wood/pv/issues/9)) Option to switch rate to per minute if really slow
|
||||
* ([#10](https://codeberg.org/a-j-wood/pv/issues/10)) Add watchfd tests
|
||||
* ([#11](https://codeberg.org/a-j-wood/pv/issues/11)) Option "`--progress-from FILE`", read last number and use it as bytes read (Jacek Wielemborek)
|
||||
* ([#12](https://codeberg.org/a-j-wood/pv/issues/12)) Allow multiple "`-d`" options (Linus Heckemann for multiple PID:FD; Jacek Wielemborek)
|
||||
* ([#15](https://codeberg.org/a-j-wood/pv/issues/15)) Use Unicode for more granular progress bar (Alexander Petrossian)
|
||||
* ([#17](https://codeberg.org/a-j-wood/pv/issues/17)) Allow "`-r`" with "`-l`" and "`-n`" to output lines/sec (Roland Kletzing)
|
||||
* ([#22](https://codeberg.org/a-j-wood/pv/issues/22)) Options to skip input and seek on output (Jason A. Pfeil, Feb 2022)
|
||||
* ([#25](https://codeberg.org/a-j-wood/pv/issues/25)) Normalise progress to 100% on overrun (Andrej Gantvorg)
|
||||
* ([#35](https://codeberg.org/a-j-wood/pv/issues/35)) Allow decimal values for "`-s`", "`-L`", "`-B`" (Thomas Watson - Aug 2020)
|
||||
* ([#38](https://codeberg.org/a-j-wood/pv/issues/38)) Reset ETA on *SIGUSR1* (Jacek Wielemborek - Jan 2019)
|
||||
* ([#40](https://codeberg.org/a-j-wood/pv/issues/40)) Permit "`-c`" with "`-d PID:FD`", reject "`-N`" with "`-d PID`" (Norman Rasmussen - Nov 2020)
|
||||
* ([#43](https://codeberg.org/a-j-wood/pv/issues/43)) Differentiate between "`--eta`" and "`--fineta`" in display (André Stapf - Apr 2017)
|
||||
* ([#45](https://codeberg.org/a-j-wood/pv/issues/45)) Option "`--sparse`" (with block size option) to write sparse output (Andriy Galetski - Apr 2019)
|
||||
* ([#46](https://codeberg.org/a-j-wood/pv/issues/46)) Option to show speed gauge (% max speed) if progress not known (Ryan Cooley - Jun 2019)
|
||||
* ([#47](https://codeberg.org/a-j-wood/pv/issues/47)) Analyse splice and buffer usage to improve performance
|
||||
* ([#48](https://codeberg.org/a-j-wood/pv/issues/48)) Option to show multiple files with individual sizes and a cumulative total (Zach Riggle - Jul 2021)
|
||||
* ([#49](https://codeberg.org/a-j-wood/pv/issues/49)) Option to provide stats for avg/min/max/stddev throughput (Venky.N.Iyer)
|
||||
* ([#50](https://codeberg.org/a-j-wood/pv/issues/50)) Allow pv to report on a whole pipeline at once (Will Entriken - Feb 2011)
|
||||
* ([#54](https://codeberg.org/a-j-wood/pv/issues/54)) Run command every n percent ([haarp](https://github.com/haarp))
|
||||
* ([#56](https://codeberg.org/a-j-wood/pv/issues/56)) Support for backgrounding pv, and allowing it to be monitored separately ([jimbobmcgee](https://github.com/jimbobmcgee))
|
||||
* ([#67](https://codeberg.org/a-j-wood/pv/issues/67)) Wrap another process to monitor its stdin & stdout ([Alex Mason](https://github.com/axman6))
|
||||
* Find a reliable way to test translations
|
||||
* Switch license to GPLv3+
|
||||
|
||||
Any assistance would be appreciated.
|
||||
Executable
+39
@@ -0,0 +1,39 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# Benchmark the read/write performance of pv by looking at the number of
|
||||
# read() and write() calls and the average amount of data transferred each
|
||||
# time, as suggested by Ville Herva <Ville.Herva@iki.fi>.
|
||||
#
|
||||
|
||||
test_input=$(mktemp /tmp/pvbench1XXXXXX)
|
||||
strace_output=$(mktemp /tmp/pvbench2XXXXXX)
|
||||
|
||||
trap 'rm -f ${test_input} ${strace_output}' EXIT
|
||||
|
||||
pv=${pv:-./pv}
|
||||
test -x "${pv}" || pv="pv"
|
||||
|
||||
dd if=/dev/zero of="${test_input}" bs=1k count=1k >/dev/null 2>&1
|
||||
|
||||
echo -e "Buf(k)\tRate(k)\tReads\tRsize\tWrites\tWsize"
|
||||
|
||||
for ((buffer=100; buffer<=1000; buffer+=100)); do
|
||||
for ((rate=100; rate<=1000; rate+=100)); do
|
||||
rateparm="-L ${rate}k"
|
||||
test ${rate} -eq 0 && rateparm=""
|
||||
strace -tt -o "${strace_output}" \
|
||||
"${pv}" "${rateparm}" -B "${buffer}k" \
|
||||
-f < "${test_input}" > /dev/null 2>&1
|
||||
rdata=$(
|
||||
awk '$2~/^read\(0,/{c++;t+=$NF}END{print c "\t" t/c}' \
|
||||
"${strace_output}"
|
||||
)
|
||||
wdata=$(
|
||||
awk '$2~/^write\(1,/{c++;t+=$NF}END{print c "\t" t/c}' \
|
||||
"${strace_output}"
|
||||
)
|
||||
echo -e "${buffer}\t${rate}\t${rdata}\t${wdata}"
|
||||
done
|
||||
done
|
||||
|
||||
# EOF
|
||||
@@ -0,0 +1,722 @@
|
||||
.TH PV 1 "September 2023" Linux "User Manuals"
|
||||
.SH NAME
|
||||
pv \- monitor the progress of data through a pipe
|
||||
.SH SYNOPSIS
|
||||
.B pv
|
||||
[\fIOPTION\fR]
|
||||
[\fIFILE\fR]...
|
||||
.br
|
||||
.B pv
|
||||
[\fI\-h\fR|\fI\-V\fR]
|
||||
|
||||
|
||||
.SH DESCRIPTION
|
||||
.B pv
|
||||
shows the progress of data through a pipeline by giving information such as
|
||||
time elapsed, percentage completed (with progress bar), current throughput
|
||||
rate, total data transferred, and ETA.
|
||||
|
||||
To use it, insert it in a pipeline between two processes, with the
|
||||
appropriate options. Its standard input will be passed through to its
|
||||
standard output and progress will be shown on standard error.
|
||||
|
||||
.B pv
|
||||
will copy each supplied
|
||||
.I FILE
|
||||
in turn to standard output
|
||||
.BR "" "(" -
|
||||
means standard input), or if no
|
||||
.IR FILE s
|
||||
are specified just standard input is copied. This is the same behaviour
|
||||
as
|
||||
.BR cat (1).
|
||||
|
||||
A simple example to watch how quickly a file is transferred using
|
||||
.BR nc (1):
|
||||
|
||||
.RS
|
||||
.B pv file | nc -w 1 somewhere.com 3000
|
||||
.RE
|
||||
|
||||
A similar example, transferring a file from another process and passing the
|
||||
expected size to
|
||||
.BR pv :
|
||||
|
||||
.RS
|
||||
.B cat file | pv -s 12345 | nc -w 1 somewhere.com 3000
|
||||
.RE
|
||||
|
||||
A more complicated example using numeric output to feed into the
|
||||
.BR dialog (1)
|
||||
program for a full-screen progress display:
|
||||
|
||||
.RS
|
||||
.B (tar cf - . \e
|
||||
.br
|
||||
.B " | pv -n -s $(du -sb . | awk '{print $1}') \e"
|
||||
.br
|
||||
.B " | gzip -9 > out.tgz) 2>&1 \e"
|
||||
.br
|
||||
.B | dialog --gauge 'Progress' 7 70
|
||||
.RE
|
||||
|
||||
Taking an image of a disk, skipping errors:
|
||||
|
||||
.RS
|
||||
.B pv -EE /dev/your/disk/device > disk-image.img
|
||||
.RE
|
||||
|
||||
Writing an image back to a disk:
|
||||
|
||||
.RS
|
||||
.B pv disk-image.img > /dev/your/disk/device
|
||||
.RE
|
||||
|
||||
Zeroing a disk:
|
||||
|
||||
.RS
|
||||
.B pv < /dev/zero > /dev/your/disk/device
|
||||
.RE
|
||||
|
||||
Note that if the input size cannot be calculated, and the output is a block
|
||||
device, then the size of the block device will be used and
|
||||
.B pv
|
||||
will automatically stop at that size as if
|
||||
.B \-S
|
||||
had been given.
|
||||
|
||||
(Linux only): Watching file descriptor 3 opened by another process 1234:
|
||||
|
||||
.RS
|
||||
.B pv -d 1234:3
|
||||
.RE
|
||||
|
||||
(Linux only): Watching all file descriptors used by process 1234:
|
||||
|
||||
.RS
|
||||
.B pv -d 1234
|
||||
.RE
|
||||
|
||||
|
||||
.SH OPTIONS
|
||||
.B pv
|
||||
takes many options, which are divided into display switches, output
|
||||
modifiers, and general options.
|
||||
|
||||
|
||||
.SH DISPLAY SWITCHES
|
||||
If no display switches are specified,
|
||||
.B pv
|
||||
behaves as if
|
||||
.BR \-p ", " \-t ", " \-e ", " \-r ", and " \-b
|
||||
had been given (i.e. everything except average rate is switched on).
|
||||
Otherwise, only those display types that are explicitly switched on will be
|
||||
shown.
|
||||
.TP
|
||||
.B \-p, \-\-progress
|
||||
Turn the progress bar on. If any inputs are not files, or are
|
||||
unreadable, and no size was explicitly given (with the
|
||||
.B \-s
|
||||
modifier), the progress bar cannot indicate how close to completion the
|
||||
transfer is, so it will just move left and right to indicate that data is
|
||||
moving.
|
||||
.TP
|
||||
.B \-t, \-\-timer
|
||||
Turn the timer on. This will display the total elapsed time that
|
||||
.B pv
|
||||
has been running for.
|
||||
.TP
|
||||
.B \-e, \-\-eta
|
||||
Turn the ETA timer on. This will attempt to guess, based on current
|
||||
transfer rates and the total data size, how long it will be before
|
||||
completion. This option will have no effect if the total data size cannot
|
||||
be determined.
|
||||
.TP
|
||||
.B \-I, \-\-fineta
|
||||
Turn the ETA timer on, but display the estimated local time of arrival
|
||||
instead of time left. When the estimated time is more than 6 hours in the
|
||||
future, the date is shown as well.
|
||||
.TP
|
||||
.B \-r, \-\-rate
|
||||
Turn the rate counter on. This will display the current rate of data
|
||||
transfer.
|
||||
.TP
|
||||
.B \-a, \-\-average\-rate
|
||||
Turn the average rate counter on. This will display the current average
|
||||
rate of data transfer (default: last 30s, see
|
||||
.BR \-m ).
|
||||
.TP
|
||||
.B \-b, \-\-bytes
|
||||
Turn the total byte counter on. This will display the total amount of
|
||||
data transferred so far.
|
||||
.TP
|
||||
.B \-8, \-\-bits
|
||||
Display the total bits instead of the total bytes. The output suffix will
|
||||
be "b" instead of "B".
|
||||
.TP
|
||||
.B \-T, \-\-buffer\-percent
|
||||
Turn on the transfer buffer percentage display. This will show the
|
||||
percentage of the transfer buffer in use - but see the caveat under
|
||||
.B %T
|
||||
in the
|
||||
.B FORMATTING
|
||||
section below. Implies
|
||||
.BR \-C .
|
||||
.TP
|
||||
.BI \-A\ NUM \fR,\ \fB\-\-last\-written\ NUM
|
||||
Show the last
|
||||
.I NUM
|
||||
bytes written - but see the caveat under
|
||||
.B %nA
|
||||
in the
|
||||
.B FORMATTING
|
||||
section below. Implies
|
||||
.BR \-C .
|
||||
.TP
|
||||
.BI \-F\ FORMAT \fR,\ \fB\-\-format\ FORMAT
|
||||
Ignore the options
|
||||
.BR \-p ,
|
||||
.BR \-t ,
|
||||
.BR \-e ,
|
||||
.BR \-r ,
|
||||
.BR \-a ,
|
||||
.BR \-b ,
|
||||
.BR \-T ,
|
||||
and
|
||||
.BR \-A ,
|
||||
and instead use the format string
|
||||
.I FORMAT
|
||||
to determine the output format. See the
|
||||
.B FORMATTING
|
||||
section below.
|
||||
.TP
|
||||
.B \-n, \-\-numeric
|
||||
Numeric output. Instead of giving a visual indication of progress,
|
||||
.B pv
|
||||
will give an integer percentage, one per line, on standard error, suitable
|
||||
for piping (via convoluted redirection) into
|
||||
.BR dialog (1).
|
||||
Note that
|
||||
.B \-f
|
||||
is not required if
|
||||
.B \-n
|
||||
is being used.
|
||||
.TP
|
||||
.B ""
|
||||
Note that if
|
||||
.B \-\-numeric
|
||||
is in use, then adding
|
||||
.B \-\-bytes
|
||||
will cause the number of bytes processed so far to be output instead of a
|
||||
percentage; if
|
||||
.B \-\-line\-mode
|
||||
is also in use as well as
|
||||
.B \-\-bytes
|
||||
and
|
||||
.BR \-\-numeric ,
|
||||
then instead of bytes or a percentage, the number of lines
|
||||
so far is output. And finally, if
|
||||
.B \-\-timer
|
||||
is added to
|
||||
.BR \-\-numeric ,
|
||||
then each output line is prefixed with the elapsed time
|
||||
so far, as a decimal number of seconds.
|
||||
.TP
|
||||
.B \-q, \-\-quiet
|
||||
No output. Useful if the
|
||||
.B \-L
|
||||
option is being used on its own to just limit the transfer rate of a pipe.
|
||||
|
||||
|
||||
.SH OUTPUT MODIFIERS
|
||||
.TP
|
||||
.B \-W, \-\-wait
|
||||
Wait until the first byte has been transferred before showing any progress
|
||||
information or calculating any ETAs. Useful if the program you are piping to
|
||||
or from requires extra information before it starts, eg piping data into
|
||||
.BR gpg (1)
|
||||
or
|
||||
.BR mcrypt (1)
|
||||
which require a passphrase before data can be processed.
|
||||
.TP
|
||||
.BI \-D\ SEC \fR,\ \fB\-\-delay\-start\ SEC
|
||||
Wait until
|
||||
.I SEC
|
||||
seconds have passed before showing any progress information, for example in
|
||||
a script where you only want to show a progress bar if it starts taking a
|
||||
long time. Note that this can be a decimal such as 0.5.
|
||||
.TP
|
||||
.BI \-s\ SIZE \fR,\ \fB\-\-size\ SIZE
|
||||
Assume the total amount of data to be transferred is
|
||||
.I SIZE
|
||||
bytes when calculating percentages and ETAs. The same suffixes of "k", "m"
|
||||
etc can be used as with
|
||||
.BR -L .
|
||||
.TP
|
||||
.B ""
|
||||
If
|
||||
.I SIZE
|
||||
starts with
|
||||
.BR "@" ,
|
||||
the size of file whose name follows the
|
||||
.B @
|
||||
will be used.
|
||||
.TP
|
||||
.B ""
|
||||
Note that
|
||||
.B \-\-size
|
||||
has no effect if used with
|
||||
.BI \-d\ PID
|
||||
to watch all file descriptors of a process, but will work with
|
||||
.BR "-d PID:FD" .
|
||||
.TP
|
||||
.B \-l, \-\-line\-mode
|
||||
Instead of counting bytes, count lines (newline characters). The progress
|
||||
bar will only move when a new line is found, and the value passed to the
|
||||
.B \-s
|
||||
option will be interpreted as a line count.
|
||||
.TP
|
||||
.B ""
|
||||
If this option is used without
|
||||
.BR \-s ,
|
||||
the "total size" (in this case, total line count) is calculated by reading
|
||||
through all input files once before transfer starts. If any inputs are
|
||||
pipes or non-regular files, or are unreadable, the total size will not be
|
||||
calculated.
|
||||
.TP
|
||||
.B \-0, \-\-null
|
||||
Count lines as terminated with a zero byte instead of with a newline.
|
||||
This option implies \-\-line\-mode.
|
||||
.TP
|
||||
.BI \-i\ SEC \fR,\ \fB\-\-interval\ SEC
|
||||
Wait
|
||||
.I SEC
|
||||
seconds between updates. The default is to update every second.
|
||||
Note that this can be a decimal such as 0.1.
|
||||
.TP
|
||||
.BI \-m\ SEC \fR,\ \fB\-\-average-rate-window\ SEC
|
||||
Compute current average rate over a
|
||||
.I SEC
|
||||
seconds window for average rate and ETA calculations (default 30 seconds).
|
||||
.TP
|
||||
.BI \-w\ WIDTH \fR,\ \fB\-\-width\ WIDTH
|
||||
Assume the terminal is
|
||||
.I WIDTH
|
||||
characters wide, instead of trying to work it out (or assuming 80 if it
|
||||
cannot be guessed). If this option is used, the output width will not be
|
||||
adjusted if the width of the terminal changes while the transfer is running.
|
||||
.TP
|
||||
.BI \-H\ HEIGHT \fR,\ \fB\-\-height\ HEIGHT
|
||||
Assume the terminal is
|
||||
.I HEIGHT
|
||||
rows high, instead of trying to work it out (or assuming 25 if it
|
||||
cannot be guessed). If this option is used, the output height will not be
|
||||
adjusted if the height of the terminal changes while the transfer is
|
||||
running.
|
||||
.TP
|
||||
.BI \-N\ NAME \fR,\ \fB\-\-name\ NAME
|
||||
Prefix the output information with
|
||||
.IR NAME .
|
||||
Useful in conjunction with
|
||||
.B \-c
|
||||
if you have a complicated pipeline and you want to be able to tell different
|
||||
parts of it apart.
|
||||
.TP
|
||||
.B \-f, \-\-force
|
||||
Force output. Normally,
|
||||
.B pv
|
||||
will not output any visual display if standard error is not a terminal.
|
||||
This option forces it to do so.
|
||||
.TP
|
||||
.B \-c, \-\-cursor
|
||||
Use cursor positioning escape sequences instead of just using carriage
|
||||
returns. This is useful in conjunction with
|
||||
.B \-N
|
||||
(name) if you are using multiple
|
||||
.B pv
|
||||
invocations in a single, long, pipeline.
|
||||
|
||||
|
||||
.SH DATA TRANSFER MODIFIERS
|
||||
.TP
|
||||
.BI \-L\ RATE \fR,\ \fB\-\-rate-limit\ RATE
|
||||
Limit the transfer to a maximum of
|
||||
.I RATE
|
||||
bytes per second. A suffix of "K", "M", "G", or "T" can be added to denote
|
||||
kibibytes (*1024), mebibytes, and so on.
|
||||
.TP
|
||||
.BI \-B\ BYTES \fR,\ \fB\-\-buffer-size\ BYTES
|
||||
Use a transfer buffer size of
|
||||
.I BYTES
|
||||
bytes. A suffix of "K", "M", "G", or "T" can be added to denote
|
||||
kibibytes (*1024), mebibytes, and so on. The default buffer size is the
|
||||
block size of the input file's filesystem multiplied by 32 (512KiB max), or
|
||||
400KiB if the block size cannot be determined. This can be useful on
|
||||
platforms like MacOS which perform better in pipelines with specific buffer
|
||||
sizes such as 1024. Implies
|
||||
.BR \-C .
|
||||
.TP
|
||||
.B \-C, \-\-no-splice
|
||||
Never use
|
||||
.BR splice (2),
|
||||
even if it would normally be possible. The
|
||||
.BR splice (2)
|
||||
system call is a more efficient way of transferring data from or to a pipe
|
||||
than regular
|
||||
.BR read (2)
|
||||
and
|
||||
.BR write (2),
|
||||
but means that the transfer buffer may not be used. This prevents
|
||||
.B \-A
|
||||
and
|
||||
.B \-T
|
||||
from working, cannot work with
|
||||
.BR \-X ,
|
||||
and makes
|
||||
.B \-B
|
||||
redundant, so using
|
||||
.BR \-A ,
|
||||
.BR \-T ,
|
||||
.BR \-X ,
|
||||
or
|
||||
.B \-B
|
||||
automatically switches on
|
||||
.BR \-C .
|
||||
Switching on
|
||||
.B \-C
|
||||
results in a small loss of transfer efficiency.
|
||||
(This option has no effect on systems where
|
||||
.BR splice (2)
|
||||
is unavailable).
|
||||
.TP
|
||||
.B \-E, \-\-skip-errors
|
||||
Ignore read errors by attempting to skip past the offending sections. The
|
||||
corresponding parts of the output will be null bytes. At first only a few
|
||||
bytes will be skipped, but if there are many errors in a row then the skips
|
||||
will move up to chunks of 512. This is intended to be similar to
|
||||
.B dd conv=sync,noerror
|
||||
but has not been as thoroughly tested.
|
||||
.TP
|
||||
.B ""
|
||||
Specify
|
||||
.B \-E
|
||||
twice to only report a read error once per file, instead of reporting each
|
||||
byte range skipped.
|
||||
.TP
|
||||
.BI \-Z\ BYTES \fR,\ \fB\-\-error\-skip\-block\ BYTES
|
||||
When ignoring read errors with
|
||||
.BR \-E ,
|
||||
instead of trying to adaptively skip by reading small amounts and skipping
|
||||
progressively larger sections until a read succeeds, move to the next file
|
||||
block of
|
||||
.I BYTES
|
||||
bytes as soon as an error occurs. There may still be some shorter skips
|
||||
where the block being skipped coincides with the end of the transfer buffer.
|
||||
.TP
|
||||
.B ""
|
||||
This option can only be used with
|
||||
.B \-E
|
||||
and is intended for use when reading from a block device, such as
|
||||
.B \-E\ \-Z\ 4K
|
||||
to skip in 4 kibibyte blocks. This will speed up reads from faulty media,
|
||||
at the expense of potentially losing more data.
|
||||
.TP
|
||||
.B \-S, \-\-stop-at-size
|
||||
If a size was specified with
|
||||
.BR \-s ,
|
||||
stop transferring data once that many bytes have been written, instead of
|
||||
continuing to the end of input.
|
||||
.TP
|
||||
.B \-Y, \-\-sync
|
||||
After every write operation, synchronise the buffer caches to disk - see
|
||||
.BR fdatasync (2).
|
||||
This has no effect when the output is a pipe. Using
|
||||
.B \-Y
|
||||
may improve the accuracy of the progress bar when writing to a slow disk.
|
||||
.TP
|
||||
.B \-K, \-\-direct-io
|
||||
Set the
|
||||
.B O_DIRECT
|
||||
flag on all inputs and outputs, if it is available. This will minimise
|
||||
the effect of caches, at the cost of performance. Due to memory alignment
|
||||
requirements, it also may cause read or write failures with an error of
|
||||
"Invalid argument", especially if reading and writing files across a variety
|
||||
of filesystems in a single
|
||||
.B pv
|
||||
call. Use this option with caution.
|
||||
.TP
|
||||
.B \-X, \-\-discard
|
||||
Instead of transferring input data to standard output, discard it. This is
|
||||
equivalent to redirecting standard output to
|
||||
.IR /dev/null ,
|
||||
except that
|
||||
.BR write (2)
|
||||
is never called. Implies
|
||||
.BR \-C .
|
||||
.TP
|
||||
.BI \-d\ PID\fR[\fB:\fR\fIFD\fR],\ \fB\-\-watchfd\ PID\fR[\fB:\fR\fIFD\fR]
|
||||
Instead of transferring data, watch file descriptor
|
||||
.I FD
|
||||
of process
|
||||
.IR PID ,
|
||||
and show its progress. The
|
||||
.B pv
|
||||
process will exit when
|
||||
.I FD
|
||||
either changes to a different file, changes read/write mode, or is closed;
|
||||
other data transfer modifiers - and remote control - may not be used with
|
||||
this option.
|
||||
.TP
|
||||
.B ""
|
||||
If only a
|
||||
.I PID
|
||||
is specified, then that process will be watched, and all regular files and
|
||||
block devices it opens will be shown with a progress bar. The
|
||||
.B pv
|
||||
process will exit when process
|
||||
.I PID
|
||||
exits.
|
||||
.TP
|
||||
.BI \-R\ PID \fR,\ \fB\-\-remote\ PID
|
||||
If
|
||||
.I PID
|
||||
is an instance of
|
||||
.B pv
|
||||
that is already running,
|
||||
.BI \-R\ PID
|
||||
will cause that instance to act as though it had been given
|
||||
this instance's command line instead. For example, if
|
||||
.B pv -L 123K
|
||||
is running with process ID 9876, then running
|
||||
.B pv -R 9876 -L 321K
|
||||
will cause it to start using a rate limit of 321KiB instead of 123KiB.
|
||||
Note that some options cannot be changed while running, such as
|
||||
.BR \-c ,
|
||||
.BR \-l ,
|
||||
.BR \-f ,
|
||||
.BR \-D ,
|
||||
.BR \-E ,
|
||||
and
|
||||
.BR \-S .
|
||||
|
||||
.SH GENERAL OPTIONS
|
||||
.TP
|
||||
.BI \-P\ FILE \fR,\ \fB\-\-pidfile\ FILE
|
||||
Save the process ID of
|
||||
.B pv
|
||||
in
|
||||
.IR FILE .
|
||||
The file will be replaced if it already exists, and will be removed when
|
||||
.B pv
|
||||
exits. While
|
||||
.B pv
|
||||
is running, it will contain a single number - the process ID of
|
||||
.B pv
|
||||
- followed by a newline.
|
||||
.TP
|
||||
.B \-h, \-\-help
|
||||
Print a usage message on standard output and exit successfully.
|
||||
.TP
|
||||
.B \-V, \-\-version
|
||||
Print version information on standard output and exit successfully.
|
||||
|
||||
|
||||
.SH FORMATTING
|
||||
If the
|
||||
.B \-F
|
||||
option is given, then the output format is determined by the given format
|
||||
string. Within that string, the following sequences can be used:
|
||||
.TP
|
||||
.B %p
|
||||
Progress bar.
|
||||
Expands to fill the remaining space. Should only be specified once.
|
||||
Equivalent to
|
||||
.BR \-p .
|
||||
.TP
|
||||
.B %t
|
||||
Elapsed time. Equivalent to
|
||||
.BR \-t .
|
||||
.TP
|
||||
.B %e
|
||||
ETA as time remaining. Equivalent to
|
||||
.BR \-e .
|
||||
.TP
|
||||
.B %I
|
||||
ETA as local time of completion. Equivalent to
|
||||
.BR \-I .
|
||||
.TP
|
||||
.B %r
|
||||
Current data transfer rate. Equivalent to
|
||||
.BR \-r .
|
||||
.TP
|
||||
.B %a
|
||||
Average data transfer rate. Equivalent to
|
||||
.BR \-a .
|
||||
.TP
|
||||
.B %b
|
||||
Bytes transferred so far (or lines if
|
||||
.B \-l
|
||||
was specified). Equivalent to
|
||||
.BR \-b .
|
||||
If
|
||||
.B \-\-bits
|
||||
was specified,
|
||||
.B %b
|
||||
shows the bits transferred so far, not bytes.
|
||||
.TP
|
||||
.B %T
|
||||
Percentage of the transfer buffer in use. Equivalent to
|
||||
.BR \-T .
|
||||
Shows "{----}" if the transfer is being done with
|
||||
.BR splice (2),
|
||||
since splicing to or from pipes does not use the buffer.
|
||||
.TP
|
||||
.B %nA
|
||||
Show the last
|
||||
.B n
|
||||
bytes written (e.g.
|
||||
.B %16A
|
||||
for the last 16 bytes).
|
||||
Shows only dots if the transfer is being done with
|
||||
.BR splice (2),
|
||||
since splicing to or from pipes does not use the buffer.
|
||||
.TP
|
||||
.B %N
|
||||
Name prefix given by
|
||||
.BR -N .
|
||||
Padded to 9 characters with spaces, and suffixed with :.
|
||||
.TP
|
||||
.B %%
|
||||
A single %.
|
||||
.P
|
||||
The format string equivalent of turning on all display switches is
|
||||
.BR "\`%N %b %T %t %r %a %p %e'" .
|
||||
|
||||
|
||||
.SH COMMON SWITCHES
|
||||
Some suggested common switch combinations:
|
||||
|
||||
.TP
|
||||
.B pv -ptebar
|
||||
Show a progress bar, elapsed time, estimated completion time, byte counter,
|
||||
average rate, and current rate.
|
||||
.TP
|
||||
.B pv -betlap
|
||||
Show a progress bar, elapsed time, estimated completion time, line counter,
|
||||
and average rate, counting lines instead of bytes.
|
||||
.TP
|
||||
.B pv -t
|
||||
Show only the elapsed time - useful as a simple timer, e.g.
|
||||
.BR "sleep 10m | pv -t" .
|
||||
.TP
|
||||
.B pv -pterb
|
||||
The default behaviour: progress bar, elapsed time, estimated completion
|
||||
time, current rate, and byte counter.
|
||||
|
||||
.P
|
||||
On MacOS, it may be useful to specify
|
||||
.B -B 1024
|
||||
in a pipeline, as this may improve performance.
|
||||
|
||||
|
||||
.SH EXIT STATUS
|
||||
An exit status of 1 indicates a problem with the
|
||||
.B \-R
|
||||
or
|
||||
.B \-P
|
||||
options.
|
||||
|
||||
Any other exit status is a bitmask of the following:
|
||||
|
||||
.TP
|
||||
.B 2
|
||||
One or more files could not be accessed,
|
||||
.BR stat (2)ed,
|
||||
or opened.
|
||||
.TP
|
||||
.B 4
|
||||
An input file was the same as the output file.
|
||||
.TP
|
||||
.B 8
|
||||
Internal error with closing a file or moving to the next file.
|
||||
.TP
|
||||
.B 16
|
||||
There was an error while transferring data from one or more input files.
|
||||
.TP
|
||||
.B 32
|
||||
A signal was caught that caused an early exit.
|
||||
.TP
|
||||
.B 64
|
||||
Memory allocation failed.
|
||||
|
||||
.P
|
||||
A zero exit status indicates no problems.
|
||||
|
||||
|
||||
.SH AUTHOR
|
||||
Written by Andrew Wood, with patches submitted by various other people.
|
||||
Please see the package's ACKNOWLEDGEMENTS file for a complete list of
|
||||
contributors.
|
||||
|
||||
|
||||
.SH KNOWN PROBLEMS
|
||||
The following problems are known to exist in
|
||||
.BR pv :
|
||||
.TP
|
||||
.B *
|
||||
In some versions of
|
||||
.BR bash (1)
|
||||
and
|
||||
.BR zsh (1),
|
||||
the construct
|
||||
.B <(pv filename)
|
||||
will not output any progress to the terminal when run from an interactive
|
||||
shell, due to the subprocess being run in a separate process group from the
|
||||
one that owns the terminal. In these cases, use
|
||||
.BR \-\-force .
|
||||
.P
|
||||
.TP
|
||||
.B *
|
||||
The
|
||||
.B -c
|
||||
option does not work properly on Cygwin without
|
||||
.B cygserver
|
||||
running, if started near the bottom of the screen (IPC is needed to handle
|
||||
the terminal scrolling). To fix this, start
|
||||
.B cygserver
|
||||
before using
|
||||
.BR "pv -c" .
|
||||
.P
|
||||
.TP
|
||||
.B *
|
||||
The
|
||||
.B -R
|
||||
option is not available on Cygwin without
|
||||
.B cygserver
|
||||
running (SYSV IPC is needed). To fix this, start
|
||||
.B cygserver
|
||||
before running the instance of
|
||||
.B pv
|
||||
you want, at runtime, to change the parameters of.
|
||||
.P
|
||||
If you find any other problems, please report them.
|
||||
|
||||
|
||||
.SH REPORTING BUGS
|
||||
Please report any bugs to: <https://codeberg.org/a-j-wood/pv/issues>
|
||||
|
||||
Alternatively, use the contact form linked from the
|
||||
.B pv
|
||||
home page: <http://www.ivarch.com/programs/pv.shtml>
|
||||
|
||||
|
||||
.SH "SEE ALSO"
|
||||
.BR cat (1),
|
||||
.BR dialog (1),
|
||||
.BR splice (2),
|
||||
.BR open (2)
|
||||
(for
|
||||
.BR O_DIRECT )
|
||||
|
||||
.SH LICENSE
|
||||
This is free software, distributed under the ARTISTIC 2.0 license.
|
||||
+548
@@ -0,0 +1,548 @@
|
||||
# NAME
|
||||
|
||||
pv - monitor the progress of data through a pipe
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**pv** \[*OPTION*\] \[*FILE*\]\...\
|
||||
**pv** \[*-h*\|*-V*\]
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
**pv** shows the progress of data through a pipeline by giving
|
||||
information such as time elapsed, percentage completed (with progress
|
||||
bar), current throughput rate, total data transferred, and ETA.
|
||||
|
||||
To use it, insert it in a pipeline between two processes, with the
|
||||
appropriate options. Its standard input will be passed through to its
|
||||
standard output and progress will be shown on standard error.
|
||||
|
||||
**pv** will copy each supplied *FILE* in turn to standard output (**-**
|
||||
means standard input), or if no *FILE*s are specified just standard
|
||||
input is copied. This is the same behaviour as **cat**(1).
|
||||
|
||||
A simple example to watch how quickly a file is transferred using
|
||||
**nc**(1):
|
||||
|
||||
> **pv file \| nc -w 1 somewhere.com 3000**
|
||||
|
||||
A similar example, transferring a file from another process and passing
|
||||
the expected size to **pv**:
|
||||
|
||||
> **cat file \| pv -s 12345 \| nc -w 1 somewhere.com 3000**
|
||||
|
||||
A more complicated example using numeric output to feed into the
|
||||
**dialog**(1) program for a full-screen progress display:
|
||||
|
||||
> **(tar cf - . \\**\
|
||||
> ** \| pv -n -s \$(du -sb . \| awk \'{print \$1}\') \\**\
|
||||
> ** \| gzip -9 \> out.tgz) 2\>&1 \\**\
|
||||
> **\| dialog \--gauge \'Progress\' 7 70**
|
||||
|
||||
Taking an image of a disk, skipping errors:
|
||||
|
||||
> **pv -EE /dev/your/disk/device \> disk-image.img**
|
||||
|
||||
Writing an image back to a disk:
|
||||
|
||||
> **pv disk-image.img \> /dev/your/disk/device**
|
||||
|
||||
Zeroing a disk:
|
||||
|
||||
> **pv \< /dev/zero \> /dev/your/disk/device**
|
||||
|
||||
Note that if the input size cannot be calculated, and the output is a
|
||||
block device, then the size of the block device will be used and **pv**
|
||||
will automatically stop at that size as if **-S** had been given.
|
||||
|
||||
(Linux only): Watching file descriptor 3 opened by another process 1234:
|
||||
|
||||
> **pv -d 1234:3**
|
||||
|
||||
(Linux only): Watching all file descriptors used by process 1234:
|
||||
|
||||
> **pv -d 1234**
|
||||
|
||||
# OPTIONS
|
||||
|
||||
**pv** takes many options, which are divided into display switches,
|
||||
output modifiers, and general options.
|
||||
|
||||
# DISPLAY SWITCHES
|
||||
|
||||
If no display switches are specified, **pv** behaves as if **-p**,
|
||||
**-t**, **-e**, **-r**, and **-b** had been given (i.e. everything
|
||||
except average rate is switched on). Otherwise, only those display types
|
||||
that are explicitly switched on will be shown.
|
||||
|
||||
**-p, \--progress**
|
||||
|
||||
: Turn the progress bar on. If any inputs are not files, or are
|
||||
unreadable, and no size was explicitly given (with the **-s**
|
||||
modifier), the progress bar cannot indicate how close to completion
|
||||
the transfer is, so it will just move left and right to indicate
|
||||
that data is moving.
|
||||
|
||||
**-t, \--timer**
|
||||
|
||||
: Turn the timer on. This will display the total elapsed time that
|
||||
**pv** has been running for.
|
||||
|
||||
**-e, \--eta**
|
||||
|
||||
: Turn the ETA timer on. This will attempt to guess, based on current
|
||||
transfer rates and the total data size, how long it will be before
|
||||
completion. This option will have no effect if the total data size
|
||||
cannot be determined.
|
||||
|
||||
**-I, \--fineta**
|
||||
|
||||
: Turn the ETA timer on, but display the estimated local time of
|
||||
arrival instead of time left. When the estimated time is more than 6
|
||||
hours in the future, the date is shown as well.
|
||||
|
||||
**-r, \--rate**
|
||||
|
||||
: Turn the rate counter on. This will display the current rate of data
|
||||
transfer.
|
||||
|
||||
**-a, \--average-rate**
|
||||
|
||||
: Turn the average rate counter on. This will display the current
|
||||
average rate of data transfer (default: last 30s, see **-m**).
|
||||
|
||||
**-b, \--bytes**
|
||||
|
||||
: Turn the total byte counter on. This will display the total amount
|
||||
of data transferred so far.
|
||||
|
||||
**-8, \--bits**
|
||||
|
||||
: Display the total bits instead of the total bytes. The output suffix
|
||||
will be \"b\" instead of \"B\".
|
||||
|
||||
**-T, \--buffer-percent**
|
||||
|
||||
: Turn on the transfer buffer percentage display. This will show the
|
||||
percentage of the transfer buffer in use - but see the caveat under
|
||||
**%T** in the **FORMATTING** section below. Implies **-C**.
|
||||
|
||||
**-A NUM, \--last-written NUM**
|
||||
|
||||
: Show the last *NUM* bytes written - but see the caveat under **%nA**
|
||||
in the **FORMATTING** section below. Implies **-C**.
|
||||
|
||||
**-F FORMAT, \--format FORMAT**
|
||||
|
||||
: Ignore the options **-p**, **-t**, **-e**, **-r**, **-a**, **-b**,
|
||||
**-T**, and **-A**, and instead use the format string *FORMAT* to
|
||||
determine the output format. See the **FORMATTING** section below.
|
||||
|
||||
**-n, \--numeric**
|
||||
|
||||
: Numeric output. Instead of giving a visual indication of progress,
|
||||
**pv** will give an integer percentage, one per line, on standard
|
||||
error, suitable for piping (via convoluted redirection) into
|
||||
**dialog**(1). Note that **-f** is not required if **-n** is being
|
||||
used.
|
||||
|
||||
: Note that if **\--numeric** is in use, then adding **\--bytes** will
|
||||
cause the number of bytes processed so far to be output instead of a
|
||||
percentage; if **\--line-mode** is also in use as well as
|
||||
**\--bytes** and **\--numeric**, then instead of bytes or a
|
||||
percentage, the number of lines so far is output. And finally, if
|
||||
**\--timer** is added to **\--numeric**, then each output line is
|
||||
prefixed with the elapsed time so far, as a decimal number of
|
||||
seconds.
|
||||
|
||||
**-q, \--quiet**
|
||||
|
||||
: No output. Useful if the **-L** option is being used on its own to
|
||||
just limit the transfer rate of a pipe.
|
||||
|
||||
# OUTPUT MODIFIERS
|
||||
|
||||
**-W, \--wait**
|
||||
|
||||
: Wait until the first byte has been transferred before showing any
|
||||
progress information or calculating any ETAs. Useful if the program
|
||||
you are piping to or from requires extra information before it
|
||||
starts, eg piping data into **gpg**(1) or **mcrypt**(1) which
|
||||
require a passphrase before data can be processed.
|
||||
|
||||
**-D SEC, \--delay-start SEC**
|
||||
|
||||
: Wait until *SEC* seconds have passed before showing any progress
|
||||
information, for example in a script where you only want to show a
|
||||
progress bar if it starts taking a long time. Note that this can be
|
||||
a decimal such as 0.5.
|
||||
|
||||
**-s SIZE, \--size SIZE**
|
||||
|
||||
: Assume the total amount of data to be transferred is *SIZE* bytes
|
||||
when calculating percentages and ETAs. The same suffixes of \"k\",
|
||||
\"m\" etc can be used as with **-L**.
|
||||
|
||||
: If *SIZE* starts with **@**, the size of file whose name follows the
|
||||
**@** will be used.
|
||||
|
||||
: Note that **\--size** has no effect if used with **-d ***PID* to
|
||||
watch all file descriptors of a process, but will work with **-d
|
||||
PID:FD**.
|
||||
|
||||
**-l, \--line-mode**
|
||||
|
||||
: Instead of counting bytes, count lines (newline characters). The
|
||||
progress bar will only move when a new line is found, and the value
|
||||
passed to the **-s** option will be interpreted as a line count.
|
||||
|
||||
: If this option is used without **-s**, the \"total size\" (in this
|
||||
case, total line count) is calculated by reading through all input
|
||||
files once before transfer starts. If any inputs are pipes or
|
||||
non-regular files, or are unreadable, the total size will not be
|
||||
calculated.
|
||||
|
||||
**-0, \--null**
|
||||
|
||||
: Count lines as terminated with a zero byte instead of with a
|
||||
newline. This option implies \--line-mode.
|
||||
|
||||
**-i SEC, \--interval SEC**
|
||||
|
||||
: Wait *SEC* seconds between updates. The default is to update every
|
||||
second. Note that this can be a decimal such as 0.1.
|
||||
|
||||
**-m SEC, \--average-rate-window SEC**
|
||||
|
||||
: Compute current average rate over a *SEC* seconds window for average
|
||||
rate and ETA calculations (default 30 seconds).
|
||||
|
||||
**-w WIDTH, \--width WIDTH**
|
||||
|
||||
: Assume the terminal is *WIDTH* characters wide, instead of trying to
|
||||
work it out (or assuming 80 if it cannot be guessed). If this option
|
||||
is used, the output width will not be adjusted if the width of the
|
||||
terminal changes while the transfer is running.
|
||||
|
||||
**-H HEIGHT, \--height HEIGHT**
|
||||
|
||||
: Assume the terminal is *HEIGHT* rows high, instead of trying to work
|
||||
it out (or assuming 25 if it cannot be guessed). If this option is
|
||||
used, the output height will not be adjusted if the height of the
|
||||
terminal changes while the transfer is running.
|
||||
|
||||
**-N NAME, \--name NAME**
|
||||
|
||||
: Prefix the output information with *NAME*. Useful in conjunction
|
||||
with **-c** if you have a complicated pipeline and you want to be
|
||||
able to tell different parts of it apart.
|
||||
|
||||
**-f, \--force**
|
||||
|
||||
: Force output. Normally, **pv** will not output any visual display if
|
||||
standard error is not a terminal. This option forces it to do so.
|
||||
|
||||
**-c, \--cursor**
|
||||
|
||||
: Use cursor positioning escape sequences instead of just using
|
||||
carriage returns. This is useful in conjunction with **-N** (name)
|
||||
if you are using multiple **pv** invocations in a single, long,
|
||||
pipeline.
|
||||
|
||||
# DATA TRANSFER MODIFIERS
|
||||
|
||||
**-L RATE, \--rate-limit RATE**
|
||||
|
||||
: Limit the transfer to a maximum of *RATE* bytes per second. A suffix
|
||||
of \"K\", \"M\", \"G\", or \"T\" can be added to denote kibibytes
|
||||
(\*1024), mebibytes, and so on.
|
||||
|
||||
**-B BYTES, \--buffer-size BYTES**
|
||||
|
||||
: Use a transfer buffer size of *BYTES* bytes. A suffix of \"K\",
|
||||
\"M\", \"G\", or \"T\" can be added to denote kibibytes (\*1024),
|
||||
mebibytes, and so on. The default buffer size is the block size of
|
||||
the input file\'s filesystem multiplied by 32 (512KiB max), or
|
||||
400KiB if the block size cannot be determined. This can be useful on
|
||||
platforms like MacOS which perform better in pipelines with specific
|
||||
buffer sizes such as 1024. Implies **-C**.
|
||||
|
||||
**-C, \--no-splice**
|
||||
|
||||
: Never use **splice**(2), even if it would normally be possible. The
|
||||
**splice**(2) system call is a more efficient way of transferring
|
||||
data from or to a pipe than regular **read**(2) and **write**(2),
|
||||
but means that the transfer buffer may not be used. This prevents
|
||||
**-A** and **-T** from working, cannot work with **-X**, and makes
|
||||
**-B** redundant, so using **-A**, **-T**, **-X**, or **-B**
|
||||
automatically switches on **-C**. Switching on **-C** results in a
|
||||
small loss of transfer efficiency. (This option has no effect on
|
||||
systems where **splice**(2) is unavailable).
|
||||
|
||||
**-E, \--skip-errors**
|
||||
|
||||
: Ignore read errors by attempting to skip past the offending
|
||||
sections. The corresponding parts of the output will be null bytes.
|
||||
At first only a few bytes will be skipped, but if there are many
|
||||
errors in a row then the skips will move up to chunks of 512. This
|
||||
is intended to be similar to **dd conv=sync,noerror** but has not
|
||||
been as thoroughly tested.
|
||||
|
||||
: Specify **-E** twice to only report a read error once per file,
|
||||
instead of reporting each byte range skipped.
|
||||
|
||||
**-Z BYTES, \--error-skip-block BYTES**
|
||||
|
||||
: When ignoring read errors with **-E**, instead of trying to
|
||||
adaptively skip by reading small amounts and skipping progressively
|
||||
larger sections until a read succeeds, move to the next file block
|
||||
of *BYTES* bytes as soon as an error occurs. There may still be some
|
||||
shorter skips where the block being skipped coincides with the end
|
||||
of the transfer buffer.
|
||||
|
||||
: This option can only be used with **-E** and is intended for use
|
||||
when reading from a block device, such as **-E -Z 4K** to skip in 4
|
||||
kibibyte blocks. This will speed up reads from faulty media, at the
|
||||
expense of potentially losing more data.
|
||||
|
||||
**-S, \--stop-at-size**
|
||||
|
||||
: If a size was specified with **-s**, stop transferring data once
|
||||
that many bytes have been written, instead of continuing to the end
|
||||
of input.
|
||||
|
||||
**-Y, \--sync**
|
||||
|
||||
: After every write operation, synchronise the buffer caches to disk -
|
||||
see **fdatasync**(2). This has no effect when the output is a pipe.
|
||||
Using **-Y** may improve the accuracy of the progress bar when
|
||||
writing to a slow disk.
|
||||
|
||||
**-K, \--direct-io**
|
||||
|
||||
: Set the **O_DIRECT** flag on all inputs and outputs, if it is
|
||||
available. This will minimise the effect of caches, at the cost of
|
||||
performance. Due to memory alignment requirements, it also may cause
|
||||
read or write failures with an error of \"Invalid argument\",
|
||||
especially if reading and writing files across a variety of
|
||||
filesystems in a single **pv** call. Use this option with caution.
|
||||
|
||||
**-X, \--discard**
|
||||
|
||||
: Instead of transferring input data to standard output, discard it.
|
||||
This is equivalent to redirecting standard output to */dev/null*,
|
||||
except that **write**(2) is never called. Implies **-C**.
|
||||
|
||||
**-d PID\[:FD\], \--watchfd PID\[:FD\]**
|
||||
|
||||
: Instead of transferring data, watch file descriptor *FD* of process
|
||||
*PID*, and show its progress. The **pv** process will exit when *FD*
|
||||
either changes to a different file, changes read/write mode, or is
|
||||
closed; other data transfer modifiers - and remote control - may not
|
||||
be used with this option.
|
||||
|
||||
: If only a *PID* is specified, then that process will be watched, and
|
||||
all regular files and block devices it opens will be shown with a
|
||||
progress bar. The **pv** process will exit when process *PID* exits.
|
||||
|
||||
**-R PID, \--remote PID**
|
||||
|
||||
: If *PID* is an instance of **pv** that is already running, **-R
|
||||
***PID* will cause that instance to act as though it had been given
|
||||
this instance\'s command line instead. For example, if **pv -L
|
||||
123K** is running with process ID 9876, then running **pv -R 9876 -L
|
||||
321K** will cause it to start using a rate limit of 321KiB instead
|
||||
of 123KiB. Note that some options cannot be changed while running,
|
||||
such as **-c**, **-l**, **-f**, **-D**, **-E**, and **-S**.
|
||||
|
||||
# GENERAL OPTIONS
|
||||
|
||||
**-P FILE, \--pidfile FILE**
|
||||
|
||||
: Save the process ID of **pv** in *FILE*. The file will be replaced
|
||||
if it already exists, and will be removed when **pv** exits. While
|
||||
**pv** is running, it will contain a single number - the process ID
|
||||
of **pv** - followed by a newline.
|
||||
|
||||
**-h, \--help**
|
||||
|
||||
: Print a usage message on standard output and exit successfully.
|
||||
|
||||
**-V, \--version**
|
||||
|
||||
: Print version information on standard output and exit successfully.
|
||||
|
||||
# FORMATTING
|
||||
|
||||
If the **-F** option is given, then the output format is determined by
|
||||
the given format string. Within that string, the following sequences can
|
||||
be used:
|
||||
|
||||
**%p**
|
||||
|
||||
: Progress bar. Expands to fill the remaining space. Should only be
|
||||
specified once. Equivalent to **-p**.
|
||||
|
||||
**%t**
|
||||
|
||||
: Elapsed time. Equivalent to **-t**.
|
||||
|
||||
**%e**
|
||||
|
||||
: ETA as time remaining. Equivalent to **-e**.
|
||||
|
||||
**%I**
|
||||
|
||||
: ETA as local time of completion. Equivalent to **-I**.
|
||||
|
||||
**%r**
|
||||
|
||||
: Current data transfer rate. Equivalent to **-r**.
|
||||
|
||||
**%a**
|
||||
|
||||
: Average data transfer rate. Equivalent to **-a**.
|
||||
|
||||
**%b**
|
||||
|
||||
: Bytes transferred so far (or lines if **-l** was specified).
|
||||
Equivalent to **-b**. If **\--bits** was specified, **%b** shows the
|
||||
bits transferred so far, not bytes.
|
||||
|
||||
**%T**
|
||||
|
||||
: Percentage of the transfer buffer in use. Equivalent to **-T**.
|
||||
Shows \"{\-\-\--}\" if the transfer is being done with
|
||||
**splice**(2), since splicing to or from pipes does not use the
|
||||
buffer.
|
||||
|
||||
**%nA**
|
||||
|
||||
: Show the last **n** bytes written (e.g. **%16A** for the last 16
|
||||
bytes). Shows only dots if the transfer is being done with
|
||||
**splice**(2), since splicing to or from pipes does not use the
|
||||
buffer.
|
||||
|
||||
**%N**
|
||||
|
||||
: Name prefix given by **-N**. Padded to 9 characters with spaces, and
|
||||
suffixed with :.
|
||||
|
||||
**%%**
|
||||
|
||||
: A single %.
|
||||
|
||||
The format string equivalent of turning on all display switches is
|
||||
**\`%N %b %T %t %r %a %p %e\'**.
|
||||
|
||||
# COMMON SWITCHES
|
||||
|
||||
Some suggested common switch combinations:
|
||||
|
||||
**pv -ptebar**
|
||||
|
||||
: Show a progress bar, elapsed time, estimated completion time, byte
|
||||
counter, average rate, and current rate.
|
||||
|
||||
**pv -betlap**
|
||||
|
||||
: Show a progress bar, elapsed time, estimated completion time, line
|
||||
counter, and average rate, counting lines instead of bytes.
|
||||
|
||||
**pv -t**
|
||||
|
||||
: Show only the elapsed time - useful as a simple timer, e.g. **sleep
|
||||
10m \| pv -t**.
|
||||
|
||||
**pv -pterb**
|
||||
|
||||
: The default behaviour: progress bar, elapsed time, estimated
|
||||
completion time, current rate, and byte counter.
|
||||
|
||||
On MacOS, it may be useful to specify **-B 1024** in a pipeline, as this
|
||||
may improve performance.
|
||||
|
||||
# EXIT STATUS
|
||||
|
||||
An exit status of 1 indicates a problem with the **-R** or **-P**
|
||||
options.
|
||||
|
||||
Any other exit status is a bitmask of the following:
|
||||
|
||||
**2**
|
||||
|
||||
: One or more files could not be accessed, **stat**(2)ed, or opened.
|
||||
|
||||
**4**
|
||||
|
||||
: An input file was the same as the output file.
|
||||
|
||||
**8**
|
||||
|
||||
: Internal error with closing a file or moving to the next file.
|
||||
|
||||
**16**
|
||||
|
||||
: There was an error while transferring data from one or more input
|
||||
files.
|
||||
|
||||
**32**
|
||||
|
||||
: A signal was caught that caused an early exit.
|
||||
|
||||
**64**
|
||||
|
||||
: Memory allocation failed.
|
||||
|
||||
A zero exit status indicates no problems.
|
||||
|
||||
# AUTHOR
|
||||
|
||||
Written by Andrew Wood, with patches submitted by various other people.
|
||||
Please see the package\'s ACKNOWLEDGEMENTS file for a complete list of
|
||||
contributors.
|
||||
|
||||
# KNOWN PROBLEMS
|
||||
|
||||
The following problems are known to exist in **pv**:
|
||||
|
||||
**\***
|
||||
|
||||
: In some versions of **bash**(1) and **zsh**(1), the construct
|
||||
**\<(pv filename)** will not output any progress to the terminal
|
||||
when run from an interactive shell, due to the subprocess being run
|
||||
in a separate process group from the one that owns the terminal. In
|
||||
these cases, use **\--force**.
|
||||
|
||||
|
||||
**\***
|
||||
|
||||
: The **-c** option does not work properly on Cygwin without
|
||||
**cygserver** running, if started near the bottom of the screen (IPC
|
||||
is needed to handle the terminal scrolling). To fix this, start
|
||||
**cygserver** before using **pv -c**.
|
||||
|
||||
|
||||
**\***
|
||||
|
||||
: The **-R** option is not available on Cygwin without **cygserver**
|
||||
running (SYSV IPC is needed). To fix this, start **cygserver**
|
||||
before running the instance of **pv** you want, at runtime, to
|
||||
change the parameters of.
|
||||
|
||||
If you find any other problems, please report them.
|
||||
|
||||
# REPORTING BUGS
|
||||
|
||||
Please report any bugs to: \<https://codeberg.org/a-j-wood/pv/issues\>
|
||||
|
||||
Alternatively, use the contact form linked from the **pv** home page:
|
||||
\<http://www.ivarch.com/programs/pv.shtml\>
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**cat**(1), **dialog**(1), **splice**(2), **open**(2) (for **O_DIRECT**)
|
||||
|
||||
# LICENSE
|
||||
|
||||
This is free software, distributed under the ARTISTIC 2.0 license.
|
||||
Reference in New Issue
Block a user