progress.1

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