1074 lines
38 KiB
C
1074 lines
38 KiB
C
/*
|
|
File: Debugging.h
|
|
|
|
Contains: Macros to handle exceptions and assertions.
|
|
|
|
Version: QuickTime 7.3
|
|
|
|
Copyright: (c) 2007 (c) 1989-2001 by Apple Computer, Inc., all rights reserved.
|
|
|
|
Bugs?: For bug reports, consult the following page on
|
|
the World Wide Web:
|
|
|
|
http://developer.apple.com/bugreporter/
|
|
|
|
*/
|
|
#ifndef __DEBUGGING__
|
|
#define __DEBUGGING__
|
|
|
|
#ifndef __MACTYPES__
|
|
#include <MacTypes.h>
|
|
#endif
|
|
|
|
#ifndef __MIXEDMODE__
|
|
#include <MixedMode.h>
|
|
#endif
|
|
|
|
#ifndef __MACERRORS__
|
|
#include <MacErrors.h>
|
|
#endif
|
|
|
|
#include <Events.h>
|
|
#ifndef __GESTALT__
|
|
#include <Gestalt.h>
|
|
#endif
|
|
|
|
|
|
|
|
#if PRAGMA_ONCE
|
|
#pragma once
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#if PRAGMA_IMPORT
|
|
#pragma import on
|
|
#endif
|
|
|
|
/*
|
|
This file supplies standard debugging routines and macros to Carbon and
|
|
Classic Mac OS programs. Other C programs which wish to use the
|
|
exception handling and assertion macros should include AssertMacros.h
|
|
instead of this file.
|
|
|
|
To activate debugger breaks, #define DEBUG to 1 (one) before including this
|
|
file. Five further levels of debugging are available, selected by #defining
|
|
one of the following conditionals to 1 after DEBUG is defined to 1.
|
|
|
|
DEBUG_INTERNAL the default; asserts include file and line number
|
|
information
|
|
|
|
DEBUG_EXTERNAL used for code which must ship to developers outside
|
|
your organization; no file or line number
|
|
information is included in asserts
|
|
|
|
DEBUG_BREAK_ONLY where an assertion string would normally be sent to
|
|
the debugger; call Debugger() instead.
|
|
|
|
PRODUCTION used for shipping code; no debugger breaks are
|
|
emitted
|
|
|
|
PERFORMANCE same as PRODUCTION
|
|
|
|
#defining DEBUG to 0 is equivalent to #defining PRODUCTION 1 when
|
|
DEBUG is 1. (No code for debugger breaks is emitted in either case.)
|
|
|
|
#defining DEBUG to 1 without specifying a level is equivalent to #defining
|
|
DEBUG_INTERNAL 1.
|
|
|
|
In addition, these macros should also be #defined (they are described in detail below):
|
|
kComponentSignatureString
|
|
COMPONENT_SIGNATURE
|
|
*/
|
|
/*
|
|
* Before including this file, #define kComponentSignatureString to a C-string
|
|
* containing the name of your client and #define COMPONENT_SIGNATURE to your
|
|
* client's unique signature (i.e., your program's registered creator type).
|
|
* For example:
|
|
*
|
|
* #define kComponentSignatureString "SurfWriter"
|
|
* #define COMPONENT_SIGNATURE 'WAVE'
|
|
*
|
|
* If you don't define kComponentSignatureString and COMPONENT_SIGNATURE, the
|
|
* default kComponentSignatureString and COMPONENT_SIGNATURE values will be
|
|
* used by the DEBUGASSERTMSG macros below.
|
|
*/
|
|
|
|
#ifndef kComponentSignatureString
|
|
#define kComponentSignatureString "Third Party Client"
|
|
#endif
|
|
#ifndef COMPONENT_SIGNATURE
|
|
#define COMPONENT_SIGNATURE '?*?*'
|
|
#endif
|
|
#define QuoteExceptionString(x) #x
|
|
|
|
|
|
/*
|
|
* The DEBUGLEVEL's
|
|
*/
|
|
#define DEBUG_LEVEL_PRODUCTION 0
|
|
#define DEBUG_LEVEL_BREAK_ONLY 1
|
|
#define DEBUG_LEVEL_EXTERNAL 3
|
|
#define DEBUG_LEVEL_INTERNAL 4
|
|
#define DEBUGFULL DEBUG_LEVEL_INTERNAL
|
|
|
|
/*
|
|
* define DEBUGLEVEL
|
|
*/
|
|
#if DEBUG
|
|
#if PRODUCTION
|
|
#define DEBUGLEVEL DEBUG_LEVEL_PRODUCTION
|
|
#elif PERFORMANCE
|
|
#define DEBUGLEVEL DEBUG_LEVEL_PRODUCTION
|
|
#elif DEBUG_BREAK_ONLY
|
|
#define DEBUGLEVEL DEBUG_LEVEL_BREAK_ONLY
|
|
#elif DEBUG_EXTERNAL
|
|
#define DEBUGLEVEL DEBUG_LEVEL_EXTERNAL
|
|
#elif DEBUG_INTERNAL
|
|
#define DEBUGLEVEL DEBUG_LEVEL_INTERNAL
|
|
#else
|
|
/* default to DEBUG_LEVEL_INTERNAL */
|
|
#define DEBUGLEVEL DEBUG_LEVEL_INTERNAL
|
|
#endif
|
|
#endif
|
|
#ifndef DEBUGLEVEL
|
|
#define DEBUGLEVEL DEBUG_LEVEL_PRODUCTION
|
|
#endif
|
|
|
|
|
|
|
|
/*
|
|
* The options parameter to DebugAssert and DEBUGASSERTMSG is currently reserved (must be zero).
|
|
*/
|
|
#define DEBUG_NO_OPTIONS 0
|
|
|
|
/*
|
|
* DEBUGASSERTMSG()
|
|
*
|
|
* Summary:
|
|
* All error reporting is routed through this macro, which calls the system
|
|
* routine DebugAssert(). If you wish to use your own assertion break
|
|
* routine, you can override DEBUGASSERTMSG by defining it before including
|
|
* this file.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* componentSignature:
|
|
* The unique signature of component causing the assertion.
|
|
*
|
|
* options:
|
|
* reserved.
|
|
*
|
|
* assertionString:
|
|
* A pointer to a string constant containing the assertion.
|
|
* This must be a string constant (and not a string variable or
|
|
* NULL) because the Proeprocessor concatenates it with other
|
|
* string constants
|
|
*
|
|
* exceptionLabelString:
|
|
* A pointer to a string containing the exceptionLabel, or NULL.
|
|
*
|
|
* errorString:
|
|
* A pointer to the error string, or NULL. DEBUGASSERTMSG macros
|
|
* must not attempt to concatenate this string with constant
|
|
* character strings.
|
|
*
|
|
* fileName:
|
|
* A pointer to the fileName or pathname (generated by the
|
|
* preprocessor __FILE__ identifier), or NULL.
|
|
*
|
|
* lineNumber:
|
|
* The line number in the file (generated by the preprocessor
|
|
* __LINE__ identifier), or 0 (zero).
|
|
*
|
|
* value:
|
|
* A value associated with the assertion, or NULL.
|
|
*/
|
|
|
|
#ifndef DEBUGASSERTMSG
|
|
#if DEBUGLEVEL == DEBUG_LEVEL_PRODUCTION
|
|
/* no debugger message */
|
|
#define DEBUGASSERTMSG(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value)
|
|
#elif DEBUGLEVEL == DEBUG_LEVEL_BREAK_ONLY
|
|
/* call Debugger() if it is available */
|
|
#define DEBUGASSERTMSG(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) \
|
|
Debugger()
|
|
#elif DEBUGLEVEL == DEBUG_LEVEL_EXTERNAL
|
|
/* exclude fileName and lineNumber */
|
|
#define DEBUGASSERTMSG(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) \
|
|
DebugAssert(componentSignature, options, assertionString, exceptionLabelString, errorString, 0, 0, (void*)value)
|
|
#else
|
|
/* include all info */
|
|
#define DEBUGASSERTMSG(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) \
|
|
DebugAssert(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, (void*)value)
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* Define the three inputs to AssertMacros.h
|
|
*/
|
|
|
|
#ifndef DEBUG_ASSERT_COMPONENT_NAME_STRING
|
|
#define DEBUG_ASSERT_COMPONENT_NAME_STRING kComponentSignatureString
|
|
#endif
|
|
#ifndef DEBUG_ASSERT_PRODUCTION_CODE
|
|
#define DEBUG_ASSERT_PRODUCTION_CODE (DEBUGLEVEL==0)
|
|
#endif
|
|
#ifndef DEBUG_ASSERT_MESSAGE
|
|
#define DEBUG_ASSERT_MESSAGE(componentNameString, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) \
|
|
DEBUGASSERTMSG(COMPONENT_SIGNATURE, DEBUG_NO_OPTIONS, componentNameString ": " assertionString, exceptionLabelString, errorString, fileName, lineNumber, value)
|
|
#endif
|
|
|
|
/*
|
|
* Include AssertMacros.h where all of the check, verify, and require macros are defined
|
|
*/
|
|
#include <AssertMacros.h>
|
|
/*
|
|
* The following check, verify, and require macros assert that TaskLevel is 0.
|
|
*/
|
|
|
|
#define ATTASKLEVEL0() \
|
|
(TaskLevel() == 0)
|
|
|
|
|
|
#define check_tasklevel0() \
|
|
check(ATTASKLEVEL0())
|
|
|
|
|
|
#define check_tasklevel0_string(cstring) \
|
|
check_string(ATTASKLEVEL0(), cstring)
|
|
|
|
|
|
#define verify_tasklevel0() \
|
|
verify(ATTASKLEVEL0())
|
|
|
|
|
|
#define verify_tasklevel0_string(cstring) \
|
|
verify_string(ATTASKLEVEL0(), cstring)
|
|
|
|
|
|
#define require_tasklevel0(exceptionLabel) \
|
|
require(ATTASKLEVEL0(), exceptionLabel)
|
|
|
|
|
|
#define require_tasklevel0_action(exceptionLabel, action) \
|
|
require_action(ATTASKLEVEL0(), exceptionLabel, action)
|
|
|
|
|
|
#define require_tasklevel0_quiet(exceptionLabel) \
|
|
require_quiet(ATTASKLEVEL0(), exceptionLabel)
|
|
|
|
|
|
#define require_tasklevel0_action_quiet(exceptionLabel, action) \
|
|
require_action_quiet(ATTASKLEVEL0(), exceptionLabel, action)
|
|
|
|
|
|
#define require_tasklevel0_string(exceptionLabel, cstring) \
|
|
require_string(ATTASKLEVEL0(), exceptionLabel, cstring)
|
|
|
|
|
|
#define require_tasklevel0_action_string(exceptionLabel, action, cstring) \
|
|
require_action_string(ATTASKLEVEL0(), exceptionLabel, action, cstring)
|
|
|
|
/*
|
|
* SafeDebugger and SafeDebugStr work like Debugger and DebugStr in both
|
|
* production and non-preduction builds, but only call the debugger
|
|
* if the debugger is installed.
|
|
*/
|
|
|
|
#if CALL_NOT_IN_CARBON
|
|
/* Make sure a low level debugger is installed on Mac OS 8 or 9 */
|
|
#define SafeDebugger() \
|
|
do \
|
|
{ \
|
|
if ( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \
|
|
(((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \
|
|
((*((unsigned long *)0x0120)) != 0) && \
|
|
((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) ) \
|
|
{ \
|
|
Debugger(); \
|
|
} \
|
|
} while ( false )
|
|
#else
|
|
/* Debugger() is always safe on Carbon under Mac OS X */
|
|
/* Otherwise we must make sure a low level debugger is installed */
|
|
#define SafeDebugger() \
|
|
do \
|
|
{ \
|
|
long response; \
|
|
if ( (Gestalt(gestaltSystemVersion, &response) == noErr) && \
|
|
(response >= 0x1000) ) \
|
|
{ \
|
|
Debugger(); \
|
|
} \
|
|
else \
|
|
{ \
|
|
if ( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \
|
|
(((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \
|
|
((*((unsigned long *)0x0120)) != 0) && \
|
|
((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) ) \
|
|
{ \
|
|
Debugger(); \
|
|
} \
|
|
} \
|
|
} while ( false )
|
|
#endif
|
|
|
|
|
|
#if CALL_NOT_IN_CARBON
|
|
/* Make sure low level debugger is installed on Mac OS 8 or 9 */
|
|
#define SafeDebugStr(str) \
|
|
do \
|
|
{ \
|
|
if ( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \
|
|
(((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \
|
|
((*((unsigned long *)0x0120)) != 0) && \
|
|
((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) ) \
|
|
{ \
|
|
DebugStr(str); \
|
|
} \
|
|
} while ( false )
|
|
#else
|
|
/* DebugStr() is always safe on Carbon under Mac OS X */
|
|
/* Otherwise we must make sure a low level debugger is installed */
|
|
#define SafeDebugStr(str) \
|
|
do \
|
|
{ \
|
|
long response; \
|
|
if ( (Gestalt(gestaltSystemVersion, &response) == noErr) && \
|
|
(response >= 0x1000) ) \
|
|
{ \
|
|
DebugStr(str); \
|
|
} \
|
|
else \
|
|
{ \
|
|
if ( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \
|
|
(((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \
|
|
((*((unsigned long *)0x0120)) != 0) && \
|
|
((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) ) \
|
|
{ \
|
|
DebugStr(str); \
|
|
} \
|
|
} \
|
|
} while ( false )
|
|
#endif
|
|
|
|
/*
|
|
* DEBUGGER and DEBUGSTR call SafeDebugger and SafeDebugStr only
|
|
* in DEBUG builds.
|
|
*
|
|
* DEBUGGER and DEBUGSTR are defined only if they are not already defined to
|
|
* prevent conflicts with developer code.
|
|
*/
|
|
|
|
#ifndef DEBUGGER
|
|
#if DEBUG
|
|
#define DEBUGGER() \
|
|
SafeDebugger()
|
|
#else
|
|
#define DEBUGGER()
|
|
#endif
|
|
#endif
|
|
|
|
#ifndef DEBUGSTR
|
|
#if DEBUG
|
|
#define DEBUGSTR(str) \
|
|
SafeDebugStr(str)
|
|
#else
|
|
#define DEBUGSTR(str)
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* CapsLockDebugger and CapsLockDebugStr call SafeDebugger and SafeDebugStr
|
|
* only if the Caps Lock key is down.
|
|
*/
|
|
|
|
#define CapsLockDebugger() \
|
|
do \
|
|
{ \
|
|
KeyMap theKeys; \
|
|
GetKeys(theKeys); \
|
|
if ( ((theKeys[1] >> 1) & 0x01) != 0 ) \
|
|
{ \
|
|
SafeDebugger(); \
|
|
} \
|
|
} while ( false )
|
|
|
|
|
|
#define CapsLockDebugStr(str) \
|
|
do \
|
|
{ \
|
|
KeyMap theKeys; \
|
|
GetKeys(theKeys); \
|
|
if ( ((theKeys[1] >> 1) & 0x01) != 0 ) \
|
|
{ \
|
|
SafeDebugStr(str); \
|
|
} \
|
|
} while ( false )
|
|
|
|
/*
|
|
* ISCAPSLOCKKEYDOWN and ISLOWLEVELDEBUGGERCALLABLE are convenience macros
|
|
* which are only defined for non-Carbon builds because they access
|
|
* low memory addresses directly. They have been left in this file for
|
|
* use by existing non-Carbon code.
|
|
*
|
|
* ISCAPSLOCKKEYDOWN and ISLOWLEVELDEBUGGERCALLABLE are defined only
|
|
* if they are not already defined to prevent conflicts with developer code.
|
|
*/
|
|
|
|
#if CALL_NOT_IN_CARBON
|
|
#ifndef ISCAPSLOCKKEYDOWN
|
|
#define ISCAPSLOCKKEYDOWN() \
|
|
((((UInt16 *)(0x0174))[3] & 0x0002) == 0x0002)
|
|
#endif
|
|
|
|
#ifndef ISLOWLEVELDEBUGGERCALLABLE
|
|
#define ISLOWLEVELDEBUGGERCALLABLE() \
|
|
( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \
|
|
(((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \
|
|
((*((unsigned long *)0x0120)) != 0) && \
|
|
((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) )
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* You can use DPRINTF as a dprintf which goes away in production builds.
|
|
* DPRINTF is not supported by Carbon because dprintf
|
|
* is not supported by Carbon.
|
|
*
|
|
* To use it, double-parenthesize the argument - i.e., use:
|
|
*
|
|
* DPRINTF(("formatString %d", 5 ));
|
|
*
|
|
* This is sadly necessary because a macro can not have a variable number
|
|
* of arguments.
|
|
*
|
|
* DPRINTF is defined only if it is not already defined to
|
|
* prevent conflicts with developer code.
|
|
*/
|
|
|
|
#if DEBUG
|
|
#define DPRINTF(x) dprintf x
|
|
#else
|
|
#define DPRINTF(x) { }
|
|
#endif
|
|
|
|
|
|
/*
|
|
* kBlessedBusErrorBait is an address that will never be mapped by
|
|
* Mac OS 8 or 9. It is close to the middle of the 64K range from 0x68F10000
|
|
* to 0x68F1FFFF that is unmapped and cannot be accessed without causing an
|
|
* exception. Thus, it's a good value to use for filling uninitialized
|
|
* pointers, etc.
|
|
*
|
|
* Mac OS X programs should NOT use kBlessedBusErrorBait and should use
|
|
* zero (0) instead, since by default, page 0 is read and write protected
|
|
* for user code.
|
|
*/
|
|
enum {
|
|
kBlessedBusErrorBait = 0x68F168F1
|
|
};
|
|
|
|
/*
|
|
* DebugAssert()
|
|
*
|
|
* Summary:
|
|
* DebugAssert is the system routine that the DEBUGASSERTMSG macro
|
|
* calls (by default) to display assertion messsages. The output
|
|
* from DebugAssert can be redirected by installing a
|
|
* DebugAssertOutputHandler with InstallDebugAssertOutputHandler.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* componentSignature:
|
|
* The unique signature of component causing the assertion.
|
|
*
|
|
* options:
|
|
* reserved.
|
|
*
|
|
* assertionString:
|
|
* A pointer to a string containing the assertion, or NULL.
|
|
*
|
|
* exceptionLabelString:
|
|
* A pointer to a string containing the exceptionLabel, or NULL.
|
|
*
|
|
* errorString:
|
|
* A pointer to the error string, or NULL.
|
|
*
|
|
* fileName:
|
|
* A pointer to the fileName or pathname (generated by the
|
|
* preprocessor __FILE__ identifier), or NULL.
|
|
*
|
|
* lineNumber:
|
|
* The line number in the file (generated by the preprocessor
|
|
* __LINE__ identifier), or 0 (zero).
|
|
*
|
|
* value:
|
|
* A value associated with the assertion, or NULL.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.0 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( void )
|
|
DebugAssert(
|
|
OSType componentSignature,
|
|
UInt32 options,
|
|
const char * assertionString,
|
|
const char * exceptionLabelString,
|
|
const char * errorString,
|
|
const char * fileName,
|
|
long lineNumber,
|
|
void * value) TWOWORDINLINE(0x7000, 0xAA7E);
|
|
|
|
|
|
/*
|
|
* TaskLevel masks
|
|
*/
|
|
enum {
|
|
k68kInterruptLevelMask = 0x00000007, /* 68K interrupt levels 0 through 7 */
|
|
kInVBLTaskMask = 0x00000010, /* VBLs are executing */
|
|
kInDeferredTaskMask = 0x00000020, /* Deferred tasks are executing */
|
|
kInSecondaryIntHandlerMask = 0x00000040, /* Secondary interrupt handlers are executing */
|
|
kInNestedInterruptMask = 0x00000080 /* The system is handling an interrupt */
|
|
};
|
|
|
|
/*
|
|
* TaskLevel()
|
|
*
|
|
* Summary:
|
|
* TaskLevel returns 0 if we're (probably) running at non-interrupt
|
|
* time. There's no way to make this perfect, but this is as close
|
|
* as we can get. If TaskLevel doesn't return 0, then one of the
|
|
* TaskLevel masks can be used to learn more.
|
|
*
|
|
* Result:
|
|
* The current task level.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.0 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( UInt32 )
|
|
TaskLevel(void) TWOWORDINLINE(0x7001, 0xAA7E);
|
|
|
|
|
|
/*
|
|
* Constants used by the DebugComponent functions
|
|
*/
|
|
enum {
|
|
kComponentDebugOption = 0 /* optionSelectorNum to turn breaks for component On or Off*/
|
|
};
|
|
|
|
enum {
|
|
kGetDebugOption = 1, /* get current debug option setting*/
|
|
kSetDebugOption = 2 /* set debug option*/
|
|
};
|
|
|
|
|
|
/*
|
|
* DebugComponentCallbackProcPtr
|
|
*
|
|
* Discussion:
|
|
* DebugComponentCallback is the callback into a component that
|
|
* registers with DebugLib. It is called to get the debug option
|
|
* setting, or to turn a debug option on or off.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* optionSelectorNum:
|
|
* The component debug option to set.
|
|
*
|
|
* command:
|
|
* The command the DebugComponentCallbackProc must handle:
|
|
* kGetDebugOption - get current debug option setting
|
|
* kSetDebugOption - set debug option
|
|
*
|
|
* optionSetting:
|
|
* A pointer to a Boolean where the DebugComponentCallbackProc
|
|
* must return the option setting: the current setting if command
|
|
* is kGetDebugOption; the new debug option if command is
|
|
* kSetDebugOption
|
|
*/
|
|
typedef CALLBACK_API( void , DebugComponentCallbackProcPtr )(SInt32 optionSelectorNum, UInt32 command, Boolean *optionSetting);
|
|
typedef STACK_UPP_TYPE(DebugComponentCallbackProcPtr) DebugComponentCallbackUPP;
|
|
/*
|
|
* NewDebugComponent()
|
|
*
|
|
* Summary:
|
|
* NewDebugComponent registers a component with DebugLib.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* componentSignature:
|
|
* The unique signature of component.
|
|
*
|
|
* componentName:
|
|
* The displayable string naming the component.
|
|
*
|
|
* componentCallback:
|
|
* The callback into component for working with options.
|
|
*
|
|
* Result:
|
|
* An operating system result code: noErr, memFullErr,
|
|
* debuggingExecutionContextErr, debuggingDuplicateSignatureErr, or
|
|
* debuggingInvalidNameErr.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.0 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
NewDebugComponent(
|
|
OSType componentSignature,
|
|
ConstStr255Param componentName,
|
|
DebugComponentCallbackUPP componentCallback) TWOWORDINLINE(0x7002, 0xAA7E);
|
|
|
|
|
|
/*
|
|
* NewDebugOption()
|
|
*
|
|
* Summary:
|
|
* NewDebugOption registers a debug option with DebugLib.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* componentSignature:
|
|
* The signature of component to register a debug option for.
|
|
*
|
|
* optionSelectorNum:
|
|
* The selector number of this debug option.
|
|
*
|
|
* optionName:
|
|
* The displayable string naming this debug option.
|
|
*
|
|
* Result:
|
|
* An operating system result code: noErr, memFullErr,
|
|
* debuggingExecutionContextErr, debuggingDuplicateOptionErr,
|
|
* debuggingInvalidSignatureErr, debuggingInvalidNameErr, or
|
|
* debuggingNoCallbackErr.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.0 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
NewDebugOption(
|
|
OSType componentSignature,
|
|
SInt32 optionSelectorNum,
|
|
ConstStr255Param optionName) TWOWORDINLINE(0x7003, 0xAA7E);
|
|
|
|
|
|
/*
|
|
* DisposeDebugComponent()
|
|
*
|
|
* Summary:
|
|
* DisposeDebugComponent removes a component registration and all
|
|
* related debug options from DebugLib.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* componentSignature:
|
|
* The unique signature of a component.
|
|
*
|
|
* Result:
|
|
* An operating system result code: noErr,
|
|
* debuggingExecutionContextErr, or debuggingInvalidSignatureErr.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.0 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
DisposeDebugComponent(OSType componentSignature) TWOWORDINLINE(0x7004, 0xAA7E);
|
|
|
|
|
|
/*
|
|
* GetDebugComponentInfo()
|
|
*
|
|
* Summary:
|
|
* GetDebugComponentInfo returns a component registered with
|
|
* DebugLib.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* index:
|
|
* The index into the list of registered components (1-based).
|
|
*
|
|
* componentSignature:
|
|
* A pointer to an OSType where the unique signature of a
|
|
* component is returned.
|
|
*
|
|
* componentName:
|
|
* A pointer to an Str255 where the displayable string naming a
|
|
* component is returned.
|
|
*
|
|
* Result:
|
|
* An operating system result code: noErr or debuggingNoMatchErr.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.0 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
GetDebugComponentInfo(
|
|
UInt32 index,
|
|
OSType * componentSignature,
|
|
Str255 componentName) TWOWORDINLINE(0x7005, 0xAA7E);
|
|
|
|
|
|
/*
|
|
* GetDebugOptionInfo()
|
|
*
|
|
* Summary:
|
|
* GetDebugOptionInfo returns a debug option registered with
|
|
* DebugLib.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* index:
|
|
* The index into the list of registered debug options (0-based);
|
|
* 0 = kComponentDebugOption.
|
|
*
|
|
* componentSignature:
|
|
* The unique signature of a component.
|
|
*
|
|
* optionSelectorNum:
|
|
* A pointer to an SInt32 where the selector number of this debug
|
|
* option is returned.
|
|
*
|
|
* optionName:
|
|
* A pointer to an Str255 where the displayable string naming this
|
|
* debug option is returned.
|
|
*
|
|
* optionSetting:
|
|
* A pointer to an Boolean where the current debug option setting
|
|
* is returned.
|
|
*
|
|
* Result:
|
|
* An operating system result code: noErr,
|
|
* debuggingInvalidSignatureErr, or debuggingNoMatchErr.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.0 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
GetDebugOptionInfo(
|
|
UInt32 index,
|
|
OSType componentSignature,
|
|
SInt32 * optionSelectorNum,
|
|
Str255 optionName,
|
|
Boolean * optionSetting) TWOWORDINLINE(0x7006, 0xAA7E);
|
|
|
|
|
|
/*
|
|
* SetDebugOptionValue()
|
|
*
|
|
* Summary:
|
|
* SetDebugOptionValue sets a debug option registered with DebugLib.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* componentSignature:
|
|
* The unique signature of a component.
|
|
*
|
|
* optionSelectorNum:
|
|
* The selector number of this debug option.
|
|
*
|
|
* newOptionSetting:
|
|
* The new debug option setting.
|
|
*
|
|
* Result:
|
|
* An operating system result code: noErr,
|
|
* debuggingInvalidSignatureErr, or debuggingInvalidOptionErr.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.0 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
SetDebugOptionValue(
|
|
OSType componentSignature,
|
|
SInt32 optionSelectorNum,
|
|
Boolean newOptionSetting) TWOWORDINLINE(0x7007, 0xAA7E);
|
|
|
|
|
|
|
|
/*
|
|
* DebugAssertOutputHandlerProcPtr
|
|
*
|
|
* Discussion:
|
|
* DebugAssertOutputHandler is the callback that registers with
|
|
* DebugLib to handle the output from DebugAssert. The
|
|
* "componentSignature" through "value" parameters are the raw
|
|
* values passed to DebugAssert when an exception occurs.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* componentSignature:
|
|
* The unique signature of component causing the assertion.
|
|
*
|
|
* options:
|
|
* reserved.
|
|
*
|
|
* assertionString:
|
|
* A pointer to a string containing the assertion, or NULL.
|
|
*
|
|
* exceptionLabelString:
|
|
* A pointer to a string containing the exceptionLabel, or NULL.
|
|
*
|
|
* errorString:
|
|
* A pointer to the error string, or NULL.
|
|
*
|
|
* fileName:
|
|
* A pointer to the fileName or pathname (generated by the
|
|
* preprocessor __FILE__ identifier), or NULL.
|
|
*
|
|
* lineNumber:
|
|
* The line number in the file (generated by the preprocessor
|
|
* __LINE__ identifier), or 0 (zero).
|
|
*
|
|
* value:
|
|
* A value associated with the assertion, or NULL.
|
|
*
|
|
* outputMsg:
|
|
* The string DebugAssert build which would normally be passed to
|
|
* DebugStr if a DebugAssertOutputHandler isn't installed.
|
|
*/
|
|
typedef CALLBACK_API( void , DebugAssertOutputHandlerProcPtr )(OSType componentSignature, UInt32 options, const char *assertionString, const char *exceptionLabelString, const char *errorString, const char *fileName, long lineNumber, void *value, ConstStr255Param outputMsg);
|
|
typedef STACK_UPP_TYPE(DebugAssertOutputHandlerProcPtr) DebugAssertOutputHandlerUPP;
|
|
/*
|
|
* InstallDebugAssertOutputHandler()
|
|
*
|
|
* Summary:
|
|
* InstallDebugAssertOutputHandler installs a
|
|
* DebugAssertOutputHandler which DebugAssert calls instead of
|
|
* DebugStr.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* handler:
|
|
* The DebugAssertOutputHandler to install or NULL to switch back
|
|
* to the default handler (DebugStr).
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.0 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( void )
|
|
InstallDebugAssertOutputHandler(DebugAssertOutputHandlerUPP handler) TWOWORDINLINE(0x7008, 0xAA7E);
|
|
|
|
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* dprintf()
|
|
*
|
|
* Summary:
|
|
* printf takes a variable argument list and 'prints' that to the
|
|
* debugging output handler. Calling dprintf() from anything but C
|
|
* or C++ is tricky.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* format:
|
|
* The format string.
|
|
*
|
|
* ...:
|
|
* The arguments to the format string.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.1 and later
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( void )
|
|
dprintf(const char * format, ...) SIXWORDINLINE(0x2057, 0x43EF, 0x0004, 0x303C, 0x000A, 0xAA7E);
|
|
|
|
|
|
/*
|
|
* vdprintf()
|
|
*
|
|
* Summary:
|
|
* vdprintf takes a va_args list and 'prints' that to the debugging
|
|
* output handler.
|
|
*
|
|
* Parameters:
|
|
*
|
|
* format:
|
|
* The format string.
|
|
*
|
|
* va_args_list:
|
|
* The va_args list.
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in DebugLib 1.1 and later
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API( void )
|
|
vdprintf(
|
|
const char * format,
|
|
char * va_args_list) TWOWORDINLINE(0x7009, 0xAA7E);
|
|
|
|
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
/*
|
|
* NewDebugComponentCallbackUPP()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: available as macro/inline
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( DebugComponentCallbackUPP )
|
|
NewDebugComponentCallbackUPP(DebugComponentCallbackProcPtr userRoutine);
|
|
#if !OPAQUE_UPP_TYPES
|
|
enum { uppDebugComponentCallbackProcInfo = 0x00000FC0 }; /* pascal no_return_value Func(4_bytes, 4_bytes, 4_bytes) */
|
|
#ifdef __cplusplus
|
|
inline DEFINE_API_C(DebugComponentCallbackUPP) NewDebugComponentCallbackUPP(DebugComponentCallbackProcPtr userRoutine) { return (DebugComponentCallbackUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebugComponentCallbackProcInfo, GetCurrentArchitecture()); }
|
|
#else
|
|
#define NewDebugComponentCallbackUPP(userRoutine) (DebugComponentCallbackUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebugComponentCallbackProcInfo, GetCurrentArchitecture())
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* NewDebugAssertOutputHandlerUPP()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: available as macro/inline
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( DebugAssertOutputHandlerUPP )
|
|
NewDebugAssertOutputHandlerUPP(DebugAssertOutputHandlerProcPtr userRoutine);
|
|
#if !OPAQUE_UPP_TYPES
|
|
enum { uppDebugAssertOutputHandlerProcInfo = 0x00FFFFC0 }; /* pascal no_return_value Func(4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes) */
|
|
#ifdef __cplusplus
|
|
inline DEFINE_API_C(DebugAssertOutputHandlerUPP) NewDebugAssertOutputHandlerUPP(DebugAssertOutputHandlerProcPtr userRoutine) { return (DebugAssertOutputHandlerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebugAssertOutputHandlerProcInfo, GetCurrentArchitecture()); }
|
|
#else
|
|
#define NewDebugAssertOutputHandlerUPP(userRoutine) (DebugAssertOutputHandlerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebugAssertOutputHandlerProcInfo, GetCurrentArchitecture())
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* DisposeDebugComponentCallbackUPP()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: available as macro/inline
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( void )
|
|
DisposeDebugComponentCallbackUPP(DebugComponentCallbackUPP userUPP);
|
|
#if !OPAQUE_UPP_TYPES
|
|
#ifdef __cplusplus
|
|
inline DEFINE_API_C(void) DisposeDebugComponentCallbackUPP(DebugComponentCallbackUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
|
|
#else
|
|
#define DisposeDebugComponentCallbackUPP(userUPP) DisposeRoutineDescriptor(userUPP)
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* DisposeDebugAssertOutputHandlerUPP()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: available as macro/inline
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( void )
|
|
DisposeDebugAssertOutputHandlerUPP(DebugAssertOutputHandlerUPP userUPP);
|
|
#if !OPAQUE_UPP_TYPES
|
|
#ifdef __cplusplus
|
|
inline DEFINE_API_C(void) DisposeDebugAssertOutputHandlerUPP(DebugAssertOutputHandlerUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
|
|
#else
|
|
#define DisposeDebugAssertOutputHandlerUPP(userUPP) DisposeRoutineDescriptor(userUPP)
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* InvokeDebugComponentCallbackUPP()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: available as macro/inline
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( void )
|
|
InvokeDebugComponentCallbackUPP(
|
|
SInt32 optionSelectorNum,
|
|
UInt32 command,
|
|
Boolean * optionSetting,
|
|
DebugComponentCallbackUPP userUPP);
|
|
#if !OPAQUE_UPP_TYPES
|
|
#ifdef __cplusplus
|
|
inline DEFINE_API_C(void) InvokeDebugComponentCallbackUPP(SInt32 optionSelectorNum, UInt32 command, Boolean * optionSetting, DebugComponentCallbackUPP userUPP) { CALL_THREE_PARAMETER_UPP(userUPP, uppDebugComponentCallbackProcInfo, optionSelectorNum, command, optionSetting); }
|
|
#else
|
|
#define InvokeDebugComponentCallbackUPP(optionSelectorNum, command, optionSetting, userUPP) CALL_THREE_PARAMETER_UPP((userUPP), uppDebugComponentCallbackProcInfo, (optionSelectorNum), (command), (optionSetting))
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* InvokeDebugAssertOutputHandlerUPP()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: available as macro/inline
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( void )
|
|
InvokeDebugAssertOutputHandlerUPP(
|
|
OSType componentSignature,
|
|
UInt32 options,
|
|
const char * assertionString,
|
|
const char * exceptionLabelString,
|
|
const char * errorString,
|
|
const char * fileName,
|
|
long lineNumber,
|
|
void * value,
|
|
ConstStr255Param outputMsg,
|
|
DebugAssertOutputHandlerUPP userUPP);
|
|
#if !OPAQUE_UPP_TYPES
|
|
#ifdef __cplusplus
|
|
inline DEFINE_API_C(void) InvokeDebugAssertOutputHandlerUPP(OSType componentSignature, UInt32 options, const char * assertionString, const char * exceptionLabelString, const char * errorString, const char * fileName, long lineNumber, void * value, ConstStr255Param outputMsg, DebugAssertOutputHandlerUPP userUPP) { CALL_NINE_PARAMETER_UPP(userUPP, uppDebugAssertOutputHandlerProcInfo, componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value, outputMsg); }
|
|
#else
|
|
#define InvokeDebugAssertOutputHandlerUPP(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value, outputMsg, userUPP) CALL_NINE_PARAMETER_UPP((userUPP), uppDebugAssertOutputHandlerProcInfo, (componentSignature), (options), (assertionString), (exceptionLabelString), (errorString), (fileName), (lineNumber), (value), (outputMsg))
|
|
#endif
|
|
#endif
|
|
|
|
#if CALL_NOT_IN_CARBON || OLDROUTINENAMES
|
|
/* support for pre-Carbon UPP routines: New...Proc and Call...Proc */
|
|
#define NewDebugComponentCallbackProc(userRoutine) NewDebugComponentCallbackUPP(userRoutine)
|
|
#define NewDebugAssertOutputHandlerProc(userRoutine) NewDebugAssertOutputHandlerUPP(userRoutine)
|
|
#define CallDebugComponentCallbackProc(userRoutine, optionSelectorNum, command, optionSetting) InvokeDebugComponentCallbackUPP(optionSelectorNum, command, optionSetting, userRoutine)
|
|
#define CallDebugAssertOutputHandlerProc(userRoutine, componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value, outputMsg) InvokeDebugAssertOutputHandlerUPP(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value, outputMsg, userRoutine)
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
|
|
#ifdef PRAGMA_IMPORT_OFF
|
|
#pragma import off
|
|
#elif PRAGMA_IMPORT
|
|
#pragma import reset
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __DEBUGGING__ */
|
|
|