xenial (1) bar.1.gz

Provided by: bar_1.11.1-2_amd64 bug

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.

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
         programs 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 similar to: "File size limit exceeded".

         When  trying  to  open  files  greater  than  2gb  on  an  OS  without Large File support, but with the
         O_LARGEFILE option that can be passed to open(), bar will receive an error when trying to retrieve  the
         file's size, but bar will be able to open the file anyway.  Under these circumstances, bar will print a
         "File too large" error message, but will then proceed to transfer the data.  Since bar will not be able
         to  retrieve  the  file's size on it's own, the --size command line option must be used after the --in-
         file option to tell bar the file size manually.  On such OS's, bar should be able to  write  more  than
         2gb of data to a file without any problems.

         For  OS's  that  support  files  greater  than 2gb, either natively or through the Large File extension
         definitions mentioned above, bar should work as expected.

       - The author has noticed that when running bar over an SSH connection, sometimes window resize events are
         not captured until after the display 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-memalign 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)