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