Cool MacsBug Tricks (an informal guide),
fourth edition

By Macneil Shonle

This guide is to help you learn how to use MacsBug. MacsBug is a system extension that can help you debug your programs. It is free and available from Apple Computer. Note that the name MacsBug is an acronym for Motorola advanced computer systems debugger, as opposed to "Macintosh debugger." This guide is a list of tricks, but it is just the tip of the iceberg of the cool stuff you can do. Hopefully, after reading this, the help part of MacsBug won't be so intimidating.

Table of Contents

How Do I Install MacsBug?

This has been the subject of much confusion judging on the amount of email I get. Many people have the problem that when they "Get Info" on MacsBug in the Finder it says that it's a document, not an extension or an application. MacsBug is what is know as a system extension, it extends the system software in ways that normal extensions don't. All that needs to be done is to put the "MacsBug" document itself (the one with the bomb icon) into the "System Folder," at the same level of the Finder and the System file. You can get a copy of MacsBug from the developer CDs, Apple computer, America Online, friends, et cetera.

How Do I Get Into MacsBug?

Once MacsBug is installed (and the computer is restarted) you can begin using MacsBug. You will know the installation was successful when the "Welcome to Macintosh..." screen says "Debugger Installed." In order to get into, or to "drop into," MacsBug you need to either hit the interrupt switch (on the side or back of your computer, see your owner's guide), or hold down on the command key and press power-on. The command key is the key with the Open Apple sign on it. The power-on key is the one with the left open arrow, typically on the upper right-hand or left-hand corner of the keyboard.

While you are in MacsBug all other Macintosh processes are halted, including background printing. (Since everything is halted, dropping into MacsBug is also a good way to pause a video game.) Once in MacsBug, you can proceed to do all of the "tricks."

To get out of MacsBug, type a "g" and hit return, or hold down on the command key and strike the "G" key. If ever you want to view the normal screen while still having the Macintosh frozen, press the escape key; to get back to the normal MacsBug screen from here, press any key.

Number Conversion

MacsBug can be used as a quick hexadecimal to decimal converter, and vice versa. I used to use a calculator DA, but now I just simply drop into MacsBug and type in the number I want to convert and hit return. Example: You want to find out what 0x3E is in decimal. When in MacsBug, type in $3E and hit return. This will be the output:

$3E = $0000003E #62 #62 '***>'

The first number ($0000003E) is the value in hexadecimal that you just typed in. The second number is what the value is as an unsigned decimal, the third is the signed version. The set of characters in single quotes ('***>') is the ASCII representation of the number, the unprintable characters are denoted with the bullet ('*').

You can find out the decimal/hexadecimal equivalent of any ASCII character by typing the letter balanced between two single quotes. Example: Type in: 'A' and hit return. You will get #65 as your answer.

By the way-- the dollar sign means that the number is in hexadecimal. Much like C's 0xXX notation, $XX is how hexadecimal numbers are represented in 68k assembly. Numbers in MacsBug will default to hexadecimal, except for when the hexadecimal number is a command or a register. For example, ea is the command to restart the current application, when you type in ea it will try this command, you must type in $ea when you mean the number.

Similarly, you have to type a # in order to express decimal numbers. You can use the conversion method just described (type in the number, hit return) to find out a decimal number's\ corresponding hexadecimal number and ASCII character.

What Was My Monitor Size?

Here's an impressive way to show friends how many pixels they have on their monitor (other than looking at Monitors control panel, or something silly like that). Drop into MacsBug and type in: dm @@MainDevice GDevice. This will show you the fi elds of the MainDeviceglobal variable (which is of GDevice type), you should see the gdPMap indented, three lines below it will be bounds with four numbers to the right of it. These four numbers are the top,left, bottom and right coordinates of the moni tor, respectively.

The dm command is short for display memory, after you type in dm type in the address of the memory you want to display. MainDevice is a system global that is a handle (a pointer to a pointer) to the main gr aphics device (the one with the menu bar). The two @@ symbols are how you express double-indirection in MacsBug, in C/C++ you use* to express indirection (i.e. de-referencing), which is in put in prefix notation. People who prog ram in Pascal can use the postfix indirection notation by using "dm MainDevice^^ GDevice".

After you give the dm command the address give it the format you want to see itdiplayed as. You can use any number for the number of bytes you want displayed, or you can say"Rect", for instance, to see the first eight bytes of the memory in the form of a rectangle. You can also use: Byte, Word, Long, SignedB yte, SignedWord, SignedLong, UnsignedByte, UnsignedWord, UnsignedLong,PString, CString, and PixMap, GDevice,RGBColor , CGrafPort and any number of other templates you may have installed.

Example: If you know a rectangle is at address $00058EA6 and you want to see what its value is, all you have to do is type in"dm $00058E A6 Rect".

By the way-A template is a layout of memory that MacsBug knows about (such as a C struct or aPascal record), you can type "tmp" to find out all of the templates your version of MacsBug has.

Error Lookup

Don't you hate it when you are working in an application, minding your own business, when all-of-a-sudden the program quits and the system tells you an error of type X occurred? There are many applica tions made where you can look up these numbers and find out what went wrong.MacsBug can also do this, all you have to do is type error and then the error number. Keep in mind that the error numbers the system gives you are decimal (not hexadecimal), so y ou should put a "#" in front of them. Example: The system tells you: "An error of type 4 has occurred," drop into MacsBug and type "error #4", MacsBug will then output "$0004 #4 zero divide error".

Note: This error feature is not in earlier versions of MacsBug, so you may not have it.

The Simple Calculator

You can use MacsBug as a simple calculator. Let's say you need to know what seven times seventeen is, type in "#7 * #17", and hit return. The number 119 should now be on your screen. It will be hidden in the line:

#7 * #17 = $00000077 #119 #119 '***w'

The lower case letter w is the 119 th ASCII character, as the previous line shows us. Let's try another example, how about five plus six? Type in "#5 + #6", and hit return. You should then see:

#5 + #6 = $0000000B #11 #11 '****'

MacsBug can al so handle multiple operations at a time, like five plus six plus ten. If you want to say something like five plus six times four, remember to put parentheses around the appropriate numbers. MacsBug has no concept of orders of operations and it's quite possible for it to add before it multiplies. So say this: "#5 + (#6 * #4)", which equals #29, instead of "#5 + #6 * #4", which equals #44.

You can use +, -, *, <, >, MOD for arithmetic operations
You can use AND (or &), OR (or |), NOT (or !), XOR for boolean operations
And you can use = ( or ==), <> (or !=), < , >, <=, >= for equality operations

If you type in "#5 + #4 = #9" MacsBug will give you a one, meaning that the eq uality you just said was true. If you said "#5 + #4 = #10", Macsbug will give you a zero, meaning that the equality five plus four equals ten is false.

Moving the Cursor

Here is a cool trick to move the cursor. It's done by setting memory-- the mouse tracking variables specifically. But I'd like to talk about setting memory beforehand. There are four commands in MacsBug to set memory: SB (set byte), SW (set word), SL (set long), and SM (set memory). You give each of these commands an address first, and then the values of what you want to set the memory to. Example: There is a byte that you have the address of that you want t o set to ten, you should type in:

SB $XXXXXXXX #10

where $XXXXXXXX is the address of the byte. Another example: There is a long that you have the address of that you want to set to "$4D616320", you should type in:

SL $XXXXXXXX $4D616320

again, where $XXXXXXXX is the address of the long. You can use the SM command the same way in the case that the length you want to set is not one, two or four bytes long . You can use SW when you want to set a word (two bytes).

If you are familiar with Points (the vertical and horizontal coordinates of a point on the graf plane) you should know that they take up four bytes in memory. The high two bytes (t he high word) is the vertical coordinate, and the low two bytes (the low word) is the horizontal coordinate. There are two global variables that are both Points, one called MTemp, the other called RawMouse, these variables are the information the Macintos h uses for controlling the cursor. You can set these points by using SL.

There is also a byte called CrsrNew, set this byte to 1 when you want to notify the Macintosh that the cursor positions have changed. This is how you move the mouse to point (5,6), near the upper-left corner of the screen:

SL MTemp $00060005
SL RawMouse $00060005
SB CrsrNew $1

Make sure MTemp and RawMouse are being set to the same value. Now type Command-G to see your newly moved cursor. In later ve rsions of MacsBug, the system globals' symbolic names have been removed, in which case the addresses themselves need to be typed in:

SL 828 $00060005
SL 82C $00060005
SB 8CE $1

This useful feature was probably removed from MacsBug in anticipation of newer system software with different globals and locations. This trick might not work in the future.

Having Fun With Menus

Here is another "set low memory globals" trick. It is concerned with setting the flash rate of menu items when you select them. Drop into MacsBug and type in: "SW A24 #50" and hit return. Get out of MacsBug via command-G and select any item from any menu, notice how the item now flashed 50 times. Go back and use a value like three (i.e. "SW A24 #3") to set it back to reasonable rate. Have fun setting it to even higher values!

GetKeys from within MacsBug

There is a routine in the Macintosh toolbox called GetKeys, this routine is great for game programmers who want a reasonably fast way to read the keyboard, without using (slower) events. The problem for C and C++ programmers using this rou tine is that the KeyMap type is a Pascal packed array. Each bit of the packed array is designated to a certain key, the bit is set to 1 if the key is down, and set to zero if the key is up. This array takes up 16 bytes (128 bits). C cannot access the elem ents of the packed array like a normal array, so the programmer has to mask out some bits to get the result that he/she wants. There is a desk accessory named "GetKeys," that is made just for this case. The problem is, you might not be on a mach ine with that program on it.

Good thing MacsBug is able to help us. Here is how you locate the bit for the letter "M": go into MacsBug and type in "dm KeyMap", but don't hit return just yet. Now strike the escape key, this should s wap the screen. Press and hold down the letter "M" on your keyboard, this should swap the screen back. Now, while still holding down "M", press return. This is what you should see:

 Displaying memory from 0174  00000174  0000
 0000 0040 0000  0000 0000 0000 0000  *****@**********

The number "00000174" is the address of the KeyMap global variable. The next set of numbers "0000 0000" is the first element of the C version of the array, in other words, it's: "keyMap[0]". The next set of numbers "0040 0000" is the second element of the array, keyMap[1]. The next group of 8 hexadecimal digits is the third element (keyMap[2]), and the last group of 8 hexadecimal digits i s the fourth element (keyMap[3]). The series of bullets is what the array looks like in ASCII form. In the second group ("0040 0000") there is a 4 in the midst of all of those zeros. This is the bit that is set to 1 whenever the "M" ke y is held down. So, to see if the "M" is down from within C we will do this:

    KeyMap keyMap;
    GetKeys(keyMap);
    if (keyMap[1] & 0x00400000) {
        DoMKeyDown();
    }

In later versions of MacsBug typing in &q uot;dm KeyMap" won't workÉ type in "dm 174" instead. Be aware of keys like the caps lock, which will always have their bits set if they are down.

The Lost Paper

I was once typing in some text in a word processor, when the computer suddenly crashed on me. I didn't save a copy on to the hard-disk yet. I had to restart the computer and type it all over again. But wait, the paper is still in the machine, I thought to myself. You see, whe n you restart, all of the computer's memory doesn't get cleared, it just stays to what it was until it gets replaced with other information (much like the behavior of a hard-disk). I had one thing going for me, I had MacsBug installed. Here are the steps I took to recover the paper:

First, I logged all of the work I was doing in MacsBug to a file. I did this using the log command. All you need to give the log command is the name of the new file to log to. I named it MyPaper. Good, now all of my MacsBu g session will be on the hard-disk so I can later open it up with a normal text editor when I'm done.

Next, I needed to find where in memory my paper was. I did this using the "f" command. The first two parameters for this command is the ran ge in memory in which you want MacsBug to search through. I wanted to search through all of my memory, which is 8 megs on my machine, so I typed in: "f 0 (400 * 400 * 8) "any string"". Where 0 is the beginning of memory and 8 megs is the top of it. (Note how 400 * 400 is exactly one megabyte of memory.) The last parameter is the search string, balanced between two single quotes. I wanted to pick a distinct string, otherwise I would have found other parts of memory, which would take longer to do. I knew the most famous mammal, the aardvark, was mentioned in my paper, so I typed in this for the find command:

f 0 (400 * 400 * 8) "aardvark"

MacsBug then started searching for me. It came up with a small memory dump of something with the word aardvark in it, but the words after it were not mine, which meant that I found another part of memory instead of my paper. I hit return to tell MacsBug to keep on searching. MacsBug then came up with a dump from my paper:

Searching for "aardvark" from 00000000 to 007FFFFF
  00358200  6161 7264 7661 726B  8000 0000 0000 002C  aardvark answer,

Which was very good news indeed! This told me that the string "aardvark answer" could be found at address 00358200. (I go t this address from the leftmost number given.)

Now that I knew where it was, the rest my task would be easy. I used MacsBug's display ASCII command to show me what came after it by typing in: dma 00358200. You might not have this command, in which ca se you'll have to use plain old dm, instead of dma. I hit return until my paper was done being displayed.

Note: You can subtract a number from the address to see what is before it.

I then typed in log again, which closed my log. Finally, I w ent out of MacsBug and opened the log file with SimpleText. Remember, the log had my whole session not just the paper, so I had to delete the addresses and such from it, which really isn't that hard to do if you know how to use your mouse and your delete key efficiently. The paper was saved.

Warning: In your search you might stumble upon MacsBug's very own memory, with its own copy of your search string. To get out of this, start the search over again with the search base address being outside of MacsBug's memory.

For Further Reading

The book How to Write Macintosh Software: The Debugging Reference for the Macintosh, third edition, by Scott Knaster, publish by Addison-Wesley, 1992, is a great resource to have, Appendix D of the book, "Debugging Quick Reference Guide," has a list of system globals (and their locations) that comes in handy at times. It is also a great book to learn more about assembly, MacsBug, and debugging.

Apple's own MacsBug Reference and Debugging Guide: For MacsBug version 6.2, published by Addison-Wesley, 1990, is a complete reference to MacsBug version 6.2... though outdated with the more current versions (such as 6.5.3) it is still useful. I don't think Apple has made a latter edition of this book.

You can also check-out another MacsBug guide, Tips and Tricks for MacsBug, which contains more cool information and links to other MacsBug pages.

The first place to read, however, is MacsBug itself. When in MacsBug type in "help" or "?" and hit return repeatedly, this will list all of the commands with a brief description of what they do.

Thanks for reading!

Feel free to distribute this document as long as it is in its original form and includes the below copyright notice. There are no warranties expressed or implied, use the information contained in this document at your own risk.