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 Jan 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. Read lines from input instead of bytes.
 148 .It Fl L Ar size
 149 Label size.
 150 If negative, shrink to longest label width.
 151 .It Fl m
 152 Multi-input mode.
 153 Instead of reading bytes from standard input, read from a set of paths
 154 .Pq one for each label .
 155 By default, each path is processed sequentially in the order given.
 156 .It Fl n Ar num
 157 Display at-most
 158 .Ar num
 159 progress indicators per screen.
 160 If zero, display as many as possible.
 161 If negative, only display the main progress indicator.
 162 Default is 0.
 163 Maximum value is 10.
 164 .It Fl N
 165 No overrun.
 166 If enabled, stop reading known-length inputs when input reaches stated length.
 167 .It Fl o Ar file
 168 Output data to
 169 .Ar file .
 170 The first occurrence of
 171 .Ql %s
 172 .Pq if any
 173 in
 174 .Ql Ar file
 175 will be replaced with the
 176 .Ar label
 177 text.
 178 .It Fl p Ar text
 179 Display
 180 .Ar text
 181 above the file progress indicator(s).
 182 .It Fl P Ar size
 183 Mini-progressbar size.
 184 If negative, don't display mini-progressbars
 185 .Pq only the large overall progress indicator is shown .
 186 If zero, auto-adjust based on number of files to read.
 187 When zero and only one file to read, defaults to -1.
 188 When zero and more than one file to read, defaults to 17.
 189 .It Fl t Ar title
 190 Display
 191 .Ar title
 192 atop the dialog box.
 193 Note that if you use this option at the same time as
 194 .Ql Fl X
 195 and
 196 .Ql Fl b Ar backtitle ,
 197 the
 198 .Ar backtitle
 199 and
 200 .Ar title
 201 are effectively switched
 202 .Pq see BUGS section below .
 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 U Ar num
 213 Update status line
 214 .Ar num
 215 times per-second.
 216 Default value is
 217 .Ql Li 2 .
 218 A value of
 219 .Ql Li 0
 220 disables status line updates.
 221 If negative, update the status line as fast as possible.
 222 Ignored when using either
 223 .Ql Fl D
 224 or
 225 .Ql Fl X
 226 which lack the ability to display the status line
 227 .Pq containing bytes/rate/thread information .
 228 .It Fl w
 229 Wide mode.
 230 Allows long
 231 .Ar text
 232 arguments used with
 233 .Ql Fl p
 234 and
 235 .Ql Fl a
 236 to bump the dialog width.
 237 Prompts wider than the maximum width will wrap
 238 .Pq unless using Xr Xdialog 1 ; see BUGS section below .
 239 .It Fl x Ar cmd
 240 Execute
 241 .Ar cmd
 242 .Pq via Xr sh 1
 243 and send it data that has been read.
 244 Data is available to
 245 .Ar cmd
 246 on standard input.
 247 With
 248 .Ql Fl m ,
 249 .Ar cmd
 250 is executed once for each
 251 .Ar path
 252 argument.
 253 The first occurrence of
 254 .Ql %s
 255 .Pq if any
 256 in
 257 .Ql Ar cmd
 258 will be replaced with the
 259 .Ar label
 260 text.
 261 .It Fl X
 262 Enable X11 mode by using
 263 .Xr Xdialog 1
 264 instead of
 265 .Xr dialog 1
 266 or
 267 .Xr dialog 3 .
 268 .El
 269 .Sh ENVIRONMENT
 270 The following environment variables are referenced by
 271 .Nm :
 272 .Bl -tag -width ".Ev USE_COLOR"
 273 .It Ev DIALOG
 274 Override command string used to launch
 275 .Xr dialog 1
 276 .Pq requires Ql Fl D
 277 or
 278 .Xr Xdialog 1
 279 .Pq requires Ql Fl X ;
 280 default is either
 281 .Ql dialog
 282 .Pq for Ql Fl D
 283 or
 284 .Ql Xdialog
 285 .Pq for Ql Fl X .
 286 .It Ev DIALOGRC
 287 If set and non-NULL, path to
 288 .Ql .dialogrc
 289 file.
 290 .It Ev HOME
 291 If
 292 .Ql Ev $DIALOGRC
 293 is either not set or NULL, used as a prefix to
 294 .Ql .dialogrc
 295 .Pq i.e., Ql $HOME/.dialogrc .
 296 .It Ev USE_COLOR
 297 If set and NULL, disables the use of color when using
 298 .Xr dialog 1
 299 .Pq does not apply to Xr Xdialog 1 .
 300 .El
 301 .Sh DEPENDENCIES
 302 If using
 303 .Ql Fl D ,
 304 .Xr dialog 1
 305 is required.
 306 .Pp
 307 If using
 308 .Ql Fl X ,
 309 .Xr Xdialog 1
 310 is required.
 311 .Sh FILES
 312 .Bl -tag -width ".Pa $HOME/.dialogrc" -compact
 313 .It Pa $HOME/.dialogrc
 314 .El
 315 .Sh EXAMPLES
 316 .Pp
 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 .Pp
 367 .Sh BUGS
 368 .Xr Xdialog 1 ,
 369 when given both
 370 .Ql Fl -title Ar title
 371 .Pq see above Ql Fl t Ar title
 372 and
 373 .Ql Fl -backtitle Ar backtitle
 374 .Pq see above Ql Fl b Ar backtitle ,
 375 displays the backtitle in place of the title and vice-versa.
 376 .Pp
 377 .Xr Xdialog 1
 378 does not wrap long prompt texts received after initial launch.
 379 This is a known issue with the
 380 .Ql --gauge
 381 widget in
 382 .Xr Xdialog 1 .
 383 .Pp
 384 .Xr dialog 1
 385 does not display the first character after a series of escaped escape-sequences
 386 (e.g., ``\\\\n'' produces ``\\'' instead of ``\\n'').
 387 This is a known issue with
 388 .Xr dialog 1
 389 and does not affect
 390 .Xr dialog 3
 391 or
 392 .Xr Xdialog 1 .
 393 .Pp
 394 If your application ignores
 395 .Ev USE_COLOR
 396 when set and NULL before calling
 397 .Xr dpv 1
 398 with color escape sequences anyway,
 399 .Xr dialog 3
 400 and
 401 .Xr dialog 1
 402 may not render properly.
 403 Workaround is to detect when
 404 .Ev USE_COLOR
 405 is set and NULL and either not use color escape sequences at that time or use
 406 .Xr unset 1
 407 .Xr [ sh 1 ]
 408 or
 409 .Xr unsetenv 1
 410 .Xr [ csh 1 ]
 411 to unset
 412 .Ev USE_COLOR ,
 413 forcing interpretation of color sequences.
 414 This does not effect
 415 .Xr Xdialog 1 ,
 416 which renders the color escape sequences as plain text.
 417 See
 418 .Do Li
 419 embedded "\\Z" sequences
 420 .Dc
 421 in
 422 .Xr dialog 1
 423 for additional information.
 424 .Sh SEE ALSO
 425 .Xr dialog 1 ,
 426 .Xr dialog 3 ,
 427 .Xr sh 1 ,
 428 .Xr Xdialog 1
 429 .Sh HISTORY
 430 A
 431 .Nm
 432 utility first appeared in
 433 .Fx 10.2 .
 434 .Sh AUTHORS
 435 .An Devin Teske Aq dteske@FreeBSD.org