gdb manual

8/9/2019 gdb manual

1/756

Debugging with gdbThe gnu Source-Level Debugger

Tenth Edition, for gdb version 7.8.50.20140729-cvs

(GDB)

Richard Stallman, Roland Pesch, Stan Shebs, et al.

8/9/2019 gdb manual

2/756

(Send bugs and comments on gdb to http://www.gnu.org/software/gdb/bugs/ .)Debugging with gdb

TEXinfo 2011-02-14.11

Published by the Free Software Foundation51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USAISBN 978-0-9831592-3-0

Copyright c 1988-2014 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the termsof the GNU Free Documentation License, Version 1.3 or any later version published bythe Free Software Foundation; with the Invariant Sections being “Free Software” and “FreeSoftware 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 Man-ual. Buying copies from GNU Press supports the FSF in developing GNU and promotingsoftware freedom.”

http://www.gnu.org/software/gdb/bugs/http://www.gnu.org/software/gdb/bugs/

8/9/2019 gdb manual

3/756

i

Table of Contents

Summary of gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Free Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Free Software Needs Free Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Contributors to gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1 A Sample gdb Session . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Getting In and Out of gdb . . . . . . . . . . . . . . . . . . . 112.1 Invoking gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.1.1 Choosing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.1.2 Choosing Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.1.3 What gdb Does During Startup . . . . . . . . . . . . . . . . . . . . . . . . . . 162.2 Quitting gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.3 Shell Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.4 Logging Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3 gdb Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.1 Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.2 Command Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.3 Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4 Running Programs Under gdb . . . . . . . . . . . . . . . 254.1 Compiling for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.2 Starting your Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264.3 Your Program’s Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304.4 Your Program’s Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304.5 Your Program’s Working Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314.6 Your Program’s Input and Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324.7 Debugging an Already-running Process . . . . . . . . . . . . . . . . . . . . . . . . 324.8 Killing the Child Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334.9 Debugging Multiple Inferiors and Programs . . . . . . . . . . . . . . . . . . . . 334.10 Debugging Programs with Multiple Threads . . . . . . . . . . . . . . . . . . 364.11 Debugging Forks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

4.12 Setting a Bookmark to Return to Later. . . . . . . . . . . . . . . . . . . . . . .

424.12.1 A Non-obvious Benet of Using Checkpoints . . . . . . . . . . . . . 43

8/9/2019 gdb manual

4/756

ii Debugging with gdb

5 Stopping and Continuing . . . . . . . . . . . . . . . . . . . . . 455.1 Breakpoints, Watchpoints, and Catchpoints . . . . . . . . . . . . . . . . . . . 45

5.1.1 Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465.1.2 Setting Watchpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525.1.3 Setting Catchpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

5.1.4 Deleting Breakpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

595.1.5 Disabling Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605.1.6 Break Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615.1.7 Breakpoint Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625.1.8 Dynamic Printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645.1.9 How to save breakpoints to a le . . . . . . . . . . . . . . . . . . . . . . . . . 655.1.10 Static Probe Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655.1.11 “Cannot insert breakpoints” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665.1.12 “Breakpoint address adjusted...” . . . . . . . . . . . . . . . . . . . . . . . . 67

5.2 Continuing and Stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675.3 Skipping Over Functions and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715.4 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

5.5 Stopping and Starting Multi-thread Programs . . . . . . . . . . . . . . . . . 745.5.1 All-Stop Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755.5.2 Non-Stop Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765.5.3 Background Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775.5.4 Thread-Specic Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785.5.5 Interrupted System Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785.5.6 Observer Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

6 Running programs backward . . . . . . . . . . . . . . . . . 81

7 Recording Inferior’s Execution and ReplayingIt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

8 Examining the Stack . . . . . . . . . . . . . . . . . . . . . . . . . . 898.1 Stack Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898.2 Backtraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908.3 Management of Frame Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938.4 Selecting a Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958.5 Information About a Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

9 Examining Source Files . . . . . . . . . . . . . . . . . . . . . . . 979.1 Printing Source Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979.2 Specifying a Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989.3 Editing Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

9.3.1 Choosing your Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009.4 Searching Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009.5 Specifying Source Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009.6 Source and Machine Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

8/9/2019 gdb manual

5/756

iii

10 Examining Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10710.1 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10910.2 Ambiguous Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11010.3 Program Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11110.4 Articial Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

10.5 Output Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11410.6 Examining Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11510.7 Automatic Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11810.8 Print Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11910.9 Pretty Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

10.9.1 Pretty-Printer Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12710.9.2 Pretty-Printer Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12810.9.3 Pretty-Printer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

10.10 Value History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12910.11 Convenience Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13010.12 Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13310.13 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

10.14 Floating Point Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13610.15 Vector Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13610.16 Operating System Auxiliary Information . . . . . . . . . . . . . . . . . . . 13610.17 Memory Region Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

10.17.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13910.17.1.1 Memory Access Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13910.17.1.2 Memory Access Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14010.17.1.3 Data Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

10.17.2 Memory Access Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14010.18 Copy Between Memory and a File . . . . . . . . . . . . . . . . . . . . . . . . . 14010.19 How to Produce a Core File from Your Program . . . . . . . . . . . 14110.20 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14110.21 Caching Data of Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14410.22 Search Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

11 Debugging Optimized Code . . . . . . . . . . . . . . . . 14911.1 Inline Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14911.2 Tail Call Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

12 C Preprocessor Macros . . . . . . . . . . . . . . . . . . . . . 153

8/9/2019 gdb manual

6/756

iv Debugging with gdb

13 Tracepoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15713.1 Commands to Set Tracepoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

13.1.1 Create and Delete Tracepoints . . . . . . . . . . . . . . . . . . . . . . . . . 15813.1.2 Enable and Disable Tracepoints . . . . . . . . . . . . . . . . . . . . . . . . 16013.1.3 Tracepoint Passcounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

13.1.4 Tracepoint Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16113.1.5 Trace State Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16113.1.6 Tracepoint Action Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16213.1.7 Listing Tracepoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16413.1.8 Listing Static Tracepoint Markers . . . . . . . . . . . . . . . . . . . . . . 16513.1.9 Starting and Stopping Trace Experiments . . . . . . . . . . . . . . 16613.1.10 Tracepoint Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

13.2 Using the Collected Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16913.2.1 tfind n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16913.2.2 tdump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17113.2.3 save tracepoints filename . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

13.3 Convenience Variables for Tracepoints . . . . . . . . . . . . . . . . . . . . . . . 172

13.4 Using Trace Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

14 Debugging Programs That Use Overlays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

14.1 How Overlays Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17514.2 Overlay Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17614.3 Automatic Overlay Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17814.4 Overlay Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

15 Using gdb with Different Languages . . . . . . 18115.1 Switching Between Source Languages . . . . . . . . . . . . . . . . . . . . . . . 181

15.1.1 List of Filename Extensions and Languages . . . . . . . . . . . . . 18115.1.2 Setting the Working Language . . . . . . . . . . . . . . . . . . . . . . . . . 18215.1.3 Having gdb Infer the Source Language . . . . . . . . . . . . . . . . . 182

15.2 Displaying the Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18215.3 Type and Range Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

15.3.1 An Overview of Type Checking . . . . . . . . . . . . . . . . . . . . . . . . 18315.3.2 An Overview of Range Checking . . . . . . . . . . . . . . . . . . . . . . . 184

15.4 Supported Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18515.4.1 C and C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

15.4.1.1 C and C++ Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18515.4.1.2 C and C++ Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

15.4.1.3 C++ Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18815.4.1.4 C and C++ Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18915.4.1.5 C and C++ Type and Range Checks . . . . . . . . . . . . . . . 18915.4.1.6 gdb and C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18915.4.1.7 gdb Features for C ++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18915.4.1.8 Decimal Floating Point format . . . . . . . . . . . . . . . . . . . . 191

15.4.2 D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19115.4.3 Go. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

8/9/2019 gdb manual

7/756

v

15.4.4 Objective-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19215.4.4.1 Method Names in Commands . . . . . . . . . . . . . . . . . . . . . 19215.4.4.2 The Print Command With Objective-C . . . . . . . . . . . . 192

15.4.5 OpenCL C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19315.4.5.1 OpenCL C Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19315.4.5.2 OpenCL C Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19315.4.5.3 OpenCL C Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

15.4.6 Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19315.4.6.1 Fortran Operators and Expressions . . . . . . . . . . . . . . . . 19315.4.6.2 Fortran Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19315.4.6.3 Special Fortran Commands . . . . . . . . . . . . . . . . . . . . . . . . 194

15.4.7 Pascal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19415.4.8 Modula-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

15.4.8.1 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19415.4.8.2 Built-in Functions and Procedures . . . . . . . . . . . . . . . . . 19515.4.8.3 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19615.4.8.4 Modula-2 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

15.4.8.5 Modula-2 Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19915.4.8.6 Deviations from Standard Modula-2 . . . . . . . . . . . . . . . 19915.4.8.7 Modula-2 Type and Range Checks . . . . . . . . . . . . . . . . . 19915.4.8.8 The Scope Operators :: and . . . . . . . . . . . . . . . . . . . . . 19915.4.8.9 gdb and Modula-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

15.4.9 Ada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20015.4.9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20015.4.9.2 Omissions from Ada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20115.4.9.3 Additions to Ada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20215.4.9.4 Stopping at the Very Beginning . . . . . . . . . . . . . . . . . . . 20315.4.9.5 Ada Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20415.4.9.6 Extensions for Ada Tasks . . . . . . . . . . . . . . . . . . . . . . . . . 20415.4.9.7 Tasking Support when Debugging Core Files . . . . . . 20715.4.9.8 Tasking Support when using the Ravenscar Prole

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20715.4.9.9 Known Peculiarities of Ada Mode . . . . . . . . . . . . . . . . . 208

15.5 Unsupported Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

16 Examining the Symbol Table . . . . . . . . . . . . . . 211

17 Altering Execution . . . . . . . . . . . . . . . . . . . . . . . . . . 21917.1 Assignment to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21917.2 Continuing at a Different Address . . . . . . . . . . . . . . . . . . . . . . . . . . . 22017.3 Giving your Program a Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22117.4 Returning from a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22117.5 Calling Program Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22317.6 Patching Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

8/9/2019 gdb manual

8/756

vi Debugging with gdb

18 gdb Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22518.1 Commands to Specify Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22518.2 Debugging Information in Separate Files . . . . . . . . . . . . . . . . . . . . 23318.3 Debugging information in a special section . . . . . . . . . . . . . . . . . . 23718.4 Index Files Speed Up gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

18.5 Errors Reading Symbol Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23818.6 GDB Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

19 Specifying a Debugging Target . . . . . . . . . . . . 24119.1 Active Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24119.2 Commands for Managing Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . 24119.3 Choosing Target Byte Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

20 Debugging Remote Programs . . . . . . . . . . . . . . 24520.1 Connecting to a Remote Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24520.2 Sending les to a remote system . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

20.3 Using the gdbserver Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24720.3.1 Running gdbserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24720.3.1.1 Attaching to a Running Program . . . . . . . . . . . . . . . . . . 24820.3.1.2 Multi-Process Mode for gdbserver . . . . . . . . . . . . . . . . 24820.3.1.3 TCP port allocation lifecycle of gdbserver . . . . . . . . 24920.3.1.4 Other Command-Line Arguments for gdbserver . . . 249

20.3.2 Connecting to gdbserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25020.3.3 Monitor Commands for gdbserver . . . . . . . . . . . . . . . . . . . . . 25020.3.4 Tracepoints support in gdbserver . . . . . . . . . . . . . . . . . . . . . . 251

20.4 Remote Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25220.5 Implementing a Remote Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

20.5.1 What the Stub Can Do for You . . . . . . . . . . . . . . . . . . . . . . . . 25820.5.2 What You Must Do for the Stub . . . . . . . . . . . . . . . . . . . . . . . 25920.5.3 Putting it All Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

21 Conguration-Specic Information . . . . . . . . 26321.1 Native . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

21.1.1 HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26321.1.2 BSD libkvm Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26321.1.3 SVR4 Process Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26321.1.4 Features for Debugging djgpp Programs . . . . . . . . . . . . . . . 26521.1.5 Features for Debugging MS Windows PE Executables . . 267

21.1.5.1 Support for DLLs without Debugging Symbols . . . . . 26921.1.5.2 DLL Name Prexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26921.1.5.3 Working with Minimal Symbols . . . . . . . . . . . . . . . . . . . 270

21.1.6 Commands Specic to gnu Hurd Systems . . . . . . . . . . . . . . 27021.1.7 Darwin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

21.2 Embedded Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27321.2.1 Using gdb with VxWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

21.2.1.1 Connecting to VxWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . 27421.2.1.2 VxWorks Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

8/9/2019 gdb manual

9/756

vii

21.2.1.3 Running Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27521.3 Embedded Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

21.3.1 ARM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27521.3.2 Renesas M32R/D and M32R/SDI . . . . . . . . . . . . . . . . . . . . . . 27721.3.3 M68k . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27821.3.4 MicroBlaze . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27921.3.5 MIPS Embedded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27921.3.6 PowerPC Embedded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28121.3.7 HP PA Embedded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28321.3.8 Tsqware Sparclet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

21.3.8.1 Setting File to Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28321.3.8.2 Connecting to Sparclet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28421.3.8.3 Sparclet Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28421.3.8.4 Running and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

21.3.9 Fujitsu Sparclite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28421.3.10 Zilog Z8000. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28421.3.11 Atmel AVR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

21.3.12 CRIS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

28521.3.13 Renesas Super-H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28621.4 Architectures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

21.4.1 AArch64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28621.4.2 x86 Architecture-specic Issues . . . . . . . . . . . . . . . . . . . . . . . . . 286

21.4.2.1 Intel(R) Memory Protection Extensions (MPX). . . . 28621.4.3 Alpha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28721.4.4 MIPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28721.4.5 HPPA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28921.4.6 Cell Broadband Engine SPU architecture . . . . . . . . . . . . . . . 28921.4.7 PowerPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29021.4.8 Nios II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

22 Controlling gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29122.1 Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29122.2 Command Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29122.3 Command History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29222.4 Screen Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29322.5 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29422.6 Conguring the Current ABI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29522.7 Automatically loading associated les . . . . . . . . . . . . . . . . . . . . . . . 296

22.7.1 Automatically loading init le in the current directory . . 29822.7.2 Automatically loading thread debugging library . . . . . . . . 298

22.7.3 Security restriction for auto-loading . . . . . . . . . . . . . . . . . . . . 29822.7.4 Displaying les tried for auto-load . . . . . . . . . . . . . . . . . . . . . . 300

22.8 Optional Warnings and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30122.9 Optional Messages about Internal Happenings . . . . . . . . . . . . . . . 30222.10 Other Miscellaneous Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

8/9/2019 gdb manual

10/756

viii Debugging with gdb

23 Extending gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30723.1 Canned Sequences of Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

23.1.1 User-dened Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30723.1.2 User-dened Command Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . 30923.1.3 Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

23.1.4 Commands for Controlled Output. . . . . . . . . . . . . . . . . . . . . .

31123.1.5 Controlling auto-loading native gdb scripts . . . . . . . . . . . . . 31323.2 Extending gdb using Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

23.2.1 Python Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31423.2.2 Python API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

23.2.2.1 Basic Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31523.2.2.2 Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31823.2.2.3 Values From Inferior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31923.2.2.4 Types In Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32423.2.2.5 Pretty Printing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32823.2.2.6 Selecting Pretty-Printers . . . . . . . . . . . . . . . . . . . . . . . . . . 32923.2.2.7 Writing a Pretty-Printer . . . . . . . . . . . . . . . . . . . . . . . . . . 330

23.2.2.8 Type Printing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33223.2.2.9 Filtering Frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33323.2.2.10 Decorating Frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33523.2.2.11 Writing a Frame Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . 33823.2.2.12 Xmethods In Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34223.2.2.13 Xmethod API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34223.2.2.14 Writing an Xmethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34423.2.2.15 Inferiors In Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34623.2.2.16 Events In Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34823.2.2.17 Threads In Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35023.2.2.18 Commands In Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35123.2.2.19 Parameters In Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35423.2.2.20 Writing new convenience functions . . . . . . . . . . . . . . . 35623.2.2.21 Program Spaces In Python . . . . . . . . . . . . . . . . . . . . . . . 35723.2.2.22 Objles In Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35823.2.2.23 Accessing inferior stack frames from Python. . . . . . 35923.2.2.24 Accessing blocks from Python. . . . . . . . . . . . . . . . . . . . 36123.2.2.25 Python representation of Symbols. . . . . . . . . . . . . . . . 36323.2.2.26 Symbol table representation in Python. . . . . . . . . . . . 36623.2.2.27 Manipulating line tables using Python . . . . . . . . . . . . 36723.2.2.28 Manipulating breakpoints using Python . . . . . . . . . . 36823.2.2.29 Finish Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37123.2.2.30 Python representation of lazy strings. . . . . . . . . . . . . 372

23.2.2.31 Python representation of architectures . . . . . . . . . . . . 37323.2.3 Python Auto-loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37323.2.4 Python modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

23.2.4.1 gdb.printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37423.2.4.2 gdb.types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37523.2.4.3 gdb.prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

23.3 Extending gdb using Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37723.3.1 Guile Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

8/9/2019 gdb manual

11/756

ix

23.3.2 Guile Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37723.3.3 Guile API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

23.3.3.1 Basic Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37823.3.3.2 Guile Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38023.3.3.3 GDB Scheme Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 38023.3.3.4 Guile Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . 38223.3.3.5 Values From Inferior In Guile . . . . . . . . . . . . . . . . . . . . . 38323.3.3.6 Arithmetic In Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38923.3.3.7 Types In Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39023.3.3.8 Guile Pretty Printing API . . . . . . . . . . . . . . . . . . . . . . . . . 39423.3.3.9 Selecting Guile Pretty-Printers . . . . . . . . . . . . . . . . . . . . 39623.3.3.10 Writing a Guile Pretty-Printer . . . . . . . . . . . . . . . . . . . 39723.3.3.11 Commands In Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39923.3.3.12 Parameters In Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40323.3.3.13 Program Spaces In Guile . . . . . . . . . . . . . . . . . . . . . . . . . 40523.3.3.14 Objles In Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40623.3.3.15 Accessing inferior stack frames from Guile. . . . . . . . 407

23.3.3.16 Accessing blocks from Guile. . . . . . . . . . . . . . . . . . . . . .

40923.3.3.17 Guile representation of Symbols. . . . . . . . . . . . . . . . . . 41123.3.3.18 Symbol table representation in Guile. . . . . . . . . . . . . . 41423.3.3.19 Manipulating breakpoints using Guile . . . . . . . . . . . . 41623.3.3.20 Guile representation of lazy strings. . . . . . . . . . . . . . . 41923.3.3.21 Guile representation of architectures . . . . . . . . . . . . . . 42023.3.3.22 Disassembly In Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42223.3.3.23 I/O Ports in Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42323.3.3.24 Memory Ports in Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . 42323.3.3.25 Iterators In Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

23.3.4 Guile Auto-loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42623.3.5 Guile Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

23.3.5.1 Guile Printing Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42723.3.5.2 Guile Types Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

23.4 Auto-loading extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42823.4.1 The ‘objfile -gdb. ext ’ le . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42823.4.2 The .debug_gdb_scripts section . . . . . . . . . . . . . . . . . . . . . . 42923.4.3 Which avor to choose? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

23.5 Multiple Extension Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43023.5.1 Python comes rst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

23.6 Creating new spellings of existing commands . . . . . . . . . . . . . . . . 431

24 Command Interpreters . . . . . . . . . . . . . . . . . . . . . 433

25 gdb Text User Interface . . . . . . . . . . . . . . . . . . . . 43525.1 TUI Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43525.2 TUI Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43625.3 TUI Single Key Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43725.4 TUI-specic Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43725.5 TUI Conguration Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

8/9/2019 gdb manual

12/756

x Debugging with gdb

26 Using gdb under gnu Emacs . . . . . . . . . . . . . . . 441

27 The gdb/mi Interface . . . . . . . . . . . . . . . . . . . . . . . 443Function and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443Notation and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44327.3 gdb/mi General Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

27.3.1 Context management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44427.3.1.1 Threads and Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44427.3.1.2 Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

27.3.2 Asynchronous command execution and non-stop mode . . 44527.3.3 Thread groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

27.4 gdb/mi Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44627.4.1 gdb/mi Input Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44727.4.2 gdb/mi Output Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

27.5 gdb/mi Compatibility with CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44927.6 gdb/mi Development and Front Ends . . . . . . . . . . . . . . . . . . . . . . . 44927.7 gdb/mi Output Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

27.7.1 gdb/mi Result Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45027.7.2 gdb/mi Stream Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45027.7.3 gdb/mi Async Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45127.7.4 gdb/mi Breakpoint Information . . . . . . . . . . . . . . . . . . . . . . . . 45427.7.5 gdb/mi Frame Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45627.7.6 gdb/mi Thread Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 45627.7.7 gdb/mi Ada Exception Information . . . . . . . . . . . . . . . . . . . . 457

27.8 Simple Examples of gdb/mi Interaction . . . . . . . . . . . . . . . . . . . . . 45727.9 gdb/mi Command Description Format . . . . . . . . . . . . . . . . . . . . . . 45827.10 gdb/mi Breakpoint Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45827.11 gdb/mi Catchpoint Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468

27.11.1 Shared Library gdb/mi Catchpoints . . . . . . . . . . . . . . . . . . 46827.11.2 Ada Exception gdb/mi Catchpoints . . . . . . . . . . . . . . . . . . . 46927.12 gdb/mi Program Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47027.13 gdb/mi Thread Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47227.14 gdb/mi Ada Tasking Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 47527.15 gdb/mi Program Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47627.16 gdb/mi Stack Manipulation Commands . . . . . . . . . . . . . . . . . . . . 48227.17 gdb/mi Variable Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48827.18 gdb/mi Data Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49827.19 gdb/mi Tracepoint Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50727.20 gdb/mi Symbol Query Commands . . . . . . . . . . . . . . . . . . . . . . . . . 51227.21 gdb/mi File Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51227.22 gdb/mi Target Manipulation Commands . . . . . . . . . . . . . . . . . . . 51427.23 gdb/mi File Transfer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 51827.24 Ada Exceptions gdb/mi Commands . . . . . . . . . . . . . . . . . . . . . . . 51927.25 gdb/mi Support Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51927.26 Miscellaneous gdb/mi Commands . . . . . . . . . . . . . . . . . . . . . . . . . 521

8/9/2019 gdb manual

13/756

xi

28 gdb Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52928.1 What is an Annotation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52928.2 The Server Prex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53028.3 Annotation for gdb Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53028.4 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531

28.5 Invalidation Notices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

53128.6 Running the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53128.7 Displaying Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532

29 JIT Compilation Interface . . . . . . . . . . . . . . . . . 53329.1 JIT Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53329.2 Registering Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53429.3 Unregistering Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53429.4 Custom Debug Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534

29.4.1 Using JIT Debug Info Readers . . . . . . . . . . . . . . . . . . . . . . . . . 53529.4.2 Writing JIT Debug Info Readers . . . . . . . . . . . . . . . . . . . . . . . 535

30 In-Process Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53730.1 In-Process Agent Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537

30.1.1 IPA Protocol Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53830.1.2 IPA Protocol Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539

31 Reporting Bugs in gdb . . . . . . . . . . . . . . . . . . . . . 54131.1 Have You Found a Bug? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54131.2 How to Report Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541

32 Command Line Editing . . . . . . . . . . . . . . . . . . . . . 54532.1 Introduction to Line Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54532.2 Readline Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545

32.2.1 Readline Bare Essentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54532.2.2 Readline Movement Commands . . . . . . . . . . . . . . . . . . . . . . . . 54632.2.3 Readline Killing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54632.2.4 Readline Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54732.2.5 Searching for Commands in the History . . . . . . . . . . . . . . . . 547

32.3 Readline Init File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54832.3.1 Readline Init File Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54832.3.2 Conditional Init Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55432.3.3 Sample Init File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555

32.4 Bindable Readline Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55832.4.1 Commands For Moving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55832.4.2 Commands For Manipulating The History . . . . . . . . . . . . . . 55832.4.3 Commands For Changing Text . . . . . . . . . . . . . . . . . . . . . . . . . 56032.4.4 Killing And Yanking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56132.4.5 Specifying Numeric Arguments . . . . . . . . . . . . . . . . . . . . . . . . . 56232.4.6 Letting Readline Type For You . . . . . . . . . . . . . . . . . . . . . . . . . 56232.4.7 Keyboard Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56332.4.8 Some Miscellaneous Commands . . . . . . . . . . . . . . . . . . . . . . . . 563

8/9/2019 gdb manual

14/756

xii Debugging with gdb

32.5 Readline vi Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

33 Using History Interactively . . . . . . . . . . . . . . . . 56733.1 History Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

33.1.1 Event Designators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

33.1.2 Word Designators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56833.1.3 Modiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568

Appendix A In Memoriam . . . . . . . . . . . . . . . . . . . . 571

Appendix B Formatting Documentation . . . . . 573

Appendix C Installing gdb . . . . . . . . . . . . . . . . . . . . 575C.1 Requirements for Building gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575C.2 Invoking the gdb ‘configure ’ Script . . . . . . . . . . . . . . . . . . . . . . . . 576

C.3 Compiling gdb in Another Directory . . . . . . . . . . . . . . . . . . . . . . . .

577C.4 Specifying Names for Hosts and Targets . . . . . . . . . . . . . . . . . . . . . 578C.5 ‘configure ’ Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579C.6 System-wide conguration and settings . . . . . . . . . . . . . . . . . . . . . . 580

C.6.1 Installed System-wide Conguration Scripts . . . . . . . . . . . . . 580

Appendix D Maintenance Commands . . . . . . . . 581

Appendix E gdb Remote Serial Protocol . . . . 589E.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589E.2 Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590

E.3 Stop Reply Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600E.4 General Query Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602E.5 Architecture-Specic Protocol Details . . . . . . . . . . . . . . . . . . . . . . . . 621

E.5.1 ARM-specic Protocol Details . . . . . . . . . . . . . . . . . . . . . . . . . . . 621E.5.1.1 ARM Breakpoint Kinds . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

E.5.2 MIPS -specic Protocol Details . . . . . . . . . . . . . . . . . . . . . . . . . . 621E.5.2.1 MIPS Register Packet Format . . . . . . . . . . . . . . . . . . . . . . 621E.5.2.2 MIPS Breakpoint Kinds . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622

E.6 Tracepoint Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622E.6.1 Relocate instruction reply packet . . . . . . . . . . . . . . . . . . . . . . . . 628

E.7 Host I/O Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629E.8 Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630E.9 Notication Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631E.10 Remote Protocol Support for Non-Stop Mode . . . . . . . . . . . . . . . 633E.11 Packet Acknowledgment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633E.12 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634E.13 File-I/O Remote Protocol Extension . . . . . . . . . . . . . . . . . . . . . . . . 634

E.13.1 File-I/O Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634E.13.2 Protocol Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635E.13.3 The F Request Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636

8/9/2019 gdb manual

15/756

xiii

E.13.4 The F Reply Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636E.13.5 The ‘Ctrl-C ’ Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636E.13.6 Console I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637E.13.7 List of Supported Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637

open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639lseek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641stat/fstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641gettimeofday . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642isatty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642

E.13.8 Protocol-specic Representation of Datatypes . . . . . . . . . . 643Integral Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643

Pointer Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

643Memory Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643struct stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644struct timeval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644

E.13.9 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645Open Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645mode t Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645Errno Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645Lseek Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646

E.13.10 File-I/O Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646E.14 Library List Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646E.15 Library List Format for SVR4 Targets . . . . . . . . . . . . . . . . . . . . . . 647E.16 Memory Map Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648E.17 Thread List Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649E.18 Traceframe Info Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649E.19 Branch Trace Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650

Appendix F The GDB Agent ExpressionMechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

F.1 General Bytecode Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653F.2 Bytecode Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655F.3 Using Agent Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660F.4 Varying Target Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661F.5 Rationale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

8/9/2019 gdb manual

16/756

xiv Debugging with gdb

Appendix G Target Descriptions . . . . . . . . . . . . . 665G.1 Retrieving Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665G.2 Target Description Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665

G.2.1 Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666G.2.2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

G.2.3 OS ABI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

667G.2.4 Compatible Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667G.2.5 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667G.2.6 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667G.2.7 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668

G.3 Predened Target Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669G.4 Standard Target Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

G.4.1 AArch64 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670G.4.2 ARM Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670G.4.3 i386 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671G.4.4 MicroBlaze Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672G.4.5 MIPS Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672

G.4.6 M68K Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672G.4.7 Nios II Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672G.4.8 PowerPC Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672G.4.9 S/390 and System z Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 673G.4.10 TMS320C6x Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

Appendix H Operating System Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

H.1 Process list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

Appendix I Trace File Format . . . . . . . . . . . . . . . 677

Appendix J .gdb_index section format . . . . . . . 679

Appendix K Manual pages . . . . . . . . . . . . . . . . . . . . 683

Appendix L GNU GENERAL PUBLICLICENSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689

Appendix M GNU Free Documentation License

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701

Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709

Command, Variable, and Function Index . . . . . . 723

8/9/2019 gdb manual

17/756

Summary of gdb 1

Summary of gdb

The purpose of a debugger such as gdb is to allow you to see what is going on “inside”

another program while it executes—or what another program was doing at the moment itcrashed.gdb can do four main kinds of things (plus other things in support of these) to help you

catch bugs in the act:• Start your program, specifying anything that might affect its behavior.• Make your program stop on specied conditions.• Examine what has happened, when your program has stopped.• Change things in your program, so you can experiment with correcting the effects of

one bug and go on to learn about another.

You can use gdb to debug programs written in C and C ++. For more information, see

Section 15.4 [Supported Languages], page 185 . For more information, see Section 15.4.1 [Cand C ++], page 185.Support for D is partial. For information on D, see Section 15.4.2 [D], page 191.Support for Modula-2 is partial. For information on Modula-2, see Section 15.4.8

[Modula-2], page 194.Support for OpenCL C is partial. For information on OpenCL C, see Section 15.4.5

[OpenCL C], page 193.Debugging Pascal programs which use sets, subranges, le variables, or nested functions

does not currently work. gdb does not support entering expressions, printing values, orsimilar features using Pascal syntax.

gdb can be used to debug programs written in Fortran, although it may be necessaryto refer to some variables with a trailing underscore.

gdb can be used to debug programs written in Objective-C, using either the Ap-ple/NeXT or the GNU Objective-C runtime.

Free Softwaregdb is free software , protected by the gnu General Public License (GPL). The GPL givesyou the freedom to copy or adapt a licensed program—but every person getting a copy alsogets with it the freedom to modify that copy (which means that they must get access to thesource code), and the freedom to distribute further copies. Typical software companies usecopyrights to limit your freedoms; the Free Software Foundation uses the GPL to preserve

these freedoms.Fundamentally, the General Public License is a license which says that you have thesefreedoms and that you cannot take these freedoms away from anyone else.

Free Software Needs Free DocumentationThe biggest deciency in the free software community today is not in the software—it is thelack of good free documentation that we can include with the free software. Many of ourmost important programs do not come with free reference manuals and free introductory

8/9/2019 gdb manual

18/756

2 Debugging with gdb

texts. Documentation is an essential part of any software package; when an important freesoftware package does not come with a free manual and a free tutorial, that is a major gap.We have many such gaps today.

Consider Perl, for instance. The tutorial manuals that people normally use are non-free.How did this come about? Because the authors of those manuals published them withrestrictive terms—no copying, no modication, source les not available—which excludethem from the free software world.

That wasn’t the rst time this sort of thing happened, and it was far from the last.Many times we have heard a GNU user eagerly describe a manual that he is writing, hisintended contribution to the community, only to learn that he had ruined everything bysigning a publication contract to make it non-free.

Free documentation, like free software, is a matter of freedom, not price. The problemwith the non-free manual is not that publishers charge a price for printed copies—that initself is ne. (The Free Software Foundation sells printed copies of manuals, too.) Theproblem is the restrictions on the use of the manual. Free manuals are available in sourcecode form, and give you permission to copy and modify. Non-free manuals do not allowthis.

The criteria of freedom for a free manual are roughly the same as for free software.Redistribution (including the normal kinds of commercial redistribution) must be permitted,so that the manual can accompany every copy of the program, both on-line and on paper.

Permission for modication of the technical content is crucial too. When people mod-ify the software, adding or changing features, if they are conscientious they will changethe manual too—so they can provide accurate and clear documentation for the modiedprogram. A manual that leaves you no choice but to write a new manual to document achanged version of the program is not really available to our community.

Some kinds of limits on the way modication is handled are acceptable. For example,requirements to preserve the original author’s copyright notice, the distribution terms, orthe list of authors, are ok. It is also no problem to require modied versions to includenotice that they were modied. Even entire sections that may not be deleted or changedare acceptable, as long as they deal with nontechnical topics (like this one). These kinds of restrictions are acceptable because they don’t obstruct the community’s normal use of themanual.

However, it must be possible to modify all the technical content of the manual, and thendistribute the result in all the usual media, through all the usual channels. Otherwise, therestrictions obstruct the use of the manual, it is not free, and we need another manual toreplace it.

Please spread the word about this issue. Our community continues to lose manualsto proprietary publishing. If we spread the word that free software needs free referencemanuals and free tutorials, perhaps the next person who wants to contribute by writingdocumentation will realize, before it is too late, that only free manuals contribute to thefree software community.

If you are writing documentation, please insist on publishing it under the GNU FreeDocumentation License or another free documentation license. Remember that this deci-sion requires your approval—you don’t have to let the publisher decide. Some commercialpublishers will use a free license if you insist, but they will not propose the option; it is up

8/9/2019 gdb manual

19/756

Summary of gdb 3

to you to raise the issue and say rmly that this is what you want. If the publisher youare dealing with refuses, please try other publishers. If you’re not sure whether a proposedlicense is free, write to [email protected] .

You can encourage commercial publishers to sell more free, copylefted manuals andtutorials by buying them, and particularly by buying copies from the publishers that paidfor their writing or for major improvements. Meanwhile, try to avoid buying non-freedocumentation at all. Check the distribution terms of a manual before you buy it, andinsist that whoever seeks your business must respect your freedom. Check the history of the book, and try to reward the publishers that have paid or pay the authors to work on it.

The Free Software Foundation maintains a list of free documentation published by otherpublishers, at http://www.fsf.org/doc/other-free-books.html .

Contributors to gdbRichard Stallman was the original author of gdb , and of many other gnu programs. Many

others have contributed to its development. This section attempts to credit major contrib-utors. One of the virtues of free software is that everyone is free to contribute to it; withregret, we cannot actually acknowledge everyone here. The le ‘ ChangeLog ’ in the gdbdistribution approximates a blow-by-blow account.

Changes much prior to version 2.0 are lost in the mists of time.Plea: Additions to this section are particularly welcome. If you or your friends(or enemies, to be evenhanded) have been unfairly omitted from this list, wewould like to add your names!

So that they may not regard their many labors as thankless, we particularly thank thosewho shepherded gdb through major releases: Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0,5.3, 5.2, 5.1 and 5.0); Jim Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs

(release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); Stu Grossmanand John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); John Gilmore (releases 4.3, 4.2, 4.1,4.0, and 3.9); Jim Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3.1,and 3.0).

Richard Stallman, assisted at various times by Peter TerMaat, Chris Hanson, andRichard Mlynarik, handled releases through 2.8.

Michael Tiemann is the author of most of the gnu C++ support in gdb , with signicantadditional contributions from Per Bothner and Daniel Berlin. James Clark wrote the gnuC++ demangler. Early work on C ++ was by Peter TerMaat (who also did much generalupdate work leading to release 3.0).

gdb uses the BFD subroutine library to examine multiple object-le formats; BFD was

a joint project of David V. Henkel-Wallace, Rich Pixley, Steve Chamberlain, and JohnGilmore.David Johnson wrote the original COFF support; Pace Willison did the original support

for encapsulated COFF.Brent Benson of Harris Computer Systems contributed DWARF 2 support.Adam de Boor and Bradley Davis contributed the ISI Optimum V support. Per Bothner,

Noboyuki Hikichi, and Alessandro Forin contributed MIPS support. Jean-Daniel Feketecontributed Sun 386i support. Chris Hanson improved the HP9000 support. Noboyuki

mailto:[email protected]://www.fsf.org/doc/other-free-books.htmlhttp://www.fsf.org/doc/other-free-books.htmlmailto:[email protected]

8/9/2019 gdb manual

20/756


Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. David Johnson con-tributed Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. Jeff Law contributed HP PA and SOM support. Keith Packard contributed NS32K support.Doug Rabson contributed Acorn Risc Machine support. Bob Rusk contributed HarrisNighthawk CX-UX support. Chris Smith contributed Convex support (and Fortran de-bugging). Jonathan Stone contributed Pyramid support. Michael Tiemann contributedSPARC support. Tim Tucker contributed support for the Gould NP1 and Gould Powern-ode. Pace Willison contributed Intel 386 support. Jay Vosburgh contributed Symmetrysupport. Marko Mlinar contributed OpenRISC 1000 support.

Andreas Schwab contributed M68K gnu /Linux support.Rich Schaefer and Peter Schauer helped with support of SunOS shared libraries.Jay Fenlason and Roland McGrath ensured that gdb and GAS agree about several

machine instruction sets.Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop remote

debugging. Intel Corporation, Wind River Systems, AMD, and ARM contributed remotedebugging modules for the i960, VxWorks, A29K UDI, and RDI targets, respectively.Brian Fox is the author of the readline libraries providing command-line editing and

command history.Andrew Beers of SUNY Buffalo wrote the language-switching code, the Modula-2 sup-

port, and contributed the Languages chapter of this manual.Fred Fish wrote most of the support for Unix System Vr4. He also enhanced the

command-completion support to cover C ++ overloaded symbols.Hitachi America (now Renesas America), Ltd. sponsored the support for H8/300,

H8/500, and Super-H processors.NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.

Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D proces-sors.

Toshiba sponsored the support for the TX39 Mips processor.Matsushita sponsored the support for the MN10200 and MN10300 processors.Fujitsu sponsored the support for SPARClite and FR30 processors.Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware watchpoints.Michael Snyder added support for tracepoints.Stu Grossman wrote gdbserver.Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly innumerable

bug xes and cleanups throughout gdb .The following people at the Hewlett-Packard Company contributed support for the PA-

RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 (narrow mode), HP’s implementationof kernel threads, HP’s aC ++ compiler, and the Text User Interface (nee Terminal UserInterface): Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, SatishPai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase provided HP-specicinformation in this manual.

DJ Delorie ported gdb to MS-DOS, for the DJGPP project. Robert Hoehne madesignicant contributions to the DJGPP port.

8/9/2019 gdb manual

21/756

Summary of gdb 5

Cygnus Solutions has sponsored gdb maintenance and much of its development since1991. Cygnus engineers who have worked on gdb fulltime include Mark Alexander, JimBlandy, Per Bothner, Kevin Buettner, Edith Epstein, Chris Faylor, Fred Fish, MartinHunt, Jim Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek Radouch, Keith Seitz,Stan Shebs, David Taylor, and Elena Zannoni. In addition, Dave Brolley, Ian Carmichael,Steve Chamberlain, Nick Clifton, JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, FrankEigler, Doug Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff Holcomb,Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, CatherineMoore, Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith, MikeStump, Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, JimWilson, and David Zuhn have made contributions both large and small.

Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for Cygnus Solu-tions, implemented the original gdb/mi interface.

Jim Blandy added support for preprocessor macros, while working for Red Hat.Andrew Cagney designed gdb ’s architecture vector. Many people including Andrew

Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, Richard Henderson, Mark Ket-tenis, Grace Sainsbury, Kei Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab,Jason Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped with themigration of old architectures to this new framework.

Andrew Cagney completely re-designed and re-implemented gdb ’s unwinder framework,this consisting of a fresh new design featuring frame IDs, independent frame sniffers, andthe sentinel frame. Mark Kettenis implemented the dwarf 2 unwinder, Jeff Johnston thelibunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad unwinders.The architecture-specic changes, each involving a complete rewrite of the architecture’sframe code, were carried out by Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew

Cagney, Stephane Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, DanielJacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei Sakamoto, YoshinoriSato, Michael Snyder, Corinna Vinschen, and Ulrich Weigand.

Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from Tensilica, Inc.contributed support for Xtensa processors. Others who have worked on the Xtensa port of gdb in the past include Steve Tjiang, John Newlin, and Scott Foehner.

Michael Eager and staff of Xilinx, Inc., contributed support for the Xilinx MicroBlazearchitecture.

8/9/2019 gdb manual

22/756

8/9/2019 gdb manual

23/756

Chapter 1: A Sample gdb Session 7

1 A Sample gdb SessionYou can use this manual at your leisure to read all about gdb . However, a handful of commands are enough to get started using the debugger. This chapter illustrates thosecommands.

In this sample session, we emphasize user input like this: input , to make it easier to pickout from the surrounding output.

One of the preliminary versions of gnu m4 (a generic macro processor) exhibits thefollowing bug: sometimes, when we change its quote strings from the default, the commandsused to capture one macro denition within another stop working. In the following short m4session, we dene a macro foo which expands to 0000 ; we then use the m4 built-in defn todene bar as the same thing. However, when we change the open quote string to and the close quote string to , the same procedure fails to dene a new synonymbaz :

$ cd gnu/m4

$ ./m4dene(foo,0000)

foo0000dene(bar,defn(‘foo’))

bar0000changequote( ,)

dene(baz,defn( foo))bazCtrl-d m4: End of input: 0: fatal error: EOF in string

Let us use gdb to try to see what is going on.$ gdb m4gdb is free software and you are welcome to distribute copies

of it under certain conditions; type "show copying" to seethe conditions.

There is absolutely no warranty for gdb ; type "show warranty"for details.

gdb 7.8.50.20140729-cvs, Copyright 1999 Free Software Foundation, Inc...(gdb)

gdb reads only enough symbol data to know where to nd the rest when needed; as a result,the rst prompt comes up very quickly. We now tell gdb to use a narrower display widththan usual, so that examples t in this manual.

(gdb) set width 70

We need to see how the m4 built-in changequote works. Having looked at the source, weknow the relevant subroutine is m4_changequote , so we set a breakpoint there with thegdb break command.

(gdb) break m4 changequoteBreakpoint 1 at 0x62f4: file builtin.c, line 879.

Using the run command, we start m4 running under gdb control; as long as control doesnot reach the m4_changequote subroutine, the program runs as usual:

8/9/2019 gdb manual

24/756


(gdb) runStarting program: /work/Editorial/gdb/gnu/m4/m4dene(foo,0000)

foo0000

To trigger the breakpoint, we call changequote . gdb suspends execution of m4, displayinginformation about the context where it stops.

changequote( ,)

Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)at builtin.c:879

879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))

Now we use the command n (next ) to advance execution to the next line of the currentfunction.

(gdb) n

882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\: nil,

set_quotes looks like a promising subroutine. We can go into it by using the command s(step ) instead of next . step goes to the next line to be executed in any subroutine, so itsteps into set_quotes .

(gdb) sset_quotes (lq=0x34c78 "", rq=0x34c88 "")

at input.c:530530 if (lquote != def_lquote)

The display that shows the subroutine where m4 is now suspended (and its arguments) iscalled a stack frame display. It shows a summary of the stack. We can use the backtracecommand (which can also be spelled bt ), to see where we are in the stack as a whole: thebacktrace command displays a stack frame for each active subroutine.

(gdb) bt#0 set_quotes (lq=0x34c78 "", rq=0x34c88 "")

at input.c:530#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)

at builtin.c:882#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)

at macro.c:71#4 0x79dc in expand_input () at macro.c:40#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195

We step through a few more lines to see what happens. The rst two times, we can use ‘ s ’;the next two times we use n to avoid falling into the xstrdup subroutine.

(gdb) s0x3b5c 532 if (rquote != def_rquote)(gdb) s0x3b80 535 lquote = (lq == nil || *lq == ’\0’) ? \def_lquote : xstrdup(lq);(gdb) n536 rquote = (rq == nil || *rq == ’\0’) ? def_rquote\

: xstrdup(rq);(gdb) n538 len_lquote = strlen(rquote);

8/9/2019 gdb manual

25/756

Chapter 1: A Sample gdb Session 9

The last line displayed looks a little odd; we can examine the variables lquote and rquoteto see if they are in fact the new left and right quotes we specied. We use the commandp (print ) to see their values.

(gdb) p lquote$1 = 0x35d40 ""(gdb) p rquote$2 = 0x35d50 ""

lquote and rquote are indeed the new left and right quotes. To look at some context, wecan display ten lines of source surrounding the current line with the l (list ) command.

(gdb) l533 xfree(rquote);534535 lquote = (lq == nil || *lq == ’\0’) ? def_lquote\

: xstrdup (lq);536 rquote = (rq == nil || *rq == ’\0’) ? def_rquote\

: xstrdup (rq);

537538 len_lquote = strlen(rquote);539 len_rquote = strlen(lquote);540 }541542 void

Let us step past the two lines that set len_lquote and len_rquote , and then examine thevalues of those variables.

(gdb) n539 len_rquote = strlen(lquote);(gdb) n540 }(gdb) p len lquote

$3 = 9(gdb) p len rquote$4 = 7

That certainly looks wrong, assuming len_lquote and len_rquote are meant to be thelengths of lquote and rquote respectively. We can set them to better values using the pcommand, since it can print the value of any expression—and that expression can includesubroutine calls and assignments.

(gdb) p len lquote=strlen(lquote)$5 = 7(gdb) p len rquote=strlen(rquote)$6 = 9

Is that enough to x the problem of using the new quotes with the m4 built-in defn ? We canallow m4 to continue executing with the c (continue ) command, and then try the examplethat caused trouble initially:

(gdb) cContinuing.

dene(baz,defn( foo))

baz0000

8/9/2019 gdb manual

26/756


Success! The new quotes now work just as well as the default ones. The problem seems tohave been just the two typos dening the wrong lengths. We allow m4 exit by giving it anEOF as input:

Ctrl-dProgram exited normally.

The message ‘Program exited normally. ’ is from gdb ; it indicates m4 has nished execut-ing. We can end our gdb session with the gdb quit command.

(gdb) quit

8/9/2019 gdb manual

27/756

Chapter 2: Getting In and Out of gdb 11

2 Getting In and Out of gdb

This chapter discusses how to start gdb , and how to get out of it. The essentials are:

• type ‘gdb ’ to start gdb .• type quit or Ctrl-d to exit.

2.1 Invoking gdbInvoke gdb by running the program gdb . Once started, gdb reads commands from theterminal until you tell it to exit.

You can also run gdb with a variety of arguments and options, to specify more of yourdebugging environment at the outset.

The command-line options described here are designed to cover a variety of situations;in some environments, some of these options may effectively be unavailable.

The most usual way to start gdb is with one argument, specifying an executable program:gdb programYou can also start with both an executable program and a core le specied:

gdb program core

You can, instead, specify a process ID as a second argument, if you want to debug arunning process:

gdb program 1234

would attach gdb to process 1234 (unless you also have a le named ‘ 1234 ’; gdb does checkfor a core le rst).

Taking advantage of the second command-line argument requires a fairly complete op-erating system; when you use gdb as a remote debugger attached to a bare board, theremay not be any notion of “process”, and there is often no way to get a core dump. gdbwill warn you if it is unable to attach or to read core dumps.

You can optionally have gdb pass any arguments after the executable le to the inferiorusing --args . This option stops option processing.

gdb --args gcc -O2 -c foo.c

This will cause gdb to debug gcc , and to set gcc ’s command-line arguments (seeSection 4.3 [Arguments], page 30 ) to ‘-O2 -c foo.c ’.

You can run gdb without printing the front material, which describes gdb ’snon-warranty, by specifying --silent (or -q / --quiet ):

gdb --silent

You can further control how gdb starts up by using command-line options. gdb itself canremind you of the options available.Type

gdb -help

to display all available options and briey describe their use (‘ gdb -h ’ is a shorter equiva-lent).

All options and command line arguments you give are processed in sequential order. Theorder makes a difference when the ‘ -x ’ option is used.

8/9/2019 gdb manual

28/756


2.1.1 Choosing FilesWhen gdb starts, it reads any arguments other than options as specifying an executablele and core le (or process ID). This is the same as if the arguments were specied by the

‘-se ’ and ‘-c ’ (or ‘-p ’) options respectively. ( gdb reads the rst argument that does nothave an associated option ag as equivalent to the ‘ -se ’ option followed by that argument;and the second argument that does not have an associated option ag, if any, as equivalentto the ‘-c ’/‘-p ’ option followed by that argument.) If the second argument begins with adecimal digit, gdb will rst attempt to attach to it as a process, and if that fails, attemptto open it as a corele. If you have a corele whose name begins with a digit, you canprevent gdb from treating it as a pid by prexing it with ‘ ./ ’, e.g. ‘./12345 ’.

If gdb has not been congured to included core le support, such as for most embeddedtargets, then it will complain about a second argument and ignore it.

Many options have both long and short forms; both are shown in the following list. gdbalso recognizes the long forms if you truncate them, so long as enough of the option ispresent to be unambiguous. (If you prefer, you can ag option arguments with ‘ -- ’ ratherthan ‘ - ’, though we illustrate the more usual convention.)

-symbols file-s file Read symbol table from le le .

-exec file-e file Use le le as the executable le to execute when appropriate, and for examining

pure data in conjunction with a core dump.

-se file Read symbol table from le le and use it as the executable le.

-core file-c file Use le le as a core dump to examine.

-pid number -p number Connect to process ID number , as with the attach command.

-command file-x file Execute commands from le le . The contents of this le is evaluated exactly

as the source command would. See Section 23.1.3 [Command les], page 310.

-eval-command command-ex command

Execute a single gdb command.This option may be used multiple times to call multiple commands. It may alsobe interleaved with ‘ -command ’ as required.

gdb -ex ’target sim’ -ex ’load’ \

-x setbreakpoints -ex ’run’ a.out-init-command file-ix file Execute commands from le le before loading the inferior (but after loading

gdbinit les). See Section 2.1.3 [Startup], page 16 .

-init-eval-command command-iex command

Execute a single gdb command before loading the inferior (but after loadinggdbinit les). See Section 2.1.3 [Startup], page 16 .

8/9/2019 gdb manual

29/756

Chapter 2: Getting In and Out of gdb 13

-directory directory -d directory

Add directory to the path to search for source and script les.

-r-readnow Read each symbol le’s entire symbol table immediately, rather than the default,which is to read it incrementally as it is needed. This makes startup slower,but makes future operations faster.

2.1.2 Choosing ModesYou can run gdb in various alternative modes—for example, in batch mode or quiet mode.

-nx-n Do not execute commands found in any initialization le. There are three init

les, loaded in the following order:

‘system.gdbinit’This is the system-wide init le. Its location is specied with the --with-system-gdbinit congure option (see Section C.6 [System-wide conguration], page 580 ). It is loaded rst when gdb starts,before command line options have been processed.

‘~/.gdbinit’This is the init le in your home directory. It is loaded next, after‘system.gdbinit ’, and before command options have been pro-cessed.

‘./.gdbinit’This is the init le in the current directory. It is loaded last, af-ter command line options other than -x and -ex have been pro-cessed. Command line options -x and -ex are processed last, after‘./.gdbinit ’ has been loaded.

For further documentation on startup processing, See Section 2.1.3 [Startup],page 16. For documentation on how to write command les, See Section 23.1.3[Command Files], page 310 .

-nh Do not execute commands found in ‘ ~/.gdbinit ’, the init le in your homedirectory. See Section 2.1.3 [Startup], page 16 .

-quiet-silent-q “Quiet”. Do not print the introductory and copyright messages. These mes-

sages are also suppressed in batch mode.-batch Run in batch mode. Exit with status 0 after processing all the command les

specied with ‘-x ’ (and all commands from initialization les, if not inhibitedwith ‘-n ’). Exit with nonzero status if an error occurs in executing the gdbcommands in the command les. Batch mode also disables pagination, sets un-limited terminal width and height see Section 22.4 [Screen Size], page 293, andacts as if set confirm off were in effect (see Section 22.8 [Messages/Warnings],page 301).

8/9/2019 gdb manual

30/756


Batch mode may be useful for running gdb as a lter, for example to downloadand run a program on another computer; in order to make this more useful, themessage

Program exited normally.

(which is ordinarily issued whenever a program running under gdb controlterminates) is not issued when running in batch mode.

-batch-silentRun in batch mode exactly like ‘ -batch ’, but totally silently. All gdb output tostdout

gdb manual

Documents

Transcript of gdb manual