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