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