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

Copyright © 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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)

---

Debugging with gdb

This file describes gdb, the gnu symbolic debugger.

This is the Tenth Edition, for gdb (GDB) Version 7.4.50.20120417.

Copyright (C) 1988-2010 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
• Copying: GNU General Public License says how you can copy and share GDB
• GNU Free Documentation License: The license for this documentation
• Index: Index

Table of Contents

• 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.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 Extensions for Ada Tasks
      • 15.4.8.6 Tasking Support when Debugging Core Files
      • 15.4.8.7 Tasking Support when using the Ravenscar Profile
      • 15.4.8.8 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 Connecting to VxWorks
      • 21.2.1.2 VxWorks Download
      • 21.2.1.3 Running Tasks
  • 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 In-Process Agent
• 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.2.1 Readline Bare Essentials
    • 32.2.2 Readline Movement Commands
    • 32.2.3 Readline Killing Commands
    • 32.2.4 Readline Arguments
    • 32.2.5 Searching for Commands in the History
  • 32.3 Readline Init File
    • 32.3.1 Readline Init File Syntax
    • 32.3.2 Conditional Init Constructs
    • 32.3.3 Sample Init File
  • 32.4 Bindable Readline Commands
    • 32.4.1 Commands For Moving
    • 32.4.2 Commands For Manipulating The History
    • 32.4.3 Commands For Changing Text
    • 32.4.4 Killing And Yanking
    • 32.4.5 Specifying Numeric Arguments
    • 32.4.6 Letting Readline Type For You
    • 32.4.7 Keyboard Macros
    • 32.4.8 Some Miscellaneous Commands
  • 32.5 Readline vi Mode
• 33 Using History Interactively
  • 33.1 History Expansion
    • 33.1.1 Event Designators
    • 33.1.2 Word Designators
    • 33.1.3 Modifiers
• 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
• 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
      • 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
• 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.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
• Appendix H Operating System Information
  • H.1 Process list
• Appendix I Trace File Format
• Appendix J .gdb_index section format
• Appendix K GNU GENERAL PUBLIC LICENSE
• Appendix L GNU Free Documentation License
• Index