Debugging with GDB
This file documents the GNU debugger GDB.
This is the Tenth Edition, of Debugging with GDB: the GNU Source-Level Debugger for GDB (GDB) Version 8.3.50.20190730-git.
Copyright © 1988-2019 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 Software Needs Free Documentation”, with the Front-Cover Texts being “A GNU Manual,” 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 Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom.”
Next: Summary, Previous: (dir), Up: (dir) [Contents][Index]
Debugging with GDB
This file describes GDB, the GNU symbolic debugger.
This is the Tenth Edition, for GDB (GDB) Version 8.3.50.20190730-git.
Copyright (C) 1988-2019 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred Fish. Fred was a long-standing contributor to GDB and to Free software in general. We will miss him.
• Summary: | Summary of GDB | |
• Sample Session: | A sample GDB session | |
| ||
---|---|---|
• Invocation: | Getting in and out of GDB | |
• Commands: | GDB commands | |
• Running: | Running programs under GDB | |
• Stopping: | Stopping and continuing | |
• Reverse Execution: | Running programs backward | |
• Process Record and Replay: | Recording inferior’s execution and replaying it | |
• Stack: | Examining the stack | |
• Source: | Examining source files | |
• Data: | Examining data | |
• Optimized Code: | Debugging optimized code | |
• Macros: | Preprocessor Macros | |
• Tracepoints: | Debugging remote targets non-intrusively | |
• Overlays: | Debugging programs that use overlays | |
| ||
• Languages: | Using GDB with different languages | |
| ||
• Symbols: | Examining the symbol table | |
• Altering: | Altering execution | |
• GDB Files: | GDB files | |
• Targets: | Specifying a debugging target | |
• Remote Debugging: | Debugging remote programs | |
• Configurations: | Configuration-specific information | |
• Controlling GDB: | Controlling GDB | |
• Extending GDB: | Extending GDB | |
• Interpreters: | Command Interpreters | |
• TUI: | GDB Text User Interface | |
• Emacs: | Using GDB under GNU Emacs | |
• GDB/MI: | GDB’s Machine Interface. | |
• Annotations: | GDB’s annotation interface. | |
• JIT Interface: | Using the JIT debugging interface. | |
• In-Process Agent: | In-Process Agent | |
| ||
• GDB Bugs: | Reporting bugs in GDB | |
| ||
• Command Line Editing: | Command Line Editing | |
• Using History Interactively: | Using History Interactively | |
• In Memoriam: | In Memoriam | |
• Formatting Documentation: | How to format and print GDB documentation | |
• Installing GDB: | Installing GDB | |
• Maintenance Commands: | Maintenance Commands | |
• Remote Protocol: | GDB Remote Serial Protocol | |
• Agent Expressions: | The GDB Agent Expression Mechanism | |
• Target Descriptions: | How targets can describe themselves to GDB | |
• Operating System Information: | Getting additional information from the operating system | |
• Trace File Format: | GDB trace file format | |
• Index Section Format: | .gdb_index section format | |
• Man Pages: | Manual pages | |
• Copying: | GNU General Public License says how you can copy and share GDB | |
• GNU Free Documentation License: | The license for this documentation | |
• Concept Index: | Index of GDB concepts | |
• Command and Variable Index: | Index of GDB commands, variables, functions, and Python data types |
Table of Contents
- Summary of GDB
- 1 A Sample GDB Session
- 2 Getting In and Out of GDB
- 3 GDB Commands
- 4 Running Programs Under GDB
- 4.1 Compiling for Debugging
- 4.2 Starting your Program
- 4.3 Your Program’s Arguments
- 4.4 Your Program’s Environment
- 4.5 Your Program’s Working Directory
- 4.6 Your Program’s Input and Output
- 4.7 Debugging an Already-running Process
- 4.8 Killing the Child Process
- 4.9 Debugging Multiple Inferiors and Programs
- 4.10 Debugging Programs with Multiple Threads
- 4.11 Debugging Forks
- 4.12 Setting a Bookmark to Return to Later
- 5 Stopping and Continuing
- 5.1 Breakpoints, Watchpoints, and Catchpoints
- 5.1.1 Setting Breakpoints
- 5.1.2 Setting Watchpoints
- 5.1.3 Setting Catchpoints
- 5.1.4 Deleting Breakpoints
- 5.1.5 Disabling Breakpoints
- 5.1.6 Break Conditions
- 5.1.7 Breakpoint Command Lists
- 5.1.8 Dynamic Printf
- 5.1.9 How to save breakpoints to a file
- 5.1.10 Static Probe Points
- 5.1.11 “Cannot insert breakpoints”
- 5.1.12 “Breakpoint address adjusted...”
- 5.2 Continuing and Stepping
- 5.3 Skipping Over Functions and Files
- 5.4 Signals
- 5.5 Stopping and Starting Multi-thread Programs
- 5.1 Breakpoints, Watchpoints, and Catchpoints
- 6 Running programs backward
- 7 Recording Inferior’s Execution and Replaying It
- 8 Examining the Stack
- 9 Examining Source Files
- 10 Examining Data
- 10.1 Expressions
- 10.2 Ambiguous Expressions
- 10.3 Program Variables
- 10.4 Artificial Arrays
- 10.5 Output Formats
- 10.6 Examining Memory
- 10.7 Automatic Display
- 10.8 Print Settings
- 10.9 Pretty Printing
- 10.10 Value History
- 10.11 Convenience Variables
- 10.12 Convenience Functions
- 10.13 Registers
- 10.14 Floating Point Hardware
- 10.15 Vector Unit
- 10.16 Operating System Auxiliary Information
- 10.17 Memory Region Attributes
- 10.18 Copy Between Memory and a File
- 10.19 How to Produce a Core File from Your Program
- 10.20 Character Sets
- 10.21 Caching Data of Targets
- 10.22 Search Memory
- 10.23 Value Sizes
- 11 Debugging Optimized Code
- 12 C Preprocessor Macros
- 13 Tracepoints
- 13.1 Commands to Set Tracepoints
- 13.1.1 Create and Delete Tracepoints
- 13.1.2 Enable and Disable Tracepoints
- 13.1.3 Tracepoint Passcounts
- 13.1.4 Tracepoint Conditions
- 13.1.5 Trace State Variables
- 13.1.6 Tracepoint Action Lists
- 13.1.7 Listing Tracepoints
- 13.1.8 Listing Static Tracepoint Markers
- 13.1.9 Starting and Stopping Trace Experiments
- 13.1.10 Tracepoint Restrictions
- 13.2 Using the Collected Data
- 13.3 Convenience Variables for Tracepoints
- 13.4 Using Trace Files
- 13.1 Commands to Set Tracepoints
- 14 Debugging Programs That Use Overlays
- 15 Using GDB with Different Languages
- 15.1 Switching Between Source Languages
- 15.2 Displaying the Language
- 15.3 Type and Range Checking
- 15.4 Supported Languages
- 15.4.1 C and C++
- 15.4.2 D
- 15.4.3 Go
- 15.4.4 Objective-C
- 15.4.5 OpenCL C
- 15.4.6 Fortran
- 15.4.7 Pascal
- 15.4.8 Rust
- 15.4.9 Modula-2
- 15.4.10 Ada
- 15.4.10.1 Introduction
- 15.4.10.2 Omissions from Ada
- 15.4.10.3 Additions to Ada
- 15.4.10.4 Overloading support for Ada
- 15.4.10.5 Stopping at the Very Beginning
- 15.4.10.6 Ada Exceptions
- 15.4.10.7 Extensions for Ada Tasks
- 15.4.10.8 Tasking Support when Debugging Core Files
- 15.4.10.9 Tasking Support when using the Ravenscar Profile
- 15.4.10.10 Ada Settings
- 15.4.10.11 Known Peculiarities of Ada Mode
- 15.5 Unsupported Languages
- 16 Examining the Symbol Table
- 17 Altering Execution
- 18 GDB Files
- 19 Specifying a Debugging Target
- 20 Debugging Remote Programs
- 21 Configuration-Specific Information
- 21.1 Native
- 21.2 Embedded Operating Systems
- 21.3 Embedded Processors
- 21.4 Architectures
- 22 Controlling GDB
- 23 Extending GDB
- 23.1 Canned Sequences of Commands
- 23.2 Extending GDB using Python
- 23.2.1 Python Commands
- 23.2.2 Python API
- 23.2.2.1 Basic Python
- 23.2.2.2 Exception Handling
- 23.2.2.3 Values From Inferior
- 23.2.2.4 Types In Python
- 23.2.2.5 Pretty Printing API
- 23.2.2.6 Selecting Pretty-Printers
- 23.2.2.7 Writing a Pretty-Printer
- 23.2.2.8 Type Printing API
- 23.2.2.9 Filtering Frames
- 23.2.2.10 Decorating Frames
- 23.2.2.11 Writing a Frame Filter
- 23.2.2.12 Unwinding Frames in Python
- 23.2.2.13 Xmethods In Python
- 23.2.2.14 Xmethod API
- 23.2.2.15 Writing an Xmethod
- 23.2.2.16 Inferiors In Python
- 23.2.2.17 Events In Python
- 23.2.2.18 Threads In Python
- 23.2.2.19 Recordings In Python
- 23.2.2.20 Commands In Python
- 23.2.2.21 Parameters In Python
- 23.2.2.22 Writing new convenience functions
- 23.2.2.23 Program Spaces In Python
- 23.2.2.24 Objfiles In Python
- 23.2.2.25 Accessing inferior stack frames from Python
- 23.2.2.26 Accessing blocks from Python
- 23.2.2.27 Python representation of Symbols
- 23.2.2.28 Symbol table representation in Python
- 23.2.2.29 Manipulating line tables using Python
- 23.2.2.30 Manipulating breakpoints using Python
- 23.2.2.31 Finish Breakpoints
- 23.2.2.32 Python representation of lazy strings
- 23.2.2.33 Python representation of architectures
- 23.2.3 Python Auto-loading
- 23.2.4 Python modules
- 23.3 Extending GDB using Guile
- 23.3.1 Guile Introduction
- 23.3.2 Guile Commands
- 23.3.3 Guile API
- 23.3.3.1 Basic Guile
- 23.3.3.2 Guile Configuration
- 23.3.3.3 GDB Scheme Data Types
- 23.3.3.4 Guile Exception Handling
- 23.3.3.5 Values From Inferior In Guile
- 23.3.3.6 Arithmetic In Guile
- 23.3.3.7 Types In Guile
- 23.3.3.8 Guile Pretty Printing API
- 23.3.3.9 Selecting Guile Pretty-Printers
- 23.3.3.10 Writing a Guile Pretty-Printer
- 23.3.3.11 Commands In Guile
- 23.3.3.12 Parameters In Guile
- 23.3.3.13 Program Spaces In Guile
- 23.3.3.14 Objfiles In Guile
- 23.3.3.15 Accessing inferior stack frames from Guile.
- 23.3.3.16 Accessing blocks from Guile.
- 23.3.3.17 Guile representation of Symbols.
- 23.3.3.18 Symbol table representation in Guile.
- 23.3.3.19 Manipulating breakpoints using Guile
- 23.3.3.20 Guile representation of lazy strings.
- 23.3.3.21 Guile representation of architectures
- 23.3.3.22 Disassembly In Guile
- 23.3.3.23 I/O Ports in Guile
- 23.3.3.24 Memory Ports in Guile
- 23.3.3.25 Iterators In Guile
- 23.3.4 Guile Auto-loading
- 23.3.5 Guile Modules
- 23.4 Auto-loading extensions
- 23.5 Multiple Extension Languages
- 23.6 Creating new spellings of existing commands
- 24 Command Interpreters
- 25 GDB Text User Interface
- 26 Using GDB under GNU Emacs
- 27 The GDB/MI Interface
- Function and Purpose
- Notation and Terminology
- 27.1 GDB/MI General Design
- 27.2 GDB/MI Command Syntax
- 27.3 GDB/MI Compatibility with CLI
- 27.4 GDB/MI Development and Front Ends
- 27.5 GDB/MI Output Records
- 27.6 Simple Examples of GDB/MI Interaction
- 27.7 GDB/MI Command Description Format
- 27.8 GDB/MI Breakpoint Commands
- 27.9 GDB/MI Catchpoint Commands
- 27.10 GDB/MI Program Context
- 27.11 GDB/MI Thread Commands
- 27.12 GDB/MI Ada Tasking Commands
- 27.13 GDB/MI Program Execution
- 27.14 GDB/MI Stack Manipulation Commands
- 27.15 GDB/MI Variable Objects
- 27.16 GDB/MI Data Manipulation
- 27.17 GDB/MI Tracepoint Commands
- 27.18 GDB/MI Symbol Query Commands
- 27.19 GDB/MI File Commands
- 27.20 GDB/MI Target Manipulation Commands
- 27.21 GDB/MI File Transfer Commands
- 27.22 Ada Exceptions GDB/MI Commands
- 27.23 GDB/MI Support Commands
- 27.24 Miscellaneous GDB/MI Commands
- 28 GDB Annotations
- 29 JIT Compilation Interface
- 30 In-Process Agent
- 31 Reporting Bugs in GDB
- 32 Command Line Editing
- 33 Using History Interactively
- Appendix A In Memoriam
- Appendix B Formatting Documentation
- Appendix C Installing GDB
- Appendix D Maintenance Commands
- Appendix E GDB Remote Serial Protocol
- E.1 Overview
- E.2 Packets
- E.3 Stop Reply Packets
- E.4 General Query Packets
- E.5 Architecture-Specific Protocol Details
- E.6 Tracepoint Packets
- E.7 Host I/O Packets
- E.8 Interrupts
- E.9 Notification Packets
- E.10 Remote Protocol Support for Non-Stop Mode
- E.11 Packet Acknowledgment
- E.12 Examples
- E.13 File-I/O Remote Protocol Extension
- E.14 Library List Format
- E.15 Library List Format for SVR4 Targets
- E.16 Memory Map Format
- E.17 Thread List Format
- E.18 Traceframe Info Format
- E.19 Branch Trace Format
- E.20 Branch Trace Configuration Format
- Appendix F The GDB Agent Expression Mechanism
- Appendix G Target Descriptions
- G.1 Retrieving Descriptions
- G.2 Target Description Format
- G.3 Predefined Target Types
- G.4 Enum Target Types
- G.5 Standard Target Features
- G.5.1 AArch64 Features
- G.5.2 ARC Features
- G.5.3 ARM Features
- G.5.4 i386 Features
- G.5.5 MicroBlaze Features
- G.5.6 MIPS Features
- G.5.7 M68K Features
- G.5.8 NDS32 Features
- G.5.9 Nios II Features
- G.5.10 Openrisc 1000 Features
- G.5.11 PowerPC Features
- G.5.12 RISC-V Features
- G.5.13 S/390 and System z Features
- G.5.14 Sparc Features
- G.5.15 TMS320C6x Features
- Appendix H Operating System Information
- Appendix I Trace File Format
- Appendix J
.gdb_index
section format - Appendix K Manual pages
- Appendix L GNU GENERAL PUBLIC LICENSE
- Appendix M GNU Free Documentation License
- Concept Index
- Command, Variable, and Function Index