err#

Simple error reporting library.

This library is modelled after the BSD error reporting family of functions with a few extensions. These functions mostly follows the documented behaviour in the unix err(3) man page, with the major exception that err() and errx() does not call exit() (unless the environment variable ERR_ABORT is set to “exit”).

Used environment variables

ERR_STREAM: Error stream to write messages to.
- empty : do not write anything
- ”stderr” | unset : write to stderr
- ”stdout” : write to stdout
- otherwise : open the given file and append to it
ERR_ABORT: Whether errors should should return normally, exit or about.
- ”0” | “normal” | unset : return normally
- ”1” | “exit” : exit
- ”2” | “abort” | empty : abort
- otherwise : return normally
ERR_WARN: Whether warnings should be ignored or turned into errors.
- ”0” | “normal” | unset : report normally
- ”1” | “ignore” : ignore
- ”2” | “error” : turn into error
- otherwise : report normally
ERR_DEBUG: Wheter debugging information (source file, line number and function name) should be included in the error message.
- ”0” | unset | empty : no debugging info
- ”1” | “debug” : print file and line number
- ”2” | “full” : print file, line number and function
- otherwise : no debugging info
ERR_OVERRIDE: How to handle error messages when there already is a message in the error message buffer. Note that these options will only affect the error message, not the error value.
- unset | empty : append new error message to the old one
- ”0” | “append” : append new error message
- ”1” | “warn-old” : overwrite old error message and write warning
- ”2” | “warn-new” : ignore new error message and write warning
- ”3” | “old” : overwrite old error message
- ”4” | “ignore-new” : ignore new error message
- otherwise : append new error message to the old one
ERR_COLOR: Whether to write error messages colour-coded.
- unset | “auto” : colour-coded only if connected to a terminal
- ”no” | “never” : not colour-coded
- ”yes” | “always” : colour-coded

ErrTry block

ErrTry blocks allows to selectively handel errors based on their error value. They are of the form:

ErrTry:
  statements...;
ErrCatch(eval1):
  error_handling...;
  break;  // do not fall-through
ErrCatch(eval2):
  error_handling...;
  break;  // not strictly needed since next clause is not an ErrCatch
ErrOther:
  fallback_error_handling...;
ErrElse:
  code_on_no_errors...;
ErrFinally:
  always_executed...;
ErrEnd;

Except for ErrTry and ErrEnd, all clauses are optional. But if they are given, they should occour in the above order.

The ErrTry clause is evaluated as normal, but errors that occurs will only be reported if they are not caught by the ErrCatch or ErrOther clauses.

Multiple ErrCatch clauses may be provided, to handle different errors. They should normally end with break. If they don’t, the evaluation will fall-through to the next ErrCatch clause. For example, in:

ErrCatch(1):
ErrCatch(2):
  statements...;
  break;

will statements... be called for errors with value 1 and 2.

The ErrOther clause will handle any error that has not been catched by an earlier ErrCatch clause.

The ErrElse clause will, if it is provided, be evaluated, if no errors occured during evaluation of the ErrTry clause.

The ErrFinally clause will, if it is provided, always be evaluated. It is typically used for cleanup-code.

It is possible to use the break statement to end the execution of any clause.

Note

Errors occuring in the ErrTry clause (including any function called from within the clause) will first be reported when execution leaves the ErrEnd clause if they are not caught. This opens for the possibility that an error might be missed if another error occurs within the same clause. How to handle this, is controlled by err_set_override_mode() and the environment variable ERR_OVERRIDE.

ErrTry#: Starts a ErrTry block.

ErrCatch(errval)#: Catches an error with the given value.

ErrOther#: Handles uncaught errors.

ErrElse#: Code to run on no errors.

ErrFinally#: Final (cleanup) code to always run.

ErrEnd#: Ends an ErrTry block.

void _err_link_record(ErrRecord *errrecord)#: Adds link to new exception handler. Called internally by the ErrTry macro. Don’t call this function directly.

void _err_unlink_record(ErrRecord *errrecord)#: Unlinks exception handler. Called internally by the ErrEnd macro. Don’t call this function directly.

ErrRecord *_err_get_record()#: Returns pointer to current error record. Called internally by the raise() macro. Don’t call this function directly.

Macros for emulating exceptions

Warning

Be careful when using raise() and raisex(), since they may skip clean-up code and leave the program in an inconsistent state or leak resources.

err_raise(eval, ...)#: Raises an exception This transfers the execution to the nearest enclosing ErrTry block. If no such block exists, fatal() is called.

err_raisex(eval, ...)#: Like raise(), but does not append a system error message to the exception message.

err_reraise()#: Reraises current error or exception This macro can only be called within ErrCatch, ErrOther and ErrFinally clauses.

Associated functions

enum ErrTryState#

Values:

enumerator errTryNormal#

enumerator errTryCatch#

enumerator errTryElse#

enumerator errTryFinally#

typedef struct ErrRecord ErrRecord#: Error record, describing the last error.

typedef void (*ErrHandler)(const ErrRecord *record)#: Prototype for error handler. The eval and msg fields of the error record are probably the most relevant. In addition it might get the current error stream with err_get_stream().

typedef const char *(*ErrNameConv)(int eval)#

Prototype for function that converts error codes to names.

It should return a static pointer to the name corresponding to error level errlevel and error code eval. May return NULL, if the error code is unknown.

void *err_get_state(void)#: Return a pointer to (thread local) state for this module.

void err_set_state(void *state)#: Sets state from state returned by err_get_state(). If state is NULL, the state is initialised to default values.

int err_getlevel(void)#: Returns the error level of the last error.

int err_geteval(void)#: Returns the error value of the last error.

int err_update_eval(int eval)#

If the current error value is non-zero, set it to eval. Nothing is done if there is no current error.

Returns the updated error value.

const char *err_getmsg(void)#

Returns a pointer the error message of the last error.

Note that the memory pointed to will be overridded by the next error. Do not use the returned pointer as input to a new error message - this may result in an overflow of the error buffer (depending of the implementation of the underlying snprintf() function).

void err_clear(void)#: Clear the last error (setting error value to zero).

const char *err_set_prefix(const char *prefix)#

Set prefix to prepend to all errors in this application. Typically this is the program name.

Returns the current prefix.

FILE *err_set_stream(FILE *stream)#

Set stream that error messages are printed to.

If stream is err_default_stream (default) the error stream determined by the ERR_STREAM environment variable.

If stream is NULL, no output will be written.

Returns the previous error stream.

FILE *err_get_stream(void)#: Returns the current error stream.

ErrAbortMode err_set_abort_mode(int mode)#

Set wheter the error functions should return normally, exit or about. Interpretation of mode argument:

mode >= 2: abort
mode == 1: exit (with error value)
mode == 0: normal return
mode < 0: check ERR_ABORT environment variable (default)

Returns the previous abort mode.

ErrAbortMode err_get_abort_mode(void)#: Returns the current abort mode.

ErrWarnMode err_set_warn_mode(int mode)#

Set whether warnings should be turned to errors. Interpretation of mode argument:

err_warn_mode >= 1: turn warnings into errors
err_warn_mode == 0: default
err_warn_mode < 0: check ERR_WARN environment variable (default) if it is set, warnings are turned into errors

ErrWarnMode err_get_warn_mode(void)#: Returns the current warning mode.

ErrDebugMode err_set_debug_mode(int mode)#

Sets whether error messages should include debugging info. Interpretation of mode argument:

mode >= 2: include file and line number and function
mode == 1: include file and line number
mode == 0: no debugging info
mode < 0: check ERR_DEBUG environment variable (default)

Returns the current debugging mode.

Note

Debugging info requeres that the compiler supports __VA_ARGS__.

ErrDebugMode err_get_debug_mode(void)#: Returns the current debugging mode.

ErrOverrideMode err_set_override_mode(int mode)#

Sets how to handle overridden error in a Try/Catch block. Interpretation of mode argument:

mode >= 4: ignore new error
mode == 3: ignore old error
mode == 2: ignore new error and write warning to error stream
mode == 1: ignore old error and write warning to error stream
mode == 0: append to previous error
mode < 0: check ERR_OVERRIDE environment variable

Returns the current debugging mode.

ErrOverrideMode err_get_override_mode(void)#: Returns the current override mode.

ErrColorMode err_set_color_mode(ErrColorMode mode)#: Sets whether to print error messages color-coded.

int err_get_color_coded()#: Returns whether error messages are printed color-coded.

void err_default_handler(const ErrRecord *record)#

Default error handler.

Writes error message to the error stream.

If the ERR_COLOR environment variable is set and the error stream is stdout or stderr, the message will be written with colours.

ErrHandler err_set_handler(ErrHandler handler)#

Sets a new error handler.

Sets new error handler.

Returns the previous error handler.

If handler is err_default_handler the default handler will be used, which simply prints the error message to the curent error stream.

If handler is NULL, no handler will be called.

Returns the current error handler.

Sets a new error handler.

If handler is err_default_handler the default handler will be used, which simply prints the error message to the curent error stream.

If handler is NULL, no handler will be called.

Returns the current error handler.

ErrHandler err_get_handler(void)#: Returns the current error handler.

ErrNameConv err_set_nameconv(ErrNameConv nameconv)#

Returns the current error name function. By default it is NULL.

ErrNameConv err_get_nameconv(void)#: Returns the current error name converter.

const char *err_getname(int eval)#

Return const pointer to name corresponding to error code eval.

Returns NULL if no error name converter has been registered or if the error code is unknown.

const char *err_getlevelname(int errlevel)#

Return const pointer to name corresponding to error level errlevel.

Returns NULL if errlevel does not correspond to a valid error level.

Defines

ERR_MSGSIZE#: Buffer size for error messages.

err_default_stream#: Default error stream (checks the ERR_STREAM environment variable)

struct ErrRecord

#include <err.h>

Error record, describing the last error.

Public Members

ErrLevel level#: Error level.

int eval#: Error value.

int errnum#: System error number.

char msg[ERR_MSGSIZE]#: Error message.

int pos#: Position of new appended error message.

int handled#: Whether the error has been handled.

int reraise#: Error value to reraise.

ErrTryState state#: Where we are in ErrTry.. ErrEnd.

struct ErrRecord *prev#: Pointer to previous record in the stack-allocated list of error records.

jmp_buf env#: Buffer for longjmp().