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
  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 ,
 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 .Pq unless using Xr Xdialog 1 ; see BUGS section below .
 253 .It Fl X
 254 Enable X11 mode by using
 255 .Xr Xdialog 1
 256 instead of
 257 .Xr dialog 1
 258 or
 259 .Xr dialog 3 .
 260 .It Fl x Ar cmd
 261 Execute
 262 .Ar cmd
 263 .Pq via Xr sh 1
 264 and send it data that has been read.
 265 Data is available to
 266 .Ar cmd
 267 on standard input.
 268 With
 269 .Ql Fl m ,
 270 .Ar cmd
 271 is executed once for each
 272 .Ar path
 273 argument.
 274 The first occurrence of
 275 .Ql %s
 276 .Pq if any
 277 in
 278 .Ql Ar cmd
 279 will be replaced with the
 280 .Ar label
 281 text.
 282 .El
 283 .Sh ENVIRONMENT
 284 The following environment variables are referenced by
 285 .Nm :
 286 .Bl -tag -width ".Ev USE_COLOR"
 287 .It Ev DIALOG
 288 Override command string used to launch
 289 .Xr dialog 1
 290 .Pq requires Ql Fl D
 291 or
 292 .Xr Xdialog 1
 293 .Pq requires Ql Fl X ;
 294 default is either
 295 .Ql dialog
 296 .Pq for Ql Fl D
 297 or
 298 .Ql Xdialog
 299 .Pq for Ql Fl X .
 300 .It Ev DIALOGRC
 301 If set and non-NULL, path to
 302 .Ql .dialogrc
 303 file.
 304 .It Ev HOME
 305 If
 306 .Ql Ev $DIALOGRC
 307 is 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
 311 If 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
 316 If using
 317 .Ql Fl D ,
 318 .Xr dialog 1
 319 is required.
 320 .Pp
 321 If using
 322 .Ql Fl X ,
 323 .Xr Xdialog 1
 324 is required.
 325 .Sh FILES
 326 .Bl -tag -width "$HOME/.dialogrc" -compact
 327 .It Pa $HOME/.dialogrc
 328 .El
 329 .Sh EXAMPLES
 330 Simple example to show how fast
 331 .Xr yes 1
 332 produces lines
 333 .Pq usually about ten-million per-second; your results may vary :
 334 .Bd -literal -offset indent
 335 yes | dpv -l yes
 336 .Ed
 337 .Pp
 338 Display progress while timing how long it takes
 339 .Xr yes 1
 340 to produce a half-billion lines
 341 .Pq usually under one minute; your results may vary :
 342 .Bd -literal -offset indent
 343 time yes | dpv -Nl 500000000:yes
 344 .Ed
 345 .Pp
 346 An example to watch how quickly a file is transferred using
 347 .Xr nc 1 :
 348 .Bd -literal -offset indent
 349 dpv -x "nc -w 1 somewhere.com 3000" -m label file
 350 .Ed
 351 .Pp
 352 A similar example, transferring a file from another process and passing the
 353 expected size to
 354 .Nm :
 355 .Bd -literal -offset indent
 356 cat file | dpv -x "nc -w 1 somewhere.com 3000" 12345:label
 357 .Ed
 358 .Pp
 359 A more complicated example:
 360 .Bd -literal -offset indent
 361 tar cf - . | dpv -x "gzip -9 > out.tgz" \\
 362         $( du -s . | awk '{print $1 * 1024}' ):label
 363 .Ed
 364 .Pp
 365 Taking an image of a disk:
 366 .Bd -literal -offset indent
 367 dpv -o disk-image.img -m label /dev/ada0
 368 .Ed
 369 .Pp
 370 Writing an image back to a disk:
 371 .Bd -literal -offset indent
 372 dpv -o /dev/ada0 -m label disk-image.img
 373 .Ed
 374 .Pp
 375 Zeroing a disk:
 376 .Bd -literal -offset indent
 377 dpv -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
 385 A
 386 .Nm
 387 utility 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 ,
 393 when given both
 394 .Ql Fl -title Ar title
 395 .Pq see above Ql Fl t Ar title
 396 and
 397 .Ql Fl -backtitle Ar backtitle
 398 .Pq see above Ql Fl b Ar backtitle ,
 399 displays the backtitle in place of the title and vice-versa.
 400 .Pp
 401 .Xr Xdialog 1
 402 does not wrap long prompt texts received after initial launch.
 403 This is a known issue with the
 404 .Ql --gauge
 405 widget in
 406 .Xr Xdialog 1 .
 407 .Pp
 408 .Xr dialog 1
 409 does not display the first character after a series of escaped escape-sequences
 410 (e.g., ``\\\\n'' produces ``\\'' instead of ``\\n'').
 411 This is a known issue with
 412 .Xr dialog 1
 413 and does not affect
 414 .Xr dialog 3
 415 or
 416 .Xr Xdialog 1 .
 417 .Pp
 418 If your application ignores
 419 .Ev USE_COLOR
 420 when set and NULL before calling
 421 .Xr dpv 1
 422 with color escape sequences anyway,
 423 .Xr dialog 3
 424 and
 425 .Xr dialog 1
 426 may not render properly.
 427 Workaround is to detect when
 428 .Ev USE_COLOR
 429 is set and NULL and either not use color escape sequences at that time or use
 430 .Xr unset 1
 431 .Xr [ sh 1 ]
 432 or
 433 .Xr unsetenv 1
 434 .Xr [ csh 1 ]
 435 to unset
 436 .Ev USE_COLOR ,
 437 forcing interpretation of color sequences.
 438 This does not effect
 439 .Xr Xdialog 1 ,
 440 which renders the color escape sequences as plain text.
 441 See
 442 .Do
 443 embedded "\\Z" sequences
 444 .Dc
 445 in
 446 .Xr dialog 1
 447 for additional information.