progress.1

   1 .\"     $NetBSD: progress.1,v 1.15 2014/04/13 01:45:34 snj 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 .Ex -std
  98 .Sh EXAMPLES
  99 The command
 100 .Dl progress -zf file.tar.gz tar xf -
 101 will extract the
 102 .Pa file.tar.gz
 103 displaying the progress bar as time passes:
 104 .Bd -literal
 105   0% |                               |     0        0.00 KiB/s    --:-- ETA
 106  40% |********                       |   273 KiB  271.95 KiB/s    00:01 ETA
 107  81% |***********************        |   553 KiB  274.61 KiB/s    00:00 ETA
 108 100% |*******************************|   680 KiB  264.59 KiB/s    00:00 ETA
 109 .Ed
 110 .Pp
 111 If it is preferred to monitor the progress of the decompression
 112 process (unlikely), then
 113 .Dl progress -f file.tar.gz tar zxf -
 114 could be used.
 115 .Pp
 116 The command
 117 .Dl dd if=/dev/rwd0d ibs=64k | \e
 118 .Dl progress -l 120g dd of=/dev/rwd1d obs=64k
 119 will copy the 120 GiB disk
 120 .Sy wd0
 121 .Pa ( /dev/rwd0d )
 122 to
 123 .Sy wd1
 124 .Pa ( /dev/rwd1d ) ,
 125 displaying a progress bar during the operation.
 126 .Sh SEE ALSO
 127 .Xr ftp 1 ,
 128 .Xr strsuftoll 3
 129 .Sh HISTORY
 130 .Nm
 131 first appeared in
 132 .Nx 1.6.1 .
 133 The dynamic progress bar display code is part of
 134 .Xr ftp 1 .
 135 .Sh AUTHORS
 136 .Nm
 137 was written by
 138 .An John Hawkinson
 139 .Aq jhawk@NetBSD.org .
 140 .Xr ftp 1 Ns 's
 141 dynamic progress bar was written by Luke Mewburn.
 142 .Sh BUGS
 143 Since the progress bar is displayed asynchronously, it may be
 144 difficult to read some error messages, both those produced by the
 145 pipeline, as well as those produced by
 146 .Nm
 147 itself.