lib/libdpv/dpv.3

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