Table of Contents

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.1.1 Choosing Files
2.1.2 Choosing Modes
2.1.3 What GDB Does During Startup

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.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 How to save breakpoints to a file
5.1.9 "Cannot insert breakpoints"
5.1.10 "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.5.1 All-Stop Mode
5.5.2 Non-Stop Mode
5.5.3 Background Execution
5.5.4 Thread-Specific Breakpoints
5.5.5 Interrupted System Calls
5.5.6 Observer Mode

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 Selecting a Frame
8.4 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 Registers
10.13 Floating Point Hardware
10.14 Vector Unit
10.15 Operating System Auxiliary Information
10.16 Memory Region Attributes

10.16.1 Attributes

10.16.1.1 Memory Access Mode
10.16.1.2 Memory Access Size
10.16.1.3 Data Cache

10.16.2 Memory Access Checking

10.17 Copy Between Memory and a File
10.18 How to Produce a Core File from Your Program
10.19 Character Sets
10.20 Caching Data of Remote Targets
10.21 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.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.2.1 tfind n
13.2.2 tdump
13.2.3 save tracepoints filename

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.1.1 List of Filename Extensions and Languages
15.1.2 Setting the Working Language
15.1.3 Having GDB Infer the Source Language

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.4.1 C and C++

15.4.1.1 C and C++ Operators
15.4.1.2 C and C++ Constants
15.4.1.3 C++ Expressions
15.4.1.4 C and C++ Defaults
15.4.1.5 C and C++ Type and Range Checks
15.4.1.6 GDB and C
15.4.1.7 GDB Features for C++
15.4.1.8 Decimal Floating Point format

15.4.2 D
15.4.3 Objective-C

15.4.3.1 Method Names in Commands
15.4.3.2 The Print Command With Objective-C

15.4.4 OpenCL C

15.4.4.1 OpenCL C Datatypes
15.4.4.2 OpenCL C Expressions
15.4.4.3 OpenCL C Operators

15.4.5 Fortran

15.4.5.1 Fortran Operators and Expressions
15.4.5.2 Fortran Defaults
15.4.5.3 Special Fortran Commands

15.4.6 Pascal
15.4.7 Modula-2

15.4.7.1 Operators
15.4.7.2 Built-in Functions and Procedures
15.4.7.3 Constants
15.4.7.4 Modula-2 Types
15.4.7.5 Modula-2 Defaults
15.4.7.6 Deviations from Standard Modula-2
15.4.7.7 Modula-2 Type and Range Checks
15.4.7.8 The Scope Operators :: and .
15.4.7.9 GDB and Modula-2

15.4.8 Ada

15.4.8.1 Introduction
15.4.8.2 Omissions from Ada
15.4.8.3 Additions to Ada
15.4.8.4 Stopping at the Very Beginning
15.4.8.5 Ada Exceptions
15.4.8.6 Extensions for Ada Tasks
15.4.8.7 Tasking Support when Debugging Core Files
15.4.8.8 Tasking Support when using the Ravenscar Profile
15.4.8.9 Debugging Generic Units
15.4.8.10 Set commands for Ada
15.4.8.11 Known Peculiarities of Ada Mode

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 Index Files Speed Up GDB
18.4 Errors Reading Symbol Files
18.5 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.3.1 Running gdbserver

20.3.1.1 Attaching to a Running Program
20.3.1.2 Multi-Process Mode for gdbserver
20.3.1.3 TCP port allocation lifecycle of gdbserver
20.3.1.4 Other Command-Line Arguments for gdbserver

20.3.2 Connecting to gdbserver
20.3.3 Monitor Commands for gdbserver
20.3.4 Tracepoints support in gdbserver

20.4 Remote Configuration
20.5 Implementing a Remote Stub

20.5.1 What the Stub Can Do for You
20.5.2 What You Must Do for the Stub
20.5.3 Putting it All Together

21. Configuration-Specific Information

21.1 Native

21.1.1 HP-UX
21.1.2 BSD libkvm Interface
21.1.3 SVR4 Process Information
21.1.4 Features for Debugging DJGPP Programs
21.1.5 Features for Debugging MS Windows PE Executables

21.1.5.1 Support for DLLs without Debugging Symbols
21.1.5.2 DLL Name Prefixes
21.1.5.3 Working with Minimal Symbols

21.1.6 Commands Specific to GNU Hurd Systems
21.1.7 QNX Neutrino
21.1.8 Darwin

21.2 Embedded Operating Systems

21.2.1 Using GDB with VxWorks

21.2.1.1 Debugging on VxWorks 5.5
21.2.1.2 Debugging on VxWorks 653
21.2.1.3 Commands and Settings Related to WTX
21.2.1.4 Debugging on VxWorks 6
21.2.1.5 Commands and Settings Related to DFW
21.2.1.6 VxWorks Module Handling

21.3 Embedded Processors

21.3.1 ARM
21.3.2 Renesas M32R/D and M32R/SDI
21.3.3 M68k
21.3.4 MicroBlaze
21.3.5 MIPS Embedded
21.3.6 OpenRISC 1000
21.3.7 PowerPC Embedded
21.3.8 HP PA Embedded
21.3.9 Tsqware Sparclet

21.3.9.1 Setting File to Debug
21.3.9.2 Connecting to Sparclet
21.3.9.3 Sparclet Download
21.3.9.4 Running and Debugging

21.3.10 Fujitsu Sparclite
21.3.11 Zilog Z8000
21.3.12 Atmel AVR
21.3.13 CRIS
21.3.14 Renesas Super-H

21.4 Architectures

21.4.1 x86 Architecture-specific Issues
21.4.2 A29K
21.4.3 Alpha
21.4.4 MIPS
21.4.5 HPPA
21.4.6 Cell Broadband Engine SPU architecture
21.4.7 PowerPC

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 Optional Warnings and Messages
22.8 Optional Messages about Internal Happenings
22.9 Other Miscellaneous Settings

23. Extending GDB

23.1 Canned Sequences of Commands

23.1.1 User-defined Commands
23.1.2 User-defined Command Hooks
23.1.3 Command Files
23.1.4 Commands for Controlled Output

23.2 Scripting 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 Inferiors In Python
23.2.2.9 Events In Python
23.2.2.10 Threads In Python
23.2.2.11 Commands In Python
23.2.2.12 Parameters In Python
23.2.2.13 Writing new convenience functions
23.2.2.14 Program Spaces In Python
23.2.2.15 Objfiles In Python
23.2.2.16 Accessing inferior stack frames from Python.
23.2.2.17 Accessing frame blocks from Python.
23.2.2.18 Python representation of Symbols.
23.2.2.19 Symbol table representation in Python.
23.2.2.20 Manipulating breakpoints using Python
23.2.2.21 Finish Breakpoints
23.2.2.22 Python representation of lazy strings.

23.2.3 Auto-loading

23.2.3.1 The `objfile-gdb.py' file
23.2.3.2 The .debug_gdb_scripts section
23.2.3.3 Which flavor to choose?

23.2.4 Python modules

23.2.4.1 gdb.printing
23.2.4.2 gdb.types
23.2.4.3 gdb.prompt

23.3 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.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 Frame Information
27.5.5 GDB/MI Thread Information
27.5.6 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 Program Context
27.10 GDB/MI Thread Commands
27.11 GDB/MI Ada Tasking Commands
27.12 GDB/MI Program Execution
27.13 GDB/MI Stack Manipulation Commands
27.14 GDB/MI Variable Objects
27.15 GDB/MI Data Manipulation
27.16 GDB/MI Tracepoint Commands
27.17 GDB/MI Symbol Query Commands
27.18 GDB/MI File Commands
27.19 GDB/MI Target Manipulation Commands
27.20 GDB/MI File Transfer Commands
27.21 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. Reporting Bugs in GDB

30.1 Have You Found a Bug?
30.2 How to Report Bugs

31. Command Line Editing

31.1 Introduction to Line Editing
31.2 Readline Interaction

31.2.1 Readline Bare Essentials
31.2.2 Readline Movement Commands
31.2.3 Readline Killing Commands
31.2.4 Readline Arguments
31.2.5 Searching for Commands in the History

31.3 Readline Init File

31.3.1 Readline Init File Syntax
31.3.2 Conditional Init Constructs
31.3.3 Sample Init File

31.4 Bindable Readline Commands

31.4.1 Commands For Moving
31.4.2 Commands For Manipulating The History
31.4.3 Commands For Changing Text
31.4.4 Killing And Yanking
31.4.5 Specifying Numeric Arguments
31.4.6 Letting Readline Type For You
31.4.7 Keyboard Macros
31.4.8 Some Miscellaneous Commands

31.5 Readline vi Mode

32. Using History Interactively

32.1 History Expansion

32.1.1 Event Designators
32.1.2 Word Designators
32.1.3 Modifiers

A. In Memoriam
B. Formatting Documentation
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

D. Maintenance Commands
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

E.5.1.1 Breakpoint Kinds

E.5.2 MIPS

E.5.2.1 Register Packet Format

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.13.1 File-I/O Overview
E.13.2 Protocol Basics
E.13.3 The F Request Packet
E.13.4 The F Reply Packet
E.13.5 The `Ctrl-C' Message
E.13.6 Console I/O
E.13.7 List of Supported Calls

open
close
read
write
lseek
rename
unlink
stat/fstat
gettimeofday
isatty
system

E.13.8 Protocol-specific Representation of Datatypes

Integral Datatypes
Pointer Values
Memory Transfer
struct stat
struct timeval

E.13.9 Constants

Open Flags
mode_t Values
Errno Values
Lseek Flags
Limits

E.13.10 File-I/O Examples

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

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

G. Target Descriptions

G.1 Retrieving Descriptions
G.2 Target Description Format

G.2.1 Inclusion
G.2.2 Architecture
G.2.3 OS ABI
G.2.4 Compatible Architecture
G.2.5 Features
G.2.6 Types
G.2.7 Registers

G.3 Predefined Target Types
G.4 Standard Target Features

G.4.1 ARM Features
G.4.2 i386 Features
G.4.3 MIPS Features
G.4.4 M68K Features
G.4.5 PowerPC Features
G.4.6 TMS320C6x Features

H. Operating System Information

H.1 Process list

I. Trace File Format
J. .gdb_index section format
K. GNU GENERAL PUBLIC LICENSE
L. GNU Free Documentation License
Index