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


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