NAME

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

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

ENVIRONMENT

BEGEMOT_ERR

Overrides the format mode.

BEGEMOT_ABORT

Generate a core dump on call to panic.

SEE ALSO

AUTHOR