debug.h File Reference

Debugging helpers/loggers/etc. Turn OFF debug code by defining NDEBUG. More...

#include <stdarg.h>
#include "pp.h"

Include dependency graph for debug.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines
#define	ppFileLine(txt)   __FILE__ ":" ppTokStr(__LINE__) ": " txt
	Output a string with file and line compatible with GNU errors.
#define	throwassert(sz)   ppDebug( { trace(( "%s\n", ppFileLine(sz) )); __asm__("int3"); } )
	Invoke a breakpoint instruction Optionally extend with __FILE__ and __LINE__ directives, but most of the time we're only interested in the debugger's text, and even a crash address from a tester will point back to the probable assertions. Your platform WILL vary; this is for MSVC/Windows/INTEL. Has the added charm of stopping the debugger on the actual line of code where the error happened.
#define	isdebugging()   ppDebug( _isdebugging() )
	Find out if we're being debugged.
#define	assert(e)   ppDebug( { if( !(e) ) throwassert(#e); } )
	Invoke a breakpoint instruction if failed.
#define	assertptr(p, len)   assert( _checkptr((p),(len),1) )
	Invoke a breakpoint instruction if a pointer looks suspiciously like NULL, or (NULL)->member pointer.
#define	assertconst(p, len)   assert( _checkconst((p),(len),1) )
	Invoke a breakpoint instruction if a pointer looks suspiciously like NULL, or (NULL)->member pointer.
#define	assertobjptr(p)   assert( _checkptr((p),sizeof(*(p)),min(4,sizeof(*(p)))) )
	Invoke a breakpoint instruction if a pointer's odd or too small or otherwise 'bad'.
#define	assertobjconst(p)   assert( _checkconst((p),sizeof(*(p)),min(4,sizeof(*(p)))) )
	Invoke a breakpoint instruction if a pointer's odd or too small or otherwise 'bad'.
#define	assertcodeptr(p)   assert( _checkcall( p ) )
	Invoke a breakpoint instruction if a pointer isn't executable.
#define	trace(args)   ppDebug( debug_trace args )
	Do debug trace ala printf.
#define	traceline(args)   ppDebug( { debug_trace("%s\n", ppFileLine(ppNULL) ); debug_trace args; } )
	Do debug trace ala printf with current file/line included.
Typedefs
typedef int(*	debug_vlog_t )(const char *, va_list)
	Logging function pointer type Similar to trace, except does not get compiled out in production code.
typedef int(*	debug_trace_t )(const char *,...)
	The universal debug trace handler.
Functions
void	debug_setvlog (debug_vlog_t debug_vlog)
	Set log handler.
void	debug_setlogmask (unsigned mask)
	Set log mask.
unsigned	debug_getlogmask (void)
	Get the log mask.
void	debug_log (unsigned mask, const char *fmt,...)
	Logging function.
void	debug_vlog (unsigned mask, const char *fmt, va_list args)
	Logging function.
void	debug_logalways (const char *fmt,...)
	Logging function that always logs.
void	debug_vlogalways (const char *fmt, va_list args)
	Logging function that always logs.
void	debug_loghex (unsigned mask, const void *ptr, size_t size)
	Log a pretty, formatted hex dump.
void	debug_settrace (debug_trace_t trace)
	Set debug trace handler.
Variables
const debug_trace_t	debug_trace
	The universal debug trace handler.

---

Detailed Description

Debugging helpers/loggers/etc. Turn OFF debug code by defining NDEBUG.

C destructor A little exception handling help. Unit test is in datagen.c, Test_Except().

Author:

David Mace

Definition in file debug.h.

---

Define Documentation

#define assert

(

e

)

ppDebug( { if( !(e) ) throwassert(#e); } )

Invoke a breakpoint instruction if failed.

Parameters:

e

Must be true, or execution is halted

Definition at line 93 of file debug.h.

Referenced by _GUI_CallNotifies(), _GUI_Control_Data(), _GUI_Control_Get(), _GUI_Dirty_Rect(), _GUI_Explode_Set(), _GUI_Heartbeat(), _GUI_Offset_Group(), _GUI_SetFocus(), _GUI_Sweep_Set(), BLIB_Copy(), BLIB_Count(), BLIB_Destroy(), BLIB_ElementAdd(), BLIB_ElementCopyData(), BLIB_ElementDelete(), BLIB_ElementInsert(), BLIB_ElementPointer(), BLIB_ElementReplace(), BLIB_ElementSize(), BLIB_Size(), BLIB_User(), BMI_ReadRow(), BMI_Save(), BMI_WriteRow(), char_record_write_string(), char_serial_write_string(), ctl_pool_base_free(), ctl_record_write_begin(), ctl_record_write_container_begin(), ctl_serial_writesize(), ctl_xmlread_init(), ctl_xmlread_string(), ctl_xmlread_translate_char(), ctl_xmlread_translate_wchar_t(), ctl_xmlwrite_string_char(), ctl_xmlwrite_string_wchar_t(), GUI_BlibInit(), GUI_tabdown(), GUI_tableft(), GUI_tabright(), GUI_tabup(), RingBuff_Consume(), RingBuff_Peek(), RingBuff_Space(), Shape_Pack(), Socket_Customize(), SocketsShutdown(), uint16_serial_write(), uint16_serial_writearray(), uint32_serial_write(), uint32_serial_writearray(), uint64_serial_write(), uint64_serial_writearray(), uint8_serial_write(), uint8_serial_writearray(), and wchar_t_serial_write_string().

#define assertcodeptr

(

p

)

assert( _checkcall( p ) )

Invoke a breakpoint instruction if a pointer isn't executable.

Parameters:

p

A pointer

Definition at line 128 of file debug.h.

Referenced by ctl_serial_setexception(), ctl_set_new_handler(), ctl_watchdog_init(), ctl_xmlread_init(), debug_log(), debug_logalways(), debug_settrace(), debug_setvlog(), debug_vlog(), debug_vlogalways(), Socket_Close(), Socket_Create_Login(), Socket_Create_Raw(), Socket_Create_User(), SocketsCycle(), SocketsSetFlashPolicy(), SocketsSetHTTP(), SocketsSetLogin(), and SocketsSetUser().

#define assertconst	(	p,
		len		)	assert( _checkconst((p),(len),1) )

Invoke a breakpoint instruction if a pointer looks suspiciously like NULL, or (NULL)->member pointer.

Parameters:

p

A pointer

Definition at line 107 of file debug.h.

Referenced by BLIB_ElementAdd(), BLIB_ElementCopyData(), BLIB_ElementInsert(), BLIB_ElementReplace(), char_record_read_gstring(), char_record_read_string(), char_record_size_gstring(), char_record_size_string(), char_record_write_string(), char_serial_read_string(), char_serial_size_string(), char_serial_write_string(), char_xml_read_gstring(), char_xml_read_string(), char_xml_write_string(), ctl_chdir(), ctl_copy(), ctl_mkdir(), ctl_mmap_open(), ctl_move(), ctl_pool_base_init(), ctl_record_contained_type_is(), ctl_record_container_validatedata(), ctl_record_head_size(), ctl_record_is(), ctl_record_objarray_head_size(), ctl_record_type_is(), ctl_record_write_begin(), ctl_record_write_container_begin(), ctl_rmdir(), ctl_serial_record_read(), ctl_serial_record_size(), ctl_serial_record_write(), ctl_unlink(), ctl_xmlread_find(), ctl_xmlread_findnext(), ctl_xmlread_getattribute(), ctl_xmlread_init(), ctl_xmlread_is(), ctl_xmlread_rawattribute(), ctl_xmlread_string(), ctl_xmlwrite_containertag(), ctl_xmlwrite_create(), ctl_xmlwrite_endtag(), ctl_xmlwrite_generaltag(), ctl_xmlwrite_string_char(), ctl_xmlwrite_string_wchar_t(), debug_log(), debug_logalways(), debug_loghex(), debug_vlog(), debug_vlogalways(), raw_xml_readbytes(), raw_xml_writebytes(), Socket_Create_Client(), Socket_Create_Listener(), Socket_Create_User(), Socket_LogError(), Socket_Write(), SocketFind(), SocketsLogHostent(), SocketsLogLastError(), SocketsParseAddress(), uint16_serial_sizearray(), uint16_serial_write(), uint16_serial_writearray(), uint32_serial_sizearray(), uint32_serial_write(), uint32_serial_writearray(), uint64_serial_sizearray(), uint64_serial_write(), uint64_serial_writearray(), uint8_serial_sizearray(), uint8_serial_write(), uint8_serial_writearray(), wchar_t_record_read_gstring(), wchar_t_record_read_string(), wchar_t_record_size_gstring(), wchar_t_record_size_string(), wchar_t_record_write_string(), wchar_t_serial_read_string(), wchar_t_serial_size_string(), wchar_t_serial_write_string(), wchar_t_xml_read_gstring(), wchar_t_xml_read_string(), and wchar_t_xml_write_string().

#define assertobjconst

(

p

)

assert( _checkconst((p),sizeof(*(p)),min(4,sizeof(*(p)))) )

Invoke a breakpoint instruction if a pointer's odd or too small or otherwise 'bad'.

Parameters:

p

A const pointer

Definition at line 121 of file debug.h.

Referenced by char_record_read_gstring(), char_record_read_string(), char_record_size_gstring(), ctl_record_contained_type(), ctl_record_contained_type_is(), ctl_record_count(), ctl_record_end(), ctl_record_is(), ctl_record_label(), ctl_record_type(), ctl_record_type_is(), ctl_record_valid(), ctl_serial_calc_size(), ctl_serial_copy(), ctl_serial_peek_serial(), ctl_serial_peeksize(), ctl_serial_record_size(), ctl_serial_record_write(), ctl_serial_write_serial(), ctl_xmlread_getcontent(), ctl_xmlread_getname(), ctl_xmlread_gettextafter(), ctl_xmlread_gettextbefore(), ctl_xmlread_is(), ctl_xmlread_rawcontent(), ctl_xmlread_rawname(), ctl_xmlread_rawtextafter(), ctl_xmlread_rawtextbefore(), ctl_xmlread_recurse(), ctl_xmlread_string(), ctl_xmlread_translate_char(), ctl_xmlread_translate_wchar_t(), raw_xml_writebytes(), RingBuff_Space(), Socket_Write_Serial(), SocketID(), uint16_serial_peek(), uint8_serial_peek(), wchar_t_record_read_gstring(), wchar_t_record_read_string(), and wchar_t_record_size_gstring().

#define assertobjptr

(

p

)

assert( _checkptr((p),sizeof(*(p)),min(4,sizeof(*(p)))) )

Invoke a breakpoint instruction if a pointer's odd or too small or otherwise 'bad'.

Parameters:

p

A pointer

Definition at line 114 of file debug.h.

Referenced by _GUI_Control_Data(), _GUI_Control_Get(), _GUI_Explode_Set(), _GUI_Sweep_Set(), char_record_read_gstring(), char_record_write_string(), char_serial_peek_sconst(), char_serial_read_fstring(), char_serial_read_gstring(), char_serial_read_sconst(), char_serial_read_string(), char_serial_write_string(), char_xml_read_gstring(), char_xml_read_string(), char_xml_write_string(), ctl_mmap_close(), ctl_mmap_open(), ctl_mstime_gm(), ctl_mstime_local(), ctl_pool_base_free(), ctl_pool_base_init(), ctl_record_container_validatedata(), ctl_record_find(), ctl_record_find_next(), ctl_record_getdata(), ctl_record_next(), ctl_record_write_begin(), ctl_record_write_container_begin(), ctl_record_write_end(), ctl_serial_copy(), ctl_serial_deref(), ctl_serial_peek_serial(), ctl_serial_read_serial(), ctl_serial_readsize(), ctl_serial_record_read(), ctl_serial_record_write(), ctl_serial_write_serial(), ctl_serial_writesize(), ctl_xmlread_canrecurse(), ctl_xmlread_find(), ctl_xmlread_findnext(), ctl_xmlread_getattribute(), ctl_xmlread_getcontent(), ctl_xmlread_getname(), ctl_xmlread_gettextafter(), ctl_xmlread_gettextbefore(), ctl_xmlread_init(), ctl_xmlread_next(), ctl_xmlread_rawattribute(), ctl_xmlread_rawcontent(), ctl_xmlread_rawname(), ctl_xmlread_rawtextafter(), ctl_xmlread_rawtextbefore(), ctl_xmlread_recurse(), ctl_xmlread_rewind(), ctl_xmlread_string(), ctl_xmlwrite_begin(), ctl_xmlwrite_close(), ctl_xmlwrite_containertag(), ctl_xmlwrite_create(), ctl_xmlwrite_endtag(), ctl_xmlwrite_generaltag(), ctl_xmlwrite_indent(), ctl_xmlwrite_newline(), ctl_xmlwrite_outdent(), ctl_xmlwrite_string_char(), ctl_xmlwrite_string_wchar_t(), raw_xml_readbytes(), raw_xml_writebytes(), RingBuff_Consume(), RingBuff_Init(), RingBuff_Peek(), Socket_Alloc_Serial(), Socket_Close(), Socket_Create_Raw(), Socket_Create_User(), Socket_Customize(), Socket_Raw_Consume(), Socket_Write(), Socket_Write_Serial(), SocketFind(), SocketsCycle(), SocketsShutdown(), uint16_serial_read(), uint16_serial_readarray(), uint16_serial_write(), uint16_serial_writearray(), uint32_serial_peek(), uint32_serial_read(), uint32_serial_readarray(), uint32_serial_write(), uint32_serial_writearray(), uint64_serial_peek(), uint64_serial_read(), uint64_serial_readarray(), uint64_serial_write(), uint64_serial_writearray(), uint8_serial_read(), uint8_serial_readarray(), uint8_serial_write(), uint8_serial_writearray(), wchar_t_record_read_gstring(), wchar_t_record_write_string(), wchar_t_serial_peek_sconst(), wchar_t_serial_read_fstring(), wchar_t_serial_read_gstring(), wchar_t_serial_read_sconst(), wchar_t_serial_read_string(), wchar_t_serial_write_string(), wchar_t_xml_read_gstring(), wchar_t_xml_read_string(), and wchar_t_xml_write_string().

#define assertptr	(	p,
		len		)	assert( _checkptr((p),(len),1) )

Invoke a breakpoint instruction if a pointer looks suspiciously like NULL, or (NULL)->member pointer.

Parameters:

p

A pointer

Definition at line 100 of file debug.h.

Referenced by char_record_read_string(), char_string_swap(), char_xml_read_string(), ctl_cwd(), ctl_mstime_print_seconds(), ctl_mstime_print_time_gm(), ctl_mstime_print_time_local(), ctl_pool_base_free(), ctl_record_write_end(), ctl_xmlread_translate_char(), ctl_xmlread_translate_wchar_t(), RingBuff_Init(), uint16_serial_peek(), uint16_serial_read(), uint16_serial_readarray(), uint32_serial_peek(), uint32_serial_read(), uint32_serial_readarray(), uint64_serial_peek(), uint64_serial_read(), uint64_serial_readarray(), uint8_serial_peek(), uint8_serial_read(), uint8_serial_readarray(), and wchar_t_xml_read_string().

#define ppFileLine

(

txt

)

__FILE__ ":" ppTokStr(__LINE__) ": " txt

Output a string with file and line compatible with GNU errors.

Parameters:

txt

Text to append after (or ppNULL )

Definition at line 29 of file debug.h.

#define trace

(

args

)

ppDebug( debug_trace args )

Do debug trace ala printf.

Parameters:

args

The arguments (with parentheses) that go to printf; trace(("%d\n",i));

Definition at line 136 of file debug.h.

Referenced by Socket_Close(), SocketsInit(), SocketsParseAddress(), and SocketsShutdown().

#define traceline

(

args

)

ppDebug( { debug_trace("%s\n", ppFileLine(ppNULL) ); debug_trace args; } )

Do debug trace ala printf with current file/line included.

Parameters:

args

The arguments (with parentheses) that go to printf; traceline(("%d\n",i));

Definition at line 143 of file debug.h.

---

Typedef Documentation

typedef int(* debug_vlog_t)(const char *, va_list)

Logging function pointer type Similar to trace, except does not get compiled out in production code.

Parameters:

	mask	Mask to set what log level this output belongs to
	fmt	printf format string and arguments

Definition at line 155 of file debug.h.

---

Function Documentation

unsigned debug_getlogmask

(

void

)

Get the log mask.

Returns:

Whatever log mask is

Definition at line 113 of file debug.c.

Referenced by serial_log().

{
    return debug_logmask;
}

void debug_log	(	unsigned	mask,
		const char *	fmt,
			...
	)

Logging function.

Parameters:

	mask	Mask to check against allowable log types, or 0 for 'always'
	fmt	It's a printf, so format accordingly

Definition at line 29 of file debug.c.

References assertcodeptr, and assertconst.

Referenced by ctl_profiles_dump(), and ctl_profiles_dump_averages_sheet().

{
    assertconst(fmt,1);
    assertcodeptr(pdebug_vlog);
    if( (mask & debug_logmask) || 0 == mask )
    {
        va_list args;
        va_start( args, fmt );
        pdebug_vlog( fmt, args );
        fflush(stdout);
    }
}

void debug_logalways	(	const char *	fmt,
			...
	)

Logging function that always logs.

Parameters:

fmt

It's a printf, so format accordingly

Definition at line 62 of file debug.c.

References assertcodeptr, and assertconst.

Referenced by debug_loghex(), and serial_log().

{
    va_list args;
    va_start( args, fmt );
    assertconst(fmt,1);
    assertcodeptr(pdebug_vlog);
    pdebug_vlog( fmt, args );
}

void debug_loghex	(	unsigned	mask,
		const void *	ptr,
		size_t	size
	)

Log a pretty, formatted hex dump.

Parameters:

	mask	Set/clear application defined bits to reduce spew
	ptr	Pointer to data to dump
	size	Size of data to dump

Definition at line 124 of file debug.c.

References assertconst, and debug_logalways().

{
    assertconst(ptr,size);
    if( (mask & debug_logmask) || 0 == mask )
    {
        char printable[16];
        const unsigned char* pBuff = (const unsigned char*)ptr;
        size_t curr = 0;
        while( curr < size )
        {
            unsigned ch = *pBuff++;
            if( 0 == (curr & 0xf) )
            {
                debug_logalways( "%08x: ", curr );
            }
            debug_logalways( "%02x ", ch );
            printable[curr&0xf] = isprint(ch) ? ch : '.';
            if( 0xf == (curr++ & 0xf) )
            {
                debug_logalways( " | %16.16s\n", printable );
            }
        }
        /* Leftovers */
        if( 0 != (size & 0xf) )
        {
            for( curr = curr & 0xf; curr < 16; ++curr )
            {
                debug_logalways( "-- " );
                printable[curr] = ' ';
            }
            debug_logalways( " | %16.16s\n", printable );
        }
    }
}

Here is the call graph for this function:

void debug_setlogmask

(

unsigned

mask

)

Set log mask.

Parameters:

mask

Set/clear application defined bits to reduce spew

Definition at line 104 of file debug.c.

{
    debug_logmask = mask;
}

void debug_settrace

(

debug_trace_t

trace

)

Set debug trace handler.

Parameters:

trace

Function to handle traces (NULL for default)

Definition at line 180 of file debug.c.

References assertcodeptr, and debug_trace.

{
    debug_trace = NULL == trace ? debug_printf : trace;
    assertcodeptr(debug_trace);
}

void debug_setvlog

(

debug_vlog_t

debug_vlog

)

Set log handler.

Parameters:

log

Function to handle traces (NULL for default - vprintf)

Definition at line 87 of file debug.c.

References assertcodeptr.

{
    if( NULL == debug_vlog )
    {
        pdebug_vlog = vprintf;
    }
    else
    {
        pdebug_vlog =  debug_vlog;
    }
    assertcodeptr(pdebug_vlog);
}

void debug_vlog	(	unsigned	mask,
		const char *	fmt,
		va_list	args
	)

Logging function.

Parameters:

	mask	Mask to check against allowable log types, or 0 for 'always'
	fmt	It's a vprintf, so format accordingly
	args	stdarg type argument pointer for vprintf-like function

Definition at line 48 of file debug.c.

References assertcodeptr, and assertconst.

Referenced by Socket_LogError(), and SocketsLogLastError().

{
    if( (mask & debug_logmask) || 0 == mask )
    {
        assertconst(fmt,1);
        assertcodeptr(pdebug_vlog);
        pdebug_vlog( fmt, args );
    }
}

void debug_vlogalways	(	const char *	fmt,
		va_list	args
	)

Logging function that always logs.

Parameters:

	fmt	It's a vprintf, so format accordingly
	args	Arguments from va_start(args,fmt)

Definition at line 76 of file debug.c.

References assertcodeptr, and assertconst.

Referenced by serial_log().

{
    assertconst(fmt,1);
    assertcodeptr(pdebug_vlog);
    pdebug_vlog( fmt, args );
}