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