err.h - Error signaling and handling

The API defined in err.h provides a struct for storing an error state, Err, and operations to set and read errors.

Object Macros

#define ERR_MSG_BUF_SZ 256

The size of the buffer used to store error messages. Includes the null-terminator.

#define ERR_FILE_BUF_SZ 256

The size of the buffer used to store the name of the file where the error was thrown. Includes the null-terminator.

Function Macros

#define SET_ERR(err, code, msg) …

Set an error. Writes the code and message data to the Err object, automatically providing the source file name and line number. See setErr() for more information.

Enums

typedef enum ENUM_ERR_CODE { … } ErrCode;

Lists all supported error codes. The value of each member is also the exit code that should be used for fatal errors.

The following members are defined:

• ErrCode_OK = 0 - No error

• ErrCode_RUN = 1 - General runtime error

• ErrCode_OPT = 2 - Bad command-line option

• ErrCode_MEM = 3 - Out of memory

• ErrCode_IO = 4 - General input/output failure

Structs

typedef struct STRUCT_ERR Err;

Contains information about the state of an error condition, including a diagnostic code, an error message, and the line and source-file where the error was thrown.

Functions

U0 delErr(Err *err);

Delete an Err object.

ErrCode getErrCode(Err err);

Return the error code data from an Err object.

I8 *getErrFile(Err *err);

Return the file name data from an Err object.

U32 getErrLn(Err *err);

Return the line number data from an Err object.

I8 *getErrMsg(Err *err);

Return the message data from an Err object.

I8 isErr(Err *err);

Test to see if an Err is in an “error condition”. That is, whether or not its error code is ErrCode_OK.

I8 isErrCode(Err *err, ErrCode code);

Test to see if an Err is set to a specific code.

Err *newErr(Err *err);

Create a new Err object.

The optional err argument is the same as with any other constructor function in the libkw library: it is an error handler used primarily to catch memory allocation failures. It is optional, and will most of the time be given NIL since most applications only need one Err object.

May set ErrCode_MEM if heap-memory cannot be allocated for the new object.

U0 panic(Err *err);

Unconconditionally panic.

Write the Err object’s message data to stderr then exit the process immediately with the value of the Err object’s code data.

U0 panicOnErr(Err *err);

Panic on all error conditions.

Same as panic(err), but only if isErr(err) is true.

U0 panicOnErrCode(Err *err, ErrCode code);

Panic on a specific error condition.

Same as panic(err), but only if isErrCode(err, code) is true.

U0 resetErr(Err *err);

Reset an Err object as if setErr() had never been called with it.

U0 setErr(Err *err, ErrCode code, I8 *msg);

Set an error.

The given error state data will be written to an Err object.

Generally, you will want to use the SET_ERR macro instead, since it automatically provides the correct file name and line number data.

U0 warn(Err *err);

Unconditionally warn.

Write the Err object’s message data to stderr.

U0 warnOnErr(Err *err);

Warn on all error conditions.

Same as warn(err), but only if isErr(err) is true.

U0 warnOnErrCode(Err *err);

Warn on a specific error condition.

Same as warn(err), but only if isErrCode(err, code) is true.