/core/externals/google-toolbox-for-mac/Foundation/GTMStackTrace.h

http://macfuse.googlecode.com/ · C Header · 106 lines · 25 code · 9 blank · 72 comment · 1 complexity · 8c69606ec1bfe2f67dde7c7e7557abc5 MD5 · raw file

  1. //
  2. // GTMStackTrace.h
  3. //
  4. // Copyright 2007-2008 Google Inc.
  5. //
  6. // Licensed under the Apache License, Version 2.0 (the "License"); you may not
  7. // use this file except in compliance with the License. You may obtain a copy
  8. // of the License at
  9. //
  10. // http://www.apache.org/licenses/LICENSE-2.0
  11. //
  12. // Unless required by applicable law or agreed to in writing, software
  13. // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  14. // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  15. // License for the specific language governing permissions and limitations under
  16. // the License.
  17. //
  18. #import <Foundation/Foundation.h>
  19. #import "GTMDefines.h"
  20. #ifdef __cplusplus
  21. extern "C" {
  22. #endif
  23. struct GTMAddressDescriptor {
  24. const void *address; // address
  25. const char *symbol; // nearest symbol to address
  26. const char *class_name; // if it is an obj-c method, the method's class
  27. BOOL is_class_method; // if it is an obj-c method, type of method
  28. const char *filename; // file that the method came from.
  29. };
  30. // Returns a string containing a nicely formatted stack trace.
  31. //
  32. // This function gets the stack trace for the current thread. It will
  33. // be from the caller of GTMStackTrace upwards to the top the calling stack.
  34. // Typically this function will be used along with some logging,
  35. // as in the following:
  36. //
  37. // MyAppLogger(@"Should never get here:\n%@", GTMStackTrace());
  38. //
  39. // Here is a sample stack trace returned from this function:
  40. //
  41. // #0 0x00002d92 D () [/Users/me/./StackLog]
  42. // #1 0x00002e45 C () [/Users/me/./StackLog]
  43. // #2 0x00002e53 B () [/Users/me/./StackLog]
  44. // #3 0x00002e61 A () [/Users/me/./StackLog]
  45. // #4 0x00002e6f main () [/Users/me/./StackLog]
  46. // #5 0x00002692 tart () [/Users/me/./StackLog]
  47. // #6 0x000025b9 tart () [/Users/me/./StackLog]
  48. //
  49. NSString *GTMStackTrace(void);
  50. #if MAC_OS_X_VERSION_MIN_REQUIRED >= MAC_OS_X_VERSION_10_5 || \
  51. __IPHONE_OS_VERSION_MIN_REQUIRED >= __IPHONE_2_0
  52. // Returns a string containing a nicely formatted stack trace from the
  53. // exception. Only available on 10.5 or later, uses
  54. // -[NSException callStackReturnAddresses].
  55. //
  56. NSString *GTMStackTraceFromException(NSException *e);
  57. #endif
  58. #if MAC_OS_X_VERSION_MIN_REQUIRED < MAC_OS_X_VERSION_10_5
  59. // Returns an array of program counters from the current thread's stack.
  60. // *** You should probably use GTMStackTrace() instead of this function ***
  61. // However, if you actually want all the PCs in "void *" form, then this
  62. // funtion is more convenient. This will include PCs of GTMStaceTrace and
  63. // its inner utility functions that you may want to strip out.
  64. //
  65. // You can use +[NSThread callStackReturnAddresses] in 10.5 or later.
  66. //
  67. // Args:
  68. // outPcs - an array of "void *" pointers to the program counters found on the
  69. // current thread's stack.
  70. // count - the number of entries in the outPcs array
  71. //
  72. // Returns:
  73. // The number of program counters actually added to outPcs.
  74. //
  75. NSUInteger GTMGetStackProgramCounters(void *outPcs[], NSUInteger count);
  76. #endif // MAC_OS_X_VERSION_MIN_REQUIRED < MAC_OS_X_VERSION_10_5
  77. // Returns an array of GTMAddressDescriptors from the current thread's stack.
  78. // *** You should probably use GTMStackTrace() instead of this function ***
  79. // However, if you actually want all the PCs with symbols, this is the way
  80. // to get them. There is no memory allocations done, so no clean up is required
  81. // except for the caller to free outDescs if they allocated it themselves.
  82. // This will include PCs of GTMStaceTrace and its inner utility functions that
  83. // you may want to strip out.
  84. //
  85. // Args:
  86. // outDescs - an array of "struct GTMAddressDescriptor" pointers corresponding
  87. // to the program counters found on the current thread's stack.
  88. // count - the number of entries in the outDescs array
  89. //
  90. // Returns:
  91. // The number of program counters actually added to outPcs.
  92. //
  93. NSUInteger GTMGetStackAddressDescriptors(struct GTMAddressDescriptor outDescs[],
  94. NSUInteger count);
  95. #ifdef __cplusplus
  96. }
  97. #endif