NAME

caterr - CAT error handling

DESCRIPTION

The caterr is a collection of functions and process global variables that are used to control error reporting and debug tracing.

Errors and Warnings

Error messages, warnings and debug traces can all be generated by the caterr_error() function. Other functions and macros provide the same functionality or indirectly call caterr_error(). All output is eventually sent to the same destination, for example a file. Errors and warnings are always generated. Debug messages can be enabled at run time.

Debug Messages

Debug trace messages can be produced by the CAT_DEBUGn macros, where n is a digit between 1 and 5, indicating the debug level at which the macros are to be active. The CAT_IFDBG macro can be used to test the debug level explicitly.

The debug level is global to each process, and is normally set by the cat_setdebug function. The default level is zero, which disables all debug tracing, limiting trace output to warnings and errors.

Debug messages are sorted into categories based on the module and function from which they are generated, using label. The label is a string with structure ``module.function_name''. The module can contain one or more sub-modules, separated by dots. When debug tracing is enabled, output can then be limited to certain modules.

Error Callback

By default, errors and debug messages are sent to stderr. To append output to a file, use the caterr_setfile() function. All error and trace reporting can also be sent to a custom callback, which is installed with caterr_setfunc(). The prototype for an error reporting callback is as follows:

typedef void caterr_func(int major_code, int retval, const char *message);

Where major_code is one of the following:

CAT_FATAL
This should be used when an error that cannot be handled has occurred. Such an error will typically terminate a session or the entire process.

CAT_ERROR
Indicates an error condition from which the program can take recovery action.

CAT_WARNING
Indicates a problem that is not a true error, but typically indicates configuration errors or other problems in the environment.

CAT_DEBUG
Debug trace (informational) message.

retval is the return value that the function raising the error intends to return to its caller.

message is a null-terminated text string that normally comprises a single line.

Error codes

The following is the set of generic error codes for CAT. All toolkit functions use these codes. Whenever a return code has a specific meaning for a function, that meaning is documented in the description of the function.

CAT_EINTERNAL (-1)
Internal toolkit error.

CAT_ENOMEM (-2)
Out of memory.

CAT_ENOMORE (-3)
No more entries.

CAT_ENOTFOUND (-4)
Not found.

CAT_EAGAIN (-5)
Retriable error.

CAT_EOF (-6)
End of data stream.

CAT_EINVAL (-7)
Invalid argument.

CAT_EBUSY (-8)
Object in use.

CAT_ENOTSUPP (-9)
Not supported by implementation.

CAT_EOVERFLOW (-10)
Value out of range.

CAT_ETIMEDOUT (-11)
Timeout.

CAT_ESYS (-12)
System error.

CAT_ECONNREFUSED (-13)
Connection refused.

CAT_EACCES (-14)
Permission denied.

CAT_EFTYPE (-15)
Invalid data type or file format.

CAT_ECRYPT (-16)
Cryptographic operation failed.

CAT_EPASSWD (-17)
Password incorrect.

CAT_ECERTEXPIRED (-18)
Certificate expired.

CAT_ECERTINVALID (-19)
Certificate invalid.

CAT_EINPROGRESS (-20)
Connection in progress.

CAT_EBADADDR (-21)
Invalid network address.

CAT_EPROTO (-22)
Protocol error.

CAT_ENOTREADY (-23)
Not ready.

CAT_ECONFIG (-24)
Configuration error.

CAT_ECERTCRITICAL (-25)
Critical extension not supported.

CAT_ECERTREVOKED (-26)
Certificate revoked.

CAT_EISSUERUNKNOWN (-27)
Certificate issuer not trusted.

CAT_ECERTBADSIGNATURE (-28)
Invalid certificate signature.

CAT_ECERTBADKEYUSAGE (-29)
Invalid certificate key usage.

CAT_ENODE (-30)
Tried to get value from a node.

CAT_ENOPARENT (-31)
Has no parent.

The following are not errors, but can be returned by some callbacks:

CAT_POP_FILTER (-100)
Pop this filter.

CAT_MORE_DATA (-101)
Filter may have more data.

CAT_UNMANAGE (-102)
Unlink session from catsock_run().

CAT_CONTINUE (-103)
Continue normal operation.

FUNCTION OVERVIEW

cat_debuglevel
Set the global debug level.

caterr_debug
Generate a debug message. This function filters out any messages that do not fit the current debug level as set with cat_debuglevel().

caterr_error
Generate a formatted error message and call any callbacks registered with caterr_setfunc().

caterr_ifdebug
Check if a certain level and label has been selected for output.

caterr_mapsys
Map a platform system error to a CAT error code.

caterr_name
Get the string representation of an error level.

caterr_setdebug
Parse a debug specification and set up any debugging.

caterr_setfile
Set the file to be used by the error handler. Output will be appended to this file.

caterr_setfunc
Set the message output function to be used by the error handler.

caterr_setprefix
Set the message prefix for all debug/error messages sent to the log.

caterr_setprogname
Set the program name for the debug/error messages sent to the log.

caterr_str
Get the description of an error code, as a string.

caterr_typestr
Get the string representation of a CAT major code.

caterr_verror
Generate an error message. This function is similar to caterr_error() but takes va_list instead of a variable number of arguments.

SEE ALSO

cat

CAT_DEBUGn, CAT_IFDBG, caterr_error, caterr_name, caterr_setdebug, caterr_setfile, caterr_setfunc, caterr_setprefix, caterr_setprogname, caterr_str, caterr_typestr, caterr_verror