.TH CLPBAR 1 "4 November 2003"

.SH NAME

clpbar \- show information about a data transfer

.SH SYNOPSIS

.RS 0

.TP 4

.B clpbar

[

.I I/O-options

]

[

.I display-options

]

[

.I color-options

]

.br

[

.I input-file

]

[

.I output-file

]

.br

[

.B -h

|

.B --help

]

[

.B -v

|

.B --version

]

.RE

.SH DESCRIPTION

.PP

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

.PP

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

.SH I/O COMMAND LINE OPTIONS

.B -if

.I input-file

.br

.B --in-file

.I input-file

.br

.RS 2

.PP

Read input from

.I input-file.

Default: stdin

.RE

.B -of

.I output-file

.br

.B --out-file

.I output-file

.br

.RS 2

.PP

Write output to

.I output-file.  If the output file is a directory, then clpbar 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

.RE

.PP

Please notice that if no 

.B -if, --in-file, -of,

or

.B --out-file

options are specified on the command line, and an unknown command line option

is encountered, then clpbar 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.

.B -s

.I size

.br

.B --size

.I size

.br

.RS 2

.PP

Expect an input stream of

.I size

bytes.

.PP

When reading a regular file or a link to a regular file, clpbar 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.

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

.I size

may also be specified in terms of 'b' for blocks (see the 

.B -bl

option below).

See examples below.

.RE

.B -c

.I size

.br

.B --completed

.I size

.br

.RS 2

.PP

Instruct clpbar that

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

.B -bs

.I buffer-size

.br

.B --buffer-size

.I buffer-size

.br

.RS 2

.PP

Allocate an I/O buffer of

.I buffer-size

bytes.  The same modifiers may apply here ('k', 'm', 'g', 't', 'p', 'e' 

and 'b') as for the

.B -s

flag above.  Changing the buffer size can improve throughput, depending on

your application of clpbar.  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)

.RE

.B -th

.I rate

.br

.B --throttle

.I rate

.br

.RS 2

.PP

Restrict I/O throughput to 

.I rate

bytes per second.  The same modifiers apply here ('k', 'm', 'g', 't', 'p', 'e'

and 'b') as for the 

.B -s

flag above.

.RE

.B -i

.I seconds

.br

.B --interval

.I seconds

.br

.RS 2

.PP

Update the display every

.I seconds

seconds.  Default: 1 second

.RE

.B -t

.I microseconds

.br

.B --timeout

.I microseconds

.br

.RS 2

.PP

The number of microseconds to wait for a change in I/O state before

.I select()

times out.  Default: 250000 (1/4 second)

.RE

.B -k

1000|1024

.br

.B --kilo

1000|1024

.br

.RS 2

.PP

Use either 1000 or 1024 as the definition of a kilobyte.  Default: 1024

.RE

.B -bl

.I size

.br

.B --block-size

.I size

.br

.RS 2

.PP

When reading sizes from the command line that are specified in terms of

blocks, assume a single block is 

.I size

bytes.

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

.I size

in terms of 'b' for blocks is not allowed for this option.  Default: 512

.RE

.SH DISPLAY COMMAND LINE OPTIONS

.B -sw

.I width

.br

.B --screen-width

.I width

.br

.RS 2

.PP

Assume a screen width of 

.I width

characters.

clpbar will attempt to retrieve the width of the terminal it is running on, and

will adjust that width if the terminal is resized.  If clpbar cannot determine

the terminal width, then clpbar will assume a default width of 79 characters.

Use the

.B --screen-width

command line option to override this behavior and specify a fixed width for

clpbar to use.  (When this option is used, clpbar will ignore terminal resized

signals and continue to use the value provided by the user.)

.RE

.B -sw-1

|

.B --screen-width-minus-one

.br

.B -sw-0

|

.B --screen-width-minus-zero

.RS 2

.PP

Instruct clpbar 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 clpbar

in a terminal that's 80 characters wide, using the command line option

.B --screen-width-minus-one

instructs clpbar to only use 79 characters to print the display.  If you're using

a terminal or shell that wraps the line whenever clpbar prints the last character

then this should alleviate that problem.  Default is to use the full

terminal's width.

.RE

.B -ti

.I string

|

.B --title

.I string

.br

.RS 2

Set the title to 

.IR string .

.RE

.B -dti

|

.B -nti

.br

.B --display-title

|

.B --no-title

.br

.RS 2

Turn on/off the title display.  Even if on, if no title string is set then no

title will be displayed.  Default is on.

.RE

.B -dtw

|

.B --display-twiddle

.br

.B -ntw

|

.B --no-twiddle

.br

.RS 2

.PP

Turn on/off the twiddle in the display.

.RE

.B -dc

|

.B --display-count

.br

.B -nc

|

.B --no-count

.br

.RS 2

.PP

Turn on/off the data count in the display.  Default is on.

.RE

.B -dcb

|

.B -ncb

.br

.B --display-count-bits

|

.B --no-count-bits

.br

.RS 2

Display the data count at bits instead of as bytes.  Default is off.

.PP

By default clpbar will display the data count as bytes using the notation of "B".

Using this option, clpbar will display the throughput as bits using the notation

of "b".

.RE

.B -dth

|

.B --display-throughput

.br

.B -nth

|

.B --no-throughput

.br

.RS 2

.PP

Turn on/off the data throughput in the display.  Default is on.

.RE

.B -dthb

|

.B -nthb

.br

.B --display-throughput-bits

|

.B --no-throughput-bits

.br

.RS 2

Display throughput as bits/second instead of as bytes/second.  Default is off.

.PP

By default clpbar will display the throughput as bytes/second using the notation

of "B/s".  Using this option, clpbar will display the throughput as bits/second

using the notation of "b/s".

.RE

.B -dt

|

.B --display-time

.br

.B -nt

|

.B --no-time

.br

.RS 2

.PP

Turn on/off the time elapsed or eta in the display.  Default is on.

.RE

.B -de

|

.B --display-elapsed-only

.br

.B -ne

|

.B --no-elapsed-only

.RS 2

.PP 

Force clpbar to display the elapsed time instead of the eta.  Default is off.

.RE

.B -dp

|

.B --display-percent

.br

.B -np

|

.B --no-percent

.br

.RS 2

.PP

Turn on/off percent complete in the display.  Default is on.

.RE

.B -db

|

.B --display-bar

.br

.B -nb

|

.B --no-bar

.br

.RS 2

.PP

Turn on/off the progress bar in the display.  Default is on.

.RE

.B -ds

|

.B --display-summary

.br

.B -ns

|

.B --no-summary

.br

.RS 2

.PP

Turn on/off the summary information displayed when the operation is complete.

Default is on.

.RE

.B -da

|

.B --display-all

.br

.B -dn

|

.B --display-none

.br

.RS 2

.PP

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.

.RE

.SH COLOR COMMAND LINE OPTIONS

.PP

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

.B -dan

|

.B --display-ansi

.br

.B -nan

|

.B --no-ansi

.br

.RS 2

.PP

Turn on/off the use of ansi color codes in the display.

.RE

.B -spbg

.I color

|

.B --space-background

.I color

.br

.RS 2

.PP

Use

.I color

as the background color for spacing between display objects.  Default: normal

.RE

.B -twfg

.I color

|

.B --twiddle-foreground

.I color

.br

.B -twbg

.I color

|

.B --twiddle-background

.I color

.br

.RS 2

.PP

Use

.I color

as the twiddle color in the display.  Default: normal

.RE

.B -twb

|

.B --twiddle-bold

.br

.B -twn

|

.B --twiddle-normal

.br

.RS 2

.PP

Turn on/off the use of bold font when displaying the twiddle.  Default off

.RE

.B -tifg

.I color

|

.B --title-foreground

.I color

.br

.B -tibg

.I color

|

.B --title-background

.I color

.br

.RS 2

.PP

Use

.I color

as the title color in the display.  Default: normal

.RE

.B -tib

|

.B --title-bold

.br

.B -tin

|

.B --title-normal

.br

.RS 2

.PP

Turn on/off the use of bold font when displaying the title.  Default off

.RE

.B -cfg

.I color

|

.B --count-foreground

.I color

.br

.B -cbg

.I color

|

.B --count-background

.I color

.br

.RS 2

.PP

Use

.I color

as the data count color in the display.  Default: normal

.RE

.B -cb

|

.B --count-bold

.br

.B -cn

|

.B --count-normal

.br

.RS 2

.PP

Turn on/off the use of bold font when displaying the data count.  Default off

.RE

.B -thlfg

.I color

|

.B --throughput-label-foreground

.I color

.br

.B -thlbg

.I color

|

.B --throughput-label-background

.I color

.br

.RS 2

.PP

Use

.I color

as the throughput label color in the display.  Default: normal

.RE

.B -thlb

|

.B --throughput-label-bold

.br

.B -thln

|

.B --throughput-label-normal

.br

.RS 2

.PP

Turn on/off the use of bold font when displaying the throughput label.

Default off

.RE

.B -thfg

.I color

|

.B --throughput-foreground

.I color

.br

.B -thbg

.I color

|

.B --throughput-background

.I color

.br

.RS 2

.PP

Use

.I color

as the throughput color in the display.  Default: normal

.RE

.B -thb

|

.B --throughput-bold

.br

.B -thn

|

.B --throughput-normal

.br

.RS 2

.PP

Turn on/off the use of bold font when displaying the throughput.

Default off

.RE

.B -tlfg

.I color

|

.B --time-label-foreground

.I color

.br

.B -tlbg

.I color

|

.B --time-label-background

.I color

.br

.RS 2

.PP

Use

.I color

as the time label color in the display.  Default: normal

.RE

.B -tlb

|

.B --time-label-bold

.br

.B -tln

|

.B --time-label-normal

.br

.RS 2

.PP

Turn on/off the use of bold font when displaying the time label.

Default off

.RE

.B -tfg

.I color

|

.B --time-foreground

.I color

.br

.B -tbg

.I color

|

.B --time-background

.I color

.br

.RS 2

.PP

Use

.I color

as the time color in the display.  Default: normal

.RE

.B -tb

|

.B --time-bold

.br

.B -tn

|

.B --time-normal

.br

.RS 2

.PP

Turn on/off the use of bold font when displaying the time.

Default off

.RE

.B -pfg

.I color

|

.B --percent-foreground

.I color

.br

.B -pbg

.I color

|

.B --percent-background

.I color

.br

.RS 2

.PP

Use

.I color

as the percent color in the display.  Default: normal