dbx User’s Guide Document Number 007-0906-110 CONTRIBUTORS Written by Wendy Ferguson, Ken Jones and Leif Wennerberg Edited by Christina Cary Production by Gloria Ackley, Kay Maitz, and Lorrie Williams Engineering contributions by Dave Anderson, Alan Foster, Jay Gischer, Ray Milkey and Jon Templeton Cover design and illustration by Rob Aguilar, Rikk Carey, Dean Hodgkinson, Erik Lindholm, and Kay Maitz © Copyright 1996 Silicon Graphics, Inc.— All Rights Reserved This document contains proprietary and confidential information of Silicon Graphics, Inc. The contents of this document may not be disclosed to third parties, copied, or duplicated in any form, in whole or in part, without the prior written permission of Silicon Graphics, Inc. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure of the technical data contained in this document by the Government is subject to restrictions as set forth in subdivision (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and/or in similar or successor clauses in the FAR, or in the DOD or NASA FAR Supplement. Unpublished rights reserved under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 2011 N. Shoreline Blvd., Mountain View, CA 94043-1389. Silicon Graphics and IRIS are registered trademarks and IRIX is a trademark of Silicon Graphics, Inc. This product documents the duel program developed by Michael Golan. dbx User’s Guide Document Number 007-0906-110 Contents List of Tables ix About This Guide xi What This Guide Contains xi What You Should Know Before Reading This Guide xii Suggestions for Further Reading xii Conventions Used in This Guide xiii 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 6 Invoking dbx 6 dbx Options 7 Specifying Object and Core Files 8 The dbx Prompt 8 Specifying Files with dbx Commands 9 Running Your Program 9 Automatically Executing Commands on Startup 10 Using Online Help 11 Entering Multiple Commands on a Single Line 11 Spanning a Command Across Multiple Lines 12 Invoking a Shell 12 Quitting dbx 13 iii Contents 3. Examining Source Files 15 Specifying Source Directories 15 Specifying Source Directories With Arguments 15 Specifying Source Directories With dbx Commands 16 Examples of dir and use 16 Path Remapping 17 Controlling use of Path Remappings and Your Source-Directory List 18 Changing Source Files 18 Listing Source Code 19 Listing Inlines and Clones 20 Searching Through Source Code 21 Calling an Editor 22 4. Controlling dbx 23 Creating and Removing dbx Variables 23 Setting dbx Variables 24 Listing dbx Variables 25 Removing Variables 25 Using the History Feature and the History Editor 25 Examining the History List 26 Repeating Commands 26 The History Editor 27 Creating and Removing dbx Aliases 28 Listing Aliases 29 Creating Command Aliases 29 Removing Command Aliases 31 Alias Example 31 Recording and Playing Back dbx Input and Output 32 Recording Input 32 Ending a Recording Session 33 Playing Back Input 33 Recording Output 34 Playing Back Output 35 Examining the Record State 35 iv Contents Executing dbx Scripts 35 5. Examining and Changing Data 37 Using Expressions 37 Operators 38 Constants 40 Numeric Constants 40 String Constants 41 Printing Expressions 41 Using Data Types and Type Coercion (Casts) 43 Qualifying Names of Program Elements 43 Displaying and Changing Program Variables 46 Variable Scope 46 Displaying the Value of a Variable 47 Changing the Value of a Variable 48 Conflicts Between Variable Names and Keywords 49 Case Sensitivity in Variable Names 50 Displaying and Changing Environment Variables Used by a Program 50 Using the High-Level Debugging Language duel 51 Using duel Quick Start 52 duel Operator Summary 54 duel EXAMPLES 55 duel SEMANTICS 57 duel Operators 58 Differences from Other Languages 62 Differences from C 62 Differences from Fortran 63 Determining Variable Scopes and Fully Qualified Names 63 Displaying Type Declarations 64 Examining the Stack 64 Printing Stack Traces 65 Moving Within the Stack 67 Moving to a Specified Procedure 69 Printing Activation Level Information 70 v Contents Using Interactive Function Calls 71 Using ccall 72 Using clearcalls 73 Nesting Interactive Function Calls 74 Obtaining Basic Blocks Counts 75 Accessing C++ Member Variables 77 6. Controlling Program Execution 79 Setting Breakpoints 79 Setting Unconditional Breakpoints 80 Setting Conditional Breakpoints 80 Stopping If a Variable or Memory Location Has Changed 81 Using Fast Data Breakpoints 82 Stopping If a Test Expression Is True 83 Conditional Breakpoints Combining Variable and Test Clauses 83 Continuing Execution After a Breakpoint 84 Tracing Program Execution 85 Writing Conditional Commands 87 Managing Breakpoints, Traces, and Conditional Commands 89 Listing Breakpoints, Traces, and Conditional Commands 89 Disabling Breakpoints, Traces, and Conditional Commands 90 Enabling Breakpoints, Traces, and Conditional Commands 91 Deleting Breakpoints, Traces, and Conditional Commands 91 Using Signal Processing 92 Catching and Ignoring Signals 92 Continuing After Catching a Signal 93 Stopping on C++ Exceptions 94 Stopping at System Calls 96 Stepping Through Your Program 97 Stepping Using the step Command 98 Stepping Using the next Command 100 Using the return Command 100 Starting at a Specified Line 100 Referring to C++ Functions 101 vi Contents 7. Debugging Machine Language Code 105 Examining and Changing Register Values 105 Printing Register Values 107 Changing Register Values 109 Examining Memory and Disassembling Code 109 Setting Machine-Level Breakpoints 112 Syntax of the stopi Command 113 Linking With DSOs 114 Continuing Execution After a Machine-Level Breakpoint 115 Tracing Execution at the Machine Level 116 Writing Conditional Commands at the Machine Level 118 Stepping Through Machine Code 119 8. Multiple Process Debugging 121 Processes and Threads 121 Using the pid Clause 122 Using the pgrp Clause 123 Using the thread Clause 123 Using Scripts 124 Listing Available Processes 124 Adding a Process to the Process Pool 125 Deleting a Process From the Process Pool 126 Selecting a Process 126 Suspending a Process 126 Resuming a Suspended Process 127 Waiting for a Resumed Process 128 Waiting for Any Running Process 129 Killing a Process 129 Handling fork System Calls 130 Handling exec System Calls 131 Handling sproc System Calls and Process Group Debugging 132 vii Contents A. dbx Commands 137 B. Predefined Aliases 159 C. Predefined dbx Variables 163 Index 173 viii List of Tables Table 2-1 dbx Command-Line Options 7 Table 3-1 Effect of $sourcepathrule on Use of Path Remapping and Source Directory List 18 Table 5-1 dbx Language Independent Operators 38 Table 5-2 C Language Operators Recognized by dbx 39 Table 5-3 Pascal Operators Recognized by dbx 39 Table 5-4 Fortran 77 and Fortran 90 Operators Recognized by dbx 40 Table 5-5 Variable Types 42 Table 5-6 duel Operator Summary 54 Table 5-7 duel Examples 55 Table 6-1 Effect of $stepintoall Variable on the step Command 99 Table 7-1 Hardware Registers and Aliases 105 Table 7-2 Memory Display Format Codes 110 Table 8-1 How the $promptonfork Variable Affects dbx’s Treatment of Forks 130 Table 8-2 How the $mp_program Variable Affects dbx’s Treatment of sprocs 133 Table B-1 Predefined Aliases 159 Table C-1 Predefined dbx Variables 163 ix About This Guide This guide explains how to use the source level debugger, dbx. You can use dbx to debug programs in C, C++, Fortran, and assembly language. What This Guide Contains This guide describes the features of dbx and provides simple examples of how to use dbx to debug programs. Specifically, this guide includes: Chapter 1, “Getting Started With dbx,” introduces some basic dbx commands and offers some tips about how to approach a debugging session. Chapter 2, “Running dbx,” explains how to run dbx and perform basic dbx control functions. Chapter 3, “Examining Source Files,” explains how to examine source files under dbx. Chapter 4, “Controlling dbx,” describes features of dbx that affect its operation while debugging a program. Chapter 5, “Examining and Changing Data,” describes how to examine and change data in your program while running it under dbx. Chapter 6, “Controlling Program Execution,” describes how to use the dbx commands that control execution of your program. Chapter 7, “Debugging Machine Language Code,” explains how to debug machine language code. Chapter 8, “Multiple Process Debugging,” explains multiprocess debugging procedures. Appendix A, “dbx Commands,” lists and describes all dbx commands. xi About This Guide Appendix B, “Predefined Aliases,” lists and describes all predefined dbx aliases. Appendix C, “Predefined dbx Variables,” lists and describes all predefined dbx variables. What You Should Know Before Reading This Guide This manual is written for programmers, and assumes that you are familiar with general debugging techniques. Suggestions for Further Reading This dbx User’s Guide is part of the IRIS Developer Option (IDO), which provides the software and documentation that you can use to write applications for Silicon Graphics platforms. A few IDO online and printed manuals that may be of interest to you are listed below. Programming on Silicon Graphics Systems: An Overview provides information about the IRIX programming environment and tools available for application programming. Topics covered include IRIX operating system, compilers, user interface and developer tools, and application libraries. Compiling and Performance Tuning Guide describes the compiler system and programming tools and interfaces, and explains how to improve program performance. Topics in IRIX Programming presents information about internationalizing an application, working with fonts, file and record locking, and inter-process communication. C Language Reference Manual covers the syntax and semantics of the C programming language as implemented on the IRIX operating system.