manpagez: man pages & more
man bar(1)
Home | html | info | man
bar(1)                                                                  bar(1)




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 calcu-
         lations at first, but they should settle down as the transfer contin-
         ues.

         -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 exper-
           iment 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  modi-
           fiers  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, respec-
           tively.  Block size must be set  before  specifying  any  sizes  in
           terms  of blocks or the default value will be used instead.  Speci-
           fying 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  ter-
         minal'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 nota-
         tion 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 through-
         put 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 infor-
         mation 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 infor-
         mation to the display before it draws the status line.  Then, period-
         ically,  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.  Oth-
         erwise, 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 rep-
         resenting 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/clp-
       barrc.  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: nor-
       mal, 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 --dis-
         play-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  --dis-
         play-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 --dis-
         play-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 infor-
         mation  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  infor-
         mation to the display before it draws the status line.  Then, period-
         ically, 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.  Oth-
         erwise, 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  rep-
         resenting  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  dis-
         play.  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, --twid-
         dle-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-back-
         ground, 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, --per-
         cent-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, clos-
         ing 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  spec-
         ify 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.  Com-
         mon 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 dis-
         play,  the  value +99... will be substituted in it's place.  The com-
         plete 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 calcula-
         tion 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  calcula-
         tion.


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



BUGS

       - Bar  uses  the  open() and fstat() functions to open and retrieve the
         size of regular files when using either the --in-file  or  --out-file
         command  line  options.   Some  OS's do not support Large Files (file
         sizes up to (2**63)-1 bytes) natively.  Some OS's support Large Files
         but  require _FILE_OFFSET_BITS or _LARGE_FILES to be defined properly
         at compile time.  Other OS's support neither, but  still  allow  pro-
         grams  to  open  files  in excess of (2**32)-1 through an O_LARGEFILE
         option that can be passed to the open() function.

         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 simi-
         lar 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 cir-
         cumstances, 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.


       - The  author has noticed that when running bar over an SSH connection,
         sometimes window resize events are not captured until after the  dis-
         play  has  gone  through one or two more updates, which can cause the
         line to wrap.


       - The author has noticed that on some systems the use of aligned memory
         allocation, through either memalign() or posix_memalign(), causes bar
         to commit a segmentation fault the first time read()  or  readv()  is
         called  and  passed  a  pointer  to  the aligned memory as it's input
         buffer.  Attempts were made to try to isolate systems in  which  this
         bug  bites  through  tests in configure, but all tests devised passed
         with flying colors.  Therefore aligned memory  allocation  is  turned
         off by default, and may only be enabled by passing --enable-use-mema-
         lign to configure when building the executable.


       - On some 64-bit systems it has been found that the CC  compiler  will,
         by default, compile bar in 32-bit mode.  This has been known to cause
         math errors which result in segmentation faults and  infinite  loops.
         Although  multiple configure tests have been added to the compilation
         phase to try to properly detect such  compilers  and  compensate  for
         such  bugs,  without  access  to  such systems for debugging purposes
         there may be other bugs waiting to rear their ugly heads.


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



DISTRIBUTION

       The latest version of bar can always be found at:
         http://www.freshmeat.net/projects/commandlineprogressbar
         http://sourceforge.net/projects/clpbar/



AUTHOR

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




                                4 November 2003                         bar(1)

bar 1.11.0 - Generated Tue Nov 23 06:10:44 CST 2010
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.