Red Hat ENTERPRISE LINUX 3 - DEBUGGING WITH GDB User Manual
Red Hat Enterprise Linux 3
Debugging with gdb
Red Hat Enterprise Linux 3: Debugging with gdb
Copyright © 1987, 1989, 1991-2003 by Free Software Foundation, Inc.
Copyright © 2003 by Red Hat, Inc.
This documentation has been prepared by Red Hat, Inc.
Red Hat, Inc.
1801 Varsity Drive
Raleigh NC 27606-2072 USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588
Research Triangle Park NC 27709 USA
Manual identifier:
• PDF: rhds-gdb-EN-3-PDF-RHI (2003-09-24T01:08)
• HTML: rhds-gdb-EN-3-HTML-RHI (2003-09-24T01:08)
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation
License, Version 1.1 or any later version published by the Free Software Foundation; with no InvariantSections, with no
Front-Cover Texts, and with no Back-Cover Texts. A copy of the licenseis included in the section entitled “GNU Free
Documentation License”.
Red Hat, Inc. is not granting permission to any redistributor to use the Red Hat name.
Red Hat is a registered trademark and the Red Hat Shadow Man logo, RPM, and the RPM logo are trademarks of Red Hat, Inc.
Linux is a registered trademark of Linus Torvalds.
All other trademarks and copyrights referred to are the property of their respective owners.
HTML, PDF, and RPM versions of the manuals are availableon the Documentation CD and online at
http://www.redhat.com/docs/.
The GPG fingerprint of the security@redhat.com key is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E
Table of Contents
1. Debugging with gdb ........................................................................................................................ 1
2. Summary of gdb.............................................................................................................................. 3
2.1. Free software...................................................................................................................... 3
2.2. Free Software Needs Free Documentation ........................................................................ 3
2.3. Contributors to gdb ............................................................................................................ 4
3. A Sample gdb Session ..................................................................................................................... 7
4. Getting In and Out of gdb............................................................................................................ 11
4.1. Invoking gdb .................................................................................................................... 11
4.1.1. Choosing files ................................................................................................... 12
4.1.2. Choosing modes................................................................................................ 13
4.2. Quitting gdb .....................................................................................................................16
4.3. Shell commands ............................................................................................................... 16
4.4. Logging output................................................................................................................. 16
5. gdb Commands .............................................................................................................................19
5.1. Command syntax .............................................................................................................19
5.2. Command completion......................................................................................................19
5.3. Getting help......................................................................................................................21
6. Running Programs Under gdb ....................................................................................................25
6.1. Compiling for debugging ................................................................................................. 25
6.2. Starting your program ...................................................................................................... 25
6.3. Your program’s arguments...............................................................................................26
6.4. Your program’s environment ........................................................................................... 27
6.5. Your program’s working directory................................................................................... 28
6.6. Your program’s input and output .....................................................................................28
6.7. Debugging an already-running process ...........................................................................29
6.8. Killing the child process .................................................................................................. 29
6.9. Debugging programs with multiple threads..................................................................... 30
6.10. Debugging programs with multiple processes...............................................................32
7. Stopping and Continuing .............................................................................................................35
7.1. Breakpoints, watchpoints, and catchpoints...................................................................... 35
7.1.1. Setting breakpoints............................................................................................35
7.1.2. Setting watchpoints...........................................................................................38
7.1.3. Setting catchpoints ............................................................................................40
7.1.4. Deleting breakpoints ......................................................................................... 41
7.1.5. Disabling breakpoints .......................................................................................42
7.1.6. Break conditions ............................................................................................... 43
7.1.7. Breakpoint command lists................................................................................. 44
7.1.8. Breakpoint menus ............................................................................................. 45
7.1.9. "Cannot insert breakpoints" .............................................................................. 46
7.2. Continuing and stepping ..................................................................................................46
7.3. Signals..............................................................................................................................49
7.4. Stopping and starting multi-thread programs ..................................................................51
8. Examining the Stack .....................................................................................................................53
8.1. Stack frames.....................................................................................................................53
8.2. Backtraces........................................................................................................................ 54
8.3. Selecting a frame.............................................................................................................. 55
8.4. Information about a frame ...............................................................................................56
9. Examining Source Files ................................................................................................................59
9.1. Printing source lines.........................................................................................................59
9.2. Editing source files........................................................................................................... 60
9.2.1. Choosing your editor.........................................................................................61
9.3. Searching source files ......................................................................................................61
9.4. Specifying source directories........................................................................................... 62
9.5. Source and machine code.................................................................................................63
10. Examining Data........................................................................................................................... 65
10.1. Expressions .................................................................................................................... 65
10.2. Program variables .......................................................................................................... 66
10.3. Artificial arrays ..............................................................................................................67
10.4. Output formats ............................................................................................................... 68
10.5. Examining memory........................................................................................................69
10.6. Automatic display ..........................................................................................................71
10.7. Print settings .................................................................................................................. 72
10.8. Value history ..................................................................................................................77
10.9. Convenience variables ...................................................................................................78
10.10. Registers.......................................................................................................................79
10.11. Floating point hardware ............................................................................................... 80
10.12. Vector Unit................................................................................................................... 81
10.13. Memory region attributes............................................................................................. 81
10.13.1. Attributes.......................................................................................................82
10.14. Copy between memory and a file................................................................................. 83
10.15. Character Sets ..............................................................................................................84
11. C Preprocessor Macros...............................................................................................................89
12. Tracepoints .................................................................................................................................. 93
12.1. Commands to Set Tracepoints ....................................................................................... 93
12.1.1. Create and Delete Tracepoints ........................................................................ 93
12.1.2. Enable and Disable Tracepoints...................................................................... 94
12.1.3. Tracepoint Passcounts..................................................................................... 94
12.1.4. Tracepoint Action Lists................................................................................... 95
12.1.5. Listing Tracepoints ......................................................................................... 96
12.1.6. Starting and Stopping Trace Experiment........................................................ 96
12.2. Using the collected data ................................................................................................. 97
12.2.1. tfind n.......................................................................................................... 97
12.2.2. tdump.............................................................................................................. 99
12.2.3. save-tracepoints filename .................................................................. 100
12.3. Convenience Variables for Tracepoints........................................................................ 100
13. Debugging Programs That Use Overlays................................................................................103
13.1. How Overlays Work.....................................................................................................103
13.2. Overlay Commands .....................................................................................................104
13.3. Automatic Overlay Debugging .................................................................................... 106
13.4. Overlay Sample Program ............................................................................................. 107
14. Using gdb with Different Languages.......................................................................................109
14.1. Switching between source languages........................................................................... 109
14.1.1. List of filename extensions and languages.................................................... 109
14.1.2. Setting the working language........................................................................ 110
14.1.3. Having gdb infer the source language .......................................................... 110
14.2. Displaying the language............................................................................................... 110
14.3. Type and range checking..............................................................................................111
14.3.1. An overview of type checking ......................................................................111
14.3.2. An overview of range checking .................................................................... 112
14.4. Supported languages .................................................................................................... 113
14.4.1. C and C++ ....................................................................................................113
14.4.2. Objective-C................................................................................................... 119
14.4.3. Modula-2.......................................................................................................121
14.5. Unsupported languages................................................................................................ 126
15. Examining the Symbol Table ................................................................................................... 129
16. Altering Execution .................................................................................................................... 135
16.1. Assignment to variables............................................................................................... 135
16.2. Continuing at a different address ................................................................................. 136
16.3. Giving your program a signal ......................................................................................137
16.4. Returning from a function............................................................................................ 137
16.5. Calling program functions ...........................................................................................137
16.6. Patching programs .......................................................................................................138
17. gdb Files ..................................................................................................................................... 139
17.1. Commands to specify files ........................................................................................... 139
17.2. Debugging Information in Separate Files ....................................................................145
17.3. Errors reading symbol files ..........................................................................................147
18. Specifying a Debugging Target ................................................................................................ 149
18.1. Active targets ............................................................................................................... 149
18.2. Commands for managing targets ................................................................................. 149
18.3. Choosing target byte order ...........................................................................................151
18.4. Remote debugging ....................................................................................................... 151
18.5. Kernel Object Display.................................................................................................. 151
19. Debugging remote programs.................................................................................................... 153
19.1. Connecting to a remote target ...................................................................................... 153
19.2. Using the gdbserverprogram .................................................................................... 154
19.3. Using the gdbserve.nlmprogram..............................................................................155
19.4. Remote configuration...................................................................................................155
19.5. Implementing a remote stub......................................................................................... 156
19.5.1. What the stub can do for you ........................................................................ 157
19.5.2. What you must do for the stub ...................................................................... 157
19.5.3. Putting it all together..................................................................................... 158
20. Configuration-Specific Information ........................................................................................ 161
20.1. Native...........................................................................................................................161
20.1.1. HP-UX .......................................................................................................... 161
20.1.2. SVR4 process information............................................................................161
20.1.3. Features for Debugging djgpp Programs ......................................................161
20.1.4. Features for Debugging MS Windows PE executables................................. 163
20.2. Embedded Operating Systems ..................................................................................... 166
20.2.1. Using gdb with VxWorks.............................................................................. 166
20.3. Embedded Processors .................................................................................................. 168
20.3.1. ARM ............................................................................................................. 168
20.3.2. Hitachi H8/300.............................................................................................. 168
20.3.3. H8/500........................................................................................................... 171
20.3.4. Mitsubishi M32R/D ...................................................................................... 171
20.3.5. M68k.............................................................................................................171
20.3.6. MIPS Embedded ...........................................................................................172
20.3.7. OpenRISC 1000 ............................................................................................173
20.3.8. PowerPC ....................................................................................................... 175
20.3.9. HP PA Embedded.......................................................................................... 176
20.3.10. Hitachi SH................................................................................................... 176
20.3.11. Tsqware Sparclet......................................................................................... 176
20.3.12. Fujitsu Sparclite .......................................................................................... 178
20.3.13. Tandem ST2000 ..........................................................................................178
20.3.14. Zilog Z8000 ................................................................................................179
20.4. Architectures ................................................................................................................ 180
20.4.1. A29K............................................................................................................. 180
20.4.2. Alpha............................................................................................................. 180
20.4.3. MIPS ............................................................................................................. 180
21. Controlling gdb .........................................................................................................................181
21.1. Prompt.......................................................................................................................... 181
21.2. Command editing......................................................................................................... 181
21.3. Command history.........................................................................................................181
21.4. Screen size ...................................................................................................................183
21.5. Numbers.......................................................................................................................183
21.6. Configuring the current ABI ........................................................................................ 184
21.7. Optional warnings and messages................................................................................. 185
21.8. Optional messages about internal happenings ............................................................. 186
22. Canned Sequences of Commands............................................................................................ 189
22.1. User-defined commands............................................................................................... 189
22.2. User-defined command hooks...................................................................................... 190
22.3. Command files .............................................................................................................191
22.4. Commands for controlled output ................................................................................. 192
23. Command Interpreters............................................................................................................. 195
24. gdb Text User Interface ............................................................................................................ 197
24.1. TUI overview ............................................................................................................... 197
24.2. TUI Key Bindings........................................................................................................198
24.3. TUI Single Key Mode.................................................................................................. 200
24.4. TUI specific commands ...............................................................................................200
24.5. TUI configuration variables ......................................................................................... 201
25. Using gdb under gnu Emacs .................................................................................................... 203
26. The gdb/mi Interface ................................................................................................................207
26.1. Function and Purpose................................................................................................... 207
26.2. Notation and Terminology ...........................................................................................207
26.3. Acknowledgments........................................................................................................207
26.4. gdb/mi Command Syntax ............................................................................................ 207
26.4.1. gdb/mi Input Syntax...................................................................................... 207
26.4.2. gdb/mi Output Syntax ...................................................................................208
26.4.3. Simple Examples of gdb/mi Interaction ....................................................... 210
26.5. gdb/mi Compatibility with CLI ...................................................................................211
26.6. gdb/mi Output Records ................................................................................................211
26.6.1. gdb/mi Result Records .................................................................................. 211
26.6.2. gdb/mi Stream Records................................................................................. 212
26.6.3. gdb/mi Out-of-band Records ........................................................................ 212
26.7. gdb/mi Command Description Format ........................................................................ 212
26.7.1. Motivation..................................................................................................... 212
26.7.2. Introduction................................................................................................... 213
26.7.3. Commands ....................................................................................................213
26.8. gdb/mi Breakpoint table commands ............................................................................ 213
26.8.1. The -break-afterCommand..................................................................... 213
26.8.2. The -break-conditionCommand ............................................................214
26.8.3. The -break-deleteCommand................................................................... 215
26.8.4. The -break-disableCommand ................................................................216
26.8.5. The -break-enableCommand................................................................... 216
26.8.6. The -break-infoCommand....................................................................... 217
26.8.7. The -break-insertCommand................................................................... 217
26.8.8. The -break-listCommand....................................................................... 219
26.8.9. The -break-watchCommand..................................................................... 220
26.9. gdb/mi Data Manipulation ........................................................................................... 223
26.9.1. The -data-disassembleCommand.......................................................... 223
26.9.2. The -data-evaluate-expressionCommand......................................... 225
26.9.3. The -data-list-changed-registersCommand ..................................226
26.9.4. The -data-list-register-namesCommand......................................... 227
26.9.5. The -data-list-register-valuesCommand ......................................227
26.9.6. The -data-read-memoryCommand.......................................................... 229
26.9.7. The -display-deleteCommand .............................................................. 231
26.9.8. The -display-disableCommand ............................................................231
26.9.9. The -display-enableCommand .............................................................. 231
26.9.10. The -display-insertCommand ............................................................ 232
26.9.11. The -display-listCommand................................................................. 232
26.9.12. The -environment-cdCommand ............................................................ 233
26.9.13. The -environment-directoryCommand ............................................. 233
26.9.14. The -environment-pathCommand........................................................234
26.9.15. The -environment-pwdCommand .......................................................... 235
26.10. gdb/mi Program control .............................................................................................235
26.10.1. Program termination ................................................................................... 235
26.10.2. Examples.....................................................................................................235
26.11. Command Descriptions..............................................................................................236
26.11.1. The -exec-abortCommand.....................................................................236
26.11.2. The -exec-argumentsCommand ............................................................ 236
26.11.3. The -exec-continueCommand .............................................................. 237
26.11.4. The -exec-finishCommand...................................................................237
26.11.5. The -exec-interruptCommand ............................................................ 238
26.11.6. The -exec-nextCommand ....................................................................... 239
26.11.7. The -exec-next-instructionCommand ............................................. 239
26.11.8. The -exec-returnCommand...................................................................240
26.11.9. The -exec-runCommand ......................................................................... 241
26.11.10. The -exec-show-argumentsCommand ............................................... 242
26.11.11. The -exec-stepCommand ..................................................................... 242
26.11.12. The -exec-step-instructionCommand ........................................... 243
26.11.13. The -exec-untilCommand...................................................................243
26.11.14. The -file-exec-and-symbolsCommand ........................................... 244
26.11.15. The -file-exec-fileCommand ..........................................................245
26.11.16. The -file-list-exec-sectionsCommand....................................... 245
26.11.17. The -file-list-exec-source-fileCommand ................................246
26.11.18. The -file-list-exec-source-filesCommand .............................. 246
26.11.19. The -file-list-shared-librariesCommand ................................247
26.11.20. The -file-list-symbol-filesCommand.........................................247
26.11.21. The -file-symbol-fileCommand......................................................247
26.12. Miscellaneous gdb commands in gdb/mi................................................................... 248
26.12.1. The -gdb-exitCommand ......................................................................... 248
26.12.2. The -gdb-setCommand ........................................................................... 249
26.12.3. The -gdb-showCommand ......................................................................... 249
26.12.4. The -gdb-versionCommand...................................................................250
26.12.5. The -interpreter-execCommand........................................................250
26.12.6. Synopsis ......................................................................................................250
26.12.7. gdb Command............................................................................................. 251
26.12.8. Example ......................................................................................................251
26.13. gdb/mi Stack Manipulation Commands ....................................................................251
26.13.1. The -stack-info-frameCommand........................................................251
26.13.2. The -stack-info-depthCommand........................................................251
26.13.3. The -stack-list-argumentsCommand ............................................... 252
26.13.4. The -stack-list-framesCommand...................................................... 253
26.13.5. The -stack-list-localsCommand...................................................... 255
26.13.6. The -stack-select-frameCommand.................................................... 256
26.14. gdb/mi Symbol Query Commands ............................................................................ 256
26.14.1. The -symbol-info-addressCommand ................................................. 256
26.14.2. The -symbol-info-fileCommand........................................................257
26.14.3. The -symbol-info-functionCommand ............................................... 257
26.14.4. The -symbol-info-lineCommand........................................................258
26.14.5. The -symbol-info-symbolCommand.................................................... 258
26.14.6. The -symbol-list-functionsCommand ............................................. 258
26.14.7. The -symbol-list-linesCommand...................................................... 259
26.14.8. The -symbol-list-typesCommand...................................................... 259
26.14.9. The -symbol-list-variablesCommand ............................................. 260
26.14.10. The -symbol-locateCommand ............................................................ 260
26.14.11. The -symbol-typeCommand.................................................................261
26.15. gdb/mi Target Manipulation Commands ...................................................................261
26.15.1. The -target-attachCommand .............................................................. 261
26.15.2. The -target-compare-sectionsCommand......................................... 262
26.15.3. The -target-detachCommand .............................................................. 262
26.15.4. The -target-disconnectCommand...................................................... 262
26.15.5. The -target-downloadCommand .......................................................... 263
26.15.6. The -target-exec-statusCommand.................................................... 265
26.15.7. The -target-list-available-targetsCommand............................ 265
26.15.8. The -target-list-current-targetsCommand ................................ 266
26.15.9. The -target-list-parametersCommand...........................................266
26.15.10. The -target-selectCommand ............................................................ 266
26.16. gdb/mi Thread Commands.........................................................................................267
26.16.1. The -thread-infoCommand...................................................................267
26.16.2. The -thread-list-all-threadsCommand......................................... 268
26.16.3. The -thread-list-idsCommand .......................................................... 268
26.16.4. The -thread-selectCommand .............................................................. 269
26.17. gdb/mi Tracepoint Commands...................................................................................270
26.18. gdb/mi Variable Objects.............................................................................................270
26.18.1. Motivation for Variable Objects in gdb/mi .................................................270
26.18.2. Introduction to Variable Objects in gdb/mi................................................. 270
26.18.3. Description And Use of Operations on Variable Objects ........................... 271
26.18.4. The -var-createCommand.....................................................................271
26.18.5. The -var-deleteCommand.....................................................................272
26.18.6. The -var-set-formatCommand ............................................................ 272
26.18.7. The -var-show-formatCommand .......................................................... 272
26.18.8. The -var-info-num-childrenCommand ............................................. 273
26.18.9. The -var-list-childrenCommand...................................................... 273
26.18.10. The -var-info-typeCommand ............................................................ 273
26.18.11. The -var-info-expressionCommand ............................................... 274
26.18.12. The -var-show-attributes Command .............................................. 274
26.18.13. The -var-evaluate-expression Command...................................... 274
26.18.14. The -var-assignCommand...................................................................275
26.18.15. The -var-updateCommand...................................................................275
27. gdb Annotations ........................................................................................................................277
27.1. What is an Annotation?................................................................................................277
27.2. The Server Prefix .........................................................................................................277
27.3. Values........................................................................................................................... 277
27.4. Frames.......................................................................................................................... 279
27.5. Displays........................................................................................................................ 281
27.6. Annotation for gdb Input .............................................................................................281
27.7. Errors............................................................................................................................282
27.8. Information on Breakpoints ......................................................................................... 282
27.9. Invalidation Notices .....................................................................................................283
27.10. Running the Program ................................................................................................. 283
27.11. Displaying Source ......................................................................................................284
27.12. Annotations We Might Want in the Future ................................................................285
28. Reporting Bugs in gdb .............................................................................................................. 287
28.1. Have you found a bug? ................................................................................................287
28.2. How to report bugs.......................................................................................................287
29. Command Line Editing ............................................................................................................ 291
29.1. Introduction to Line Editing.........................................................................................291
29.2. Readline Interaction ..................................................................................................... 291
29.2.1. Readline Bare Essentials...............................................................................291
29.2.2. Readline Movement Commands ................................................................... 292
29.2.3. Readline Killing Commands......................................................................... 292
29.2.4. Readline Arguments...................................................................................... 293
29.2.5. Searching for Commands in the History.......................................................293
29.3. Readline Init File.......................................................................................................... 294
29.3.1. Readline Init File Syntax .............................................................................. 294
29.3.2. Conditional Init Constructs...........................................................................298
29.3.3. Sample Init File............................................................................................. 299
29.4. Bindable Readline Commands..................................................................................... 301
29.4.1. Commands For Moving ................................................................................301
29.4.2. Commands For Manipulating The History ...................................................302
29.4.3. Commands For Changing Text ..................................................................... 303
29.4.4. Killing And Yanking..................................................................................... 304
29.4.5. Specifying Numeric Arguments ...................................................................305
29.4.6. Letting Readline Type For You.....................................................................305
29.4.7. Keyboard Macros.......................................................................................... 306
29.4.8. Some Miscellaneous Commands .................................................................. 306
29.5. Readline vi Mode.........................................................................................................308
30. Using History Interactively ...................................................................................................... 309
30.1. History Expansion........................................................................................................ 309
30.1.1. Event Designators ......................................................................................... 309
30.1.2. Word Designators.......................................................................................... 310
30.1.3. Modifiers....................................................................................................... 311
A. Formatting Documentation.......................................................................................................313
B. Installing gdb .............................................................................................................................. 315
B.1. Compiling gdb in another directory ..............................................................................316
B.2. Specifying names for hosts and targets ......................................................................... 317
B.3. configure options....................................................................................................... 318
C. Maintenance Commands ........................................................................................................... 319
D. gdb Remote Serial Protocol....................................................................................................... 321
D.1. Overview.......................................................................................................................321
D.2. Packets ..........................................................................................................................322
D.3. Stop Reply Packets........................................................................................................ 330
D.4. General Query Packets..................................................................................................331
D.5. Register Packet Format ................................................................................................. 334
D.6. Examples.......................................................................................................................334
D.7. File-I/O remote protocol extension ...............................................................................335
D.7.1. File-I/O Overview .......................................................................................... 335
D.7.2. Protocol basics ...............................................................................................335
D.7.3. The Frequest packet ....................................................................................... 336
D.7.4. The Freply packet...........................................................................................336
D.7.5. Memory transfer.............................................................................................337
D.7.6. The Ctrl-C message........................................................................................337
D.7.7. Console I/O ....................................................................................................337
D.7.8. The isatty(3) call ............................................................................................ 338
D.7.9. The system(3) call.......................................................................................... 338
D.7.10. List of supported calls ..................................................................................338
D.7.11. Protocol specific representation of datatypes............................................... 347
D.7.12. Constants...................................................................................................... 349
D.7.13. File-I/O Examples ........................................................................................ 350
E. The GDB Agent Expression Mechanism..................................................................................353
E.1. General Bytecode Design.............................................................................................. 353
E.2. Bytecode Descriptions...................................................................................................355
E.3. Using Agent Expressions .............................................................................................. 359
E.4. Varying Target Capabilities ...........................................................................................359
E.5. Tracing on Symmetrix...................................................................................................360
E.6. Rationale........................................................................................................................361
F. GNU GENERAL PUBLIC LICENSE...................................................................................... 365
F.1. Preamble ........................................................................................................................ 365
F.2. How to Apply These Terms to Your New Programs...................................................... 368
G. GNU Free Documentation License........................................................................................... 371
G.1. ADDENDUM: How to use this License for your documents.......................................375
Index.................................................................................................................................................377
Chapter 1.
Debugging with gdb
This file describes gdb, the gnu symbolic debugger.
This is the Ninth Edition, for gdb Version 2003-07-22-cvs.
Copyright (C) 1988-2003 Free Software Foundation, Inc.
2 Chapter 1. Debugging with gdb
Chapter 2.
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 it crashed.
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 specified 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, (refer to Section
14.4 Supported languages. For more information, (refer to Section 14.4.1 C and C++.
Support for Modula-2 is partial. For information on Modula-2, refer to (refer to Section 14.4.3
Modula-2.
Debugging Pascal programs which use sets, subranges, file variables, or nested functions does not
currently work. gdb does not support entering expressions, printing values, or similar features using
Pascal syntax.
gdb can be used to debug programs written in Fortran, although it may be necessary to refer to some
variables with a trailing underscore.
gdb can be used to debug programs written in Objective-C, using either the Apple/NeXT or the GNU
Objective-C runtime.
2.1. Free software
gdb is free software, protected by the gnu General Public License (GPL). The GPL gives you the free-
dom to copy or adapt a licensed program--but every person getting a copy also gets with it the freedom
to modify that copy (which means that they must get access to the source code), and the freedom to
distribute further copies. Typical software companies use copyrights 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 these freedoms and
that you cannot take these freedoms away from anyone else.
2.2. Free Software Needs Free Documentation
The biggest deficiency in the free software community today is not in the software--it is the lack of
good free documentation that we can include with the free software. Many of our most important
programs do not come with free reference manuals and free introductory texts. Documentation is an
essential part of any software package; when an important free software 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 with restrictive terms--no copying,
no modification, source files not available--which exclude them from the free software world.
4 Chapter 2. Summary of gdb
That wasn’t the first 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, his intended contribution to the
community, only to learn that he had ruined everything by signing a publication contract to make it
non-free.
Free documentation, like free software, is a matter of freedom, not price. The problem with the nonfree manual is not that publishers charge a price for printed copies--that in itself is fine. (The Free
Software Foundation sells printed copies of manuals, too.) The problem is the restrictions on the use
of the manual. Free manuals are available in source code form, and give you permission to copy and
modify. Non-free manuals do not allow this.
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 modification of the technical content is crucial too. When people modify the software,
adding or changing features, if they are conscientious they will change the manual too--so they can
provide accurate and clear documentation for the modified program. A manual that leaves you no
choice but to write a new manual to document a changed version of the program is not really available
to our community.
Some kinds of limits on the way modification is handled are acceptable. For example, requirements
to preserve the original author’s copyright notice, the distribution terms, or the list of authors, are ok.
It is also no problem to require modified versions to include notice that they were modified. Even
entire sections that may not be deleted or changed are 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 the manual.
However, it must be possible to modify all the technical content of the manual, and then distribute the
result in all the usual media, through all the usual channels. Otherwise, the restrictions obstruct the
use of the manual, it is not free, and we need another manual to replace it.
Please spread the word about this issue. Our community continues to lose manuals to proprietary
publishing. If we spread the word that free software needs free reference manuals and free tutorials,
perhaps the next person who wants to contribute by writing documentation will realize, before it is
too late, that only free manuals contribute to the free software community.
If you are writing documentation, please insist on publishing it under the GNU Free Documentation
License or another free documentation license. Remember that this decision requires your approval-you don’t have to let the publisher decide. Some commercial publishers will use a free license if you
insist, but they will not propose the option; it is up to you to raise the issue and say firmly that this is
what you want. If the publisher you are dealing with refuses, please try other publishers. If you’re not
sure whether a proposed license is free, write to mailto:licensing@@gnu.org.
You can encourage commercial publishers to sell more free, copylefted manuals and tutorials by
buying them, and particularly by buying copies from the publishers that paid for their writing or
for major improvements. Meanwhile, try to avoid buying non-free documentation at all. Check the
distribution terms of a manual before you buy it, and insist 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 other publishers,
at http://www.fsf.org/doc/other-free-books.html.
2.3. Contributors to gdb
Richard 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 contributors. One of the virtues
of free software is that everyone is free to contribute to it; with regret, we cannot actually acknowledge
everyone here. The file ChangeLog in the gdb distribution approximates a blow-by-blow account.
Chapter 2. Summary of gdb 5
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, we would like to add your names!
So that they may not regard their many labors as thankless, we particularly thank those who shepherded gdb through major releases: Andrew Cagney (releases 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 Grossman and 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, and Richard Mlynarik,
handled releases through 2.8.
Michael Tiemann is the author of most of the gnu C++ support in gdb, with significant additional
contributions from Per Bothner and Daniel Berlin. James Clark wrote the gnu C++ demangler. Early
work on C++ was by Peter TerMaat (who also did much general update work leading to release 3.0).
gdb uses the BFD subroutine library to examine multiple object-file formats; BFD was a joint project
of David V. Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
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 Fekete contributed Sun 386i
support. Chris Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. David Johnson contributed 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 Harris Nighthawk CX-UX support. Chris Smith contributed Convex support (and Fortran
debugging). Jonathan Stone contributed Pyramid support. Michael Tiemann contributed SPARC support. Tim Tucker contributed support for the Gould NP1 and Gould Powernode. Pace Willison contributed Intel 386 support. Jay Vosburgh contributed Symmetry support. 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 remote debugging 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 support, 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, 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 sponsored the support for D10V, D30V, and M32R/D processors.
Toshiba sponsored the support for the TX39 Mips processor.
6 Chapter 2. Summary of gdb
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 fixes 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 implementation of kernel threads,
HP’s aC++ compiler, and the terminal user interface: Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
provided HP-specific information in this manual.
DJ Delorie ported gdb to MS-DOS, for the DJGPP project. Robert Hoehne made significant contributions to the DJGPP port.
Cygnus Solutions has sponsored gdb maintenance and much of its development since 1991. Cygnus
engineers who have worked on gdb fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, 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, Frank Eigler, Doug Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, Catherine
Moore, Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump,
Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David Zuhn
have made contributions both large and small.
Jim Blandy added support for preprocessor macros, while working for Red Hat.
Chapter 3.
A Sample gdb Session
You 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 those commands.
One of the preliminary versions of gnu m4 (a generic macro processor) exhibits the following bug:
sometimes, when we change its quote strings from the default, the commands used to capture one
macro definition within another stop working. In the following short m4 session, we define a macro
foo which expands to 0000; we then use the m4 built-in defn to define bar as the same thing. How-
ever, when we change the open quote string to
QUOTE
and the close quote string to
UNQUOTE
,
the same procedure fails to define a new synonym baz:
$ cd gnu/m4
$ ./m4
define(foo,0000)
foo
0000
define(bar,defn(‘foo’))
bar
0000
changequote(
QUOTE,UNQUOTE)
define(baz,defn(QUOTEfooUNQUOTE))
baz
C-d
m4: End of input: 0: fatal error: EOF in string
Let us use gdb to try to see what is going on.
$ gdb m4
gdb is free software and you are welcome to distribute copies
of it under certain conditions; type "show copying" to see
the conditions.
There is absolutely no warranty for gdb; type "show warranty"
for details.
gdb 2003-07-22-cvs, Copyright 1999 Free Software Foundation, Inc...
(gdb)
gdb reads only enough symbol data to know where to find the rest when needed; as a result, the first
prompt comes up very quickly. We now tell gdb to use a narrower display width than usual, so that
examples fit in this manual.
(gdb) set width 70
We need to see how the m4 built-in changequote works. Having looked at the source, we know the
relevant subroutine is m4_changequote, so we set a breakpoint there with the gdb break command.
8 Chapter 3. A Sample gdb Session
(gdb) break m4_changequote
Breakpoint 1 at 0x62f4: file builtin.c, line 879.
Using the run command, we start m4 running under gdb control; as long as control does not reach the
m4_changequote subroutine, the program runs as usual:
(gdb) run
Starting program: /work/Editorial/gdb/gnu/m4/m4
define(foo,0000)
foo
0000
To trigger the breakpoint, we call changequote. gdb suspends execution of m4, displaying information about the context where it stops.
changequote(QUOTE,UNQUOTE)
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 current function.
(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 it steps into
set_quotes.
(gdb) s
set_quotes (lq=0x34c78 "QUOTE", rq=0x34c88 "UNQUOTE")
at input.c:530
530 if (lquote != def_lquote)
The display that shows the subroutine where m4 is now suspended (and its arguments) is called a stack
frame display. It shows a summary of the stack. We can use the backtrace command (which can
also be spelled bt), to see where we are in the stack as a whole: the backtrace command displays a
stack frame for each active subroutine.
(gdb) bt
#0 set_quotes (lq=0x34c78 "
QUOTE", rq=0x34c88 "UNQUOTE")
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
Chapter 3. A Sample gdb Session 9
#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 first two times, we can use s; the next two
times we use n to avoid falling into the xstrdup subroutine.
(gdb) s
0x3b5c 532 if (rquote != def_rquote)
(gdb) s
0x3b80 535 lquote = (lq == nil || *lq == ’\0’) ? \
def_lquote : xstrdup(lq);
(gdb) n
536 rquote = (rq == nil || *rq == ’\0’) ? def_rquote\
: xstrdup(rq);
(gdb) n
538 len_lquote = strlen(rquote);
The last line displayed looks a little odd; we can examine the variables lquote and rquote to see
if they are in fact the new left and right quotes we specified. We use the command p (print) to see
their values.
(gdb) p lquote
$1 = 0x35d40 "QUOTE"
(gdb) p rquote
$2 = 0x35d50 "UNQUOTE"
lquote and rquote are indeed the new left and right quotes. To look at some context, we can display
ten lines of source surrounding the current line with the l (list) command.
(gdb) l
533 xfree(rquote);
534
535 lquote = (lq == nil || *lq == ’\0’) ? def_lquote\
: xstrdup (lq);
536 rquote = (rq == nil || *rq == ’\0’) ? def_rquote\
: xstrdup (rq);
537
538 len_lquote = strlen(rquote);
539 len_rquote = strlen(lquote);
540 }
541
542 void
Let us step past the two lines that set len_lquote and len_rquote, and then examine the values of
those variables.
(gdb) n
539 len_rquote = strlen(lquote);
(gdb) n
540 }
(gdb) p len_lquote
$3 = 9
10 Chapter 3. A Sample gdb Session
(gdb) p len_rquote
$4 = 7
That certainly looks wrong, assuming len_lquote and len_rquote are meant to be the lengths of
lquote and rquote respectively. We can set them to better values using the p command, since it can
print the value of any expression--and that expression can include subroutine calls and assignments.
(gdb) p len_lquote=strlen(lquote)
$5 = 7
(gdb) p len_rquote=strlen(rquote)
$6 = 9
Is that enough to fix the problem of using the new quotes with the m4 built-in defn? We can allow m4
to continue executing with the c (continue) command, and then try the example that caused trouble
initially:
(gdb) c
Continuing.
define(baz,defn(
QUOTEfooUNQUOTE))
baz
0000
Success! The new quotes now work just as well as the default ones. The problem seems to have been
just the two typos defining the wrong lengths. We allow m4 exit by giving it an EOF as input:
C-d
Program exited normally.
The message Program exited normally. is from gdb; it indicates m4 has finished executing. We
can end our gdb session with the gdb quit command.
(gdb) quit
Chapter 4.
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 C-d to exit.
4.1. Invoking gdb
Invoke gdb by running the program gdb. Once started, gdb reads commands from the terminal until
you tell it to exit.
You can also run gdb with a variety of arguments and options, to specify more of your debugging
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 program
You can also start with both an executable program and a core file specified:
gdb program core
You can, instead, specify a process ID as a second argument, if you want to debug a running process:
gdb program 1234
would attach gdb to process 1234 (unless you also have a file named 1234; gdb does check for a core
file first).
Taking advantage of the second command-line argument requires a fairly complete operating system;
when you use gdb as a remote debugger attached to a bare board, there may not be any notion of
"process", and there is often no way to get a core dump. gdb will warn you if it is unable to attach or
to read core dumps.
You can optionally have gdb pass any arguments after the executable file to the inferior using -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 (Refer to Section 6.3
Your program’s arguments) to -O2 -c foo.c.
You can run gdb without printing the front material, which describes gdb’s non-warranty, by specifying -silent:
12 Chapter 4. Getting In and Out of gdb
gdb -silent
You can further control how gdb starts up by using command-line options. gdb itself can remind you
of the options available.
Type
gdb -help
to display all available options and briefly describe their use (gdb -h is a shorter equivalent).
All options and command line arguments you give are processed in sequential order. The order makes
a difference when the -x option is used.
4.1.1. Choosing files
When gdb starts, it reads any arguments other than options as specifying an executable file and core
file (or process ID). This is the same as if the arguments were specified by the -se and -c (or -p
options respectively. (gdb reads the first argument that does not have an associated option flag as
equivalent to the -se option followed by that argument; and the second argument that does not have
an associated option flag, if any, as equivalent to the -c/-p option followed by that argument.) If the
second argument begins with a decimal digit, gdb will first attempt to attach to it as a process, and if
that fails, attempt to open it as a corefile. If you have a corefile whose name begins with a digit, you
can prevent gdb from treating it as a pid by prefixing it with ./, eg. ./12345.
If gdb has not been configured to included core file support, such as for most embedded targets, 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. gdb also recognizes
the long forms if you truncate them, so long as enough of the option is present to be unambiguous.
(If you prefer, you can flag option arguments with - rather than -, though we illustrate the more usual
convention.)
-symbols file
-s file
Read symbol table from file file.
-exec file
-e file
Use file file as the executable file to execute when appropriate, and for examining pure data in
conjunction with a core dump.
-se file
Read symbol table from file file and use it as the executable file.
-core file
-c file
Use file file as a core dump to examine.
Chapter 4. Getting In and Out of gdb 13
-c number
-pid number
-p number
Connect to process ID number, as with the attach command. If there is no such process, gdb
will attempt to open a core file named number.
-command file
-x file
Execute gdb commands from file file. Refer to Section 22.3 Command files.
-directory directory
-d directory
Add directory to the path to search for source files.
-m
-mapped
Warning: this option depends on operating system facilities that are not supported on all systems.
If memory-mapped files are available on your system through the mmap system call, you can
use this option to have gdb write the symbols from your program into a reusable file in the
current directory. If the program you are debugging is called /tmp/fred, the mapped symbol
file is /tmp/fred.syms. Future gdb debugging sessions notice the presence of this file, and
can quickly map in symbol information from it, rather than reading the symbol table from the
executable program.
The .syms file is specific to the host machine where gdb is run. It holds an exact image of the
internal gdb symbol table. It cannot be shared across multiple host platforms.
-r
-readnow
Read each symbol file’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.
You typically combine the -mapped and -readnow options in order to build a .syms file that contains
complete symbol information. (Refer to Section 17.1 Commands to specify files for information on
.syms files.) A simple gdb invocation to do nothing but build a .syms file for future use is:
gdb -batch -nx -mapped -readnow programname
4.1.2. Choosing modes
You 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 files. Normally, gdb executes the commands
in these files after all the command options and arguments have been processed. Refer to Section
22.3 Command files.
14 Chapter 4. Getting In and Out of gdb
-quiet
-silent
-q
"Quiet". Do not print the introductory and copyright messages. These messages are also suppressed in batch mode.
-batch
Run in batch mode. Exit with status 0 after processing all the command files specified with -x
(and all commands from initialization files, if not inhibited with -n). Exit with nonzero status if
an error occurs in executing the gdb commands in the command files.
Batch mode may be useful for running gdb as a filter, for example to download and run a program
on another computer; in order to make this more useful, the message
Program exited normally.
(which is ordinarily issued whenever a program running under gdb control terminates) is not
issued when running in batch mode.
-nowindows
-nw
"No windows". If gdb comes with a graphical user interface (GUI) built in, then this option tells
gdb to only use the command-line interface. If no GUI is available, this option has no effect.
-windows
-w
If gdb includes a GUI, then this option requires it to be used if possible.
-cd directory
Run gdb using directory as its working directory, instead of the current directory.
-fullname
-f
gnu Emacs sets this option when it runs gdb as a subprocess. It tells gdb to output the full file
name and line number in a standard, recognizable fashion each time a stack frame is displayed
(which includes each time your program stops). This recognizable format looks like two \032
characters, followed by the file name, line number and character position separated by colons,
and a newline. The Emacs-to-gdb interface program uses the two \032 characters as a signal to
display the source code for the frame.
-epoch
The Epoch Emacs-gdb interface sets this option when it runs gdb as a subprocess. It tells gdb
to modify its print routines so as to allow Epoch to display values of expressions in a separate
window.
-annotate level
This option sets the annotation level inside gdb. Its effect is identical to using set annotate
level (refer to Chapter 27 gdb Annotations). Annotation level controls how much information
does gdb print together with its prompt, values of expressions, source lines, and other types of
output. Level 0 is the normal, level 1 is for use when gdb is run as a subprocess of gnu Emacs,
level 2 is the maximum annotation suitable for programs that control gdb.
Chapter 4. Getting In and Out of gdb 15
-async
Use the asynchronous event loop for the command-line interface. gdb processes all events, such
as user keyboard input, via a special event loop. This allows gdb to accept and process user
commands in parallel with the debugged process being run1, so you don’t need to wait for control
to return to gdb before you type the next command. (Note: as of version 5.1, the target side of
the asynchronous operation is not yet in place, so -async does not work fully yet.)
When the standard input is connected to a terminal device, gdb uses the asynchronous event loop
by default, unless disabled by the -noasync option.
-noasync
Disable the asynchronous event loop for the command-line interface.
-args
Change interpretation of command line so that arguments following the executable file are passed
as command line arguments to the inferior. This option stops option processing.
-baud bps
-b bps
Set the line speed (baud rate or bits per second) of any serial interface used by gdb for remote
debugging.
-tty device
-t device
Run using device for your program’s standard input and output.
-tui
Activate the Terminal User Interface when starting. The Terminal User Interface manages several
text windows on the terminal, showing source, assembly, registers and gdb command outputs
(refer to Chapter 24 gdb Text User Interface). Do not use this option if you run gdb from Emacs
(refer to Chapter 25 Using gdb under gnu Emacs).
-interpreter interp
Use the interpreter interp for interface with the controlling program or device. This option is
meant to be set by programs which communicate with gdb using it as a back end (refer to Chapter
23 Command Interpreters.
-interpreter=mi (or -interpreter=mi2) causes gdb to use the current gdb/mi interface
(refer to Chapter 26 The gdb/mi Interface). The previous gdb/mi interface, included in gdb version 5.3, can be selected with -interpreter=mi1. Earlier gdb/mi interfaces are not supported.
-write
Open the executable and core files for both reading and writing. This is equivalent to the set
write on command inside gdb (refer to Section 16.6 Patching programs).
-statistics
This option causes gdb to print statistics about time and memory usage after it completes each
command and returns to the prompt.
1. gdb built with djgpp tools for MS-DOS/MS-Windows supports this mode of operation, but the event loop is
suspended when the debuggee runs.
16 Chapter 4. Getting In and Out of gdb
-version
This option causes gdb to print its version number and no-warranty blurb, and exit.
4.2. Quitting gdb
quit [expression]
q
To exit gdb, use the quit command (abbreviated q), or type an end-of-file character (usually
C-d). If you do not supply expression, gdb will terminate normally; otherwise it will terminate
using the result of expression as the error code.
An interrupt (often C-c) does not exit from gdb, but rather terminates the action of any gdb command
that is in progress and returns to gdb command level. It is safe to type the interrupt character at any
time because gdb does not allow it to take effect until a time when it is safe.
If you have been using gdb to control an attached process or device, you can release it with the detach
command (refer to Section 6.7 Debugging an already-running process).
4.3. Shell commands
If you need to execute occasional shell commands during your debugging session, there is no need to
leave or suspend gdb; you can just use the shell command.
shell command string
Invoke a standard shell to execute command string. If it exists, the environment variable SHELL
determines which shell to run. Otherwise gdb uses the default shell (/bin/sh on Unix systems,
COMMAND.COM on MS-DOS, etc.).
The utility make is often needed in development environments. You do not have to use the shell
command for this purpose in gdb:
make make-args
Execute the make program with the specified arguments. This is equivalent to shell make
make-args.
4.4. Logging output
You may want to save the output of gdb commands to a file. There are several commands to control
gdb’s logging.
set logging on
Enable logging.
set logging off
Disable logging.
Chapter 4. Getting In and Out of gdb 17
set logging file file
Change the name of the current logfile. The default logfile is gdb.txt.
set logging overwrite [on|off]
By default, gdb will append to the logfile. Set overwrite if you want set logging on to
overwrite the logfile instead.
set logging redirect [on|off]
By default, gdb output will go to both the terminal and the logfile. Set redirect if you want
output to go only to the log file.
show logging
Show the current values of the logging settings.
18 Chapter 4. Getting In and Out of gdb
Chapter 5.
gdb Commands
You can abbreviate a gdb command to the first few letters of the command name, if that abbreviation
is unambiguous; and you can repeat certain gdb commands by typing just [RET]. You can also use
the [TAB] key to get gdb to fill out the rest of a word in a command (or to show you the alternatives
available, if there is more than one possibility).
5.1. Command syntax
A gdb command is a single line of input. There is no limit on how long it can be. It starts with a
command name, which is followed by arguments whose meaning depends on the command name.
For example, the command step accepts an argument which is the number of times to step, as in
step 5. You can also use the step command with no arguments. Some commands do not allow any
arguments.
gdb command names may always be truncated if that abbreviation is unambiguous. Other possible
command abbreviations are listed in the documentation for individual commands. In some cases,
even ambiguous abbreviations are allowed; for example, s is specially defined as equivalent to step
even though there are other commands whose names start with s. You can test abbreviations by using
them as arguments to the help command.
A blank line as input to gdb (typing just [RET]) means to repeat the previous command. Certain
commands (for example, run) will not repeat this way; these are commands whose unintentional
repetition might cause trouble and which you are unlikely to want to repeat.
The list and x commands, when you repeat them with [RET], construct new arguments rather than
repeating exactly as typed. This permits easy scanning of source or memory.
gdb can also use [RET] in another way: to partition lengthy output, in a way similar to the common
utility more (refer to Section 21.4 Screen size). Since it is easy to press one [RET] too many in this
situation, gdb disables command repetition after any command that generates this sort of display.
Any text from a # to the end of the line is a comment; it does nothing. This is useful mainly in
command files (refer to Section 22.3 Command files).
The C-o binding is useful for repeating a complex sequence of commands. This command accepts
the current line, like RET, and then fetches the next line relative to the current line from the history
for editing.
5.2. Command completion
gdb can fill in the rest of a word in a command for you, if there is only one possibility; it can also
show you what the valid possibilities are for the next word in a command, at any time. This works for
gdb commands, gdb subcommands, and the names of symbols in your program.
Press the [TAB] key whenever you want gdb to fill out the rest of a word. If there is only one possibility,
gdb fills in the word, and waits for you to finish the command (or press [RET] to enter it). For example,
if you type
(gdb) info bre [TAB]
gdb fills in the rest of the word breakpoints, since that is the only info subcommand beginning
with bre:
20 Chapter 5. gdb Commands
(gdb) info breakpoints
You can either press [RET] at this point, to run the info breakpoints command, or backspace
and enter something else, if breakpoints does not look like the command you expected. (If you
were sure you wanted info breakpoints in the first place, you might as well just type [RET]
immediately after info bre, to exploit command abbreviations rather than command completion).
If there is more than one possibility for the next word when you press [TAB], gdb sounds a bell.
You can either supply more characters and try again, or just press [TAB] a second time; gdb displays
all the possible completions for that word. For example, you might want to set a breakpoint on a
subroutine whose name begins with make_, but when you type b make_[TAB] gdb just sounds
the bell. Typing [TAB] again displays all the function names in your program that begin with those
characters, for example:
(gdb) b make_ [TAB]
gdb sounds bell; press [TAB] again, to see: make_a_section_from_file make_environ
make_abs_section make_function_type
make_blockvector make_pointer_type
make_cleanup make_reference_type
make_command make_symbol_completion_list
(gdb) b make_
After displaying the available possibilities, gdb copies your partial input (b make_ in the example)
so you can finish the command.
If you just want to see the list of alternatives in the first place, you can press M-? rather than pressing
[TAB] twice. M-? means [META] ?. You can type this either by holding down a key designated as
the [META] shift on your keyboard (if there is one) while typing ?, or as [ESC] followed by ?.
Sometimes the string you need, while logically a "word", may contain parentheses or other characters
that gdb normally excludes from its notion of a word. To permit word completion to work in this
situation, you may enclose words in ’ (single quote marks) in gdb commands.
The most likely situation where you might need this is in typing the name of a C++ function. This
is because C++ allows function overloading (multiple definitions of the same function, distinguished
by argument type). For example, when you want to set a breakpoint you may need to distinguish
whether you mean the version of name that takes an int parameter, name(int), or the version that
takes a float parameter, name(float). To use the word-completion facilities in this situation, type
a single quote ’ at the beginning of the function name. This alerts gdb that it may need to consider
more information than usual when you press [TAB] or M-? to request word completion:
(gdb) b ’bubble( M-?
bubble(double,double) bubble(int,int)
(gdb) b ’bubble(
In some cases, gdb can tell that completing a name requires using quotes. When this happens, gdb
inserts the quote for you (while completing as much as it can) if you do not type the quote in the first
place:
(gdb) b bub [TAB]
gdb alters your input line to the following, and rings a bell: (gdb) b ’bubble(
Loading...