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 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 , 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 252.Pq unless using Xr Xdialog 1 ; see BUGS section below . 253.It Fl X 254Enable X11 mode by using 255.Xr Xdialog 1 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 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 313.Pq does not apply to Xr Xdialog 1 . 314.El 315.Sh DEPENDENCIES 316If using 317.Ql Fl D , 318.Xr dialog 1 319is required. 320.Pp 321If using 322.Ql Fl X , 323.Xr Xdialog 1 324is required. 325.Sh FILES 326.Bl -tag -width "$HOME/.dialogrc" -compact 327.It Pa $HOME/.dialogrc 328.El 329.Sh EXAMPLES 330Simple example to show how fast 331.Xr yes 1 332produces lines 333.Pq usually about ten-million per-second; your results may vary : 334.Bd -literal -offset indent 335yes | dpv -l yes 336.Ed 337.Pp 338Display progress while timing how long it takes 339.Xr yes 1 340to produce a half-billion lines 341.Pq usually under one minute; your results may vary : 342.Bd -literal -offset indent 343time yes | dpv -Nl 500000000:yes 344.Ed 345.Pp 346An example to watch how quickly a file is transferred using 347.Xr nc 1 : 348.Bd -literal -offset indent 349dpv -x "nc -w 1 somewhere.com 3000" -m label file 350.Ed 351.Pp 352A similar example, transferring a file from another process and passing the 353expected size to 354.Nm : 355.Bd -literal -offset indent 356cat file | dpv -x "nc -w 1 somewhere.com 3000" 12345:label 357.Ed 358.Pp 359A more complicated example: 360.Bd -literal -offset indent 361tar cf - . | dpv -x "gzip -9 > out.tgz" \\ 362 $( du -s . | awk '{print $1 * 1024}' ):label 363.Ed 364.Pp 365Taking an image of a disk: 366.Bd -literal -offset indent 367dpv -o disk-image.img -m label /dev/ada0 368.Ed 369.Pp 370Writing an image back to a disk: 371.Bd -literal -offset indent 372dpv -o /dev/ada0 -m label disk-image.img 373.Ed 374.Pp 375Zeroing a disk: 376.Bd -literal -offset indent 377dpv -o /dev/md42 "Zeroing md42" < /dev/zero 378.Ed 379.Sh SEE ALSO 380.Xr dialog 1 , 381.Xr sh 1 , 382.Xr Xdialog 1 , 383.Xr dialog 3 384.Sh HISTORY 385A 386.Nm 387utility first appeared in 388.Fx 10.2 . 389.Sh AUTHORS 390.An Devin Teske Aq dteske@FreeBSD.org 391.Sh BUGS 392.Xr Xdialog 1 , 393when given both 394.Ql Fl -title Ar title 395.Pq see above Ql Fl t Ar title 396and 397.Ql Fl -backtitle Ar backtitle 398.Pq see above Ql Fl b Ar backtitle , 399displays the backtitle in place of the title and vice-versa. 400.Pp 401.Xr Xdialog 1 402does not wrap long prompt texts received after initial launch. 403This is a known issue with the 404.Ql --gauge 405widget in 406.Xr Xdialog 1 . 407.Pp 408.Xr dialog 1 409does not display the first character after a series of escaped escape-sequences 410(e.g., ``\\\\n'' produces ``\\'' instead of ``\\n''). 411This is a known issue with 412.Xr dialog 1 413and does not affect 414.Xr dialog 3 415or 416.Xr Xdialog 1 . 417.Pp 418If your application ignores 419.Ev USE_COLOR 420when set and NULL before calling 421.Xr dpv 1 422with color escape sequences anyway, 423.Xr dialog 3 424and 425.Xr dialog 1 426may not render properly. 427Workaround is to detect when 428.Ev USE_COLOR 429is set and NULL and either not use color escape sequences at that time or use 430.Xr unset 1 431.Xr [ sh 1 ] 432or 433.Xr unsetenv 1 434.Xr [ csh 1 ] 435to unset 436.Ev USE_COLOR , 437forcing interpretation of color sequences. 438This does not effect 439.Xr Xdialog 1 , 440which renders the color escape sequences as plain text. 441See 442.Do 443embedded "\\Z" sequences 444.Dc 445in 446.Xr dialog 1 447for additional information. 448