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

Description

The GNU Debugger allows you to see what is going on "inside" a program while it executes - or what a program was doing at the moment it crashed. GDB supports C, C++, Java, Fortran and Assembly among other languages; it is also designed to work closely with the GNU Compiler Collection (GCC). The GNU Debugger Program has four special features that helps you catch bugs in the act: It starts your program for you, specifying anything that might affect it's behavior. Makes your program stop under specified conditions. Examines what happened when the program stopped. Allows you to experiment with changes to see what effect they have on the program. This book will show you: setting and clearing breakpoints examining the stack, source files and data examining the symbol table altering program execution specifying a target for debugging how to control the debugger how to use canned command sequences how to install GDB and much more! This manual is written for programmers. It is designed so someone can begin utilizing GDB after just reading the first chapter, or read the whole manual and master the program. Synopsis of ideas and extensive examples are given. Summary of gdb Free Software Free Software Needs Free Documentation Contributors to gdb A Sample gdb Session Getting In and Out of gdb Invoking gdb Choosing Files Choosing Modes What gdb Does During Startup Quitting gdb Shell Commands Logging Output gdb Commands Command Syntax Command Completion Getting Help Running Programs Under gdb Compiling for Debugging Starting your Program Your Program's Arguments Your Program's Environment Your Program's Working Directory Your Program's Input and Output Debugging an Already-running Process Killing the Child Process Debugging Multiple Inferiors and Programs Debugging Programs with Multiple Threads Debugging Forks Setting a Bookmark to Return to Later A Non-obvious Benefit of Using Checkpoints Stopping and Continuing Breakpoints, Watchpoints, and Catchpoints Setting Breakpoints Setting Watchpoints Setting Catchpoints Deleting Breakpoints Disabling Breakpoints Break Conditions Breakpoint Command Lists Dynamic Printf How to save breakpoints to a file Static Probe Points ``Cannot insert breakpoints'' ``Breakpoint address adjusted...'' Continuing and Stepping Skipping Over Functions and Files Signals Stopping and Starting Multi-thread Programs All-Stop Mode Non-Stop Mode Background Execution Thread-Specific Breakpoints Interrupted System Calls Observer Mode Running programs backward Recording Inferior's Execution and Replaying It Examining the Stack Stack Frames Backtraces Selecting a Frame Information About a Frame Management of Frame Filters. Examining Source Files Printing Source Lines Specifying a Location Linespec Locations Explicit Locations Address Locations Editing Source Files Choosing your Editor Searching Source Files Specifying Source Directories Source and Machine Code Examining Data Expressions Ambiguous Expressions Program Variables Artificial Arrays Output Formats Examining Memory Automatic Display Print Settings Pretty Printing Pretty-Printer Introduction Pretty-Printer Example Pretty-Printer Commands Value History Convenience Variables Convenience Functions Registers Floating Point Hardware Vector Unit Operating System Auxiliary Information Memory Region Attributes Attributes Memory Access Mode Memory Access Size Data Cache Memory Access Checking Copy Between Memory and a File How to Produce a Core File from Your Program Character Sets Caching Data of Targets Search Memory Value Sizes Debugging Optimized Code Inline Functions Tail Call Frames C Preprocessor Macros Tracepoints Commands to Set Tracepoints Create and Delete Tracepoints Enable and Disable Tracepoints Tracepoint Passcounts Tracepoint Conditions Trace State Variables Tracepoint Action Lists Listing Tracepoints Listing Static Tracepoint Markers Starting and Stopping Trace Experiments Tracepoint Restrictions Using the Collected Data tfind n tdump save tracepoints filename Convenience Variables for Tracepoints Using Trace Files Debugging Programs That Use Overlays How Overlays Work Overlay Commands Automatic Overlay Debugging Overlay Sample Program Using gdb with Different Languages Switching Between Source Languages List of Filename Extensions and Languages Setting the Working Language Having gdb Infer the Source Language Displaying the Language Type and Range Checking An Overview of Type Checking An Overview of Range Checking Supported Languages C and C++ C and C++ Operators C and C++ Constants C++ Expressions C and C++ Defaults C and C++ Type and Range Checks gdb and C gdb Features for C++ Decimal Floating Point format D Go Objective-C Method Names in Commands The Print Command With Objective-C OpenCL C OpenCL C Datatypes OpenCL C Expressions OpenCL C Operators Fortran Fortran Operators and Expressions Fortran Defaults Special Fortran Commands Pascal Rust Modula-2 Operators Built-in Functions and Procedures Constants Modula-2 Types Modula-2 Defaults Deviations from Standard Modula-2 Modula-2 Type and Range Checks The Scope Operators :: and . gdb and Modula-2 Ada Introduction Omissions from Ada Additions to Ada Overloading support for Ada Stopping at the Very Beginning Ada Exceptions Extensions for Ada Tasks Tasking Support when Debugging Core Files Tasking Support when using the Ravenscar Profile Known Peculiarities of Ada Mode Unsupported Languages Examining the Symbol Table Altering Execution Assignment to Variables Continuing at a Different Address Giving your Program a Signal Returning from a Function Calling Program Functions Patching Programs Compiling and injecting code in gdb Compilation options for the compile command Caveats when using the compile command Compiler search for the compile command gdb Files Commands to Specify Files File Caching Debugging Information in Separate Files Debugging information in a special section Index Files Speed Up gdb Errors Reading Symbol Files GDB Data Files Specifying a Debugging Target Active Targets Commands for Managing Targets Choosing Target Byte Order Debugging Remote Programs Connecting to a Remote Target Types of Remote Connections Host and Target Files Remote Connection Commands Sending files to a remote system Using the gdbserver Program Running gdbserver Attaching to a Running Program TCP port allocation lifecycle of gdbserver Other Command-Line Arguments for gdbserver Connecting to gdbserver Monitor Commands for gdbserver Tracepoints support in gdbserver Remote Configuration Implementing a Remote Stub What the Stub Can Do for You What You Must Do for the Stub Putting it All Together Configuration-Specific Information Native BSD libkvm Interface SVR4 Process Information Features for Debugging djgpp Programs Features for Debugging MS Windows PE Executables Support for DLLs without Debugging Symbols DLL Name Prefixes Working with Minimal Symbols Commands Specific to gnu Hurd Systems Darwin Embedded Operating Systems Embedded Processors Synopsys ARC ARM M68k MicroBlaze MIPS Embedded PowerPC Embedded Atmel AVR CRIS Renesas Super-H Architectures AArch64 x86 Architecture-specific Issues Intel Memory Protection Extensions (MPX). Alpha MIPS HPPA Cell Broadband Engine SPU architecture PowerPC Nios II Controlling gdb Prompt Command Editing Command History Screen Size Numbers Configuring the Current ABI Automatically loading associated files Automatically loading init file in the current directory Automatically loading thread debugging library Security restriction for auto-loading Displaying files tried for auto-load Optional Warnings and Messages Optional Messages about Internal Happenings Other Miscellaneous Settings Extending gdb Canned Sequences of Commands User-defined Commands User-defined Command Hooks Command Files Commands for Controlled Output Controlling auto-loading native gdb scripts Extending gdb using Python Python Commands Python API Basic Python Exception Handling Values From Inferior Types In Python Pretty Printing API Selecting Pretty-Printers Writing a Pretty-Printer Type Printing API Filtering Frames. Decorating Frames. Writing a Frame Filter Unwinding Frames in Python Xmethods In Python Xmethod API Writing an Xmethod Inferiors In Python Events In Python Threads In Python Commands In Python Parameters In Python Writing new convenience functions Program Spaces In Python Objfiles In Python Accessing inferior stack frames from Python. Accessing blocks from Python. Python representation of Symbols. Symbol table representation in Python. Manipulating line tables using Python Manipulating breakpoints using Python Finish Breakpoints Python representation of lazy strings. Python representation of architectures Python Auto-loading Python modules gdb.printing gdb.types gdb.prompt Extending gdb using Guile Guile Introduction Guile Commands Guile API Basic Guile Guile Configuration GDB Scheme Data Types Guile Exception Handling Values From Inferior In Guile Arithmetic In Guile Types In Guile Guile Pretty Printing API Selecting Guile Pretty-Printers Writing a Guile Pretty-Printer Commands In Guile Parameters In Guile Program Spaces In Guile Objfiles In Guile Accessing inferior stack frames from Guile. Accessing blocks from Guile. Guile representation of Symbols. Symbol table representation in Guile. Manipulating breakpoints using Guile Guile representation of lazy strings. Guile representation of architectures Disassembly In Guile I/O Ports in Guile Memory Ports in Guile Iterators In Guile Guile Auto-loading Guile Modules Guile Printing Module Guile Types Module Auto-loading extensions The objfile-gdb.ext file The .debug_gdb_scripts section Script File Entries Script Text Entries Which flavor to choose? Multiple Extension Languages Python comes first Creating new spellings of existing commands Command Interpreters gdb Text User Interface TUI Overview TUI Key Bindings TUI Single Key Mode TUI-specific Commands TUI Configuration Variables Using gdb under gnu Emacs The gdb/mi Interface Function and Purpose Notation and Terminology gdb/mi General Design Context management Threads and Frames Language Asynchronous command execution and non-stop mode Thread groups gdb/mi Command Syntax gdb/mi Input Syntax gdb/mi Output Syntax gdb/mi Compatibility with CLI gdb/mi Development and Front Ends gdb/mi Output Records gdb/mi Result Records gdb/mi Stream Records gdb/mi Async Records gdb/mi Breakpoint Information gdb/mi Frame Information gdb/mi Thread Information gdb/mi Ada Exception Information Simple Examples of gdb/mi Interaction gdb/mi Command Description Format gdb/mi Breakpoint Commands gdb/mi Catchpoint Commands Shared Library gdb/mi Catchpoints Ada Exception gdb/mi Catchpoints gdb/mi Program Context gdb/mi Thread Commands gdb/mi Ada Tasking Commands gdb/mi Program Execution gdb/mi Stack Manipulation Commands gdb/mi Variable Objects gdb/mi Data Manipulation gdb/mi Tracepoint Commands gdb/mi Symbol Query Commands gdb/mi File Commands gdb/mi Target Manipulation Commands gdb/mi File Transfer Commands Ada Exceptions gdb/mi Commands gdb/mi Support Commands Miscellaneous gdb/mi Commands gdb Annotations What is an Annotation? The Server Prefix Annotation for gdb Input Errors Invalidation Notices Running the Program Displaying Source JIT Compilation Interface JIT Declarations Registering Code Unregistering Code Custom Debug Info Using JIT Debug Info Readers Writing JIT Debug Info Readers In-Process Agent In-Process Agent Protocol IPA Protocol Objects IPA Protocol Commands Reporting Bugs in gdb Have You Found a Bug? How to Report Bugs Command Line Editing Introduction to Line Editing Readline Interaction Readline Bare Essentials Readline Movement Commands Readline Killing Commands Readline Arguments Searching for Commands in the History Readline Init File Readline Init File Syntax Conditional Init Constructs Sample Init File Bindable Readline Commands Commands For Moving Commands For Manipulating The History Commands For Changing Text Killing And Yanking Specifying Numeric Arguments Letting Readline Type For You Keyboard Macros Some Miscellaneous Commands Readline vi Mode Using History Interactively History Expansion Event Designators Word Designators Modifiers In Memoriam Formatting Documentation Installing gdb Requirements for Building gdb Invoking the gdb configure Script Compiling gdb in Another Directory Specifying Names for Hosts and Targets configure Options System-wide configuration and settings Installed System-wide Configuration Scripts Maintenance Commands gdb Remote Serial Protocol Overview Packets Stop Reply Packets General Query Packets Architecture-Specific Protocol Details ARM-specific Protocol Details ARM Breakpoint Kinds MIPS-specific Protocol Details MIPS Register Packet Format MIPS Breakpoint Kinds Tracepoint Packets Relocate instruction reply packet Host I/O Packets Interrupts Notification Packets Remote Protocol Support for Non-Stop Mode Packet Acknowledgment Examples File-I/O Remote Protocol Extension File-I/O Overview Protocol Basics The F Request Packet The F Reply Packet The Ctrl-C Message Console I/O List of Supported Calls open close read write lseek rename unlink stat/fstat gettimeofday isatty system Protocol-specific Representation of Datatypes Integral Datatypes Pointer Values Memory Transfer struct stat struct timeval Constants Open Flags mode_t Values Errno Values Lseek Flags Limits File-I/O Examples Library List Format Library List Format for SVR4 Targets Memory Map Format Thread List Format Traceframe Info Format Branch Trace Format Branch Trace Configuration Format The GDB Agent Expression Mechanism General Bytecode Design Bytecode Descriptions Using Agent Expressions Varying Target Capabilities Rationale Target Descriptions Retrieving Descriptions Target Description Format Inclusion Architecture OS ABI Compatible Architecture Features Types Registers Predefined Target Types Enum Target Types Standard Target Features AArch64 Features ARC Features ARM Features i386 Features MicroBlaze Features MIPS Features M68K Features NDS32 Features Nios II Features PowerPC Features S/390 and System z Features TMS320C6x Features Operating System Information Process list Trace File Format .gdb_index section format Manual pages GNU GENERAL PUBLIC LICENSE GNU Free Documentation License Concept Index Command, Variable, and Function Index