Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
BAR(1)			    General Commands Manual			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 ex-
	 tract	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  be-
	 low).	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, de-
	   pending 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  op-
	   tion.  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, us-
	 ing the command line option --screen-width-minus-one instructs	bar to
	 only  use 79 characters to print the display.	If you're using	a ter-
	 minal or shell	that wraps the line whenever bar prints	the last char-
	 acter 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.   De-
	 fault 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 di-
	 rectly	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  ob-
	 jects.	 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.  De-
	 fault 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.  De-
	 fault 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 la-
	 bel.  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.  De-
	 fault 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.  De-
	 fault 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.  De-
	 fault 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.  De-
	 fault 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 ab-
       breviations y and n), true and false, (and the single-character	abbre-
       viations	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 di-
	 rectly	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 ob-
	 jects.	 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 ti-
	 tle, and use a	bold font.  See	the --title-foreground,	 --title-back-
	 ground, 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 in-
	 stead	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 er-
	 ror 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 op-
	 tion 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 re-
	 trieve	 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  buf-
	 fer.	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)

NAME | SYNOPSIS | DESCRIPTION | I/O COMMAND LINE OPTIONS | DISPLAY COMMAND LINE OPTIONS | COLOR COMMAND LINE OPTIONS | RESOURCE FILE OPTIONS | EXAMPLES | NOTES | BUGS | DISTRIBUTION | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=bar&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help