Debugging with GDB

This is the Tenth Edition, of Debugging with gdb: the gnu Source-Level Debugger for gdb (GDB) Version 7.7.

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.”

Debugging with gdb

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.

Debugging with gdb
Summary of gdb
- Free Software
- Free Software Needs Free Documentation
- Contributors to gdb
1 A Sample gdb Session
2 Getting In and Out of gdb
- 2.1 Invoking gdb
- 2.2 Quitting gdb
- 2.3 Shell Commands
- 2.4 Logging Output
3 gdb Commands
- 3.1 Command Syntax
- 3.2 Command Completion
- 3.3 Getting Help
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
  - 4.12.1 A Non-obvious Benefit of Using Checkpoints
5 Stopping and Continuing
- 5.1 Breakpoints, Watchpoints, and Catchpoints
- 5.2 Continuing and Stepping
- 5.3 Skipping Over Functions and Files
- 5.4 Signals
- 5.5 Stopping and Starting Multi-thread Programs
6 Running programs backward
7 Recording Inferior's Execution and Replaying It
8 Examining the Stack
- 8.1 Stack Frames
- 8.2 Backtraces
- 8.3 Management of Frame Filters.
- 8.4 Selecting a Frame
- 8.5 Information About a Frame
9 Examining Source Files
- 9.1 Printing Source Lines
- 9.2 Specifying a Location
- 9.3 Editing Source Files
  - 9.3.1 Choosing your Editor
- 9.4 Searching Source Files
- 9.5 Specifying Source Directories
- 9.6 Source and Machine Code
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.9.1 Pretty-Printer Introduction
  - 10.9.2 Pretty-Printer Example
  - 10.9.3 Pretty-Printer Commands
- 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.17.1 Attributes
  - 10.17.2 Memory Access Checking
- 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
11 Debugging Optimized Code
- 11.1 Inline Functions
- 11.2 Tail Call Frames
12 C Preprocessor Macros
13 Tracepoints
- 13.1 Commands to Set Tracepoints
- 13.2 Using the Collected Data
- 13.3 Convenience Variables for Tracepoints
- 13.4 Using Trace Files
14 Debugging Programs That Use Overlays
- 14.1 How Overlays Work
- 14.2 Overlay Commands
- 14.3 Automatic Overlay Debugging
- 14.4 Overlay Sample Program
15 Using gdb with Different Languages
- 15.1 Switching Between Source Languages
- 15.2 Displaying the Language
- 15.3 Type and Range Checking
  - 15.3.1 An Overview of Type Checking
  - 15.3.2 An Overview of Range Checking
- 15.4 Supported Languages
- 15.5 Unsupported Languages
16 Examining the Symbol Table
17 Altering Execution
- 17.1 Assignment to Variables
- 17.2 Continuing at a Different Address
- 17.3 Giving your Program a Signal
- 17.4 Returning from a Function
- 17.5 Calling Program Functions
- 17.6 Patching Programs
18 gdb Files
- 18.1 Commands to Specify Files
- 18.2 Debugging Information in Separate Files
- 18.3 Debugging information in a special section
- 18.4 Index Files Speed Up gdb
- 18.5 Errors Reading Symbol Files
- 18.6 GDB Data Files
19 Specifying a Debugging Target
- 19.1 Active Targets
- 19.2 Commands for Managing Targets
- 19.3 Choosing Target Byte Order
20 Debugging Remote Programs
- 20.1 Connecting to a Remote Target
- 20.2 Sending files to a remote system
- 20.3 Using the gdbserver Program
- 20.4 Remote Configuration
- 20.5 Implementing a Remote Stub
21 Configuration-Specific Information
- 21.1 Native
- 21.2 Embedded Operating Systems
  - 21.2.1 Using gdb with VxWorks
- 21.3 Embedded Processors
- 21.4 Architectures
22 Controlling gdb
- 22.1 Prompt
- 22.2 Command Editing
- 22.3 Command History
- 22.4 Screen Size
- 22.5 Numbers
- 22.6 Configuring the Current ABI
- 22.7 Automatically loading associated files
- 22.8 Optional Warnings and Messages
- 22.9 Optional Messages about Internal Happenings
- 22.10 Other Miscellaneous Settings
23 Extending gdb
- 23.1 Canned Sequences of Commands
- 23.2 Extending gdb using Python
- 23.3 Auto-loading extensions
- 23.4 Creating new spellings of existing commands
24 Command Interpreters
25 gdb Text User Interface
- 25.1 TUI Overview
- 25.2 TUI Key Bindings
- 25.3 TUI Single Key Mode
- 25.4 TUI-specific Commands
- 25.5 TUI Configuration Variables
26 Using gdb under gnu Emacs
27 The gdb/mi Interface
- Function and Purpose
- Notation and Terminology
- 27.1 gdb/mi General Design
  - 27.1.1 Context management
    - 27.1.1.1 Threads and Frames
    - 27.1.1.2 Language
  - 27.1.2 Asynchronous command execution and non-stop mode
  - 27.1.3 Thread groups
- 27.2 gdb/mi Command Syntax
  - 27.2.1 gdb/mi Input Syntax
  - 27.2.2 gdb/mi Output Syntax
- 27.3 gdb/mi Compatibility with CLI
- 27.4 gdb/mi Development and Front Ends
- 27.5 gdb/mi Output Records
  - 27.5.1 gdb/mi Result Records
  - 27.5.2 gdb/mi Stream Records
  - 27.5.3 gdb/mi Async Records
  - 27.5.4 gdb/mi Breakpoint Information
  - 27.5.5 gdb/mi Frame Information
  - 27.5.6 gdb/mi Thread Information
  - 27.5.7 gdb/mi Ada Exception Information
- 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.9.1 Shared Library gdb/mi Catchpoints
  - 27.9.2 Ada Exception gdb/mi Catchpoints
- 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
- 28.1 What is an Annotation?
- 28.2 The Server Prefix
- 28.3 Annotation for gdb Input
- 28.4 Errors
- 28.5 Invalidation Notices
- 28.6 Running the Program
- 28.7 Displaying Source
29 JIT Compilation Interface
- 29.1 JIT Declarations
- 29.2 Registering Code
- 29.3 Unregistering Code
- 29.4 Custom Debug Info
  - 29.4.1 Using JIT Debug Info Readers
  - 29.4.2 Writing JIT Debug Info Readers
30 In-Process Agent
- 30.1 In-Process Agent Protocol
  - 30.1.1 IPA Protocol Objects
  - 30.1.2 IPA Protocol Commands
31 Reporting Bugs in gdb
- 31.1 Have You Found a Bug?
- 31.2 How to Report Bugs
32 Command Line Editing
- 32.1 Introduction to Line Editing
- 32.2 Readline Interaction
- 32.3 Readline Init File
- 32.4 Bindable Readline Commands
- 32.5 Readline vi Mode
33 Using History Interactively
- 33.1 History Expansion
Appendix A In Memoriam
Appendix B Formatting Documentation
Appendix C Installing gdb
- C.1 Requirements for Building gdb
- C.2 Invoking the gdb configure Script
- C.3 Compiling gdb in Another Directory
- C.4 Specifying Names for Hosts and Targets
- C.5 configure Options
- C.6 System-wide configuration and settings
  - C.6.1 Installed System-wide Configuration Scripts
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.5.1 ARM-specific Protocol Details
    - E.5.1.1 ARM Breakpoint Kinds
  - E.5.2 MIPS-specific Protocol Details
    - E.5.2.1 MIPS Register Packet Format
    - E.5.2.2 MIPS Breakpoint Kinds
- E.6 Tracepoint Packets
  - E.6.1 Relocate instruction reply packet
- 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
Appendix F The GDB Agent Expression Mechanism
- F.1 General Bytecode Design
- F.2 Bytecode Descriptions
- F.3 Using Agent Expressions
- F.4 Varying Target Capabilities
- F.5 Rationale
Appendix G Target Descriptions
- G.1 Retrieving Descriptions
- G.2 Target Description Format
- G.3 Predefined Target Types
- G.4 Standard Target Features
Appendix H Operating System Information
- H.1 Process list
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

Debugging with gdb

Table of Contents