1CLPBAR(1) General Commands Manual CLPBAR(1)
2
6 clpbar - show information about a data transfer
7
9 clpbar
10 [ I/O-options ] [ display-options ] [ color-options ]
11 [ input-file ] [ output-file ]
12 [ -h | --help ] [ -v | --version ]
13
16 clpbar is a simple tool to process a stream of data and print a display
17 for the user on stderr showing (a) the amount of data passed, (b) the
18 throughput of the data transfer, and, if the total size of the data
19 stream is known, (c) estimated time remaining, percent complete, and a
20 progress bar.
21 clpbar was originally written for the purpose of estimating the amount
24 of time needed to transfer large amounts (many, many gigabytes) of data
25 across a network. (Usually in an SSH/tar pipe.)
26
29 -if input-file
30 --in-file input-file
31 Read input from input-file. Default: stdin
33 -of output-file
35 --out-file output-file
36 Write output to output-file. If the output file is a directory, then
38 clpbar will attempt to create a file in the output directory with the
39 same name as the input file, and attempt to copy the input file mode
40 as well as it's data. Default: stdout
41 Please notice that if no -if, --in-file, -of, or --out-file options are
43 specified on the command line, and an unknown command line option is
44 encountered, then clpbar will assume that the first unknown command
45 line option is a path to an input file, and the second (if found) is a
46 path to an output file.
47 -s size
49 --size size
50 Expect an input stream of size bytes.
52 When reading a regular file or a link to a regular file, clpbar will
54 extract the file size on it's own. However, this flag is useful for
55 reading from a character- or block-special device file, or from a
56 pipe. size may be followed by 'k', 'm', 'g', 't', 'p', or 'e' for
57 kilobytes, megabytes, gigabytes, terabytes, petabytes, or exabytes,
58 respectively (see also the -k option below). Alternatively, size may
59 also be specified in terms of 'b' for blocks (see the -bl option
60 below). See examples below.
61 -c size
63 --completed size
64 Instruct clpbar that size bytes of the data stream have already been
66 copied, and that this is a continuation of a previous data stream.
67 Note that use of this option will throw off throughput and ETA calcu‐
68 lations at first, but they should settle down as the transfer contin‐
69 ues.
70 -bs buffer-size
72 --buffer-size buffer-size
73 Allocate an I/O buffer of buffer-size bytes. The same modifiers
75 may apply here ('k', 'm', 'g', 't', 'p', 'e' and 'b') as for the -s
76 flag above. Changing the buffer size can improve throughput,
77 depending on your application of clpbar. For fast I/O operations,
78 say from a ramdisk for instance, it might be worth your while to
79 experiment with a large buffer (circa 1MB for instance). But for
80 slow I/O operations, like from a tape drive, you could merely be
81 wasting your memory. Default: 52488 (512KB)
82 -th rate
84 --throttle rate
85 Restrict I/O throughput to rate bytes per second. The same modi‐
87 fiers apply here ('k', 'm', 'g', 't', 'p', 'e' and 'b') as for the
88 -s flag above.
89 -i seconds
91 --interval seconds
92 Update the display every seconds seconds. Default: 1 second
94 -t microseconds
96 --timeout microseconds
97 The number of microseconds to wait for a change in I/O state before
99 select() times out. Default: 250000 (1/4 second)
100 -k 1000|1024
102 --kilo 1000|1024
103 Use either 1000 or 1024 as the definition of a kilobyte. Default:
105 1024
106 -bl size
108 --block-size size
109 When reading sizes from the command line that are specified in
111 terms of blocks, assume a single block is size bytes. Size may be
112 followed by 'k', 'm', 'g', 't', 'p', or 'e' for kilobytes,
113 megabytes, gigabytes, terabytes, petabytes, or exabytes, respec‐
114 tively. Block size must be set before specifying any sizes in
115 terms of blocks or the default value will be used instead. Speci‐
116 fying size in terms of 'b' for blocks is not allowed for this
117 option. Default: 512
118
121 -sw width
122 --screen-width width
123 Assume a screen width of width characters.
125 clpbar will attempt to retrieve the width of the terminal it is run‐
127 ning on, and will adjust that width if the terminal is resized. If
128 clpbar cannot determine the terminal width, then clpbar will assume a
129 default width of 79 characters. Use the --screen-width command line
130 option to override this behavior and specify a fixed width for clpbar
131 to use. (When this option is used, clpbar will ignore terminal
132 resized signals and continue to use the value provided by the user.)
133 -sw-1 | --screen-width-minus-one
135 -sw-0 | --screen-width-minus-zero
136 Instruct clpbar to use either the entire column width reported by
138 termio, or one less than reported by termio. I.e. If termio reports
139 that you are running clpbar in a terminal that's 80 characters wide,
140 using the command line option --screen-width-minus-one instructs clp‐
141 bar to only use 79 characters to print the display. If you're using
142 a terminal or shell that wraps the line whenever clpbar prints the
143 last character then this should alleviate that problem. Default is
144 to use the full terminal's width.
145 -ti string | --title string
147 Set the title to string.
148 -dti | -nti
150 --display-title | --no-title
151 Turn on/off the title display. Even if on, if no title string is set
152 then no title will be displayed. Default is on.
153 -dtw | --display-twiddle
155 -ntw | --no-twiddle
156 Turn on/off the twiddle in the display.
158 -dc | --display-count
160 -nc | --no-count
161 Turn on/off the data count in the display. Default is on.
163 -dcb | -ncb
165 --display-count-bits | --no-count-bits
166 Display the data count at bits instead of as bytes. Default is off.
167 By default clpbar will display the data count as bytes using the
169 notation of "B". Using this option, clpbar will display the through‐
170 put as bits using the notation of "b".
171 -dth | --display-throughput
173 -nth | --no-throughput
174 Turn on/off the data throughput in the display. Default is on.
176 -dthb | -nthb
178 --display-throughput-bits | --no-throughput-bits
179 Display throughput as bits/second instead of as bytes/second.
180 Default is off.
181 By default clpbar will display the throughput as bytes/second using
183 the notation of "B/s". Using this option, clpbar will display the
184 throughput as bits/second using the notation of "b/s".
185 -dt | --display-time
187 -nt | --no-time
188 Turn on/off the time elapsed or eta in the display. Default is on.
190 -de | --display-elapsed-only
192 -ne | --no-elapsed-only
193 Force clpbar to display the elapsed time instead of the eta. Default
195 is off.
196 -dp | --display-percent
198 -np | --no-percent
199 Turn on/off percent complete in the display. Default is on.
201 -db | --display-bar
203 -nb | --no-bar
204 Turn on/off the progress bar in the display. Default is on.
206 -ds | --display-summary
208 -ns | --no-summary
209 Turn on/off the summary information displayed when the operation is
211 complete. Default is on.
212 -da | --display-all
214 -dn | --display-none
215 Turn on/off all displays. -dn is equivalent to -ntw -nc -nth -nt -np
217 -nb. (Using -dn followed by -db would be equivalent to -ntw -nc -nth
218 -nt -np.) -da is equivalent to -dtw -dc -dth -dt -dp -db.
219
222 For the following color-specific command line options, the following
223 keywords are recognized as valid color names: normal, black, red,
224 green, yellow, blue, magenta, cyan, and white
225 -dan | --display-ansi
227 -nan | --no-ansi
228 Turn on/off the use of ansi color codes in the display.
230 -spbg color | --space-background color
232 Use color as the background color for spacing between display
234 objects. Default: normal
235 -twfg color | --twiddle-foreground color
237 -twbg color | --twiddle-background color
238 Use color as the twiddle color in the display. Default: normal
240 -twb | --twiddle-bold
242 -twn | --twiddle-normal
243 Turn on/off the use of bold font when displaying the twiddle.
245 Default off
246 -tifg color | --title-foreground color
248 -tibg color | --title-background color
249 Use color as the title color in the display. Default: normal
251 -tib | --title-bold
253 -tin | --title-normal
254 Turn on/off the use of bold font when displaying the title. Default
256 off
257 -cfg color | --count-foreground color
259 -cbg color | --count-background color
260 Use color as the data count color in the display. Default: normal
262 -cb | --count-bold
264 -cn | --count-normal
265 Turn on/off the use of bold font when displaying the data count.
267 Default off
268 -thlfg color | --throughput-label-foreground color
270 -thlbg color | --throughput-label-background color
271 Use color as the throughput label color in the display. Default:
273 normal
274 -thlb | --throughput-label-bold
276 -thln | --throughput-label-normal
277 Turn on/off the use of bold font when displaying the throughput
279 label. Default off
280 -thfg color | --throughput-foreground color
282 -thbg color | --throughput-background color
283 Use color as the throughput color in the display. Default: normal
285 -thb | --throughput-bold
287 -thn | --throughput-normal
288 Turn on/off the use of bold font when displaying the throughput.
290 Default off
291 -tlfg color | --time-label-foreground color
293 -tlbg color | --time-label-background color
294 Use color as the time label color in the display. Default: normal
296 -tlb | --time-label-bold
298 -tln | --time-label-normal
299 Turn on/off the use of bold font when displaying the time label.
301 Default off
302 -tfg color | --time-foreground color
304 -tbg color | --time-background color
305 Use color as the time color in the display. Default: normal
307 -tb | --time-bold
309 -tn | --time-normal
310 Turn on/off the use of bold font when displaying the time. Default
312 off
313 -pfg color | --percent-foreground color
315 -pbg color | --percent-background color
316 Use color as the percent color in the display. Default: normal
318 -pb | --percent-bold
320 -pn | --percent-normal
321 Turn on/off the use of bold font when displaying the percent.
323 Default off
324 -bbfg color | --bar-brace-foreground color
326 -bbbg color | --bar-brace-background color
327 Use color as the brace color around the progress bar in the display.
329 Default: normal
330 -bbb | --bar-brace-bold
332 -bbn | --bar-brace-normal
333 Turn on/off the use of bold font when displaying the bar braces.
335 Default off
336 -bfg color | --bar-foreground color
338 -bbg color | --bar-background color
339 Use color as the color of the progress bar in the display. Default:
341 normal
342 -bb | --bar-bold
344 -bn | --bar-normal
345 Turn on/off the use of bold font when displaying the progress bar.
347 Default off
348 -h | --help
350 Display this text and exit.
352 -v | --version
354 Display the program version and exit.
356
359 Some command line options may be specified in a resource file. clpbar
360 will search for a resource file by the name of ~/.clpbarrc and, if
361 found, clpbar will use the values within by default. In addition, clp‐
362 bar will also search for a file in the directory in which it is run,
363 ./.clpbarrc. If this file exists, it's values will override the values
364 found in ~/.clpbarrc. Values in both files may be overridden by com‐
365 mand line flags. Lines that begin with a # are ignored.
366 For resource options requiring a boolean value, the following values
369 are recognized: on and off, yes and no, (and the single-character
370 abbreviations y and n), true and false, (and the single-character
371 abbreviations t and f), 0 and 1.
372 For resource options requiring a color value, the same keywords are
375 recognized as for the color-specific command line options above: nor‐
376 mal, black, red, green, yellow, blue, magenta, cyan, and white
377 buffer-size: buffer-size
379 Allocate an I/O buffer of buffer-size bytes. See the --buffer-size
381 command line option above.
382 throttle: rate
384 Restrict I/O throughput to rate bytes per second. See the --throttle
386 command line option above.
387 interval: seconds
389 Update the display every seconds seconds. See the --interval command
391 line option above.
392 timeout: microseconds
394 The number of microseconds to wait for a change in I/O state before
396 select() times out. See the --timeout command line option above.
397 kilobyte: 1000|1024
399 Use either 1000 or 1024 as the definition of a kilobyte. See the
401 --kilo command line option above.
402 block-size: size
404 When parsing sizes specified in terms of blocks, assume a single
405 block is size bytes. See the --block-size command line option above.
406 screen-width: width
408 Override termio and assume that the screen is width characters wide.
410 See the --screen-width command line option above.
411 screen-width-minus-one: boolean
413 Instruct clpbar to restrict the number of columns reported by termio
415 by one. See the --screen-width-minus-one command line option above.
416 display-twiddle: boolean
418 Instruct clpbar to turn on/off the twirling twiddle character in the
420 display. See the --display-twiddle command line option above.
421 display-title: boolean
423 Instruct clpbar to turn on/off the title in the display. See the
425 --display-title command line option above.
426 display-count: boolean
428 Instruct clpbar to turn on/off the data count in the display. See
430 the --display-count command line option above.
431 display-count-bits: boolean
433 Display the data count as bits instead of as bytes. See the --dis‐
435 play-count-bits command line option above.
436 display-throughput: boolean
438 Instruct clpbar to turn on/off the data throughput in the display.
440 See the --display-throughput command line option above.
441 display-throughput-bits: boolean
443 Display throughput as bits/sec instead of as bytes/sec. See the
445 --display-throughput-bits command line option above.
446 display-time: boolean
448 Instruct clpbar to turn on/off the time in the display. See the
450 --display-time command line option above.
451 display-elapsed-only: boolean
453 Force clpbar to display the elapsed time instead of the eta. See the
455 --display-elapsed-only command line option above.
456 display-percent: boolean
458 Instruct clpbar to turn on/off the percent complete in the display.
460 See the --display-percent command line option above.
461 display-bar: boolean
463 Instruct clpbar to turn on/off the progress bar in the display. See
465 the --display-bar command line option above.
466 display-summary: boolean
468 Instruct clpbar to turn on/off the summary information displayed when
470 operation is complete. See the --display-summary command line option
471 above.
472 display-ansi: boolean
474 Instruct clpbar to turn on/off the use of ansi color codes in the
476 display. See the --display-ansi command line option above.
477 space-background: color
479 Use color as the background color for spacing between display
481 objects. See the --space-background command line option above.
482 twiddle-foreground: color
484 twiddle-background: color
485 twiddle-bold: boolean
486 Use the specified colors for the foreground and background of the
488 twiddle, and use a bold font. See the --twiddle-foreground, --twid‐
489 dle-background, and --twiddle-bold command line options above.
490 title: string
492 Set the title string for the display. See the --title command line
494 option above.
495 title-foreground: color
497 title-background: color
498 title-bold: boolean
499 Use the specified colors for the foreground and background of the
501 title, and use a bold font. See the --title-foreground, --title-
502 background, and --title-bold command line options above.
503 count-foreground: color
505 count-background: color
506 count-bold: boolean
507 Use the specified colors for the foreground and background of the
509 data count, and use a bold font. See the --count-foreground,
510 --count-background, and --count-bold command line options above.
511 throughput-label-foreground: color
513 throughput-label-background: color
514 throughput-label-bold: boolean
515 Use the specified colors for the foreground and background of the
517 throughput label, and use a bold font. See the --throughput-label-
518 foreground, --throughput-label-background, and --throughput-label-
519 bold command line options above.
520 throughput-foreground: color
522 throughput-background: color
523 throughput-bold: boolean
524 Use the specified colors for the foreground and background of the
526 throughput, and use a bold font. See the --throughput-foreground,
527 --throughput-background, and --throughput-bold command line options
528 above.
529 time-label-foreground: color
531 time-label-background: color
532 time-label-bold: boolean
533 Use the specified colors for the foreground and background of the
535 time label, and use a bold font. See the --time-label-foreground,
536 --time-label-background, and --time-label-bold command line options
537 above.
538 time-foreground: color
540 time-background: color
541 time-bold: boolean
542 Use the specified colors for the foreground and background of the
544 time, and use a bold font. See the --time-foreground, --time-back‐
545 ground, and --time-bold command line options above.
546 percent-foreground: color
548 percent-background: color
549 percent-bold: boolean
550 Use the specified colors for the foreground and background of the
552 percent, and use a bold font. See the --percent-foreground, --per‐
553 cent-background, and --percent-bold command line options above.
554 bar-brace-foreground: color
556 bar-brace-background: color
557 bar-brace-bold: boolean
558 Use the specified colors for the foreground and background of the
560 brace surrounding the progress bar, and use a bold font. See the
561 --bar-brace-foreground, --bar-brace-background, and --bar-brace-bold
562 command line options above.
563 bar-foreground: color
565 bar-background: color
566 bar-bold: boolean
567 Use the specified colors for the foreground and background of the
568 progress bar, and use a bold font. See the --bar-foreground, --bar-
569 background, and --bar-bold command line options above.
570
573 Example 1: Using clpbar to copy a 2.4gb file from a device (in this
574 case a tape drive) to a file, using a 64k buffer.
575 prompt% clpbar --in-file /dev/rmt/1cbn --out-file \
578 tape-restore.tar --size 2.4g --buffer-size 64k
579 Example 2: Using clpbar to copy a 37tb file across the network using
582 SSH.
583 prompt% ssh remote 'dd if=file' | clpbar --size 37t > file
586 Example 3: Using clpbar inside a tar-pipe command:
589 Normal tar-pipe command might be:
592 prompt% (cd /some/dir/somewhere && tar -cf - *) \
595 | (cd /some/other/dir && tar -xBpf -)
596 3a: Using clpbar within the tar-pipe:
599 prompt% (cd /some/dir/somewhere && tar -cf - *) \
602 | clpbar \
603 | (cd /some/other/dir && tar -xBpf -)
604 3b: Using clpbar with the --size option in a tar-pipe:
607 prompt% du -sk /some/dir/somewhere
610 6281954 /some/dir/somewhere
611 prompt% (cd /some/dir/somewhere && tar -cf - *) \
613 | clpbar --size 6281954k \
614 | (cd /some/other/dir && tar -xBpf -)
615 Example 4: Using clpbar on a regular file. (Note that the --size
618 option is not needed here, as clpbar will retrieve the file size
619 itself.)
620 prompt% clpbar --in-file ./file | ssh remote 'cd /some/dir && dd
623 of=file'
624 Example 5: Generating a 512k file of random data.
627 prompt% dd if=/dev/random bs=1024 count=512 \
630 | clpbar -s 512k -of ./random
631 Example 6: An example .clpbarrc file.
634 #
635 # This is an example of what a ~/.clpbarrc file
636 # might look like. Note that lines beginning
637 # with a # are ignored.
638 #
639 display-twiddle: no
640 display-ansi: yes
641 # space-background: black
642 twiddle-foreground: green
643 # twiddle-background: normal
644 # twiddle-bold: no
645 count-foreground: green
646 # count-background: magenta
647 count-bold: yes
648 throughput-label-foreground: normal
649 # throughput-label-background: red
650 throughput-label-bold: no
651 throughput-foreground: green
652 # throughput-background: black
653 throughput-bold: yes
654 time-label-foreground: normal
655 # time-label-background: red
656 time-label-bold: no
657 time-foreground: green
658 # time-background: black
659 time-bold: yes
660 percent-foreground: green
661 # percent-background: green
662 percent-bold: yes
663 bar-brace-foreground: red
664 # bar-brace-background: blue
665 bar-brace-bold: no
666 bar-foreground: yellow
667 # bar-background: blue
668 bar-bold: yes
669
672 - The --size option is only used by clpbar in calculating information
673 about the data transfer. clpbar will not cease copying data once it
674 has reached the number of bytes specified with the --size option, but
675 instead clpbar will continue to copy data until and end of input is
676 reached. If this behavior is undesirable then clpbar may be used in
677 conjunction with dd, where the count option is used with dd to spec‐
678 ify when to cut off the input stream. (See examples above.)
679 - When using other commands such as du -k to calculate the expected
682 size of a data transfer stream, the value returned may not be exactly
683 the number of bytes counted by clpbar in the actual data transfer.
684 Common causes for this discrepancy could be attributed to round-off
685 error or the use of 1000 bytes as a kilobyte rather than 1024. (If
686 the later is the case, then using the -k 1000 option to clpbar will
687 help.) When such discrepancies occur, clpbar may report that the
688 data stream contained only 98% or as much as 101% of it's expected
689 size. (If you have doubts, you should definitely verify your data
690 using md5sum, diff, or cmp.)
691 - When the value of a calculation exceeds the size alloted for the dis‐
694 play, the value +99... will be substituted in it's place. The com‐
695 plete value will be displayed in a summary statement after clpbar has
696 reached the end of input.
697 - clpbar assumes a linear relationship between the speed of the data
700 transfer and the amount of time remaining. Specifically the calcula‐
701 tion is based on the following:
702 elapsed time / eta = bytes written / total size
704 However, it has been the author's experience that the throughput
706 speed will change, particularly at the beginning of the transfer, and
707 this will affect the estimated time remaining. The author does not
708 believe this is a bug, but a side-effect of this method of calcula‐
709 tion.
710 - clpbar assumes that there are 8 bits in both a byte and a char.
713
716 - clpbar uses the open() and fstat() functions to open and retrieve the
717 size of regular files when using either the --in-file or --out-file
718 command line options. Some OS's do not support Large Files (file
719 sizes up to (2**63)-1 bytes) natively. Some OS's support Large Files
720 but require _FILE_OFFSET_BITS or _LARGE_FILES to be defined properly
721 at compile time. Other OS's support neither, but still allow pro‐
722 grams to open files in excess of (2**32)-1 through an O_LARGEFILE
723 option that can be passed to the open() function.
724 When trying to open files greater than 2gb on an OS without Large
726 File support, clpbar will exit with the message: "File too large".
727 When trying to write more than 2gb of data to a file, clpbar will
728 write 2**32-1 bytes and then the OS may terminate clpbar with a mes‐
729 sage similar to: "File size limit exceeded".
730 When trying to open files greater than 2gb on an OS without Large
732 File support, but with the O_LARGEFILE option that can be passed to
733 open(), clpbar will receive an error when trying to retrieve the
734 file's size, but clpbar will be able to open the file anyway. Under
735 these circumstances, clpbar will print a "File too large" error mes‐
736 sage, but will then proceed to transfer the data. Since clpbar will
737 not be able to retrieve the file's size on it's own, the --size com‐
738 mand line option must be used after the --in-file option to tell clp‐
739 bar the file size manually. On such OS's, clpbar should be able to
740 write more than 2gb of data to a file without any problems.
741 For OS's that support files greater than 2gb, either natively or
743 through the Large File extension definitions mentioned above, clpbar
744 should work as expected.
745 - The author has noticed that when running clpbar over an SSH connec‐
748 tion, sometimes window resize events are not captured until after the
749 display has gone through one or two more updates, which can cause the
750 line to wrap.
751 - The author has noticed that on some systems the use of aligned memory
754 allocation, through either memalign() or posix_memalign(), causes
755 clpbar to commit a segmentation fault the first time read() or
756 readv() is called and passed a pointer to the aligned memory as it's
757 input buffer. Attempts were made to try to isolate systems in which
758 this bug bites through tests in configure, but all tests devised
759 passed with flying colors. Therefore aligned memory allocation is
760 turned off by default, and may only be enabled by passing --enable-
761 use-memalign to configure when building the executable.
762 Report all bugs to the author.
765 clpbar was developed on a Sun workstation running Solaris 8. To the
768 best of the author's knowledge clpbar should compile and run on other
769 platforms without much trouble. Should other OS's require modifica‐
770 tions to the code, the author welcomes all patch submissions, but
771 requests that you include the file config.log and the output of gcc
772 -dumpspecs (or a listing of predefined variables, if not using gcc).
773
776 The latest version of clpbar can always be found at:
777 http://www.freshmeat.net/projects/commandlineprogressbar
778 http://sourceforge.net/projects/clpbar/
779
782 clpbar was written by Michael Peek. See DISTRIBUTION above for contact
783 information.
784 Occasionally, the author fancies that he knows what he's doing. It is
786 at these times more than ever that his coworkers should cower in
787 fear...
788 4 November 2003 CLPBAR(1)