caterr - CAT error handling
The caterr is a collection of functions and process global variables that are used to
control error reporting and debug tracing.
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 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.
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.
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.
- 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.
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