PROGRESSBAR(3)            OpenBSD Programmer's Manual           PROGRESSBAR(3)

NAME
     progressbar_start, progressbar_update, progressbar_change,
     progressbar_finish, progressbar_winch - display a progress bar

SYNOPSIS
     #include <progressbar.h>

     struct progressbar *
     progressbar_start(FILE *tty, unsigned long max, const char *title,
             int flags);

     void
     progressbar_update(struct progressbar *p, unsigned long pos);

     void
     progressbar_change(struct progressbar *p, unsigned long max,
             const char *title, int flags);

     void
     progressbar_finish(struct progressbar *p);

     void
     progressbar_winch(int sig);

DESCRIPTION
     Often, visual feedback can be helpful to a user.  These functions display
     a growing progress bar or meter that includes an estimated completion
     time.  Users can disable and customize progress bars through an environ-
     ment variable.

     The progressbar_start() function creates an initially empty progress bar
     on tty titled with the given string.  If title is NULL, no title is used.

     The flags parameter specifies various options to be used in the progress
     bar display, and are as follows:

     PB_NOWINCH    Do not install a signal handler to catch SIGWINCH signals.

     PB_BYTES      Indicate that pos and max are byte counts, allowing a
                   transfer rate to be deduced.

     The progressbar_update() function should be called whenever progress is
     made. The pos argument should be an integer between 0 and max, inclusive.
     No screen output is generated when there is no change in the display, if
     the process is not the foreground process, or if the output is not a ter-
     minal, so it is safe to call this function as often as possible.

     The progressbar_change() function can be used to dynamically change the
     progress bar's options, title or expected maximum.

     The progressbar_finish() function must be called when the progress bar is
     no longer needed.  It deallocates resources, updates the display with the
     time elapsed, and begins a new line as needed.  After caling this func-
     tion, the p pointer is no longer valid.

     The progressbar_winch() function is provided for when the PB_NOWINCH flag
     is used.  It should be called from within a SIGWINCH signal handler to
     inform the library that the screen size has changed.

RETURN VALUES
     The progressbar_start() function returns NULL if storage allocation
     failed.

ENVIRONMENT
     The PROGRESSBAR environment variable affects how progress bars are ulti-
     mately displayed.  If it is present and a non-empty string, it should
     take the form of an optional integer followed by a series of string-inte-
     ger pairs.

     For example:
           3 ftp 0 cp 5 mv 5 rm -1 fsck -1

     The string integer pairs indicate program names and the number of seconds
     to wait until commencing display of the progress bar in that application.
     If 0 is specified, the meter is always shown, and if a negative number is
     specified, the meter is never shown.

     The first integer provides a default for applications not mentioned.  If
     PROGRESSBAR variable is not set, the following default is used:
           4 ftp 0 scp 0

     If an error is encountered in the parsing of PROGRESSBAR, the trailing
     portion of the string is silently ignored.

AUTHORS
     David Leonard

OpenBSD 2.9                    January 14, 2002                              2