Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

21    Debug Manager

System Management

Exploring Palm OS®

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 ^TOP^

DbgBreak Function ^TOP^

Purpose

Connects to the external debugger and halts execution.

Declared In

DebugMgr.h

Prototype

void DbgBreak (
   void
)

Parameters

None.

Returns

Returns nothing.

Comments

This function currently halts the entire device. Future implementations may halt only the calling thread.

See Also

DbgBreakMessage(), DbgBreakMessageIf()

DbgBreakMessage Macro ^TOP^

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

message
The string to be sent to the current debug device.

Returns

Returns nothing.

Comments

This macro uses DbgMessage() to send the string to the current debug device and DbgBreak() to halt execution.

DbgBreakMessageIf Macro ^TOP^

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

Returns nothing.

Comments

This macro uses DbgMessage() to send the string to the current debug device and DbgBreak() to halt execution.

DbgFatalErrorInContext Function ^TOP^

Purpose

Declared In

DebugMgr.h

Prototype

uint32_t DbgFatalErrorInContext (
   const char *fileName,
   uint32_t lineNum,
   const char *errMsg,
   uint32_t options,
   uint32_t allowedResponses
)

Parameters

fileName
lineNum
errMsg
options
allowedResponses

Returns

Comments

Low-level error reporting: this gives a few options to the developer such as ignore, break, etc.

DbgGetChar Function ^TOP^

Purpose

Reads a single character from the debug device.

Declared In

DebugMgr.h

Prototype

char DbgGetChar (
   void
)

Parameters

None.

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 ^TOP^

Purpose

Determine whether the debugger is connected.

Declared In

DebugMgr.h

Prototype

Boolean DbgIsPresent (
   void
)

Parameters

None.

Returns

Returns true if the debugger is connected, false otherwise.

DbgLookupSymbol Function ^TOP^

Purpose

Obtain the raw symbol name for a given function.

Declared In

DebugMgr.h

Prototype

status_t DbgLookupSymbol (
   const void *addr,
   int32_t maxLen,
   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

DbgUnmangleSymbol()

DbgMessage Function ^TOP^

Purpose

Sends a null-terminated string to the current debug device.

Declared In

DebugMgr.h

Prototype

void DbgMessage (
   const char *iStringP
)

Parameters

iStringP
The string to be sent to the current debug device.

Returns

Returns nothing.

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

DbgPrintf(), DbgVPrintf()

DbgOutputSync Function ^TOP^

Purpose

Forces the output stream to be flushed if the output device is buffered.

Declared In

DebugMgr.h

Prototype

void DbgOutputSync (
   void
)

Parameters

None.

Returns

Returns nothing.

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 ^TOP^

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

DbgMessage(), DbgVPrintf()

DbgRestartMallocProfiling Function ^TOP^

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

None.

Returns

Nothing.

See Also

DbgSetMallocProfiling()

DbgSetMallocProfiling Function ^TOP^

Purpose

Declared In

DebugMgr.h

Prototype

void DbgSetMallocProfiling (
   Boolean enabled,
   int32_t dumpPeriod,
   int32_t maxItems,
   int32_t stackDepth
)

Parameters

enabled
dumpPeriod
maxItems
stackDepth

Returns

See Also

DbgRestartMallocProfiling()

DbgUnmangleSymbol Function ^TOP^

Purpose

Get the corresponding unmanged name for a symbol.

Declared In

DebugMgr.h

Prototype

status_t DbgUnmangleSymbol (
   char *symbol,
   int32_t maxLen,
   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

DbgLookupSymbol()

DbgVPrintf Function ^TOP^

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_list arglist
)

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

DbgMessage(), DbgPrintf()

DbgWalkStack Function ^TOP^

Purpose

Retrieve a stack crawl for the current thread.

Declared In

DebugMgr.h

Prototype

int32_t DbgWalkStack (
   int32_t ignoreDepth,
   int32_t maxResults,
   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()