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

  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
 19#import <Foundation/Foundation.h>
 20#import "GTMDefines.h"
 21
 22#ifdef __cplusplus
 23extern "C" {
 24#endif
 25
 26struct GTMAddressDescriptor {
 27  const void *address;  // address
 28  const char *symbol;  // nearest symbol to address
 29  const char *class_name;  // if it is an obj-c method, the method's class
 30  BOOL is_class_method;  // if it is an obj-c method, type of method
 31  const char *filename;  // file that the method came from.
 32};
 33
 34// Returns a string containing a nicely formatted stack trace.
 35// 
 36// This function gets the stack trace for the current thread. It will
 37// be from the caller of GTMStackTrace upwards to the top the calling stack.
 38// Typically this function will be used along with some logging, 
 39// as in the following:
 40//
 41//   MyAppLogger(@"Should never get here:\n%@", GTMStackTrace());
 42//
 43// Here is a sample stack trace returned from this function:
 44//
 45// #0  0x00002d92 D ()  [/Users/me/./StackLog]
 46// #1  0x00002e45 C ()  [/Users/me/./StackLog]
 47// #2  0x00002e53 B ()  [/Users/me/./StackLog]
 48// #3  0x00002e61 A ()  [/Users/me/./StackLog]
 49// #4  0x00002e6f main ()  [/Users/me/./StackLog]
 50// #5  0x00002692 tart ()  [/Users/me/./StackLog]
 51// #6  0x000025b9 tart ()  [/Users/me/./StackLog]
 52//
 53
 54NSString *GTMStackTrace(void);
 55
 56#if MAC_OS_X_VERSION_MIN_REQUIRED >= MAC_OS_X_VERSION_10_5 || \
 57    __IPHONE_OS_VERSION_MIN_REQUIRED >= __IPHONE_2_0
 58// Returns a string containing a nicely formatted stack trace from the
 59// exception.  Only available on 10.5 or later, uses 
 60// -[NSException callStackReturnAddresses].
 61//
 62NSString *GTMStackTraceFromException(NSException *e);
 63#endif
 64
 65#if MAC_OS_X_VERSION_MIN_REQUIRED < MAC_OS_X_VERSION_10_5
 66// Returns an array of program counters from the current thread's stack.
 67// *** You should probably use GTMStackTrace() instead of this function ***
 68// However, if you actually want all the PCs in "void *" form, then this
 69// funtion is more convenient. This will include PCs of GTMStaceTrace and
 70// its inner utility functions that you may want to strip out.
 71//
 72// You can use +[NSThread callStackReturnAddresses] in 10.5 or later.
 73//
 74// Args:
 75//   outPcs - an array of "void *" pointers to the program counters found on the
 76//            current thread's stack.
 77//   count - the number of entries in the outPcs array
 78//
 79// Returns:
 80//   The number of program counters actually added to outPcs.
 81//
 82NSUInteger GTMGetStackProgramCounters(void *outPcs[], NSUInteger count);
 83#endif  // MAC_OS_X_VERSION_MIN_REQUIRED < MAC_OS_X_VERSION_10_5
 84
 85// Returns an array of GTMAddressDescriptors from the current thread's stack.
 86// *** You should probably use GTMStackTrace() instead of this function ***
 87// However, if you actually want all the PCs with symbols, this is the way
 88// to get them. There is no memory allocations done, so no clean up is required
 89// except for the caller to free outDescs if they allocated it themselves.
 90// This will include PCs of GTMStaceTrace and its inner utility functions that 
 91// you may want to strip out.
 92//
 93// Args:
 94//   outDescs - an array of "struct GTMAddressDescriptor" pointers corresponding
 95//              to the program counters found on the current thread's stack.
 96//   count - the number of entries in the outDescs array
 97//
 98// Returns:
 99//   The number of program counters actually added to outPcs.
100//
101NSUInteger GTMGetStackAddressDescriptors(struct GTMAddressDescriptor outDescs[], 
102                                         NSUInteger count);
103
104#ifdef __cplusplus
105}
106#endif