This file is indexed.

/usr/include/GNUstep/Foundation/NSException.h is in libgnustep-base-dev 1.24.0-1ubuntu3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
/** Interface for NSException for GNUStep
   Copyright (C) 1995, 1996 Free Software Foundation, Inc.

   Written by:  Adam Fedor <fedor@boulder.colorado.edu>
   Date: 1995
   
   This file is part of the GNUstep Base Library.

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.
   
   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.
   
   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free
   Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02111 USA.

    <title>NSException and NSAssertionHandler class reference</title>

    AutogsdocSource: NSAssertionHandler.m
    AutogsdocSource: NSException.m

   */ 

#ifndef __NSException_h_GNUSTEP_BASE_INCLUDE
#define __NSException_h_GNUSTEP_BASE_INCLUDE
#import	<GNUstepBase/GSVersionMacros.h>
#import	<GNUstepBase/GSConfig.h>

#if     defined(_NATIVE_OBJC_EXCEPTIONS)
#define USER_NATIVE_OBJC_EXCEPTIONS       1
#else
#define USER_NATIVE_OBJC_EXCEPTIONS       0
#endif
#if     !BASE_NATIVE_OBJC_EXCEPTIONS && USER_NATIVE_OBJC_EXCEPTIONS
#error  The current setting for native-objc-exceptions does not match that of gnustep-base ... please correct this.
#endif

#import	<Foundation/NSString.h>
#include <setjmp.h>
#include <stdarg.h>

#if	defined(__cplusplus)
extern "C" {
#endif

@class NSDictionary;

/**
   <p>
   The <code>NSException</code> class helps manage errors in a program. It
   provides a mechanism for lower-level methods to provide information about
   problems to higher-level methods, which more often than not, have a
   better ability to decide what to do about the problems.
   </p>
   <p>
   Exceptions are typically handled by enclosing a sensitive section
   of code inside the macros <code>NS_DURING</code> and <code>NS_HANDLER</code>,
   and then handling any problems after this, up to the
   <code>NS_ENDHANDLER</code> macro:
   </p>
   <example>
   NS_DURING
    code that might cause an exception
   NS_HANDLER
    code that deals with the exception. If this code cannot deal with
    it, you can re-raise the exception like this
    [localException raise]
    so the next higher level of code can handle it
   NS_ENDHANDLER
   </example>
   <p>
   The local variable <code>localException</code> is the name of the exception
   object you can use in the <code>NS_HANDLER</code> section.
   The easiest way to cause an exception is using the +raise:format:,...
   method.
   </p>
   <p>
   If there is no NS_HANDLER ... NS_ENDHANDLER block enclosing (directly or
   indirectly) code where an exception is raised, then control passes to
   the <em>uncaught exception handler</em> function and the program is
   then terminated.<br />
   The uncaught exception handler is set using NSSetUncaughtExceptionHandler()
   and if not set, defaults to a function which will simply print an error
   message before the program terminates.
   </p>
*/
@interface NSException : NSObject <NSCoding, NSCopying>
{    
#if	GS_EXPOSE(NSException)
@private
  NSString *_e_name;
  NSString *_e_reason;
  void *_reserved;
#endif
}

/**
 * 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
 * <em>raised</em> 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 <em>raised</em>
 * using the -raise method.
 */
+ (void) raise: (NSString*)name
	format: (NSString*)format
     arguments: (va_list)argList;

#if OS_API_VERSION(100500,GS_API_LATEST) && GS_API_VERSION( 11501,GS_API_LATEST)
/** Returns an array of the call stack return addresses at the point when
 * the exception was raised.  Re-raising the exception does not change
 * this value.
 */
- (NSArray*) callStackReturnAddresses;
#endif

#if OS_API_VERSION(100600,GS_API_LATEST) && GS_API_VERSION( 11903,GS_API_LATEST)
/**
 * Returns an array of the symbolic names of the call stack return addresses.  
 * Note that, on some platforms, symbols are only exported in
 * position-independent code and so these may only return numeric addresses for
 * code in static libraries or the main application.  
 */
- (NSArray*) callStackSymbols;
#endif

/**
 * <init/>Initializes a newly allocated NSException object with a
 * name, reason and a dictionary userInfo.
 */
- (id) initWithName: (NSString*)name 
	     reason: (NSString*)reason 
	   userInfo: (NSDictionary*)userInfo;

/** Returns the name of the exception. */
- (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.<br />
 * 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.<br />
 * 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.<br />
 * 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.<br />
 */
- (NSDictionary*) userInfo;

@end

/** An exception when character set conversion fails.
 */
GS_EXPORT NSString* const NSCharacterConversionException;

/** Attempt to use an invalidated destination.
 */
GS_EXPORT NSString* const NSDestinationInvalidException;

/** A generic exception for general purpose usage.
 */
GS_EXPORT NSString* const NSGenericException;

/** An exception for cases where unexpected state is detected within an object.
 */
GS_EXPORT NSString* const NSInternalInconsistencyException;

/** An exception used when an invalid argument is passed to a method
 * or function.
 */
GS_EXPORT NSString* const NSInvalidArgumentException;

/** Attempt to use a receive port which has been invalidated.
 */
GS_EXPORT NSString * const NSInvalidReceivePortException;

/** Attempt to use a send port which has been invalidated.
 */
GS_EXPORT NSString * const NSInvalidSendPortException;

/** An exception used when the system fails to allocate required memory.
 */
GS_EXPORT NSString* const NSMallocException;

/**  An exception when a remote object is sent a message from a thread
 *  unable to access the object.
 */
GS_EXPORT NSString* const NSObjectInaccessibleException;

/**  Attempt to send to an object which is no longer available.
 */
GS_EXPORT NSString* const NSObjectNotAvailableException;

/**  UNused ... for MacOS-X compatibility.
 */
GS_EXPORT NSString* const NSOldStyleException;

#if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
/** An exception used when some form of parsing fails.
 */
GS_EXPORT NSString* const NSParseErrorException;
#endif

/** Some failure to receive on a port.
 */
GS_EXPORT NSString * const NSPortReceiveException;

/** Some failure to send on a port.
 */
GS_EXPORT NSString * const NSPortSendException;

/**
 *  Exception raised by [NSPort], [NSConnection], and friends if sufficient
 *  time elapses while waiting for a response, or if the receiving port is
 *  invalidated before a request can be received.  See
 *  [NSConnection-setReplyTimeout:].
 */
GS_EXPORT NSString * const NSPortTimeoutException; /* OPENSTEP */

/** An exception used when an illegal range is encountered ... usually this
 * is used to provide more information than an invalid argument exception.
 */
GS_EXPORT NSString* const NSRangeException;

/**
 * The actual structure for an NSHandler.  You shouldn't need to worry about it.
 */
typedef struct _NSHandler 
{
    jmp_buf jumpState;			/* place to longjmp to */
    struct _NSHandler *next;		/* ptr to next handler */
    __unsafe_unretained NSException *exception;
} NSHandler;

/**
 *  This is the type of the exception handler called when an exception is
 *  generated and not caught by the programmer.  See
 *  NSGetUncaughtExceptionHandler(), NSSetUncaughtExceptionHandler().
 */
typedef void NSUncaughtExceptionHandler(NSException *exception);

/**
 *  Returns the exception handler called when an exception is generated and
 *  not caught by the programmer (by enclosing in <code>NS_DURING</code> and
 *  <code>NS_HANDLER</code>...<code>NS_ENDHANDLER</code>).  The default prints
 *  an error message and exits the program.  You can change this behavior by
 *  calling NSSetUncaughtExceptionHandler().
 */
GS_EXPORT NSUncaughtExceptionHandler *
NSGetUncaughtExceptionHandler();

/**
 *  <p>Sets the exception handler called when an exception is generated and
 *  not caught by the programmer (by enclosing in <code>NS_DURING</code> and
 *  <code>NS_HANDLER</code>...<code>NS_ENDHANDLER</code>).  The default prints
 *  an error message and exits the program.  proc should take a single argument
 *  of type <code>NSException *</code>.
 *  </p>
 *  <p>NB. If the exception handler set by this function does not terminate
 *  the process, the process will be terminateed anyway.  This is a safety
 *  precaution to ensure that, in the event of an exception being raised
 *  and not handled, the program does not try to continue running in a
 *  confused state (possibly doing horrible things like billing customers
 *  who shouldn't be billed etc), but shuts down as cleanly as possible.
 *  </p>
 *  <p>Process termination is normally accomplished by calling the standard
 *  exit function of the C runtime library, but if the environment variable
 *  CRASH_ON_ABORT is set to YES or TRUE or 1 the termination will be
 *  accomplished by calling the abort function instead, which should cause
 *  a core dump to be made for debugging.
 *  </p>
 *  <p>The value of proc should be a pointer to a function taking an
 *  [NSException] instance as an argument.
 *  </p>
 */
GS_EXPORT void
NSSetUncaughtExceptionHandler(NSUncaughtExceptionHandler *handler);

/* NS_DURING, NS_HANDLER and NS_ENDHANDLER are always used like: 

	NS_DURING
	    some code which might raise an error
	NS_HANDLER
	    code that will be jumped to if an error occurs
	NS_ENDHANDLER

   If any error is raised within the first block of code, the second block
   of code will be jumped to.  Typically, this code will clean up any
   resources allocated in the routine, possibly case on the error code
   and perform special processing, and default to RERAISE the error to
   the next handler.  Within the scope of the handler, a local variable
   called "localException" holds information about the exception raised.

   It is illegal to exit the first block of code by any other means than
   NS_VALRETURN, NS_VOIDRETURN, or just falling out the bottom.
 */
#if     USER_NATIVE_OBJC_EXCEPTIONS

# define NS_DURING       @try {
# define NS_HANDLER      } @catch (NSException * localException) {
# define NS_ENDHANDLER   }

# define NS_VALRETURN(val)              return (val)
# define NS_VALUERETURN(object, id)     return (object)
# define NS_VOIDRETURN                  return

#elif   !USER_NATIVE_OBJC_EXCEPTIONS && !BASE_NATIVE_OBJC_EXCEPTIONS

/** Private support routine.  Do not call directly. */
GS_EXPORT void _NSAddHandler( NSHandler *handler );
/** Private support routine.  Do not call directly. */
GS_EXPORT void _NSRemoveHandler( NSHandler *handler );

#define NS_DURING { NSHandler NSLocalHandler;			\
		    _NSAddHandler(&NSLocalHandler);		\
		    if( !setjmp(NSLocalHandler.jumpState) ) {

#define NS_HANDLER _NSRemoveHandler(&NSLocalHandler); } else { \
		    NSException *localException;               \
		    localException = NSLocalHandler.exception; \
		    {

#define NS_ENDHANDLER }}}

#define NS_VALRETURN(val)  do { __typeof__(val) temp = (val);	\
			_NSRemoveHandler(&NSLocalHandler);	\
			return(temp); } while (0)

#define NS_VALUERETURN(object, id) do { id temp = object;	\
			_NSRemoveHandler(&NSLocalHandler);	\
			return(temp); } while (0) 

#define NS_VOIDRETURN	do { _NSRemoveHandler(&NSLocalHandler);	\
			return; } while (0)

#endif // _NATIVE_OBJC_EXCEPTIONS

/* ------------------------------------------------------------------------ */
/*   Assertion Handling */
/* ------------------------------------------------------------------------ */

@interface NSAssertionHandler : NSObject

+ (NSAssertionHandler*) currentHandler;

- (void) handleFailureInFunction: (NSString*)functionName 
			    file: (NSString*)fileName 
		      lineNumber: (NSInteger)line 
		     description: (NSString*)format,... GS_NORETURN_METHOD;

- (void) handleFailureInMethod: (SEL)aSelector 
			object: object 
			  file: (NSString*)fileName 
		    lineNumber: (NSInteger)line 
		   description: (NSString*)format,... GS_NORETURN_METHOD;

@end
extern NSString *const NSAssertionHandlerKey;

#ifdef	NS_BLOCK_ASSERTIONS
#define _NSAssertArgs(condition, desc, args...)		
#define _NSCAssertArgs(condition, desc, args...)	
#else
#define _NSAssertArgs(condition, desc, args...)			\
    do {							\
	if (!(condition)) {					\
	    [[NSAssertionHandler currentHandler] 		\
	    	handleFailureInMethod: _cmd 			\
		object: self 					\
		file: [NSString stringWithUTF8String: __FILE__] 	\
		lineNumber: __LINE__ 				\
		description: (desc) , ## args]; 			\
	}							\
    } while(0)

#define _NSCAssertArgs(condition, desc, args...)		\
    do {							\
	if (!(condition)) {					\
	    [[NSAssertionHandler currentHandler] 		\
	    handleFailureInFunction: [NSString stringWithUTF8String: __PRETTY_FUNCTION__] 				\
	    file: [NSString stringWithUTF8String: __FILE__] 		\
	    lineNumber: __LINE__ 				\
	    description: (desc) , ## args]; 			\
	}							\
    } while(0)
#endif

/** Used in an ObjC method body.<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc and arg1, arg2,
 * arg3, arg4, arg5 */
#define NSAssert5(condition, desc, arg1, arg2, arg3, arg4, arg5)	\
    _NSAssertArgs((condition), (desc), (arg1), (arg2), (arg3), (arg4), (arg5))

/** Used in an ObjC method body.<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc and arg1, arg2,
 * arg3, arg4 */
#define NSAssert4(condition, desc, arg1, arg2, arg3, arg4)	\
    _NSAssertArgs((condition), (desc), (arg1), (arg2), (arg3), (arg4))

/** Used in an ObjC method body.<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc and arg1, arg2,
 * arg3 */
#define NSAssert3(condition, desc, arg1, arg2, arg3)	\
    _NSAssertArgs((condition), (desc), (arg1), (arg2), (arg3))

/** Used in an ObjC method body.<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc and arg1, arg2 */
#define NSAssert2(condition, desc, arg1, arg2)		\
    _NSAssertArgs((condition), (desc), (arg1), (arg2))

/** Used in an ObjC method body.<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc  and arg1 */
#define NSAssert1(condition, desc, arg1)		\
    _NSAssertArgs((condition), (desc), (arg1))

/** Used in an ObjC method body.<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc */
#define NSAssert(condition, desc)			\
    _NSAssertArgs((condition), (desc))

/** Used in an ObjC method body.<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception saying that an invalid
 * parameter was supplied to the method. */
#define NSParameterAssert(condition)			\
    _NSAssertArgs((condition), @"Invalid parameter not satisfying: %s", #condition)

/** Used in plain C code (not in an ObjC method body).<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc and arg1, arg2,
 * arg3, arg4, arg5 */
#define NSCAssert5(condition, desc, arg1, arg2, arg3, arg4, arg5)	\
    _NSCAssertArgs((condition), (desc), (arg1), (arg2), (arg3), (arg4), (arg5))

/** Used in plain C code (not in an ObjC method body).<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc and arg1, arg2,
 * arg3, arg4 */
#define NSCAssert4(condition, desc, arg1, arg2, arg3, arg4)	\
    _NSCAssertArgs((condition), (desc), (arg1), (arg2), (arg3), (arg4))

/** Used in plain C code (not in an ObjC method body).<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc and arg1, arg2,
 * arg3 */
#define NSCAssert3(condition, desc, arg1, arg2, arg3)	\
    _NSCAssertArgs((condition), (desc), (arg1), (arg2), (arg3))

/** Used in plain C code (not in an ObjC method body).<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc and arg1, arg2
 */
#define NSCAssert2(condition, desc, arg1, arg2)		\
    _NSCAssertArgs((condition), (desc), (arg1), (arg2))

/** Used in plain C code (not in an ObjC method body).<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc and arg1
 */
#define NSCAssert1(condition, desc, arg1)		\
    _NSCAssertArgs((condition), (desc), (arg1))

/** Used in plain C code (not in an ObjC method body).<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception using desc
 */
#define NSCAssert(condition, desc)			\
    _NSCAssertArgs((condition), (desc))

/** Used in plain C code (not in an ObjC method body).<br />
 * See [NSAssertionHandler] for details.<br />
 * When condition is false, raise an exception saying that an invalid
 * parameter was supplied to the method. */
#define NSCParameterAssert(condition)			\
    _NSCAssertArgs((condition), @"Invalid parameter not satisfying: %s", #condition)

#if	defined(__cplusplus)
}
#endif

#endif /* __NSException_h_GNUSTEP_BASE_INCLUDE */