This chapter provides reference material for the Debug Manager. It is organized as follows:
Debug Manager Functions and Macros
The header file DebugMgr.h
declares the API that this chapter describes.
Debug Manager Functions and Macros
DbgBreak Function
Purpose
Connects to the external debugger and halts execution.
Declared In
DebugMgr.h
Prototype
void DbgBreak ( void )
Parameters
Returns
Comments
This function currently halts the entire device. Future implementations may halt only the calling thread.
See Also
DbgBreakMessage()
, DbgBreakMessageIf()
DbgBreakMessage Macro
Purpose
Sends a null-terminated string to the current debug device, then connects to the external debugger and halts execution.
Declared In
DebugMgr.h
Prototype
#define DbgBreakMessage (
message
)
Parameters
Returns
Comments
This macro uses DbgMessage()
to send the string to the current debug device and DbgBreak()
to halt execution.
DbgBreakMessageIf Macro
Purpose
If a specified condition evaluates to true
, sends a null-terminated string to the current debug device, then connects to the external debugger and halts execution.
Declared In
DebugMgr.h
Prototype
#define DbgBreakMessageIf (condition
,message
)
Parameters
-
→ condition
- If this argument evaluates to
true
, the macro sends a null-terminated string to the current debug device, then connects to the external debugger and halts execution. Otherwise, this macro does nothing. -
→ message
- The string to be sent to the current debug device.
Returns
Comments
This macro uses DbgMessage()
to send the string to the current debug device and DbgBreak()
to halt execution.
DbgFatalErrorInContext Function
Purpose
Declared In
DebugMgr.h
Prototype
uint32_t DbgFatalErrorInContext ( const char*fileName
, uint32_tlineNum
, const char*errMsg
, uint32_toptions
, uint32_tallowedResponses
)
Parameters
Returns
Comments
Low-level error reporting: this gives a few options to the developer such as ignore, break, etc.
DbgGetChar Function
Purpose
Reads a single character from the debug device.
Declared In
DebugMgr.h
Prototype
char DbgGetChar ( void )
Parameters
Returns
Returns the character read from the debug device.
Comments
On some devices, this may block all threads until the character has been read.
DbgIsPresent Function
Purpose
Determine whether the debugger is connected.
Declared In
DebugMgr.h
Prototype
Boolean DbgIsPresent ( void )
Parameters
Returns
Returns true
if the debugger is connected, false
otherwise.
DbgLookupSymbol Function
Purpose
Obtain the raw symbol name for a given function.
Declared In
DebugMgr.h
Prototype
status_t DbgLookupSymbol ( const void*addr
, int32_tmaxLen
, char*outSymbol
, void**outAddr
)
Parameters
-
→ addr
- The address of the function for which the raw symbol name is to be returned.
-
→ maxLen
- The size of the buffer into which the raw symbol name is to be written.
-
← outSymbol
- The raw symbol name of the specified function.
-
← outAddr
Returns
Compatibility
This function is only implemented for the Palm OS Simulator.
See Also
DbgMessage Function
Purpose
Sends a null-terminated string to the current debug device.
Declared In
DebugMgr.h
Prototype
void DbgMessage (
const char *iStringP
)
Parameters
Returns
Comments
The string is not guaranteed to be sent atomically; concurrent DbgMessage()
calls may result in interleaved output unless some mutual exclusion is provided by the caller.
See Also
DbgOutputSync Function
Purpose
Forces the output stream to be flushed if the output device is buffered.
Declared In
DebugMgr.h
Prototype
void DbgOutputSync ( void )
Parameters
Returns
Comments
The call does not return until all pending output has been written out. If the output device is not buffered, this call is a no-op.
DbgPrintf Function
Purpose
Sends a string to the current debug device. The string is constructed using sprintf()
; accordingly, you pass this function a format string and a set of arguments.
Declared In
DebugMgr.h
Prototype
long DbgPrintf ( const char *iFormat, ... )
Parameters
-
→ iFormat
- Format string, as specified by
sprintf()
. -
→ ...
- Zero or more argument to be written, formatted according to
iFormat
, to the current debug device.
Returns
Returns the number of bytes written to the current debug device.
Comments
This function builds a string, up to 200 characters in length, using sprintf()
, and then sends it out using DbgMessage()
. Formatted strings in excess of 200 characters will be truncated.
See Also
DbgRestartMallocProfiling Function
Purpose
Clear out all malloc()
profiling statistics that have been collected so far for the current process.
Declared In
DebugMgr.h
Prototype
void DbgRestartMallocProfiling ( void )
Parameters
Returns
See Also
DbgSetMallocProfiling Function
Purpose
Declared In
DebugMgr.h
Prototype
void DbgSetMallocProfiling ( Booleanenabled
, int32_tdumpPeriod
, int32_tmaxItems
, int32_tstackDepth
)
Parameters
Returns
See Also
DbgUnmangleSymbol Function
Purpose
Get the corresponding unmanged name for a symbol.
Declared In
DebugMgr.h
Prototype
status_t DbgUnmangleSymbol ( char*symbol
, int32_tmaxLen
, char*outName
)
Parameters
-
→ symbol
- The name of the symbol.
-
→ maxLen
- The size of the buffer into which the unmangled name is to be written.
-
← outName
- The unmangled name of the symbol.
Returns
Compatibility
This function is only implemented for the Palm OS Simulator.
See Also
DbgVPrintf Function
Purpose
Sends a string to the current debug device. The string is constructed using vsprintf()
; accordingly, you pass this function a format string and a set of arguments.
Declared In
DebugMgr.h
Prototype
long DbgVPrintf ( const char*iFormat
, va_listarglist
)
Parameters
-
→ iFormat
- Format string, as specified by
vsprintf()
. -
→ arglist
- Set of arguments (specified varargs-style) to be written, formatted according to
iFormat
, to the current debug device.
Returns
Returns the number of bytes written to the current debug device.
Comments
This function builds a string, up to 200 characters in length, using vsprintf()
, and then sends it out via DbgMessage()
. Formatted strings in excess of 200 characters will be truncated.
See Also
DbgWalkStack Function
Purpose
Retrieve a stack crawl for the current thread.
Declared In
DebugMgr.h
Prototype
int32_t DbgWalkStack ( int32_tignoreDepth
, int32_tmaxResults
, void**outAddresses
)
Parameters
-
→ ignoreDepth
- Allows you to skip functions at the top of the stack.
-
→ maxResults
- The maximum number of available slots to return.
-
← outAddresses
- Filled in with the address of each function on the stack, from the immediate caller down.
Returns
Returns the number of functions actually found.
Compatibility
This function is only implemented for the Palm OS Simulator.
See Also
DbgLookupSymbol()
, DbgUnmangleSymbol()