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 the purpose of estimating the amount of time needed to transfer large amounts (many, many gigabytes) of data across a network. (Usually in an SSH/tar pipe.)
-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', 't', 'p', or 'e' for kilobytes, megabytes, gigabytes, terabytes, petabytes, or exabytes, respectively (see also the -k option below). Alternatively, size may also be specified in terms of 'b' for blocks (see the -bl option below). See examples 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', 't', 'p', 'e' and 'b') as for the -s flag above. Changing the buffer size can improve throughput, depending on your application of bar. For fast I/O operations, say from a ramdisk for instance, it might be worth your while to experiment with a large buffer (circa 1MB for instance). But for slow I/O operations, like from a tape drive, you could merely be wasting your memory. Default: 52488 (512KB)
-th
rate
--throttle
rate
Restrict I/O throughput to rate bytes per second. The same modifiers apply here ('k', 'm', 'g', 't', 'p', 'e' and 'b') as for the -s flag above.
-i
seconds
--interval
seconds
Update the display every seconds seconds. Default: 1 second
-t
microseconds
--timeout
microseconds
The number of microseconds to wait for a change in I/O state before select() times out. Default: 250000 (1/4 second)
-k
1000|1024
--kilo
1000|1024
Use either 1000 or 1024 as the definition of a kilobyte. Default: 1024
-bl
size
--block-size
size
When reading sizes from the command line that are specified in terms of blocks, assume a single block is size bytes. Size may be followed by 'k', 'm', 'g', 't', 'p', or 'e' for kilobytes, megabytes, gigabytes, terabytes, petabytes, or exabytes, respectively. Block size must be set before specifying any sizes in terms of blocks or the default value will be used instead. Specifying size in terms of 'b' for blocks is not allowed for this option. Default: 512
-sw
width
--screen-width
width
Assume a screen width of width characters.
Bar will attempt to retrieve the width of the terminal it is running on, and will adjust that width if the terminal is resized. If bar cannot determine the terminal width, then bar will assume a default width of 79 characters. Use the --screen-width command line option to override this behavior and specify a fixed width for bar to use. (When this option is used, bar will ignore terminal resized signals and continue to use the value provided by the user.)
-sw-1
|
--screen-width-minus-one
-sw-0
|
--screen-width-minus-zero
Instruct bar to use either the entire column width reported by termio, or one less than reported by termio. I.e. If termio reports that you are running bar in a terminal that's 80 characters wide, using the command line option --screen-width-minus-one instructs bar to only use 79 characters to print the display. If you're using a terminal or shell that wraps the line whenever bar prints the last character then this should alleviate that problem. Default is to use the full terminal's width.
-ti
string
|
--title
string
-dti
|
-nti
--display-title
|
--no-title
-dtw
|
--display-twiddle
-ntw
|
--no-twiddle
Turn on/off the twiddle in the display.
-dc
|
--display-count
-nc
|
--no-count
Turn on/off the data count in the display. Default is on.
-dcb
|
-ncb
--display-count-bits
|
--no-count-bits
By default bar will display the data count as bytes using the notation of "B". Using this option, bar will display the throughput as bits using the notation of "b".
-dth
|
--display-throughput
-nth
|
--no-throughput
Turn on/off the data throughput in the display. Default is on.
-dthb
|
-nthb
--display-throughput-bits
|
--no-throughput-bits
By default bar will display the throughput as bytes/second using the notation of "B/s". Using this option, bar will display the throughput as bits/second using the notation of "b/s".
-dt
|
--display-time
-nt
|
--no-time
Turn on/off the time elapsed or eta in the display. Default is on.
-de
|
--display-elapsed-only
-ne
|
--no-elapsed-only
Force bar to display the elapsed time instead of the eta. Default is off.
-dp
|
--display-percent
-np
|
--no-percent
Turn on/off percent complete in the display. Default is on.
-db
|
--display-bar
-nb
|
--no-bar
Turn on/off the progress bar in the display. Default is on.
-ds
|
--display-summary
-ns
|
--no-summary
Turn on/off the summary information displayed when the operation is complete. Default is on.
-da
|
--display-all
-dn
|
--display-none
Turn on/off all displays. -dn is equivalent to -ntw -nc -nth -nt -np -nb. (Using -dn followed by -db would be equivalent to -ntw -nc -nth -nt -np.) -da is equivalent to -dtw -dc -dth -dt -dp -db.
For the following color-specific command line options, the following keywords are recognized as valid color names: normal, black, red, green, yellow, blue, magenta, cyan, and white
-dan
|
--display-ansi
-nan
|
--no-ansi
Turn on/off the use of ansi color codes in the display.
-spbg
color
|
--space-background
color
Use color as the background color for spacing between display objects. Default: normal
-twfg
color
|
--twiddle-foreground
color
-twbg
color
|
--twiddle-background
color
Use color as the twiddle color in the display. Default: normal
-twb
|
--twiddle-bold
-twn
|
--twiddle-normal
Turn on/off the use of bold font when displaying the twiddle. Default off
-tifg
color
|
--title-foreground
color
-tibg
color
|
--title-background
color
Use color as the title color in the display. Default: normal
-tib
|
--title-bold
-tin
|
--title-normal
Turn on/off the use of bold font when displaying the title. Default off
-cfg
color
|
--count-foreground
color
-cbg
color
|
--count-background
color
Use color as the data count color in the display. Default: normal
-cb
|
--count-bold
-cn
|
--count-normal
Turn on/off the use of bold font when displaying the data count. Default off
-thlfg
color
|
--throughput-label-foreground
color
-thlbg
color
|
--throughput-label-background
color
Use color as the throughput label color in the display. Default: normal
-thlb
|
--throughput-label-bold
-thln
|
--throughput-label-normal
Turn on/off the use of bold font when displaying the throughput label. Default off
-thfg
color
|
--throughput-foreground
color
-thbg
color
|
--throughput-background
color
Use color as the throughput color in the display. Default: normal
-thb
|
--throughput-bold
-thn
|
--throughput-normal
Turn on/off the use of bold font when displaying the throughput. Default off
-tlfg
color
|
--time-label-foreground
color
-tlbg
color
|
--time-label-background
color
Use color as the time label color in the display. Default: normal
-tlb
|
--time-label-bold
-tln
|
--time-label-normal
Turn on/off the use of bold font when displaying the time label. Default off
-tfg
color
|
--time-foreground
color
-tbg
color
|
--time-background
color
Use color as the time color in the display. Default: normal
-tb
|
--time-bold
-tn
|
--time-normal
Turn on/off the use of bold font when displaying the time. Default off
-pfg
color
|
--percent-foreground
color
-pbg
color
|
--percent-background
color
Use color as the percent color in the display. Default: normal
-pb
|
--percent-bold
-pn
|
--percent-normal
Turn on/off the use of bold font when displaying the percent. Default off
-bbfg
color
|
--bar-brace-foreground
color
-bbbg
color
|
--bar-brace-background
color
Use color as the brace color around the progress bar in the display. Default: normal
-bbb
|
--bar-brace-bold
-bbn
|
--bar-brace-normal
Turn on/off the use of bold font when displaying the bar braces. Default off
-bfg
color
|
--bar-foreground
color
-bbg
color
|
--bar-background
color
Use color as the color of the progress bar in the display. Default: normal
-bb
|
--bar-bold
-bn
|
--bar-normal
Turn on/off the use of bold font when displaying the progress bar. Default off
-h
|
--help
Display this text and exit.
-v
|
--version
Display the program version and exit.
Some command line options may be specified in a resource file. Bar will search for a resource file by the name of ~/.barrc and, if found, bar will use the values within by default. In addition, bar will also search for a file in the directory in which it is run, ./.barrc. If this file exists, it's values will override the values found in ~/.barrc. Values in both files may be overridden by command line flags. Lines that begin with a # are ignored.
For resource options requiring a boolean value, the following values are recognized: on and off, yes and no, (and the single-character abbreviations y and n), true and false, (and the single-character abbreviations t and f), 0 and 1.
For resource options requiring a color value, the same keywords are recognized as for the color-specific command line options above: normal, black, red, green, yellow, blue, magenta, cyan, and white
buffer-size: buffer-size
Allocate an I/O buffer of buffer-size bytes. See the --buffer-size command line option above.
throttle: rate
Restrict I/O throughput to rate bytes per second. See the --throttle command line option above.
interval: seconds
Update the display every seconds seconds. See the --interval command line option above.
timeout: microseconds
The number of microseconds to wait for a change in I/O state before select() times out. See the --timeout command line option above.
kilobyte: 1000|1024
Use either 1000 or 1024 as the definition of a kilobyte. See the --kilo command line option above.
block-size: size
screen-width: width
Override termio and assume that the screen is width characters wide. See the --screen-width command line option above.
screen-width-minus-one:
boolean
Instruct bar to restrict the number of columns reported by termio by one. See the --screen-width-minus-one command line option above.
display-twiddle:
boolean
Instruct bar to turn on/off the twirling twiddle character in the display. See the --display-twiddle command line option above.
display-title:
boolean
Instruct bar to turn on/off the title in the display. See the --display-title command line option above.
display-count:
boolean
Instruct bar to turn on/off the data count in the display. See the --display-count command line option above.
display-count-bits:
boolean
Display the data count as bits instead of as bytes. See the --display-count-bits command line option above.
display-throughput:
boolean
Instruct bar to turn on/off the data throughput in the display. See the --display-throughput command line option above.
display-throughput-bits:
boolean
Display throughput as bits/sec instead of as bytes/sec. See the --display-throughput-bits command line option above.
display-time:
boolean
Instruct bar to turn on/off the time in the display. See the --display-time command line option above.
display-elapsed-only:
boolean
Force bar to display the elapsed time instead of the eta. See the --display-elapsed-only command line option above.
display-percent:
boolean
Instruct bar to turn on/off the percent complete in the display. See the --display-percent command line option above.
display-bar:
boolean
Instruct bar to turn on/off the progress bar in the display. See the --display-bar command line option above.
display-summary:
boolean
Instruct bar to turn on/off the summary information displayed when operation is complete. See the --display-summary command line option above.
display-ansi:
boolean
Instruct bar to turn on/off the use of ansi color codes in the display. See the --display-ansi command line option above.
space-background:
color
Use color as the background color for spacing between display objects. See the --space-background command line option above.
twiddle-foreground:
color
twiddle-background:
color
twiddle-bold:
boolean
Use the specified colors for the foreground and background of the twiddle, and use a bold font. See the --twiddle-foreground, --twiddle-background, and --twiddle-bold command line options above.
title:
string
Set the title string for the display. See the --title command line option above.
title-foreground:
color
title-background:
color
title-bold:
boolean
Use the specified colors for the foreground and background of the title, and use a bold font. See the --title-foreground, --title-background, and --title-bold command line options above.
count-foreground:
color
count-background:
color
count-bold:
boolean
Use the specified colors for the foreground and background of the data count, and use a bold font. See the --count-foreground, --count-background, and --count-bold command line options above.
throughput-label-foreground:
color
throughput-label-background:
color
throughput-label-bold:
boolean
Use the specified colors for the foreground and background of the throughput label, and use a bold font. See the --throughput-label-foreground, --throughput-label-background, and --throughput-label-bold command line options above.
throughput-foreground:
color
throughput-background:
color
throughput-bold:
boolean
Use the specified colors for the foreground and background of the throughput, and use a bold font. See the --throughput-foreground, --throughput-background, and --throughput-bold command line options above.
time-label-foreground:
color
time-label-background:
color
time-label-bold:
boolean
Use the specified colors for the foreground and background of the time label, and use a bold font. See the --time-label-foreground, --time-label-background, and --time-label-bold command line options above.
time-foreground:
color
time-background:
color
time-bold:
boolean
Use the specified colors for the foreground and background of the time, and use a bold font. See the --time-foreground, --time-background, and --time-bold command line options above.
percent-foreground:
color
percent-background:
color
percent-bold:
boolean
Use the specified colors for the foreground and background of the percent, and use a bold font. See the --percent-foreground, --percent-background, and --percent-bold command line options above.
bar-brace-foreground:
color
bar-brace-background:
color
bar-brace-bold:
boolean
Use the specified colors for the foreground and background of the brace surrounding the progress bar, and use a bold font. See the --bar-brace-foreground, --bar-brace-background, and --bar-brace-bold command line options above.
bar-foreground:
color
bar-background:
color
bar-bold:
boolean
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
Example 6: An example .barrc file.
elapsed time / eta = bytes written / total size
However, it has been the author's experience that the throughput speed will change, particularly at the beginning of the transfer, and this will affect the estimated time remaining. The author does not believe this is a bug, but a side-effect of this method of calculation.
When trying to open files greater than 2gb on an OS without Large File support, bar will exit with the message: "File too large". When trying to write more than 2gb of data to a file, bar will write 2**32-1 bytes and then the OS may terminate bar with a message similar to: "File size limit exceeded".
When trying to open files greater than 2gb on an OS without Large File support, but with the O_LARGEFILE option that can be passed to open(), bar will receive an error when trying to retrieve the file's size, but bar will be able to open the file anyway. Under these circumstances, bar will print a "File too large" error message, but will then proceed to transfer the data. Since bar will not be able to retrieve the file's size on it's own, the --size command line option must be used after the --in-file option to tell bar the file size manually. On such OS's, bar should be able to write more than 2gb of data to a file without any problems.
For OS's that support files greater than 2gb, either natively or through the Large File extension definitions mentioned above, bar should work as expected.
Report all bugs to the author.
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).
The latest version of bar can always be found at:
Bar was written by Michael Peek. See DISTRIBUTION above for contact information.
Occasionally, the author fancies that he knows what he's doing. It is at these times more than ever that his coworkers should cower in fear...