report.h : Debugging and reporting

To enable the debug() function on all of the software, just type: ./configure --enable-debug and recompile with 'make'.

To enable the debug() function only in specific files: 1) Configure without enabling debug (that is without --enable-debug) 2) Edit the source file that you want to debug and put the following line at the top, before the #include "report.h" line: #define DEBUG 3) Then recompile with 'make' This way, the global DEBUG macro is off but is locally enabled in certains parts of the software.

The reporting levels have the following meaning.

Reporting Levels

0 RPT_CRIT

Critical conditions: the program stops right after this. Only use this if the program is actually exited from the current function.

1 RPT_ERR

Error conditions: serious problem, program continues. Use this just before you return -1 from a function.

2 RPT_WARNING

Warning conditions: Something that the user should fix, but the program can continue without a real problem. Ex: Protocol errors from a client.

3 RPT_NOTICE

Major event in the program: (un)loading of driver, client (dis)connect.

4 RPT_INFO

Minor event in the program: the activation of a setting, details of a loaded driver, a key reservation, a keypress, a screen switch.

5 RPT_DEBUG

Insignificant event: What function has been called, what subpart of a function is being executed, what was received and sent over the socket, etc.

Levels 4 (maybe) and 5 (certainly) should be reported using the debug function. The code that this function generates will not be in the executable when compiled without debugging. This way memory and CPU cycles are saved.

report.h file defines 3 functions for debugging and reporting:

Sets reporting level and message destination

int set_reporting(application_name,  
 new_level,  
 new_dest); 
char *  application_name;
int  new_level;
int  new_dest;

Returns the content of the byte.

Report the message to the selected destination if important enough

void report(level,  
 format,  
 ); 
const int  level;
const char * format;
 ;

Returns nothing (void).

The format parameter is the same as the one used by printf.

Send debugging information if important enough

Consider the debug function to be exactly the same as the report function. The only difference is that it is only compiled in if DEBUG is defined.