bar - Online in the Cloud

PROGRAM:

NAME

bar - show information about a data transfer

SYNOPSIS

bar [ I/O-options ] [ display-options ] [ color-options ]
[ input-file ] [ output-file ]
[ -h | --help ] [ -v | --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 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.)

I/O COMMAND LINE 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. If the output file is a directory, then bar will attempt to
create a file in the output directory with the same name as the input file, and attempt
to copy the input file mode as well as it's data. Default: stdout

Please notice that if no -if, --in-file, -of, or --out-file options are specified on the
command line, and an unknown command line option is encountered, then bar will assume that
the first unknown command line option is a path to an input file, and the second (if
found) is a path to an output file.

-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.

-c size
--completed size

Instruct bar that size bytes of the data stream have already been copied, and that this
is a continuation of a previous data stream. Note that use of this option will throw
off throughput and ETA calculations at first, but they should settle down as the
transfer continues.

-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

DISPLAY COMMAND LINE OPTIONS

-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.

-sh height
--screen-height height

Assume a screen height of height characters.

Bar will attempt to retrieve the height of the terminal it is running on, and will
adjust that height if the terminal is resized. If bar cannot determine the terminal
height, then bar will assume a default height of 23 characters. Use the --screen-height
command line option to override this behavior and specify a fixed height 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.)

Please note that this option is only useful when used in conjunction with the --info-
file command line option. Otherwise bar has no need to know the screen height in order
to perform it's function.

-sh-1 | --screen-height-minus-one
-sh-0 | --screen-height-minus-zero

Instruct bar to use either the entire row height 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 24 rows characters high, using the command line option --screen-height-minus-one
instructs bar to only use 23 rows 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 height.

Please note that this option is only useful when used in conjunction with the --info-
file command line option. Otherwise bar has no need to know the screen height in order
to perform it's function.

-ti string | --title string
Set the title to string.

-dti | -nti
--display-title | --no-title
Turn on/off the title display. Even if on, if no title string is set then no title will
be displayed. Default is on.

-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
Display the data count at bits instead of as bytes. Default is off.

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
Display throughput as bits/second instead of as bytes/second. Default is off.

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.

-inf infofile | --info-file infofile

Display the information contained in infofile while copying data. The file infofile is
a regular text file containing tidbits of information broken up into sections. Each
section is separated by a line containing the string "@@@" by itself, with no other
characters on the line, either preceeding or following.

When bar begins, it will count the number of sections within the file. Bar will then
begin by displaying the first section of information to the display before it draws the
status line. Then, periodically, each of the successive sections will be displayed as
the progress indicator fills up.

The progress of the data transfer is the trigger for each successive display. For
instance, if your information file has exactly four sections to it, then the first
section will be printed as bar begins, the second section after the data transfer hits
25%, the third at 50%, and the fourth at 75%.

If bar is configured to use ANSI control codes, then the screen will be cleared before
printing a section from the information file. Otherwise, the contents of the current
screen are scolled up and off the screen.

-dnum | --display-numeric

Do not render the usual display, but instead display an integer representing the percent
of the transfer that is complete, one integer per line. This output is suitable for
piping to other programs such as dialog(1) or zenity(1). This implies that the total
transfer size must be known by bar, either by finding the size of an input file directly
or by using the --size command line option.

-dw | --display-wait
Wait for the first byte of data to come through before displaying anything.

COLOR COMMAND LINE OPTIONS

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

-bobc | --bar-openbrace-char char

char as the open brace character on the progress bar.

-bcbc | --bar-closebrace-char char

char as the close brace character on the progress bar.

-bcc | --bar-complete-char char

char as the completed character on the progress bar.

-bic | --bar-incomplete-char char

char as the incomplete character on the progress bar.

-h | --help

Display this text and exit.

-v | --version

Display the program version and exit.

RESOURCE FILE OPTIONS

Some command line options may be specified in a resource file. Bar will search for a
resource file by the name of /etc/clpbarrc and, if found, bar will use the values within
by default. Next bar will search for ~/.barrc and, if found, bar will use these values to
override any values set within /etc/clpbarrc. Last, bar will search for a file in the
current working directory named ./.barrc. If this file exists, it's values will override
the values found in ~/.barrc or /etc/clpbarrc. Values in all 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
When parsing sizes specified in terms of blocks, assume a single block is size bytes.
See the --block-size command line option above.

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.

info-file: infofile
Display the information contained in infofile while copying data. The file infofile is
a regular text file containing tidbits of information broken up into sections. Each
section is separated by a line containing the string "@@@" by itself, with no other
characters on the line, either preceeding or following.

When bar begins, it will count the number of sections within the file. Bar will then
begin by displaying the first section of information to the display before it draws the
status line. Then, periodically, each of the successive sections will be displayed as
the progress indicator fills up.

The progress of the data transfer is the trigger for each successive display. For
instance, if your information file has exactly four sections to it, then the first
section will be printed as bar begins, the second section after the data transfer hits
25%, the third at 50%, and the fourth at 75%.

If bar is configured to use ANSI control codes, then the screen will be cleared before
printing a section from the information file. Otherwise, the contents of the current
screen are scolled up and off the screen.

display-numeric: boolean
Do not render the usual display, but instead display an integer representing the percent
of the transfer that is complete, one integer per line. This output is suitable for
piping to other programs such as dialog(1) or zenity(1). This implies that the total
transfer size must be known by bar, either by finding the size of an input file directly
or by using the --size command line option.

display-wait: boolean
Wait for the first byte of data to come through before displaying anything.

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
Use the specified colors for the foreground and background of the progress bar, and use
a bold font. See the --bar-foreground, --bar-background, and --bar-bold command line
options above.

bar-openbrace-char: char
bar-closebrace-char: char
bar-complete-char: char
bar-incomplete-char:
Use the specified custom characters char for the opening brace, closing brace,
completed, and incomplete characters when rendering the progress bar.

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

Example 6: An example .barrc file.
#
# This is an example of what a ~/.barrc file
# might look like. Note that lines beginning
# with a # are ignored.
#
display-twiddle: no
display-ansi: yes
# space-background: black
twiddle-foreground: green
# twiddle-background: normal
# twiddle-bold: no
count-foreground: green
# count-background: magenta
count-bold: yes
throughput-label-foreground: normal
# throughput-label-background: red
throughput-label-bold: no
throughput-foreground: green
# throughput-background: black
throughput-bold: yes
time-label-foreground: normal
# time-label-background: red
time-label-bold: no
time-foreground: green
# time-background: black
time-bold: yes
percent-foreground: green
# percent-background: green
percent-bold: yes
bar-brace-foreground: red
# bar-brace-background: blue
bar-brace-bold: no
bar-foreground: yellow
# bar-background: blue
bar-bold: yes

NOTES

- The --size option is only used by bar 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 commands 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 linear relationship between the speed of the data transfer and the amount
of time remaining. Specifically the calculation is based on the following:

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.

- Bar assumes that there are 8 bits in both a byte and a char.

Use bar online using onworks.net services