Using MacsBug


MacsBug is a low-level debugger for 68k and PowerPC Macintosh computers. In basic terms, that means that it’s a bit of software that sits at a low level, and kicks in when a problem occurs.

Warning: playing with MacsBug may cause you to lose data in any running applications, and from it you can restart the computer. Don’t mess around with MacsBug with your unsaved 20-page report open in an application.

Obtaining MacsBug

You can download MacsBug from Apple’s servers here.

Installing MacsBug

Unstuff the downloaded archive with Stuffit Expander, if this has not already been done automatically. Drag the MacsBug file into the System Folder — it should just go in the System Folder itself, not in any sub-folders. This is the minimum you need to do. You can also move the ‘PowerPC dcmds’ file into a folder called ‘MacsBug Preferences’ in the ‘Preferences’ folder.

Now restart the computer. You should see the message ‘Debugger installed’ early in the startup process.


Once MacsBug is intalled, you can activate it (known as “dropping into MacsBug with a user break”) by pressing the Command-power key combination (hold down the command/clover/ apple key, and press the power-on key on the keyboard). MacsBug takes over the screen, showing you a black and white screen with a bunch of scarey-looking hex numbers. Don’t panic!

If you run your machine with MacsBug installed, you may also find that you get dumped into the debugger sometimes. This usually means that the software you are running has hit a bug that MacsBug has detected. If this happens, the safest option is to type ‘es’ to kill the current application, then restart the computer.

Some basic MacsBug commands are as follows:

help Help Show help. Type help <subtopic> for help on subtopic.
g Go Continue execution where it was interrupted
es Exit to shell Kill the current application
dx Debugger Exchange Turn user breaks on or off (toggles). Use this avoid invoking MacsBug when an application calls Debugger() or DebugStr().
sc Stack crawl Show the stack using A6/R1 links
sc7 Stack crawl Show return addresses on the stack
hc all Heap check all Check all heaps
hc Heap check Check the current heap
log <filename> Log file Write output of following commands to log file <filename>. Typing log again toggles the log off.
stdlog Standard log Write a log file containing general information usefulf for debugging a crash

Getting a log file for a crashing bug

If you experience a bug that causes crashes, use the following procedure to get a log file to send to tech support, or the author of the software that you think is causing the crash.

Install MacsBug as described above. (Of course you only need to do this once.) Run the software that causes the crash. At the point where it normally crashes, you will, hopefully, get dropped into MacsBug. You’ll know this because the screen changes to show lots of black and white text, with a row of numbers down the left. At this point, simply type ‘stdlog’ (without the quotes) and MacsBug will write a file called “stdlog” to the desktop. Now type ‘es’ to kill the errant application. It’s probably a good idea to restart your Mac at this point.

Now simply attach the stdlog file to an email to the software author.

More information

MacsBug is a much more sophisticated tool than I have suggested here, but using it requires extensive knowledge of low-level system software and hardware details. The following links may be useful if you want to develop your MacsBug expertise:

permalink | computing/archaic | 2007.11.19-22:31.00