]> git.saurik.com Git - apple/mdnsresponder.git/blob - mDNSWindows/DebugServices.h
projects / apple / mdnsresponder.git / blob
? search:


fd914eecc51ee3eeef8ff0c4d1c87ca93c2bce7b
[apple/mdnsresponder.git] / mDNSWindows / DebugServices.h
1 /*
2 * Copyright (c) 1997-2004 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.
7 *
8 * This file contains Original Code and/or Modifications of Original Code
9 * as defined in and that are subject to the Apple Public Source License
10 * Version 2.0 (the 'License'). You may not use this file except in
11 * compliance with the License. Please obtain a copy of the License at
12 * http://www.opensource.apple.com/apsl/ and read it before using this
13 * file.
14 *
15 * The Original Code and all software distributed under the License are
16 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
17 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
18 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
20 * Please see the License for the specific language governing rights and
21 * limitations under the License.
22 *
23 * @APPLE_LICENSE_HEADER_END@
24
25 Change History (most recent first):
26
27 $Log: DebugServices.h,v $
28 Revision 1.4 2004/04/15 08:59:08 bradley
29 Removed deprecated debug and log levels and replaced them with modern equivalents.
30
31 Revision 1.3 2004/04/08 09:29:55 bradley
32 Manually do host->network byte order conversion to avoid needing libraries for htons/htonl. Changed
33 hex dumps to better separate hex and ASCII. Added support for %.8a syntax in DebugSNPrintF for Fibre
34 Channel addresses (00:11:22:33:44:55:66:77). Fixed a few places where HeaderDoc was incorrect.
35
36 Revision 1.2 2004/03/07 05:59:34 bradley
37 Sync'd with internal version: Added expect macros, error codes, and CoreServices exclusion.
38
39 Revision 1.1 2004/01/30 02:27:30 bradley
40 Debugging support for various platforms.
41
42 */
43
44 //---------------------------------------------------------------------------------------------------------------------------
45 /*! @header DebugServices
46
47 Debugging Library
48 */
49
50 #ifndef __DEBUG_SERVICES__
51 #define __DEBUG_SERVICES__
52
53 #include <stdarg.h>
54
55 #include "CommonServices.h"
56
57 #if( TARGET_OS_VXWORKS )
58 #include "logLib.h"
59 #endif
60
61 #if 0
62 #pragma mark == Settings ==
63 #endif
64
65 //===========================================================================================================================
66 // Settings
67 //===========================================================================================================================
68
69 // General
70
71 #if( !defined( DEBUG ) )
72 #define DEBUG 0
73 #endif
74
75 #if( defined( NDEBUG ) && DEBUG )
76 #error NDEBUG defined and DEBUG is also enabled...they need to be in-sync
77 #endif
78
79 // AssertMacros.h/Debugging.h overrides.
80
81 #if( !defined( DEBUG_OVERRIDE_APPLE_MACROS ) )
82 #define DEBUG_OVERRIDE_APPLE_MACROS 1
83 #endif
84
85 // Routine name. Uses ISO __func__ where possible. Otherwise, uses the best thing that is available (if anything).
86
87 #if( defined( __MWERKS__ ) || ( __GNUC__ > 2 ) || ( ( __GNUC__ == 2 ) && ( __GNUC_MINOR__ >= 9 ) ) )
88 #define __ROUTINE__ __func__
89 #elif( defined( __GNUC__ ) )
90 #define __ROUTINE__ __PRETTY_FUNCTION__
91 #elif( defined( _MSC_VER ) && !defined( _WIN32_WCE ) )
92 #define __ROUTINE__ __FUNCTION__
93 #else
94 #define __ROUTINE__ ""
95 #endif
96
97 // Variable argument macro support. Use ANSI C99 __VA_ARGS__ where possible. Otherwise, use the next best thing.
98
99 #if( defined( __GNUC__ ) )
100 #if( ( __GNUC__ > 3 ) || ( ( __GNUC__ == 3 ) && ( __GNUC_MINOR__ >= 3) ) )
101 #define DEBUG_C99_VA_ARGS 1
102 #define DEBUG_GNU_VA_ARGS 0
103 #else
104 #define DEBUG_C99_VA_ARGS 0
105 #define DEBUG_GNU_VA_ARGS 1
106 #endif
107 #elif( defined( __MWERKS__ ) )
108 #define DEBUG_C99_VA_ARGS 1
109 #define DEBUG_GNU_VA_ARGS 0
110 #else
111 #define DEBUG_C99_VA_ARGS 0
112 #define DEBUG_GNU_VA_ARGS 0
113 #endif
114
115 #if 0
116 #pragma mark == Output ==
117 #endif
118
119 //---------------------------------------------------------------------------------------------------------------------------
120 /*! @defined DEBUG_FPRINTF_ENABLED
121
122 @abstract Enables ANSI C fprintf output.
123 */
124
125 #if( !defined( DEBUG_FPRINTF_ENABLED ) )
126 #if( !TARGET_API_MAC_OSX_KERNEL && !TARGET_OS_WINDOWS_CE )
127 #define DEBUG_FPRINTF_ENABLED 1
128 #else
129 #define DEBUG_FPRINTF_ENABLED 0
130 #endif
131 #else
132 #if( TARGET_API_MAC_OSX_KERNEL || TARGET_OS_WINDOWS_CE )
133 #error fprintf enabled, but not supported on Mac OS X kernel or Windows CE
134 #endif
135 #endif
136
137 //---------------------------------------------------------------------------------------------------------------------------
138 /*! @defined DEBUG_MAC_OS_X_IOLOG_ENABLED
139
140 @abstract Enables IOLog (Mac OS X Kernel) output.
141 */
142
143 #if( !defined( DEBUG_MAC_OS_X_IOLOG_ENABLED ) )
144 #define DEBUG_MAC_OS_X_IOLOG_ENABLED TARGET_API_MAC_OSX_KERNEL
145 #endif
146
147 //---------------------------------------------------------------------------------------------------------------------------
148 /*! @defined DEBUG_KPRINTF_ENABLED
149
150 @abstract Enables kprintf (Mac OS X Kernel) output.
151 */
152
153 #if( !defined( DEBUG_KPRINTF_ENABLED ) )
154 #define DEBUG_KPRINTF_ENABLED TARGET_API_MAC_OSX_KERNEL
155 #endif
156
157 //---------------------------------------------------------------------------------------------------------------------------
158 /*! @defined DEBUG_IDEBUG_ENABLED
159
160 @abstract Enables iDebug (Mac OS X user and Kernel) output.
161
162 @discussion
163
164 For Mac OS X kernel development, iDebug is enabled by default because we can dynamically check for the presence
165 of iDebug via some exported IOKit symbols. Mac OS X app usage doesn't allow dynamic detection because it relies
166 on statically linking to the iDebugServices.cp file so for Mac OS X app usage, you have to manually enable iDebug.
167 */
168
169 #if( !defined( DEBUG_IDEBUG_ENABLED ) )
170 #define DEBUG_IDEBUG_ENABLED TARGET_API_MAC_OSX_KERNEL
171 #endif
172
173 //---------------------------------------------------------------------------------------------------------------------------
174 /*! @defined DEBUG_CORE_SERVICE_ASSERTS_ENABLED
175
176 @abstract Controls whether Core Services assert handling is enabled. Enabling requires CoreServices framework.
177 */
178
179 #if( !defined( DEBUG_CORE_SERVICE_ASSERTS_ENABLED ) )
180 #if( defined( __DEBUGGING__ ) )
181 #define DEBUG_CORE_SERVICE_ASSERTS_ENABLED 1
182 #else
183 #define DEBUG_CORE_SERVICE_ASSERTS_ENABLED 0
184 #endif
185 #endif
186
187 //---------------------------------------------------------------------------------------------------------------------------
188 /*! @typedef DebugOutputType
189
190 @abstract Type of debug output (i.e. where the output goes).
191 */
192
193 typedef uint32_t DebugOutputType;
194
195 #define kDebugOutputTypeNone 0x6E6F6E65U // 'none' - no params
196 #define kDebugOutputTypeCustom 0x63757374U // 'cust' - 1st param = function ptr, 2nd param = context
197 #define kDebugOutputTypeFPrintF 0x66707269U // 'fpri' - 1st param = DebugOutputTypeFlags [, 2nd param = filename]
198 #define kDebugOutputTypeiDebug 0x69646267U // 'idbg' - no params
199 #define kDebugOutputTypeKPrintF 0x6B707266U // 'kprf' - no params
200 #define kDebugOutputTypeMacOSXIOLog 0x696C6F67U // 'ilog' - no params
201 #define kDebugOutputTypeMacOSXLog 0x786C6F67U // 'xlog' - no params
202 #define kDebugOutputTypeWindowsDebugger 0x77696E64U // 'wind' - no params
203 #define kDebugOutputTypeWindowsEventLog 0x7765766CU // 'wevl' - 1st param = C-string name, 2nd param = HMODULE or NULL.
204
205 // Console meta output kind - Any kind of Console output (in horizontal order of preference):
206 //
207 // Mac OS X = ANSI printf (viewable in Console.app)
208 // Mac OS X Kernel = IOLog (/var/log/system.log) or kprintf (serial).
209 // Windows = ANSI printf (Console window) or OutputDebugString (debugger).
210 // Other = ANSI printf (viewer varies).
211
212 #define kDebugOutputTypeMetaConsole 0x434F4E53U // 'CONS' - no params
213
214 //---------------------------------------------------------------------------------------------------------------------------
215 /*! @typedef DebugOutputTypeFlags
216
217 @abstract Flags controlling how the output type is configured.
218
219 @constant kDebugOutputTypeFlagsTypeMask Bit mask for the output type (e.g. stdout, stderr, file, etc.).
220 @constant kDebugOutputTypeFlagsStdOut fprintf should go to stdout.
221 @constant kDebugOutputTypeFlagsStdErr fprintf should go to stderr.
222 @constant kDebugOutputTypeFlagsFile fprintf should go to a specific file (filename passed as va_arg).
223 */
224
225 typedef unsigned int DebugOutputTypeFlags;
226
227 #define kDebugOutputTypeFlagsTypeMask 0xF
228 #define kDebugOutputTypeFlagsStdOut 1
229 #define kDebugOutputTypeFlagsStdErr 2
230 #define kDebugOutputTypeFlagsFile 10
231
232 //---------------------------------------------------------------------------------------------------------------------------
233 /*! @typedef DebugOutputFunctionPtr
234
235 @abstract Function ptr for a custom callback to print debug output.
236 */
237
238 typedef void ( *DebugOutputFunctionPtr )( char *inData, size_t inSize, void *inContext );
239
240 //===========================================================================================================================
241 // Constants
242 //===========================================================================================================================
243
244 #if 0
245 #pragma mark == Flags ==
246 #endif
247
248 //---------------------------------------------------------------------------------------------------------------------------
249 /*! @typedef DebugFlags
250
251 @abstract Flags controlling how output is printed.
252 */
253
254 typedef uint32_t DebugFlags;
255
256 #define kDebugFlagsNone 0
257 #define kDebugFlagsNoAddress ( 1 << 0 )
258 #define kDebugFlagsNoOffset ( 1 << 1 )
259 #define kDebugFlags32BitOffset ( 1 << 2 )
260 #define kDebugFlagsNoASCII ( 1 << 3 )
261 #define kDebugFlagsNoNewLine ( 1 << 4 )
262 #define kDebugFlags8BitSeparator ( 1 << 5 )
263 #define kDebugFlags16BitSeparator ( 1 << 6 )
264 #define kDebugFlagsNo32BitSeparator ( 1 << 7 )
265 #define kDebugFlagsNo16ByteHexPad ( 1 << 8 )
266 #define kDebugFlagsNoByteCount ( 1 << 9 )
267
268 //---------------------------------------------------------------------------------------------------------------------------
269 /*! @enum DebugTaskLevelFlags
270
271 @abstract Flags indicating the task level.
272 */
273
274 enum
275 {
276 kDebugInterruptLevelShift = 0,
277 kDebugInterruptLevelMask = 0x00000007,
278 kDebugInVBLTaskMask = 0x00000010,
279 kDebugInDeferredTaskMask = 0x00000020,
280 kDebugInSecondaryInterruptHandlerMask = 0x00000040,
281 kDebugPageFaultFatalMask = 0x00000100, // There should be a "kPageFaultFatalMask" in Debugging.h.
282 kDebugMPTaskLevelMask = 0x00000200, // There should be a "kMPTaskLevelMask" in Debugging.h.
283 kDebugInterruptDepthShift = 16,
284 kDebugInterruptDepthMask = 0x00FF0000
285 };
286
287 #define DebugExtractTaskLevelInterruptLevel( LEVEL ) \
288 ( ( ( LEVEL ) & kDebugInterruptLevelMask ) >> kDebugInterruptLevelShift )
289
290 #define DebugExtractTaskLevelInterruptDepth( LEVEL ) \
291 ( ( ( LEVEL ) & kDebugInterruptDepthMask ) >> kDebugInterruptDepthShift )
292
293 #if 0
294 #pragma mark == Levels ==
295 #endif
296
297 //===========================================================================================================================
298 // Constants & Types - Levels
299 //===========================================================================================================================
300
301 //---------------------------------------------------------------------------------------------------------------------------
302 /*! @typedef DebugLevel
303
304 @abstract Level used to control debug logging.
305 */
306
307 typedef int32_t DebugLevel;
308
309 // Levels
310
311 #define kDebugLevelMask 0x0000FFFF
312 #define kDebugLevelChatty 100
313 #define kDebugLevelVerbose 500
314 #define kDebugLevelTrace 800
315 #define kDebugLevelInfo 1000
316 #define kDebugLevelNotice 3000
317 #define kDebugLevelWarning 5000
318 #define kDebugLevelAssert 6000
319 #define kDebugLevelRequire 7000
320 #define kDebugLevelError 8000
321 #define kDebugLevelCritical 9000
322 #define kDebugLevelAlert 10000
323 #define kDebugLevelEmergency 11000
324 #define kDebugLevelTragic 12000
325 #define kDebugLevelMax 0x0000FFFF
326
327 // Level Flags
328
329 #define kDebugLevelFlagMask 0xFFFF0000
330 #define kDebugLevelFlagStackTrace 0x00010000
331 #define kDebugLevelFlagDebugBreak 0x00020000
332
333 //---------------------------------------------------------------------------------------------------------------------------
334 /*! @typedef LogLevel
335
336 @abstract Level used to control which events are logged.
337 */
338
339 typedef int32_t LogLevel;
340
341 #define kLogLevelUninitialized -1L
342 #define kLogLevelAll 0L
343 #define kLogLevelChatty 100L
344 #define kLogLevelVerbose 500L
345 #define kLogLevelTrace 800L
346 #define kLogLevelInfo 1000L
347 #define kLogLevelNotice 3000L
348 #define kLogLevelWarning 4000L
349 #define kLogLevelAssert 6000L
350 #define kLogLevelRequire 7000L
351 #define kLogLevelError 8000L
352 #define kLogLevelCritical 9000L
353 #define kLogLevelAlert 10000L
354 #define kLogLevelEmergency 11000L
355 #define kLogLevelTragic 12000L
356 #define kLogLevelOff 0x0000FFFEL
357
358 #if 0
359 #pragma mark == Properties ==
360 #endif
361
362 //---------------------------------------------------------------------------------------------------------------------------
363 /*! @typedef DebugPropertyTag
364
365 @abstract Tag for properties.
366 */
367
368 typedef uint32_t DebugPropertyTag;
369
370 #define kDebugPropertyTagPrintLevelMin 0x6D696E70U // 'minp' Get: 1st param = DebugLevel *
371 // Set: 1st param = DebugLevel
372
373 #define kDebugPropertyTagPrintLevel kDebugPropertyTagPrintLevelMin
374
375 #define kDebugPropertyTagPrintLevelMax 0x706D786CU // 'maxp' Get: 1st param = DebugLevel *
376 // Set: 1st param = DebugLevel
377
378 #define kDebugPropertyTagBreakLevel 0x62726B6CU // 'brkl' Get: 1st param = DebugLevel *
379 // Set: 1st param = DebugLevel
380 #if 0
381 #pragma mark == General macros ==
382 #endif
383
384 //---------------------------------------------------------------------------------------------------------------------------
385 /*! @defined DEBUG_UNUSED
386
387 @abstract Macro to mark a paramter as unused to avoid unused parameter warnings.
388
389 @discussion
390
391 There is no universally supported pragma/attribute for indicating a variable is unused. DEBUG_UNUSED lets us
392 indicate a variable is unused in a manner that is supported by most compilers.
393 */
394
395 #define DEBUG_UNUSED( X ) (void)( X )
396
397 //---------------------------------------------------------------------------------------------------------------------------
398 /*! @defined DEBUG_USE_ONLY
399
400 @abstract Macro to mark a variable as used only when debugging is enabled.
401
402 @discussion
403
404 Variables are sometimes needed only for debugging. When debugging is turned off, these debug-only variables generate
405 compiler warnings about unused variables. To eliminate these warnings, use these macros to indicate variables that
406 are only used for debugging.
407 */
408
409 #if( DEBUG )
410 #define DEBUG_USE_ONLY( X )
411 #else
412 #define DEBUG_USE_ONLY( X ) (void)( X )
413 #endif
414
415 //---------------------------------------------------------------------------------------------------------------------------
416 /*! @defined DEBUG_LOCAL
417
418 @abstract Macros to make variables and functions static when debugging is off, but extern when debugging is on.
419
420 @discussion
421
422 Rather than using "static" directly, using this macros allows you to access these variables external while
423 debugging without being penalized for production builds.
424 */
425
426 #if( DEBUG )
427 #define DEBUG_LOCAL
428 #else
429 #define DEBUG_LOCAL static
430 #endif
431
432 //---------------------------------------------------------------------------------------------------------------------------
433 /*! @defined DEBUG_STATIC
434
435 @abstract Macros to make variables and functions static when debugging is off, but extern when debugging is on.
436
437 @discussion
438
439 Rather than using "static" directly, using this macros allows you to access these variables external while
440 debugging without being penalized for production builds.
441 */
442
443 #if( DEBUG )
444 #define DEBUG_STATIC
445 #else
446 #define DEBUG_STATIC static
447 #endif
448
449 //---------------------------------------------------------------------------------------------------------------------------
450 /*! @defined DEBUG_EXPORT
451
452 @abstract Macros to export variables.
453
454 @discussion
455
456 "__private_extern__" is a hack for IOKit to allow symbols to be exported from compilation units, but
457 // not exported outside a driver (IOKit uses a lame global namespace for symbols). This still does not
458 // solve the problem of multiple drivers in the same dependency chain since they share symbols.
459 */
460
461 #if( TARGET_API_MAC_OSX_KERNEL )
462 #define DEBUG_EXPORT __private_extern__
463 #else
464 #define DEBUG_EXPORT extern
465 #endif
466
467 //---------------------------------------------------------------------------------------------------------------------------
468 /*! @defined debug_add
469
470 @abstract Macro to add (or subtract if negative) a value when debugging is on. Does nothing if debugging is off.
471 */
472
473 #if( DEBUG )
474 #define debug_add( A, B ) ( A ) += ( B )
475 #else
476 #define debug_add( A, B )
477 #endif
478
479 //---------------------------------------------------------------------------------------------------------------------------
480 /*! @defined debug_perform
481
482 @abstract Macro to perform something in debug-only builds.
483 */
484
485 #if( DEBUG )
486 #define debug_perform( X ) do { X; } while( 0 )
487 #else
488 #define debug_perform( X )
489 #endif
490
491 //---------------------------------------------------------------------------------------------------------------------------
492 /*! @function translate_errno
493
494 @abstract Returns 0 if the test success. If the test fails, returns errno if non-zero and othewise the alternate error.
495 */
496
497 #define translate_errno( TEST, ERRNO, ALTERNATE_ERROR ) ( ( TEST ) ? 0 : ( ERRNO ) ? ( ERRNO ) : ( ALTERNATE_ERROR ) )
498
499 #if 0
500 #pragma mark == Compile Time macros ==
501 #endif
502
503 //---------------------------------------------------------------------------------------------------------------------------
504 /*! @defined check_compile_time
505
506 @abstract Performs a compile-time check of something such as the size of an int.
507
508 @discussion
509
510 This declares an array with a size that is determined by a compile-time expression. If the expression evaluates
511 to 0, the array has a size of -1, which is illegal and generates a compile-time error.
512
513 For example:
514
515 check_compile_time( sizeof( int ) == 4 );
516
517 Note: This only works with compile-time expressions.
518 Note: This only works in places where extern declarations are allowed (e.g. global scope).
519
520 References:
521
522 <http://www.jaggersoft.com/pubs/CVu11_3.html>
523 <http://www.jaggersoft.com/pubs/CVu11_5.html>
524
525 Note: The following macros differ from the macros on the www.jaggersoft.com web site because those versions do not
526 work with GCC due to GCC allow a zero-length array. Using a -1 condition turned out to be more portable.
527 */
528
529 #define check_compile_time( X ) extern int debug_compile_time_name[ ( X ) ? 1 : -1 ]
530
531 //---------------------------------------------------------------------------------------------------------------------------
532 /*! @defined check_compile_time_code
533
534 @abstract Perform a compile-time check, suitable for placement in code, of something such as the size of an int.
535
536 @discussion
537
538 This creates a switch statement with an existing case for 0 and an additional case using the result of a
539 compile-time expression. A switch statement cannot have two case labels with the same constant so if the
540 compile-time expression evaluates to 0, it is illegal and generates a compile-time error. If the compile-time
541 expression does not evaluate to 0, the resulting value is used as the case label and it compiles without error.
542
543 For example:
544
545 check_compile_time_code( sizeof( int ) == 4 );
546
547 Note: This only works with compile-time expressions.
548 Note: This does not work in a global scope so it must be inside a function.
549
550 References:
551
552 <http://www.jaggersoft.com/pubs/CVu11_3.html>
553 <http://www.jaggersoft.com/pubs/CVu11_5.html>
554 */
555
556 #define check_compile_time_code( X ) switch( 0 ) { case 0: case X:; }
557
558 #if 0
559 #pragma mark == check macros ==
560 #endif
561
562 //---------------------------------------------------------------------------------------------------------------------------
563 /*! @defined check
564
565 @abstract Check that an expression is true (non-zero).
566
567 @discussion
568
569 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
570 function name, etc.) using the default debugging output method.
571
572 Code inside check() statements is not compiled into production builds.
573 */
574
575 #if( DEBUG_OVERRIDE_APPLE_MACROS )
576 #undef check
577 #endif
578 #if( !defined( check ) )
579 #if( DEBUG )
580 #define check( X ) \
581 do \
582 { \
583 if( !( X ) ) \
584 { \
585 debug_print_assert( 0, #X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
586 } \
587 } while( 0 )
588 #else
589 #define check( X )
590 #endif
591 #endif
592
593 //---------------------------------------------------------------------------------------------------------------------------
594 /*! @defined check_string
595
596 @abstract Check that an expression is true (non-zero) with an explanation.
597
598 @discussion
599
600 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
601 function name, etc.) and a custom explanation string using the default debugging output method.
602
603 Code inside check_string() statements is not compiled into production builds.
604 */
605
606 #if( DEBUG_OVERRIDE_APPLE_MACROS )
607 #undef check_string
608 #endif
609 #if( !defined( check_string ) )
610 #if( DEBUG )
611 #define check_string( X, STR ) \
612 do \
613 { \
614 if( !( X ) ) \
615 { \
616 debug_print_assert( 0, #X, STR, __FILE__, __LINE__, __ROUTINE__ ); \
617 } \
618 \
619 } while( 0 )
620 #else
621 #define check_string( X, STR )
622 #endif
623 #endif
624
625 //---------------------------------------------------------------------------------------------------------------------------
626 /*! @defined check_noerr
627
628 @abstract Check that an error code is noErr (0).
629
630 @discussion
631
632 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
633 function name, etc.) using the default debugging output method.
634
635 Code inside check_noerr() statements is not compiled into production builds.
636 */
637
638 #if( DEBUG_OVERRIDE_APPLE_MACROS )
639 #undef check_noerr
640 #endif
641 #if( !defined( check_noerr ) )
642 #if( DEBUG )
643 #define check_noerr( ERR ) \
644 do \
645 { \
646 int_least32_t localErr; \
647 \
648 localErr = (int_least32_t)( ERR ); \
649 if( localErr != 0 ) \
650 { \
651 debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
652 } \
653 \
654 } while( 0 )
655 #else
656 #define check_noerr( ERR )
657 #endif
658 #endif
659
660 //---------------------------------------------------------------------------------------------------------------------------
661 /*! @defined check_noerr_string
662
663 @abstract Check that an error code is noErr (0) with an explanation.
664
665 @discussion
666
667 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
668 function name, etc.) and a custom explanation string using the default debugging output method.
669
670 Code inside check_noerr_string() statements is not compiled into production builds.
671 */
672
673 #if( DEBUG_OVERRIDE_APPLE_MACROS )
674 #undef check_noerr_string
675 #endif
676 #if( !defined( check_noerr_string ) )
677 #if( DEBUG )
678 #define check_noerr_string( ERR, STR ) \
679 do \
680 { \
681 int_least32_t localErr; \
682 \
683 localErr = (int_least32_t)( ERR ); \
684 if( localErr != 0 ) \
685 { \
686 debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \
687 } \
688 \
689 } while( 0 )
690 #else
691 #define check_noerr_string( ERR, STR )
692 #endif
693 #endif
694
695 //---------------------------------------------------------------------------------------------------------------------------
696 /*! @defined check_translated_errno
697
698 @abstract Check a condition and prints errno (if non-zero) to the log.
699
700 @discussion
701
702 Code inside check_translated_errno() statements is not compiled into production builds.
703 */
704
705 #if( !defined( check_translated_errno ) )
706 #if( DEBUG )
707 #define check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR ) \
708 do \
709 { \
710 if( !( TEST ) ) \
711 { \
712 int_least32_t localErr; \
713 \
714 localErr = (int_least32_t)( ERRNO ); \
715 localErr = ( localErr != 0 ) ? localErr : (int_least32_t)( ALTERNATE_ERROR ); \
716 debug_print_assert( localErr, #TEST, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
717 } \
718 \
719 } while( 0 )
720 #else
721 #define check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR )
722 #endif
723 #endif
724
725 //---------------------------------------------------------------------------------------------------------------------------
726 /*! @defined check_ptr_overlap
727
728 @abstract Checks that two ptrs do not overlap.
729 */
730
731 #define check_ptr_overlap( P1, P1_SIZE, P2, P2_SIZE ) \
732 do \
733 { \
734 check( !( ( (uintptr_t)( P1 ) >= (uintptr_t)( P2 ) ) && \
735 ( (uintptr_t)( P1 ) < ( ( (uintptr_t)( P2 ) ) + ( P2_SIZE ) ) ) ) ); \
736 check( !( ( (uintptr_t)( P2 ) >= (uintptr_t)( P1 ) ) && \
737 ( (uintptr_t)( P2 ) < ( ( (uintptr_t)( P1 ) ) + ( P1_SIZE ) ) ) ) ); \
738 \
739 } while( 0 )
740
741 #if 0
742 #pragma mark == require macros ==
743 #endif
744
745 //---------------------------------------------------------------------------------------------------------------------------
746 /*! @defined require
747
748 @abstract Requires that an expression evaluate to true.
749
750 @discussion
751
752 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
753 function name, etc.) using the default debugging output method then jumps to a label.
754 */
755
756 #if( DEBUG_OVERRIDE_APPLE_MACROS )
757 #undef require
758 #endif
759 #if( !defined( require ) )
760 #define require( X, LABEL ) \
761 do \
762 { \
763 if( !( X ) ) \
764 { \
765 debug_print_assert( 0, #X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
766 goto LABEL; \
767 } \
768 \
769 } while( 0 )
770 #endif
771
772 //---------------------------------------------------------------------------------------------------------------------------
773 /*! @defined require_string
774
775 @abstract Requires that an expression evaluate to true with an explanation.
776
777 @discussion
778
779 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
780 function name, etc.) and a custom explanation string using the default debugging output method then jumps to a label.
781 */
782
783 #if( DEBUG_OVERRIDE_APPLE_MACROS )
784 #undef require_string
785 #endif
786 #if( !defined( require_string ) )
787 #define require_string( X, LABEL, STR ) \
788 do \
789 { \
790 if( !( X ) ) \
791 { \
792 debug_print_assert( 0, #X, STR, __FILE__, __LINE__, __ROUTINE__ ); \
793 goto LABEL; \
794 } \
795 \
796 } while( 0 )
797 #endif
798
799 //---------------------------------------------------------------------------------------------------------------------------
800 /*! @defined require_quiet
801
802 @abstract Requires that an expression evaluate to true.
803
804 @discussion
805
806 If expression evalulates to false, this jumps to a label. No debugging information is printed.
807 */
808
809 #if( DEBUG_OVERRIDE_APPLE_MACROS )
810 #undef require_quiet
811 #endif
812 #if( !defined( require_quiet ) )
813 #define require_quiet( X, LABEL ) \
814 do \
815 { \
816 if( !( X ) ) \
817 { \
818 goto LABEL; \
819 } \
820 \
821 } while( 0 )
822 #endif
823
824 //---------------------------------------------------------------------------------------------------------------------------
825 /*! @defined require_noerr
826
827 @abstract Require that an error code is noErr (0).
828
829 @discussion
830
831 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
832 function name, etc.) using the default debugging output method then jumps to a label.
833 */
834
835 #if( DEBUG_OVERRIDE_APPLE_MACROS )
836 #undef require_noerr
837 #endif
838 #if( !defined( require_noerr ) )
839 #define require_noerr( ERR, LABEL ) \
840 do \
841 { \
842 int_least32_t localErr; \
843 \
844 localErr = (int_least32_t)( ERR ); \
845 if( localErr != 0 ) \
846 { \
847 debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
848 goto LABEL; \
849 } \
850 \
851 } while( 0 )
852 #endif
853
854 //---------------------------------------------------------------------------------------------------------------------------
855 /*! @defined require_noerr_string
856
857 @abstract Require that an error code is noErr (0).
858
859 @discussion
860
861 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
862 function name, etc.), and a custom explanation string using the default debugging output method using the
863 default debugging output method then jumps to a label.
864 */
865
866 #if( DEBUG_OVERRIDE_APPLE_MACROS )
867 #undef require_noerr_string
868 #endif
869 #if( !defined( require_noerr_string ) )
870 #define require_noerr_string( ERR, LABEL, STR ) \
871 do \
872 { \
873 int_least32_t localErr; \
874 \
875 localErr = (int_least32_t)( ERR ); \
876 if( localErr != 0 ) \
877 { \
878 debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \
879 goto LABEL; \
880 } \
881 \
882 } while( 0 )
883 #endif
884
885 //---------------------------------------------------------------------------------------------------------------------------
886 /*! @defined require_noerr_action_string
887
888 @abstract Require that an error code is noErr (0).
889
890 @discussion
891
892 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
893 function name, etc.), and a custom explanation string using the default debugging output method using the
894 default debugging output method then executes an action and jumps to a label.
895 */
896
897 #if( DEBUG_OVERRIDE_APPLE_MACROS )
898 #undef require_noerr_action_string
899 #endif
900 #if( !defined( require_noerr_action_string ) )
901 #define require_noerr_action_string( ERR, LABEL, ACTION, STR ) \
902 do \
903 { \
904 int_least32_t localErr; \
905 \
906 localErr = (int_least32_t)( ERR ); \
907 if( localErr != 0 ) \
908 { \
909 debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \
910 { ACTION; } \
911 goto LABEL; \
912 } \
913 \
914 } while( 0 )
915 #endif
916
917 //---------------------------------------------------------------------------------------------------------------------------
918 /*! @defined require_noerr_quiet
919
920 @abstract Require that an error code is noErr (0).
921
922 @discussion
923
924 If the error code is non-0, this jumps to a label. No debugging information is printed.
925 */
926
927 #if( DEBUG_OVERRIDE_APPLE_MACROS )
928 #undef require_noerr_quiet
929 #endif
930 #if( !defined( require_noerr_quiet ) )
931 #define require_noerr_quiet( ERR, LABEL ) \
932 do \
933 { \
934 if( ( ERR ) != 0 ) \
935 { \
936 goto LABEL; \
937 } \
938 \
939 } while( 0 )
940 #endif
941
942 //---------------------------------------------------------------------------------------------------------------------------
943 /*! @defined require_noerr_action
944
945 @abstract Require that an error code is noErr (0) with an action to execute otherwise.
946
947 @discussion
948
949 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
950 function name, etc.) using the default debugging output method then executes an action and jumps to a label.
951 */
952
953 #if( DEBUG_OVERRIDE_APPLE_MACROS )
954 #undef require_noerr_action
955 #endif
956 #if( !defined( require_noerr_action ) )
957 #define require_noerr_action( ERR, LABEL, ACTION ) \
958 do \
959 { \
960 int_least32_t localErr; \
961 \
962 localErr = (int_least32_t)( ERR ); \
963 if( localErr != 0 ) \
964 { \
965 debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
966 { ACTION; } \
967 goto LABEL; \
968 } \
969 \
970 } while( 0 )
971 #endif
972
973 //---------------------------------------------------------------------------------------------------------------------------
974 /*! @defined require_noerr_action_quiet
975
976 @abstract Require that an error code is noErr (0) with an action to execute otherwise.
977
978 @discussion
979
980 If the error code is non-0, this executes an action and jumps to a label. No debugging information is printed.
981 */
982
983 #if( DEBUG_OVERRIDE_APPLE_MACROS )
984 #undef require_noerr_action_quiet
985 #endif
986 #if( !defined( require_noerr_action_quiet ) )
987 #define require_noerr_action_quiet( ERR, LABEL, ACTION ) \
988 do \
989 { \
990 if( ( ERR ) != 0 ) \
991 { \
992 { ACTION; } \
993 goto LABEL; \
994 } \
995 \
996 } while( 0 )
997 #endif
998
999 //---------------------------------------------------------------------------------------------------------------------------
1000 /*! @defined require_action
1001
1002 @abstract Requires that an expression evaluate to true with an action to execute otherwise.
1003
1004 @discussion
1005
1006 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
1007 function name, etc.) using the default debugging output method then executes an action and jumps to a label.
1008 */
1009
1010 #if( DEBUG_OVERRIDE_APPLE_MACROS )
1011 #undef require_action
1012 #endif
1013 #if( !defined( require_action ) )
1014 #define require_action( X, LABEL, ACTION ) \
1015 do \
1016 { \
1017 if( !( X ) ) \
1018 { \
1019 debug_print_assert( 0, #X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
1020 { ACTION; } \
1021 goto LABEL; \
1022 } \
1023 \
1024 } while( 0 )
1025 #endif
1026
1027 //---------------------------------------------------------------------------------------------------------------------------
1028 /*! @defined require_action_quiet
1029
1030 @abstract Requires that an expression evaluate to true with an action to execute otherwise.
1031
1032 @discussion
1033
1034 If expression evalulates to false, this executes an action and jumps to a label. No debugging information is printed.
1035 */
1036
1037 #if( DEBUG_OVERRIDE_APPLE_MACROS )
1038 #undef require_action_quiet
1039 #endif
1040 #if( !defined( require_action_quiet ) )
1041 #define require_action_quiet( X, LABEL, ACTION ) \
1042 do \
1043 { \
1044 if( !( X ) ) \
1045 { \
1046 { ACTION; } \
1047 goto LABEL; \
1048 } \
1049 \
1050 } while( 0 )
1051 #endif
1052
1053 //---------------------------------------------------------------------------------------------------------------------------
1054 /*! @defined require_action_string
1055
1056 @abstract Requires that an expression evaluate to true with an explanation and action to execute otherwise.
1057
1058 @discussion
1059
1060 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
1061 function name, etc.) and a custom explanation string using the default debugging output method then executes an
1062 action and jumps to a label.
1063 */
1064
1065 #if( DEBUG_OVERRIDE_APPLE_MACROS )
1066 #undef require_action_string
1067 #endif
1068 #if( !defined( require_action_string ) )
1069 #define require_action_string( X, LABEL, ACTION, STR ) \
1070 do \
1071 { \
1072 if( !( X ) ) \
1073 { \
1074 debug_print_assert( 0, #X, STR, __FILE__, __LINE__, __ROUTINE__ ); \
1075 { ACTION; } \
1076 goto LABEL; \
1077 } \
1078 \
1079 } while( 0 )
1080
1081 #endif
1082
1083 //---------------------------------------------------------------------------------------------------------------------------
1084 /*! @defined require_throw
1085
1086 @abstract Requires that an expression evaluates to true or an exception is thrown.
1087
1088 @discussion
1089
1090 If the expression evaluates to false, this prints debugging information (actual expression string, file,
1091 line number, function name, etc.) using the default debugging output method then throws an exception.
1092 */
1093
1094 #if( defined( __cplusplus ) )
1095 #define require_throw( X ) \
1096 do \
1097 { \
1098 if( !( X ) ) \
1099 { \
1100 debug_print_assert( 0, #X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
1101 throw kUnknownErr; \
1102 } \
1103 \
1104 } while( 0 )
1105 #endif
1106
1107 #if 0
1108 #pragma mark == Design-By-Contract macros ==
1109 #endif
1110
1111 //===========================================================================================================================
1112 // Design-By-Contract macros
1113 //===========================================================================================================================
1114
1115 #define ensure( X ) check( X )
1116 #define ensure_string( X, STR ) check_string( X, STR )
1117 #define ensure_noerr( ERR ) check_noerr( ERR )
1118 #define ensure_noerr_string( ERR, STR ) check_noerr_string( ERR, STR )
1119 #define ensure_translated_errno( TEST, ERRNO, ALTERNATE_ERROR ) check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR )
1120
1121 // Note: Design-By-Contract "require" macros are already defined elsewhere.
1122
1123 #if 0
1124 #pragma mark == Expect macros ==
1125 #endif
1126
1127 //===========================================================================================================================
1128 // Expect macros
1129 //===========================================================================================================================
1130
1131 // Expect macros allow code to include runtime checking of things that should not happen in shipping code (e.g. internal
1132 // programmer errors, such as a NULL parameter where it is not allowed). Once the code has been verified to work correctly
1133 // without asserting, the DEBUG_EXPECT_VERIFIED conditional can be set to eliminate the error checking entirely. It can
1134 // also be useful to measure the cost of error checking code by profiling with it enable and with it disabled.
1135
1136 #if( DEBUG_EXPECT_VERIFIED )
1137 #define require_expect
1138 #define require_string_expect
1139 #define require_quiet_expect
1140 #define require_noerr_expect
1141 #define require_noerr_string_expect
1142 #define require_noerr_action_string_expect
1143 #define require_noerr_quiet_expect
1144 #define require_noerr_action_expect
1145 #define require_noerr_action_quiet_expect
1146 #define require_action_expect
1147 #define require_action_quiet_expect
1148 #define require_action_string_expect
1149 #else
1150 #define require_expect require
1151 #define require_string_expect require_string
1152 #define require_quiet_expect require_quiet
1153 #define require_noerr_expect require_noerr
1154 #define require_noerr_string_expect require_noerr_string
1155 #define require_noerr_action_string_expect require_noerr_action_string
1156 #define require_noerr_quiet_expect require_noerr_quiet
1157 #define require_noerr_action_expect require_noerr_action
1158 #define require_noerr_action_quiet_expect require_noerr_action_quiet
1159 #define require_action_expect require_action
1160 #define require_action_quiet_expect require_action_quiet
1161 #define require_action_string_expect require_action_string
1162 #endif
1163
1164 #if 0
1165 #pragma mark == Output macros ==
1166 #endif
1167
1168 //---------------------------------------------------------------------------------------------------------------------------
1169 /*! @defined debug_string
1170
1171 @abstract Prints a debugging C string.
1172 */
1173
1174 #if( DEBUG_OVERRIDE_APPLE_MACROS )
1175 #undef debug_string
1176 #endif
1177 #if( !defined( debug_string ) )
1178 #if( DEBUG )
1179 #define debug_string( STR ) \
1180 do \
1181 { \
1182 debug_print_assert( 0, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \
1183 \
1184 } while( 0 )
1185 #else
1186 #define debug_string( STR )
1187 #endif
1188 #endif
1189
1190 //---------------------------------------------------------------------------------------------------------------------------
1191 /*! @defined debug_print_assert
1192
1193 @abstract Prints an assertion.
1194 */
1195
1196 #if( DEBUG )
1197 #define debug_print_assert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION ) \
1198 DebugPrintAssert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION )
1199 #else
1200 #define debug_print_assert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION )
1201 #endif
1202
1203 //---------------------------------------------------------------------------------------------------------------------------
1204 /*! @defined dlog
1205
1206 @abstract Prints a debug-only message.
1207 */
1208
1209 #if( DEBUG )
1210 #if( DEBUG_C99_VA_ARGS )
1211 #define dlog( ... ) DebugPrintF( __VA_ARGS__ )
1212 #elif( DEBUG_GNU_VA_ARGS )
1213 #define dlog( ARGS... ) DebugPrintF( ## ARGS )
1214 #else
1215 #define dlog DebugPrintF
1216 #endif
1217 #else
1218 #if( DEBUG_C99_VA_ARGS )
1219 #define dlog( ... )
1220 #elif( DEBUG_GNU_VA_ARGS )
1221 #define dlog( ARGS... )
1222 #else
1223 #define dlog while( 0 )
1224 #endif
1225 #endif
1226
1227 //---------------------------------------------------------------------------------------------------------------------------
1228 /*! @defined dlogv
1229
1230 @abstract Prints a debug-only message.
1231 */
1232
1233 #if( DEBUG )
1234 #define dlogv( LEVEL, FORMAT, LIST ) DebugPrintFVAList( ( LEVEL ), ( FORMAT ), ( LIST ) )
1235 #else
1236 #define dlogv( LEVEL, FORMAT, LIST )
1237 #endif
1238
1239 //---------------------------------------------------------------------------------------------------------------------------
1240 /*! @defined dlogmem
1241
1242 @abstract Prints a debug-only dump of memory.
1243 */
1244
1245 #if( DEBUG )
1246 #define dlogmem( LEVEL, PTR, SIZE ) \
1247 DebugHexDump( ( LEVEL ), 0, NULL, 0, 0, NULL, 0, ( PTR ), ( PTR ), ( SIZE ), kDebugFlagsNone, NULL, 0 )
1248 #else
1249 #define dlogmem( LEVEL, PTR, SIZE )
1250 #endif
1251
1252 //---------------------------------------------------------------------------------------------------------------------------
1253 /*! @defined DebugNSLog
1254
1255 @abstract Debug-only macro for the Cocoa NSLog function.
1256 */
1257
1258 #if( DEBUG )
1259 #if( DEBUG_C99_VA_ARGS )
1260 #define DebugNSLog( ... ) NSLog( __VA_ARGS__ )
1261 #elif( DEBUG_GNU_VA_ARGS )
1262 #define DebugNSLog( ARGS... ) NSLog( ## ARGS )
1263 #else
1264 #define DebugNSLog NSLog
1265 #endif
1266 #else
1267 #if( DEBUG_C99_VA_ARGS )
1268 #define DebugNSLog( ... )
1269 #elif( DEBUG_GNU_VA_ARGS )
1270 #define DebugNSLog( ARGS... )
1271 #else
1272 #define DebugNSLog while( 0 )
1273 #endif
1274 #endif
1275
1276 //---------------------------------------------------------------------------------------------------------------------------
1277 /*! @defined DebugLogMsg
1278
1279 @abstract Debug-only macro for the VxWorks logMsg function.
1280 */
1281
1282 #if( TARGET_OS_VXWORKS )
1283 #if( DEBUG )
1284 #define DebugLogMsg( LEVEL, FORMAT, P1, P2, P3, P4, P5, P6 ) \
1285 do \
1286 { \
1287 if( ( inLevel >= gDebugPrintLevelMin ) || ( inLevel <= gDebugPrintLevelMax ) ) \
1288 { \
1289 logMsg( ( FORMAT ), ( P1 ), ( P2 ), ( P3 ), ( P4 ), ( P5 ), ( P6 ) ); \
1290 } \
1291 \
1292 } while( 0 )
1293 #else
1294 #define DebugLogMsg( LEVEL, FORMAT, P1, P2, P3, P4, P5, P6 )
1295 #endif
1296 #else
1297 #define DebugLogMsg dlog
1298 #endif
1299
1300 #if 0
1301 #pragma mark == Routines - General ==
1302 #endif
1303
1304 #ifdef __cplusplus
1305 extern "C" {
1306 #endif
1307
1308 //---------------------------------------------------------------------------------------------------------------------------
1309 /*! @function DebugInitialize
1310
1311 @abstract Initializes the debugging library for a specific kind of output.
1312
1313 @param inType
1314 @param varArg Variable number parameters, controlled by the "inType" parameter.
1315 */
1316
1317 #if( DEBUG )
1318 DEBUG_EXPORT OSStatus DebugInitialize( DebugOutputType inType, ... );
1319 #endif
1320
1321 #if( DEBUG )
1322 #if( DEBUG_C99_VA_ARGS )
1323 #define debug_initialize( ... ) DebugInitialize( __VA_ARGS__ )
1324 #elif( DEBUG_GNU_VA_ARGS )
1325 #define debug_initialize( ARGS... ) DebugInitialize( ## ARGS )
1326 #else
1327 #define debug_initialize DebugInitialize
1328 #endif
1329 #else
1330 #if( DEBUG_C99_VA_ARGS )
1331 #define debug_initialize( ... )
1332 #elif( DEBUG_GNU_VA_ARGS )
1333 #define debug_initialize( ARGS... )
1334 #else
1335 #define debug_initialize while( 0 )
1336 #endif
1337 #endif
1338
1339 //---------------------------------------------------------------------------------------------------------------------------
1340 /*! @function DebugFinalize
1341
1342 @abstract Releases any resources used by the debugging library
1343 */
1344
1345 #if( DEBUG )
1346 DEBUG_EXPORT void DebugFinalize( void );
1347 #endif
1348
1349 #if( DEBUG )
1350 #define debug_terminate() DebugFinalize()
1351 #else
1352 #define debug_terminate()
1353 #endif
1354
1355 //---------------------------------------------------------------------------------------------------------------------------
1356 /*! @function DebugGetProperty
1357
1358 @abstract Gets the specified property from the debugging library.
1359 */
1360
1361 #if( DEBUG )
1362 DEBUG_EXPORT OSStatus DebugGetProperty( DebugPropertyTag inTag, ... );
1363 #endif
1364
1365 #if( DEBUG )
1366 #if( DEBUG_C99_VA_ARGS )
1367 #define debug_get_property( ... ) DebugGetProperty( __VA_ARGS__ )
1368 #elif( DEBUG_GNU_VA_ARGS )
1369 #define debug_get_property( ARGS... ) DebugGetProperty( ## ARGS )
1370 #else
1371 #define debug_get_property DebugGetProperty
1372 #endif
1373 #else
1374 #if( DEBUG_C99_VA_ARGS )
1375 #define debug_get_property( ... )
1376 #elif( DEBUG_GNU_VA_ARGS )
1377 #define debug_get_property( ARGS... )
1378 #else
1379 #define debug_get_property while( 0 )
1380 #endif
1381 #endif
1382
1383 //---------------------------------------------------------------------------------------------------------------------------
1384 /*! @function DebugSetProperty
1385
1386 @abstract Sets the specified property from the debugging library.
1387 */
1388
1389 #if( DEBUG )
1390 DEBUG_EXPORT OSStatus DebugSetProperty( DebugPropertyTag inTag, ... );
1391 #endif
1392
1393 #if( DEBUG )
1394 #if( DEBUG_C99_VA_ARGS )
1395 #define debug_set_property( ... ) DebugSetProperty( __VA_ARGS__ )
1396 #elif( DEBUG_GNU_VA_ARGS )
1397 #define debug_set_property( ARGS... ) DebugSetProperty( ## ARGS )
1398 #else
1399 #define debug_set_property DebugSetProperty
1400 #endif
1401 #else
1402 #if( DEBUG_C99_VA_ARGS )
1403 #define debug_set_property( ... )
1404 #elif( DEBUG_GNU_VA_ARGS )
1405 #define debug_set_property( ARGS... )
1406 #else
1407 #define debug_set_property while( 0 )
1408 #endif
1409 #endif
1410
1411 #if 0
1412 #pragma mark == Routines - Debugging Output ==
1413 #endif
1414
1415 //---------------------------------------------------------------------------------------------------------------------------
1416 /*! @function DebugPrintF
1417
1418 @abstract Prints a debug message with printf-style formatting.
1419
1420 @param inLevel Error that generated this assert or noErr.
1421
1422 @param inFormatString
1423 C string containing assertion text.
1424
1425 @param VAR_ARG
1426 Variable number of arguments depending on the format string.
1427
1428 @result Number of bytes printed or -1 on error.
1429 */
1430
1431 #if( DEBUG )
1432 DEBUG_EXPORT size_t DebugPrintF( DebugLevel inLevel, const char *inFormat, ... );
1433 #endif
1434
1435 //---------------------------------------------------------------------------------------------------------------------------
1436 /*! @function DebugPrintFVAList
1437
1438 @abstract va_list version of DebugPrintF. See DebugPrintF for more info.
1439 */
1440
1441 #if( DEBUG )
1442 DEBUG_EXPORT size_t DebugPrintFVAList( DebugLevel inLevel, const char *inFormat, va_list inArgs );
1443 #endif
1444
1445 //---------------------------------------------------------------------------------------------------------------------------
1446 /*! @function DebugPrintAssert
1447
1448 @abstract Prints a message describing the reason the (e.g. an assert failed), an optional error message,
1449 an optional source filename, an optional source line number.
1450
1451 @param inErrorCode Error that generated this assert or noErr.
1452 @param inAssertString C string containing assertion text.
1453 @param inMessage C string containing a message about the assert.
1454 @param inFileName C string containing path of file where the error occurred.
1455 @param inLineNumber Line number in source file where the error occurred.
1456 @param inFunction C string containing name of function where assert occurred.
1457
1458 @discussion
1459
1460 Example output:
1461
1462 [ASSERT] assert: "dataPtr != NULL" allocate memory for object failed
1463 [ASSERT] where: "MyFile.c", line 123, ("MyFunction")
1464
1465 OR
1466
1467 [ASSERT] error: -6728 (kNoMemoryErr)
1468 [ASSERT] where: "MyFile.c", line 123, ("MyFunction")
1469 */
1470
1471 #if( DEBUG )
1472 DEBUG_EXPORT void
1473 DebugPrintAssert(
1474 int_least32_t inErrorCode,
1475 const char * inAssertString,
1476 const char * inMessage,
1477 const char * inFilename,
1478 int_least32_t inLineNumber,
1479 const char * inFunction );
1480 #endif
1481
1482 #if 0
1483 #pragma mark == Routines - Utilities ==
1484 #endif
1485
1486 //---------------------------------------------------------------------------------------------------------------------------
1487 /*! @function DebugSNPrintF
1488
1489 @abstract Debugging versions of standard C snprintf with extra features.
1490
1491 @param sbuffer Buffer to receive result. Null terminated unless the buffer size is 0.
1492 @param buflen Size of the buffer including space for the null terminator.
1493 @param fmt printf-style format string.
1494 @param VAR_ARG Variable number of arguments depending on the format string.
1495
1496 @result Number of characters written (minus the null terminator).
1497
1498 @discussion
1499
1500 Extra features over the standard C snprintf:
1501 <pre>
1502 64-bit support for %d (%lld), %i (%lli), %u (%llu), %o (%llo), %x (%llx), and %b (%llb).
1503 %@ - Cocoa/CoreFoundation object. Param is the object. Strings are used directly. Others use CFCopyDescription.
1504 %a - Network Address: %.4a=IPv4, %.6a=Ethernet, %.8a Fibre Channel, %.16a=IPv6. Arg=ptr to network address.
1505 %#a - IPv4 or IPv6 mDNSAddr. Arg=ptr to mDNSAddr.
1506 %##a - IPv4 (if AF_INET defined) or IPv6 (if AF_INET6 defined) sockaddr. Arg=ptr to sockaddr.
1507 %b - Binary representation of integer (e.g. 01101011). Modifiers and arg=the same as %d, %x, etc.
1508 %C - Mac-style FourCharCode (e.g. 'APPL'). Arg=32-bit value to print as a Mac-style FourCharCode.
1509 %H - Hex Dump (e.g. "\x6b\xa7" -> "6B A7"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size.
1510 %#H - Hex Dump & ASCII (e.g. "\x41\x62" -> "6B A7 'Ab'"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size.
1511 %m - Error Message (e.g. 0 -> "kNoErr"). Modifiers and error code arg=the same as %d, %x, etc.
1512 %#s - Pascal-style length-prefixed string. Arg=ptr to string.
1513 %##s - DNS label-sequence name. Arg=ptr to name.
1514 %S - UTF-16 string, 0x0000 terminated. Host order if no BOM. Precision is UTF-16 count. Precision includes BOM.
1515 %#S - Big Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S.
1516 %##S - Little Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S.
1517 %U - Universally Unique Identifier (UUID) (e.g. 6ba7b810-9dad-11d1-80b4-00c04fd430c8). Arg=ptr to 16-byte UUID.
1518 </pre>
1519 */
1520
1521 #if( DEBUG )
1522 DEBUG_EXPORT size_t DebugSNPrintF(char *sbuffer, size_t buflen, const char *fmt, ...);
1523 #endif
1524
1525 //---------------------------------------------------------------------------------------------------------------------------
1526 /*! @function DebugSNPrintFVAList
1527
1528 @abstract va_list version of DebugSNPrintF. See DebugSNPrintF for more info.
1529 */
1530
1531 #if( DEBUG )
1532 DEBUG_EXPORT size_t DebugSNPrintFVAList(char *sbuffer, size_t buflen, const char *fmt, va_list arg);
1533 #endif
1534
1535 //---------------------------------------------------------------------------------------------------------------------------
1536 /*! @function DebugGetErrorString
1537
1538 @abstract Gets an error string from an error code.
1539
1540 @param inStatus Error code to get the string for.
1541 @param inBuffer Optional buffer to copy the string to for non-static strings. May be null.
1542 @param inBufferSize Size of optional buffer. May be 0.
1543
1544 @result C string containing error string for the error code. Guaranteed to be a valid, static string. If a
1545 buffer is supplied, the return value will always be a pointer to the supplied buffer, which will
1546 contain the best available description of the error code. If a buffer is not supplied, the return
1547 value will be the best available description of the error code that can be represented as a static
1548 string. This allows code that cannot use a temporary buffer to hold the result to still get a useful
1549 error string in most cases, but also allows code that can use a temporary buffer to get the best
1550 available description.
1551 */
1552
1553 #if( DEBUG )
1554 DEBUG_EXPORT const char * DebugGetErrorString( int_least32_t inErrorCode, char *inBuffer, size_t inBufferSize );
1555 #endif
1556
1557 //---------------------------------------------------------------------------------------------------------------------------
1558 /*! @function DebugHexDump
1559
1560 @abstract Hex dumps data to a string or to the output device.
1561 */
1562
1563 #if( DEBUG )
1564 DEBUG_EXPORT size_t
1565 DebugHexDump(
1566 DebugLevel inLevel,
1567 int inIndent,
1568 const char * inLabel,
1569 size_t inLabelSize,
1570 int inLabelMinWidth,
1571 const char * inType,
1572 size_t inTypeSize,
1573 const void * inDataStart,
1574 const void * inData,
1575 size_t inDataSize,
1576 DebugFlags inFlags,
1577 char * outBuffer,
1578 size_t inBufferSize );
1579 #endif
1580
1581 #if( DEBUG )
1582 #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE ) \
1583 DebugHexDump( ( LEVEL ), (INDENT), ( LABEL ), ( LABEL_SIZE ), ( LABEL_MIN_SIZE ), ( TYPE ), ( TYPE_SIZE ), \
1584 ( DATA_START ), ( DATA ), ( DATA_SIZE ), ( FLAGS ), ( BUFFER ), ( BUFFER_SIZE ) )
1585 #else
1586 #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE )
1587 #endif
1588
1589 //---------------------------------------------------------------------------------------------------------------------------
1590 /*! @function DebugTaskLevel
1591
1592 @abstract Returns the current task level.
1593
1594 @result Current task level
1595
1596 @discussion
1597
1598 Bit masks to isolate portions of the result (note that some masks may also need bit shifts to right justify):
1599 <pre>
1600 kDebugInterruptLevelMask - Indicates the current interrupt level (> 0 means interrupt time).
1601 kDebugInVBLTaskMask - Indicates if a VBL task is currently being executed.
1602 kDebugInDeferredTaskMask - Indicates if a Deferred Task is currently being executed.
1603 kDebugInSecondaryInterruptHandlerMask - Indicates if a Secondary Interrupt Handler is currently being executed.
1604 kDebugPageFaultFatalMask - Indicates if it is unsafe to cause a page fault (worse than interrupt time).
1605 kDebugMPTaskLevelMask - Indicates if being called from an MP task.
1606 kDebugInterruptDepthMask - 0 means task level, 1 means in interrupt, > 1 means in nested interrupt.
1607 </pre>
1608
1609 Helpers:
1610 <pre>
1611 DebugExtractTaskLevelInterruptDepth() - Macro to extract interrupt depth from task level value.
1612 </pre>
1613 */
1614
1615 #if( DEBUG )
1616 DEBUG_EXPORT uint32_t DebugTaskLevel( void );
1617 #endif
1618
1619 //---------------------------------------------------------------------------------------------------------------------------
1620 /*! @function DebugServicesTest
1621
1622 @abstract Unit test.
1623 */
1624
1625 #if( DEBUG )
1626 DEBUG_EXPORT OSStatus DebugServicesTest( void );
1627 #endif
1628
1629 #ifdef __cplusplus
1630 }
1631 #endif
1632
1633 #endif // __DEBUG_SERVICES__
mirror of mDNSResponder