TweetFollow Us on Twitter

Simple Call Stack Logging

Volume Number: 25
Issue Number: 06
Column Tag: Programming

Simple Call Stack Logging

Who called NSLog()?

by Sengan Baring-Gould

In this article I present an extension to NSLog() which not only prints out a user specified message but also lists the function calls that led to its invocation. By the end of this article you will have a new tool you can use in your own applications, and you'll understand how it works so that you can adapt it to your needs.

Why log?

NSLog() is an important tool for debugging. It can be placed anywhere in an application to log internal state.

Many programmers prefer logging to using a debugger, as it helps them concentrate on possible causes of a problem while filtering out irrelevant information. Logging provides a complete textual record of the problem that can be studied later.

Debuggers on the other hand interrupt the developer who must record by hand all the relevant state before letting the application continue. Continuing is an unforgiving operation: once performed, prior state that was not recorded is lost.

Brian W Kernighan (one of the authors of the seminal text on the C language) said:

"As a personal choice, we tend not to use debuggers beyond getting a stack trace or the value of a variable or two. One reason is that it is easy to get lost in details of complicated data structures and control flow; we find stepping through a program less productive than thinking harder and adding output statements and self-checking code at critical places. Clicking over statements takes longer than scanning the output of judiciously-placed displays. It takes less time to decide where to put print statements than to single-step to the critical section of code, even assuming we know where that is. More important, debugging statements stay with the program; debugger sessions are transient".

However, if NSLog() is invoked from a function that is called from many other functions, determining which function call caused the bug can be very difficult. We need a record of the function calls that led to the invocation of NSLog().

Where we are headed

Our new debug function debugLog() will print out any message we want the same way NSLog() does. Following the message, it will list the function invocations that led it to be called:

2009-04-05 15:37:58.119 TestDebugLog[14442:10b] C++ constructor
        0000301f — CPP::CPP() + 33             (TestDebugLog)
        0000316c — main + 86                   (TestDebugLog)
        00001a5e — start + 54                  (TestDebugLog)

The first line follows NSLog()'s traditional format: the date, the time, the name of the application (TestDebugLog) and then the message we passed as argument: "C++ Constructor".

On the next lines, debugLog() lists the function invocations that led it to be called:

  • debugLog() was called from the C++ constructor CPP::CPP() defined in TestDebugLog.
  • CPP:CPP() was called by main also defined in TestDebugLog.
  • main was called by start also defined in TestDebugLog. (start is the function the Operating System calls when it starts an application).

The module name between parentheses specifies where a function is defined. In the following example, NSPopAutoreleasePool is shown to be defined in the Foundation framework:

2009-04-05 15:40:03.921 TestDebugLog[14462:10b] Objective-C dealloc
        000030d3 — [Objc dealloc]  + 33        (TestDebugLog)
        91117e4f — NSPopAutoreleasePool + 431  (Foundation)
        000031d1 — main + 207                  (TestDebugLog)
        00001a4a — start + 54                  (TestDebugLog)

Obtaining the list of function invocations

Obtaining the list of function invocations to print is a two step process. First, debugLog() must obtain the addresses of the functions that called it. A computer uses addresses to keep track of what it is doing, but addresses are not specified in a program's source-code.

Then debugLog() must translate these addresses into the function names that appear in the program's source code. Three different methods are required to obtain C, C++, and Objective-C function names.

1. Retrieving the list of called functions' addresses

Compilers transform source-code into machine code that computers understand. When a function is called, the caller's return address must be saved so that the CPU can continue running the caller after the function invocation completes. In the context of this discussion, we will assume that these return addresses are stored on the stack. (We will ignore specific optimizations used by the PowerPC and x86 CPUs).

Unfortunately, the stack also records other information, such as local variables and function arguments. Determining precisely which items in the stack are return addresses requires compiler specific knowledge. Conveniently, the new version of gcc which ships with Leopard provides a new function, backtrace(), which gives us the return addresses in the current stack.

Remember that inlined functions are embedded within their callers rather than being invoked. This means backtrace will not see them in the stack and they will not be listed by debugLog().

2. Function layout in memory

Functions are compiled independently by the compiler and occupy contiguous areas of memory. Therefore if we know the starting addresses of any two consecutive functions f and g, and if we have an address x which falls between f and g ( &f <= x < &g ), we know that x belongs to the function f.

One rarely has addresses that match the beginning of each function precisely. Therefore function-lookup functions are designed to return information about the preceding function when given an address. Our case matches this scenario: the return addresses provided by backtrace occur within functions. Thus we can safely ignore the difference between return addresses and starting function addresses for most of this discussion. Similarly, we'll adopt the standard convention of referring to starting function addresses as function addresses.

3. Retrieving C function names

When an application is first loaded into memory, it needs to be told the addresses of the external library functions it wants to use. Because libraries are updated independently of applications, the addresses of their functions may change, although the names of their functions will not. It is the responsibility of the dynamic linker to give each application this information.

The dynamic linker reads function names from a symbol table embedded in the application and the libraries the application uses. The symbol table lists all the C function addresses and the C function names that can be accessed externally. Therefore if we know an address, we can ask the dynamic linker for the corresponding function name. The backtrace_symbols() function provides this functionality.

Because the dynamic linker only knows about externally visible function names, backtrace_symbols() always returns the nearest preceding external symbol. Static C functions are not exported and will not be given the correct name by the linker.

Most symbols will be exported as external if you compile your application in Debug Configuration. This is not true if you compile it in Release Configuration. The UNIX utility nm lists exported function names with a preceding capital T letting you check if an unexpected function name shows up.

4. Retrieving Objective-C method names

Objective-C does not use the dynamic linker. Instead it uses the Objective-C runtime, which like the dynamic linker keeps track of all known method addresses and names. (A method is a function defined within a class). However there is no equivalent to backtrace_symbols() which returns a function name when given a function address. We must build one ourselves.

The Objective-C runtime provides a function to enumerate all the Objective-C classes that can be invoked by the application, including those in the frameworks bound to the application. It also provides a function to enumerate the methods in any Objective-C class. With these components we can obtain every method's address and name.

Implementation

This code is Objective-C++ so don't forget to use the ".mm" extension for your implementation filename. We start with the necessary includes:

DebugLog Implementation File: SBGDebug.mm

#include "SBGDebug.h"
#include <cxxabi.h>
#include <map>
#include <string>
#include <execinfo.h>
#include <stdio.h>
#import <objc/Object.h>

1. Finding Objective-C methods

We want to build a method-lookup function that will return the method in which an address lies. We know how to enumerate the name and address of every Objective-C method available to the application, but this enumeration is expensive. Therefore we need a data structure in which to store the locations of the member functions.

The data structure must return the correct member function when queried with any address belonging to that member function. NSDictionary does not provide this functionality, but C++'s Standard Template Library's (STL) map container does.

map::upper_bound returns an iterator to the first element in the map whose key is larger than the queried key. For a map with method addresses as keys and method names as values, map::upper_bound will return an iterator pointing to the name of the method following the one we are looking for. Simply decrementing the iterator will make it point to the preceding method name.

// Lookup Function names
static std::map<uint32, std::string>* objectiveCMethodNames = NULL;
inline static uint32 lookupFunction(uint32 addr, const char** name)
{
   if (objectiveCMethodNames == NULL)
      return NULL;
     // Find the next function
   std::map<uint32, std::string>::iterator iter
      = objectiveCMethodNames->upper_bound( addr );
    // Go back a function: now we are looking at the right one!
   —iter;
   *name = iter->second.c_str();
   return iter->first;
}

Populating the STL map is a simple matter of iterating through all the classes known to the Objective-C runtime, and enumerating their methods.

// Add classes by stepping through their method lists.
inline static void  addObjectiveCMethod(uint32 addr, const char* name)
{   (*objectiveCMethodNames)[addr] = std::string(name); }
void addClass(Class c)
{
   unsigned int method_count;
   Method *method_list = class_copyMethodList(c, &method_count);
   for (int i = 0; i < method_count; i++)
   {
      Method      func = method_list[i];
      const char* name = sel_getName( method_getName( func ) );
      uint32      addr = (uint32) method_getImplementation( func );
      addObjectiveCMethod(   addr,
                           [[NSStringstringWith Format:@"[%s %s]",
                           class_getName(c), name] cString]);
   }
}

We could call the code that enumerates the Objective-C methods explicitly from main, but that requires remembering to add the call to each new application that uses debugLog(). Instead I can put the enumeration code into the load method of an Objective-C class which is guaranteed to be called if debugLog() is built into the application. The only gotcha is that the load method is invoked before Cocoa has created an NSAutoreleasePool. That's why the code below creates its own NSAutoreleasePool to avoid memory leaks.

@implementation SBGDebug
+ (void) load
{
   if (objectiveCMethodNames != NULL)
      return;
   NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init];
   objectiveCMethodNames = new std::map<uint32, std::string>();
   int numClasses = objc_getClassList(NULL, 0);
   if (numClasses > 0 )
   {
      Class *classes = (Class*) malloc(sizeof(Class) * numClasses);
      numClasses     = objc_getClassList(classes, numClasses);
      for (int i = 0; i < numClasses; ++i)
         addClass(classes[i]);
      free(classes);
   }
   [pool release];
}
@end

2. Deciding whether a function is C, C++ or Objective-C

The return addresses provided by backtrace() could belong to a C function, a C++ function or an Objective-C method. We need a way to decide which case we're dealing with. We start by asking both the C/C++ function-lookup function and the Objective-C method-lookup function to what function they believe a return address belongs. We will obtain two addresses a and b which should both be smaller than the return address r. Because functions are contiguous and do not intersect with each other, a and b must differ, and one of them must be lower than the other. For the same reason, the return address r cannot belong to the function with the lower address, as that function must end before the higher address. Therefore we use the name of the function that starts at the higher address:

extern "C" void debugLog(NSString* format, ...)
{
   // Print the debug message
   va_list arguments;
   va_start(arguments,format);
   NSLogv(format, arguments);
   // Dump the callstack
   uint32 callstack[128];
   int  frames = backtrace((void**) callstack, 128);
   char** strs = backtrace_symbols((void**) callstack, frames);
   for (int i = 1; i < frames; ++i)
   {
      char functionSymbol[64*1024];
      char moduleName    [64*1024];
      int  offset        = 0;
      sscanf(strs[i], "%*d %s %*s %s %*s %d", &moduleName,
                                       &functionSymbol, &offset);
      uint32 addr = callstack[i];
      if (objectiveCMethodNames)
      {
         const char* objcName;
         uint32      objcAddr = lookupFunction(addr, &objcName);
         if (      (objcAddr != 0)
               &&   (addr > objcAddr)
               &&   (addr - objcAddr < offset))
         {   printf("\t%8.8x — %s  + %d\t\t(%s)\n", addr, objcName,
                                             addr - objcAddr, moduleName);
            continue; };
      };
      int   validCppName;
      char* functionName = abi::__cxa_demangle(functionSymbol, NULL, 0,
                                                            &validCppName);
      if (validCppName == 0)
         printf(   "\t%8.8x — %s + %d\t\t(%s)\n",
                  addr, functionName, offset, moduleName);
      else
         printf(   "\t%8.8x — %s + %d\t\t(%s)\n",
                  addr, functionSymbol, offset, moduleName);
      if (functionName)
         free(functionName);
   }
   free(strs);
}

The output of backtrace_symbols() is an array of C-strings. We use sscanf() to parse them. The resulting function names are passed to the C++ demangler to convert into human-readable form if they are C++ names.

debugLog() uses printf() rather than NSLog() to avoid printing the application's name at the beginning of each line.

debugLog() is declared as extern "C" so it can be linked directly to Objective-C code. The class interface file does the same:

DebugLog Interface File: SBGDebug.h

@interface SBGDebug : NSObject
+ (void) load;
@end
#ifdef __cplusplus
extern "C" {
#endif
void debugLog(NSString* format, ...);
#ifdef __cplusplus
};
#endif

Using DebugLog

Invoke debugLog() just as you would NSLog():

Test file: TestDebugLog.mm

#import "SBGDebug.h"
// C++ test
struct CPP      { CPP(); ~CPP(); };
CPP::CPP()      { debugLog(@"C++ Constructor"); };
CPP::~CPP()   { debugLog(@"C++ Destructor"); };
// Objective C test
@interface Objc : NSObject
@end
@implementation Objc
- (id)      init
{ debugLog(@"Objective-C init"); return [super init]; };
(void)   dealloc
{ debugLog(@"Objective-C dealloc"); [super dealloc]; };
@end
// Main
int main(int argc, const char* argv[])
{
   NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init];
   CPP   cpp;
   Objc* objc = [[[Objc alloc] init] autorelease];
   debugLog(@"C — test arguments work too: %@", objc);
   [pool release];
   return 0;
}

Conclusion

Leopard provides all the components necessary to build a cross-platform NSLog() which can print function call traces. Although the code I provide assumes compilation to a 32-bit executable, extending it to 64 bits should be straightforward as only standard library functions are used.

You can download the entire Objective-C++ project from the MacTech ftp source archive at ftp.mactech.com/src/mactech/volume25_2009/25.06.sit.

Don't forget to compile it and run it in Debug Configuration!

References:

backtrace() : man backtrace.

backtrace_symbols() limitations : http://lists.apple.com/archives/darwin-dev/2009/Mar/msg00111.html.

backtrace_symbols() : man backtrace_symbols.

abi::__cxa_demangle : http://www.ib.cnea.gov.ar/~oop/biblio/libstdc++/namespaceabi.html.

Objective-C runtime: http://developer.apple.com/documentation/Cocoa/Reference/ObjCRuntimeRef/ObjCRuntimeRef.pdf.

The Standard Template Library: http://www.sgi.com/tech/stl/


Dr. Sengan Baring-Gould is a Boulder, Colorado-based independent Mac OS X developer and writer. He is available for consulting and specializes in Algorithms, AI, Cocoa, Debugging tools, High performance code, and UIs. He can be reached at sengan@ansemond.com.

 
AAPL
$102.64
Apple Inc.
+1.58
MSFT
$46.56
Microsoft Corpora
-0.50
GOOG
$581.13
Google Inc.
-6.24

MacTech Search:
Community Search:

Software Updates via MacUpdate

GarageSale 6.8 - Create outstanding eBay...
GarageSale is a slick, full-featured client application for the eBay online auction system. Create and manage your auctions with ease. With GarageSale, you can create, edit, track, and manage... Read more
ScreenFlow 4.5.3 - Create screen recordi...
Save 5% with the MacUpdate coupon code: 68031AE15F -- Buy now! ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your entire... Read more
NeoOffice 2014.3 - Mac-tailored, OpenOff...
NeoOffice is a complete office suite for OS X. With NeoOffice, users can view, edit, and save OpenOffice documents, PDF files, and most Microsoft Word, Excel, and PowerPoint documents. NeoOffice 3.x... Read more
Typinator 6.2 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
PopChar X 6.7 - Floating window shows av...
PopChar X helps you get the most out of your font collection. With its crystal-clear interface, PopChar X provides a frustration-free way to access any font's special characters. Expanded... Read more
Evernote 5.6.0 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
Monosnap 2.2.2 - Versatile screenshot ut...
Monosnap allows you to save screenshots easily, conveniently, and quickly, sharing them with friends and colleagues at once. It's the ideal choice for anyone who is looking for a smart and fast... Read more
Tunnelblick 3.4beta36 - GUI for OpenVPN...
Tunnelblick is a free, open source graphic user interface for OpenVPN on OS X. It provides easy control of OpenVPN client and/or server connections. It comes as a ready-to-use application with all... Read more
SoftRAID 5.0.4 - High-quality RAID manag...
SoftRAID allows you to create and manage disk arrays to increase performance and reliability. SoftRAID's intuitive interface and powerful feature set makes this utility a must have for any Mac OS X... Read more
Audio Hijack Pro 2.11.3 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more

Latest Forum Discussions

See All

Manual – Custom exposure camera (Photog...
Manual – Custom exposure camera 1.0 Device: iOS iPhone Category: Photography Price: $1.99, Version: 1.0 (iTunes) Description: Custom exposure for your iPhone camera. A powerful camera app with full control over your image. Quickly... | Read more »
Why I Don’t Want to Upgrade to the iPhon...
I’ve been living with my iPhone 4S for the past two years or so, and if I was living in a world where I wasn’t bombarded with new phone announcements and people of the general public caring enough to upgrade constantly, I wouldn’t think my phone... | Read more »
Tictail Review
Tictail Review By Jennifer Allen on September 23rd, 2014 Our Rating: :: CLASSY SHOPPINGiPhone App - Designed for the iPhone, compatible with the iPad Tictail is an attractive and stylish way of looking for some great new clothes... | Read more »
Super Glyph Quest is Bringing More Match...
Super Glyph Quest is Bringing More Match-3 Magics to the App Store Soon Posted by Jessica Fisher on September 23rd, 2014 [ permalink ] Fans of Glyph Quest, by Alex Trowers and Leanne Bayley, | Read more »
Sword King Review
Sword King Review By Jennifer Allen on September 23rd, 2014 Our Rating: :: WEAK, SO WEAKUniversal App - Designed for iPhone and iPad Ever wanted to tap on a screen and assume you’ve killed a monster or two? Probably not, but just... | Read more »
Pangea Software Unveil Bundles and iOS 8...
Pangea Software Unveil Bundles and iOS 8 Updates Posted by Ellis Spice on September 23rd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Race Team Manager Review
Race Team Manager Review By Jennifer Allen on September 23rd, 2014 Our Rating: :: LIGHT RACINGUniversal App - Designed for iPhone and iPad Want to be in charge of a racing team but not be overwhelmed by tactics and options? Race... | Read more »
Kobojo Works with Creative Minds from Fi...
Kobojo has announced details for their newest game, Zodiac – a 2D persistent online RPG. Kobojo has put together a crack team of developers including composer Hitoshi Sakimoto and scenario writer Kazushige Nojima, whose work includes many of the... | Read more »
PlayHaus Review
PlayHaus Review By Amy Solomon on September 23rd, 2014 Our Rating: iPad Only App - Designed for the iPad PlayHaus is a interesting, stylish app for young children, full of cause-and-effect interactions.   | Read more »
Astropolo Review
Astropolo Review By Amy Solomon on September 23rd, 2014 Our Rating: Universal App - Designed for iPhone and iPad Astropolo is a space-themed children’s app with a great sense of style.   | Read more »

Price Scanner via MacPrices.net

Razer DeathAdder Chroma Gaming Mouse Upgraded...
Razer has announced the launch of their new Razer DeathAdder Chroma gaming mouse. Even if you’re not a gamer, the DeathAdder bears considering. I’m a fan of the hard-wired tracking accuracy,... Read more
Check Apple prices on your device with iTracx
MacPrices is proud to offer readers a free iOS app (iPhones, iPads, & iPod touch) and Android app (Google Play and Amazon App Store) called iTracx, which allows you to glance at today’s lowest... Read more
Refurbished 2013 MacBook Pros available for u...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available starting at $929. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros (4GB RAM/... Read more
New iPhones Score Big in SquareTrade Breakabi...
SquareTrade has announced the iPhone 6 and its larger sibling, iPhone 6 Plus, performed impressively in Breakability testing, and each carries the top Breakability Score in their respective category... Read more
10 Million + First Weekend Sales Set New iPho...
Apple has announced it sold over 10 million new iPhone 6 and iPhone 6 Plus models, a new record, just three days after the launch on September 19. iPhone 6 and iPhone 6 Plus are now available in the... Read more
Betty Crocker Launches New Cookbook for iOS
Betty Crocker, a General Mills brand, an established food industry leader, has announced its free digital cookbook app has been refreshed to make cooking with iPhone, iPad and iPod touch even easier... Read more
Apple restocks some refurbished 2014 MacBook...
The Apple Store has restocked some Apple Certified Refurbished 2014 MacBook Airs, with prices starting at $769. An Apple one-year warranty is included with each MacBook, and shipping is free. These... Read more
13-inch 128GB MacBook Air on sale for $949, s...
B&H Photo has the new 2014 13″ 1.4GHz/128GB MacBook Air on sale for $949.99 including free shipping plus NY tax only. Their price is $50 off MSRP. B&H will also include free copies of... Read more
Apple offering free $25 iTunes Gift Card with...
The Apple Store is offering a free $25 iTunes Gift Card with the purchase of a $99 Apple TV for a limited time. Shipping is free. Read more
Apple refurbished iPod touch available for up...
The Apple Store has Apple Certified Refurbished 5th generation iPod touches available starting at $149. Apple’s one-year warranty is included with each model, and shipping is free. Most colors are... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.