xref: /freebsd/lib/libdpv/dpv.3 (revision 59e2ff550c448126b988150ce800cdf73bb5103e)
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 Oct 24, 2014
28.Dt DPV 3
29.Os
30.Sh NAME
31.Nm dpv
32.Nd dialog progress view library
33.Sh LIBRARY
34.Lb libdpv
35.Sh SYNOPSIS
36.In dpv.h
37.Ft int
38.Fo dpv
39.Fa "struct dpv_config *config, struct dpv_file_node *file_list"
40.Fc
41.Ft void
42.Fo dpv_free
43.Fa "void"
44.Fc
45.Sh DESCRIPTION
46The
47.Nm
48library provides an interface for creating complex
49.Dq gauge
50widgets for displaying progress on various actions.
51The
52.Nm
53library can display progress with one of
54.Xr dialog 3 ,
55.Xr dialog 1 ,
56or
57.Xr Xdialog 1
58.Pq x11/xdialog from the ports tree .
59.Pp
60The
61.Fn dpv
62.Fa config
63argument contains the following properties for configuring global display
64features:
65.Bd -literal -offset indent
66struct dpv_config {
67    enum dpv_display display_type;  /* Def. DPV_DISPLAY_LIBDIALOG */
68    enum dpv_output  output_type;   /* Default DPV_OUTPUT_NONE */
69    int              debug;         /* Enable debug on stderr */
70    int              display_limit; /* Files/page. Default -1 */
71    int              label_size;    /* Label size. Default 28 */
72    int              pbar_size;     /* Mini-progress size */
73    int              dialog_updates_per_second; /* Default 16 */
74    int              status_updates_per_second; /* Default 2 */
75    uint16_t         options;       /* Default 0 (none) */
76    char             *title;        /* Widget title */
77    char             *backtitle;    /* Widget backtitle */
78    char             *aprompt;      /* Append. Default NULL */
79    char             *pprompt;      /* Prefix. Default NULL */
80    char             *msg_done;     /* Default `Done' */
81    char             *msg_fail;     /* Default `Fail' */
82    char             *msg_pending;  /* Default `Pending' */
83    char             *output;       /* Output format string */
84    const char       *status_solo;  /* dialog(3) solo-status format.
85                                     * Default DPV_STATUS_SOLO */
86    const char       *status_many;  /* dialog(3) many-status format.
87                                     * Default DPV_STATUS_MANY */
88
89    /*
90     * Function pointer; action to perform data transfer
91     */
92    int (*action)(struct dpv_file_node *file, int out);
93};
94
95enum dpv_display {
96    DPV_DISPLAY_LIBDIALOG = 0, /* Use dialog(3) (default) */
97    DPV_DISPLAY_STDOUT,        /* Use stdout */
98    DPV_DISPLAY_DIALOG,        /* Use spawned dialog(1) */
99    DPV_DISPLAY_XDIALOG,       /* Use spawned Xdialog(1) */
100};
101
102enum dpv_output {
103    DPV_OUTPUT_NONE = 0, /* No output (default) */
104    DPV_OUTPUT_FILE,     /* Read `output' member as file path */
105    DPV_OUTPUT_SHELL,    /* Read `output' member as shell cmd */
106};
107.Ed
108.Pp
109The
110.Va options
111member of the
112.Fn dpv
113.Fa config
114argument is a mask of bit fields indicating various processing options.
115Possible flags are as follows:
116.Bl -tag -width DPV_NO_OVERRUN
117.It Dv DPV_TEST_MODE
118Enable test mode.
119In test mode, the
120.Fn action
121callback of the
122.Fa config
123argument is not called but instead simulated-data is used to drive progress.
124Appends
125.Dq [TEST MODE]
126to the status line
127.Po
128to override, set the
129.Va status_format
130member of the
131.Fn dpv
132.Fa config
133argument;
134e.g., to
135.Dv DPV_STATUS_DEFAULT
136.Pc .
137.It Dv DPV_WIDE_MODE
138Enable wide mode.
139In wide mode, the length of the
140.Va aprompt
141and
142.Va pprompt
143members of the
144.Fn dpv
145.Fa config
146argument will bump the width of the gauge widget.
147Prompts wider than the maximum width will wrap
148.Po
149unless using
150.Xr Xdialog 1 ;
151see BUGS section below
152.Pc .
153.It Dv DPV_NO_LABELS
154Disables the display of labels associated with each transfer
155.Po
156.Va label_size
157member of
158.Fn dpv
159.Fa config
160argument is ignored
161.Pc .
162.It Dv DPV_USE_COLOR
163Force the use of color even if the
164.Va display_type
165does not support color
166.Po
167.Ev USE_COLOR
168environment variable is ignored
169.Pc .
170.It Dv DPV_NO_OVERRUN
171When enabled, callbacks for the current
172.Vt dpv_file_node
173are terminated when
174.Fn action
175returns 100 or greater
176.Po
177alleviates the need to change the
178.Va status
179of the current
180.Vt dpv_file_node
181but may also cause file truncation if the stream exceeds expected length
182.Pc .
183.El
184.Pp
185The
186.Fa file_list
187argument to
188.Fn dpv
189is a pointer to a
190.Dq linked-list ,
191described as follows in
192.In dpv.h :
193.Bd -literal -offset indent
194struct dpv_file_node {
195    enum dpv_status    status; /* status of read operation */
196    char               *msg;   /* display instead of "Done/Fail" */
197    char               *name;  /* name of file to read */
198    char               *path;  /* path to file */
199    long long          length; /* expected size */
200    long long          read;   /* number units read (e.g., bytes) */
201    struct dpv_file_node *next;/* pointer to next (end with NULL) */
202};
203.Ed
204.Pp
205For each of the items in the
206.Fa file_list
207.Dq linked-list
208argument, the
209.Fn action
210callback member of the
211.Fn dpv
212.Fa config
213argument is called.
214The
215.Fn action
216function should perform a
217.Dq nominal
218action on the file and return.
219The return value of
220.Vt int
221represents the current progress percentage
222.Pq 0-100
223for the current file.
224.Pp
225The
226.Fn action
227callback provides two variables for each call.
228.Fa file
229provides a reference to the current
230.Vt dpv_file_node
231being processed.
232.Fa out
233provides a file descriptor where the data should go.
234.Pp
235If the
236.Va output
237member of the
238.Fn dpv
239.Fa config
240argument was set to DPV_OUTPUT_NONE
241.Pq default ; when invoking Fn dpv ,
242the
243.Fa out
244file descriptor of
245.Fn action
246will be zero and should be ignored.
247If
248.Fa output
249was set to DPV_OUTPUT_FILE,
250.Fa out
251will be an open file descriptor to a file.
252If
253.Fa output
254was set to DPV_OUTPUT_SHELL,
255.Fa out
256will be an open file descriptor to a pipe for a spawned shell program.
257When
258.Fa out
259is greater than zero, you should write any data you have read back to
260.Fa out .
261.Pp
262To abort
263.Fn dpv ,
264either from the
265.Fn action
266callback or asynchronously from a signal handler, two globals are provided via
267.In dpv.h :
268.Bd -literal -offset indent
269extern int dpv_interrupt; /* Set to TRUE in interrupt handler */
270extern int dpv_abort;     /* Set to true in callback to abort */
271.Ed
272.Pp
273These globals are not automatically reset and must be manually maintained.
274Don't forget to reset these globals before subsequent invocations of
275.Fn dpv
276when making multiple calls from the same program.
277.Pp
278In addition, the
279.Va status
280member of the
281.Fn action
282.Fa file
283argument can be used to control callbacks for the current file.
284The
285.Va status
286member can be set to any of the following from
287.In dpv.h :
288.Bd -literal -offset indent
289enum dpv_status {
290	DPV_STATUS_RUNNING = 0, /* Running (default) */
291	DPV_STATUS_DONE,        /* Completed */
292	DPV_STATUS_FAILED,      /* Oops, something went wrong */
293};
294.Ed
295.Pp
296The default
297.Fa status
298is zero, DPV_STATUS_RUNING, which keeps the callbacks coming for the current
299.Fn file .
300Setting
301.Ql file->status
302to anything other than DPV_STATUS_RUNNING will cause
303.Fn dpv
304to loop to the next file, effecting the next callback, if any.
305.Pp
306The
307.Fn action
308callback is responsible for calculating percentages and
309.Pq recommended
310maintaining a
311.Nm
312global counter so
313.Fn dpv
314can display throughput statistics.
315Percentages are reported through the
316.Vt int
317return value of the
318.Fn action
319callback.
320Throughput statistics are calculated from the following global
321.Vt int
322in
323.In dpv.h :
324.Bd -literal -offset indent
325extern int dpv_overall_read;
326.Ed
327.Pp
328This should be set to the number of bytes that have been read for all files.
329Throughput information is displayed in the status line
330.Pq only available when using Xr dialog 3
331at the bottom of the screen.
332See DPV_DISPLAY_LIBDIALOG above.
333.Pp
334Note that
335.Va dpv_overall_read
336does not have to represent bytes.
337For example, you can change the
338.Va status_format
339to display something other than
340.Dq Li bytes
341and increment
342.Va dpv_overall_read
343accordingly
344.Pq e.g., counting lines .
345.Pp
346When
347.Fn dpv
348is processing the current file, the
349.Va length
350and
351.Va read
352members of the
353.Fn action
354.Fa file
355argument are used for calculating the display of mini progress bars
356.Po
357if enabled; see
358.Va pbar_size
359above
360.Pc .
361If the
362.Va length
363member of the current
364.Fa file
365is less than zero
366.Pq indicating an unknown file length ,
367a
368.Xr humanize_number 3
369version of the
370.Va read
371member is used instead of a traditional progress bar.
372Otherwise a progress bar is calculated as percentage read to file length.
373.Fn action
374callback must maintain these member values for mini-progress bars.
375.Pp
376The
377.Fn dpv_free
378function performs
379.Xr free 3
380on private global variables initialized by
381.Fn dpv .
382.Sh ENVIRONMENT
383The following environment variables are referenced by
384.Nm :
385.Bl -tag -width ".Ev USE_COLOR"
386.It Ev DIALOG
387Override command string used to launch
388.Xr dialog 1
389.Pq requires Dv DPV_DISPLAY_DIALOG
390or
391.Xr Xdialog 1
392.Pq requires Dv DPV_DISPLAY_XDIALOG ;
393default is either
394.Ql dialog
395.Pq for Dv DPV_DISPLAY_DIALOG
396or
397.Ql Xdialog
398.Pq for Dv DPV_DISPLAY_XDIALOG .
399.It Ev DIALOGRC
400If set and non-NULL, path to
401.Ql .dialogrc
402file.
403.It Ev HOME
404If
405.Ql Ev $DIALOGRC
406is either not set or NULL, used as a prefix to
407.Ql .dialogrc
408.Pq i.e., Ql $HOME/.dialogrc .
409.It Ev USE_COLOR
410If set and NULL, disables the use of color when using
411.Xr dialog 1
412.Pq does not apply to Xr Xdialog 1 .
413.It Ev msg_done Ev msg_fail Ev msg_pending
414Internationalization strings for overriding the default English strings
415.Ql Done ,
416.Ql Fail ,
417and
418.Ql Pending
419respectively.
420To prevent their usage, explicitly set the
421.Va msg_done ,
422.Va msg_fail ,
423and
424.Va msg_pending
425members of
426.Fn dpv
427.Fa config
428argument to default macros
429.Pq DPV_DONE_DEFAULT, DPV_FAIL_DEFAULT, and DPV_PENDING_DEFAULT
430or desired values.
431.El
432.Sh FILES
433.Bl -tag -width ".Pa $HOME/.dialogrc" -compact
434.It Pa $HOME/.dialogrc
435.El
436.Sh SEE ALSO
437.Xr dialog 1 ,
438.Xr Xdialog 1 ,
439.Xr dialog 3
440.Sh HISTORY
441The
442.Nm
443library first appeared in
444.Fx 11.0 .
445.Sh AUTHORS
446.An Devin Teske Aq dteske@FreeBSD.org
447.Sh BUGS
448.Xr Xdialog 1 ,
449when given both
450.Ql Fl -title Ar title
451.Po
452see above
453.Ql Va title
454member of
455.Va struct dpv_config
456.Pc
457and
458.Ql Fl -backtitle Ar backtitle
459.Po
460see above
461.Ql Va backtitle
462member of
463.Va struct dpv_config
464.Pc ,
465displays the backtitle in place of the title and vice-versa.
466.Pp
467.Xr Xdialog 1
468does not wrap long prompt texts received after initial launch.
469This is a known issue with the
470.Ql --gauge
471widget in
472.Xr Xdialog 1 .
473Embed escaped newlines within prompt text(s) to force line breaks.
474.Pp
475.Xr dialog 1
476does not display the first character after a series of escaped escape-sequences
477(e.g., ``\\\\n'' produces ``\\'' instead of ``\\n'').
478This is a known issue with
479.Xr dialog 1
480and does not affect
481.Xr dialog 3
482or
483.Xr Xdialog 1 .
484.Pp
485If your application ignores
486.Ev USE_COLOR
487when set and NULL before calling
488.Xr dpv 3
489with color escape sequences anyway,
490.Xr dialog 3
491and
492.Xr dialog 1
493may not render properly.
494Workaround is to detect when
495.Ev USE_COLOR
496is set and NULL and either not use color escape sequences at that time or use
497.Xr unsetenv 3
498to unset
499.Ev USE_COLOR ,
500forcing interpretation of color sequences.
501This does not effect
502.Xr Xdialog 1 ,
503which renders the color escape sequences as plain text.
504See
505.Do
506embedded "\\Z" sequences
507.Dc
508in
509.Xr dialog 1
510for additional information.
511