Hide full article
Here's a fun game: let's plot Macintosh software on a map of the Earth, based on how Mac-like the software is.
We would naturally plot the points representing the easiest, most intuitive software for the Mac OS at Apple headquarters in Cupertino, California. As we plotted more points, we'd find the surrounding San Francisco area would be peppered with thousands of dots, each representing a Macintosh program. In fact, most Macintosh software - even hard-to-learn programs or obtuse, cryptic utilities meant for power users - could be plotted within, say, a few thousand miles of Cupertino. That's not the kind of travel you'd undertake without packing a toothbrush and some clean underwear, but, for many people, getting there is at least conceivable in today's world.
However, on the opposite side of the globe, well south of Mauritius in the Indian Ocean, we would find a dot representing MacsBug.
MacsBug is Apple's low-level assembly language Macintosh debugger. If I remember correctly, MacsBug stands for "Motorola Advanced Computer System Debugger" and predates the Macintosh, first appearing in 1981. There's nothing Mac-like about MacsBug: it has no menu bar, no menus, no windows, no icons, no dialogs, and no buttons. Its display is a jumble of numbers, letters, and some cryptic words. You communicate with MacsBug using a command line, precisely the thing many people sought to escape with the Mac. MacsBug doesn't provide intuitive feedback about practically anything - in short, MacsBug violates every aspect of the Macintosh ideal.
MacsBug breaks these rules because it was designed to live underneath the Macintosh system software so programmers can see what's going on in overwhelming detail. MacsBug provides direct access to things users were never meant to see: system globals, application heap zones, CPU registers, task queues, and executing code.
Sounds scary, right? It is. But MacsBug is powerful, and power is seductive. Mastering MacsBug would require most Macintosh users to apply for passports and visas, receive immunizations and inoculations, make expensive travel arrangements, endure radical culture shock, leave their real lives, and maybe even grow gills. However, you can benefit from MacsBug without travelling to the other side of the world (or learning to read assembly language). MacsBug's not for everybody, but if you've been willing to travel from Cupertino to, say, Ohio, for another Macintosh program (like DeBabelizer or ResEdit), you should be able to put MacsBug to work for you. MacsBug can provide detailed information about your computer and problems you might be having, and - perhaps most significantly - save work in other applications when an otherwise fatal system error occurs.
Installing MacsBug -- You can download MacsBug for free from Apple. I recommend the most recent version available - even if it's not a final release - because it's likely to work with the latest versions of the Mac OS. You can also download a PDF version of Apple's pre-PowerPC MacsBug documentation, which makes for interesting reading if you're curious about MacsBug's more abstruse capabilities. As of this writing, the current version of MacsBug is 6.5.4.a6.
<http://developer.apple.com/dev/tools/debuggers/ MacsBug/>
You install MacsBug by dragging it into your System Folder and restarting your Mac (feel free to ignore other files that come with it). Your Mac OS startup screen will say "Debugger installed" to let you know MacsBug is there. MacsBug works with any Mac newer than the Mac Plus and System 6.0 or higher; it might even work with earlier system software. Although for years MacsBug occupied only a few hundred kilobytes of RAM, changes to the Macintosh architecture over the last few years mean MacsBug commonly requires 1 to 1.5 MB of RAM on modern Macs.
Recent versions of MacsBug come with a program called MacsBugApp, which, despite limitations, is a stand-alone application that behaves much like MacsBug itself. It's occasionally flaky, but you can use it to follow along with some of the examples below without installing MacsBug itself.
Invoking MacsBug -- Once you've installed MacsBug, you might wonder where it is - nothing on your screen changes. There are two ways to enter MacsBug: deliberately and dramatically.
To enter MacsBug deliberately, press Command-Power, where Power is the key you use to turn on your Mac from the keyboard. This combination works on most Macs; older Macintosh models (up to the NuBus Power Macs, I believe) may also have a physical interrupt switch on the front, side, or back of the machine. If you've ever pressed a switch and seen a mysterious dialog containing only a greater-than symbol (">"), that's the interrupt switch. (By the way, that dialog is referred to as MicroBug or the programmer's window; to get out, your best bet is to type the letter G and press Return. You'll never see MicroBug with MacsBug installed, but Apple has a brief TechNote about it if you're curious.)
<http://developer.apple.com/technotes/tn/ tn1136.html>
You can also invoke MacsBug by holding down the Control key when your Mac starts up. Only programmers typically need to do this, but I was once surprised by an old keyboard with sticky modifier keys.
The dramatic way to enter MacsBug is to experience a system error. Normally, a system error produces a bomb dialog, or a program quits, resulting in a dialog saying "An error of type -1 occurred." or something equally unhelpful. Now, MacsBug instantaneously appears, completely taking over your startup monitor. You need to be careful about how you exit MacsBug in response to a system error; your options are covered below.
First, let's describe MacsBug's display - it's divided into four areas. At the bottom is the command line, where you type MacsBug commands. Immediately above the command line is the PC region: PC stands for "program counter," and it displays the next instruction the CPU will execute, along with the disassembly of that instruction. This information is for programmers: it can give you an idea of where a system error occurred, but things like instruction pipelining (where the CPU executes more than one instruction at a time) sometimes mean the PC may not point to the actual error. Programmers sometimes need to disassemble forward and backward from the current PC to find the problem.
The largest area of the MacsBug display is called the output region, and it's where MacsBug shows the results of your commands. Although it doesn't have scrollbars, the Page Up, Page Down, Home, and End keys do scroll the output region's history. When you first enter MacsBug, it displays the version and copyright information in the output region, along with the reason MacsBug was entered.
Finally, along the entire left side of the MacsBug display is the status region, most of which displays CPU registers (R0 to R31 for PowerPC code, D0 to D7 and A0 to A7 for 68K code), along with the current stack pointer and, for 68K code, the stack itself. Don't worry about the stack and CPU registers. In the middle of all this, however, is some important information: beneath the label CurAppName, MacsBug shows the name of the currently executing application. If you entered MacsBug because of a system error, this is the program that had control when the error occurred, although it may not be the program you were using. Programs continue to execute when they aren't frontmost, and many things we think of as extensions - like Web Sharing and File Sharing - are in fact faceless applications that run in the background. Further, although CurAppName always says what program was in control when a problem occurred, the real problem could be in an extension, driver, or other software that underlies an application.
Near CurAppName, MacsBug also displays VM if you're using virtual memory, vM to indicate MacsBug was invoked while the Memory Manager was swapping between real and virtual memory, or RM to show you're using real memory. MacsBug also shows a number from 0 to 7 that indicates the interrupt level before MacsBug was invoked. Interrupts tell your CPU to set aside whatever it's doing and immediately take up a more important operation - they're used to handle mouse actions, screen redraws, network activity, serial port operations, and many other functions. MacsBug itself takes control of your system by generating a level 7 interrupt, otherwise known as a Non-Maskable Interrupt or NMI. (If you enter MacsBug deliberately, it tells you that the reason is an NMI rather than a system error.) An NMI overrides everything and can't be interrupted by other tasks. Generally, this isn't a problem: your applications aren't even aware they've been suspended. However, other computers on a network can notice that your Mac is no longer responding. After a few minutes, AppleShare servers will assume your Mac is gone and drop their connections; similarly, Internet servers might drop connections, and ISPs might hang up on you.
Stop This Crazy Thing! Now that you're in MacsBug, the first thing most sensible people want to do is get out. If you invoked MacsBug deliberately, this is simple: just type G then press Return, or press Command-G. This stands for Go, and tells your Mac to resume operating right where it left off. MacsBug then vanishes, your Mac's normal display reappears, and your Macintosh universe resumes its normal, harmonious state.
If you entered MacsBug as the result of a system error, try the following options. First, under CurAppName in the status region, note the name of the program executing when the error occurred. Also look at the bottom of the output region for the reason MacsBug was triggered. It might say something like "bus error" or "illegal instruction." If you need to see what you were doing on screen when the error occurred, pressing Escape toggles between your normal Macintosh display and MacsBug. Don't become confused: pressing Escape doesn't exit MacsBug, it just shows your screen at the instant MacsBug was triggered, which can be handy for writing down that paragraph of erudition that you otherwise stand no chance of recreating. Press Escape again to return to MacsBug.
Next, try typing G then pressing Return, or pressing Command-G. Most likely, you'll immediately reenter MacsBug with the same error, but it's worth a shot.
Type ES then press Return. ES stands for Exit to Shell, and tells MacsBug to terminate the current application and return you to the Finder. This is roughly equivalent to forcing an application to quit by pressing Command-Option-Escape. You may have to try ES a few times - just make sure you check which program is currently executing before repeating the command. If ES returns you to the Finder, save all your work and restart. If an application appears to have locked up, you can enter MacsBug intentionally and use ES to terminate that program. Use this capability with discretion, however: there's no telling what might be left in your computer's memory, whether any files that program had open will be closed properly, whether preferences might be damaged, etc. If you do this, restart as soon as possible.
If none of these techniques work - you keep popping into MacsBug with a system error - you may have no choice but to restart, even though it means losing unsaved work. You do this by typing RB (for ReBoot), then pressing Return. The RB command unmounts your startup volume and then restarts the machine. If you have multiple volumes, this action can result in delays the next time you need to use those disks: since they weren't properly unmounted, the Mac makes sure they're okay before mounting them on the desktop. You can alternatively use the RS command (for ReStart) to unmount all drives, then restart the system. Some programmers may tell you the RS command is dangerous, since it could write corrupted volume information back to your drives, potentially leading to data loss or a session with a disk recovery tool. In my experience, everyday problems with the RS command are quite rare, and changes to both the RS and RB commands in recent versions of MacsBug reduce the danger further. However, either command is preferable to turning your computer off and on.
Note that there are crashes from which MacsBug can't save you, and there are crashes that will still freeze your Mac, failing to invoke MacsBug at all. (The latter are often caused by poor or non-existent error checking when a program is low on memory.) In these cases, MacsBug can't help you, but having it installed doesn't hurt.
Impress Your Friends -- Now that you can get into and out of MacsBug, let's look at some simple tricks to enhance your guru status.
Being a low-level programmer's tool, MacsBug's default numbering system is base 16, or hexadecimal. Hexadecimal digits run from zero to fifteen, with ten through fifteen represented by the letters A through F. So, the number 200 is written as C8 in hexadecimal, which means "twelve times sixteen, plus eight." Hexadecimal is useful for representing binary values, and if you've done much HTML authoring, you've seen six-digit hexadecimal values like 3366CC used to specify colors. This might be wonderful from MacsBug's point of view, but hexadecimal isn't intuitive for people like me who have trouble making change for a dollar. Fortunately, you can tell MacsBug a number is a normal decimal number by preceding it with a pound symbol ("#"). Thus, if you type 42, MacsBug sees it as hexadecimal and thinks you mean 66 (four times sixteen, plus two), but if you type #42, MacsBug thinks you mean 42.
One instance where this esoteric knowledge becomes practical is in conjunction with MacsBug's error command, which returns a short description of cryptic Mac OS error numbers. If a program complains that "an error -43 occurred" you can identify the error number by popping into MacsBug, typing "error #-43", and pressing Return:
$FFD5 #-43 fnfErr - File not found
The application is telling you it tried to open a file, but couldn't find it. Depending on the program, this might be caused by a missing extension, plug-in, or document, but at least it gives you something to go by. The error command can score big points: I once got a frantic call from a small business owner who had an AppleScript that essentially looked up records in a database and printed a variety of labels. "I think it has corrupted the hard drive! Every time I need to use the machine, it says there's an error -1711 - big error numbers are really bad, right?" So, assuring the caller that the number of digits in an error has nothing to do with its severity, I popped into MacsBug and looked up the number:
$F951 #-1711 errAEWaitCanceled - in AESend, the user cancelled
out of wait loop for reply or receipt
It turned out this script had been designed to run overnight, since it spent most of its time waiting around for other applications. However, the script was instead being run during lunch breaks and other odd times. Whenever someone needed to use the machine, they pressed Command-Period to stop the script, which promptly produced this error. The situation was harmless, but in this case having MacsBug installed helped me reduce my caller's blood pressure and gave me a low-stress consulting job fixing the script.
You can also use MacsBug to convert between decimal and hexadecimal, which can be useful with other MacsBug commands. Since MacsBug assumes numbers are hexadecimal; entering "3366CC" on MacsBug's command line yields this result:
3366cc = $003366CC #3368652 #3368652 '*3fA' (between #3M and #4M)
This shows the number 3366CC as a hexadecimal value, an unsigned decimal value, a signed decimal value, an ASCII value, and (often) a semi-human-friendly conversion to memory units, in this case between three and four megabytes. If you're converting from hexadecimal to decimal, the number you want is the third - the signed ASCII value (notice that it's preceded with a pound sign). Thus, 3366CC in hexadecimal is equal to 3,368,652 in decimal. The second (unsigned) decimal value will be identical for non-negative numbers, but wildly different for negative numbers. Convert #-43 and see what you get. You can use this trick to convert numbers up to about 2.1 billion.
Recent versions of MacsBug include basic mouse support in the output region, enabling you to click on a word, number, or term in order to place it in the command line. Although this mouse support drives some programmers insane (say, if the mouse moves while debugging a problem with a pop-up menu), you can quickly convert a number from hexadecimal to decimal by clicking it and pressing Return.
Finally, you can do math using MacsBug - try entering 32 + 32, or #32 + #32. Programmers occasionally rave about this capability, since they often need to play with hexadecimal values after an application has crashed. But most people should stick to the Calculator desk accessory.
Break Point -- In the next part of this article, we'll look at some MacsBug commands that provide important information about your computer and applications, and how to make MacsBug automatically restart your computer if an application crashes, which can be great for unattended servers.
