usr.bin/dpv/dpv.1

   1 .\" Copyright (c) 2013-2014 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 Sep 7, 2014
  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 l
 142 Line mode. Read lines from input instead of bytes.
 143 .It Fl L Ar size
 144 Label size.
 145 If negative, shrink to longest label width.
 146 .It Fl m
 147 Multi-input mode.
 148 Instead of reading bytes from standard input, read from a set of paths
 149 .Pq one for each label .
 150 By default, each path is processed sequentially in the order given.
 151 .It Fl n Ar num
 152 Display at-most
 153 .Ar num
 154 progress indicators per screen.
 155 If zero, display as many as possible.
 156 If negative, only display the main progress indicator.
 157 Default is 0.
 158 Maximum value is 10.
 159 .It Fl N
 160 No overrun.
 161 If enabled, stop reading known-length inputs when input reaches stated length.
 162 .It Fl o Ar file
 163 Output data to
 164 .Ar file .
 165 The first occurrence of
 166 .Ql %s
 167 .Pq if any
 168 in
 169 .Ql Ar file
 170 will be replaced with the
 171 .Ar label
 172 text.
 173 .It Fl p Ar text
 174 Display
 175 .Ar text
 176 above the file progress indicator(s).
 177 .It Fl P Ar size
 178 Mini-progressbar size.
 179 If negative, don't display mini-progressbars
 180 .Pq only the large overall progress indicator is shown .
 181 If zero, auto-adjust based on number of files to read.
 182 When zero and only one file to read, defaults to -1.
 183 When zero and more than one file to read, defaults to 17.
 184 .It Fl t Ar title
 185 Display
 186 .Ar title
 187 atop the dialog box.
 188 Note that if you use this option at the same time as
 189 .Ql Fl X
 190 and
 191 .Ql Fl b Ar backtitle ,
 192 the
 193 .Ar backtitle
 194 and
 195 .Ar title
 196 are effectively switched
 197 .Pq see BUGS section below .
 198 .It Fl T
 199 Test mode.
 200 Simulate reading a number of bytes, divided evenly across the number of files,
 201 while stepping through each percent value of each file to process.
 202 Appends
 203 .Dq Li [TEST MODE]
 204 to the status line
 205 .Pq to override, use Ql Fl u Ar format .
 206 No data is actually read.
 207 .It Fl U Ar num
 208 Update status line
 209 .Ar num
 210 times per-second.
 211 Default value is
 212 .Ql Li 2 .
 213 A value of
 214 .Ql Li 0
 215 disables status line updates.
 216 If negative, update the status line as fast as possible.
 217 Ignored when using either
 218 .Ql Fl D
 219 or
 220 .Ql Fl X
 221 which lack the ability to display the status line
 222 .Pq containing bytes/rate/thread information .
 223 .It Fl w
 224 Wide mode.
 225 Allows long
 226 .Ar text
 227 arguments used with
 228 .Ql Fl p
 229 and
 230 .Ql Fl a
 231 to bump the dialog width.
 232 Prompts wider than the maximum width will wrap
 233 .Pq unless using Xr Xdialog 1 ; see BUGS section below .
 234 .It Fl x Ar cmd
 235 Execute
 236 .Ar cmd
 237 .Pq via Xr sh 1
 238 and send it data that has been read.
 239 Data is available to
 240 .Ar cmd
 241 on standard input.
 242 With
 243 .Ql Fl m ,
 244 .Ar cmd
 245 is executed once for each
 246 .Ar path
 247 argument.
 248 The first occurrence of
 249 .Ql %s
 250 .Pq if any
 251 in
 252 .Ql Ar cmd
 253 will be replaced with the
 254 .Ar label
 255 text.
 256 .It Fl X
 257 Enable X11 mode by using
 258 .Xr Xdialog 1
 259 instead of
 260 .Xr dialog 1
 261 or
 262 .Xr dialog 3 .
 263 .El
 264 .Sh ENVIRONMENT
 265 The following environment variables are referenced by
 266 .Nm :
 267 .Bl -tag -width ".Ev USE_COLOR"
 268 .It Ev DIALOG
 269 Override command string used to launch
 270 .Xr dialog 1
 271 .Pq requires Ql Fl D
 272 or
 273 .Xr Xdialog 1
 274 .Pq requires Ql Fl X ;
 275 default is either
 276 .Ql dialog
 277 .Pq for Ql Fl D
 278 or
 279 .Ql Xdialog
 280 .Pq for Ql Fl X .
 281 .It Ev DIALOGRC
 282 If set and non-NULL, path to
 283 .Ql .dialogrc
 284 file.
 285 .It Ev HOME
 286 If
 287 .Ql Ev $DIALOGRC
 288 is either not set or NULL, used as a prefix to
 289 .Ql .dialogrc
 290 .Pq i.e., Ql $HOME/.dialogrc .
 291 .It Ev USE_COLOR
 292 If set and NULL, disables the use of color when using
 293 .Xr dialog 1
 294 .Pq does not apply to Xr Xdialog 1 .
 295 .El
 296 .Sh DEPENDENCIES
 297 If using
 298 .Ql Fl D ,
 299 .Xr dialog 1
 300 is required.
 301 .Pp
 302 If using
 303 .Ql Fl X ,
 304 .Xr Xdialog 1
 305 is required.
 306 .Sh FILES
 307 .Bl -tag -width ".Pa $HOME/.dialogrc" -compact
 308 .It Pa $HOME/.dialogrc
 309 .El
 310 .Sh EXAMPLES
 311 Simple example to show how fast
 312 .Xr yes 1
 313 produces lines
 314 .Pq usually about ten-million per-second; your results may vary :
 315 .Bd -literal -offset indent
 316 yes | dpv -l yes
 317 .Ed
 318 .Pp
 319 Display progress while timing how long it takes
 320 .Xr yes 1
 321 to produce a half-billion lines
 322 .Pq usually under one minute; your results may vary :
 323 .Bd -literal -offset indent
 324 time yes | dpv -Nl 500000000:yes
 325 .Ed
 326 .Pp
 327 An example to watch how quickly a file is transferred using
 328 .Xr nc 1 :
 329 .Bd -literal -offset indent
 330 dpv -x "nc -w 1 somewhere.com 3000" -m label file
 331 .Ed
 332 .Pp
 333 A similar example, transferring a file from another process and passing the
 334 expected size to
 335 .Nm :
 336 .Bd -literal -offset indent
 337 cat file | dpv -x "nc -w 1 somewhere.com 3000" 12345:label
 338 .Ed
 339 .Pp
 340 A more complicated example:
 341 .Bd -literal -offset indent
 342 tar cf - . | dpv -x "gzip -9 > out.tgz" \\
 343         $( du -s . | awk '{print $1 * 1024}' ):label
 344 .Ed
 345 .Pp
 346 Taking an image of a disk:
 347 .Bd -literal -offset indent
 348 dpv -o disk-image.img -m label /dev/ada0
 349 .Ed
 350 .Pp
 351 Writing an image back to a disk:
 352 .Bd -literal -offset indent
 353 dpv -o /dev/ada0 -m label disk-image.img
 354 .Ed
 355 .Pp
 356 Zeroing a disk:
 357 .Bd -literal -offset indent
 358 dpv -o /dev/md42 < /dev/zero
 359 .Ed
 360 .Sh SEE ALSO
 361 .Xr dialog 1 ,
 362 .Xr sh 1 ,
 363 .Xr Xdialog 1 ,
 364 .Xr dialog 3
 365 .Sh HISTORY
 366 A
 367 .Nm
 368 utility first appeared in
 369 .Fx 11.0 .
 370 .Sh AUTHORS
 371 .An Devin Teske Aq dteske@FreeBSD.org
 372 .Sh BUGS
 373 .Xr Xdialog 1 ,
 374 when given both
 375 .Ql Fl -title Ar title
 376 .Pq see above Ql Fl t Ar title
 377 and
 378 .Ql Fl -backtitle Ar backtitle
 379 .Pq see above Ql Fl b Ar backtitle ,
 380 displays the backtitle in place of the title and vice-versa.
 381 .Pp
 382 .Xr Xdialog 1
 383 does not wrap long prompt texts received after initial launch.
 384 This is a known issue with the
 385 .Ql --gauge
 386 widget in
 387 .Xr Xdialog 1 .
 388 .Pp
 389 .Xr dialog 1
 390 does not display the first character after a series of escaped escape-sequences
 391 (e.g., ``\\\\n'' produces ``\\'' instead of ``\\n'').
 392 This is a known issue with
 393 .Xr dialog 1
 394 and does not affect
 395 .Xr dialog 3
 396 or
 397 .Xr Xdialog 1 .
 398 .Pp
 399 If your application ignores
 400 .Ev USE_COLOR
 401 when set and NULL before calling
 402 .Xr dpv 1
 403 with color escape sequences anyway,
 404 .Xr dialog 3
 405 and
 406 .Xr dialog 1
 407 may not render properly.
 408 Workaround is to detect when
 409 .Ev USE_COLOR
 410 is set and NULL and either not use color escape sequences at that time or use
 411 .Xr unset 1
 412 .Xr [ sh 1 ]
 413 or
 414 .Xr unsetenv 1
 415 .Xr [ csh 1 ]
 416 to unset
 417 .Ev USE_COLOR ,
 418 forcing interpretation of color sequences.
 419 This does not effect
 420 .Xr Xdialog 1 ,
 421 which renders the color escape sequences as plain text.
 422 See
 423 .Do
 424 embedded "\\Z" sequences
 425 .Dc
 426 in
 427 .Xr dialog 1
 428 for additional information.