DragonFly On-Line Manual Pages

Search: Section:  

panic(l)                        BEGEMOT Library                       panic(l)


NAME

       panic, warn - print error or warning message and eventualy exit


SYNOPSIS


       # include <begemot.h>

       volatile void panic(const char *fmt, ...);

       volatile void bug(const char *fmt, ...);

       void error(const char *fmt, ...);

       void warn(const char *fmt, ...);

       void inform(const char *fmt, ...);

       int geterrorcnt();

       int getwarncnt();

       void set_errmode(int mode);

       void set_argv0(char *argv0);


DESCRIPTION

       The functions panic, bug, error, warn and inform are used to print
       messages in a standardized format to stderr.

       panic should be used, when the program encounters an error of that
       kind, that it's better to stop the program. It calles exit(3) with a
       value of 1.  If the environment variable BEGEMOT_ABORT is set, the
       program calls abort(3) instead.  error on the other hand should be
       used, when there is a severe error, but the program can continue (but
       the user should expect bad things).  error returns to the caller.  bug
       should be used, if the program encounters an error, that is obviously a
       programming error. A good example is putting bug in the default case of
       a switch statement, if it 'should not happen'.  warn can be called if
       there may be an error and it's better to inform the user about it.
       inform is called to print informative messages.

       There are also v-versions of this functions, which take a va_list as
       second argument.

       There are two message formats: a simple one and a complicated one. The
       simple one is the default. It consists of one of the words panic,
       error, warning, info or bug, followed by a colon, the formatted message
       and a new-line. For the complicated format this is prefixed with the
       program name, which can be set with set_argv0.  If it is not set,
       nothing is printed.  The name is followed by the program's pid, the
       current time.

       The mode can be selected with set_errmode.  An argument of zero selects
       the simple mode, non-zero values the complicated one. This setting may
       be overriden with the environment variable BEGEMOT_ERR.  Setting the
       error mode to a value greater than 1 produces the current time as the
       number of seconds (as a floating point value) from some point in time.
       This number of seconds is obtained: with the gethrtime(2) system call
       on systems that provide it (Solaris), else with clock_gettime(2) and a
       clockid of CLOCK_REALTIME on Posix systems, and with gettimeofday(2) if
       everything else failes. This mode is intended for parsing the output.

       It is often not simple to decide which of these functions to call in a
       certain situation. If the program comes in a situation, where
       continuation will most probably make things worse, then call panic.
       Examples of this are: memory cannot be allocated (exhaustion of virtual
       memory under UNIX is in almost all cases the outcome of a bug), a
       critical file cannot be found.  A warning should be issued, if the
       program cannot decide what the user's indentation was, but continuation
       will do no harm. The error function should be called, if the program
       can not continue as needed, but manual user actions can correct things.
       If the program finds, for example, after a long computation, that it
       cannot write the output to the desired file because of protection, it
       may write the output to /tmp and give the user a hint where to find it.

       The calls to error and warn are counted. These counts can be retrieved
       with geterrorcnt and getwarncnt.


RETURN VALUE

       panic and bug never return.  warn, error and inform return nothing.
       geterrorcnt and getwarncnt return the respective counts. This may be
       wrong if the functions are called more the 4 billion times.


ENVIRONMENT

       BEGEMOT_ERR
              Overrides the format mode.

       BEGEMOT_ABORT
              Generate a core dump on call to panic.


SEE ALSO

       abort(3), clock_gettime(2) exit(2), fprintf(3), gethrtime(2),
       gettimeofday(2), stdarg(3), vfprintf(3)


AUTHOR

       Harti Brandt

BEGEMOT                           28 Mar 2000                         panic(l)

Search: Section: