Table Of Content

DISK INCLUDtD f>t18 6.2 0 .l). 01) ~(}cs ':?J>_,f Debugging MacintosH 1~s Software ~ w 1 )> KONSTANTIN OTHMER JIM STRAUS Debugging Macintosh® Software with MacsBug® Debugging Macintosh® Software with MacsBug® Includes MacsBug 6.2 on Disk Konstantin Othmer Jim Straus Addison-Wesley Publishing Company, Inc. Reading, Massachusetts Menlo Park, California New York Don Mills, Ontario Wokingham, England Amsterdam Bonn Sydney Singapore Tokyo Madrid SanJuan Paris Seoul Milan Mexico City Taipei Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book and Addison-Wesley was aware of a trademark claim, the designations have been printed in initial capital letters. APPLE COMPUTER, INC. ("APPLE") MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING MACSBUG. APPLE DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF MACSBUG IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS OR OTHERWISE. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF MACSBUG IS ASSUMED BY YOU. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL APPLE, ITS DIRECTORS, OFFICERS, EMPLOYEES, OR AGENTS BE LIABLE TO YOU FOR ANY CONSEQUENTIAL, INCIDENTAL, OR INDIRECT DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE) ARISING OUT OF THE USE OR INABILITY 1U USE MACSBUG EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATIONS MAY NOT APPLY 1U YOU. Apple's liability to you for actual damages from any cause whatsoever, and regardless of the form of the action (whether in contract, tort (including negligence), product liability, or otherwise), will be limited to $50. Library of Congress Cataloging-in-Publication Othmer, Konstantin. Debugging Macintosh software with MacsBug: includes MacsBug 6.2/Konstantin Othmer, Jim Straus. P· em. Includes index. ISBN 0-201-57049-1 1. Macintosh (Computer)-Programming. 2. Debugging in computer science. 3. MacsBug. I. Straus, Jim. ll. Title. QA76.8.M3084 1991 005.369-dc20 91-8059 CIP Copyright© 1991 by Konstantin Othmer and Jim Straus All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of the publisher. Printed in the United States of America. Published simultaneously in Canada. Associate Editor: Rachel Guichard Technical Reviewer: Chris Derossi Disk Review: scott douglass, Ed Tecot Cover Design: Ronn Campisi Set in 10.5-point Palatino by Inprint Publishing Corp. 12345 6 789-MW -9594939291 First printing, April1991 Contents Foreword by Scott Knaster xv Acknowledgments xvii ..._ PART ONE GeHing Started 1 1. Introduction 3 Why Learn to Use MacsBug? 3 What You Need to Know 5 What's in This Book? 5 Symbols Used in This Book 6 What's on the Disk? 7 How to Use This Book 7 Summary 8 2. MacsBug Basics 9 Installing and Configuring MacsBug 9 The Monitors Control Panel 10 Res Edit and the Debugger Prefs File 11 v vi ...,. Contents Using MacsBug for Temporary Customization 13 Low Level Details of the Macintosh 13 The Processor and Memory 13 Memory Maps 15 The Anatomy of the MacsBug Screen 19 Basic Command Line Editing 21 Arrow Keys 21 Option Ketj 22 Delete Key 22 Return Key 22 The Command History Buffer 22 Entering MacsBug 22 The Programmer's Switch 23 The Programmer's Key INIT 23 The Debugger and DebugStr Traps 24 System Error 24 Leaving MacsBug 24 Step 24 T(or SO) 25 GoTo 25 Go 25 Exit to Shell 25 Exit to Application 26 ReBoot 26 ReStart 26 A Sample MacsBug Session 26 A-Trap Break 26 The Escape and Back Quote Keys 27 A-Trap Clear 27 BReak 27 BReak Clear 28 Display Memory 28 TeMPlates 29 HOW 30 HELP 30 Summary 31 ...,. Contents vii .._ PART TWO Exploring the Macintosh with MacsBug 33 3. Accessing the ROM 35 Where Is The ROM? 36 A-Traps 37 ToolBox Calling Conventions 39 OS Traps: Usually Register-Based Calls 40 Toolbox Traps: Usually Stack-Based Calls 40 High Level Languages and Traps 40 MacsBug' s A-Trap Commands 49 ROM Organization: the MPW ROMMap File 60 Summary 60 4. How RAM is Organized and Maintained 63 Heaps 64 Pointers and Handles 66 The System Heap 71 The MultiFinder Heap 71 The Application Heap 73 MacsBug Commands That Operate on Heaps 77 HeapZone 77 Heap Exchange 80 Heap Display 81 Heap Totals 85 Heap Check 86 A-Trap Heap Check 88 Heap Scramble 89 The Application Stack and the Link Instruction 89 Low Memory Globals 96 Application Globals 97 The Segment Loader 98 Jump Table Entries for Routines in Unloaded Segments 99 Jump Table Entries for Routines in Loaded Segments 101 Stepping Into Another Segment 103 Common Problems Using the Memory Manager 104 Corrupting the Heap 104 viii ...,. Contents Fragmenting the Heap 106 Memory Leakage 109 Summary 110 5. The Main Event Loop 113 Finding the Event Loop 113 What's In an Event Loop 114 WaitNextEvent 116 Catching a Keyboard Event 117 The Event Queue 119 Forcing an Application to Quit 121 Summary 122 6. Resources 123 Specifying a Resource 124 Owned Resource IDs 125 Resources In Memory 126 Attributes 128 Code Resources 130 Other Resources 131 Resources on Disk 132 Resources In ROM 134 The Resource Chain 135 Resource Maps 138 Structure of a Resource Map 138 Summary 141 7. Menus 143 How the Menu Manager Works 143 The Menu List 144 Other Globals 147 The Menu Definition Function (MDEF) 149 The Menu Bar Definition Function (MBDF) 153 Summary 156 .,.. Contents lx 8. Windows 159 How the Window Manager Works 159 Update Region Maintenance 160 The Window List 166 The Window Definition Function (WDEF) 167 Summary 180 9. Dialogs 181 Creating Dialogs 181 Creating a Dialog without Resources 183 Dialog Record and Dialog Item Lists 186 Setting User Items 190 Alerts 191 Dialog Event Management 191 Modeless Dialogs 191 Modal Dialogs 192 Summary 195 10. Controls and CDEFs 197 Properties of Controls 197 Creating Controls 198 The Control ID 198 Part Codes 199 The Control Record 200 TheCDEF 204 How Controls Respond to Events 204 Summary 209 11. QuickDraw 211 Classic QuickDraw 212 Color QuickDraw and 32-bit QuickDraw 212 HowQuickDrawWorks 214 The Current Port 214 GrafPorts and CGrafPorts 216 BitMaps and PixMaps 220 Destination Color Information and GDevices 221 x ...,. Contents CopyBits 223 Copy Bits Colorizing 223 Destination Color Revisited 224 The Color Table Seed 228 Accessing 32-bit Addressed PixMaps 229 Common Problems Using QuickDraw 230 Bug 1: Why is CopyBits Drawing the Wrong Image? 231 Bug 2: Drawing Occurs to the Screen Instead of to the Offscreen PixMap 238 Bug 3: Drawing Is Correct Only if the Main Screen Is 8-bit 246 Summary 251 12. Device Drivers and Desk Accessories 253 Structure of a Driver 255 Desk Accessories 257 An Easier Way: The DRVR Dcmd 260 Summary 261 13. The File Manager 263 Understanding the File Manager 263 Calling the File Manager 265 The File Manager Traps 265 File Manager Glue 266 Parameter Blocks 268 In Memory Data Structures 272 The FCB Array 272 The VCB Queue 276 The WDCB Array 278 The Default Volume 279 More File Manager Tips 281 The "Poor Man's Search Path" (PMSP) 281 Some Useful MacsBug Commands 285 Summary 286 14. The Printing Manager 287 Device Independence 287