| blob | a9a7a64164687418ccfd72d10f387aba0d1eb3b2 |
1 .\" $NetBSD: progress.1,v 1.13 2007/06/06 17:49:14 briggs Exp $
2 .\"
3 .\" Copyright (c) 2003-2007 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by John Hawkinson.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd June 6, 2007
31 .Dt PROGRESS 1
32 .Os
33 .Sh NAME
34 .Nm progress
35 .Nd feed input to a command, displaying a progress bar
36 .Sh SYNOPSIS
37 .Nm
38 .Op Fl ez
39 .Op Fl b Ar buffersize
40 .Op Fl f Ar file
41 .Op Fl l Ar length
42 .Op Fl p Ar prefix
43 .Ar cmd
44 .Op Ar args ...
45 .Sh DESCRIPTION
46 The
47 .Nm
48 utility opens a pipe to
49 .Ar cmd
50 and feeds an input stream into it, while displaying a progress bar to
51 standard output.
52 If no filename is specified,
53 .Nm
54 reads from standard input.
55 Where feasible,
56 .Nm
57 .Xr fstat 2 Ns s
58 the input to determine the length, so a time estimate can be calculated.
59 .Pp
60 If no length is specified or determined,
61 .Nm
62 simply displays a count of the data and the data rate.
63 .Pp
64 The options are as follows:
65 .Bl -tag -width XlXlengthXX
66 .It Fl b Ar buffersize
67 Read in buffers of the specified size (default 64k).
68 An optional suffix (per
69 .Xr strsuftoll 3 )
70 may be given.
71 .It Fl e
72 Display progress to standard error instead of standard output.
73 .It Fl f Ar file
74 Read from the specified
75 .Ar file
76 instead of standard input.
77 .It Fl l Ar length
78 Use the specified length for the time estimate, rather than attempting to
79 .Xr fstat 2
80 the input.
81 An optional suffix (per
82 .Xr strsuftoll 3 )
83 may be given.
84 .It Fl p Ar prefix
85 Print the given
86 .Dq prefix
87 text before (left of) the progress bar.
88 .It Fl z
89 Filter the input through
90 .Xr gunzip 1 .
91 If
92 .Fl f
93 is specified, calculate the length using
94 .Ic gzip -l .
95 .El
96 .Sh EXIT STATUS
97 .Nm
98 exits 0 on success.
99 .Sh EXAMPLES
100 The command
101 .Dl progress -zf file.tar.gz tar xf -
102 will extract the
103 .Pa file.tar.gz
104 displaying the progress bar as time passes:
105 .Bd -literal
106 0% | | 0 0.00 KiB/s --:-- ETA
107 40% |******** | 273 KiB 271.95 KiB/s 00:01 ETA
108 81% |*********************** | 553 KiB 274.61 KiB/s 00:00 ETA
109 100% |*******************************| 680 KiB 264.59 KiB/s 00:00 ETA
110 .Ed
111 .Pp
112 If it is preferred to monitor the progress of the decompression
113 process (unlikely), then
114 .Dl progress -f file.tar.gz tar zxf -
115 could be used.
116 .Pp
117 The command
118 .Dl dd if=/dev/rwd0d ibs=64k | \e
119 .Dl progress -l 120g dd of=/dev/rwd1d obs=64k
120 will copy the 120 GiB disk
121 .Sy wd0
122 .Pa ( /dev/rwd0d )
123 to
124 .Sy wd1
125 .Pa ( /dev/rwd1d ) ,
126 displaying a progress bar during the operation.
127 .Sh SEE ALSO
128 .Xr ftp 1 ,
129 .Xr strsuftoll 3
130 .Sh HISTORY
131 .Nm
132 first appeared in
133 .Nx 1.6.1 .
134 The dynamic progress bar display code is part of
135 .Xr ftp 1 .
136 .Sh AUTHORS
137 .Nm
138 was written by
139 .An John Hawkinson
140 .Aq jhawk@NetBSD.org .
141 .Xr ftp 1 Ns 's
142 dynamic progress bar was written by Luke Mewburn.
143 .Sh BUGS
144 Since the progress bar is displayed asynchronously, it may be
145 difficult to read some error messages, both those produced by the
146 pipeline, as well as those produced by
147 .Nm
148 itself.