usr.bin/dpv/dpv.1

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