DeskLib 2.90a:Debug.h

Contents

Introduction and Overview

This file has prototypes for a standard set of simple debugging functions.

Several different ways of outputting debug messages are provided. Call Debug_Initialise to specify which method to use (otherwise the library defaults to outputting to stderr).

This header file ensures that all calls to Debug_xxx functions are macro-ed out by the preprocessor unless DeskLib_DEBUG is predefined. So don't worry about debug calls taking up space in your finished project, they will disappear when you build a normal version of your project.

Functions

Debug_Initialise

void Debug_Initialise(debug_type type);

Sets up the debug library. Call this before you use the Debug_Print or Debug_Printf functions. "type" specifies how the debug functions will output the debug information.

Calling this function is not mandatory, as it will be automatically called if you don't do so. In this case, it is initialised to the STDERR output.

Debug_InitialiseSignal

void Debug_InitialiseSignal(void );

Sets up a default handler for signals which calls Error_Report. To set up your own handler, use Debug_ClaimSignal (which calls Debug_InitialiseSignal for you).

Debug_ClaimSignal

void Debug_ClaimSignal(debug_signalhandlerfn fn, void *reference);

Makes 'fn' be called when a signal occurs.

Debug_ReleaseSignal

void Debug_ReleaseSignal(void );

Stops the fn, from a previous call to Debug_ClaimSignal, being called. The default handler is re-instated.

Debug_Printf

int Debug_Printf(const char *format, ... );

Sends the text to the debug output, in same way as printf.

Debug_Print

void Debug_Print(const char *text);

Sends a string to the debug output.

Function-like macros

Debug_Error_CheckFatal

	#define Debug_Error_CheckFatal( errfn) \
		do	{					\
			os_error	*debug__e = errfn;	\
				if ( debug__e)	{		\
				Error_ReportFatal( 		\
					debug__e->errnum, 	\
					error_PLACE "%s", 	\
					debug__e->errmess	\
					);			\
				}				\
			}					\
			while (0)

As Error_ReportFatal, but also displays the file and line number if DeskLib_DEBUG is predefined.

Debug_Assert

	#define Debug_Assert( expression)					\
		(								\
			(expression) 						\
				? 						\
				(void) 0	 				\
				: 						\
				Debug__Assert( #expression, __FILE__, __LINE__)	\
		)

This is similar to the standard ANSI C 'assert' macro. If 'expression' evaluates to FALSE, Debug_Printf is used (indirectly) to output a diagnostic message.

Like all the Debug_ commands, Debug_Assert is removed before compilation unless DeskLib_DEBUG is defined.

Macros

Debug1_Printf

#define Debug1_Printf (debug_level<1) ? 0 : Debug_Printf

Only outputs diagnostics if debug_level is >= 1

Debug2_Printf

#define Debug2_Printf (debug_level<2) ? 0 : Debug_Printf

Only outputs diagnostics if debug_level is >= 2

Debug3_Printf

#define Debug3_Printf (debug_level<3) ? 0 : Debug_Printf

Only outputs diagnostics if debug_level is >= 3

Debug4_Printf

#define Debug4_Printf (debug_level<4) ? 0 : Debug_Printf

Only outputs diagnostics if debug_level is >= 4

Debug5_Printf

#define Debug5_Printf (debug_level<5) ? 0 : Debug_Printf

Only outputs diagnostics if debug_level is >= 5

Types

debug_type

typedef enum
{
debug_UNINITIALISED,
debug_REPORTER,
debug_PIPETYPE,
debug_STDERR,
debug_UNIQUEFILE,
debug_UNIQUEPIPE
} debug_type;

This enum is used to specify which method of outputting debug information you'd like the debug functions to use. Pass one of the values to Debug_Initialise.

REPORTER will output to Martin Avison's reporter if it's present when the debug library is initialised (otherwise it will default to stderr).

PIPETYPE writes to a file in Pipe: and displays it in a taskwindow on screen (so can only be initialised after the program has called Event_Initialise).

STDERR writes to the stderr output (usually specified by redirection in your !Run file).

UNIQUEFILE writes to a unique file inside Scrap

UNIQUEPIPE is similar to PIPETYPE but creates a unique file in Pipe: and does not open it in a taskwindow.

UNINITIALISED is only for use internally.

debug_signalhandlerfn

typedef void (*debug_signalhandlerfn)(int sig, void *reference);

This is a function type which is called when a signal happens.

Variable

debug_level

extern int debug_level;

This is initially 0. Setting it to values greater than zero will turn on any subsequent DebugX_Printf statements.

Note that this will only happen with code compiled with DeskLib_DEBUG predefined.

Note that this selection of DebugX_Printf is 'live' - ie you can change debug_level before calling different functions to only have diagnostics from certain parts of your code.

At present, no DeskLib libraries have DebugX or Debug calls (and even if they did, you would have to build a new DeskLib with DeskLib_DEBUG predefined to use them).