Debugging with GDB: The GNU source-level debugger (GNU manuals) by Richard Stallman (2011-05-03)

794 Pages·2011·2.458 MB·English

by  Richard Stallman, Roland Pesch, et al Stan Shebs

gdb
Debugging with
The gnu Source-Level Debugger
Tenth Edition, for gdb version 7.12.50.20161008-git
(GDB)
Richard Stallman, Roland Pesch, Stan Shebs, et al.
(Send bugs and comments on gdb to http://www.gnu.org/software/gdb/bugs/.)
Debugging with gdb
TEXinfo 2011-02-14.11
Published by the Free Software Foundation
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
ISBN 978-0-9831592-3-0
Copyright (cid:13)c 1988-2016 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms
of the GNU Free Documentation License, Version 1.3 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 FSF’s Back-Cover Text is: “You are free to copy and modify this GNU Man-
ual. Buying copies from GNU Press supports the FSF in developing GNU and promoting
software freedom.”
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.1.3 What gdb Does During Startup.......................... 16
2.2 Quitting gdb................................................. 17
2.3 Shell Commands.............................................. 17
2.4 Logging Output............................................... 18
3 gdb Commands................................ 19
3.1 Command Syntax............................................. 19
3.2 Command Completion........................................ 19
3.3 Getting Help.................................................. 22
4 Running Programs Under gdb ............... 25
4.1 Compiling for Debugging...................................... 25
4.2 Starting your Program........................................ 26
4.3 Your Program’s Arguments ................................... 30
4.4 Your Program’s Environment.................................. 30
4.5 Your Program’s Working Directory............................ 31
4.6 Your Program’s Input and Output ............................ 32
4.7 Debugging an Already-running Process........................ 32
4.8 Killing the Child Process...................................... 33
4.9 Debugging Multiple Inferiors and Programs.................... 33
4.10 Debugging Programs with Multiple Threads.................. 36
4.11 Debugging Forks............................................. 40
4.12 Setting a Bookmark to Return to Later....................... 43
4.12.1 A Non-obvious Benefit of Using Checkpoints............. 44
ii Debugging with gdb
5 Stopping and Continuing ..................... 45
5.1 Breakpoints, Watchpoints, and Catchpoints ................... 45
5.1.1 Setting Breakpoints...................................... 46
5.1.2 Setting Watchpoints...................................... 52
5.1.3 Setting Catchpoints...................................... 54
5.1.4 Deleting Breakpoints..................................... 59
5.1.5 Disabling Breakpoints.................................... 60
5.1.6 Break Conditions......................................... 61
5.1.7 Breakpoint Command Lists .............................. 62
5.1.8 Dynamic Printf .......................................... 64
5.1.9 How to save breakpoints to a file......................... 65
5.1.10 Static Probe Points..................................... 65
5.1.11 “Cannot insert breakpoints”............................. 67
5.1.12 “Breakpoint address adjusted...” ........................ 67
5.2 Continuing and Stepping...................................... 68
5.3 Skipping Over Functions and Files ............................ 71
5.4 Signals........................................................ 74
5.5 Stopping and Starting Multi-thread Programs................. 77
5.5.1 All-Stop Mode........................................... 77
5.5.2 Non-Stop Mode.......................................... 78
5.5.3 Background Execution ................................... 79
5.5.4 Thread-Specific Breakpoints.............................. 80
5.5.5 Interrupted System Calls................................. 81
5.5.6 Observer Mode........................................... 82
6 Running programs backward................. 85
7 Recording Inferior’s Execution and Replaying
It .............................................. 87
8 Examining the Stack.......................... 95
8.1 Stack Frames ................................................. 95
8.2 Backtraces.................................................... 96
8.3 Selecting a Frame............................................. 98
8.4 Information About a Frame................................... 99
8.5 Management of Frame Filters................................. 100
iii
9 Examining Source Files...................... 103
9.1 Printing Source Lines........................................ 103
9.2 Specifying a Location........................................ 104
9.2.1 Linespec Locations...................................... 104
9.2.2 Explicit Locations....................................... 105
9.2.3 Address Locations....................................... 106
9.3 Editing Source Files.......................................... 106
9.3.1 Choosing your Editor................................... 107
9.4 Searching Source Files....................................... 107
9.5 Specifying Source Directories................................. 107
9.6 Source and Machine Code.................................... 110
10 Examining Data............................. 115
10.1 Expressions................................................. 117
10.2 Ambiguous Expressions..................................... 118
10.3 Program Variables.......................................... 119
10.4 Artificial Arrays............................................ 121
10.5 Output Formats............................................ 122
10.6 Examining Memory......................................... 123
10.7 Automatic Display.......................................... 126
10.8 Print Settings............................................... 127
10.9 Pretty Printing............................................. 135
10.9.1 Pretty-Printer Introduction ............................ 136
10.9.2 Pretty-Printer Example................................ 136
10.9.3 Pretty-Printer Commands.............................. 137
10.10 Value History.............................................. 138
10.11 Convenience Variables..................................... 139
10.12 Convenience Functions..................................... 141
10.13 Registers.................................................. 144
10.14 Floating Point Hardware................................... 146
10.15 Vector Unit................................................ 146
10.16 Operating System Auxiliary Information................... 146
10.17 Memory Region Attributes................................. 148
10.17.1 Attributes............................................ 149
10.17.1.1 Memory Access Mode............................ 149
10.17.1.2 Memory Access Size.............................. 149
10.17.1.3 Data Cache...................................... 149
10.17.2 Memory Access Checking............................. 150
10.18 Copy Between Memory and a File ......................... 150
10.19 How to Produce a Core File from Your Program........... 151
10.20 Character Sets............................................. 152
10.21 Caching Data of Targets................................... 154
10.22 Search Memory............................................ 156
10.23 Value Sizes................................................ 157
11 Debugging Optimized Code................ 159
11.1 Inline Functions ............................................ 159
11.2 Tail Call Frames............................................ 160
iv Debugging with gdb
12 C Preprocessor Macros..................... 163
13 Tracepoints.................................. 167
13.1 Commands to Set Tracepoints .............................. 167
13.1.1 Create and Delete Tracepoints ......................... 168
13.1.2 Enable and Disable Tracepoints........................ 170
13.1.3 Tracepoint Passcounts ................................. 170
13.1.4 Tracepoint Conditions.................................. 171
13.1.5 Trace State Variables .................................. 171
13.1.6 Tracepoint Action Lists................................ 172
13.1.7 Listing Tracepoints .................................... 174
13.1.8 Listing Static Tracepoint Markers...................... 175
13.1.9 Starting and Stopping Trace Experiments.............. 176
13.1.10 Tracepoint Restrictions............................... 178
13.2 Using the Collected Data ................................... 179
13.2.1 tfind n................................................ 179
13.2.2 tdump.................................................. 181
13.2.3 save tracepoints filename........................... 182
13.3 Convenience Variables for Tracepoints....................... 182
13.4 Using Trace Files........................................... 183
14 Debugging Programs That Use Overlays
............................................... 185
14.1 How Overlays Work......................................... 185
14.2 Overlay Commands......................................... 186
14.3 Automatic Overlay Debugging.............................. 188
14.4 Overlay Sample Program ................................... 189
15 Using gdb with Different Languages ...... 191
15.1 Switching Between Source Languages ....................... 191
15.1.1 List of Filename Extensions and Languages............. 191
15.1.2 Setting the Working Language......................... 192
15.1.3 Having gdb Infer the Source Language................. 192
15.2 Displaying the Language.................................... 192
15.3 Type and Range Checking.................................. 193
15.3.1 An Overview of Type Checking ........................ 193
15.3.2 An Overview of Range Checking....................... 194
15.4 Supported Languages....................................... 195
15.4.1 C and C++............................................. 195
15.4.1.1 C and C++ Operators............................. 195
15.4.1.2 C and C++ Constants............................. 197
15.4.1.3 C++ Expressions .................................. 198
15.4.1.4 C and C++ Defaults............................... 199
15.4.1.5 C and C++ Type and Range Checks............... 199
15.4.1.6 gdb and C........................................ 199
15.4.1.7 gdb Features for C++............................. 199
15.4.1.8 Decimal Floating Point format.................... 201
v
15.4.2 D...................................................... 201
15.4.3 Go..................................................... 201
15.4.4 Objective-C............................................ 202
15.4.4.1 Method Names in Commands..................... 202
15.4.4.2 The Print Command With Objective-C............ 202
15.4.5 OpenCL C............................................. 203
15.4.5.1 OpenCL C Datatypes............................. 203
15.4.5.2 OpenCL C Expressions............................ 203
15.4.5.3 OpenCL C Operators............................. 203
15.4.6 Fortran................................................ 203
15.4.6.1 Fortran Operators and Expressions................ 203
15.4.6.2 Fortran Defaults.................................. 203
15.4.6.3 Special Fortran Commands........................ 204
15.4.7 Pascal................................................. 204
15.4.8 Rust................................................... 204
15.4.9 Modula-2.............................................. 205
15.4.9.1 Operators......................................... 205
15.4.9.2 Built-in Functions and Procedures................. 206
15.4.9.3 Constants......................................... 207
15.4.9.4 Modula-2 Types................................... 208
15.4.9.5 Modula-2 Defaults................................ 210
15.4.9.6 Deviations from Standard Modula-2............... 210
15.4.9.7 Modula-2 Type and Range Checks................. 210
15.4.9.8 The Scope Operators :: and ..................... 210
15.4.9.9 gdb and Modula-2................................ 211
15.4.10 Ada.................................................. 211
15.4.10.1 Introduction..................................... 211
15.4.10.2 Omissions from Ada ............................. 212
15.4.10.3 Additions to Ada ................................ 213
15.4.10.4 Overloading support for Ada..................... 214
15.4.10.5 Stopping at the Very Beginning.................. 215
15.4.10.6 Ada Exceptions.................................. 215
15.4.10.7 Extensions for Ada Tasks........................ 215
15.4.10.8 Tasking Support when Debugging Core Files..... 218
15.4.10.9 Tasking Support when using the Ravenscar Profile
........................................................ 219
15.4.10.10 Known Peculiarities of Ada Mode............... 219
15.5 Unsupported Languages .................................... 220
16 Examining the Symbol Table .............. 221
vi Debugging with gdb
17 Altering Execution.......................... 229
17.1 Assignment to Variables .................................... 229
17.2 Continuing at a Different Address........................... 230
17.3 Giving your Program a Signal............................... 231
17.4 Returning from a Function.................................. 232
17.5 Calling Program Functions.................................. 233
17.6 Patching Programs ......................................... 234
17.7 Compiling and injecting code in gdb........................ 234
17.7.1 Compilation options for the compile command......... 236
17.7.2 Caveats when using the compile command............. 236
17.7.3 Compiler search for the compile command............. 238
18 gdb Files..................................... 241
18.1 Commands to Specify Files................................. 241
18.2 File Caching................................................ 249
18.3 Debugging Information in Separate Files.................... 250
18.4 Debugging information in a special section.................. 253
18.5 Index Files Speed Up gdb.................................. 254
18.6 Errors Reading Symbol Files................................ 255
18.7 GDB Data Files............................................ 256
19 Specifying a Debugging Target ............ 257
19.1 Active Targets.............................................. 257
19.2 Commands for Managing Targets........................... 257
19.3 Choosing Target Byte Order................................ 259
20 Debugging Remote Programs.............. 261
20.1 Connecting to a Remote Target............................. 261
20.1.1 Types of Remote Connections.......................... 261
20.1.2 Host and Target Files.................................. 262
20.1.3 Remote Connection Commands........................ 263
20.2 Sending files to a remote system ............................ 264
20.3 Using the gdbserver Program.............................. 265
20.3.1 Running gdbserver.................................... 265
20.3.1.1 Attaching to a Running Program.................. 266
20.3.1.2 TCP port allocation lifecycle of gdbserver........ 266
20.3.1.3 Other Command-Line Arguments for gdbserver... 267
20.3.2 Connecting to gdbserver.............................. 267
20.3.3 Monitor Commands for gdbserver..................... 268
20.3.4 Tracepoints support in gdbserver...................... 269
20.4 Remote Configuration....................................... 270
20.5 Implementing a Remote Stub............................... 275
20.5.1 What the Stub Can Do for You........................ 276
20.5.2 What You Must Do for the Stub....................... 277
20.5.3 Putting it All Together................................. 278
vii
21 Configuration-Specific Information........ 281
21.1 Native...................................................... 281
21.1.1 BSD libkvm Interface.................................. 281
21.1.2 SVR4 Process Information............................. 281
21.1.3 Features for Debugging djgpp Programs............... 283
21.1.4 Features for Debugging MS Windows PE Executables .. 285
21.1.4.1 Support for DLLs without Debugging Symbols..... 287
21.1.4.2 DLL Name Prefixes............................... 287
21.1.4.3 Working with Minimal Symbols................... 288
21.1.5 Commands Specific to gnu Hurd Systems.............. 288
21.1.6 Darwin................................................ 291
21.2 Embedded Operating Systems .............................. 291
21.3 Embedded Processors....................................... 291
21.3.1 Synopsys ARC......................................... 292
21.3.2 ARM.................................................. 292
21.3.3 M68k.................................................. 293
21.3.4 MicroBlaze ............................................ 293
21.3.5 MIPS Embedded....................................... 294
21.3.6 PowerPC Embedded................................... 294
21.3.7 Atmel AVR............................................ 295
21.3.8 CRIS.................................................. 296
21.3.9 Renesas Super-H....................................... 296
21.4 Architectures............................................... 296
21.4.1 AArch64............................................... 297
21.4.2 x86 Architecture-specific Issues......................... 297
21.4.2.1 Intel Memory Protection Extensions (MPX)....... 297
21.4.3 Alpha.................................................. 298
21.4.4 MIPS.................................................. 298
21.4.5 HPPA................................................. 299
21.4.6 Cell Broadband Engine SPU architecture............... 300
21.4.7 PowerPC.............................................. 301
21.4.8 Nios II................................................. 301
22 Controlling gdb ............................. 303
22.1 Prompt..................................................... 303
22.2 Command Editing.......................................... 303
22.3 Command History.......................................... 304
22.4 Screen Size................................................. 305
22.5 Numbers ................................................... 306
22.6 Configuring the Current ABI................................ 307
22.7 Automatically loading associated files....................... 308
22.7.1 Automatically loading init file in the current directory.. 310
22.7.2 Automatically loading thread debugging library ........ 310
22.7.3 Security restriction for auto-loading.................... 311
22.7.4 Displaying files tried for auto-load...................... 312
22.8 Optional Warnings and Messages............................ 313
22.9 Optional Messages about Internal Happenings............... 314
22.10 Other Miscellaneous Settings............................... 319
viii Debugging with gdb
23 Extending gdb .............................. 321
23.1 Canned Sequences of Commands............................ 321
23.1.1 User-defined Commands ............................... 321
23.1.2 User-defined Command Hooks.......................... 323
23.1.3 Command Files........................................ 324
23.1.4 Commands for Controlled Output...................... 325
23.1.5 Controlling auto-loading native gdb scripts............. 327
23.2 Extending gdb using Python ............................... 327
23.2.1 Python Commands .................................... 328
23.2.2 Python API ........................................... 329
23.2.2.1 Basic Python ..................................... 329
23.2.2.2 Exception Handling............................... 332
23.2.2.3 Values From Inferior.............................. 333
23.2.2.4 Types In Python.................................. 338
23.2.2.5 Pretty Printing API............................... 342
23.2.2.6 Selecting Pretty-Printers.......................... 343
23.2.2.7 Writing a Pretty-Printer .......................... 344
23.2.2.8 Type Printing API................................ 346
23.2.2.9 Filtering Frames................................... 347
23.2.2.10 Decorating Frames............................... 349
23.2.2.11 Writing a Frame Filter........................... 352
23.2.2.12 Unwinding Frames in Python .................... 356
23.2.2.13 Xmethods In Python............................. 358
23.2.2.14 Xmethod API.................................... 359
23.2.2.15 Writing an Xmethod............................. 360
23.2.2.16 Inferiors In Python............................... 363
23.2.2.17 Events In Python................................ 364
23.2.2.18 Threads In Python............................... 368
23.2.2.19 Commands In Python............................ 369
23.2.2.20 Parameters In Python............................ 372
23.2.2.21 Writing new convenience functions............... 374
23.2.2.22 Program Spaces In Python....................... 375
23.2.2.23 Objfiles In Python............................... 376
23.2.2.24 Accessing inferior stack frames from Python...... 379
23.2.2.25 Accessing blocks from Python.................... 381
23.2.2.26 Python representation of Symbols. ............... 383
23.2.2.27 Symbol table representation in Python............ 386
23.2.2.28 Manipulating line tables using Python............ 388
23.2.2.29 Manipulating breakpoints using Python.......... 389
23.2.2.30 Finish Breakpoints............................... 392
23.2.2.31 Python representation of lazy strings. ............ 392
23.2.2.32 Python representation of architectures............ 393
23.2.3 Python Auto-loading................................... 394
23.2.4 Python modules ....................................... 394
23.2.4.1 gdb.printing....................................... 395
23.2.4.2 gdb.types......................................... 395
23.2.4.3 gdb.prompt....................................... 396
23.3 Extending gdb using Guile ................................. 397