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
30 .Nd stream data from stdin or multiple paths with dialog progress view
56 provides a dialog progress view, allowing a user to see current throughput rate
57 and total data transferred for one or more streams.
61 utility has two main modes for processing input.
63 The default input mode, without
66 reads bytes from standard input.
67 A label for the data must be provided.
69 The secondary input mode, with
73 .Pq up to 2047 or Dq ARG_MAX/2-1 ,
76 Data read in either mode is either thrown away
78 sent to a spawned instance of the program specified via
80 or sent to a unique file specified by
85 progress is displayed using one of
91 .Xr Xdialog 1 Pq Pa ports/x11/xdialog
94 The following options are available:
95 .Bl -tag -width "-b backtitle"
99 below the file progress indicator(s).
100 .It Fl b Ar backtitle
103 on the backdrop, at top-left, behind the dialog widget.
105 .Xr Xdialog 1 Pq Pa ports/x11/xdialog ,
106 this is displayed inside the window
108 followed by a separator line.
110 Do not use the default interface of
112 but instead spawn an instance of
118 environment variable or simply
123 Print dialog prompt data to standard out and provide additional debugging on
126 Produce a short syntax usage with brief option descriptions and exit.
127 Output is produced on standard error.
129 Customize the multi-file format string used to update the status line.
130 Ignored when using either
134 which lack the ability to display the status line
135 .Pq containing bytes/rate/thread information .
138 .Dq Li %'10lli bytes read @ %'9.1f bytes/sec. [%i/%i busy/wait] .
139 This format is used when handling more than one file.
141 Customize the single-file format string used to update the status line.
142 Ignored when using either
146 which lack the ability to display the status line
147 .Pq containing bytes/rate/thread information .
150 .Dq Li %'10lli bytes read @ %'9.1f bytes/sec. .
151 This format is used when handling one file.
154 Prevent visually distracting initialization/exit routines for scripts running
159 If negative, shrink to longest label width.
162 Read lines from input instead of bytes.
165 Instead of reading bytes from standard input, read from a set of paths
166 .Pq one for each label .
167 By default, each path is processed sequentially in the order given.
170 If enabled, stop reading known-length inputs when input reaches stated length.
174 progress indicators per screen.
175 If zero, display as many as possible.
176 If negative, only display the main progress indicator.
182 The first occurrence of
187 will be replaced with the
191 Mini-progressbar size.
192 If negative, don't display mini-progressbars
193 .Pq only the large overall progress indicator is shown .
194 If zero, auto-adjust based on number of files to read.
195 When zero and only one file to read, defaults to -1.
196 When zero and more than one file to read, defaults to 17.
200 above the file progress indicator(s).
203 Simulate reading a number of bytes, divided evenly across the number of files,
204 while stepping through each percent value of each file to process.
208 .Pq to override, use Ql Fl u Ar format .
209 No data is actually read.
214 Note that if you use this option at the same time as
217 .Ql Fl b Ar backtitle ,
222 are effectively switched
223 .Pq see BUGS section below .
232 disables status line updates.
233 If negative, update the status line as fast as possible.
234 Ignored when using either
238 which lack the ability to display the status line
239 .Pq containing bytes/rate/thread information .
248 to bump the dialog width.
249 Prompts wider than the maximum width will wrap
251 .Xr Xdialog 1 Pq Pa ports/x11/xdialog ;
252 see BUGS section below.
254 Enable X11 mode by using
255 .Xr Xdialog 1 Pq Pa ports/x11/xdialog
264 and send it data that has been read.
271 is executed once for each
274 The first occurrence of
279 will be replaced with the
284 The following environment variables are referenced by
286 .Bl -tag -width ".Ev USE_COLOR"
288 Override command string used to launch
292 .Xr Xdialog 1 Pq Pa ports/x11/xdialog
293 .Pq requires Ql Fl X ;
301 If set and non-NULL, path to
307 is either not set or NULL, used as a prefix to
309 .Pq i.e., Ql $HOME/.dialogrc .
311 If set and NULL, disables the use of color when using
314 .Xr Xdialog 1 Pq Pa ports/x11/xdialog .
324 .Xr Xdialog 1 Pq Pa ports/x11/xdialog
327 .Bl -tag -width "$HOME/.dialogrc" -compact
328 .It Pa $HOME/.dialogrc
331 Simple example to show how fast
334 .Pq usually about ten-million per-second; your results may vary :
335 .Bd -literal -offset indent
339 Display progress while timing how long it takes
341 to produce a half-billion lines
342 .Pq usually under one minute; your results may vary :
343 .Bd -literal -offset indent
344 time yes | dpv -Nl 500000000:yes
347 An example to watch how quickly a file is transferred using
349 .Bd -literal -offset indent
350 dpv -x "nc -w 1 somewhere.com 3000" -m label file
353 A similar example, transferring a file from another process and passing the
356 .Bd -literal -offset indent
357 cat file | dpv -x "nc -w 1 somewhere.com 3000" 12345:label
360 A more complicated example:
361 .Bd -literal -offset indent
362 tar cf - . | dpv -x "gzip -9 > out.tgz" \\
363 $( du -s . | awk '{print $1 * 1024}' ):label
366 Taking an image of a disk:
367 .Bd -literal -offset indent
368 dpv -o disk-image.img -m label /dev/ada0
371 Writing an image back to a disk:
372 .Bd -literal -offset indent
373 dpv -o /dev/ada0 -m label disk-image.img
377 .Bd -literal -offset indent
378 dpv -o /dev/md42 "Zeroing md42" < /dev/zero
383 .Xr Xdialog 1 Pq Pa ports/x11/xdialog ,
388 utility first appeared in
391 .An Devin Teske Aq dteske@FreeBSD.org
393 .Xr Xdialog 1 Pq Pa ports/x11/xdialog ,
395 .Ql Fl -title Ar title
396 .Pq see above Ql Fl t Ar title
398 .Ql Fl -backtitle Ar backtitle
399 .Pq see above Ql Fl b Ar backtitle ,
400 displays the backtitle in place of the title and vice-versa.
402 .Xr Xdialog 1 Pq Pa ports/x11/xdialog
403 does not wrap long prompt texts received after initial launch.
404 This is a known issue with the
407 .Xr Xdialog 1 Pq Pa ports/x11/xdialog .
410 does not display the first character after a series of escaped escape-sequences
411 (e.g., ``\\\\n'' produces ``\\'' instead of ``\\n'').
412 This is a known issue with
417 .Xr Xdialog 1 Pq Pa ports/x11/xdialog .
419 If your application ignores
421 when set and NULL before calling
423 with color escape sequences anyway,
427 may not render properly.
428 Workaround is to detect when
430 is set and NULL and either not use color escape sequences at that time or use
438 forcing interpretation of color sequences.
440 .Xr Xdialog 1 Pq Pa ports/x11/xdialog ,
441 which renders the color escape sequences as plain text.
444 embedded "\\Z" sequences
448 for additional information.