lib/libdpv/dpv.3

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