A system-level debugger tool for the Classic Mac OS. It sits dormant until something provokes it, and then it rises in full fury, stops all multitasking, takes over the screen, and gives you a nice little interface to do anything you want to memory. The interface is very dense (although, once you learn what to ignore, easy to grasp) and consists of several panels: one showing the name of the currently active application and the status of all the memory registers; one showing the status of the current procedure along with its name (assuming the program in question exported the required symbols, which it usually doesn't); and two panels (one for input, one for output) that form a command-line interface. Anyone who has never seen MacsBug before and then suddenly comes into contact with it on someone else's machine will probably be terrified by this sudden apparition, seeing as first off the screen will be filled with hexadecimal and second off they won't know how to get out.

MacsBug, once installed, can be entered into in a number of ways: if the programmers key (a button on the cases of a few, but not all, mac models) is pressed, if command-power is pressed (on pre-2001 macs), if command-cd eject is pressed (on post-2001 macs), if the program being run explicitly invokes a debugger, or if the program being run crashes. If MacsBug is invoked (by any method other than a crash) on a machine that does not have MacsBug installed, you will be dropped into the mini-debugger instead.

Once in MacsBug, you can do literally anything; invoke functions, kill the menubar, read any block of memory you want, write to any block of memory you want, anything.This is, of course, not to say you will be able to figure out how to do these things; just that it's theoretically possible. Most of the usefulness of macsbug comes when you are actually writing a program, in which case there are all sorts of nifty tools built in to help you step through compiled code and figure out what your program is doing at the moment. Otherwise, a few of the commands you will find useful for day-to-day use in Macsbug are:

  • ? - prints the helpfiles for macsbug to screen.
  • ? command - prints the part of the helpfiles relevant to a specific macsbug command to screen.
  • g - The most important command of all, as this is the command you use to exit MacsBug and continue as if nothing had happened. Note that this will not work if you have crashed, because you will essentially be leaving MacsBug and going right back into the crash. If you have crashed, you should probably try to use
  • es - "escape to shell", which is essentially the same thing as a force quit. However, it is a good bit more dependable than force quit, and will sometimes allow you to recover from a crash that force quit would not have. This is the reason most people install macsbug-- not because they are developers needing to debug, but because they want to force quit.
  • ea - "escape to application" - the same as es, except instead of trying to go to the Finder after force quitting it attempts to go to the nearest available application instead. This is probably what you should try to do if the Finder crashes, although a Finder crash is exceedingly rare these days. (Note: this command has been removed in recent versions of macsbug.)
  • stdlog - prints out a whole bunch of useful information into a file on the desktop named stdlog. The information-- status of memory registers, status of variables, currently running applications and extensions, etc-- tends to be extremely helpful to those who know how to decode it all in determining what exactly caused the crash and why. Thus, most mac applications in beta will come with a note requesting anyone who gets a crash to email an stdlog back to the application author.
  • log filename - will begin logging all MacsBug CLI output into the file filename until you type "log" with no commands to turn it off. This is mostly useful if you are using
  • dw address - "display word" - which reads a single memory address and prints its value to screen. Slightly more useful is
  • dm address quantity - "display memory" - which will display a block of memory of size quantity. Why is this handy? Well, lets say that you're writing something, and the program you're writing it in crashes. If you can immediately drop into macsbug, the text written will probably still be floating out there in memory somewhere, and if you can locate it, you can retrieve it using dm. The way you find it is
  • F address1 address2 'string' - searches for string between address1 and address2. If it finds it, returns where it found it.
So if MSIE crashes right now before i am able to submit this writeup, i could type
    log MacsBugNode
to begin logging,
    F 0 FFFFFFFF 'A [system-level] [debugger] tool for the'
to find my writeup in memory,
    dm (the address returned by the last command) 500
to print out that block of memory to the screen (and thus to the MacsBugNode file), and
to safely quit MSIE. Maybe not simple, but definitely a useful thing to know...