dbx User’s Guide 007–0906–140 COPYRIGHT © 1996, 1999 – 2003 Silicon Graphics, Inc. All rights reserved; provided portions may be copyright in third parties, as indicated elsewhere herein. No permission is granted to copy, distribute, or create derivative works from the contents of this electronic documentation in any manner, in whole or in part, without the prior written permission of Silicon Graphics Inc. LIMITED RIGHTS LEGEND The electronic (software) version of this document was developed at private expense; if acquired under an agreement with the USA government or any contractor thereto, it is acquired as "commercial computer software" subject to the provisions of its applicable license agreement, as specified in (a) 48 CFR 12.212 of the FAR; or, if acquired for Department of Defense units, (b) 48 CFR 227-7202 of the DoD FAR Supplement; or sections succeeding thereto. Contractor/manufacturer is Silicon Graphics, Inc., 1600 Amphitheatre Pkwy 2E, Mountain View, CA 94043-1351. TRADEMARKS AND ATTRIBUTIONS Silicon Graphics, SGI, the SGI logo, IRIS and IRIX are registered trademarks and ProDev, and Power Challenge are trademarks of Silicon Graphics, Inc. in the United States and/or other countries worldwide. MIPSpro is a trademark of MIPS Technologies, Inc., and is used under license by Silicon Graphics, Inc. UNIX and the X device are registered trademarks of The Open Group in the United States and other countries This product documents the duel program developed by Michael Golan. Cover design by Sarah Bolles, Sarah Bolles Design, and Dany Galgani, SGI Technical Publications. New Features in This Manual Information regarding new user-level preferences to control internal breakpoints has been added to Chapter 8, "Debugging Multiprocess Programs", page 117. 007–0906–140 iii Record of Revision Version Description 1996 Original Printing. 7.3 June, 1999 This revision supports the ProDev 7.4 release. 120 November, 2001 This revision supports the ProDev 2.9.1 release. 130 September, 2002 This revision supports dbx version 7.3.4. 140 June 2003 Additional information added regarding user-level preferences. 007–0906–140 v Contents About This Guide .....................xxiii Related Publications . ...................xxiv Obtaining Publications . ...................xxiv Conventions . ........................xxv Reader Comments .......................xxv 1. Getting Started with dbx ................. 1 Examining Core Dumps to Determine Cause of Failure . ......... 1 Debugging Your Programs . ................... 2 Studying a New Program . ................... 3 Avoiding Common Pitfalls . ................... 4 2. Running dbx ...................... 5 Compiling a Program for Debugging under dbx .............. 5 Compiling and Linking Programs with Dynamic Shared Objects ......... 5 Invoking dbx ........................ 6 Specifying Object and Core Files .................. 7 Specifying Files with dbx Commands . .............. 8 Running Your Program (run, rerun, and sort).............. 8 Automatically Executing Commands on Startup .............. 10 Using Online Help ....................... 10 Entering Multiple Commands on a Single Line .............. 11 Spanning a Command Across Multiple Lines . .............. 11 Invoking a Shell ........................ 11 007–0906–140 vii Contents Quitting dbx ......................... 12 3. Examining Source Files . ................. 13 Specifying Source Directories . ................... 13 Specifying Source Directories with Arguments ............. 13 Specifying Source Directories with dbx Commands . ......... 14 Path Remapping . ................... 15 Controlling Use of Path Remappings and Your Source-Directory List . 15 Changing Source Files . ................... 16 Listing Source Code . ................... 17 Listing Inlines and Clones . ................... 18 Searching through Source Code ................... 19 Calling an Editor ....................... 20 4. Controlling dbx ..................... 21 Creating and Removing dbx Variables . .............. 21 Setting dbx Variables . ................... 22 Removing dbx Variables . ................... 23 Using the History Feature and the History Editor ............. 23 Examining the History List ................... 23 Repeating Commands . ................... 24 The History Editor . ................... 26 Creating and Removing dbx Aliases . .............. 26 Creating Command Aliases ................... 27 Listing Aliases ....................... 30 Removing Aliases . ................... 30 Recording and Playing Back dbx Input and Output ............. 30 viii 007–0906–140 dbx User’s Guide Recording Input ....................... 31 Ending a Recording Session ................... 31 Playing Back Input . ................... 32 Recording Output . ................... 32 Playing Output ....................... 33 Examining the Record State ................... 33 Executing dbx Scripts . ................... 34 5. Examining and Changing Data . .......... 35 Using Expressions ....................... 35 Operators . ........................ 36 Constants . ........................ 38 Printing Expressions . ................... 39 Value History for Print and Calls .................. 40 Using Data Types and Type Coercion (Casts) . .............. 41 Qualifying Names of Program Elements . .............. 41 Displaying and Changing Program Variables . .............. 44 Variable Scope ....................... 45 Displaying the Value of a Variable . .............. 45 Changing the Value of a Variable .................. 47 Conflicts between Variable Names and Keywords . ......... 48 Case Sensitivity in Variable Names . .............. 48 Displaying and Changing Environment Variables Used by a Program ....... 49 Using the High-Level Debugging Language duel ............. 49 Using duel Quick Start . ................... 50 duel Operator Summary . ................... 52 duel Examples ....................... 53 007–0906–140 ix Contents duel Semantics ....................... 55 duel Operators ....................... 56 Differences from Other Languages . .............. 61 Determining Variable Scopes and Fully Qualified Names . ......... 62 Displaying Type Declarations . ................... 63 Examining the Stack . ................... 63 Printing Stack Traces . ................... 64 Moving within the Stack . ................... 66 Moving to a Specified Procedure .................. 68 Printing Activation Level Information . .............. 69 Using Interactive Function Calls ................... 70 Using the ccall Command ................... 71 Using the clearcalls Command . .............. 72 Nesting Interactive Function Calls . .............. 73 Obtaining Basic Blocks Counts ................... 74 Accessing C++ Member Variables .................. 75 6. Controlling Program Execution . .......... 77 Setting Breakpoints ....................... 77 Setting Unconditional Breakpoints . .............. 78 Setting Conditional Breakpoints .................. 78 Stopping If a Variable or Memory Location Has Changed . ......... 79 Using Fast Data Breakpoints ................... 80 Stopping If a Test Expression Is True . .............. 81 Conditional Breakpoints Combining Variable and Test Clauses ........ 81 Continuing Execution after a Breakpoint . .............. 82 Tracing Program Execution . ................... 83 x 007–0906–140 dbx User’s Guide Writing Conditional Commands ................... 85 Managing Breakpoints, Traces, and Conditional Commands . ......... 87 Listing Breakpoints, Traces, and Conditional Commands . ......... 87 Disabling Breakpoints, Traces, and Conditional Commands . ......... 88 Enabling Breakpoints, Traces, and Conditional Commands . ......... 89 Deleting Breakpoints, Traces, and Conditional Commands . ......... 89 Using Signal Processing . ................... 90 Catching and Ignoring Signals .................. 90 Continuing after Catching a Signal . .............. 91 Stopping on C++ Exceptions . ................... 92 Stopping at System Calls . ................... 94 Stepping through Your Program ................... 95 Stepping Using the step Command . .............. 96 Stepping Using the next Command . .............. 97 Using the return Command ................... 98 Starting at a Specified Line . ................... 98 Referring to C++ Functions . ................... 98 7. Debugging Machine Language Code . .......... 103 Examining and Changing Register Values . .............. 103 Printing Register Values . ................... 105 Changing Register Values . ................... 106 Examining Memory and Disassembling Code . .............. 107 Setting Machine-Level Breakpoints .................. 110 Syntax of the Stopi Command .................. 110 Continuing Execution after a Machine-Level Breakpoint . ......... 112 Tracing Execution at the Machine Level . .............. 113 007–0906–140 xi Contents Writing Conditional Commands at the Machine Level . ......... 114 Stepping through Machine Code ................... 115 8. Debugging Multiprocess Programs . .......... 117 Processes and Threads . ................... 117 User-Level Preferences . ................... 118 Setting up Your Environment ................... 119 Using the pid Clause . ................... 119 Using the pgrp Clause . ................... 120 Using the thread Clause . ................... 120 Using Scripts ........................ 121 Listing Available Processes . ................... 121 Adding a Process to the Process Pool . .............. 122 Deleting a Process from the Process Pool . .............. 123 Selecting a Process ......................