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