lib/libdpv/dpv.3

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