Debugging with GDB: The GNU Source-Level Debugger

329 Pages·2002·1.47 MB·English

by  Richard M. Stallman

Debugging with GDB
The gnu Source-Level Debugger
Ninth Edition, for GDB version 5.1.1
January 2002
Richard Stallman, Roland Pesch, Stan Shebs, et al.
Copyright (cid:1)c 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
2002 Free Software Foundation, Inc.
Published by the Free Software Foundation
59 Temple Place - Suite 330,
Boston, MA 02111-1307 USA
ISBN 1-882114-88-4
Permission is granted to copy, distribute and/or modify this document under the terms
of the GNU Free Documentation License, Version 1.1 or any later version published by
the Free Software Foundation; with the Invariant Sections being “Free Software” and “Free
SoftwareNeedsFreeDocumentation”, withtheFront-CoverTextsbeing“AGNUManual,”
and with the Back-Cover Texts as in (a) below.
(a) The Free Software Foundation’s Back-Cover Text is: “You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free Software
Foundation raise funds for GNU development.”
i
Table of Contents
Summary of GDB............................. 1
Free software ................................................ 1
Free Software Needs Free Documentation...................... 1
Contributors to GDB......................................... 3
1 A Sample GDB Session .................... 7
2 Getting In and Out of GDB............... 11
2.1 Invoking GDB......................................... 11
2.1.1 Choosing files................................. 12
2.1.2 Choosing modes............................... 13
2.2 Quitting GDB......................................... 15
2.3 Shell commands........................................ 15
3 GDB Commands ......................... 17
3.1 Command syntax ...................................... 17
3.2 Command completion .................................. 17
3.3 Getting help........................................... 19
4 Running Programs Under GDB ........... 23
4.1 Compiling for debugging................................ 23
4.2 Starting your program.................................. 23
4.3 Your program’s arguments.............................. 24
4.4 Your program’s environment............................ 25
4.5 Your program’s working directory ....................... 26
4.6 Your program’s input and output........................ 26
4.7 Debugging an already-running process................... 27
4.8 Killing the child process ................................ 28
4.9 Debugging programs with multiple threads............... 28
4.10 Debugging programs with multiple processes............ 30
5 Stopping and Continuing.................. 33
5.1 Breakpoints, watchpoints, and catchpoints ............... 33
5.1.1 Setting breakpoints............................ 34
5.1.2 Setting watchpoints............................ 37
5.1.3 Setting catchpoints............................ 39
5.1.4 Deleting breakpoints........................... 40
5.1.5 Disabling breakpoints.......................... 41
5.1.6 Break conditions............................... 42
5.1.7 Breakpoint command lists...................... 43
5.1.8 Breakpoint menus............................. 44
ii Debugging with GDB
5.1.9 “Cannot insert breakpoints”.................... 45
5.2 Continuing and stepping................................ 45
5.3 Signals................................................ 48
5.4 Stopping and starting multi-thread programs............. 50
6 Examining the Stack...................... 53
6.1 Stack frames........................................... 53
6.2 Backtraces............................................. 54
6.3 Selecting a frame....................................... 55
6.4 Information about a frame.............................. 56
7 Examining Source Files ................... 57
7.1 Printing source lines.................................... 57
7.2 Searching source files................................... 58
7.3 Specifying source directories ............................ 59
7.4 Source and machine code............................... 59
8 Examining Data .......................... 63
8.1 Expressions............................................ 63
8.2 Program variables...................................... 64
8.3 Artificial arrays........................................ 65
8.4 Output formats........................................ 66
8.5 Examining memory..................................... 67
8.6 Automatic display...................................... 68
8.7 Print settings.......................................... 70
8.8 Value history .......................................... 75
8.9 Convenience variables .................................. 76
8.10 Registers............................................. 77
8.11 Floating point hardware............................... 78
8.12 Memory Region Attributes............................. 78
8.12.1 Attributes ................................... 79
8.12.1.1 Memory Access Mode................ 79
8.12.1.2 Memory Access Size.................. 79
8.12.1.3 Data Cache.......................... 80
9 Tracepoints............................... 81
9.1 Commands to Set Tracepoints........................... 81
9.1.1 Create and Delete Tracepoints.................. 81
9.1.2 Enable and Disable Tracepoints................. 82
9.1.3 Tracepoint Passcounts ......................... 82
9.1.4 Tracepoint Action Lists........................ 83
9.1.5 Listing Tracepoints............................ 84
9.1.6 Starting and Stopping Trace Experiment........ 85
9.2 Using the collected data................................ 85
9.2.1 tfind n....................................... 85
9.2.2 tdump......................................... 87
9.2.3 save-tracepoints filename.................... 88
9.3 Convenience Variables for Tracepoints ................... 88
iii
10 Debugging Programs That Use Overlays .. 91
10.1 How Overlays Work................................... 91
10.2 Overlay Commands ................................... 92
10.3 Automatic Overlay Debugging ......................... 94
10.4 Overlay Sample Program.............................. 95
11 Using GDB with Different Languages..... 97
11.1 Switching between source languages .................... 97
11.1.1 List of filename extensions and languages....... 97
11.1.2 Setting the working language.................. 98
11.1.3 Having GDB infer the source language......... 98
11.2 Displaying the language ............................... 98
11.3 Type and range checking .............................. 99
11.3.1 An overview of type checking.................. 99
11.3.2 An overview of range checking................ 100
11.4 Supported languages ................................. 101
11.4.1 C and C++.................................. 102
11.4.1.1 C and C++ operators................ 102
11.4.1.2 C and C++ constants................ 104
11.4.1.3 C++ expressions..................... 104
11.4.1.4 C and C++ defaults ................. 105
11.4.1.5 C and C++ type and range checks.... 105
11.4.1.6 GDB and C........................ 106
11.4.1.7 GDB features for C++............... 106
11.4.2 Modula-2................................... 107
11.4.2.1 Operators.......................... 107
11.4.2.2 Built-in functions and procedures .... 109
11.4.2.3 Constants.......................... 110
11.4.2.4 Modula-2 defaults................... 110
11.4.2.5 Deviations from standard Modula-2.. 110
11.4.2.6 Modula-2 type and range checks ..... 111
11.4.2.7 The scope operators :: and ......... 111
11.4.2.8 GDB and Modula-2................. 111
11.4.3 Chill ....................................... 112
11.4.3.1 How modes are displayed............ 112
11.4.3.2 Locations and their accesses......... 114
11.4.3.3 Values and their Operations ......... 114
11.4.3.4 Chill type and range checks.......... 116
11.4.3.5 Chill defaults....................... 117
12 Examining the Symbol Table............ 119
iv Debugging with GDB
13 Altering Execution ..................... 123
13.1 Assignment to variables .............................. 123
13.2 Continuing at a different address...................... 124
13.3 Giving your program a signal ......................... 125
13.4 Returning from a function............................ 125
13.5 Calling program functions ............................ 126
13.6 Patching programs................................... 126
14 GDB Files ............................. 127
14.1 Commands to specify files ............................ 127
14.2 Errors reading symbol files............................ 132
15 Specifying a Debugging Target .......... 135
15.1 Active targets........................................ 135
15.2 Commands for managing targets...................... 135
15.3 Choosing target byte order............................ 137
15.4 Remote debugging ................................... 137
15.5 Kernel Object Display................................ 138
16 Debugging remote programs ............ 139
16.1 Using the gdbserver program......................... 139
16.2 Using the gdbserve.nlm program..................... 140
16.3 Implementing a remote stub .......................... 141
16.3.1 What the stub can do for you ................ 142
16.3.2 What you must do for the stub............... 142
16.3.3 Putting it all together ....................... 144
17 Configuration-Specific Information....... 147
17.1 Native .............................................. 147
17.1.1 HP-UX..................................... 147
17.1.2 SVR4 process information.................... 147
17.1.3 Features for Debugging djgpp Programs...... 147
17.1.4 Features for Debugging MS Windows PE
executables..................................... 149
17.2 Embedded Operating Systems......................... 150
17.2.1 Using GDB with VxWorks................... 150
17.2.1.1 Connecting to VxWorks............. 151
17.2.1.2 VxWorks download ................. 151
17.2.1.3 Running tasks...................... 152
17.3 Embedded Processors ................................ 152
17.3.1 ARM....................................... 152
17.3.2 Hitachi H8/300.............................. 152
17.3.2.1 Connecting to Hitachi boards........ 153
17.3.2.2 Using the E7000 in-circuit emulator.. 154
17.3.2.3 Special GDB commands for Hitachi micros
........................................ 155
17.3.3 H8/500..................................... 155
v
17.3.4 Intel i960................................... 155
17.3.4.1 Startup with Nindy................. 156
17.3.4.2 Options for Nindy .................. 156
17.3.4.3 Nindy reset command............... 156
17.3.5 Mitsubishi M32R/D......................... 156
17.3.6 M68k....................................... 157
17.3.7 M88K...................................... 157
17.3.8 MIPS Embedded............................ 157
17.3.9 PowerPC ................................... 159
17.3.10 HP PA Embedded.......................... 159
17.3.11 Hitachi SH................................. 159
17.3.12 Tsqware Sparclet........................... 160
17.3.12.1 Setting file to debug................ 160
17.3.12.2 Connecting to Sparclet............. 160
17.3.12.3 Sparclet download ................. 161
17.3.12.4 Running and debugging............ 161
17.3.13 Fujitsu Sparclite............................ 161
17.3.14 Tandem ST2000............................ 161
17.3.15 Zilog Z8000................................ 162
17.4 Architectures........................................ 163
17.4.1 A29K....................................... 163
17.4.2 Alpha ...................................... 163
17.4.3 MIPS....................................... 163
18 Controlling GDB ....................... 165
18.1 Prompt ............................................. 165
18.2 Command editing.................................... 165
18.3 Command history.................................... 165
18.4 Screen size........................................... 167
18.5 Numbers............................................ 167
18.6 Optional warnings and messages ...................... 168
18.7 Optional messages about internal happenings........... 169
19 Canned Sequences of Commands ........ 171
19.1 User-defined commands............................... 171
19.2 User-defined command hooks ......................... 172
19.3 Command files....................................... 173
19.4 Commands for controlled output...................... 174
20 GDB Text User Interface ............... 177
20.1 TUI overview........................................ 177
20.2 TUI Key Bindings ................................... 177
20.3 TUI specific commands............................... 178
20.4 TUI configuration variables........................... 179
21 Using GDB under gnu Emacs ........... 181
vi Debugging with GDB
22 GDB Annotations ...................... 183
22.1 What is an Annotation?.............................. 183
22.2 The Server Prefix.................................... 183
22.3 Values............................................... 184
22.4 Frames.............................................. 185
22.5 Displays............................................. 187
22.6 Annotation for GDB Input............................ 187
22.7 Errors............................................... 188
22.8 Information on Breakpoints........................... 188
22.9 Invalidation Notices.................................. 189
22.10 Running the Program............................... 189
22.11 Displaying Source................................... 190
22.12 Annotations We Might Want in the Future............ 190
23 The gdb/mi Interface ................... 191
Function and Purpose...................................... 191
Notation and Terminology.................................. 191
23.1 gdb/mi Command Syntax............................ 191
23.1.1 gdb/mi Input Syntax........................ 191
23.1.2 gdb/mi Output Syntax...................... 192
23.1.3 Simple Examples of gdb/mi Interaction....... 194
23.2 gdb/mi Compatibility with CLI....................... 195
23.3 gdb/mi Output Records.............................. 195
23.3.1 gdb/mi Result Records...................... 195
23.3.2 gdb/mi Stream Records ..................... 195
23.3.3 gdb/mi Out-of-band Records................. 196
23.4 gdb/mi Command Description Format ................ 196
23.5 gdb/mi Breakpoint table commands................... 197
23.6 gdb/mi Data Manipulation........................... 205
23.7 gdb/mi Program control ............................. 215
23.8 Miscellaneous GDB commands in gdb/mi.............. 225
23.9 gdb/mi Stack Manipulation Commands ............... 227
23.10 gdb/mi Symbol Query Commands................... 232
23.11 gdb/mi Target Manipulation Commands............. 235
23.12 gdb/mi Thread Commands.......................... 240
23.13 gdb/mi Tracepoint Commands....................... 242
23.14 gdb/mi Variable Objects............................ 242
24 Reporting Bugs in GDB ................ 247
24.1 Have you found a bug?............................... 247
24.2 How to report bugs .................................. 247
vii
25 Command Line Editing ................. 251
25.1 Introduction to Line Editing.......................... 251
25.2 Readline Interaction.................................. 251
25.2.1 Readline Bare Essentials..................... 251
25.2.2 Readline Movement Commands............... 252
25.2.3 Readline Killing Commands.................. 252
25.2.4 Readline Arguments......................... 253
25.2.5 Searching for Commands in the History....... 253
25.3 Readline Init File.................................... 254
25.3.1 Readline Init File Syntax..................... 254
25.3.2 Conditional Init Constructs .................. 258
25.3.3 Sample Init File............................. 259
25.4 Bindable Readline Commands......................... 262
25.4.1 Commands For Moving...................... 262
25.4.2 Commands For Manipulating The History..... 262
25.4.3 Commands For Changing Text ............... 263
25.4.4 Killing And Yanking......................... 264
25.4.5 Specifying Numeric Arguments............... 265
25.4.6 Letting Readline Type For You............... 266
25.4.7 Keyboard Macros............................ 266
25.4.8 Some Miscellaneous Commands............... 267
25.5 Readline vi Mode.................................... 268
26 Using History Interactively.............. 269
26.1 History Expansion ................................... 269
26.1.1 Event Designators........................... 269
26.1.2 Word Designators ........................... 270
26.1.3 Modifiers ................................... 270
Appendix A Formatting Documentation .... 273
Appendix B Installing GDB................ 275
B.1 Compiling GDB in another directory................... 276
B.2 Specifying names for hosts and targets ................. 277
B.3 configure options.................................... 277
Appendix C Maintenance Commands....... 279
Appendix D GDB Remote Serial Protocol .. 281
Appendix E GNU GENERAL PUBLIC
LICENSE.............................. 293
Preamble.................................................. 293
TERMS AND CONDITIONS FOR COPYING,
DISTRIBUTION AND MODIFICATION ............... 294
How to Apply These Terms to Your New Programs........... 298