?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
bump product version to 5.0.4.1
[LibreOffice.git] / sd / source / ui / remotecontrol / mDNSResponder / DebugServices.h
blob11d927a60fa5a7755bf3b580ddc17b83d970dd70
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 kDebugLevelInfo 1000
286 #define kDebugLevelNotice 3000
287 #define kDebugLevelWarning 5000
288 #define kDebugLevelAssert 6000
289 #define kDebugLevelError 8000
290 #define kDebugLevelMax 0x0000FFFF
291
292 // Level Flags
293
294
295
296 /*! @typedef LogLevel
297
298 @abstract Level used to control which events are logged.
299 */
300
301 typedef int32_t LogLevel;
302
303 #define kLogLevelUninitialized -1L
304
305 #if 0
306 #pragma mark == Properties ==
307 #endif
308
309
310 /*! @typedef DebugPropertyTag
311
312 @abstract Tag for properties.
313 */
314
315 typedef uint32_t DebugPropertyTag;
316
317 #define kDebugPropertyTagPrintLevelMin 0x6D696E70U // 'minp' Get: 1st param = DebugLevel *
318 // Set: 1st param = DebugLevel
319
320
321 #define kDebugPropertyTagPrintLevelMax 0x706D786CU // 'maxp' Get: 1st param = DebugLevel *
322 // Set: 1st param = DebugLevel
323
324 #define kDebugPropertyTagBreakLevel 0x62726B6CU // 'brkl' Get: 1st param = DebugLevel *
325 // Set: 1st param = DebugLevel
326 #if 0
327 #pragma mark == General macros ==
328 #endif
329
330
331 /*! @defined DEBUG_UNUSED
332
333 @abstract Macro to mark a parameter as unused to avoid unused parameter warnings.
334
335 @discussion
336
337 There is no universally supported pragma/attribute for indicating a variable is unused. DEBUG_UNUSED lets us
338 indicate a variable is unused in a manner that is supported by most compilers.
339 */
340
341 #define DEBUG_UNUSED( X ) (void)( X )
342
343
344 /*! @defined DEBUG_USE_ONLY
345
346 @abstract Macro to mark a variable as used only when debugging is enabled.
347
348 @discussion
349
350 Variables are sometimes needed only for debugging. When debugging is turned off, these debug-only variables generate
351 compiler warnings about unused variables. To eliminate these warnings, use these macros to indicate variables that
352 are only used for debugging.
353 */
354
355 #if ( DEBUG )
356 #define DEBUG_USE_ONLY( X )
357 #else
358 #define DEBUG_USE_ONLY( X ) (void)( X )
359 #endif
360
361
362 /*! @defined DEBUG_LOCAL
363
364 @abstract Macros to make variables and functions static when debugging is off, but extern when debugging is on.
365
366 @discussion
367
368 Rather than using "static" directly, using this macros allows you to access these variables external while
369 debugging without being penalized for production builds.
370 */
371
372 #if ( DEBUG )
373 #define DEBUG_LOCAL
374 #else
375 #define DEBUG_LOCAL static
376 #endif
377
378
379 /*! @defined DEBUG_STATIC
380
381 @abstract Macros to make variables and functions static when debugging is off, but extern when debugging is on.
382
383 @discussion
384
385 Rather than using "static" directly, using this macros allows you to access these variables external while
386 debugging without being penalized for production builds.
387 */
388
389 #if ( DEBUG )
390 #define DEBUG_STATIC
391 #else
392 #define DEBUG_STATIC static
393 #endif
394
395
396 /*! @defined DEBUG_EXPORT
397
398 @abstract Macros to export variables.
399
400 @discussion
401
402 "__private_extern__" is a hack for IOKit to allow symbols to be exported from compilation units, but
403 // not exported outside a driver (IOKit uses a lame global namespace for symbols). This still does not
404 // solve the problem of multiple drivers in the same dependency chain since they share symbols.
405 */
406
407 #if ( TARGET_API_MAC_OSX_KERNEL )
408 #define DEBUG_EXPORT __private_extern__
409 #else
410 #define DEBUG_EXPORT extern
411 #endif
412
413
414 /*! @defined debug_add
415
416 @abstract Macro to add (or subtract if negative) a value when debugging is on. Does nothing if debugging is off.
417 */
418
419 #if ( DEBUG )
420 #define debug_add( A, B ) ( A ) += ( B )
421 #else
422 #define debug_add( A, B )
423 #endif
424
425
426 /*! @defined debug_perform
427
428 @abstract Macro to perform something in debug-only builds.
429 */
430
431 #if ( DEBUG )
432 #define debug_perform( X ) do { X; } while( 0 )
433 #else
434 #define debug_perform( X )
435 #endif
436
437
438 /*! @function translate_errno
439
440 @abstract Returns 0 if the test success. If the test fails, returns errno if non-zero and othewise the alternate error.
441 */
442
443 #define translate_errno( TEST, ERRNO, ALTERNATE_ERROR ) ( ( TEST ) ? 0 : ( ERRNO ) ? ( ERRNO ) : ( ALTERNATE_ERROR ) )
444
445 #if 0
446 #pragma mark == Compile Time macros ==
447 #endif
448
449
450 /*! @defined check_compile_time
451
452 @abstract Performs a compile-time check of something such as the size of an int.
453
454 @discussion
455
456 This declares an array with a size that is determined by a compile-time expression. If the expression evaluates
457 to 0, the array has a size of -1, which is illegal and generates a compile-time error.
458
459 For example:
460
461 check_compile_time( sizeof( int ) == 4 );
462
463 Note: This only works with compile-time expressions.
464 Note: This only works in places where extern declarations are allowed (e.g. global scope).
465
466 References:
467
468 <http://www.jaggersoft.com/pubs/CVu11_3.html>
469 <http://www.jaggersoft.com/pubs/CVu11_5.html>
470
471 Note: The following macros differ from the macros on the www.jaggersoft.com web site because those versions do not
472 work with GCC due to GCC allow a zero-length array. Using a -1 condition turned out to be more portable.
473 */
474
475 #define check_compile_time( X ) extern int debug_compile_time_name[ ( X ) ? 1 : -1 ]
476
477
478 /*! @defined check_compile_time_code
479
480 @abstract Perform a compile-time check, suitable for placement in code, of something such as the size of an int.
481
482 @discussion
483
484 This creates a switch statement with an existing case for 0 and an additional case using the result of a
485 compile-time expression. A switch statement cannot have two case labels with the same constant so if the
486 compile-time expression evaluates to 0, it is illegal and generates a compile-time error. If the compile-time
487 expression does not evaluate to 0, the resulting value is used as the case label and it compiles without error.
488
489 For example:
490
491 check_compile_time_code( sizeof( int ) == 4 );
492
493 Note: This only works with compile-time expressions.
494 Note: This does not work in a global scope so it must be inside a function.
495
496 References:
497
498 <http://www.jaggersoft.com/pubs/CVu11_3.html>
499 <http://www.jaggersoft.com/pubs/CVu11_5.html>
500 */
501
502 #define check_compile_time_code( X ) switch( 0 ) { case 0: case X:; }
503
504 #if 0
505 #pragma mark == check macros ==
506 #endif
507
508
509 /*! @defined check
510
511 @abstract Check that an expression is true (non-zero).
512
513 @discussion
514
515 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
516 function name, etc.) using the default debugging output method.
517
518 Code inside check() statements is not compiled into production builds.
519 */
520
521 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
522 #undef check
523 #endif
524 #if ( !defined( check ) )
525 #if ( DEBUG )
526 #define check( X ) \
527 do \
528 { \
529 if( !( X ) ) \
530 { \
531 debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
532 } \
533 } while( 0 )
534 #else
535 #define check( X )
536 #endif
537 #endif
538
539
540 /*! @defined check_string
541
542 @abstract Check that an expression is true (non-zero) with an explanation.
543
544 @discussion
545
546 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
547 function name, etc.) and a custom explanation string using the default debugging output method.
548
549 Code inside check_string() statements is not compiled into production builds.
550 */
551
552 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
553 #undef check_string
554 #endif
555 #if ( !defined( check_string ) )
556 #if ( DEBUG )
557 #define check_string( X, STR ) \
558 do \
559 { \
560 if( !( X ) ) \
561 { \
562 debug_print_assert( 0, # X, STR, __FILE__, __LINE__, __ROUTINE__ ); \
563 } \
564 \
565 } while( 0 )
566 #else
567 #define check_string( X, STR )
568 #endif
569 #endif
570
571
572 /*! @defined check_noerr
573
574 @abstract Check that an error code is noErr (0).
575
576 @discussion
577
578 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
579 function name, etc.) using the default debugging output method.
580
581 Code inside check_noerr() statements is not compiled into production builds.
582 */
583
584 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
585 #undef check_noerr
586 #endif
587 #if ( !defined( check_noerr ) )
588 #if ( DEBUG )
589 #define check_noerr( ERR ) \
590 do \
591 { \
592 int_least32_t localErr; \
593 \
594 localErr = (int_least32_t)( ERR ); \
595 if( localErr != 0 ) \
596 { \
597 debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
598 } \
599 \
600 } while( 0 )
601 #else
602 #define check_noerr( ERR )
603 #endif
604 #endif
605
606
607 /*! @defined check_noerr_string
608
609 @abstract Check that an error code is noErr (0) with an explanation.
610
611 @discussion
612
613 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
614 function name, etc.) and a custom explanation string using the default debugging output method.
615
616 Code inside check_noerr_string() statements is not compiled into production builds.
617 */
618
619 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
620 #undef check_noerr_string
621 #endif
622 #if ( !defined( check_noerr_string ) )
623 #if ( DEBUG )
624 #define check_noerr_string( ERR, STR ) \
625 do \
626 { \
627 int_least32_t localErr; \
628 \
629 localErr = (int_least32_t)( ERR ); \
630 if( localErr != 0 ) \
631 { \
632 debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \
633 } \
634 \
635 } while( 0 )
636 #else
637 #define check_noerr_string( ERR, STR )
638 #endif
639 #endif
640
641
642 /*! @defined check_translated_errno
643
644 @abstract Check a condition and prints errno (if non-zero) to the log.
645
646 @discussion
647
648 Code inside check_translated_errno() statements is not compiled into production builds.
649 */
650
651 #if ( !defined( check_translated_errno ) )
652 #if ( DEBUG )
653 #define check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR ) \
654 do \
655 { \
656 if( !( TEST ) ) \
657 { \
658 int_least32_t localErr; \
659 \
660 localErr = (int_least32_t)( ERRNO ); \
661 localErr = ( localErr != 0 ) ? localErr : (int_least32_t)( ALTERNATE_ERROR ); \
662 debug_print_assert( localErr, # TEST, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
663 } \
664 \
665 } while( 0 )
666 #else
667 #define check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR )
668 #endif
669 #endif
670
671
672 /*! @defined check_ptr_overlap
673
674 @abstract Checks that two ptrs do not overlap.
675 */
676
677 #define check_ptr_overlap( P1, P1_SIZE, P2, P2_SIZE ) \
678 do \
679 { \
680 check( !( ( (uintptr_t)( P1 ) >= (uintptr_t)( P2 ) ) && \
681 ( (uintptr_t)( P1 ) < ( ( (uintptr_t)( P2 ) ) + ( P2_SIZE ) ) ) ) ); \
682 check( !( ( (uintptr_t)( P2 ) >= (uintptr_t)( P1 ) ) && \
683 ( (uintptr_t)( P2 ) < ( ( (uintptr_t)( P1 ) ) + ( P1_SIZE ) ) ) ) ); \
684 \
685 } while( 0 )
686
687 #if 0
688 #pragma mark == require macros ==
689 #endif
690
691
692 /*! @defined require
693
694 @abstract Requires that an expression evaluate to true.
695
696 @discussion
697
698 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
699 function name, etc.) using the default debugging output method then jumps to a label.
700 */
701
702 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
703 #undef require
704 #endif
705 #if ( !defined( require ) )
706 #define require( X, LABEL ) \
707 do \
708 { \
709 if( !( X ) ) \
710 { \
711 debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
712 goto LABEL; \
713 } \
714 \
715 } while( 0 )
716 #endif
717
718
719 /*! @defined require_string
720
721 @abstract Requires that an expression evaluate to true with an explanation.
722
723 @discussion
724
725 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
726 function name, etc.) and a custom explanation string using the default debugging output method then jumps to a label.
727 */
728
729 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
730 #undef require_string
731 #endif
732 #if ( !defined( require_string ) )
733 #define require_string( X, LABEL, STR ) \
734 do \
735 { \
736 if( !( X ) ) \
737 { \
738 debug_print_assert( 0, # X, STR, __FILE__, __LINE__, __ROUTINE__ ); \
739 goto LABEL; \
740 } \
741 \
742 } while( 0 )
743 #endif
744
745
746 /*! @defined require_quiet
747
748 @abstract Requires that an expression evaluate to true.
749
750 @discussion
751
752 If expression evalulates to false, this jumps to a label. No debugging information is printed.
753 */
754
755 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
756 #undef require_quiet
757 #endif
758 #if ( !defined( require_quiet ) )
759 #define require_quiet( X, LABEL ) \
760 do \
761 { \
762 if( !( X ) ) \
763 { \
764 goto LABEL; \
765 } \
766 \
767 } while( 0 )
768 #endif
769
770
771 /*! @defined require_noerr
772
773 @abstract Require that an error code is noErr (0).
774
775 @discussion
776
777 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
778 function name, etc.) using the default debugging output method then jumps to a label.
779 */
780
781 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
782 #undef require_noerr
783 #endif
784 #if ( !defined( require_noerr ) )
785 #define require_noerr( ERR, LABEL ) \
786 do \
787 { \
788 int_least32_t localErr; \
789 \
790 localErr = (int_least32_t)( ERR ); \
791 if( localErr != 0 ) \
792 { \
793 debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
794 goto LABEL; \
795 } \
796 \
797 } while( 0 )
798 #endif
799
800
801 /*! @defined require_noerr_string
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.), and a custom explanation string using the default debugging output method using the
809 default debugging output method then jumps to a label.
810 */
811
812 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
813 #undef require_noerr_string
814 #endif
815 #if ( !defined( require_noerr_string ) )
816 #define require_noerr_string( ERR, LABEL, STR ) \
817 do \
818 { \
819 int_least32_t localErr; \
820 \
821 localErr = (int_least32_t)( ERR ); \
822 if( localErr != 0 ) \
823 { \
824 debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \
825 goto LABEL; \
826 } \
827 \
828 } while( 0 )
829 #endif
830
831
832 /*! @defined require_noerr_action_string
833
834 @abstract Require that an error code is noErr (0).
835
836 @discussion
837
838 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
839 function name, etc.), and a custom explanation string using the default debugging output method using the
840 default debugging output method then executes an action and jumps to a label.
841 */
842
843 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
844 #undef require_noerr_action_string
845 #endif
846 #if ( !defined( require_noerr_action_string ) )
847 #define require_noerr_action_string( ERR, LABEL, ACTION, STR ) \
848 do \
849 { \
850 int_least32_t localErr; \
851 \
852 localErr = (int_least32_t)( ERR ); \
853 if( localErr != 0 ) \
854 { \
855 debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \
856 { ACTION; } \
857 goto LABEL; \
858 } \
859 \
860 } while( 0 )
861 #endif
862
863
864 /*! @defined require_noerr_quiet
865
866 @abstract Require that an error code is noErr (0).
867
868 @discussion
869
870 If the error code is non-0, this jumps to a label. No debugging information is printed.
871 */
872
873 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
874 #undef require_noerr_quiet
875 #endif
876 #if ( !defined( require_noerr_quiet ) )
877 #define require_noerr_quiet( ERR, LABEL ) \
878 do \
879 { \
880 if( ( ERR ) != 0 ) \
881 { \
882 goto LABEL; \
883 } \
884 \
885 } while( 0 )
886 #endif
887
888
889 /*! @defined require_noerr_action
890
891 @abstract Require that an error code is noErr (0) with an action to execute otherwise.
892
893 @discussion
894
895 If the error code is non-0, this prints debugging information (actual expression string, file, line number,
896 function name, etc.) using the default debugging output method then executes an action and jumps to a label.
897 */
898
899 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
900 #undef require_noerr_action
901 #endif
902 #if ( !defined( require_noerr_action ) )
903 #define require_noerr_action( ERR, LABEL, ACTION ) \
904 do \
905 { \
906 int_least32_t localErr; \
907 \
908 localErr = (int_least32_t)( ERR ); \
909 if( localErr != 0 ) \
910 { \
911 debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
912 { ACTION; } \
913 goto LABEL; \
914 } \
915 \
916 } while( 0 )
917 #endif
918
919
920 /*! @defined require_noerr_action_quiet
921
922 @abstract Require that an error code is noErr (0) with an action to execute otherwise.
923
924 @discussion
925
926 If the error code is non-0, this executes an action and jumps to a label. No debugging information is printed.
927 */
928
929 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
930 #undef require_noerr_action_quiet
931 #endif
932 #if ( !defined( require_noerr_action_quiet ) )
933 #define require_noerr_action_quiet( ERR, LABEL, ACTION ) \
934 do \
935 { \
936 if( ( ERR ) != 0 ) \
937 { \
938 { ACTION; } \
939 goto LABEL; \
940 } \
941 \
942 } while( 0 )
943 #endif
944
945
946 /*! @defined require_action
947
948 @abstract Requires that an expression evaluate to true with an action to execute otherwise.
949
950 @discussion
951
952 If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
953 function name, etc.) using the default debugging output method then executes an action and jumps to a label.
954 */
955
956 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
957 #undef require_action
958 #endif
959 #if ( !defined( require_action ) )
960 #define require_action( X, LABEL, ACTION ) \
961 do \
962 { \
963 if( !( X ) ) \
964 { \
965 debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
966 { ACTION; } \
967 goto LABEL; \
968 } \
969 \
970 } while( 0 )
971 #endif
972
973
974 /*! @defined require_action_quiet
975
976 @abstract Requires that an expression evaluate to true with an action to execute otherwise.
977
978 @discussion
979
980 If expression evalulates to false, 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_action_quiet
985 #endif
986 #if ( !defined( require_action_quiet ) )
987 #define require_action_quiet( X, LABEL, ACTION ) \
988 do \
989 { \
990 if( !( X ) ) \
991 { \
992 { ACTION; } \
993 goto LABEL; \
994 } \
995 \
996 } while( 0 )
997 #endif
998
999
1000 /*! @defined require_action_string
1001
1002 @abstract Requires that an expression evaluate to true with an explanation and 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.) and a custom explanation string using the default debugging output method then executes an
1008 action and jumps to a label.
1009 */
1010
1011 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
1012 #undef require_action_string
1013 #endif
1014 #if ( !defined( require_action_string ) )
1015 #define require_action_string( X, LABEL, ACTION, STR ) \
1016 do \
1017 { \
1018 if( !( X ) ) \
1019 { \
1020 debug_print_assert( 0, # X, STR, __FILE__, __LINE__, __ROUTINE__ ); \
1021 { ACTION; } \
1022 goto LABEL; \
1023 } \
1024 \
1025 } while( 0 )
1026
1027 #endif
1028
1029
1030 /*! @defined require_throw
1031
1032 @abstract Requires that an expression evaluates to true or an exception is thrown.
1033
1034 @discussion
1035
1036 If the expression evaluates to false, this prints debugging information (actual expression string, file,
1037 line number, function name, etc.) using the default debugging output method then throws an exception.
1038 */
1039
1040 #if ( defined( __cplusplus ) )
1041 #define require_throw( X ) \
1042 do \
1043 { \
1044 if( !( X ) ) \
1045 { \
1046 debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \
1047 throw kUnknownErr; \
1048 } \
1049 \
1050 } while( 0 )
1051 #endif
1052
1053 #if 0
1054 #pragma mark == Design-By-Contract macros ==
1055 #endif
1056
1057
1058 // Design-By-Contract macros
1059
1060
1061 #define ensure( X ) check( X )
1062 #define ensure_string( X, STR ) check_string( X, STR )
1063 #define ensure_noerr( ERR ) check_noerr( ERR )
1064 #define ensure_noerr_string( ERR, STR ) check_noerr_string( ERR, STR )
1065 #define ensure_translated_errno( TEST, ERRNO, ALTERNATE_ERROR ) check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR )
1066
1067 // Note: Design-By-Contract "require" macros are already defined elsewhere.
1068
1069 #if 0
1070 #pragma mark == Expect macros ==
1071 #endif
1072
1073
1074 // Expect macros
1075
1076
1077 // Expect macros allow code to include runtime checking of things that should not happen in shipping code (e.g. internal
1078 // programmer errors, such as a NULL parameter where it is not allowed). Once the code has been verified to work correctly
1079 // without asserting, the DEBUG_EXPECT_VERIFIED conditional can be set to eliminate the error checking entirely. It can
1080 // also be useful to measure the cost of error checking code by profiling with it enable and with it disabled.
1081
1082 #if ( DEBUG_EXPECT_VERIFIED )
1083 #define require_expect
1084 #define require_string_expect
1085 #define require_quiet_expect
1086 #define require_noerr_expect
1087 #define require_noerr_string_expect
1088 #define require_noerr_action_string_expect
1089 #define require_noerr_quiet_expect
1090 #define require_noerr_action_expect
1091 #define require_noerr_action_quiet_expect
1092 #define require_action_expect
1093 #define require_action_quiet_expect
1094 #define require_action_string_expect
1095 #else
1096 #define require_expect require
1097 #define require_string_expect require_string
1098 #define require_quiet_expect require_quiet
1099 #define require_noerr_expect require_noerr
1100 #define require_noerr_string_expect require_noerr_string
1101 #define require_noerr_action_string_expect require_noerr_action_string
1102 #define require_noerr_quiet_expect require_noerr_quiet
1103 #define require_noerr_action_expect require_noerr_action
1104 #define require_noerr_action_quiet_expect require_noerr_action_quiet
1105 #define require_action_expect require_action
1106 #define require_action_quiet_expect require_action_quiet
1107 #define require_action_string_expect require_action_string
1108 #endif
1109
1110 #if 0
1111 #pragma mark == Output macros ==
1112 #endif
1113
1114
1115 /*! @defined debug_string
1116
1117 @abstract Prints a debugging C string.
1118 */
1119
1120 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
1121 #undef debug_string
1122 #endif
1123 #if ( !defined( debug_string ) )
1124 #if ( DEBUG )
1125 #define debug_string( STR ) \
1126 do \
1127 { \
1128 debug_print_assert( 0, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \
1129 \
1130 } while( 0 )
1131 #else
1132 #define debug_string( STR )
1133 #endif
1134 #endif
1135
1136
1137 /*! @defined debug_print_assert
1138
1139 @abstract Prints an assertion.
1140 */
1141
1142 #if ( DEBUG )
1143 #define debug_print_assert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION ) \
1144 DebugPrintAssert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION )
1145 #else
1146 #define debug_print_assert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION )
1147 #endif
1148
1149
1150 /*! @defined dlog
1151
1152 @abstract Prints a debug-only message.
1153 */
1154
1155 #if ( DEBUG )
1156 #if ( DEBUG_C99_VA_ARGS )
1157 #define dlog(... ) DebugPrintF( __VA_ARGS__ )
1158 #elif ( DEBUG_GNU_VA_ARGS )
1159 #define dlog( ARGS... ) DebugPrintF( ## ARGS )
1160 #else
1161 #define dlog DebugPrintF
1162 #endif
1163 #else
1164 #if ( DEBUG_C99_VA_ARGS )
1165 #define dlog(... )
1166 #elif ( DEBUG_GNU_VA_ARGS )
1167 #define dlog( ARGS... )
1168 #else
1169 #define dlog while( 0 )
1170 #endif
1171 #endif
1172
1173
1174 /*! @defined dlogv
1175
1176 @abstract Prints a debug-only message.
1177 */
1178
1179 #if ( DEBUG )
1180 #define dlogv( LEVEL, FORMAT, LIST ) DebugPrintFVAList( ( LEVEL ), ( FORMAT ), ( LIST ) )
1181 #else
1182 #define dlogv( LEVEL, FORMAT, LIST )
1183 #endif
1184
1185
1186 /*! @defined dlogmem
1187
1188 @abstract Prints a debug-only dump of memory.
1189 */
1190
1191 #if ( DEBUG )
1192 #define dlogmem( LEVEL, PTR, SIZE ) \
1193 DebugHexDump( ( LEVEL ), 0, NULL, 0, 0, NULL, 0, ( PTR ), ( PTR ), ( SIZE ), kDebugFlagsNone, NULL, 0 )
1194 #else
1195 #define dlogmem( LEVEL, PTR, SIZE )
1196 #endif
1197
1198
1199 /*! @defined DebugNSLog
1200
1201 @abstract Debug-only macro for the Cocoa NSLog function.
1202 */
1203
1204 #if ( DEBUG )
1205 #if ( DEBUG_C99_VA_ARGS )
1206 #define DebugNSLog(... ) NSLog( __VA_ARGS__ )
1207 #elif ( DEBUG_GNU_VA_ARGS )
1208 #define DebugNSLog( ARGS... ) NSLog( ## ARGS )
1209 #else
1210 #define DebugNSLog NSLog
1211 #endif
1212 #else
1213 #if ( DEBUG_C99_VA_ARGS )
1214 #define DebugNSLog(... )
1215 #elif ( DEBUG_GNU_VA_ARGS )
1216 #define DebugNSLog( ARGS... )
1217 #else
1218 #define DebugNSLog while( 0 )
1219 #endif
1220 #endif
1221
1222
1223 /*! @defined DebugLogMsg
1224
1225 @abstract Debug-only macro for the VxWorks logMsg function.
1226 */
1227
1228 #if ( TARGET_OS_VXWORKS )
1229 #if ( DEBUG )
1230 #define DebugLogMsg( LEVEL, FORMAT, P1, P2, P3, P4, P5, P6 ) \
1231 do \
1232 { \
1233 if( ( inLevel >= gDebugPrintLevelMin ) || ( inLevel <= gDebugPrintLevelMax ) ) \
1234 { \
1235 logMsg( ( FORMAT ), ( P1 ), ( P2 ), ( P3 ), ( P4 ), ( P5 ), ( P6 ) ); \
1236 } \
1237 \
1238 } while( 0 )
1239 #else
1240 #define DebugLogMsg( LEVEL, FORMAT, P1, P2, P3, P4, P5, P6 )
1241 #endif
1242 #else
1243 #define DebugLogMsg dlog
1244 #endif
1245
1246 #if 0
1247 #pragma mark == Routines - General ==
1248 #endif
1249
1250 #ifdef __cplusplus
1251 extern "C" {
1252 #endif
1253
1254
1255 /*! @function DebugInitialize
1256
1257 @abstract Initializes the debugging library for a specific kind of output.
1258
1259 @param inType
1260 @param varArg Variable number parameters, controlled by the "inType" parameter.
1261 */
1262
1263 #if ( DEBUG )
1264 DEBUG_EXPORT OSStatus DebugInitialize( DebugOutputType inType, ... );
1265 #endif
1266
1267 #if ( DEBUG )
1268 #if ( DEBUG_C99_VA_ARGS )
1269 #define debug_initialize(... ) DebugInitialize( __VA_ARGS__ )
1270 #elif ( DEBUG_GNU_VA_ARGS )
1271 #define debug_initialize( ARGS... ) DebugInitialize( ## ARGS )
1272 #else
1273 #define debug_initialize DebugInitialize
1274 #endif
1275 #else
1276 #if ( DEBUG_C99_VA_ARGS )
1277 #define debug_initialize(... )
1278 #elif ( DEBUG_GNU_VA_ARGS )
1279 #define debug_initialize( ARGS... )
1280 #else
1281 #define debug_initialize while( 0 )
1282 #endif
1283 #endif
1284
1285
1286 /*! @function DebugFinalize
1287
1288 @abstract Releases any resources used by the debugging library
1289 */
1290
1291 #if ( DEBUG )
1292 DEBUG_EXPORT void DebugFinalize( void );
1293 #endif
1294
1295 #if ( DEBUG )
1296 #define debug_terminate() DebugFinalize()
1297 #else
1298 #define debug_terminate()
1299 #endif
1300
1301
1302 /*! @function DebugGetProperty
1303
1304 @abstract Gets the specified property from the debugging library.
1305 */
1306
1307 #if ( DEBUG )
1308 DEBUG_EXPORT OSStatus DebugGetProperty( DebugPropertyTag inTag, ... );
1309 #endif
1310
1311 #if ( DEBUG )
1312 #if ( DEBUG_C99_VA_ARGS )
1313 #define debug_get_property(... ) DebugGetProperty( __VA_ARGS__ )
1314 #elif ( DEBUG_GNU_VA_ARGS )
1315 #define debug_get_property( ARGS... ) DebugGetProperty( ## ARGS )
1316 #else
1317 #define debug_get_property DebugGetProperty
1318 #endif
1319 #else
1320 #if ( DEBUG_C99_VA_ARGS )
1321 #define debug_get_property(... )
1322 #elif ( DEBUG_GNU_VA_ARGS )
1323 #define debug_get_property( ARGS... )
1324 #else
1325 #define debug_get_property while( 0 )
1326 #endif
1327 #endif
1328
1329
1330 /*! @function DebugSetProperty
1331
1332 @abstract Sets the specified property from the debugging library.
1333 */
1334
1335 #if ( DEBUG )
1336 DEBUG_EXPORT OSStatus DebugSetProperty( DebugPropertyTag inTag, ... );
1337 #endif
1338
1339 #if ( DEBUG )
1340 #if ( DEBUG_C99_VA_ARGS )
1341 #define debug_set_property(... ) DebugSetProperty( __VA_ARGS__ )
1342 #elif ( DEBUG_GNU_VA_ARGS )
1343 #define debug_set_property( ARGS... ) DebugSetProperty( ## ARGS )
1344 #else
1345 #define debug_set_property DebugSetProperty
1346 #endif
1347 #else
1348 #if ( DEBUG_C99_VA_ARGS )
1349 #define debug_set_property(... )
1350 #elif ( DEBUG_GNU_VA_ARGS )
1351 #define debug_set_property( ARGS... )
1352 #else
1353 #define debug_set_property while( 0 )
1354 #endif
1355 #endif
1356
1357 #if 0
1358 #pragma mark == Routines - Debugging Output ==
1359 #endif
1360
1361
1362 /*! @function DebugPrintF
1363
1364 @abstract Prints a debug message with printf-style formatting.
1365
1366 @param inLevel Error that generated this assert or noErr.
1367
1368 @param inFormatString
1369 C string containing assertion text.
1370
1371 @param VAR_ARG
1372 Variable number of arguments depending on the format string.
1373
1374 @result Number of bytes printed or -1 on error.
1375 */
1376
1377 #if ( DEBUG )
1378 DEBUG_EXPORT size_t DebugPrintF( DebugLevel inLevel, const char *inFormat, ... );
1379 #endif
1380
1381
1382 /*! @function DebugPrintFVAList
1383
1384 @abstract va_list version of DebugPrintF. See DebugPrintF for more info.
1385 */
1386
1387 #if ( DEBUG )
1388 DEBUG_EXPORT size_t DebugPrintFVAList( DebugLevel inLevel, const char *inFormat, va_list inArgs );
1389 #endif
1390
1391
1392 /*! @function DebugPrintAssert
1393
1394 @abstract Prints a message describing the reason the (e.g. an assert failed), an optional error message,
1395 an optional source filename, an optional source line number.
1396
1397 @param inErrorCode Error that generated this assert or noErr.
1398 @param inAssertString C string containing assertion text.
1399 @param inMessage C string containing a message about the assert.
1400 @param inFileName C string containing path of file where the error occurred.
1401 @param inLineNumber Line number in source file where the error occurred.
1402 @param inFunction C string containing name of function where assert occurred.
1403
1404 @discussion
1405
1406 Example output:
1407
1408 [ASSERT] assert: "dataPtr != NULL" allocate memory for object failed
1409 [ASSERT] where: "MyFile.c", line 123, ("MyFunction")
1410
1411 OR
1412
1413 [ASSERT] error: -6728 (kNoMemoryErr)
1414 [ASSERT] where: "MyFile.c", line 123, ("MyFunction")
1415 */
1416
1417 #if ( DEBUG )
1418 DEBUG_EXPORT void
1419 DebugPrintAssert(
1420 int_least32_t inErrorCode,
1421 const char * inAssertString,
1422 const char * inMessage,
1423 const char * inFilename,
1424 int_least32_t inLineNumber,
1425 const char * inFunction );
1426 #endif
1427
1428 #if 0
1429 #pragma mark == Routines - Utilities ==
1430 #endif
1431
1432
1433 /*! @function DebugSNPrintF
1434
1435 @abstract Debugging versions of standard C snprintf with extra features.
1436
1437 @param sbuffer Buffer to receive result. Null terminated unless the buffer size is 0.
1438 @param buflen Size of the buffer including space for the null terminator.
1439 @param fmt printf-style format string.
1440 @param VAR_ARG Variable number of arguments depending on the format string.
1441
1442 @result Number of characters written (minus the null terminator).
1443
1444 @discussion
1445
1446 Extra features over the standard C snprintf:
1447 <pre>
1448 64-bit support for %d (%lld), %i (%lli), %u (%llu), %o (%llo), %x (%llx), and %b (%llb).
1449 %@ - Cocoa/CoreFoundation object. Param is the object. Strings are used directly. Others use CFCopyDescription.
1450 %a - Network Address: %.4a=IPv4, %.6a=Ethernet, %.8a Fibre Channel, %.16a=IPv6. Arg=ptr to network address.
1451 %#a - IPv4 or IPv6 mDNSAddr. Arg=ptr to mDNSAddr.
1452 %##a - IPv4 (if AF_INET defined) or IPv6 (if AF_INET6 defined) sockaddr. Arg=ptr to sockaddr.
1453 %b - Binary representation of integer (e.g. 01101011). Modifiers and arg=the same as %d, %x, etc.
1454 %C - Mac-style FourCharCode (e.g. 'APPL'). Arg=32-bit value to print as a Mac-style FourCharCode.
1455 %H - Hex Dump (e.g. "\x6b\xa7" -> "6B A7"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size.
1456 %#H - Hex Dump & ASCII (e.g. "\x41\x62" -> "6B A7 'Ab'"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size.
1457 %m - Error Message (e.g. 0 -> "kNoErr"). Modifiers and error code arg=the same as %d, %x, etc.
1458 %#s - Pascal-style length-prefixed string. Arg=ptr to string.
1459 %##s - DNS label-sequence name. Arg=ptr to name.
1460 %S - UTF-16 string, 0x0000 terminated. Host order if no BOM. Precision is UTF-16 count. Precision includes BOM.
1461 %#S - Big Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S.
1462 %##S - Little Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S.
1463 %U - Universally Unique Identifier (UUID) (e.g. 6ba7b810-9dad-11d1-80b4-00c04fd430c8). Arg=ptr to 16-byte UUID.
1464 </pre>
1465 */
1466
1467 #if ( DEBUG )
1468 DEBUG_EXPORT size_t DebugSNPrintF(char *sbuffer, size_t buflen, const char *fmt, ...);
1469 #endif
1470
1471
1472 /*! @function DebugSNPrintFVAList
1473
1474 @abstract va_list version of DebugSNPrintF. See DebugSNPrintF for more info.
1475 */
1476
1477 #if ( DEBUG )
1478 DEBUG_EXPORT size_t DebugSNPrintFVAList(char *sbuffer, size_t buflen, const char *fmt, va_list arg);
1479 #endif
1480
1481
1482 /*! @function DebugGetErrorString
1483
1484 @abstract Gets an error string from an error code.
1485
1486 @param inStatus Error code to get the string for.
1487 @param inBuffer Optional buffer to copy the string to for non-static strings. May be null.
1488 @param inBufferSize Size of optional buffer. May be 0.
1489
1490 @result C string containing error string for the error code. Guaranteed to be a valid, static string. If a
1491 buffer is supplied, the return value will always be a pointer to the supplied buffer, which will
1492 contain the best available description of the error code. If a buffer is not supplied, the return
1493 value will be the best available description of the error code that can be represented as a static
1494 string. This allows code that cannot use a temporary buffer to hold the result to still get a useful
1495 error string in most cases, but also allows code that can use a temporary buffer to get the best
1496 available description.
1497 */
1498
1499 #if ( DEBUG )
1500 DEBUG_EXPORT const char * DebugGetErrorString( int_least32_t inErrorCode, char *inBuffer, size_t inBufferSize );
1501 #endif
1502
1503
1504 /*! @function DebugHexDump
1505
1506 @abstract Hex dumps data to a string or to the output device.
1507 */
1508
1509 #if ( DEBUG )
1510 DEBUG_EXPORT size_t
1511 DebugHexDump(
1512 DebugLevel inLevel,
1513 int inIndent,
1514 const char * inLabel,
1515 size_t inLabelSize,
1516 int inLabelMinWidth,
1517 const char * inType,
1518 size_t inTypeSize,
1519 const void * inDataStart,
1520 const void * inData,
1521 size_t inDataSize,
1522 DebugFlags inFlags,
1523 char * outBuffer,
1524 size_t inBufferSize );
1525 #endif
1526
1527 #if ( DEBUG )
1528 #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE ) \
1529 DebugHexDump( ( LEVEL ), (INDENT), ( LABEL ), ( LABEL_SIZE ), ( LABEL_MIN_SIZE ), ( TYPE ), ( TYPE_SIZE ), \
1530 ( DATA_START ), ( DATA ), ( DATA_SIZE ), ( FLAGS ), ( BUFFER ), ( BUFFER_SIZE ) )
1531 #else
1532 #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE )
1533 #endif
1534
1535
1536 /*! @function DebugTaskLevel
1537
1538 @abstract Returns the current task level.
1539
1540 @result Current task level
1541
1542 @discussion
1543
1544 Bit masks to isolate portions of the result (note that some masks may also need bit shifts to right justify):
1545 <pre>
1546 kDebugInterruptLevelMask - Indicates the current interrupt level (> 0 means interrupt time).
1547 kDebugInVBLTaskMask - Indicates if a VBL task is currently being executed.
1548 kDebugInDeferredTaskMask - Indicates if a Deferred Task is currently being executed.
1549 kDebugInSecondaryInterruptHandlerMask - Indicates if a Secondary Interrupt Handler is currently being executed.
1550 kDebugPageFaultFatalMask - Indicates if it is unsafe to cause a page fault (worse than interrupt time).
1551 kDebugMPTaskLevelMask - Indicates if being called from an MP task.
1552 kDebugInterruptDepthMask - 0 means task level, 1 means in interrupt, > 1 means in nested interrupt.
1553 </pre>
1554
1555 Helpers:
1556 <pre>
1557 DebugExtractTaskLevelInterruptDepth() - Macro to extract interrupt depth from task level value.
1558 </pre>
1559 */
1560
1561 #if ( DEBUG )
1562 DEBUG_EXPORT uint32_t DebugTaskLevel( void );
1563 #endif
1564
1565
1566 /*! @function DebugServicesTest
1567
1568 @abstract Unit test.
1569 */
1570
1571 #if ( DEBUG )
1572 DEBUG_EXPORT OSStatus DebugServicesTest( void );
1573 #endif
1574
1575 #ifdef __cplusplus
1576 }
1577 #endif
1578
1579 #endif // __DEBUG_SERVICES__
FREE OFFICE SUITE