1 .\" Copyright (c) 2013-2016 Devin Teske
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd stream data from stdin or multiple paths with dialog progress view
42 .Op Ar [bytes2:]label2 path2 ...
45 provides a dialog progress view, allowing a user to see current throughput rate
46 and total data transferred for one or more streams.
50 utility has two main modes for processing input.
52 The default input mode, without
55 reads bytes from standard input.
56 A label for the data must be provided.
58 The secondary input mode, with
62 .Pq up to 2047 or Dq ARG_MAX/2-1 ,
65 Data read in either mode is either thrown away
67 sent to a spawned instance of the program specified via
69 or sent to a unique file specified by
74 progress is displayed using one of
83 The following options are available:
84 .Bl -tag -width ".Fl b Ar backtitle"
88 below the file progress indicator(s).
92 on the backdrop, at top-left, behind the dialog widget.
95 this is displayed inside the window
97 followed by a separator line.
100 Print dialog prompt data to standard out and provide additional debugging on
103 Do not use the default interface of
105 but instead spawn an instance of
111 environment variable or simply
115 Produce a short syntax usage with brief option descriptions and exit.
116 Output is produced on standard error.
118 Customize the single-file format string used to update the status line.
119 Ignored when using either
123 which lack the ability to display the status line
124 .Pq containing bytes/rate/thread information .
127 .Dq Li %'10lli bytes read @ %'9.1f bytes/sec. .
128 This format is used when handling one file.
130 Customize the multi-file format string used to update the status line.
131 Ignored when using either
135 which lack the ability to display the status line
136 .Pq containing bytes/rate/thread information .
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.
143 Prevent visually distracting initialization/exit routines for scripts running
147 Line mode. Read lines from input instead of bytes.
150 If negative, shrink to longest label width.
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.
159 progress indicators per screen.
160 If zero, display as many as possible.
161 If negative, only display the main progress indicator.
166 If enabled, stop reading known-length inputs when input reaches stated length.
170 The first occurrence of
175 will be replaced with the
181 above the file progress indicator(s).
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.
193 Note that if you use this option at the same time as
196 .Ql Fl b Ar backtitle ,
201 are effectively switched
202 .Pq see BUGS section below .
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.
210 .Pq to override, use Ql Fl u Ar format .
211 No data is actually read.
220 disables status line updates.
221 If negative, update the status line as fast as possible.
222 Ignored when using either
226 which lack the ability to display the status line
227 .Pq containing bytes/rate/thread information .
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 .
243 and send it data that has been read.
250 is executed once for each
253 The first occurrence of
258 will be replaced with the
262 Enable X11 mode by using
270 The following environment variables are referenced by
272 .Bl -tag -width ".Ev USE_COLOR"
274 Override command string used to launch
279 .Pq requires Ql Fl X ;
287 If set and non-NULL, path to
293 is either not set or NULL, used as a prefix to
295 .Pq i.e., Ql $HOME/.dialogrc .
297 If set and NULL, disables the use of color when using
299 .Pq does not apply to Xr Xdialog 1 .
312 .Bl -tag -width ".Pa $HOME/.dialogrc" -compact
313 .It Pa $HOME/.dialogrc
316 Simple example to show how fast
319 .Pq usually about ten-million per-second; your results may vary :
320 .Bd -literal -offset indent
324 Display progress while timing how long it takes
326 to produce a half-billion lines
327 .Pq usually under one minute; your results may vary :
328 .Bd -literal -offset indent
329 time yes | dpv -Nl 500000000:yes
332 An example to watch how quickly a file is transferred using
334 .Bd -literal -offset indent
335 dpv -x "nc -w 1 somewhere.com 3000" -m label file
338 A similar example, transferring a file from another process and passing the
341 .Bd -literal -offset indent
342 cat file | dpv -x "nc -w 1 somewhere.com 3000" 12345:label
345 A more complicated example:
346 .Bd -literal -offset indent
347 tar cf - . | dpv -x "gzip -9 > out.tgz" \\
348 $( du -s . | awk '{print $1 * 1024}' ):label
351 Taking an image of a disk:
352 .Bd -literal -offset indent
353 dpv -o disk-image.img -m label /dev/ada0
356 Writing an image back to a disk:
357 .Bd -literal -offset indent
358 dpv -o /dev/ada0 -m label disk-image.img
362 .Bd -literal -offset indent
363 dpv -o /dev/md42 < /dev/zero
373 utility first appeared in
376 .An Devin Teske Aq dteske@FreeBSD.org
380 .Ql Fl -title Ar title
381 .Pq see above Ql Fl t Ar title
383 .Ql Fl -backtitle Ar backtitle
384 .Pq see above Ql Fl b Ar backtitle ,
385 displays the backtitle in place of the title and vice-versa.
388 does not wrap long prompt texts received after initial launch.
389 This is a known issue with the
395 does not display the first character after a series of escaped escape-sequences
396 (e.g., ``\\\\n'' produces ``\\'' instead of ``\\n'').
397 This is a known issue with
404 If your application ignores
406 when set and NULL before calling
408 with color escape sequences anyway,
412 may not render properly.
413 Workaround is to detect when
415 is set and NULL and either not use color escape sequences at that time or use
423 forcing interpretation of color sequences.
426 which renders the color escape sequences as plain text.
429 embedded "\\Z" sequences
433 for additional information.