DbgLog filters and logs debugging/error messages according to errno, calling module/function, warning keyword and debugging level. Particular errno/keyword combinations can be made fatal. Output log files depend on keyword.
Error tracking
To use DbgLog, simply #include <DbgLog.h>.
Error reporting can be done using:
void DbgLog(const char * mod, const char * key, unsigned char lev, const char * mes, ...) ;
'mod' is the calling module or function name. This is the main context
data, as this information will structure the actual hierarchy of calls.
'key' is a debugging key, an identifier tag that will direct logging and
filtering of this message. 'lev' is a numeric indication of severity
(the lower, the more severe, with 0 having sense as "system-level error").
For instance:
DbgLog("MyFunction","dummyerror",16,"This is my error number %d",num++) ;
Reporting levels
DbgLog_UpDbgLvl and DbgLog_DnDbgLvl respectively toggle on and off displaying messages from the error levels given by the set bits of the mask (1 being the level 0, 1<<1 the level 1, and then on until 1<<31).
Error stack and recursive calls
DbgLog_OpenBlock and DbgLog_CloseBlock are used to open and close trapping blocks, that is to suspend error reporting. No messages will be printed, except when DbgLog_Flush is called, that will print all trapped error entries from the last call to DbgLog_OpenBlock.
Managing imbricated failures
When using imbricated calls to functions using DbgLog, the uppermost can fail because one lower call failed. In this case, using DbgLog again would result in two messages for the same material error.. While this may be desirable, most often this would only be confusing at debug time. It is advisable to limit the use of DbgLog on generation of error, that is: a failed system call (so the errno variable is set to a meaningfull value), a check that showed some discrepancy in data, wrong arguments...
