a50e959
.TH CLPBAR 1 "4 November 2003"
a50e959
.SH NAME
a50e959
clpbar \- show information about a data transfer
a50e959
.SH SYNOPSIS
a50e959
.RS 0
a50e959
.TP 4
a50e959
.B clpbar
a50e959
[
a50e959
.I I/O-options
a50e959
]
a50e959
[
a50e959
.I display-options
a50e959
]
a50e959
[
a50e959
.I color-options
a50e959
]
a50e959
.br
a50e959
[
a50e959
.I input-file
a50e959
]
a50e959
[
a50e959
.I output-file
a50e959
]
a50e959
.br
a50e959
[
a50e959
.B -h
a50e959
|
a50e959
.B --help
a50e959
]
a50e959
[
a50e959
.B -v
a50e959
|
a50e959
.B --version
a50e959
]
a50e959
.RE
a50e959
a50e959
.SH DESCRIPTION
a50e959
.PP
a50e959
clpbar is a simple tool to process a stream of data and print a display for the
a50e959
user on stderr showing (a) the amount of data passed, (b) the throughput of
a50e959
the data transfer, and, if the total size of the data stream is known, (c)
a50e959
estimated time remaining, percent complete, and a progress bar.
a50e959
a50e959
.PP
a50e959
clpbar was originally written for the purpose of estimating the amount of time
a50e959
needed to transfer large amounts (many, many gigabytes) of data across a
a50e959
network.  (Usually in an SSH/tar pipe.)
a50e959
a50e959
.SH I/O COMMAND LINE OPTIONS
a50e959
a50e959
.B -if
a50e959
.I input-file
a50e959
.br
a50e959
.B --in-file
a50e959
.I input-file
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Read input from
a50e959
.I input-file.
a50e959
Default: stdin
a50e959
.RE
a50e959
a50e959
.B -of
a50e959
.I output-file
a50e959
.br
a50e959
.B --out-file
a50e959
.I output-file
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Write output to
a50e959
.I output-file.  If the output file is a directory, then clpbar will attempt to
a50e959
create a file in the output directory with the same name as the input file,
a50e959
and attempt to copy the input file mode as well as it's data.
a50e959
Default: stdout
a50e959
.RE
a50e959
.PP
a50e959
Please notice that if no 
a50e959
.B -if, --in-file, -of,
a50e959
or
a50e959
.B --out-file
a50e959
options are specified on the command line, and an unknown command line option
a50e959
is encountered, then clpbar will assume that the first unknown command line
a50e959
option is a path to an input file, and the second (if found) is a path to an
a50e959
output file.
a50e959
a50e959
.B -s
a50e959
.I size
a50e959
.br
a50e959
.B --size
a50e959
.I size
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Expect an input stream of
a50e959
.I size
a50e959
bytes.
a50e959
.PP
a50e959
When reading a regular file or a link to a regular file, clpbar will extract the
a50e959
file size on it's own.  However, this flag is useful for reading from a
a50e959
character- or block-special device file, or from a pipe.
a50e959
.I size
a50e959
may be followed by 'k', 'm', 'g', 't', 'p', or 'e' for kilobytes, megabytes,
a50e959
gigabytes, terabytes, petabytes, or exabytes, respectively (see also the -k
a50e959
option below).  Alternatively, 
a50e959
.I size
a50e959
may also be specified in terms of 'b' for blocks (see the 
a50e959
.B -bl
a50e959
option below).
a50e959
See examples below.
a50e959
.RE
a50e959
a50e959
.B -c
a50e959
.I size
a50e959
.br
a50e959
.B --completed
a50e959
.I size
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar that
a50e959
.I size
a50e959
bytes of the data stream have already been copied, and that this is a
a50e959
continuation of a previous data stream.  Note that use of this option will
a50e959
throw off throughput and ETA calculations at first, but they should settle
a50e959
down as the transfer continues.
a50e959
a50e959
.B -bs
a50e959
.I buffer-size
a50e959
.br
a50e959
.B --buffer-size
a50e959
.I buffer-size
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Allocate an I/O buffer of
a50e959
.I buffer-size
a50e959
bytes.  The same modifiers may apply here ('k', 'm', 'g', 't', 'p', 'e' 
a50e959
and 'b') as for the
a50e959
.B -s
a50e959
flag above.  Changing the buffer size can improve throughput, depending on
a50e959
your application of clpbar.  For fast I/O operations, say from a ramdisk for
a50e959
instance, it might be worth your while to experiment with a large buffer
a50e959
(circa 1MB for instance).  But for slow I/O operations, like from a tape
a50e959
drive, you could merely be wasting your memory.  Default: 52488 (512KB)
a50e959
.RE
a50e959
a50e959
.B -th
a50e959
.I rate
a50e959
.br
a50e959
.B --throttle
a50e959
.I rate
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Restrict I/O throughput to 
a50e959
.I rate
a50e959
bytes per second.  The same modifiers apply here ('k', 'm', 'g', 't', 'p', 'e'
a50e959
and 'b') as for the 
a50e959
.B -s
a50e959
flag above.
a50e959
.RE
a50e959
a50e959
.B -i
a50e959
.I seconds
a50e959
.br
a50e959
.B --interval
a50e959
.I seconds
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Update the display every
a50e959
.I seconds
a50e959
seconds.  Default: 1 second
a50e959
.RE
a50e959
a50e959
.B -t
a50e959
.I microseconds
a50e959
.br
a50e959
.B --timeout
a50e959
.I microseconds
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
The number of microseconds to wait for a change in I/O state before
a50e959
.I select()
a50e959
times out.  Default: 250000 (1/4 second)
a50e959
.RE
a50e959
a50e959
.B -k
a50e959
1000|1024
a50e959
.br
a50e959
.B --kilo
a50e959
1000|1024
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use either 1000 or 1024 as the definition of a kilobyte.  Default: 1024
a50e959
.RE
a50e959
a50e959
.B -bl
a50e959
.I size
a50e959
.br
a50e959
.B --block-size
a50e959
.I size
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
When reading sizes from the command line that are specified in terms of
a50e959
blocks, assume a single block is 
a50e959
.I size
a50e959
bytes.
a50e959
.I Size
a50e959
may be followed by 'k', 'm', 'g', 't', 'p', or 'e' for kilobytes, megabytes,
a50e959
gigabytes, terabytes, petabytes, or exabytes, respectively.  Block size must
a50e959
be set before specifying any sizes in terms of blocks or the default value
a50e959
will be used instead.  Specifying
a50e959
.I size
a50e959
in terms of 'b' for blocks is not allowed for this option.  Default: 512
a50e959
.RE
a50e959
a50e959
.SH DISPLAY COMMAND LINE OPTIONS
a50e959
a50e959
.B -sw
a50e959
.I width
a50e959
.br
a50e959
.B --screen-width
a50e959
.I width
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Assume a screen width of 
a50e959
.I width
a50e959
characters.
a50e959
a50e959
clpbar will attempt to retrieve the width of the terminal it is running on, and
a50e959
will adjust that width if the terminal is resized.  If clpbar cannot determine
a50e959
the terminal width, then clpbar will assume a default width of 79 characters.
a50e959
Use the
a50e959
.B --screen-width
a50e959
command line option to override this behavior and specify a fixed width for
a50e959
clpbar to use.  (When this option is used, clpbar will ignore terminal resized
a50e959
signals and continue to use the value provided by the user.)
a50e959
.RE
a50e959
a50e959
.B -sw-1
a50e959
|
a50e959
.B --screen-width-minus-one
a50e959
.br
a50e959
.B -sw-0
a50e959
|
a50e959
.B --screen-width-minus-zero
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to use either the entire column width reported by termio, or one
a50e959
less than reported by termio.  I.e. If termio reports that you are running clpbar
a50e959
in a terminal that's 80 characters wide, using the command line option
a50e959
.B --screen-width-minus-one
a50e959
instructs clpbar to only use 79 characters to print the display.  If you're using
a50e959
a terminal or shell that wraps the line whenever clpbar prints the last character
a50e959
then this should alleviate that problem.  Default is to use the full
a50e959
terminal's width.
a50e959
.RE
a50e959
a50e959
.B -ti
a50e959
.I string
a50e959
|
a50e959
.B --title
a50e959
.I string
a50e959
.br
a50e959
.RS 2
a50e959
Set the title to 
a50e959
.IR string .
a50e959
.RE
a50e959
a50e959
.B -dti
a50e959
|
a50e959
.B -nti
a50e959
.br
a50e959
.B --display-title
a50e959
|
a50e959
.B --no-title
a50e959
.br
a50e959
.RS 2
a50e959
Turn on/off the title display.  Even if on, if no title string is set then no
a50e959
title will be displayed.  Default is on.
a50e959
.RE
a50e959
a50e959
.B -dtw
a50e959
|
a50e959
.B --display-twiddle
a50e959
.br
a50e959
.B -ntw
a50e959
|
a50e959
.B --no-twiddle
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the twiddle in the display.
a50e959
.RE
a50e959
a50e959
.B -dc
a50e959
|
a50e959
.B --display-count
a50e959
.br
a50e959
.B -nc
a50e959
|
a50e959
.B --no-count
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the data count in the display.  Default is on.
a50e959
.RE
a50e959
a50e959
.B -dcb
a50e959
|
a50e959
.B -ncb
a50e959
.br
a50e959
.B --display-count-bits
a50e959
|
a50e959
.B --no-count-bits
a50e959
.br
a50e959
.RS 2
a50e959
Display the data count at bits instead of as bytes.  Default is off.
a50e959
.PP
a50e959
By default clpbar will display the data count as bytes using the notation of "B".
a50e959
Using this option, clpbar will display the throughput as bits using the notation
a50e959
of "b".
a50e959
.RE
a50e959
a50e959
.B -dth
a50e959
|
a50e959
.B --display-throughput
a50e959
.br
a50e959
.B -nth
a50e959
|
a50e959
.B --no-throughput
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the data throughput in the display.  Default is on.
a50e959
.RE
a50e959
a50e959
.B -dthb
a50e959
|
a50e959
.B -nthb
a50e959
.br
a50e959
.B --display-throughput-bits
a50e959
|
a50e959
.B --no-throughput-bits
a50e959
.br
a50e959
.RS 2
a50e959
Display throughput as bits/second instead of as bytes/second.  Default is off.
a50e959
.PP
a50e959
By default clpbar will display the throughput as bytes/second using the notation
a50e959
of "B/s".  Using this option, clpbar will display the throughput as bits/second
a50e959
using the notation of "b/s".
a50e959
.RE
a50e959
a50e959
.B -dt
a50e959
|
a50e959
.B --display-time
a50e959
.br
a50e959
.B -nt
a50e959
|
a50e959
.B --no-time
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the time elapsed or eta in the display.  Default is on.
a50e959
.RE
a50e959
a50e959
.B -de
a50e959
|
a50e959
.B --display-elapsed-only
a50e959
.br
a50e959
.B -ne
a50e959
|
a50e959
.B --no-elapsed-only
a50e959
.RS 2
a50e959
.PP 
a50e959
Force clpbar to display the elapsed time instead of the eta.  Default is off.
a50e959
.RE
a50e959
a50e959
.B -dp
a50e959
|
a50e959
.B --display-percent
a50e959
.br
a50e959
.B -np
a50e959
|
a50e959
.B --no-percent
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off percent complete in the display.  Default is on.
a50e959
.RE
a50e959
a50e959
.B -db
a50e959
|
a50e959
.B --display-bar
a50e959
.br
a50e959
.B -nb
a50e959
|
a50e959
.B --no-bar
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the progress bar in the display.  Default is on.
a50e959
.RE
a50e959
a50e959
.B -ds
a50e959
|
a50e959
.B --display-summary
a50e959
.br
a50e959
.B -ns
a50e959
|
a50e959
.B --no-summary
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the summary information displayed when the operation is complete.
a50e959
Default is on.
a50e959
.RE
a50e959
a50e959
.B -da
a50e959
|
a50e959
.B --display-all
a50e959
.br
a50e959
.B -dn
a50e959
|
a50e959
.B --display-none
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off all displays.  -dn is equivalent to -ntw -nc -nth -nt -np -nb.
a50e959
(Using -dn followed by -db would be equivalent to -ntw -nc -nth -nt -np.)
a50e959
-da is equivalent to -dtw -dc -dth -dt -dp -db.
a50e959
.RE
a50e959
a50e959
.SH COLOR COMMAND LINE OPTIONS
a50e959
a50e959
.PP
a50e959
For the following color-specific command line options, the following keywords
a50e959
are recognized as valid color names: normal, black, red, green, yellow, blue,
a50e959
magenta, cyan, and white
a50e959
a50e959
.B -dan
a50e959
|
a50e959
.B --display-ansi
a50e959
.br
a50e959
.B -nan
a50e959
|
a50e959
.B --no-ansi
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of ansi color codes in the display.
a50e959
.RE
a50e959
a50e959
.B -spbg
a50e959
.I color
a50e959
|
a50e959
.B --space-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the background color for spacing between display objects.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -twfg
a50e959
.I color
a50e959
|
a50e959
.B --twiddle-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -twbg
a50e959
.I color
a50e959
|
a50e959
.B --twiddle-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the twiddle color in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -twb
a50e959
|
a50e959
.B --twiddle-bold
a50e959
.br
a50e959
.B -twn
a50e959
|
a50e959
.B --twiddle-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the twiddle.  Default off
a50e959
.RE
a50e959
a50e959
.B -tifg
a50e959
.I color
a50e959
|
a50e959
.B --title-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -tibg
a50e959
.I color
a50e959
|
a50e959
.B --title-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the title color in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -tib
a50e959
|
a50e959
.B --title-bold
a50e959
.br
a50e959
.B -tin
a50e959
|
a50e959
.B --title-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the title.  Default off
a50e959
.RE
a50e959
a50e959
.B -cfg
a50e959
.I color
a50e959
|
a50e959
.B --count-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -cbg
a50e959
.I color
a50e959
|
a50e959
.B --count-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the data count color in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -cb
a50e959
|
a50e959
.B --count-bold
a50e959
.br
a50e959
.B -cn
a50e959
|
a50e959
.B --count-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the data count.  Default off
a50e959
.RE
a50e959
a50e959
.B -thlfg
a50e959
.I color
a50e959
|
a50e959
.B --throughput-label-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -thlbg
a50e959
.I color
a50e959
|
a50e959
.B --throughput-label-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the throughput label color in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -thlb
a50e959
|
a50e959
.B --throughput-label-bold
a50e959
.br
a50e959
.B -thln
a50e959
|
a50e959
.B --throughput-label-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the throughput label.
a50e959
Default off
a50e959
.RE
a50e959
a50e959
.B -thfg
a50e959
.I color
a50e959
|
a50e959
.B --throughput-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -thbg
a50e959
.I color
a50e959
|
a50e959
.B --throughput-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the throughput color in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -thb
a50e959
|
a50e959
.B --throughput-bold
a50e959
.br
a50e959
.B -thn
a50e959
|
a50e959
.B --throughput-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the throughput.
a50e959
Default off
a50e959
.RE
a50e959
a50e959
.B -tlfg
a50e959
.I color
a50e959
|
a50e959
.B --time-label-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -tlbg
a50e959
.I color
a50e959
|
a50e959
.B --time-label-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the time label color in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -tlb
a50e959
|
a50e959
.B --time-label-bold
a50e959
.br
a50e959
.B -tln
a50e959
|
a50e959
.B --time-label-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the time label.
a50e959
Default off
a50e959
.RE
a50e959
a50e959
.B -tfg
a50e959
.I color
a50e959
|
a50e959
.B --time-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -tbg
a50e959
.I color
a50e959
|
a50e959
.B --time-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the time color in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -tb
a50e959
|
a50e959
.B --time-bold
a50e959
.br
a50e959
.B -tn
a50e959
|
a50e959
.B --time-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the time.
a50e959
Default off
a50e959
.RE
a50e959
a50e959
.B -pfg
a50e959
.I color
a50e959
|
a50e959
.B --percent-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -pbg
a50e959
.I color
a50e959
|
a50e959
.B --percent-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the percent color in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -pb
a50e959
|
a50e959
.B --percent-bold
a50e959
.br
a50e959
.B -pn
a50e959
|
a50e959
.B --percent-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the percent.
a50e959
Default off
a50e959
.RE
a50e959
a50e959
.B -bbfg
a50e959
.I color
a50e959
|
a50e959
.B --bar-brace-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -bbbg
a50e959
.I color
a50e959
|
a50e959
.B --bar-brace-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the brace color around the progress bar in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -bbb
a50e959
|
a50e959
.B --bar-brace-bold
a50e959
.br
a50e959
.B -bbn
a50e959
|
a50e959
.B --bar-brace-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the bar braces.
a50e959
Default off
a50e959
.RE
a50e959
a50e959
.B -bfg
a50e959
.I color
a50e959
|
a50e959
.B --bar-foreground
a50e959
.I color
a50e959
.br
a50e959
.B -bbg
a50e959
.I color
a50e959
|
a50e959
.B --bar-background
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the color of the progress bar in the display.  Default: normal
a50e959
.RE
a50e959
a50e959
.B -bb
a50e959
|
a50e959
.B --bar-bold
a50e959
.br
a50e959
.B -bn
a50e959
|
a50e959
.B --bar-normal
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Turn on/off the use of bold font when displaying the progress bar.
a50e959
Default off
a50e959
.RE
a50e959
a50e959
.B -h
a50e959
|
a50e959
.B --help
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Display this text and exit.
a50e959
.RE
a50e959
a50e959
.B -v
a50e959
|
a50e959
.B --version
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Display the program version and exit.
a50e959
.RE
a50e959
a50e959
.SH RESOURCE FILE OPTIONS
a50e959
a50e959
.PP
a50e959
Some command line options may be specified in a resource file.  clpbar will
a50e959
search for a resource file by the name of
a50e959
.B ~/.clpbarrc
a50e959
and, if found, clpbar will use the values within by default.  In addition, clpbar
a50e959
will also search for a file in the directory in which it is run,
a50e959
.BR ./.clpbarrc .
a50e959
If this file exists, it's values will override the values found in
a50e959
.BR ~/.clpbarrc .
a50e959
Values in both files may be overridden by command line flags.  Lines that
a50e959
begin with a # are ignored.
a50e959
a50e959
.PP
a50e959
For resource options requiring a
a50e959
.I boolean
a50e959
value, the following values are recognized: on and off, yes and no, (and the
a50e959
single-character abbreviations y and n), true and false, (and the
a50e959
single-character abbreviations t and f), 0 and 1.
a50e959
a50e959
.PP
a50e959
For resource options requiring a
a50e959
.I color
a50e959
value, the same keywords are recognized as for the color-specific command line
a50e959
options above: normal, black, red, green, yellow, blue, magenta, cyan, and
a50e959
white
a50e959
a50e959
.BR buffer-size :
a50e959
.I buffer-size
a50e959
.RS 2
a50e959
.PP
a50e959
Allocate an I/O buffer of
a50e959
.I buffer-size
a50e959
bytes.  See the
a50e959
.B --buffer-size
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR throttle :
a50e959
.I rate
a50e959
.RS 2
a50e959
.PP
a50e959
Restrict I/O throughput to 
a50e959
.I rate
a50e959
bytes per second.  See the
a50e959
.B --throttle
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR interval :
a50e959
.I seconds
a50e959
.RS 2
a50e959
.PP
a50e959
Update the display every
a50e959
.I seconds
a50e959
seconds.  See the
a50e959
.B --interval
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR timeout :
a50e959
.I microseconds
a50e959
.RS 2
a50e959
.PP
a50e959
The number of microseconds to wait for a change in I/O state before
a50e959
.I select()
a50e959
times out.  See the 
a50e959
.B --timeout
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR kilobyte :
a50e959
1000|1024
a50e959
.RS 2
a50e959
.PP
a50e959
Use either 1000 or 1024 as the definition of a kilobyte.  See the
a50e959
.B --kilo
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR block-size :
a50e959
.I size
a50e959
.RS 2
a50e959
When parsing sizes specified in terms of blocks, assume a single block is 
a50e959
.I size
a50e959
bytes.  See the
a50e959
.B --block-size
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR screen-width :
a50e959
.I width
a50e959
.RS 2
a50e959
.PP
a50e959
Override termio and assume that the screen is 
a50e959
.I width
a50e959
characters wide.  See the 
a50e959
.B --screen-width
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR screen-width-minus-one :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to restrict the number of columns reported by termio by one.  See
a50e959
the
a50e959
.B --screen-width-minus-one
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-twiddle :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to turn on/off the twirling twiddle character in the display.
a50e959
See the 
a50e959
.B --display-twiddle
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-title :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to turn on/off the title in the display.  See the
a50e959
.B --display-title 
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-count :
a50e959
boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to turn on/off the data count in the display.  See the
a50e959
.B --display-count
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-count-bits :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Display the data count as bits instead of as bytes.  See the
a50e959
.B --display-count-bits
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-throughput :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to turn on/off the data throughput in the display.  See the
a50e959
.B --display-throughput
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-throughput-bits :
a50e959
boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Display throughput as bits/sec instead of as bytes/sec.  See the
a50e959
.B --display-throughput-bits
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-time :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to turn on/off the time in the display.  See the
a50e959
.B --display-time
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-elapsed-only :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Force clpbar to display the elapsed time instead of the eta.  See the
a50e959
.B --display-elapsed-only
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-percent :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to turn on/off the percent complete in the display.  See the
a50e959
.B --display-percent
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-bar :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to turn on/off the progress bar in the display.  See the
a50e959
.B --display-bar
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-summary :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to turn on/off the summary information displayed when operation
a50e959
is complete.  See the 
a50e959
.B --display-summary
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR display-ansi :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Instruct clpbar to turn on/off the use of ansi color codes in the display.  See
a50e959
the
a50e959
.B --display-ansi
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR space-background :
a50e959
.I color
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use
a50e959
.I color
a50e959
as the background color for spacing between display objects.  See the
a50e959
.B --space-background
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR twiddle-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR twiddle-background :
a50e959
.I color
a50e959
.br
a50e959
.BR twiddle-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use the specified colors for the foreground and background of the twiddle,
a50e959
and use a bold font.  See the
a50e959
.BR --twiddle-foreground ,
a50e959
.BR --twiddle-background ,
a50e959
and
a50e959
.B --twiddle-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.BR title :
a50e959
.I string
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Set the title string for the display.  See the
a50e959
.B --title
a50e959
command line option above.
a50e959
.RE
a50e959
a50e959
.BR title-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR title-background :
a50e959
.I color
a50e959
.br
a50e959
.BR title-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use the specified colors for the foreground and background of the title,
a50e959
and use a bold font.  See the
a50e959
.BR --title-foreground ,
a50e959
.BR --title-background ,
a50e959
and
a50e959
.B --title-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.BR count-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR count-background :
a50e959
.I color
a50e959
.br
a50e959
.BR count-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use the specified colors for the foreground and background of the data count,
a50e959
and use a bold font.  See the
a50e959
.BR --count-foreground ,
a50e959
.BR --count-background ,
a50e959
and
a50e959
.B --count-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.BR throughput-label-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR throughput-label-background :
a50e959
.I color
a50e959
.br
a50e959
.BR throughput-label-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use the specified colors for the foreground and background of the throughput
a50e959
label, and use a bold font.  See the
a50e959
.BR --throughput-label-foreground ,
a50e959
.BR --throughput-label-background ,
a50e959
and
a50e959
.B --throughput-label-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.BR throughput-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR throughput-background :
a50e959
.I color
a50e959
.br
a50e959
.BR throughput-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use the specified colors for the foreground and background of the throughput,
a50e959
and use a bold font.  See the
a50e959
.BR --throughput-foreground ,
a50e959
.BR --throughput-background ,
a50e959
and
a50e959
.B --throughput-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.BR time-label-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR time-label-background :
a50e959
.I color
a50e959
.br
a50e959
.BR time-label-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use the specified colors for the foreground and background of the time
a50e959
label, and use a bold font.  See the
a50e959
.BR --time-label-foreground ,
a50e959
.BR --time-label-background ,
a50e959
and
a50e959
.B --time-label-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.BR time-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR time-background :
a50e959
.I color
a50e959
.br
a50e959
.BR time-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use the specified colors for the foreground and background of the time,
a50e959
and use a bold font.  See the
a50e959
.BR --time-foreground ,
a50e959
.BR --time-background ,
a50e959
and
a50e959
.B --time-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.BR percent-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR percent-background :
a50e959
.I color
a50e959
.br
a50e959
.BR percent-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use the specified colors for the foreground and background of the percent,
a50e959
and use a bold font.  See the
a50e959
.BR --percent-foreground ,
a50e959
.BR --percent-background ,
a50e959
and
a50e959
.B --percent-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.BR bar-brace-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR bar-brace-background :
a50e959
.I color
a50e959
.br
a50e959
.BR bar-brace-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
.PP
a50e959
Use the specified colors for the foreground and background of the brace
a50e959
surrounding the progress bar, and use a bold font.  See the
a50e959
.BR --bar-brace-foreground ,
a50e959
.BR --bar-brace-background ,
a50e959
and
a50e959
.B --bar-brace-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.BR bar-foreground :
a50e959
.I color
a50e959
.br
a50e959
.BR bar-background :
a50e959
.I color
a50e959
.br
a50e959
.BR bar-bold :
a50e959
.I boolean
a50e959
.br
a50e959
.RS 2
a50e959
Use the specified colors for the foreground and background of the progress
a50e959
bar, and use a bold font.  See the
a50e959
.BR --bar-foreground ,
a50e959
.BR --bar-background ,
a50e959
and
a50e959
.B --bar-bold
a50e959
command line options above.
a50e959
.RE
a50e959
a50e959
.SH EXAMPLES
a50e959
a50e959
.PP
a50e959
Example 1: Using clpbar to copy a 2.4gb file from a device (in this case a tape
a50e959
drive) to a file, using a 64k buffer.
a50e959
a50e959
.RS 2
a50e959
.PP
a50e959
prompt% clpbar --in-file /dev/rmt/1cbn --out-file \\
a50e959
.br
a50e959
tape-restore.tar --size 2.4g --buffer-size 64k
a50e959
.RE
a50e959
  
a50e959
.PP
a50e959
Example 2: Using clpbar to copy a 37tb file across the network using SSH.
a50e959
a50e959
.RS 2
a50e959
.PP
a50e959
prompt% ssh remote 'dd if=file' | clpbar --size 37t > file
a50e959
.RE
a50e959
a50e959
.PP
a50e959
Example 3: Using clpbar inside a tar-pipe command:
a50e959
a50e959
.RS 2
a50e959
.PP
a50e959
Normal tar-pipe command might be:
a50e959
a50e959
.RS 2
a50e959
.PP
a50e959
prompt% (cd /some/dir/somewhere && tar -cf - *) \\
a50e959
.br
a50e959
| (cd /some/other/dir && tar -xBpf -)
a50e959
.RE
a50e959
a50e959
.PP
a50e959
3a: Using clpbar within the tar-pipe:
a50e959
a50e959
.RS 2
a50e959
.PP
a50e959
prompt% (cd /some/dir/somewhere && tar -cf - *) \\
a50e959
.br
a50e959
| clpbar \\
a50e959
.br
a50e959
| (cd /some/other/dir && tar -xBpf -)
a50e959
.RE
a50e959
a50e959
.PP
a50e959
3b: Using clpbar with the --size option in a tar-pipe:
a50e959
a50e959
.RS 2
a50e959
.PP
a50e959
prompt% du -sk /some/dir/somewhere
a50e959
.br
a50e959
6281954 /some/dir/somewhere
a50e959
.br
a50e959
.PP
a50e959
prompt% (cd /some/dir/somewhere && tar -cf - *) \\
a50e959
.br
a50e959
| clpbar --size 6281954k \\
a50e959
.br
a50e959
| (cd /some/other/dir && tar -xBpf -)
a50e959
.RE
a50e959
.RE
a50e959
a50e959
.PP
a50e959
Example 4: Using clpbar on a regular file.  (Note that the
a50e959
.B --size
a50e959
option is not needed here, as clpbar will retrieve the file size itself.)
a50e959
a50e959
.RS 2
a50e959
.PP
a50e959
prompt% clpbar --in-file ./file | ssh remote 'cd /some/dir && dd of=file'
a50e959
.RE
a50e959
  
a50e959
.PP
a50e959
Example 5: Generating a 512k file of random data.
a50e959
a50e959
.RS 2
a50e959
.PP
a50e959
prompt% dd if=/dev/random bs=1024 count=512 \\
a50e959
.br
a50e959
| clpbar -s 512k -of ./random
a50e959
.RE
a50e959
a50e959
.PP
a50e959
Example 6: An example .clpbarrc file.
a50e959
.RS 2
a50e959
#
a50e959
.br
a50e959
# This is an example of what a ~/.clpbarrc file 
a50e959
.br
a50e959
# might look like.  Note that lines beginning
a50e959
.br
a50e959
# with a # are ignored.
a50e959
.br
a50e959
#
a50e959
.br
a50e959
display-twiddle: no
a50e959
.br
a50e959
display-ansi: yes
a50e959
.br
a50e959
# space-background: black
a50e959
.br
a50e959
twiddle-foreground: green
a50e959
.br
a50e959
# twiddle-background: normal
a50e959
.br
a50e959
# twiddle-bold: no
a50e959
.br
a50e959
count-foreground: green
a50e959
.br
a50e959
# count-background: magenta
a50e959
.br
a50e959
count-bold: yes
a50e959
.br
a50e959
throughput-label-foreground: normal
a50e959
.br
a50e959
# throughput-label-background: red
a50e959
.br
a50e959
throughput-label-bold: no
a50e959
.br
a50e959
throughput-foreground: green
a50e959
.br
a50e959
# throughput-background: black
a50e959
.br
a50e959
throughput-bold: yes
a50e959
.br
a50e959
time-label-foreground: normal
a50e959
.br
a50e959
# time-label-background: red
a50e959
.br
a50e959
time-label-bold: no
a50e959
.br
a50e959
time-foreground: green
a50e959
.br
a50e959
# time-background: black
a50e959
.br
a50e959
time-bold: yes
a50e959
.br
a50e959
percent-foreground: green
a50e959
.br
a50e959
# percent-background: green
a50e959
.br
a50e959
percent-bold: yes
a50e959
.br
a50e959
bar-brace-foreground: red
a50e959
.br
a50e959
# bar-brace-background: blue
a50e959
.br
a50e959
bar-brace-bold: no
a50e959
.br
a50e959
bar-foreground: yellow
a50e959
.br
a50e959
# bar-background: blue
a50e959
.br
a50e959
bar-bold: yes
a50e959
.RE
a50e959
a50e959
.SH NOTES
a50e959
a50e959
.RS 0
a50e959
.TP 2
a50e959
-
a50e959
The
a50e959
.B --size
a50e959
option is only used by clpbar in calculating information about the data
a50e959
transfer.  clpbar will not cease copying data once it has reached the number of
a50e959
bytes specified with the 
a50e959
.B --size
a50e959
option, but instead clpbar will continue to copy
a50e959
data until and end of input is reached.  If this behavior is undesirable then
a50e959
clpbar may be used in conjunction with dd, where the count option is used with dd
a50e959
to specify when to cut off the input stream.  (See examples above.)
a50e959
.RE
a50e959
a50e959
.RS 0
a50e959
.TP 2
a50e959
-
a50e959
When using other commands such as 
a50e959
.B du -k
a50e959
to calculate the expected size of a
a50e959
data transfer stream, the value returned may not be exactly the number of
a50e959
bytes counted by clpbar in the actual data transfer.  Common causes for this
a50e959
discrepancy could be attributed to round-off error or the use of 1000 bytes as
a50e959
a kilobyte rather than 1024.  (If the later is the case, then using the 
a50e959
.B -k
a50e959
1000 option to clpbar will help.)  When such discrepancies occur, clpbar may report
a50e959
that the data stream contained only 98% or as much as 101% of it's expected
a50e959
size.  (If you have doubts, you should definitely verify your data using
a50e959
md5sum, diff, or cmp.)
a50e959
.RE
a50e959
a50e959
.RS 0
a50e959
.TP 2
a50e959
-
a50e959
When the value of a calculation exceeds the size alloted for the display, the
a50e959
value +99... will be substituted in it's place.  The complete value will be
a50e959
displayed in a summary statement after clpbar has reached the end of input.
a50e959
.RE
a50e959
a50e959
.RS 0
a50e959
.TP 2
a50e959
-
a50e959
clpbar assumes a linear relationship between the speed of the data transfer and
a50e959
the amount of time remaining.  Specifically the calculation is based on the
a50e959
following:
a50e959
a50e959
elapsed time / eta = bytes written / total size
a50e959
a50e959
However, it has been the author's experience that the throughput speed will
a50e959
change, particularly at the beginning of the transfer, and this will affect the
a50e959
estimated time remaining.  The author does not believe this is a bug, but a
a50e959
side-effect of this method of calculation.
a50e959
.RE
a50e959
a50e959
.RS 0
a50e959
.TP 2
a50e959
-
a50e959
clpbar assumes that there are 8 bits in both a byte and a char.
a50e959
.RE
a50e959
a50e959
.SH BUGS
a50e959
a50e959
.TP 2
a50e959
-
a50e959
clpbar uses the
a50e959
.I open()
a50e959
and
a50e959
.I fstat()
a50e959
functions to open and retrieve the size of regular files when using either the
a50e959
.B --in-file
a50e959
or
a50e959
.B --out-file
a50e959
command line options.  Some OS's do not support Large Files (file sizes up to
a50e959
(2**63)-1 bytes) natively.  Some OS's support Large Files but require
a50e959
_FILE_OFFSET_BITS or _LARGE_FILES to be defined properly at compile time.
a50e959
Other OS's support neither, but still allow programs to open files in excess
a50e959
of (2**32)-1 through an O_LARGEFILE option that can be passed to the
a50e959
.I open()
a50e959
function.
a50e959
a50e959
When trying to open files greater than 2gb on an OS without Large File
a50e959
support, clpbar will exit with the message: "File too large".  When trying to
a50e959
write more than 2gb of data to a file, clpbar will write 2**32-1 bytes and then
a50e959
the OS may terminate clpbar with a message similar to: "File size limit
a50e959
exceeded".
a50e959
a50e959
When trying to open files greater than 2gb on an OS without Large File
a50e959
support, but with the O_LARGEFILE option that can be passed to 
a50e959
.IR open() ,
a50e959
clpbar will receive an error when trying to retrieve the file's size, but clpbar
a50e959
will be able to open the file anyway.  Under these circumstances, clpbar will
a50e959
print a "File too large" error message, but will then proceed to transfer the
a50e959
data.  Since clpbar will not be able to retrieve the file's size on it's own, the
a50e959
.B --size
a50e959
command line option must be used after the
a50e959
.B --in-file
a50e959
option to tell clpbar the file size manually.  On such OS's, clpbar should be able
a50e959
to write more than 2gb of data to a file without any problems.
a50e959
a50e959
For OS's that support files greater than 2gb, either natively or through the
a50e959
Large File extension definitions mentioned above, clpbar should work as expected.
a50e959
a50e959
.TP 2
a50e959
-
a50e959
The author has noticed that when running clpbar over an SSH connection, sometimes
a50e959
window resize events are not captured until after the display has gone through
a50e959
one or two more updates, which can cause the line to wrap.
a50e959
a50e959
.TP 2
a50e959
-
a50e959
The author has noticed that on some systems the use of aligned memory
a50e959
allocation, through either memalign() or posix_memalign(), causes clpbar to
a50e959
commit a segmentation fault the first time read() or readv() is called and
a50e959
passed a pointer to the aligned memory as it's input buffer.  Attempts were
a50e959
made to try to isolate systems in which this bug bites through tests in
a50e959
configure, but all tests devised passed with flying colors.  Therefore aligned
a50e959
memory allocation is turned off by default, and may only be enabled by passing
a50e959
--enable-use-memalign to configure when building the executable.
a50e959
a50e959
.PP
a50e959
Report all bugs to the author.
a50e959
a50e959
.PP
a50e959
clpbar was developed on a Sun workstation running Solaris 8.  To the best of the
a50e959
author's knowledge clpbar should compile and run on other platforms without much
a50e959
trouble.  Should other OS's require modifications to the code, the author
a50e959
welcomes all patch submissions, but requests that you include the file
a50e959
.I config.log
a50e959
and the output of 
a50e959
.I "gcc -dumpspecs"
a50e959
(or a listing of predefined variables, if not using gcc).
a50e959
a50e959
.SH DISTRIBUTION
a50e959
.PP
a50e959
The latest version of clpbar can always be found at:
a50e959
.RS 2
a50e959
http://www.freshmeat.net/projects/commandlineprogressbar
a50e959
.br
a50e959
http://sourceforge.net/projects/clpbar/
a50e959
.RE
a50e959
a50e959
.SH AUTHOR
a50e959
.PP
a50e959
clpbar was written by Michael Peek.  See DISTRIBUTION above for contact
a50e959
information.
a50e959
.PP
a50e959
Occasionally, the author fancies that he knows what he's doing.  It is at
a50e959
these times more than ever that his coworkers should cower in fear...
a50e959