Symbolicating iOS and OS X Apps

Many of the errors that happen in Mac OS X and iOS apps don’t actually crash the app, they just dump a stack trace to the console. You can view these using the Console app — select the System Log and you’ll see all the messages the app sends to the console.

Unfortunately, these stack dumps can’t be directly used by the programmer to find the bug. With a little work, however, it’s possible to get right down to the line of code that caused the problem.

A stack trace will look like this:

Sep 13 19:04:32 Users-Mac.local PocketBible[727]: *** -[__NSCFString rangeOfString:options:range:locale:]: Range {3040, 18446744073709551600} out of bounds; string length 3504
Sep 13 19:04:32 Users-iMac.local PocketBible[727]: (
		0   CoreFoundation                      0x00007fff910e225c __exceptionPreprocess + 172
		1   libobjc.A.dylib                     0x00007fff96598e75 objc_exception_throw + 43
		2   CoreFoundation                      0x00007fff910e210c +[NSException raise:format:] + 204
		3   Foundation                          0x00007fff94074985 -[NSString rangeOfString:options:range:locale:] + 186
		4   Foundation                          0x00007fff940945b4 -[NSString rangeOfString:options:range:] + 29
		5   PocketBible                         0x00000001077cec78 PocketBible + 797816
		6   PocketBible                         0x000000010776c771 PocketBible + 395121
		7   PocketBible                         0x000000010776aa43 PocketBible + 387651
		8   AppKit                              0x00007fff92c84c38 -[NSTabView selectTabViewItem:] + 389
		9   AppKit                              0x00007fff92ff8b09 -[NSTabView mouseDown:] + 145
		10  AppKit                              0x00007fff92b76a58 -[NSWindow sendEvent:] + 11296
		11  AppKit                              0x00007fff92b155d4 -[NSApplication sendEvent:] + 2021
		12  AppKit                              0x00007fff929659f9 -[NSApplication run] + 646
		13  AppKit                              0x00007fff92950783 NSApplicationMain + 940
		14  PocketBible                         0x000000010770d244 PocketBible + 4676
		15  ???                                 0x0000000000000001 0x0 + 1
	)

The trick, of course, is to find the last bit of PocketBible code that was running when the error occurred. To do this, we need our symbol map. Fortunately, XCode archives that with our program and we can access those archives through the Organizer. So here’s what we need to do:

1. Create a working folder somewhere
2. Go into the Archive area of Organizer and select the archived version of the program from which the stack trace was created
3. Right-click and select Show In Finder
4. Right-click on the archive and select Show Package Contents
5. Copy the .dSYM file from the dSYMs folder into the working folder
6. Copy the application from Products/Applications into the working folder
7. In Terminal, go to the working folder

Now enter this command:

atos -o PocketBible.app/Contents/MacOS/PocketBible -arch x86_64 -l [load address] [target address]

To calculate [load addresses], subtract the offset you see on any PocketBible line from the address to its left. So looking at line 5, you would subtract 797816 (decimal) from 0x1077cec78 (hex) and get 0x10770c000. [target_address] is the address you see in the stack trace for the line you’re interested in (for example, 0x1077cec78 for line 5).

If you do it right, atos will tell you the object and method, plus the file and line number in the file corresponding to the line in the stack trace:

got symbolicator for PocketBible.app/Contents/MacOS/PocketBible, base address 100000000
-[NSString(HTMLTags) rangeOfHtmlTagInRange:] (in PocketBible) (NSString+HTMLTags.m:67)

Which sends us to NSString+HTMLTags.m, line 67.

If you want to enter several addresses, press enter after [load address]. You are then in “interactive mode” and can enter addresses and get results without leaving atos or re-entering all the other parameters. Press ^C to exit this mode.