Debugging Functions

Module Description

Flexible debug output and system error messages.
#include <uLib/Debug.h>

The default settings are dbg_Level = DP_DEBUG, dbg_LogFile = NULL, and dbg_Name = "[uLib]",
so a typical debugging ingress in WinMain might be...

#if _DEBUG
  dbg_Name = "[MyProgram]";
  //dbg_Level = DP_VERBOSE; // or whatever fits the situation..
  dbg_LogFile = OpenLogFile( NULL, false ); // Use default log pathname.
#endif

Groups
	DPrint Levels
	DPrint severity filtering thresholds...
	Conditional Debugging Macros
	These macros are active in _DEBUG builds, and voided in Release builds.

Macros
#define	_F(s)   _T("[") _T(__FUNCTION__) _T("] ") _T(s)
#define	DP_StdFailMsg(What)   DPrint( DP_ERROR, What _T(" failed: %s\n"), SysErrorMsg() )

Functions
void __cdecl	DPrint (int Level, CSTR Fmt,...)
CSTR	SysErrorMsg (DWORD Err=0, TSTR Buf=NULL, UINT Length=0)
CSTR	NtErrorMsg (NTSTATUS Status=0, TSTR Buf=NULL, UINT Size=0)
bool	SetLastErrorFromNtStatus (NTSTATUS Status)
ACSTR	GetWinMsgName (WORD msgId)
ACSTR	GetExceptionName (DWORD xCode)
int	SetDebugLevel (int Level)
HANDLE	OpenLogFile (CSTR Name, bool Append)
CSTR	DefaultLogFileName (HMODULE hModule)

Variables
CSTR	dbg_Name
int	dbg_Level
HANDLE	dbg_LogFile
bool	dbg_Flush

Macro Definition Documentation

_F

#define _F

(

s

)

_T("[") _T(__FUNCTION__) _T("] ") _T(s)

The resulting string OF _F() has the form "[FunctionName] string-argument".

Typical use: TRACE( DP_DEBUG, _F("Xyz failed: %s\n"), SysErrorMsg() );

Note: On GCC, the _F macro can ony be used in var-arg parameter lists! See also: TRACE, TRACEX, TRACE_IF

Definition at line 49 of file Debug.h.

DP_StdFailMsg

#define DP_StdFailMsg

(

What

)

DPrint( DP_ERROR, What _T(" failed: %s\n"), SysErrorMsg() )

Persistent debug trace (as opposed to build dependent TRACE)

Definition at line 169 of file Debug.h.

Function Documentation

DPrint()

void __cdecl DPrint	(	int	Level,
		CSTR	Fmt,
			...
	)

DPrint outputs a string to the debugger if Level <= dbg_Level.

The output string has the format "dbg_Name LEVEL: Fmt and inserts".
If dbg_LogFile is not NULL, the string is written to the log file as well.

Level zero messages are meant to always be emitted.
To squelch all output, set dbg_Level = -1.
Text is formatted with _vstprintf_s into an internal buffer of 512 chars.
See also dbg_Name, dbg_Level

Definition at line 134 of file Debug.cpp.

SysErrorMsg()

CSTR SysErrorMsg	(	DWORD	Err = 0,
		TSTR	Buf = NULL,
		UINT	Length = 0
	)

SysErrorMsg returns the system defined error message for the Err code.

If Err zero is passed in, the error is queried with GetLastError().
If a Buf is passed in, it is used to return the error string.
If Buf is NULL and Length is non-zero, Buf is allocated with newStrBuf().
If Buf is NULL and Length is zero, an internal static buffer is used.

Returns

Returns the resulting string, with any trailing CR|LF removed.

Definition at line 39 of file Debug.cpp.

NtErrorMsg()

CSTR NtErrorMsg	(	NTSTATUS	Status = 0,
		TSTR	Buf = NULL,
		UINT	Size = 0
	)

NtErrorMsg is an experimental wrap for SysErrorMsg,
using LsaNtStatusToWinError() to translate the NTSTATUS..
Will the error code translations make sense ?

Definition at line 67 of file Debug.cpp.

SetLastErrorFromNtStatus()

bool SetLastErrorFromNtStatus

(

NTSTATUS

Status

)

Provide a wrap for "RtlSetLastWin32ErrorAndNtStatusFromNtStatus()" (urrk).
If that API wasn't found, use SetLastError( LsaNtStatusToWinError( Status )).
Return true if the Rtl API was found in NTDLL.

Definition at line 74 of file Debug.cpp.

GetWinMsgName()

ACSTR GetWinMsgName

(

WORD

msgId

)

Get a string representation of a windows message, e.g "WM_CONTEXTMENU".
In a release build this only returns "WM_<hex>(<decimal>)".

Definition at line 37 of file MsgTbl.cpp.

GetExceptionName()

ACSTR GetExceptionName

(

DWORD

xCode

)

Get a string representation of an exception code, e.g "EXCEPTION_ACCESS_VIOLATION".
In a release build this only returns "Exception <hex>".

Definition at line 641 of file MsgTbl.cpp.

SetDebugLevel()

int SetDebugLevel

(

int

Level

)

SetDebugLevel sets the debugging output threshold dbg_Level.
It returns the previous debugging level.

Definition at line 107 of file Debug.cpp.

OpenLogFile()

HANDLE OpenLogFile	(	CSTR	Name,
		bool	Append
	)

Open a debugging log file, suitable for dbg_LogFile.

If Name is NULL, the file name is generated with DefaultLogFileName().
If Append is true, the file pointer is moved to the end of the file.

Definition at line 220 of file Debug.cpp.

DefaultLogFileName()

CSTR DefaultLogFileName

(

HMODULE

hModule

)

Generate a file name suitable for a debugging log file.

hModule is used to generate a name of the form "X:\Path\NameOfModule.log".
If hModule is NULL, the file name of the current process is used as base.

Definition at line 239 of file Debug.cpp.

Variable Documentation

dbg_Name

CSTR dbg_Name

DPrint prefix string. Default = "[uLib]".

Definition at line 114 of file Debug.cpp.

dbg_Level

int dbg_Level

DPrint threshold level. Default = DP_DEBUG.

Definition at line 105 of file Debug.cpp.

dbg_LogFile

HANDLE dbg_LogFile

Optional DPrint logfile handle. Default = NULL.

Definition at line 115 of file Debug.cpp.

dbg_Flush

bool dbg_Flush

Always FlushFileBuffers on logfile write. Default = false.

Definition at line 116 of file Debug.cpp.