Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

FreeBSD 11.0 - man page for dpv (freebsd section 1)

DPV(1)							    BSD General Commands Manual 						    DPV(1)

NAME
dpv -- stream data from stdin or multiple paths with dialog progress view
SYNOPSIS
dpv [options] [bytes:]label dpv [options] -m [bytes1:]label1 path1 [[bytes2:]label2 path2 ...]
DESCRIPTION
dpv provides a dialog progress view, allowing a user to see current throughput rate and total data transferred for one or more streams. The dpv utility has two main modes for processing input. The default input mode, without '-m', dpv reads bytes from standard input. A label for the data must be provided. The secondary input mode, with '-m', dpv reads multiple paths (up to 2047 or ``ARG_MAX/2-1''), sequentially. Data read in either mode is either thrown away (default), sent to a spawned instance of the program specified via '-x cmd', or sent to a unique file specified by '-o file'. With or without '-m', progress is displayed using one of dialog(3) (default), dialog(1) (see '-D'), or instead Xdialog(1) (see '-X'). The following options are available: -a text Display text below the file progress indicator(s). -b backtitle Display backtitle on the backdrop, at top-left, behind the dialog widget. When using Xdialog(1), this is displayed inside the window (at the top) followed by a separator line. -d Debug mode. Print dialog prompt data to standard out and provide additional debugging on standard error. -D Do not use the default interface of dialog(3), but instead spawn an instance of dialog(1). The path to dialog(1) is taken from the DIALOG environment variable or simply ``dialog'' if unset or NULL. -h Produce a short syntax usage with brief option descriptions and exit. Output is produced on standard error. -i format Customize the single-file format string used to update the status line. Ignored when using either '-D' or '-X' which lack the ability to display the status line (containing bytes/rate/thread information). Default value is ``%'10lli bytes read @ %'9.1f bytes/sec.''. This format is used when handling one file. -I format Customize the multi-file format string used to update the status line. Ignored when using either '-D' or '-X' which lack the ability to display the status line (containing bytes/rate/thread information). Default value is ``%'10lli bytes read @ %'9.1f bytes/sec. [%i/%i busy/wait]''. This format is used when handling more than one file. -l Line mode. Read lines from input instead of bytes. -L size Label size. If negative, shrink to longest label width. -m Multi-input mode. Instead of reading bytes from standard input, read from a set of paths (one for each label). By default, each path is processed sequentially in the order given. -n num Display at-most num progress indicators per screen. If zero, display as many as possible. If negative, only display the main progress indicator. Default is 0. Maximum value is 10. -N No overrun. If enabled, stop reading known-length inputs when input reaches stated length. -o file Output data to file. The first occurrence of '%s' (if any) in 'file' will be replaced with the label text. -p text Display text above the file progress indicator(s). -P size Mini-progressbar size. If negative, don't display mini-progressbars (only the large overall progress indicator is shown). If zero, auto-adjust based on number of files to read. When zero and only one file to read, defaults to -1. When zero and more than one file to read, defaults to 17. -t title Display title atop the dialog box. Note that if you use this option at the same time as '-X' and '-b backtitle', the backtitle and title are effectively switched (see BUGS section below). -T Test mode. Simulate reading a number of bytes, divided evenly across the number of files, while stepping through each percent value of each file to process. Appends ``[TEST MODE]'' to the status line (to override, use '-u format'). No data is actually read. -U num Update status line num times per-second. Default value is '2'. A value of '0' disables status line updates. If negative, update the status line as fast as possible. Ignored when using either '-D' or '-X' which lack the ability to display the sta- tus line (containing bytes/rate/thread information). -w Wide mode. Allows long text arguments used with '-p' and '-a' to bump the dialog width. Prompts wider than the maximum width will wrap (unless using Xdialog(1); see BUGS section below). -x cmd Execute cmd (via sh(1)) and send it data that has been read. Data is available to cmd on standard input. With '-m', cmd is executed once for each path argument. The first occurrence of '%s' (if any) in 'cmd' will be replaced with the label text. -X Enable X11 mode by using Xdialog(1) instead of dialog(1) or dialog(3).
ENVIRONMENT
The following environment variables are referenced by dpv: DIALOG Override command string used to launch dialog(1) (requires '-D') or Xdialog(1) (requires '-X'); default is either 'dialog' (for '-D') or 'Xdialog' (for '-X'). DIALOGRC If set and non-NULL, path to '.dialogrc' file. HOME If '$DIALOGRC' is either not set or NULL, used as a prefix to '.dialogrc' (i.e., '$HOME/.dialogrc'). USE_COLOR If set and NULL, disables the use of color when using dialog(1) (does not apply to Xdialog(1)).
DEPENDENCIES
If using '-D', dialog(1) is required. If using '-X', Xdialog(1) is required.
FILES
$HOME/.dialogrc
EXAMPLES
Simple example to show how fast yes(1) produces lines (usually about ten-million per-second; your results may vary): yes | dpv -l yes Display progress while timing how long it takes yes(1) to produce a half-billion lines (usually under one minute; your results may vary): time yes | dpv -Nl 500000000:yes An example to watch how quickly a file is transferred using nc(1): dpv -x "nc -w 1 somewhere.com 3000" -m label file A similar example, transferring a file from another process and passing the expected size to dpv: cat file | dpv -x "nc -w 1 somewhere.com 3000" 12345:label A more complicated example: tar cf - . | dpv -x "gzip -9 > out.tgz" \ $( du -s . | awk '{print $1 * 1024}' ):label Taking an image of a disk: dpv -o disk-image.img -m label /dev/ada0 Writing an image back to a disk: dpv -o /dev/ada0 -m label disk-image.img Zeroing a disk: dpv -o /dev/md42 < /dev/zero
SEE ALSO
dialog(1), sh(1), Xdialog(1), dialog(3)
HISTORY
A dpv utility first appeared in FreeBSD 11.0.
AUTHORS
Devin Teske <dteske@FreeBSD.org>
BUGS
Xdialog(1), when given both '--title title' (see above '-t title') and '--backtitle backtitle' (see above '-b backtitle'), displays the back- title in place of the title and vice-versa. Xdialog(1) does not wrap long prompt texts received after initial launch. This is a known issue with the '--gauge' widget in Xdialog(1). dialog(1) does not display the first character after a series of escaped escape-sequences (e.g., ``\\n'' produces ``\'' instead of ``\n''). This is a known issue with dialog(1) and does not affect dialog(3) or Xdialog(1). If your application ignores USE_COLOR when set and NULL before calling dpv(1) with color escape sequences anyway, dialog(3) and dialog(1) may not render properly. Workaround is to detect when USE_COLOR is set and NULL and either not use color escape sequences at that time or use unset(1) [sh(1)] or unsetenv(1) [csh(1)] to unset USE_COLOR, forcing interpretation of color sequences. This does not effect Xdialog(1), which renders the color escape sequences as plain text. See ``embedded "\Z" sequences'' in dialog(1) for additional information.
BSD
Sep 7, 2014 BSD