1 .\" Copyright (c) 2013-2015 Devin Teske 2 .\" All rights reserved. 3 .\" 4 .\" Redistribution and use in source and binary forms, with or without 5 .\" modification, are permitted provided that the following conditions 6 .\" are met: 7 .\" 1. Redistributions of source code must retain the above copyright 8 .\" notice, this list of conditions and the following disclaimer. 9 .\" 2. Redistributions in binary form must reproduce the above copyright 10 .\" notice, this list of conditions and the following disclaimer in the 11 .\" documentation and/or other materials provided with the distribution. 12 .\" 13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23 .\" SUCH DAMAGE. 24 .\" 25 .\" $FreeBSD$ 26 .\" 27 .Dd Oct 22, 2015 28 .Dt DPV 1 29 .Os 30 .Sh NAME 31 .Nm dpv 32 .Nd stream data from stdin or multiple paths with dialog progress view 33 .Sh SYNOPSIS 34 .Nm 35 .Op options 36 .Ar [bytes:]label 37 .Nm 38 .Op options 39 .Fl m 40 .Ar [bytes1:]label1 41 .Ar path1 42 .Op Ar [bytes2:]label2 path2 ... 43 .Sh DESCRIPTION 44 .Nm 45 provides a dialog progress view, allowing a user to see current throughput rate 46 and total data transferred for one or more streams. 47 .Pp 48 The 49 .Nm 50 utility has two main modes for processing input. 51 .Pp 52 The default input mode, without 53 .Ql Fl m , 54 .Nm 55 reads bytes from standard input. 56 A label for the data must be provided. 57 .Pp 58 The secondary input mode, with 59 .Ql Fl m , 60 .Nm 61 reads multiple paths 62 .Pq up to 2047 or Dq ARG_MAX/2-1 , 63 sequentially. 64 .Pp 65 Data read in either mode is either thrown away 66 .Pq default , 67 sent to a spawned instance of the program specified via 68 .Ql Fl x Ar cmd , 69 or sent to a unique file specified by 70 .Ql Fl o Ar file . 71 .Pp 72 With or without 73 .Ql Fl m , 74 progress is displayed using one of 75 .Xr dialog 3 76 .Pq default , 77 .Xr dialog 1 78 .Pq see Ql Fl D , 79 or instead 80 .Xr Xdialog 1 81 .Pq see Ql Fl X . 82 .Pp 83 The following options are available: 84 .Bl -tag -width ".Fl b Ar backtitle" 85 .It Fl a Ar text 86 Display 87 .Ar text 88 below the file progress indicator(s). 89 .It Fl b Ar backtitle 90 Display 91 .Ar backtitle 92 on the backdrop, at top-left, behind the dialog widget. 93 When using 94 .Xr Xdialog 1 , 95 this is displayed inside the window 96 .Pq at the top 97 followed by a separator line. 98 .It Fl d 99 Debug mode. 100 Print dialog prompt data to standard out and provide additional debugging on 101 standard error. 102 .It Fl D 103 Do not use the default interface of 104 .Xr dialog 3 , 105 but instead spawn an instance of 106 .Xr dialog 1 . 107 The path to 108 .Xr dialog 1 109 is taken from the 110 .Ev DIALOG 111 environment variable or simply 112 .Dq Li dialog 113 if unset or NULL. 114 .It Fl h 115 Produce a short syntax usage with brief option descriptions and exit. 116 Output is produced on standard error. 117 .It Fl i Ar format 118 Customize the single-file format string used to update the status line. 119 Ignored when using either 120 .Ql Fl D 121 or 122 .Ql Fl X 123 which lack the ability to display the status line 124 .Pq containing bytes/rate/thread information . 125 Default value 126 is 127 .Dq Li %'10lli bytes read @ %'9.1f bytes/sec. . 128 This format is used when handling one file. 129 .It Fl I Ar format 130 Customize the multi-file format string used to update the status line. 131 Ignored when using either 132 .Ql Fl D 133 or 134 .Ql Fl X 135 which lack the ability to display the status line 136 .Pq containing bytes/rate/thread information . 137 Default value 138 is 139 .Dq Li %'10lli bytes read @ %'9.1f bytes/sec. [%i/%i busy/wait] . 140 This format is used when handling more than one file. 141 .It Fl l 142 Line mode. Read lines from input instead of bytes. 143 .It Fl L Ar size 144 Label size. 145 If negative, shrink to longest label width. 146 .It Fl m 147 Multi-input mode. 148 Instead of reading bytes from standard input, read from a set of paths 149 .Pq one for each label . 150 By default, each path is processed sequentially in the order given. 151 .It Fl n Ar num 152 Display at-most 153 .Ar num 154 progress indicators per screen. 155 If zero, display as many as possible. 156 If negative, only display the main progress indicator. 157 Default is 0. 158 Maximum value is 10. 159 .It Fl N 160 No overrun. 161 If enabled, stop reading known-length inputs when input reaches stated length. 162 .It Fl o Ar file 163 Output data to 164 .Ar file . 165 The first occurrence of 166 .Ql %s 167 .Pq if any 168 in 169 .Ql Ar file 170 will be replaced with the 171 .Ar label 172 text. 173 .It Fl p Ar text 174 Display 175 .Ar text 176 above the file progress indicator(s). 177 .It Fl P Ar size 178 Mini-progressbar size. 179 If negative, don't display mini-progressbars 180 .Pq only the large overall progress indicator is shown . 181 If zero, auto-adjust based on number of files to read. 182 When zero and only one file to read, defaults to -1. 183 When zero and more than one file to read, defaults to 17. 184 .It Fl t Ar title 185 Display 186 .Ar title 187 atop the dialog box. 188 Note that if you use this option at the same time as 189 .Ql Fl X 190 and 191 .Ql Fl b Ar backtitle , 192 the 193 .Ar backtitle 194 and 195 .Ar title 196 are effectively switched 197 .Pq see BUGS section below . 198 .It Fl T 199 Test mode. 200 Simulate reading a number of bytes, divided evenly across the number of files, 201 while stepping through each percent value of each file to process. 202 Appends 203 .Dq Li [TEST MODE] 204 to the status line 205 .Pq to override, use Ql Fl u Ar format . 206 No data is actually read. 207 .It Fl U Ar num 208 Update status line 209 .Ar num 210 times per-second. 211 Default value is 212 .Ql Li 2 . 213 A value of 214 .Ql Li 0 215 disables status line updates. 216 If negative, update the status line as fast as possible. 217 Ignored when using either 218 .Ql Fl D 219 or 220 .Ql Fl X 221 which lack the ability to display the status line 222 .Pq containing bytes/rate/thread information . 223 .It Fl w 224 Wide mode. 225 Allows long 226 .Ar text 227 arguments used with 228 .Ql Fl p 229 and 230 .Ql Fl a 231 to bump the dialog width. 232 Prompts wider than the maximum width will wrap 233 .Pq unless using Xr Xdialog 1 ; see BUGS section below . 234 .It Fl x Ar cmd 235 Execute 236 .Ar cmd 237 .Pq via Xr sh 1 238 and send it data that has been read. 239 Data is available to 240 .Ar cmd 241 on standard input. 242 With 243 .Ql Fl m , 244 .Ar cmd 245 is executed once for each 246 .Ar path 247 argument. 248 The first occurrence of 249 .Ql %s 250 .Pq if any 251 in 252 .Ql Ar cmd 253 will be replaced with the 254 .Ar label 255 text. 256 .It Fl X 257 Enable X11 mode by using 258 .Xr Xdialog 1 259 instead of 260 .Xr dialog 1 261 or 262 .Xr dialog 3 . 263 .El 264 .Sh ENVIRONMENT 265 The following environment variables are referenced by 266 .Nm : 267 .Bl -tag -width ".Ev USE_COLOR" 268 .It Ev DIALOG 269 Override command string used to launch 270 .Xr dialog 1 271 .Pq requires Ql Fl D 272 or 273 .Xr Xdialog 1 274 .Pq requires Ql Fl X ; 275 default is either 276 .Ql dialog 277 .Pq for Ql Fl D 278 or 279 .Ql Xdialog 280 .Pq for Ql Fl X . 281 .It Ev DIALOGRC 282 If set and non-NULL, path to 283 .Ql .dialogrc 284 file. 285 .It Ev HOME 286 If 287 .Ql Ev $DIALOGRC 288 is either not set or NULL, used as a prefix to 289 .Ql .dialogrc 290 .Pq i.e., Ql $HOME/.dialogrc . 291 .It Ev USE_COLOR 292 If set and NULL, disables the use of color when using 293 .Xr dialog 1 294 .Pq does not apply to Xr Xdialog 1 . 295 .El 296 .Sh DEPENDENCIES 297 If using 298 .Ql Fl D , 299 .Xr dialog 1 300 is required. 301 .Pp 302 If using 303 .Ql Fl X , 304 .Xr Xdialog 1 305 is required. 306 .Sh FILES 307 .Bl -tag -width ".Pa $HOME/.dialogrc" -compact 308 .It Pa $HOME/.dialogrc 309 .El 310 .Sh EXAMPLES 311 Simple example to show how fast 312 .Xr yes 1 313 produces lines 314 .Pq usually about ten-million per-second; your results may vary : 315 .Bd -literal -offset indent 316 yes | dpv -l yes 317 .Ed 318 .Pp 319 Display progress while timing how long it takes 320 .Xr yes 1 321 to produce a half-billion lines 322 .Pq usually under one minute; your results may vary : 323 .Bd -literal -offset indent 324 time yes | dpv -Nl 500000000:yes 325 .Ed 326 .Pp 327 An example to watch how quickly a file is transferred using 328 .Xr nc 1 : 329 .Bd -literal -offset indent 330 dpv -x "nc -w 1 somewhere.com 3000" -m label file 331 .Ed 332 .Pp 333 A similar example, transferring a file from another process and passing the 334 expected size to 335 .Nm : 336 .Bd -literal -offset indent 337 cat file | dpv -x "nc -w 1 somewhere.com 3000" 12345:label 338 .Ed 339 .Pp 340 A more complicated example: 341 .Bd -literal -offset indent 342 tar cf - . | dpv -x "gzip -9 > out.tgz" \\ 343 $( du -s . | awk '{print $1 * 1024}' ):label 344 .Ed 345 .Pp 346 Taking an image of a disk: 347 .Bd -literal -offset indent 348 dpv -o disk-image.img -m label /dev/ada0 349 .Ed 350 .Pp 351 Writing an image back to a disk: 352 .Bd -literal -offset indent 353 dpv -o /dev/ada0 -m label disk-image.img 354 .Ed 355 .Pp 356 Zeroing a disk: 357 .Bd -literal -offset indent 358 dpv -o /dev/md42 < /dev/zero 359 .Ed 360 .Sh SEE ALSO 361 .Xr dialog 1 , 362 .Xr sh 1 , 363 .Xr Xdialog 1 , 364 .Xr dialog 3 365 .Sh HISTORY 366 A 367 .Nm 368 utility first appeared in 369 .Fx 10.2 . 370 .Sh AUTHORS 371 .An Devin Teske Aq dteske@FreeBSD.org 372 .Sh BUGS 373 .Xr Xdialog 1 , 374 when given both 375 .Ql Fl -title Ar title 376 .Pq see above Ql Fl t Ar title 377 and 378 .Ql Fl -backtitle Ar backtitle 379 .Pq see above Ql Fl b Ar backtitle , 380 displays the backtitle in place of the title and vice-versa. 381 .Pp 382 .Xr Xdialog 1 383 does not wrap long prompt texts received after initial launch. 384 This is a known issue with the 385 .Ql --gauge 386 widget in 387 .Xr Xdialog 1 . 388 .Pp 389 .Xr dialog 1 390 does not display the first character after a series of escaped escape-sequences 391 (e.g., ``\\\\n'' produces ``\\'' instead of ``\\n''). 392 This is a known issue with 393 .Xr dialog 1 394 and does not affect 395 .Xr dialog 3 396 or 397 .Xr Xdialog 1 . 398 .Pp 399 If your application ignores 400 .Ev USE_COLOR 401 when set and NULL before calling 402 .Xr dpv 1 403 with color escape sequences anyway, 404 .Xr dialog 3 405 and 406 .Xr dialog 1 407 may not render properly. 408 Workaround is to detect when 409 .Ev USE_COLOR 410 is set and NULL and either not use color escape sequences at that time or use 411 .Xr unset 1 412 .Xr [ sh 1 ] 413 or 414 .Xr unsetenv 1 415 .Xr [ csh 1 ] 416 to unset 417 .Ev USE_COLOR , 418 forcing interpretation of color sequences. 419 This does not effect 420 .Xr Xdialog 1 , 421 which renders the color escape sequences as plain text. 422 See 423 .Do 424 embedded "\\Z" sequences 425 .Dc 426 in 427 .Xr dialog 1 428 for additional information. 429