Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 in-
     put.  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.

     -k		   Keep	tite.  Prevent visually	distracting initializa-
		   tion/exit routines for scripts running dialog(1) several
		   times.

     -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 dis-
		   play	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 neg-
		   ative, update the status line as fast as possible.  Ignored
		   when	using either `-D' or `-X' which	lack the ability to
		   display the status 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 max-
		   imum	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 10.2.

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 backti-
     tle 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 in-
     terpretation 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			       January 26, 2016				   BSD

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | DEPENDENCIES | FILES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dpv&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help