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