diff --git a/ChangeLog b/ChangeLog index 8f02d985e..7d5907afa 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2007-02-06 Richard Frith-Macdonald + + * Documentation/manual/manual.texi: fix format errors + * Source/NSException.m: control stack trace with environment variable + * Headers/Foundation/NSException.h: document stack trace + * Documentation/Base.gsdoc: document stack trace + 2007-02-05 Richard Frith-Macdonald * configure.ac: minor tweak to avoid possible inconsistency in diff --git a/Documentation/Base.gsdoc b/Documentation/Base.gsdoc index cbc1d4064..69c5ddc1e 100644 --- a/Documentation/Base.gsdoc +++ b/Documentation/Base.gsdoc @@ -269,6 +269,16 @@ notice and this notice are preserved. core dump on systems where that is possible.

+ GNUSTEP_STACK_TRACE + +

+ When this is set to YES a stack trace is placed in + the user information dictionary of the NSException object + created when an exception is raised. The trace is keyed + on GSStackTraceKey and provides additional + information to let you know where the exception occurred. +

+ GNUSTEP_STRING_ENCODING

diff --git a/Documentation/manual/manual.texi b/Documentation/manual/manual.texi index 9a2f6f9ef..9188aeff0 100644 --- a/Documentation/manual/manual.texi +++ b/Documentation/manual/manual.texi @@ -95,16 +95,16 @@ into another language, under the above conditions for modified versions. @page @c Chapter 1, Introduction -@include Introduction.texi +@include Introduction.texi @c Chapter 2, The Objective-C Language -@include ObjcLanguage.texi +@include ObjcLanguage.texi @c Chapter 3, Working with Objects -@include WorkingWithObjects.texi +@include WorkingWithObjects.texi @c Chapter 4, Writing New Classes -@include WritingNewClasses.texi +@include WritingNewClasses.texi @c Chapter 5, Advanced Messaging @include AdvancedMessaging.texi diff --git a/Headers/Foundation/NSException.h b/Headers/Foundation/NSException.h index 63d9f597f..f9e126477 100644 --- a/Headers/Foundation/NSException.h +++ b/Headers/Foundation/NSException.h @@ -89,37 +89,37 @@ extern "C" { } /** - Create an an exception object with a name, reason and a dictionary - userInfo which can be used to provide additional information or - access to objects needed to handle the exception. After the - exception is created you must -raise it. -*/ + * Create an an exception object with a name, reason and a dictionary + * userInfo which can be used to provide additional information or + * access to objects needed to handle the exception. After the + * exception is created you must -raise it. + */ + (NSException*) exceptionWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo; /** - Creates an exception with a name and a reason using the - format string and any additional arguments. The exception is then - raised using the -raise method. + * Creates an exception with a name and a reason using the + * format string and any additional arguments. The exception is then + * raised using the -raise method. */ + (void) raise: (NSString*)name format: (NSString*)format,...; /** - Creates an exception with a name and a reason string using the - format string and additional arguments specified as a variable - argument list argList. The exception is then raised - using the -raise method. + * Creates an exception with a name and a reason string using the + * format string and additional arguments specified as a variable + * argument list argList. The exception is then raised + * using the -raise method. */ + (void) raise: (NSString*)name format: (NSString*)format arguments: (va_list)argList; /** - Initializes a newly allocated NSException object with a - name, reason and a dictionary userInfo. -*/ + * Initializes a newly allocated NSException object with a + * name, reason and a dictionary userInfo. + */ - (id) initWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo; @@ -128,25 +128,31 @@ extern "C" { - (NSString*) name; /** - Raises the exception. All code following the raise will not be - executed and program control will be transfered to the closest - calling method which encapsulates the exception code in an - NS_DURING macro.
- If the exception was not caught in a macro, the currently set - uncaught exception handler is called to perform final logging - and the program is then terminated.
- If the uncaught exception handler fails to terminate the program, - then the default behavior is to terminate the program as soon as - the uncaught exception handler function returns.
- NB. all other exception raising methods call this one, so if you - want to set a breakpoint when debugging, set it in this method. -*/ + * Raises the exception. All code following the raise will not be + * executed and program control will be transfered to the closest + * calling method which encapsulates the exception code in an + * NS_DURING macro.
+ * If the exception was not caught in a macro, the currently set + * uncaught exception handler is called to perform final logging + * and the program is then terminated.
+ * If the uncaught exception handler fails to terminate the program, + * then the default behavior is to terminate the program as soon as + * the uncaught exception handler function returns.
+ * NB. all other exception raising methods call this one, so if you + * want to set a breakpoint when debugging, set it in this method. + */ - (void) raise; /** Returns the exception reason. */ - (NSString*) reason; -/** Returns the exception userInfo dictionary. */ +/** Returns the exception userInfo dictionary.
+ * There is a GNUstep extension, enabled when the GNUSTEP_STACK_TRACE + * environment variable is set to YES, which causes a stack trace to + * be placed in this dictionary (keyed on GSStackTraceKey) at the point + * when the exception is raised. This can be useful for determining + * where an exception ocurred. + */ - (NSDictionary*) userInfo; @end diff --git a/Source/NSException.m b/Source/NSException.m index aed91a8f7..fdd4b3eeb 100644 --- a/Source/NSException.m +++ b/Source/NSException.m @@ -681,7 +681,8 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) #endif #if defined(DEBUG) - if ([_e_info objectForKey: @"GSStackTraceKey"] == nil) + if (GSPrivateEnvironmentFlag("GNUSTEP_STACK_TRACE", NO) == YES + && [_e_info objectForKey: @"GSStackTraceKey"] == nil) { NSMutableDictionary *m;