Command Line Progress Bar Files

NAME

  bar - show information about a data transfer


SYNOPSIS

  bar [-if <input-file>] [-of <output-file>] [-s <size>] 
      [-bs <buffer-size>] [-i <seconds>] [-k <1000|1024>] [-h] [-v]

  bar [--in-file <input-file>] [--out-file <output-file>] [--size <size>]
      [--buffer-size <buffer-size>] [--interval <seconds>] 
      [--kilo <1000|1024>] [--help] [--version]

DESCRIPTION

  Bar is a simple tool to process a stream of data and print a display for the
  user on stderr showing (a) the amount of data passed, (b) the throughput of
  the data transfer, and, if the total size of the data stream is known, (c)
  estimated time remaining, percent complete, and a progress bar.

  Bar was originally written for myself so that I could get an estimate of how
  long it would take to transfer large amounts (many, many gigabytes) of data
  across the network.  (I mostly use it when moving home directories from one
  host to another.)


OPTIONS

  -if <input-file>
  --in-file <input-file>
       Read input from <input-file>.  Default: stdin

  -of <output-file>
  --out-file <output-file>
       Write output to <output-file>.  Default: stdout

  -s <size>
  --size <size>
       Expect an input stream of <size> bytes.

       When reading a regular file or a link to a regular file, bar will
       extract the file size on it's own.  However, this flag is useful for
       reading from a character- or block-special device file, or from a pipe.
       <size> may be followed by 'k', 'm', 'g', or 't' for kilobytes, 
       megabytes, gigabytes, or terabytes, respectively.  (Notice: see the -k
       option below.)

  -bs <buffer-size>
  --buffer-size <buffer-size>
       Allocate an I/O buffer of <buffer-size> bytes.  The same modifiers
       may apply here ('k', 'm', 'g', and 't') as for the -s flag above.

  -i <seconds>
  --interval <seconds>
       Update the display every <seconds> seconds.

  -k <1000|1024>
  --kilo <1000|1024>
       Use either 1000 or 1024 as the definition of a kilobyte.  Default: 1024

  -h
  --help
       Display this text and exit.

  -v
  --version
       Display the program version and exit.


EXAMPLES

  Example 1: Using bar to copy a 2.4gb file from a device (in this case a tape
             drive) to a file, using a 64k buffer.

    prompt% bar --in-file /dev/rmt/1cbn --out-file ./tape-restore.tar \
    --size 2.4g --buffer-size 64k
  
  Example 2: Using bar to copy a 37tb file across the network using ssh.

    prompt% ssh remote 'dd if=file' | bar --size 37t > file
  
  Example 3: Using bar inside a tar-pipe command:

    Normal tar-pipe command might be:

      prompt% (cd /some/dir/somewhere && tar -cf - *) \
      | (cd /some/other/dir && tar -xBpf -)

    3a: Using bar within the tar-pipe:

      prompt% (cd /some/dir/somewhere && tar -cf - *) \
      | bar \
      | (cd /some/other/dir && tar -xBpf -)

    3b: Using bar with the --size option in a tar-pipe:

      prompt% du -sk /some/dir/somewhere
      6281954 /some/dir/somewhere

      prompt% (cd /some/dir/somewhere && tar -cf - *) \
      | bar --size 6281954k \
      | (cd /some/other/dir && tar -xBpf -)

  Example 4: Using bar on a regular file.  (Note that the --size option is not
             needed here, as bar will retrieve the file size itself.)

    prompt% bar --in-file ./file | ssh remote 'cd /some/dir && dd of=file'
  
  Example 5: Generating a 512k file of random data.

    prompt% dd if=/dev/random bs=1024 count=512 | bar -s 512k -of ./random


NOTES

  - The --size option is only used in calculating information about the data
    transfer.  Bar will not cease copying data once it has reached the number
    of bytes specified with the --size option, but instead bar will continue
    to copy data until and end of input is reached.  If this behavior is
    undesirable then bar may be used in conjunction with dd, where the count
    option is used with dd to specify when to cut off the input stream.  (See
    examples above.)

  - When using other command such as du -k to calculate the expected size of a
    data transfer stream, the value returned may not be exactly the number of
    bytes counted by bar in the actual data transfer.  Common causes for this
    discrepancy could be attributed to round-off error or the use of 1000
    bytes as a kilobyte rather than 1024.  (If the later is the case, then
    using the -k 1000 option to bar will help.)  When such discrepancies
    occur, bar may report that the data stream contained only 98% or as much
    as 101% of it's expected size.  (If you have doubts, you should definitely
    verify your data using md5sum, diff, or cmp.)
  
  - When the value of a calculation exceeds the size alloted for the display,
    the value +99... will be substituted in it's place.  The complete value
    will be displayed in a summary statement after bar has reached the end of
    input.
  
  - Bar assumes a display width of 80 characters.

  - The type unsigned long long is used internally by bar for calculations,
    therefore your compiler must be able to support unsigned long long as a
    valid type.

  - The function fstat() is used to read the size of regular files, which
    returns the file size as the type off_t.  Some operating systems may not
    be able to handle large files (such as files in excess of 8gb) properly.
    Such circumstances may cause bar to generate an erratic or erroneous
    statistics in it's display.  If this happens, try specifying the file size
    using the --size command line flag.  (But be sure to specify --size
    after specifying the input file, or the value returned by fstat() will
    replace the size you gave on the command line.)

  - Bar uses unsigned long long for --size, and size_t for --buffer-size.  (On
    a Solaris 8 workstation, bar can handle --size up to 2400000t and
    --buffer-size up to 3.99g.  (Why you would want a buffer size that large
    is beyond me, but bar will do it.))


BUGS/PORTS

  - Minor bug fixes to the display algorithms.  Once again, there are no known
    bugs at the time of this writing. :)

  - Bar was developed on a Sun workstation running Solaris 8.  To the best of
    the author's knowledge bar should compile and run on other platforms
    without much trouble.  Should other OS's require modifications to the
    code, the author welcomes all patch submissions, but requests that you
    include the file config.log and the output of "gcc -dumpspecs" (or a
    listing of predefined variables, if not using gcc).