| \input texinfo @c -*-texinfo-*- |
| @c Copyright (C) 1988--2021 Free Software Foundation, Inc. |
| @c |
| @c %**start of header |
| @c makeinfo ignores cmds prev to setfilename, so its arg cannot make use |
| @c of @set vars. However, you can override filename with makeinfo -o. |
| @setfilename gdb.info |
| @c |
| @c man begin INCLUDE |
| @include gdb-cfg.texi |
| @c man end |
| @c |
| @settitle Debugging with @value{GDBN} |
| @setchapternewpage odd |
| @c %**end of header |
| |
| @iftex |
| @c @smallbook |
| @c @cropmarks |
| @end iftex |
| |
| @finalout |
| @c To avoid file-name clashes between index.html and Index.html, when |
| @c the manual is produced on a Posix host and then moved to a |
| @c case-insensitive filesystem (e.g., MS-Windows), we separate the |
| @c indices into two: Concept Index and all the rest. |
| @syncodeindex ky fn |
| @syncodeindex tp fn |
| |
| @c readline appendices use @vindex, @findex and @ftable, |
| @c annotate.texi and gdbmi use @findex. |
| @syncodeindex vr fn |
| |
| @c !!set GDB manual's edition---not the same as GDB version! |
| @c This is updated by GNU Press. |
| @set EDITION Tenth |
| |
| @c !!set GDB edit command default editor |
| @set EDITOR /bin/ex |
| |
| @c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER. |
| |
| @c This is a dir.info fragment to support semi-automated addition of |
| @c manuals to an info tree. |
| @dircategory Software development |
| @direntry |
| * Gdb: (gdb). The GNU debugger. |
| * gdbserver: (gdb) Server. The GNU debugging server. |
| @end direntry |
| |
| @copying |
| @c man begin COPYRIGHT |
| Copyright @copyright{} 1988-2021 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software'' and ``Free Software Needs |
| Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' |
| and with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: ``You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom.'' |
| @c man end |
| @end copying |
| |
| @ifnottex |
| This file documents the @sc{gnu} debugger @value{GDBN}. |
| |
| This is the @value{EDITION} Edition, of @cite{Debugging with |
| @value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN} |
| @ifset VERSION_PACKAGE |
| @value{VERSION_PACKAGE} |
| @end ifset |
| Version @value{GDBVN}. |
| |
| @insertcopying |
| @end ifnottex |
| |
| @titlepage |
| @title Debugging with @value{GDBN} |
| @subtitle The @sc{gnu} Source-Level Debugger |
| @sp 1 |
| @subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN} |
| @ifset VERSION_PACKAGE |
| @sp 1 |
| @subtitle @value{VERSION_PACKAGE} |
| @end ifset |
| @author Richard Stallman, Roland Pesch, Stan Shebs, et al. |
| @page |
| @tex |
| {\parskip=0pt |
| \hfill (Send bugs and comments on @value{GDBN} to @value{BUGURL}.)\par |
| \hfill {\it Debugging with @value{GDBN}}\par |
| \hfill \TeX{}info \texinfoversion\par |
| } |
| @end tex |
| |
| @vskip 0pt plus 1filll |
| Published by the Free Software Foundation @* |
| 51 Franklin Street, Fifth Floor, |
| Boston, MA 02110-1301, USA@* |
| ISBN 978-0-9831592-3-0 @* |
| |
| @insertcopying |
| @end titlepage |
| @page |
| |
| @ifnottex |
| @node Top, Summary |
| |
| @top Debugging with @value{GDBN} |
| |
| This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. |
| |
| This is the @value{EDITION} Edition, for @value{GDBN} |
| @ifset VERSION_PACKAGE |
| @value{VERSION_PACKAGE} |
| @end ifset |
| Version @value{GDBVN}. |
| |
| Copyright (C) 1988-2021 Free Software Foundation, Inc. |
| |
| This edition of the GDB manual is dedicated to the memory of Fred |
| Fish. Fred was a long-standing contributor to GDB and to Free |
| software in general. We will miss him. |
| |
| @menu |
| * Summary:: Summary of @value{GDBN} |
| * Sample Session:: A sample @value{GDBN} session |
| |
| * Invocation:: Getting in and out of @value{GDBN} |
| * Commands:: @value{GDBN} commands |
| * Running:: Running programs under @value{GDBN} |
| * Stopping:: Stopping and continuing |
| * Reverse Execution:: Running programs backward |
| * Process Record and Replay:: Recording inferior's execution and replaying it |
| * Stack:: Examining the stack |
| * Source:: Examining source files |
| * Data:: Examining data |
| * Optimized Code:: Debugging optimized code |
| * Macros:: Preprocessor Macros |
| * Tracepoints:: Debugging remote targets non-intrusively |
| * Overlays:: Debugging programs that use overlays |
| |
| * Languages:: Using @value{GDBN} with different languages |
| |
| * Symbols:: Examining the symbol table |
| * Altering:: Altering execution |
| * GDB Files:: @value{GDBN} files |
| * Targets:: Specifying a debugging target |
| * Remote Debugging:: Debugging remote programs |
| * Configurations:: Configuration-specific information |
| * Controlling GDB:: Controlling @value{GDBN} |
| * Extending GDB:: Extending @value{GDBN} |
| * Interpreters:: Command Interpreters |
| * TUI:: @value{GDBN} Text User Interface |
| * Emacs:: Using @value{GDBN} under @sc{gnu} Emacs |
| * GDB/MI:: @value{GDBN}'s Machine Interface. |
| * Annotations:: @value{GDBN}'s annotation interface. |
| * JIT Interface:: Using the JIT debugging interface. |
| * In-Process Agent:: In-Process Agent |
| |
| * GDB Bugs:: Reporting bugs in @value{GDBN} |
| |
| @ifset SYSTEM_READLINE |
| * Command Line Editing: (rluserman). Command Line Editing |
| * Using History Interactively: (history). Using History Interactively |
| @end ifset |
| @ifclear SYSTEM_READLINE |
| * Command Line Editing:: Command Line Editing |
| * Using History Interactively:: Using History Interactively |
| @end ifclear |
| * In Memoriam:: In Memoriam |
| * Formatting Documentation:: How to format and print @value{GDBN} documentation |
| * Installing GDB:: Installing GDB |
| * Maintenance Commands:: Maintenance Commands |
| * Remote Protocol:: GDB Remote Serial Protocol |
| * Agent Expressions:: The GDB Agent Expression Mechanism |
| * Target Descriptions:: How targets can describe themselves to |
| @value{GDBN} |
| * Operating System Information:: Getting additional information from |
| the operating system |
| * Trace File Format:: GDB trace file format |
| * Index Section Format:: .gdb_index section format |
| * Man Pages:: Manual pages |
| * Copying:: GNU General Public License says |
| how you can copy and share GDB |
| * GNU Free Documentation License:: The license for this documentation |
| * Concept Index:: Index of @value{GDBN} concepts |
| * Command and Variable Index:: Index of @value{GDBN} commands, variables, |
| functions, and Python data types |
| @end menu |
| |
| @end ifnottex |
| |
| @contents |
| |
| @node Summary |
| @unnumbered Summary of @value{GDBN} |
| |
| The purpose of a debugger such as @value{GDBN} 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. |
| |
| @value{GDBN} can do four main kinds of things (plus other things in support of |
| these) to help you catch bugs in the act: |
| |
| @itemize @bullet |
| @item |
| Start your program, specifying anything that might affect its behavior. |
| |
| @item |
| Make your program stop on specified conditions. |
| |
| @item |
| Examine what has happened, when your program has stopped. |
| |
| @item |
| Change things in your program, so you can experiment with correcting the |
| effects of one bug and go on to learn about another. |
| @end itemize |
| |
| You can use @value{GDBN} to debug programs written in C and C@t{++}. |
| For more information, see @ref{Supported Languages,,Supported Languages}. |
| For more information, see @ref{C,,C and C++}. |
| |
| Support for D is partial. For information on D, see |
| @ref{D,,D}. |
| |
| @cindex Modula-2 |
| Support for Modula-2 is partial. For information on Modula-2, see |
| @ref{Modula-2,,Modula-2}. |
| |
| Support for OpenCL C is partial. For information on OpenCL C, see |
| @ref{OpenCL C,,OpenCL C}. |
| |
| @cindex Pascal |
| Debugging Pascal programs which use sets, subranges, file variables, or |
| nested functions does not currently work. @value{GDBN} does not support |
| entering expressions, printing values, or similar features using Pascal |
| syntax. |
| |
| @cindex Fortran |
| @value{GDBN} can be used to debug programs written in Fortran, although |
| it may be necessary to refer to some variables with a trailing |
| underscore. |
| |
| @value{GDBN} can be used to debug programs written in Objective-C, |
| using either the Apple/NeXT or the GNU Objective-C runtime. |
| |
| @menu |
| * Free Software:: Freely redistributable software |
| * Free Documentation:: Free Software Needs Free Documentation |
| * Contributors:: Contributors to GDB |
| @end menu |
| |
| @node Free Software |
| @unnumberedsec Free Software |
| |
| @value{GDBN} is @dfn{free software}, protected by the @sc{gnu} |
| General Public License |
| (GPL). The GPL gives you the freedom 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. |
| |
| @node Free Documentation |
| @unnumberedsec 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. |
| |
| 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 non-free 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 @emph{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 @email{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 |
| @url{http://www.fsf.org/doc/other-free-books.html}. |
| |
| @node Contributors |
| @unnumberedsec Contributors to @value{GDBN} |
| |
| Richard Stallman was the original author of @value{GDBN}, and of many |
| other @sc{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 @file{ChangeLog} in the @value{GDBN} distribution approximates a |
| blow-by-blow account. |
| |
| Changes much prior to version 2.0 are lost in the mists of time. |
| |
| @quotation |
| @emph{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! |
| @end quotation |
| |
| So that they may not regard their many labors as thankless, we |
| particularly thank those who shepherded @value{GDBN} 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 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 @sc{gnu} C@t{++} support |
| in @value{GDBN}, with significant additional contributions from Per |
| Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} |
| demangler. Early work on C@t{++} was by Peter TerMaat (who also did |
| much general update work leading to release 3.0). |
| |
| @value{GDBN} 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 @sc{gnu}/Linux support. |
| |
| Rich Schaefer and Peter Schauer helped with support of SunOS shared |
| libraries. |
| |
| Jay Fenlason and Roland McGrath ensured that @value{GDBN} 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@t{++} 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 |
| processors. |
| |
| 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 fixes and cleanups throughout @value{GDBN}. |
| |
| 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@t{++} |
| compiler, and the Text User Interface (nee 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 @value{GDBN} to MS-DOS, for the DJGPP project. |
| Robert Hoehne made significant contributions to the DJGPP port. |
| |
| Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its |
| development since 1991. Cygnus engineers who have worked on @value{GDBN} |
| 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. |
| |
| Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for |
| Cygnus Solutions, implemented the original @sc{gdb/mi} interface. |
| |
| Jim Blandy added support for preprocessor macros, while working for Red |
| Hat. |
| |
| Andrew Cagney designed @value{GDBN}'s architecture vector. Many |
| people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick |
| Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei |
| Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason |
| Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped |
| with the migration of old architectures to this new framework. |
| |
| Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s |
| unwinder framework, this consisting of a fresh new design featuring |
| frame IDs, independent frame sniffers, and the sentinel frame. Mark |
| Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the |
| libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and |
| trad unwinders. The architecture-specific changes, each involving a |
| complete rewrite of the architecture's frame code, were carried out by |
| Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane |
| Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel |
| Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei |
| Sakamoto, Yoshinori Sato, 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 @value{GDBN} in the past include |
| Steve Tjiang, John Newlin, and Scott Foehner. |
| |
| Michael Eager and staff of Xilinx, Inc., contributed support for the |
| Xilinx MicroBlaze architecture. |
| |
| Initial support for the FreeBSD/mips target and native configuration |
| was developed by SRI International and the University of Cambridge |
| Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 |
| ("CTSRD"), as part of the DARPA CRASH research programme. |
| |
| Initial support for the FreeBSD/riscv target and native configuration |
| was developed by SRI International and the University of Cambridge |
| Computer Laboratory (Department of Computer Science and Technology) |
| under DARPA contract HR0011-18-C-0016 ("ECATS"), as part of the DARPA |
| SSITH research programme. |
| |
| The original port to the OpenRISC 1000 is believed to be due to |
| Alessandro Forin and Per Bothner. More recent ports have been the work |
| of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and |
| Stafford Horne. |
| |
| Weimin Pan, David Faust and Jose E. Marchesi contributed support for |
| the Linux kernel BPF virtual architecture. This work was sponsored by |
| Oracle. |
| |
| @node Sample Session |
| @chapter A Sample @value{GDBN} Session |
| |
| You can use this manual at your leisure to read all about @value{GDBN}. |
| However, a handful of commands are enough to get started using the |
| debugger. This chapter illustrates those commands. |
| |
| @iftex |
| In this sample session, we emphasize user input like this: @b{input}, |
| to make it easier to pick out from the surrounding output. |
| @end iftex |
| |
| @c FIXME: this example may not be appropriate for some configs, where |
| @c FIXME...primary interest is in remote use. |
| |
| One of the preliminary versions of @sc{gnu} @code{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 @code{m4} |
| session, we define a macro @code{foo} which expands to @code{0000}; we |
| then use the @code{m4} built-in @code{defn} to define @code{bar} as the |
| same thing. However, when we change the open quote string to |
| @code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same |
| procedure fails to define a new synonym @code{baz}: |
| |
| @smallexample |
| $ @b{cd gnu/m4} |
| $ @b{./m4} |
| @b{define(foo,0000)} |
| |
| @b{foo} |
| 0000 |
| @b{define(bar,defn(`foo'))} |
| |
| @b{bar} |
| 0000 |
| @b{changequote(<QUOTE>,<UNQUOTE>)} |
| |
| @b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} |
| @b{baz} |
| @b{Ctrl-d} |
| m4: End of input: 0: fatal error: EOF in string |
| @end smallexample |
| |
| @noindent |
| Let us use @value{GDBN} to try to see what is going on. |
| |
| @smallexample |
| $ @b{@value{GDBP} m4} |
| @c FIXME: this falsifies the exact text played out, to permit smallbook |
| @c FIXME... format to come out better. |
| @value{GDBN} 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 @value{GDBN}; type "show warranty" |
| for details. |
| |
| @value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... |
| (@value{GDBP}) |
| @end smallexample |
| |
| @noindent |
| @value{GDBN} 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 @value{GDBN} to use a narrower display width than usual, so |
| that examples fit in this manual. |
| |
| @smallexample |
| (@value{GDBP}) @b{set width 70} |
| @end smallexample |
| |
| @noindent |
| We need to see how the @code{m4} built-in @code{changequote} works. |
| Having looked at the source, we know the relevant subroutine is |
| @code{m4_changequote}, so we set a breakpoint there with the @value{GDBN} |
| @code{break} command. |
| |
| @smallexample |
| (@value{GDBP}) @b{break m4_changequote} |
| Breakpoint 1 at 0x62f4: file builtin.c, line 879. |
| @end smallexample |
| |
| @noindent |
| Using the @code{run} command, we start @code{m4} running under @value{GDBN} |
| control; as long as control does not reach the @code{m4_changequote} |
| subroutine, the program runs as usual: |
| |
| @smallexample |
| (@value{GDBP}) @b{run} |
| Starting program: /work/Editorial/gdb/gnu/m4/m4 |
| @b{define(foo,0000)} |
| |
| @b{foo} |
| 0000 |
| @end smallexample |
| |
| @noindent |
| To trigger the breakpoint, we call @code{changequote}. @value{GDBN} |
| suspends execution of @code{m4}, displaying information about the |
| context where it stops. |
| |
| @smallexample |
| @b{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)) |
| @end smallexample |
| |
| @noindent |
| Now we use the command @code{n} (@code{next}) to advance execution to |
| the next line of the current function. |
| |
| @smallexample |
| (@value{GDBP}) @b{n} |
| 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ |
| : nil, |
| @end smallexample |
| |
| @noindent |
| @code{set_quotes} looks like a promising subroutine. We can go into it |
| by using the command @code{s} (@code{step}) instead of @code{next}. |
| @code{step} goes to the next line to be executed in @emph{any} |
| subroutine, so it steps into @code{set_quotes}. |
| |
| @smallexample |
| (@value{GDBP}) @b{s} |
| set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") |
| at input.c:530 |
| 530 if (lquote != def_lquote) |
| @end smallexample |
| |
| @noindent |
| The display that shows the subroutine where @code{m4} is now |
| suspended (and its arguments) is called a stack frame display. It |
| shows a summary of the stack. We can use the @code{backtrace} |
| command (which can also be spelled @code{bt}), to see where we are |
| in the stack as a whole: the @code{backtrace} command displays a |
| stack frame for each active subroutine. |
| |
| @smallexample |
| (@value{GDBP}) @b{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 |
| #4 0x79dc in expand_input () at macro.c:40 |
| #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 |
| @end smallexample |
| |
| @noindent |
| We step through a few more lines to see what happens. The first two |
| times, we can use @samp{s}; the next two times we use @code{n} to avoid |
| falling into the @code{xstrdup} subroutine. |
| |
| @smallexample |
| (@value{GDBP}) @b{s} |
| 0x3b5c 532 if (rquote != def_rquote) |
| (@value{GDBP}) @b{s} |
| 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ |
| def_lquote : xstrdup(lq); |
| (@value{GDBP}) @b{n} |
| 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ |
| : xstrdup(rq); |
| (@value{GDBP}) @b{n} |
| 538 len_lquote = strlen(rquote); |
| @end smallexample |
| |
| @noindent |
| The last line displayed looks a little odd; we can examine the variables |
| @code{lquote} and @code{rquote} to see if they are in fact the new left |
| and right quotes we specified. We use the command @code{p} |
| (@code{print}) to see their values. |
| |
| @smallexample |
| (@value{GDBP}) @b{p lquote} |
| $1 = 0x35d40 "<QUOTE>" |
| (@value{GDBP}) @b{p rquote} |
| $2 = 0x35d50 "<UNQUOTE>" |
| @end smallexample |
| |
| @noindent |
| @code{lquote} and @code{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 @code{l} (@code{list}) command. |
| |
| @smallexample |
| (@value{GDBP}) @b{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 |
| @end smallexample |
| |
| @noindent |
| Let us step past the two lines that set @code{len_lquote} and |
| @code{len_rquote}, and then examine the values of those variables. |
| |
| @smallexample |
| (@value{GDBP}) @b{n} |
| 539 len_rquote = strlen(lquote); |
| (@value{GDBP}) @b{n} |
| 540 @} |
| (@value{GDBP}) @b{p len_lquote} |
| $3 = 9 |
| (@value{GDBP}) @b{p len_rquote} |
| $4 = 7 |
| @end smallexample |
| |
| @noindent |
| That certainly looks wrong, assuming @code{len_lquote} and |
| @code{len_rquote} are meant to be the lengths of @code{lquote} and |
| @code{rquote} respectively. We can set them to better values using |
| the @code{p} command, since it can print the value of |
| any expression---and that expression can include subroutine calls and |
| assignments. |
| |
| @smallexample |
| (@value{GDBP}) @b{p len_lquote=strlen(lquote)} |
| $5 = 7 |
| (@value{GDBP}) @b{p len_rquote=strlen(rquote)} |
| $6 = 9 |
| @end smallexample |
| |
| @noindent |
| Is that enough to fix the problem of using the new quotes with the |
| @code{m4} built-in @code{defn}? We can allow @code{m4} to continue |
| executing with the @code{c} (@code{continue}) command, and then try the |
| example that caused trouble initially: |
| |
| @smallexample |
| (@value{GDBP}) @b{c} |
| Continuing. |
| |
| @b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} |
| |
| baz |
| 0000 |
| @end smallexample |
| |
| @noindent |
| 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 @code{m4} exit by giving it an EOF as input: |
| |
| @smallexample |
| @b{Ctrl-d} |
| Program exited normally. |
| @end smallexample |
| |
| @noindent |
| The message @samp{Program exited normally.} is from @value{GDBN}; it |
| indicates @code{m4} has finished executing. We can end our @value{GDBN} |
| session with the @value{GDBN} @code{quit} command. |
| |
| @smallexample |
| (@value{GDBP}) @b{quit} |
| @end smallexample |
| |
| @node Invocation |
| @chapter Getting In and Out of @value{GDBN} |
| |
| This chapter discusses how to start @value{GDBN}, and how to get out of it. |
| The essentials are: |
| @itemize @bullet |
| @item |
| type @samp{@value{GDBP}} to start @value{GDBN}. |
| @item |
| type @kbd{quit} or @kbd{Ctrl-d} to exit. |
| @end itemize |
| |
| @menu |
| * Invoking GDB:: How to start @value{GDBN} |
| * Quitting GDB:: How to quit @value{GDBN} |
| * Shell Commands:: How to use shell commands inside @value{GDBN} |
| * Logging Output:: How to log @value{GDBN}'s output to a file |
| @end menu |
| |
| @node Invoking GDB |
| @section Invoking @value{GDBN} |
| |
| Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, |
| @value{GDBN} reads commands from the terminal until you tell it to exit. |
| |
| You can also run @code{@value{GDBP}} 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 @value{GDBN} is with one argument, |
| specifying an executable program: |
| |
| @smallexample |
| @value{GDBP} @var{program} |
| @end smallexample |
| |
| @noindent |
| You can also start with both an executable program and a core file |
| specified: |
| |
| @smallexample |
| @value{GDBP} @var{program} @var{core} |
| @end smallexample |
| |
| You can, instead, specify a process ID as a second argument or use option |
| @code{-p}, if you want to debug a running process: |
| |
| @smallexample |
| @value{GDBP} @var{program} 1234 |
| @value{GDBP} -p 1234 |
| @end smallexample |
| |
| @noindent |
| would attach @value{GDBN} to process @code{1234}. With option @option{-p} you |
| can omit the @var{program} filename. |
| |
| Taking advantage of the second command-line argument requires a fairly |
| complete operating system; when you use @value{GDBN} 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. @value{GDBN} |
| will warn you if it is unable to attach or to read core dumps. |
| |
| You can optionally have @code{@value{GDBP}} pass any arguments after the |
| executable file to the inferior using @code{--args}. This option stops |
| option processing. |
| @smallexample |
| @value{GDBP} --args gcc -O2 -c foo.c |
| @end smallexample |
| This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set |
| @code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. |
| |
| You can run @code{@value{GDBP}} without printing the front material, which describes |
| @value{GDBN}'s non-warranty, by specifying @code{--silent} |
| (or @code{-q}/@code{--quiet}): |
| |
| @smallexample |
| @value{GDBP} --silent |
| @end smallexample |
| |
| @noindent |
| You can further control how @value{GDBN} starts up by using command-line |
| options. @value{GDBN} itself can remind you of the options available. |
| |
| @noindent |
| Type |
| |
| @smallexample |
| @value{GDBP} -help |
| @end smallexample |
| |
| @noindent |
| to display all available options and briefly describe their use |
| (@samp{@value{GDBP} -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 |
| @samp{-x} option is used. |
| |
| |
| @menu |
| * File Options:: Choosing files |
| * Mode Options:: Choosing modes |
| * Startup:: What @value{GDBN} does during startup |
| * Initialization Files:: Initialization Files |
| @end menu |
| |
| @node File Options |
| @subsection Choosing Files |
| |
| When @value{GDBN} 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 @samp{-se} and |
| @samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the |
| first argument that does not have an associated option flag as |
| equivalent to the @samp{-se} option followed by that argument; and the |
| second argument that does not have an associated option flag, if any, as |
| equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) |
| If the second argument begins with a decimal digit, @value{GDBN} 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 @value{GDBN} from treating it as a pid by |
| prefixing it with @file{./}, e.g.@: @file{./12345}. |
| |
| If @value{GDBN} 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. @value{GDBN} 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 @samp{--} rather |
| than @samp{-}, though we illustrate the more usual convention.) |
| |
| @c NOTE: the @cindex entries here use double dashes ON PURPOSE. This |
| @c way, both those who look for -foo and --foo in the index, will find |
| @c it. |
| |
| @table @code |
| @item -symbols @var{file} |
| @itemx -s @var{file} |
| @cindex @code{--symbols} |
| @cindex @code{-s} |
| Read symbol table from file @var{file}. |
| |
| @item -exec @var{file} |
| @itemx -e @var{file} |
| @cindex @code{--exec} |
| @cindex @code{-e} |
| Use file @var{file} as the executable file to execute when appropriate, |
| and for examining pure data in conjunction with a core dump. |
| |
| @item -se @var{file} |
| @cindex @code{--se} |
| Read symbol table from file @var{file} and use it as the executable |
| file. |
| |
| @item -core @var{file} |
| @itemx -c @var{file} |
| @cindex @code{--core} |
| @cindex @code{-c} |
| Use file @var{file} as a core dump to examine. |
| |
| @item -pid @var{number} |
| @itemx -p @var{number} |
| @cindex @code{--pid} |
| @cindex @code{-p} |
| Connect to process ID @var{number}, as with the @code{attach} command. |
| |
| @item -command @var{file} |
| @itemx -x @var{file} |
| @cindex @code{--command} |
| @cindex @code{-x} |
| Execute commands from file @var{file}. The contents of this file is |
| evaluated exactly as the @code{source} command would. |
| @xref{Command Files,, Command files}. |
| |
| @item -eval-command @var{command} |
| @itemx -ex @var{command} |
| @cindex @code{--eval-command} |
| @cindex @code{-ex} |
| Execute a single @value{GDBN} command. |
| |
| This option may be used multiple times to call multiple commands. It may |
| also be interleaved with @samp{-command} as required. |
| |
| @smallexample |
| @value{GDBP} -ex 'target sim' -ex 'load' \ |
| -x setbreakpoints -ex 'run' a.out |
| @end smallexample |
| |
| @item -init-command @var{file} |
| @itemx -ix @var{file} |
| @cindex @code{--init-command} |
| @cindex @code{-ix} |
| Execute commands from file @var{file} before loading the inferior (but |
| after loading gdbinit files). |
| @xref{Startup}. |
| |
| @item -init-eval-command @var{command} |
| @itemx -iex @var{command} |
| @cindex @code{--init-eval-command} |
| @cindex @code{-iex} |
| Execute a single @value{GDBN} command before loading the inferior (but |
| after loading gdbinit files). |
| @xref{Startup}. |
| |
| @item -early-init-command @var{file} |
| @itemx -eix @var{file} |
| @cindex @code{--early-init-command} |
| @cindex @code{-eix} |
| Execute commands from @var{file} very early in the initialization |
| process, before any output is produced. @xref{Startup}. |
| |
| @item -early-init-eval-command @var{command} |
| @itemx -eiex @var{command} |
| @cindex @code{--early-init-eval-command} |
| @cindex @code{-eiex} |
| Execute a single @value{GDBN} command very early in the initialization |
| process, before any output is produced. |
| |
| @item -directory @var{directory} |
| @itemx -d @var{directory} |
| @cindex @code{--directory} |
| @cindex @code{-d} |
| Add @var{directory} to the path to search for source and script files. |
| |
| @item -r |
| @itemx -readnow |
| @cindex @code{--readnow} |
| @cindex @code{-r} |
| 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. |
| |
| @item --readnever |
| @anchor{--readnever} |
| @cindex @code{--readnever}, command-line option |
| Do not read each symbol file's symbolic debug information. This makes |
| startup faster but at the expense of not being able to perform |
| symbolic debugging. DWARF unwind information is also not read, |
| meaning backtraces may become incomplete or inaccurate. One use of |
| this is when a user simply wants to do the following sequence: attach, |
| dump core, detach. Loading the debugging information in this case is |
| an unnecessary cause of delay. |
| @end table |
| |
| @node Mode Options |
| @subsection Choosing Modes |
| |
| You can run @value{GDBN} in various alternative modes---for example, in |
| batch mode or quiet mode. |
| |
| @table @code |
| @anchor{-nx} |
| @item -nx |
| @itemx -n |
| @cindex @code{--nx} |
| @cindex @code{-n} |
| Do not execute commands found in any initialization files |
| (@pxref{Initialization Files}). |
| |
| @anchor{-nh} |
| @item -nh |
| @cindex @code{--nh} |
| Do not execute commands found in any home directory initialization |
| file (@pxref{Initialization Files,,Home directory initialization |
| file}). The system wide and current directory initialization files |
| are still loaded. |
| |
| @item -quiet |
| @itemx -silent |
| @itemx -q |
| @cindex @code{--quiet} |
| @cindex @code{--silent} |
| @cindex @code{-q} |
| ``Quiet''. Do not print the introductory and copyright messages. These |
| messages are also suppressed in batch mode. |
| |
| @kindex set startup-quietly |
| @kindex show startup-quietly |
| This can also be enabled using @code{set startup-quietly on}. The |
| default is @code{off}. Use @code{show startup-quietly} to see the |
| current setting. Place @code{set startup-quietly on} into your early |
| initialization file (@pxref{Initialization Files,,Initialization |
| Files}) to have future @value{GDBN} sessions startup quietly. |
| |
| @item -batch |
| @cindex @code{--batch} |
| Run in batch mode. Exit with status @code{0} after processing all the |
| command files specified with @samp{-x} (and all commands from |
| initialization files, if not inhibited with @samp{-n}). Exit with |
| nonzero status if an error occurs in executing the @value{GDBN} commands |
| in the command files. Batch mode also disables pagination, sets unlimited |
| terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm |
| off} were in effect (@pxref{Messages/Warnings}). |
| |
| Batch mode may be useful for running @value{GDBN} as a filter, for |
| example to download and run a program on another computer; in order to |
| make this more useful, the message |
| |
| @smallexample |
| Program exited normally. |
| @end smallexample |
| |
| @noindent |
| (which is ordinarily issued whenever a program running under |
| @value{GDBN} control terminates) is not issued when running in batch |
| mode. |
| |
| @item -batch-silent |
| @cindex @code{--batch-silent} |
| Run in batch mode exactly like @samp{-batch}, but totally silently. All |
| @value{GDBN} output to @code{stdout} is prevented (@code{stderr} is |
| unaffected). This is much quieter than @samp{-silent} and would be useless |
| for an interactive session. |
| |
| This is particularly useful when using targets that give @samp{Loading section} |
| messages, for example. |
| |
| Note that targets that give their output via @value{GDBN}, as opposed to |
| writing directly to @code{stdout}, will also be made silent. |
| |
| @item -return-child-result |
| @cindex @code{--return-child-result} |
| The return code from @value{GDBN} will be the return code from the child |
| process (the process being debugged), with the following exceptions: |
| |
| @itemize @bullet |
| @item |
| @value{GDBN} exits abnormally. E.g., due to an incorrect argument or an |
| internal error. In this case the exit code is the same as it would have been |
| without @samp{-return-child-result}. |
| @item |
| The user quits with an explicit value. E.g., @samp{quit 1}. |
| @item |
| The child process never runs, or is not allowed to terminate, in which case |
| the exit code will be -1. |
| @end itemize |
| |
| This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent}, |
| when @value{GDBN} is being used as a remote program loader or simulator |
| interface. |
| |
| @item -nowindows |
| @itemx -nw |
| @cindex @code{--nowindows} |
| @cindex @code{-nw} |
| ``No windows''. If @value{GDBN} comes with a graphical user interface |
| (GUI) built in, then this option tells @value{GDBN} to only use the command-line |
| interface. If no GUI is available, this option has no effect. |
| |
| @item -windows |
| @itemx -w |
| @cindex @code{--windows} |
| @cindex @code{-w} |
| If @value{GDBN} includes a GUI, then this option requires it to be |
| used if possible. |
| |
| @item -cd @var{directory} |
| @cindex @code{--cd} |
| Run @value{GDBN} using @var{directory} as its working directory, |
| instead of the current directory. |
| |
| @item -data-directory @var{directory} |
| @itemx -D @var{directory} |
| @cindex @code{--data-directory} |
| @cindex @code{-D} |
| Run @value{GDBN} using @var{directory} as its data directory. |
| The data directory is where @value{GDBN} searches for its |
| auxiliary files. @xref{Data Files}. |
| |
| @item -fullname |
| @itemx -f |
| @cindex @code{--fullname} |
| @cindex @code{-f} |
| @sc{gnu} Emacs sets this option when it runs @value{GDBN} as a |
| subprocess. It tells @value{GDBN} 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 @samp{\032} characters, followed by |
| the file name, line number and character position separated by colons, |
| and a newline. The Emacs-to-@value{GDBN} interface program uses the two |
| @samp{\032} characters as a signal to display the source code for the |
| frame. |
| |
| @item -annotate @var{level} |
| @cindex @code{--annotate} |
| This option sets the @dfn{annotation level} inside @value{GDBN}. Its |
| effect is identical to using @samp{set annotate @var{level}} |
| (@pxref{Annotations}). The annotation @var{level} controls how much |
| information @value{GDBN} prints 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 @value{GDBN} is run as a subprocess of |
| @sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs |
| that control @value{GDBN}, and level 2 has been deprecated. |
| |
| The annotation mechanism has largely been superseded by @sc{gdb/mi} |
| (@pxref{GDB/MI}). |
| |
| @item --args |
| @cindex @code{--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. |
| |
| @item -baud @var{bps} |
| @itemx -b @var{bps} |
| @cindex @code{--baud} |
| @cindex @code{-b} |
| Set the line speed (baud rate or bits per second) of any serial |
| interface used by @value{GDBN} for remote debugging. |
| |
| @item -l @var{timeout} |
| @cindex @code{-l} |
| Set the timeout (in seconds) of any communication used by @value{GDBN} |
| for remote debugging. |
| |
| @item -tty @var{device} |
| @itemx -t @var{device} |
| @cindex @code{--tty} |
| @cindex @code{-t} |
| Run using @var{device} for your program's standard input and output. |
| @c FIXME: kingdon thinks there is more to -tty. Investigate. |
| |
| @c resolve the situation of these eventually |
| @item -tui |
| @cindex @code{--tui} |
| Activate the @dfn{Text User Interface} when starting. The Text User |
| Interface manages several text windows on the terminal, showing |
| source, assembly, registers and @value{GDBN} command outputs |
| (@pxref{TUI, ,@value{GDBN} Text User Interface}). Do not use this |
| option if you run @value{GDBN} from Emacs (@pxref{Emacs, , |
| Using @value{GDBN} under @sc{gnu} Emacs}). |
| |
| @item -interpreter @var{interp} |
| @cindex @code{--interpreter} |
| Use the interpreter @var{interp} for interface with the controlling |
| program or device. This option is meant to be set by programs which |
| communicate with @value{GDBN} using it as a back end. |
| @xref{Interpreters, , Command Interpreters}. |
| |
| @samp{--interpreter=mi} (or @samp{--interpreter=mi3}) causes |
| @value{GDBN} to use the @dfn{@sc{gdb/mi} interface} version 3 (@pxref{GDB/MI, , |
| The @sc{gdb/mi} Interface}) included since @value{GDBN} version 9.1. @sc{gdb/mi} |
| version 2 (@code{mi2}), included in @value{GDBN} 6.0 and version 1 (@code{mi1}), |
| included in @value{GDBN} 5.3, are also available. Earlier @sc{gdb/mi} |
| interfaces are no longer supported. |
| |
| @item -write |
| @cindex @code{--write} |
| Open the executable and core files for both reading and writing. This |
| is equivalent to the @samp{set write on} command inside @value{GDBN} |
| (@pxref{Patching}). |
| |
| @item -statistics |
| @cindex @code{--statistics} |
| This option causes @value{GDBN} to print statistics about time and |
| memory usage after it completes each command and returns to the prompt. |
| |
| @item -version |
| @cindex @code{--version} |
| This option causes @value{GDBN} to print its version number and |
| no-warranty blurb, and exit. |
| |
| @item -configuration |
| @cindex @code{--configuration} |
| This option causes @value{GDBN} to print details about its build-time |
| configuration parameters, and then exit. These details can be |
| important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}). |
| |
| @end table |
| |
| @node Startup |
| @subsection What @value{GDBN} Does During Startup |
| @cindex @value{GDBN} startup |
| |
| Here's the description of what @value{GDBN} does during session startup: |
| |
| @enumerate |
| |
| @item |
| Performs minimal setup required to initialize basic internal state. |
| |
| @item |
| @cindex early initialization file |
| Reads commands from the early initialization file (if any) in your |
| home directory. Only a restricted set of commands can be placed into |
| an early initialization file, see @ref{Initialization Files}, for |
| details. |
| |
| @item |
| Executes commands and command files specified by the @samp{-eiex} and |
| @samp{-eix} command line options in their specified order. Only a |
| restricted set of commands can be used with @samp{-eiex} and |
| @samp{eix}, see @ref{Initialization Files}, for details. |
| |
| @item |
| Sets up the command interpreter as specified by the command line |
| (@pxref{Mode Options, interpreter}). |
| |
| @item |
| @cindex init file |
| Reads the system wide initialization file and the files from the |
| system wide initialization directory, @pxref{System Wide Init Files}. |
| |
| @item |
| Reads the initialization file (if any) in your home directory and |
| executes all the commands in that file, @pxref{Home Directory Init |
| File}. |
| |
| @anchor{Option -init-eval-command} |
| @item |
| Executes commands and command files specified by the @samp{-iex} and |
| @samp{-ix} options in their specified order. Usually you should use the |
| @samp{-ex} and @samp{-x} options instead, but this way you can apply |
| settings before @value{GDBN} init files get executed and before inferior |
| gets loaded. |
| |
| @item |
| Processes command line options and operands. |
| |
| @item |
| Reads and executes the commands from the initialization file (if any) |
| in the current working directory as long as @samp{set auto-load |
| local-gdbinit} is set to @samp{on} (@pxref{Init File in the Current |
| Directory}). This is only done if the current directory is different |
| from your home directory. Thus, you can have more than one init file, |
| one generic in your home directory, and another, specific to the |
| program you are debugging, in the directory where you invoke |
| @value{GDBN}. @xref{Init File in the Current Directory during |
| Startup}. |
| |
| @item |
| If the command line specified a program to debug, or a process to |
| attach to, or a core file, @value{GDBN} loads any auto-loaded |
| scripts provided for the program or for its loaded shared libraries. |
| @xref{Auto-loading}. |
| |
| If you wish to disable the auto-loading during startup, |
| you must do something like the following: |
| |
| @smallexample |
| $ gdb -iex "set auto-load python-scripts off" myprogram |
| @end smallexample |
| |
| Option @samp{-ex} does not work because the auto-loading is then turned |
| off too late. |
| |
| @item |
| Executes commands and command files specified by the @samp{-ex} and |
| @samp{-x} options in their specified order. @xref{Command Files}, for |
| more details about @value{GDBN} command files. |
| |
| @item |
| Reads the command history recorded in the @dfn{history file}. |
| @xref{Command History}, for more details about the command history and the |
| files where @value{GDBN} records it. |
| @end enumerate |
| |
| @node Initialization Files |
| @subsection Initialization Files |
| @cindex init file name |
| |
| During startup (@pxref{Startup}) @value{GDBN} will execute commands |
| from several initialization files. These initialization files use the |
| same syntax as @dfn{command files} (@pxref{Command Files}) and are |
| processed by @value{GDBN} in the same way. |
| |
| To display the list of initialization files loaded by @value{GDBN} at |
| startup, in the order they will be loaded, you can use @kbd{gdb |
| --help}. |
| |
| @cindex early initialization |
| The @dfn{early initialization} file is loaded very early in |
| @value{GDBN}'s initialization process, before the interpreter |
| (@pxref{Interpreters}) has been initialized, and before the default |
| target (@pxref{Targets}) is initialized. Only @code{set} or |
| @code{source} commands should be placed into an early initialization |
| file, and the only @code{set} commands that can be used are those that |
| control how @value{GDBN} starts up. |
| |
| Commands that can be placed into an early initialization file will be |
| documented as such throughout this manual. Any command that is not |
| documented as being suitable for an early initialization file should |
| instead be placed into a general initialization file. Command files |
| passed to @code{--early-init-command} or @code{-eix} are also early |
| initialization files, with the same command restrictions. Only |
| commands that can appear in an early initialization file should be |
| passed to @code{--early-init-eval-command} or @code{-eiex}. |
| |
| @cindex general initialization |
| In contrast, the @dfn{general initialization} files are processed |
| later, after @value{GDBN} has finished its own internal initialization |
| process, any valid command can be used in these files. |
| |
| @cindex initialization file |
| Throughout the rest of this document the term @dfn{initialization |
| file} refers to one of the general initialization files, not the early |
| initialization file. Any discussion of the early initialization file |
| will specifically mention that it is the early initialization file |
| being discussed. |
| |
| As the system wide and home directory initialization files are |
| processed before most command line options, changes to settings |
| (e.g.@: @samp{set complaints}) can affect subsequent processing of |
| command line options and operands. |
| |
| The following sections describe where @value{GDBN} looks for the early |
| initialization and initialization files, and the order that the files |
| are searched for. |
| |
| @subsubsection Home directory early initialization files |
| |
| @value{GDBN} initially looks for an early initialization file in the |
| users home directory@footnote{On DOS/Windows systems, the home |
| directory is the one pointed to by the @env{HOME} environment |
| variable.}. There are a number of locations that @value{GDBN} will |
| search in the home directory, these locations are searched in order |
| and @value{GDBN} will load the first file that it finds, and |
| subsequent locations will not be checked. |
| |
| On non-macOS hosts the locations searched are: |
| @itemize |
| @item |
| The file @file{gdb/gdbearlyinit} within the directory pointed to by the |
| environment variable @env{XDG_CONFIG_HOME}, if it is defined. |
| @item |
| The file @file{.config/gdb/gdbearlyinit} within the directory pointed to |
| by the environment variable @env{HOME}, if it is defined. |
| @item |
| The file @file{.gdbearlyinit} within the directory pointed to by the |
| environment variable @env{HOME}, if it is defined. |
| @end itemize |
| |
| By contrast, on macOS hosts the locations searched are: |
| @itemize |
| @item |
| The file @file{Library/Preferences/gdb/gdbearlyinit} within the |
| directory pointed to by the environment variable @env{HOME}, if it is |
| defined. |
| @item |
| The file @file{.gdbearlyinit} within the directory pointed to by the |
| environment variable @env{HOME}, if it is defined. |
| @end itemize |
| |
| It is possible to prevent the home directory early initialization file |
| from being loaded using the @samp{-nx} or @samp{-nh} command line |
| options, @pxref{Mode Options,,Choosing Modes}. |
| |
| @anchor{System Wide Init Files} |
| @subsubsection System wide initialization files |
| |
| There are two locations that are searched for system wide |
| initialization files. Both of these locations are always checked: |
| |
| @table @code |
| |
| @item @file{system.gdbinit} |
| This is a single system-wide initialization file. Its location is |
| specified with the @code{--with-system-gdbinit} configure option |
| (@pxref{System-wide configuration}). It is loaded first when |
| @value{GDBN} starts, before command line options have been processed. |
| |
| @item @file{system.gdbinit.d} |
| This is the system-wide initialization directory. Its location is |
| specified with the @code{--with-system-gdbinit-dir} configure option |
| (@pxref{System-wide configuration}). Files in this directory are |
| loaded in alphabetical order immediately after @file{system.gdbinit} |
| (if enabled) when @value{GDBN} starts, before command line options |
| have been processed. Files need to have a recognized scripting |
| language extension (@file{.py}/@file{.scm}) or be named with a |
| @file{.gdb} extension to be interpreted as regular @value{GDBN} |
| commands. @value{GDBN} will not recurse into any subdirectories of |
| this directory. |
| |
| @end table |
| |
| It is possible to prevent the system wide initialization files from |
| being loaded using the @samp{-nx} command line option, @pxref{Mode |
| Options,,Choosing Modes}. |
| |
| @anchor{Home Directory Init File} |
| @subsubsection Home directory initialization file |
| @cindex @file{gdbinit} |
| @cindex @file{.gdbinit} |
| @cindex @file{gdb.ini} |
| |
| After loading the system wide initialization files @value{GDBN} will |
| look for an initialization file in the users home |
| directory@footnote{On DOS/Windows systems, the home directory is the |
| one pointed to by the @env{HOME} environment variable.}. There are a |
| number of locations that @value{GDBN} will search in the home |
| directory, these locations are searched in order and @value{GDBN} will |
| load the first file that it finds, and subsequent locations will not |
| be checked. |
| |
| On non-Apple hosts the locations searched are: |
| @table @file |
| @item $XDG_CONFIG_HOME/gdb/gdbinit |
| @item $HOME/.config/gdb/gdbinit |
| @item $HOME/.gdbinit |
| @end table |
| |
| While on Apple hosts the locations searched are: |
| @table @file |
| @item $HOME/Library/Preferences/gdb/gdbinit |
| @item $HOME/.gdbinit |
| @end table |
| |
| It is possible to prevent the home directory initialization file from |
| being loaded using the @samp{-nx} or @samp{-nh} command line options, |
| @pxref{Mode Options,,Choosing Modes}. |
| |
| The DJGPP port of @value{GDBN} uses the name @file{gdb.ini} instead of |
| @file{.gdbinit} or @file{gdbinit}, due to the limitations of file |
| names imposed by DOS filesystems. The Windows port of @value{GDBN} |
| uses the standard name, but if it finds a @file{gdb.ini} file in your |
| home directory, it warns you about that and suggests to rename the |
| file to the standard name. |
| |
| @anchor{Init File in the Current Directory during Startup} |
| @subsubsection Local directory initialization file |
| |
| @value{GDBN} will check the current directory for a file called |
| @file{.gdbinit}. It is loaded last, after command line options |
| other than @samp{-x} and @samp{-ex} have been processed. The command |
| line options @samp{-x} and @samp{-ex} are processed last, after |
| @file{.gdbinit} has been loaded, @pxref{File Options,,Choosing |
| Files}. |
| |
| If the file in the current directory was already loaded as the home |
| directory initialization file then it will not be loaded a second |
| time. |
| |
| It is possible to prevent the local directory initialization file from |
| being loaded using the @samp{-nx} command line option, @pxref{Mode |
| Options,,Choosing Modes}. |
| |
| @node Quitting GDB |
| @section Quitting @value{GDBN} |
| @cindex exiting @value{GDBN} |
| @cindex leaving @value{GDBN} |
| |
| @table @code |
| @kindex quit @r{[}@var{expression}@r{]} |
| @kindex q @r{(@code{quit})} |
| @item quit @r{[}@var{expression}@r{]} |
| @itemx q |
| To exit @value{GDBN}, use the @code{quit} command (abbreviated |
| @code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}). If you |
| do not supply @var{expression}, @value{GDBN} will terminate normally; |
| otherwise it will terminate using the result of @var{expression} as the |
| error code. |
| @end table |
| |
| @cindex interrupt |
| An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather |
| terminates the action of any @value{GDBN} command that is in progress and |
| returns to @value{GDBN} command level. It is safe to type the interrupt |
| character at any time because @value{GDBN} does not allow it to take effect |
| until a time when it is safe. |
| |
| If you have been using @value{GDBN} to control an attached process or |
| device, you can release it with the @code{detach} command |
| (@pxref{Attach, ,Debugging an Already-running Process}). |
| |
| @node Shell Commands |
| @section Shell Commands |
| |
| If you need to execute occasional shell commands during your |
| debugging session, there is no need to leave or suspend @value{GDBN}; you can |
| just use the @code{shell} command. |
| |
| @table @code |
| @kindex shell |
| @kindex ! |
| @cindex shell escape |
| @item shell @var{command-string} |
| @itemx !@var{command-string} |
| Invoke a standard shell to execute @var{command-string}. |
| Note that no space is needed between @code{!} and @var{command-string}. |
| On GNU and Unix systems, the environment variable @env{SHELL}, if it |
| exists, determines which shell to run. Otherwise @value{GDBN} uses |
| the default shell (@file{/bin/sh} on GNU and Unix systems, |
| @file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.). |
| @end table |
| |
| The utility @code{make} is often needed in development environments. |
| You do not have to use the @code{shell} command for this purpose in |
| @value{GDBN}: |
| |
| @table @code |
| @kindex make |
| @cindex calling make |
| @item make @var{make-args} |
| Execute the @code{make} program with the specified |
| arguments. This is equivalent to @samp{shell make @var{make-args}}. |
| @end table |
| |
| @table @code |
| @kindex pipe |
| @kindex | |
| @cindex send the output of a gdb command to a shell command |
| @anchor{pipe} |
| @item pipe [@var{command}] | @var{shell_command} |
| @itemx | [@var{command}] | @var{shell_command} |
| @itemx pipe -d @var{delim} @var{command} @var{delim} @var{shell_command} |
| @itemx | -d @var{delim} @var{command} @var{delim} @var{shell_command} |
| Executes @var{command} and sends its output to @var{shell_command}. |
| Note that no space is needed around @code{|}. |
| If no @var{command} is provided, the last command executed is repeated. |
| |
| In case the @var{command} contains a @code{|}, the option @code{-d @var{delim}} |
| can be used to specify an alternate delimiter string @var{delim} that separates |
| the @var{command} from the @var{shell_command}. |
| |
| Example: |
| @smallexample |
| @group |
| (gdb) p var |
| $1 = @{ |
| black = 144, |
| red = 233, |
| green = 377, |
| blue = 610, |
| white = 987 |
| @} |
| @end group |
| @group |
| (gdb) pipe p var|wc |
| 7 19 80 |
| (gdb) |p var|wc -l |
| 7 |
| @end group |
| @group |
| (gdb) p /x var |
| $4 = @{ |
| black = 0x90, |
| red = 0xe9, |
| green = 0x179, |
| blue = 0x262, |
| white = 0x3db |
| @} |
| (gdb) ||grep red |
| red => 0xe9, |
| @end group |
| @group |
| (gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/' |
| this contains a PIPE char |
| (gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/' |
| this contains a PIPE char! |
| (gdb) |
| @end group |
| @end smallexample |
| @end table |
| |
| The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal} |
| can be used to examine the exit status of the last shell command launched |
| by @code{shell}, @code{make}, @code{pipe} and @code{|}. |
| @xref{Convenience Vars,, Convenience Variables}. |
| |
| @node Logging Output |
| @section Logging Output |
| @cindex logging @value{GDBN} output |
| @cindex save @value{GDBN} output to a file |
| |
| You may want to save the output of @value{GDBN} commands to a file. |
| There are several commands to control @value{GDBN}'s logging. |
| |
| @table @code |
| @kindex set logging |
| @item set logging on |
| Enable logging. |
| @item set logging off |
| Disable logging. |
| @cindex logging file name |
| @item set logging file @var{file} |
| Change the name of the current logfile. The default logfile is @file{gdb.txt}. |
| @item set logging overwrite [on|off] |
| By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if |
| you want @code{set logging on} to overwrite the logfile instead. |
| @item set logging redirect [on|off] |
| By default, @value{GDBN} output will go to both the terminal and the logfile. |
| Set @code{redirect} if you want output to go only to the log file. |
| @item set logging debugredirect [on|off] |
| By default, @value{GDBN} debug output will go to both the terminal and the logfile. |
| Set @code{debugredirect} if you want debug output to go only to the log file. |
| @kindex show logging |
| @item show logging |
| Show the current values of the logging settings. |
| @end table |
| |
| You can also redirect the output of a @value{GDBN} command to a |
| shell command. @xref{pipe}. |
| @node Commands |
| @chapter @value{GDBN} Commands |
| |
| You can abbreviate a @value{GDBN} command to the first few letters of the command |
| name, if that abbreviation is unambiguous; and you can repeat certain |
| @value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} |
| key to get @value{GDBN} 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). |
| |
| @menu |
| * Command Syntax:: How to give commands to @value{GDBN} |
| * Command Settings:: How to change default behavior of commands |
| * Completion:: Command completion |
| * Command Options:: Command options |
| * Help:: How to ask @value{GDBN} for help |
| @end menu |
| |
| @node Command Syntax |
| @section Command Syntax |
| |
| A @value{GDBN} 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 @code{step} accepts an argument which is the number of times to |
| step, as in @samp{step 5}. You can also use the @code{step} command |
| with no arguments. Some commands do not allow any arguments. |
| |
| @cindex abbreviation |
| @value{GDBN} 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, @code{s} is specially defined as |
| equivalent to @code{step} even though there are other commands whose |
| names start with @code{s}. You can test abbreviations by using them as |
| arguments to the @code{help} command. |
| |
| @cindex repeating commands |
| @kindex RET @r{(repeat last command)} |
| A blank line as input to @value{GDBN} (typing just @key{RET}) means to |
| repeat the previous command. Certain commands (for example, @code{run}) |
| will not repeat this way; these are commands whose unintentional |
| repetition might cause trouble and which you are unlikely to want to |
| repeat. User-defined commands can disable this feature; see |
| @ref{Define, dont-repeat}. |
| |
| The @code{list} and @code{x} commands, when you repeat them with |
| @key{RET}, construct new arguments rather than repeating |
| exactly as typed. This permits easy scanning of source or memory. |
| |
| @value{GDBN} can also use @key{RET} in another way: to partition lengthy |
| output, in a way similar to the common utility @code{more} |
| (@pxref{Screen Size,,Screen Size}). Since it is easy to press one |
| @key{RET} too many in this situation, @value{GDBN} disables command |
| repetition after any command that generates this sort of display. |
| |
| @kindex # @r{(a comment)} |
| @cindex comment |
| Any text from a @kbd{#} to the end of the line is a comment; it does |
| nothing. This is useful mainly in command files (@pxref{Command |
| Files,,Command Files}). |
| |
| @cindex repeating command sequences |
| @kindex Ctrl-o @r{(operate-and-get-next)} |
| The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of |
| commands. This command accepts the current line, like @key{RET}, and |
| then fetches the next line relative to the current line from the history |
| for editing. |
| |
| |
| @node Command Settings |
| @section Command Settings |
| @cindex default behavior of commands, changing |
| @cindex default settings, changing |
| |
| Many commands change their behavior according to command-specific |
| variables or settings. These settings can be changed with the |
| @code{set} subcommands. For example, the @code{print} command |
| (@pxref{Data, ,Examining Data}) prints arrays differently depending on |
| settings changeable with the commands @code{set print elements |
| NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others. |
| |
| You can change these settings to your preference in the gdbinit files |
| loaded at @value{GDBN} startup. @xref{Startup}. |
| |
| The settings can also be changed interactively during the debugging |
| session. For example, to change the limit of array elements to print, |
| you can do the following: |
| @smallexample |
| (@value{GDBN}) set print elements 10 |
| (@value{GDBN}) print some_array |
| $1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} |
| @end smallexample |
| |
| The above @code{set print elements 10} command changes the number of |
| elements to print from the default of 200 to 10. If you only intend |
| this limit of 10 to be used for printing @code{some_array}, then you |
| must restore the limit back to 200, with @code{set print elements |
| 200}. |
| |
| Some commands allow overriding settings with command options. For |
| example, the @code{print} command supports a number of options that |
| allow overriding relevant global print settings as set by @code{set |
| print} subcommands. @xref{print options}. The example above could be |
| rewritten as: |
| @smallexample |
| (@value{GDBN}) print -elements 10 -- some_array |
| $1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} |
| @end smallexample |
| |
| Alternatively, you can use the @code{with} command to change a setting |
| temporarily, for the duration of a command invocation. |
| |
| @table @code |
| @kindex with command |
| @kindex w @r{(@code{with})} |
| @cindex settings |
| @cindex temporarily change settings |
| @item with @var{setting} [@var{value}] [-- @var{command}] |
| @itemx w @var{setting} [@var{value}] [-- @var{command}] |
| Temporarily set @var{setting} to @var{value} for the duration of |
| @var{command}. |
| |
| @var{setting} is any setting you can change with the @code{set} |
| subcommands. @var{value} is the value to assign to @code{setting} |
| while running @code{command}. |
| |
| If no @var{command} is provided, the last command executed is |
| repeated. |
| |
| If a @var{command} is provided, it must be preceded by a double dash |
| (@code{--}) separator. This is required because some settings accept |
| free-form arguments, such as expressions or filenames. |
| |
| For example, the command |
| @smallexample |
| (@value{GDBN}) with print array on -- print some_array |
| @end smallexample |
| @noindent |
| is equivalent to the following 3 commands: |
| @smallexample |
| (@value{GDBN}) set print array on |
| (@value{GDBN}) print some_array |
| (@value{GDBN}) set print array off |
| @end smallexample |
| |
| The @code{with} command is particularly useful when you want to |
| override a setting while running user-defined commands, or commands |
| defined in Python or Guile. @xref{Extending GDB,, Extending GDB}. |
| |
| @smallexample |
| (@value{GDBN}) with print pretty on -- my_complex_command |
| @end smallexample |
| |
| To change several settings for the same command, you can nest |
| @code{with} commands. For example, @code{with language ada -- with |
| print elements 10} temporarily changes the language to Ada and sets a |
| limit of 10 elements to print for arrays and strings. |
| |
| @end table |
| |
| @node Completion |
| @section Command Completion |
| |
| @cindex completion |
| @cindex word completion |
| @value{GDBN} 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 @value{GDBN} |
| commands, @value{GDBN} subcommands, command options, and the names of symbols |
| in your program. |
| |
| Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest |
| of a word. If there is only one possibility, @value{GDBN} fills in the |
| word, and waits for you to finish the command (or press @key{RET} to |
| enter it). For example, if you type |
| |
| @c FIXME "@key" does not distinguish its argument sufficiently to permit |
| @c complete accuracy in these examples; space introduced for clarity. |
| @c If texinfo enhancements make it unnecessary, it would be nice to |
| @c replace " @key" by "@key" in the following... |
| @smallexample |
| (@value{GDBP}) info bre @key{TAB} |
| @end smallexample |
| |
| @noindent |
| @value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is |
| the only @code{info} subcommand beginning with @samp{bre}: |
| |
| @smallexample |
| (@value{GDBP}) info breakpoints |
| @end smallexample |
| |
| @noindent |
| You can either press @key{RET} at this point, to run the @code{info |
| breakpoints} command, or backspace and enter something else, if |
| @samp{breakpoints} does not look like the command you expected. (If you |
| were sure you wanted @code{info breakpoints} in the first place, you |
| might as well just type @key{RET} immediately after @samp{info bre}, |
| to exploit command abbreviations rather than command completion). |
| |
| If there is more than one possibility for the next word when you press |
| @key{TAB}, @value{GDBN} sounds a bell. You can either supply more |
| characters and try again, or just press @key{TAB} a second time; |
| @value{GDBN} displays all the possible completions for that word. For |
| example, you might want to set a breakpoint on a subroutine whose name |
| begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} |
| just sounds the bell. Typing @key{TAB} again displays all the |
| function names in your program that begin with those characters, for |
| example: |
| |
| @smallexample |
| (@value{GDBP}) b make_ @key{TAB} |
| @exdent @value{GDBN} sounds bell; press @key{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 |
| (@value{GDBP}) b make_ |
| @end smallexample |
| |
| @noindent |
| After displaying the available possibilities, @value{GDBN} copies your |
| partial input (@samp{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 @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} |
| means @kbd{@key{META} ?}. You can type this either by holding down a |
| key designated as the @key{META} shift on your keyboard (if there is |
| one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. |
| |
| If the number of possible completions is large, @value{GDBN} will |
| print as much of the list as it has collected, as well as a message |
| indicating that the list may be truncated. |
| |
| @smallexample |
| (@value{GDBP}) b m@key{TAB}@key{TAB} |
| main |
| <... the rest of the possible completions ...> |
| *** List may be truncated, max-completions reached. *** |
| (@value{GDBP}) b m |
| @end smallexample |
| |
| @noindent |
| This behavior can be controlled with the following commands: |
| |
| @table @code |
| @kindex set max-completions |
| @item set max-completions @var{limit} |
| @itemx set max-completions unlimited |
| Set the maximum number of completion candidates. @value{GDBN} will |
| stop looking for more completions once it collects this many candidates. |
| This is useful when completing on things like function names as collecting |
| all the possible candidates can be time consuming. |
| The default value is 200. A value of zero disables tab-completion. |
| Note that setting either no limit or a very large limit can make |
| completion slow. |
| @kindex show max-completions |
| @item show max-completions |
| Show the maximum number of candidates that @value{GDBN} will collect and show |
| during completion. |
| @end table |
| |
| @cindex quotes in commands |
| @cindex completion of quoted strings |
| Sometimes the string you need, while logically a ``word'', may contain |
| parentheses or other characters that @value{GDBN} normally excludes from |
| its notion of a word. To permit word completion to work in this |
| situation, you may enclose words in @code{'} (single quote marks) in |
| @value{GDBN} commands. |
| |
| A likely situation where you might need this is in typing an |
| expression that involves a C@t{++} symbol name with template |
| parameters. This is because when completing expressions, GDB treats |
| the @samp{<} character as word delimiter, assuming that it's the |
| less-than comparison operator (@pxref{C Operators, , C and C@t{++} |
| Operators}). |
| |
| For example, when you want to call a C@t{++} template function |
| interactively using the @code{print} or @code{call} commands, you may |
| need to distinguish whether you mean the version of @code{name} that |
| was specialized for @code{int}, @code{name<int>()}, or the version |
| that was specialized for @code{float}, @code{name<float>()}. To use |
| the word-completion facilities in this situation, type a single quote |
| @code{'} at the beginning of the function name. This alerts |
| @value{GDBN} that it may need to consider more information than usual |
| when you press @key{TAB} or @kbd{M-?} to request word completion: |
| |
| @smallexample |
| (@value{GDBP}) p 'func< @kbd{M-?} |
| func<int>() func<float>() |
| (@value{GDBP}) p 'func< |
| @end smallexample |
| |
| When setting breakpoints however (@pxref{Specify Location}), you don't |
| usually need to type a quote before the function name, because |
| @value{GDBN} understands that you want to set a breakpoint on a |
| function: |
| |
| @smallexample |
| (@value{GDBP}) b func< @kbd{M-?} |
| func<int>() func<float>() |
| (@value{GDBP}) b func< |
| @end smallexample |
| |
| This is true even in the case of typing the name of C@t{++} overloaded |
| functions (multiple definitions of the same function, distinguished by |
| argument type). For example, when you want to set a breakpoint you |
| don't need to distinguish whether you mean the version of @code{name} |
| that takes an @code{int} parameter, @code{name(int)}, or the version |
| that takes a @code{float} parameter, @code{name(float)}. |
| |
| @smallexample |
| (@value{GDBP}) b bubble( @kbd{M-?} |
| bubble(int) bubble(double) |
| (@value{GDBP}) b bubble(dou @kbd{M-?} |
| bubble(double) |
| @end smallexample |
| |
| See @ref{quoting names} for a description of other scenarios that |
| require quoting. |
| |
| For more information about overloaded functions, see @ref{C Plus Plus |
| Expressions, ,C@t{++} Expressions}. You can use the command @code{set |
| overload-resolution off} to disable overload resolution; |
| see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}. |
| |
| @cindex completion of structure field names |
| @cindex structure field name completion |
| @cindex completion of union field names |
| @cindex union field name completion |
| When completing in an expression which looks up a field in a |
| structure, @value{GDBN} also tries@footnote{The completer can be |
| confused by certain kinds of invalid expressions. Also, it only |
| examines the static type of the expression, not the dynamic type.} to |
| limit completions to the field names available in the type of the |
| left-hand-side: |
| |
| @smallexample |
| (@value{GDBP}) p gdb_stdout.@kbd{M-?} |
| magic to_fputs to_rewind |
| to_data to_isatty to_write |
| to_delete to_put to_write_async_safe |
| to_flush to_read |
| @end smallexample |
| |
| @noindent |
| This is because the @code{gdb_stdout} is a variable of the type |
| @code{struct ui_file} that is defined in @value{GDBN} sources as |
| follows: |
| |
| @smallexample |
| struct ui_file |
| @{ |
| int *magic; |
| ui_file_flush_ftype *to_flush; |
| ui_file_write_ftype *to_write; |
| ui_file_write_async_safe_ftype *to_write_async_safe; |
| ui_file_fputs_ftype *to_fputs; |
| ui_file_read_ftype *to_read; |
| ui_file_delete_ftype *to_delete; |
| ui_file_isatty_ftype *to_isatty; |
| ui_file_rewind_ftype *to_rewind; |
| ui_file_put_ftype *to_put; |
| void *to_data; |
| @} |
| @end smallexample |
| |
| @node Command Options |
| @section Command options |
| |
| @cindex command options |
| Some commands accept options starting with a leading dash. For |
| example, @code{print -pretty}. Similarly to command names, you can |
| abbreviate a @value{GDBN} option to the first few letters of the |
| option name, if that abbreviation is unambiguous, and you can also use |
| the @key{TAB} key to get @value{GDBN} to fill out the rest of a word |
| in an option (or to show you the alternatives available, if there is |
| more than one possibility). |
| |
| @cindex command options, raw input |
| Some commands take raw input as argument. For example, the print |
| command processes arbitrary expressions in any of the languages |
| supported by @value{GDBN}. With such commands, because raw input may |
| start with a leading dash that would be confused with an option or any |
| of its abbreviations, e.g.@: @code{print -p} (short for @code{print |
| -pretty} or printing negative @code{p}?), if you specify any command |
| option, then you must use a double-dash (@code{--}) delimiter to |
| indicate the end of options. |
| |
| @cindex command options, boolean |
| |
| Some options are described as accepting an argument which can be |
| either @code{on} or @code{off}. These are known as @dfn{boolean |
| options}. Similarly to boolean settings commands---@code{on} and |
| @code{off} are the typical values, but any of @code{1}, @code{yes} and |
| @code{enable} can also be used as ``true'' value, and any of @code{0}, |
| @code{no} and @code{disable} can also be used as ``false'' value. You |
| can also omit a ``true'' value, as it is implied by default. |
| |
| For example, these are equivalent: |
| |
| @smallexample |
| (@value{GDBP}) print -object on -pretty off -element unlimited -- *myptr |
| (@value{GDBP}) p -o -p 0 -e u -- *myptr |
| @end smallexample |
| |
| You can discover the set of options some command accepts by completing |
| on @code{-} after the command name. For example: |
| |
| @smallexample |
| (@value{GDBP}) print -@key{TAB}@key{TAB} |
| -address -max-depth -raw-values -union |
| -array -null-stop -repeats -vtbl |
| -array-indexes -object -static-members |
| -elements -pretty -symbol |
| @end smallexample |
| |
| Completion will in some cases guide you with a suggestion of what kind |
| of argument an option expects. For example: |
| |
| @smallexample |
| (@value{GDBP}) print -elements @key{TAB}@key{TAB} |
| NUMBER unlimited |
| @end smallexample |
| |
| Here, the option expects a number (e.g., @code{100}), not literal |
| @code{NUMBER}. Such metasyntactical arguments are always presented in |
| uppercase. |
| |
| (For more on using the @code{print} command, see @ref{Data, ,Examining |
| Data}.) |
| |
| @node Help |
| @section Getting Help |
| @cindex online documentation |
| @kindex help |
| |
| You can always ask @value{GDBN} itself for information on its commands, |
| using the command @code{help}. |
| |
| @table @code |
| @kindex h @r{(@code{help})} |
| @item help |
| @itemx h |
| You can use @code{help} (abbreviated @code{h}) with no arguments to |
| display a short list of named classes of commands: |
| |
| @smallexample |
| (@value{GDBP}) help |
| List of classes of commands: |
| |
| aliases -- User-defined aliases of other commands |
| breakpoints -- Making program stop at certain points |
| data -- Examining data |
| files -- Specifying and examining files |
| internals -- Maintenance commands |
| obscure -- Obscure features |
| running -- Running the program |
| stack -- Examining the stack |
| status -- Status inquiries |
| support -- Support facilities |
| tracepoints -- Tracing of program execution without |
| stopping the program |
| user-defined -- User-defined commands |
| |
| Type "help" followed by a class name for a list of |
| commands in that class. |
| Type "help" followed by command name for full |
| documentation. |
| Command name abbreviations are allowed if unambiguous. |
| (@value{GDBP}) |
| @end smallexample |
| @c the above line break eliminates huge line overfull... |
| |
| @item help @var{class} |
| Using one of the general help classes as an argument, you can get a |
| list of the individual commands in that class. If a command has |
| aliases, the aliases are given after the command name, separated by |
| commas. If an alias has default arguments, the full definition of |
| the alias is given after the first line. |
| For example, here is the help display for the class @code{status}: |
| |
| @smallexample |
| (@value{GDBP}) help status |
| Status inquiries. |
| |
| List of commands: |
| |
| @c Line break in "show" line falsifies real output, but needed |
| @c to fit in smallbook page size. |
| info, inf, i -- Generic command for showing things |
| about the program being debugged |
| info address, iamain -- Describe where symbol SYM is stored. |
| alias iamain = info address main |
| info all-registers -- List of all registers and their contents, |
| for selected stack frame. |
| ... |
| show, info set -- Generic command for showing things |
| about the debugger |
| |
| Type "help" followed by command name for full |
| documentation. |
| Command name abbreviations are allowed if unambiguous. |
| (@value{GDBP}) |
| @end smallexample |
| |
| @item help @var{command} |
| With a command name as @code{help} argument, @value{GDBN} displays a |
| short paragraph on how to use that command. If that command has |
| one or more aliases, @value{GDBN} will display a first line with |
| the command name and all its aliases separated by commas. |
| This first line will be followed by the full definition of all aliases |
| having default arguments. |
| |
| @kindex apropos |
| @item apropos [-v] @var{regexp} |
| The @code{apropos} command searches through all of the @value{GDBN} |
| commands, and their documentation, for the regular expression specified in |
| @var{args}. It prints out all matches found. The optional flag @samp{-v}, |
| which stands for @samp{verbose}, indicates to output the full documentation |
| of the matching commands and highlight the parts of the documentation |
| matching @var{regexp}. For example: |
| |
| @smallexample |
| apropos alias |
| @end smallexample |
| |
| @noindent |
| results in: |
| |
| @smallexample |
| @group |
| alias -- Define a new command that is an alias of an existing command |
| aliases -- User-defined aliases of other commands |
| @end group |
| @end smallexample |
| |
| @noindent |
| while |
| |
| @smallexample |
| apropos -v cut.*thread apply |
| @end smallexample |
| |
| @noindent |
| results in the below output, where @samp{cut for 'thread apply} |
| is highlighted if styling is enabled. |
| |
| @smallexample |
| @group |
| taas -- Apply a command to all threads (ignoring errors |
| and empty output). |
| Usage: taas COMMAND |
| shortcut for 'thread apply all -s COMMAND' |
| |
| tfaas -- Apply a command to all frames of all threads |
| (ignoring errors and empty output). |
| Usage: tfaas COMMAND |
| shortcut for 'thread apply all -s frame apply all -s COMMAND' |
| @end group |
| @end smallexample |
| |
| @kindex complete |
| @item complete @var{args} |
| The @code{complete @var{args}} command lists all the possible completions |
| for the beginning of a command. Use @var{args} to specify the beginning of the |
| command you want completed. For example: |
| |
| @smallexample |
| complete i |
| @end smallexample |
| |
| @noindent results in: |
| |
| @smallexample |
| @group |
| if |
| ignore |
| info |
| inspect |
| @end group |
| @end smallexample |
| |
| @noindent This is intended for use by @sc{gnu} Emacs. |
| @end table |
| |
| In addition to @code{help}, you can use the @value{GDBN} commands @code{info} |
| and @code{show} to inquire about the state of your program, or the state |
| of @value{GDBN} itself. Each command supports many topics of inquiry; this |
| manual introduces each of them in the appropriate context. The listings |
| under @code{info} and under @code{show} in the Command, Variable, and |
| Function Index point to all the sub-commands. @xref{Command and Variable |
| Index}. |
| |
| @c @group |
| @table @code |
| @kindex info |
| @kindex i @r{(@code{info})} |
| @item info |
| This command (abbreviated @code{i}) is for describing the state of your |
| program. For example, you can show the arguments passed to a function |
| with @code{info args}, list the registers currently in use with @code{info |
| registers}, or list the breakpoints you have set with @code{info breakpoints}. |
| You can get a complete list of the @code{info} sub-commands with |
| @w{@code{help info}}. |
| |
| @kindex set |
| @item set |
| You can assign the result of an expression to an environment variable with |
| @code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with |
| @code{set prompt $}. |
| |
| @kindex show |
| @item show |
| In contrast to @code{info}, @code{show} is for describing the state of |
| @value{GDBN} itself. |
| You can change most of the things you can @code{show}, by using the |
| related command @code{set}; for example, you can control what number |
| system is used for displays with @code{set radix}, or simply inquire |
| which is currently in use with @code{show radix}. |
| |
| @kindex info set |
| To display all the settable parameters and their current |
| values, you can use @code{show} with no arguments; you may also use |
| @code{info set}. Both commands produce the same display. |
| @c FIXME: "info set" violates the rule that "info" is for state of |
| @c FIXME...program. Ck w/ GNU: "info set" to be called something else, |
| @c FIXME...or change desc of rule---eg "state of prog and debugging session"? |
| @end table |
| @c @end group |
| |
| Here are several miscellaneous @code{show} subcommands, all of which are |
| exceptional in lacking corresponding @code{set} commands: |
| |
| @table @code |
| @kindex show version |
| @cindex @value{GDBN} version number |
| @item show version |
| Show what version of @value{GDBN} is running. You should include this |
| information in @value{GDBN} bug-reports. If multiple versions of |
| @value{GDBN} are in use at your site, you may need to determine which |
| version of @value{GDBN} you are running; as @value{GDBN} evolves, new |
| commands are introduced, and old ones may wither away. Also, many |
| system vendors ship variant versions of @value{GDBN}, and there are |
| variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well. |
| The version number is the same as the one announced when you start |
| @value{GDBN}. |
| |
| @kindex show copying |
| @kindex info copying |
| @cindex display @value{GDBN} copyright |
| @item show copying |
| @itemx info copying |
| Display information about permission for copying @value{GDBN}. |
| |
| @kindex show warranty |
| @kindex info warranty |
| @item show warranty |
| @itemx info warranty |
| Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty, |
| if your version of @value{GDBN} comes with one. |
| |
| @kindex show configuration |
| @item show configuration |
| Display detailed information about the way @value{GDBN} was configured |
| when it was built. This displays the optional arguments passed to the |
| @file{configure} script and also configuration parameters detected |
| automatically by @command{configure}. When reporting a @value{GDBN} |
| bug (@pxref{GDB Bugs}), it is important to include this information in |
| your report. |
| |
| @end table |
| |
| @node Running |
| @chapter Running Programs Under @value{GDBN} |
| |
| When you run a program under @value{GDBN}, you must first generate |
| debugging information when you compile it. |
| |
| You may start @value{GDBN} with its arguments, if any, in an environment |
| of your choice. If you are doing native debugging, you may redirect |
| your program's input and output, debug an already running process, or |
| kill a child process. |
| |
| @menu |
| * Compilation:: Compiling for debugging |
| * Starting:: Starting your program |
| * Arguments:: Your program's arguments |
| * Environment:: Your program's environment |
| |
| * Working Directory:: Your program's working directory |
| * Input/Output:: Your program's input and output |
| * Attach:: Debugging an already-running process |
| * Kill Process:: Killing the child process |
| * Inferiors Connections and Programs:: Debugging multiple inferiors |
| connections and programs |
| * Threads:: Debugging programs with multiple threads |
| * Forks:: Debugging forks |
| * Checkpoint/Restart:: Setting a @emph{bookmark} to return to later |
| @end menu |
| |
| @node Compilation |
| @section Compiling for Debugging |
| |
| In order to debug a program effectively, you need to generate |
| debugging information when you compile it. This debugging information |
| is stored in the object file; it describes the data type of each |
| variable or function and the correspondence between source line numbers |
| and addresses in the executable code. |
| |
| To request debugging information, specify the @samp{-g} option when you run |
| the compiler. |
| |
| Programs that are to be shipped to your customers are compiled with |
| optimizations, using the @samp{-O} compiler option. However, some |
| compilers are unable to handle the @samp{-g} and @samp{-O} options |
| together. Using those compilers, you cannot generate optimized |
| executables containing debugging information. |
| |
| @value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or |
| without @samp{-O}, making it possible to debug optimized code. We |
| recommend that you @emph{always} use @samp{-g} whenever you compile a |
| program. You may think your program is correct, but there is no sense |
| in pushing your luck. For more information, see @ref{Optimized Code}. |
| |
| Older versions of the @sc{gnu} C compiler permitted a variant option |
| @w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this |
| format; if your @sc{gnu} C compiler has this option, do not use it. |
| |
| @value{GDBN} knows about preprocessor macros and can show you their |
| expansion (@pxref{Macros}). Most compilers do not include information |
| about preprocessor macros in the debugging information if you specify |
| the @option{-g} flag alone. Version 3.1 and later of @value{NGCC}, |
| the @sc{gnu} C compiler, provides macro information if you are using |
| the DWARF debugging format, and specify the option @option{-g3}. |
| |
| @xref{Debugging Options,,Options for Debugging Your Program or GCC, |
| gcc, Using the @sc{gnu} Compiler Collection (GCC)}, for more |
| information on @value{NGCC} options affecting debug information. |
| |
| You will have the best debugging experience if you use the latest |
| version of the DWARF debugging format that your compiler supports. |
| DWARF is currently the most expressive and best supported debugging |
| format in @value{GDBN}. |
| |
| @need 2000 |
| @node Starting |
| @section Starting your Program |
| @cindex starting |
| @cindex running |
| |
| @table @code |
| @kindex run |
| @kindex r @r{(@code{run})} |
| @item run |
| @itemx r |
| Use the @code{run} command to start your program under @value{GDBN}. |
| You must first specify the program name with an argument to |
| @value{GDBN} (@pxref{Invocation, ,Getting In and Out of |
| @value{GDBN}}), or by using the @code{file} or @code{exec-file} |
| command (@pxref{Files, ,Commands to Specify Files}). |
| |
| @end table |
| |
| If you are running your program in an execution environment that |
| supports processes, @code{run} creates an inferior process and makes |
| that process run your program. In some environments without processes, |
| @code{run} jumps to the start of your program. Other targets, |
| like @samp{remote}, are always running. If you get an error |
| message like this one: |
| |
| @smallexample |
| The "remote" target does not support "run". |
| Try "help target" or "continue". |
| @end smallexample |
| |
| @noindent |
| then use @code{continue} to run your program. You may need @code{load} |
| first (@pxref{load}). |
| |
| The execution of a program is affected by certain information it |
| receives from its superior. @value{GDBN} provides ways to specify this |
| information, which you must do @emph{before} starting your program. (You |
| can change it after starting your program, but such changes only affect |
| your program the next time you start it.) This information may be |
| divided into four categories: |
| |
| @table @asis |
| @item The @emph{arguments.} |
| Specify the arguments to give your program as the arguments of the |
| @code{run} command. If a shell is available on your target, the shell |
| is used to pass the arguments, so that you may use normal conventions |
| (such as wildcard expansion or variable substitution) in describing |
| the arguments. |
| In Unix systems, you can control which shell is used with the |
| @env{SHELL} environment variable. If you do not define @env{SHELL}, |
| @value{GDBN} uses the default shell (@file{/bin/sh}). You can disable |
| use of any shell with the @code{set startup-with-shell} command (see |
| below for details). |
| |
| @item The @emph{environment.} |
| Your program normally inherits its environment from @value{GDBN}, but you can |
| use the @value{GDBN} commands @code{set environment} and @code{unset |
| environment} to change parts of the environment that affect |
| your program. @xref{Environment, ,Your Program's Environment}. |
| |
| @item The @emph{working directory.} |
| You can set your program's working directory with the command |
| @kbd{set cwd}. If you do not set any working directory with this |
| command, your program will inherit @value{GDBN}'s working directory if |
| native debugging, or the remote server's working directory if remote |
| debugging. @xref{Working Directory, ,Your Program's Working |
| Directory}. |
| |
| @item The @emph{standard input and output.} |
| Your program normally uses the same device for standard input and |
| standard output as @value{GDBN} is using. You can redirect input and output |
| in the @code{run} command line, or you can use the @code{tty} command to |
| set a different device for your program. |
| @xref{Input/Output, ,Your Program's Input and Output}. |
| |
| @cindex pipes |
| @emph{Warning:} While input and output redirection work, you cannot use |
| pipes to pass the output of the program you are debugging to another |
| program; if you attempt this, @value{GDBN} is likely to wind up debugging the |
| wrong program. |
| @end table |
| |
| When you issue the @code{run} command, your program begins to execute |
| immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion |
| of how to arrange for your program to stop. Once your program has |
| stopped, you may call functions in your program, using the @code{print} |
| or @code{call} commands. @xref{Data, ,Examining Data}. |
| |
| If the modification time of your symbol file has changed since the last |
| time @value{GDBN} read its symbols, @value{GDBN} discards its symbol |
| table, and reads it again. When it does this, @value{GDBN} tries to retain |
| your current breakpoints. |
| |
| @table @code |
| @kindex start |
| @item start |
| @cindex run to main procedure |
| The name of the main procedure can vary from language to language. |
| With C or C@t{++}, the main procedure name is always @code{main}, but |
| other languages such as Ada do not require a specific name for their |
| main procedure. The debugger provides a convenient way to start the |
| execution of the program and to stop at the beginning of the main |
| procedure, depending on the language used. |
| |
| The @samp{start} command does the equivalent of setting a temporary |
| breakpoint at the beginning of the main procedure and then invoking |
| the @samp{run} command. |
| |
| @cindex elaboration phase |
| Some programs contain an @dfn{elaboration} phase where some startup code is |
| executed before the main procedure is called. This depends on the |
| languages used to write your program. In C@t{++}, for instance, |
| constructors for static and global objects are executed before |
| @code{main} is called. It is therefore possible that the debugger stops |
| before reaching the main procedure. However, the temporary breakpoint |
| will remain to halt execution. |
| |
| Specify the arguments to give to your program as arguments to the |
| @samp{start} command. These arguments will be given verbatim to the |
| underlying @samp{run} command. Note that the same arguments will be |
| reused if no argument is provided during subsequent calls to |
| @samp{start} or @samp{run}. |
| |
| It is sometimes necessary to debug the program during elaboration. In |
| these cases, using the @code{start} command would stop the execution |
| of your program too late, as the program would have already completed |
| the elaboration phase. Under these circumstances, either insert |
| breakpoints in your elaboration code before running your program or |
| use the @code{starti} command. |
| |
| @kindex starti |
| @item starti |
| @cindex run to first instruction |
| The @samp{starti} command does the equivalent of setting a temporary |
| breakpoint at the first instruction of a program's execution and then |
| invoking the @samp{run} command. For programs containing an |
| elaboration phase, the @code{starti} command will stop execution at |
| the start of the elaboration phase. |
| |
| @anchor{set exec-wrapper} |
| @kindex set exec-wrapper |
| @item set exec-wrapper @var{wrapper} |
| @itemx show exec-wrapper |
| @itemx unset exec-wrapper |
| When @samp{exec-wrapper} is set, the specified wrapper is used to |
| launch programs for debugging. @value{GDBN} starts your program |
| with a shell command of the form @kbd{exec @var{wrapper} |
| @var{program}}. Quoting is added to @var{program} and its |
| arguments, but not to @var{wrapper}, so you should add quotes if |
| appropriate for your shell. The wrapper runs until it executes |
| your program, and then @value{GDBN} takes control. |
| |
| You can use any program that eventually calls @code{execve} with |
| its arguments as a wrapper. Several standard Unix utilities do |
| this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending |
| with @code{exec "$@@"} will also work. |
| |
| For example, you can use @code{env} to pass an environment variable to |
| the debugged program, without setting the variable in your shell's |
| environment: |
| |
| @smallexample |
| (@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so' |
| (@value{GDBP}) run |
| @end smallexample |
| |
| This command is available when debugging locally on most targets, excluding |
| @sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino. |
| |
| @kindex set startup-with-shell |
| @anchor{set startup-with-shell} |
| @item set startup-with-shell |
| @itemx set startup-with-shell on |
| @itemx set startup-with-shell off |
| @itemx show startup-with-shell |
| On Unix systems, by default, if a shell is available on your target, |
| @value{GDBN}) uses it to start your program. Arguments of the |
| @code{run} command are passed to the shell, which does variable |
| substitution, expands wildcard characters and performs redirection of |
| I/O. In some circumstances, it may be useful to disable such use of a |
| shell, for example, when debugging the shell itself or diagnosing |
| startup failures such as: |
| |
| @smallexample |
| (@value{GDBP}) run |
| Starting program: ./a.out |
| During startup program terminated with signal SIGSEGV, Segmentation fault. |
| @end smallexample |
| |
| @noindent |
| which indicates the shell or the wrapper specified with |
| @samp{exec-wrapper} crashed, not your program. Most often, this is |
| caused by something odd in your shell's non-interactive mode |
| initialization file---such as @file{.cshrc} for C-shell, |
| $@file{.zshenv} for the Z shell, or the file specified in the |
| @env{BASH_ENV} environment variable for BASH. |
| |
| @anchor{set auto-connect-native-target} |
| @kindex set auto-connect-native-target |
| @item set auto-connect-native-target |
| @itemx set auto-connect-native-target on |
| @itemx set auto-connect-native-target off |
| @itemx show auto-connect-native-target |
| |
| By default, if the current inferior is not connected to any target yet |
| (e.g., with @code{target remote}), the @code{run} command starts your |
| program as a native process under @value{GDBN}, on your local machine. |
| If you're sure you don't want to debug programs on your local machine, |
| you can tell @value{GDBN} to not connect to the native target |
| automatically with the @code{set auto-connect-native-target off} |
| command. |
| |
| If @code{on}, which is the default, and if the current inferior is not |
| connected to a target already, the @code{run} command automaticaly |
| connects to the native target, if one is available. |
| |
| If @code{off}, and if the current inferior is not connected to a |
| target already, the @code{run} command fails with an error: |
| |
| @smallexample |
| (@value{GDBP}) run |
| Don't know how to run. Try "help target". |
| @end smallexample |
| |
| If the current inferior is already connected to a target, @value{GDBN} |
| always uses it with the @code{run} command. |
| |
| In any case, you can explicitly connect to the native target with the |
| @code{target native} command. For example, |
| |
| @smallexample |
| (@value{GDBP}) set auto-connect-native-target off |
| (@value{GDBP}) run |
| Don't know how to run. Try "help target". |
| (@value{GDBP}) target native |
| (@value{GDBP}) run |
| Starting program: ./a.out |
| [Inferior 1 (process 10421) exited normally] |
| @end smallexample |
| |
| In case you connected explicitly to the @code{native} target, |
| @value{GDBN} remains connected even if all inferiors exit, ready for |
| the next @code{run} command. Use the @code{disconnect} command to |
| disconnect. |
| |
| Examples of other commands that likewise respect the |
| @code{auto-connect-native-target} setting: @code{attach}, @code{info |
| proc}, @code{info os}. |
| |
| @kindex set disable-randomization |
| @item set disable-randomization |
| @itemx set disable-randomization on |
| This option (enabled by default in @value{GDBN}) will turn off the native |
| randomization of the virtual address space of the started program. This option |
| is useful for multiple debugging sessions to make the execution better |
| reproducible and memory addresses reusable across debugging sessions. |
| |
| This feature is implemented only on certain targets, including @sc{gnu}/Linux. |
| On @sc{gnu}/Linux you can get the same behavior using |
| |
| @smallexample |
| (@value{GDBP}) set exec-wrapper setarch `uname -m` -R |
| @end smallexample |
| |
| @item set disable-randomization off |
| Leave the behavior of the started executable unchanged. Some bugs rear their |
| ugly heads only when the program is loaded at certain addresses. If your bug |
| disappears when you run the program under @value{GDBN}, that might be because |
| @value{GDBN} by default disables the address randomization on platforms, such |
| as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set |
| disable-randomization off} to try to reproduce such elusive bugs. |
| |
| On targets where it is available, virtual address space randomization |
| protects the programs against certain kinds of security attacks. In these |
| cases the attacker needs to know the exact location of a concrete executable |
| code. Randomizing its location makes it impossible to inject jumps misusing |
| a code at its expected addresses. |
| |
| Prelinking shared libraries provides a startup performance advantage but it |
| makes addresses in these libraries predictable for privileged processes by |
| having just unprivileged access at the target system. Reading the shared |
| library binary gives enough information for assembling the malicious code |
| misusing it. Still even a prelinked shared library can get loaded at a new |
| random address just requiring the regular relocation process during the |
| startup. Shared libraries not already prelinked are always loaded at |
| a randomly chosen address. |
| |
| Position independent executables (PIE) contain position independent code |
| similar to the shared libraries and therefore such executables get loaded at |
| a randomly chosen address upon startup. PIE executables always load even |
| already prelinked shared libraries at a random address. You can build such |
| executable using @command{gcc -fPIE -pie}. |
| |
| Heap (malloc storage), stack and custom mmap areas are always placed randomly |
| (as long as the randomization is enabled). |
| |
| @item show disable-randomization |
| Show the current setting of the explicit disable of the native randomization of |
| the virtual address space of the started program. |
| |
| @end table |
| |
| @node Arguments |
| @section Your Program's Arguments |
| |
| @cindex arguments (to your program) |
| The arguments to your program can be specified by the arguments of the |
| @code{run} command. |
| They are passed to a shell, which expands wildcard characters and |
| performs redirection of I/O, and thence to your program. Your |
| @env{SHELL} environment variable (if it exists) specifies what shell |
| @value{GDBN} uses. If you do not define @env{SHELL}, @value{GDBN} uses |
| the default shell (@file{/bin/sh} on Unix). |
| |
| On non-Unix systems, the program is usually invoked directly by |
| @value{GDBN}, which emulates I/O redirection via the appropriate system |
| calls, and the wildcard characters are expanded by the startup code of |
| the program, not by the shell. |
| |
| @code{run} with no arguments uses the same arguments used by the previous |
| @code{run}, or those set by the @code{set args} command. |
| |
| @table @code |
| @kindex set args |
| @item set args |
| Specify the arguments to be used the next time your program is run. If |
| @code{set args} has no arguments, @code{run} executes your program |
| with no arguments. Once you have run your program with arguments, |
| using @code{set args} before the next @code{run} is the only way to run |
| it again without arguments. |
| |
| @kindex show args |
| @item show args |
| Show the arguments to give your program when it is started. |
| @end table |
| |
| @node Environment |
| @section Your Program's Environment |
| |
| @cindex environment (of your program) |
| The @dfn{environment} consists of a set of environment variables and |
| their values. Environment variables conventionally record such things as |
| your user name, your home directory, your terminal type, and your search |
| path for programs to run. Usually you set up environment variables with |
| the shell and they are inherited by all the other programs you run. When |
| debugging, it can be useful to try running your program with a modified |
| environment without having to start @value{GDBN} over again. |
| |
| @table @code |
| @kindex path |
| @item path @var{directory} |
| Add @var{directory} to the front of the @env{PATH} environment variable |
| (the search path for executables) that will be passed to your program. |
| The value of @env{PATH} used by @value{GDBN} does not change. |
| You may specify several directory names, separated by whitespace or by a |
| system-dependent separator character (@samp{:} on Unix, @samp{;} on |
| MS-DOS and MS-Windows). If @var{directory} is already in the path, it |
| is moved to the front, so it is searched sooner. |
| |
| You can use the string @samp{$cwd} to refer to whatever is the current |
| working directory at the time @value{GDBN} searches the path. If you |
| use @samp{.} instead, it refers to the directory where you executed the |
| @code{path} command. @value{GDBN} replaces @samp{.} in the |
| @var{directory} argument (with the current path) before adding |
| @var{directory} to the search path. |
| @c 'path' is explicitly nonrepeatable, but RMS points out it is silly to |
| @c document that, since repeating it would be a no-op. |
| |
| @kindex show paths |
| @item show paths |
| Display the list of search paths for executables (the @env{PATH} |
| environment variable). |
| |
| @kindex show environment |
| @item show environment @r{[}@var{varname}@r{]} |
| Print the value of environment variable @var{varname} to be given to |
| your program when it starts. If you do not supply @var{varname}, |
| print the names and values of all environment variables to be given to |
| your program. You can abbreviate @code{environment} as @code{env}. |
| |
| @kindex set environment |
| @anchor{set environment} |
| @item set environment @var{varname} @r{[}=@var{value}@r{]} |
| Set environment variable @var{varname} to @var{value}. The value |
| changes for your program (and the shell @value{GDBN} uses to launch |
| it), not for @value{GDBN} itself. The @var{value} may be any string; the |
| values of environment variables are just strings, and any |
| interpretation is supplied by your program itself. The @var{value} |
| parameter is optional; if it is eliminated, the variable is set to a |
| null value. |
| @c "any string" here does not include leading, trailing |
| @c blanks. Gnu asks: does anyone care? |
| |
| For example, this command: |
| |
| @smallexample |
| set env USER = foo |
| @end smallexample |
| |
| @noindent |
| tells the debugged program, when subsequently run, that its user is named |
| @samp{foo}. (The spaces around @samp{=} are used for clarity here; they |
| are not actually required.) |
| |
| Note that on Unix systems, @value{GDBN} runs your program via a shell, |
| which also inherits the environment set with @code{set environment}. |
| If necessary, you can avoid that by using the @samp{env} program as a |
| wrapper instead of using @code{set environment}. @xref{set |
| exec-wrapper}, for an example doing just that. |
| |
| Environment variables that are set by the user are also transmitted to |
| @command{gdbserver} to be used when starting the remote inferior. |
| @pxref{QEnvironmentHexEncoded}. |
| |
| @kindex unset environment |
| @anchor{unset environment} |
| @item unset environment @var{varname} |
| Remove variable @var{varname} from the environment to be passed to your |
| program. This is different from @samp{set env @var{varname} =}; |
| @code{unset environment} removes the variable from the environment, |
| rather than assigning it an empty value. |
| |
| Environment variables that are unset by the user are also unset on |
| @command{gdbserver} when starting the remote inferior. |
| @pxref{QEnvironmentUnset}. |
| @end table |
| |
| @emph{Warning:} On Unix systems, @value{GDBN} runs your program using |
| the shell indicated by your @env{SHELL} environment variable if it |
| exists (or @code{/bin/sh} if not). If your @env{SHELL} variable |
| names a shell that runs an initialization file when started |
| non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv} |
| for the Z shell, or the file specified in the @env{BASH_ENV} |
| environment variable for BASH---any variables you set in that file |
| affect your program. You may wish to move setting of environment |
| variables to files that are only run when you sign on, such as |
| @file{.login} or @file{.profile}. |
| |
| @node Working Directory |
| @section Your Program's Working Directory |
| |
| @cindex working directory (of your program) |
| Each time you start your program with @code{run}, the inferior will be |
| initialized with the current working directory specified by the |
| @kbd{set cwd} command. If no directory has been specified by this |
| command, then the inferior will inherit @value{GDBN}'s current working |
| directory as its working directory if native debugging, or it will |
| inherit the remote server's current working directory if remote |
| debugging. |
| |
| @table @code |
| @kindex set cwd |
| @cindex change inferior's working directory |
| @anchor{set cwd command} |
| @item set cwd @r{[}@var{directory}@r{]} |
| Set the inferior's working directory to @var{directory}, which will be |
| @code{glob}-expanded in order to resolve tildes (@file{~}). If no |
| argument has been specified, the command clears the setting and resets |
| it to an empty state. This setting has no effect on @value{GDBN}'s |
| working directory, and it only takes effect the next time you start |
| the inferior. The @file{~} in @var{directory} is a short for the |
| @dfn{home directory}, usually pointed to by the @env{HOME} environment |
| variable. On MS-Windows, if @env{HOME} is not defined, @value{GDBN} |
| uses the concatenation of @env{HOMEDRIVE} and @env{HOMEPATH} as |
| fallback. |
| |
| You can also change @value{GDBN}'s current working directory by using |
| the @code{cd} command. |
| @xref{cd command}. |
| |
| @kindex show cwd |
| @cindex show inferior's working directory |
| @item show cwd |
| Show the inferior's working directory. If no directory has been |
| specified by @kbd{set cwd}, then the default inferior's working |
| directory is the same as @value{GDBN}'s working directory. |
| |
| @kindex cd |
| @cindex change @value{GDBN}'s working directory |
| @anchor{cd command} |
| @item cd @r{[}@var{directory}@r{]} |
| Set the @value{GDBN} working directory to @var{directory}. If not |
| given, @var{directory} uses @file{'~'}. |
| |
| The @value{GDBN} working directory serves as a default for the |
| commands that specify files for @value{GDBN} to operate on. |
| @xref{Files, ,Commands to Specify Files}. |
| @xref{set cwd command}. |
| |
| @kindex pwd |
| @item pwd |
| Print the @value{GDBN} working directory. |
| @end table |
| |
| It is generally impossible to find the current working directory of |
| the process being debugged (since a program can change its directory |
| during its run). If you work on a system where @value{GDBN} supports |
| the @code{info proc} command (@pxref{Process Information}), you can |
| use the @code{info proc} command to find out the |
| current working directory of the debuggee. |
| |
| @node Input/Output |
| @section Your Program's Input and Output |
| |
| @cindex redirection |
| @cindex i/o |
| @cindex terminal |
| By default, the program you run under @value{GDBN} does input and output to |
| the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal |
| to its own terminal modes to interact with you, but it records the terminal |
| modes your program was using and switches back to them when you continue |
| running your program. |
| |
| @table @code |
| @kindex info terminal |
| @item info terminal |
| Displays information recorded by @value{GDBN} about the terminal modes your |
| program is using. |
| @end table |
| |
| You can redirect your program's input and/or output using shell |
| redirection with the @code{run} command. For example, |
| |
| @smallexample |
| run > outfile |
| @end smallexample |
| |
| @noindent |
| starts your program, diverting its output to the file @file{outfile}. |
| |
| @kindex tty |
| @cindex controlling terminal |
| Another way to specify where your program should do input and output is |
| with the @code{tty} command. This command accepts a file name as |
| argument, and causes this file to be the default for future @code{run} |
| commands. It also resets the controlling terminal for the child |
| process, for future @code{run} commands. For example, |
| |
| @smallexample |
| tty /dev/ttyb |
| @end smallexample |
| |
| @noindent |
| directs that processes started with subsequent @code{run} commands |
| default to do input and output on the terminal @file{/dev/ttyb} and have |
| that as their controlling terminal. |
| |
| An explicit redirection in @code{run} overrides the @code{tty} command's |
| effect on the input/output device, but not its effect on the controlling |
| terminal. |
| |
| When you use the @code{tty} command or redirect input in the @code{run} |
| command, only the input @emph{for your program} is affected. The input |
| for @value{GDBN} still comes from your terminal. @code{tty} is an alias |
| for @code{set inferior-tty}. |
| |
| @cindex inferior tty |
| @cindex set inferior controlling terminal |
| You can use the @code{show inferior-tty} command to tell @value{GDBN} to |
| display the name of the terminal that will be used for future runs of your |
| program. |
| |
| @table @code |
| @item set inferior-tty [ @var{tty} ] |
| @kindex set inferior-tty |
| Set the tty for the program being debugged to @var{tty}. Omitting @var{tty} |
| restores the default behavior, which is to use the same terminal as |
| @value{GDBN}. |
| |
| @item show inferior-tty |
| @kindex show inferior-tty |
| Show the current tty for the program being debugged. |
| @end table |
| |
| @node Attach |
| @section Debugging an Already-running Process |
| @kindex attach |
| @cindex attach |
| |
| @table @code |
| @item attach @var{process-id} |
| This command attaches to a running process---one that was started |
| outside @value{GDBN}. (@code{info files} shows your active |
| targets.) The command takes as argument a process ID. The usual way to |
| find out the @var{process-id} of a Unix process is with the @code{ps} utility, |
| or with the @samp{jobs -l} shell command. |
| |
| @code{attach} does not repeat if you press @key{RET} a second time after |
| executing the command. |
| @end table |
| |
| To use @code{attach}, your program must be running in an environment |
| which supports processes; for example, @code{attach} does not work for |
| programs on bare-board targets that lack an operating system. You must |
| also have permission to send the process a signal. |
| |
| When you use @code{attach}, the debugger finds the program running in |
| the process first by looking in the current working directory, then (if |
| the program is not found) by using the source file search path |
| (@pxref{Source Path, ,Specifying Source Directories}). You can also use |
| the @code{file} command to load the program. @xref{Files, ,Commands to |
| Specify Files}. |
| |
| @anchor{set exec-file-mismatch} |
| If the debugger can determine that the executable file running in the |
| process it is attaching to does not match the current exec-file loaded |
| by @value{GDBN}, the option @code{exec-file-mismatch} specifies how to |
| handle the mismatch. @value{GDBN} tries to compare the files by |
| comparing their build IDs (@pxref{build ID}), if available. |
| |
| @table @code |
| @kindex exec-file-mismatch |
| @cindex set exec-file-mismatch |
| @item set exec-file-mismatch @samp{ask|warn|off} |
| |
| Whether to detect mismatch between the current executable file loaded |
| by @value{GDBN} and the executable file used to start the process. If |
| @samp{ask}, the default, display a warning and ask the user whether to |
| load the process executable file; if @samp{warn}, just display a |
| warning; if @samp{off}, don't attempt to detect a mismatch. |
| If the user confirms loading the process executable file, then its symbols |
| will be loaded as well. |
| |
| @cindex show exec-file-mismatch |
| @item show exec-file-mismatch |
| Show the current value of @code{exec-file-mismatch}. |
| |
| @end table |
| |
| The first thing @value{GDBN} does after arranging to debug the specified |
| process is to stop it. You can examine and modify an attached process |
| with all the @value{GDBN} commands that are ordinarily available when |
| you start processes with @code{run}. You can insert breakpoints; you |
| can step and continue; you can modify storage. If you would rather the |
| process continue running, you may use the @code{continue} command after |
| attaching @value{GDBN} to the process. |
| |
| @table @code |
| @kindex detach |
| @item detach |
| When you have finished debugging the attached process, you can use the |
| @code{detach} command to release it from @value{GDBN} control. Detaching |
| the process continues its execution. After the @code{detach} command, |
| that process and @value{GDBN} become completely independent once more, and you |
| are ready to @code{attach} another process or start one with @code{run}. |
| @code{detach} does not repeat if you press @key{RET} again after |
| executing the command. |
| @end table |
| |
| If you exit @value{GDBN} while you have an attached process, you detach |
| that process. If you use the @code{run} command, you kill that process. |
| By default, @value{GDBN} asks for confirmation if you try to do either of these |
| things; you can control whether or not you need to confirm by using the |
| @code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and |
| Messages}). |
| |
| @node Kill Process |
| @section Killing the Child Process |
| |
| @table @code |
| @kindex kill |
| @item kill |
| Kill the child process in which your program is running under @value{GDBN}. |
| @end table |
| |
| This command is useful if you wish to debug a core dump instead of a |
| running process. @value{GDBN} ignores any core dump file while your program |
| is running. |
| |
| On some operating systems, a program cannot be executed outside @value{GDBN} |
| while you have breakpoints set on it inside @value{GDBN}. You can use the |
| @code{kill} command in this situation to permit running your program |
| outside the debugger. |
| |
| The @code{kill} command is also useful if you wish to recompile and |
| relink your program, since on many systems it is impossible to modify an |
| executable file while it is running in a process. In this case, when you |
| next type @code{run}, @value{GDBN} notices that the file has changed, and |
| reads the symbol table again (while trying to preserve your current |
| breakpoint settings). |
| |
| @node Inferiors Connections and Programs |
| @section Debugging Multiple Inferiors Connections and Programs |
| |
| @value{GDBN} lets you run and debug multiple programs in a single |
| session. In addition, @value{GDBN} on some systems may let you run |
| several programs simultaneously (otherwise you have to exit from one |
| before starting another). On some systems @value{GDBN} may even let |
| you debug several programs simultaneously on different remote systems. |
| In the most general case, you can have multiple threads of execution |
| in each of multiple processes, launched from multiple executables, |
| running on different machines. |
| |
| @cindex inferior |
| @value{GDBN} represents the state of each program execution with an |
| object called an @dfn{inferior}. An inferior typically corresponds to |
| a process, but is more general and applies also to targets that do not |
| have processes. Inferiors may be created before a process runs, and |
| may be retained after a process exits. Inferiors have unique |
| identifiers that are different from process ids. Usually each |
| inferior will also have its own distinct address space, although some |
| embedded targets may have several inferiors running in different parts |
| of a single address space. Each inferior may in turn have multiple |
| threads running in it. |
| |
| To find out what inferiors exist at any moment, use @w{@code{info |
| inferiors}}: |
| |
| @table @code |
| @kindex info inferiors [ @var{id}@dots{} ] |
| @item info inferiors |
| Print a list of all inferiors currently being managed by @value{GDBN}. |
| By default all inferiors are printed, but the argument @var{id}@dots{} |
| -- a space separated list of inferior numbers -- can be used to limit |
| the display to just the requested inferiors. |
| |
| @value{GDBN} displays for each inferior (in this order): |
| |
| @enumerate |
| @item |
| the inferior number assigned by @value{GDBN} |
| |
| @item |
| the target system's inferior identifier |
| |
| @item |
| the target connection the inferior is bound to, including the unique |
| connection number assigned by @value{GDBN}, and the protocol used by |
| the connection. |
| |
| @item |
| the name of the executable the inferior is running. |
| |
| @end enumerate |
| |
| @noindent |
| An asterisk @samp{*} preceding the @value{GDBN} inferior number |
| indicates the current inferior. |
| |
| For example, |
| @end table |
| @c end table here to get a little more width for example |
| |
| @smallexample |
| (@value{GDBP}) info inferiors |
| Num Description Connection Executable |
| * 1 process 3401 1 (native) goodbye |
| 2 process 2307 2 (extended-remote host:10000) hello |
| @end smallexample |
| |
| To get informations about the current inferior, use @code{inferior}: |
| |
| @table @code |
| @kindex inferior |
| @item inferior |
| Shows information about the current inferior. |
| |
| For example, |
| @end table |
| @c end table here to get a little more width for example |
| |
| @smallexample |
| (@value{GDBP}) inferior |
| [Current inferior is 1 [process 3401] (helloworld)] |
| @end smallexample |
| |
| To find out what open target connections exist at any moment, use |
| @w{@code{info connections}}: |
| |
| @table @code |
| @kindex info connections [ @var{id}@dots{} ] |
| @item info connections |
| Print a list of all open target connections currently being managed by |
| @value{GDBN}. By default all connections are printed, but the |
| argument @var{id}@dots{} -- a space separated list of connections |
| numbers -- can be used to limit the display to just the requested |
| connections. |
| |
| @value{GDBN} displays for each connection (in this order): |
| |
| @enumerate |
| @item |
| the connection number assigned by @value{GDBN}. |
| |
| @item |
| the protocol used by the connection. |
| |
| @item |
| a textual description of the protocol used by the connection. |
| |
| @end enumerate |
| |
| @noindent |
| An asterisk @samp{*} preceding the connection number indicates the |
| connection of the current inferior. |
| |
| For example, |
| @end table |
| @c end table here to get a little more width for example |
| |
| @smallexample |
| (@value{GDBP}) info connections |
| Num What Description |
| * 1 extended-remote host:10000 Extended remote serial target in gdb-specific protocol |
| 2 native Native process |
| 3 core Local core dump file |
| @end smallexample |
| |
| To switch focus between inferiors, use the @code{inferior} command: |
| |
| @table @code |
| @kindex inferior @var{infno} |
| @item inferior @var{infno} |
| Make inferior number @var{infno} the current inferior. The argument |
| @var{infno} is the inferior number assigned by @value{GDBN}, as shown |
| in the first field of the @samp{info inferiors} display. |
| @end table |
| |
| @vindex $_inferior@r{, convenience variable} |
| The debugger convenience variable @samp{$_inferior} contains the |
| number of the current inferior. You may find this useful in writing |
| breakpoint conditional expressions, command scripts, and so forth. |
| @xref{Convenience Vars,, Convenience Variables}, for general |
| information on convenience variables. |
| |
| You can get multiple executables into a debugging session via the |
| @code{add-inferior} and @w{@code{clone-inferior}} commands. On some |
| systems @value{GDBN} can add inferiors to the debug session |
| automatically by following calls to @code{fork} and @code{exec}. To |
| remove inferiors from the debugging session use the |
| @w{@code{remove-inferiors}} command. |
| |
| @table @code |
| @kindex add-inferior |
| @item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ] [-no-connection ] |
| Adds @var{n} inferiors to be run using @var{executable} as the |
| executable; @var{n} defaults to 1. If no executable is specified, |
| the inferiors begins empty, with no program. You can still assign or |
| change the program assigned to the inferior at any time by using the |
| @code{file} command with the executable name as its argument. |
| |
| By default, the new inferior begins connected to the same target |
| connection as the current inferior. For example, if the current |
| inferior was connected to @code{gdbserver} with @code{target remote}, |
| then the new inferior will be connected to the same @code{gdbserver} |
| instance. The @samp{-no-connection} option starts the new inferior |
| with no connection yet. You can then for example use the @code{target |
| remote} command to connect to some other @code{gdbserver} instance, |
| use @code{run} to spawn a local program, etc. |
| |
| @kindex clone-inferior |
| @item clone-inferior [ -copies @var{n} ] [ @var{infno} ] |
| Adds @var{n} inferiors ready to execute the same program as inferior |
| @var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the |
| number of the current inferior. This is a convenient command when you |
| want to run another instance of the inferior you are debugging. |
| |
| @smallexample |
| (@value{GDBP}) info inferiors |
| Num Description Connection Executable |
| * 1 process 29964 1 (native) helloworld |
| (@value{GDBP}) clone-inferior |
| Added inferior 2. |
| 1 inferiors added. |
| (@value{GDBP}) info inferiors |
| Num Description Connection Executable |
| * 1 process 29964 1 (native) helloworld |
| 2 <null> 1 (native) helloworld |
| @end smallexample |
| |
| You can now simply switch focus to inferior 2 and run it. |
| |
| @kindex remove-inferiors |
| @item remove-inferiors @var{infno}@dots{} |
| Removes the inferior or inferiors @var{infno}@dots{}. It is not |
| possible to remove an inferior that is running with this command. For |
| those, use the @code{kill} or @code{detach} command first. |
| |
| @end table |
| |
| To quit debugging one of the running inferiors that is not the current |
| inferior, you can either detach from it by using the @w{@code{detach |
| inferior}} command (allowing it to run independently), or kill it |
| using the @w{@code{kill inferiors}} command: |
| |
| @table @code |
| @kindex detach inferiors @var{infno}@dots{} |
| @item detach inferior @var{infno}@dots{} |
| Detach from the inferior or inferiors identified by @value{GDBN} |
| inferior number(s) @var{infno}@dots{}. Note that the inferior's entry |
| still stays on the list of inferiors shown by @code{info inferiors}, |
| but its Description will show @samp{<null>}. |
| |
| @kindex kill inferiors @var{infno}@dots{} |
| @item kill inferiors @var{infno}@dots{} |
| Kill the inferior or inferiors identified by @value{GDBN} inferior |
| number(s) @var{infno}@dots{}. Note that the inferior's entry still |
| stays on the list of inferiors shown by @code{info inferiors}, but its |
| Description will show @samp{<null>}. |
| @end table |
| |
| After the successful completion of a command such as @code{detach}, |
| @code{detach inferiors}, @code{kill} or @code{kill inferiors}, or after |
| a normal process exit, the inferior is still valid and listed with |
| @code{info inferiors}, ready to be restarted. |
| |
| |
| To be notified when inferiors are started or exit under @value{GDBN}'s |
| control use @w{@code{set print inferior-events}}: |
| |
| @table @code |
| @kindex set print inferior-events |
| @cindex print messages on inferior start and exit |
| @item set print inferior-events |
| @itemx set print inferior-events on |
| @itemx set print inferior-events off |
| The @code{set print inferior-events} command allows you to enable or |
| disable printing of messages when @value{GDBN} notices that new |
| inferiors have started or that inferiors have exited or have been |
| detached. By default, these messages will not be printed. |
| |
| @kindex show print inferior-events |
| @item show print inferior-events |
| Show whether messages will be printed when @value{GDBN} detects that |
| inferiors have started, exited or have been detached. |
| @end table |
| |
| Many commands will work the same with multiple programs as with a |
| single program: e.g., @code{print myglobal} will simply display the |
| value of @code{myglobal} in the current inferior. |
| |
| |
| Occasionally, when debugging @value{GDBN} itself, it may be useful to |
| get more info about the relationship of inferiors, programs, address |
| spaces in a debug session. You can do that with the @w{@code{maint |
| info program-spaces}} command. |
| |
| @table @code |
| @kindex maint info program-spaces |
| @item maint info program-spaces |
| Print a list of all program spaces currently being managed by |
| @value{GDBN}. |
| |
| @value{GDBN} displays for each program space (in this order): |
| |
| @enumerate |
| @item |
| the program space number assigned by @value{GDBN} |
| |
| @item |
| the name of the executable loaded into the program space, with e.g., |
| the @code{file} command. |
| |
| @end enumerate |
| |
| @noindent |
| An asterisk @samp{*} preceding the @value{GDBN} program space number |
| indicates the current program space. |
| |
| In addition, below each program space line, @value{GDBN} prints extra |
| information that isn't suitable to display in tabular form. For |
| example, the list of inferiors bound to the program space. |
| |
| @smallexample |
| (@value{GDBP}) maint info program-spaces |
| Id Executable |
| * 1 hello |
| 2 goodbye |
| Bound inferiors: ID 1 (process 21561) |
| @end smallexample |
| |
| Here we can see that no inferior is running the program @code{hello}, |
| while @code{process 21561} is running the program @code{goodbye}. On |
| some targets, it is possible that multiple inferiors are bound to the |
| same program space. The most common example is that of debugging both |
| the parent and child processes of a @code{vfork} call. For example, |
| |
| @smallexample |
| (@value{GDBP}) maint info program-spaces |
| Id Executable |
| * 1 vfork-test |
| Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) |
| @end smallexample |
| |
| Here, both inferior 2 and inferior 1 are running in the same program |
| space as a result of inferior 1 having executed a @code{vfork} call. |
| @end table |
| |
| @node Threads |
| @section Debugging Programs with Multiple Threads |
| |
| @cindex threads of execution |
| @cindex multiple threads |
| @cindex switching threads |
| In some operating systems, such as GNU/Linux and Solaris, a single program |
| may have more than one @dfn{thread} of execution. The precise semantics |
| of threads differ from one operating system to another, but in general |
| the threads of a single program are akin to multiple processes---except |
| that they share one address space (that is, they can all examine and |
| modify the same variables). On the other hand, each thread has its own |
| registers and execution stack, and perhaps private memory. |
| |
| @value{GDBN} provides these facilities for debugging multi-thread |
| programs: |
| |
| @itemize @bullet |
| @item automatic notification of new threads |
| @item @samp{thread @var{thread-id}}, a command to switch among threads |
| @item @samp{info threads}, a command to inquire about existing threads |
| @item @samp{thread apply [@var{thread-id-list} | all] @var{args}}, |
| a command to apply a command to a list of threads |
| @item thread-specific breakpoints |
| @item @samp{set print thread-events}, which controls printing of |
| messages on thread start and exit. |
| @item @samp{set libthread-db-search-path @var{path}}, which lets |
| the user specify which @code{libthread_db} to use if the default choice |
| isn't compatible with the program. |
| @end itemize |
| |
| @cindex focus of debugging |
| @cindex current thread |
| The @value{GDBN} thread debugging facility allows you to observe all |
| threads while your program runs---but whenever @value{GDBN} takes |
| control, one thread in particular is always the focus of debugging. |
| This thread is called the @dfn{current thread}. Debugging commands show |
| program information from the perspective of the current thread. |
| |
| @cindex @code{New} @var{systag} message |
| @cindex thread identifier (system) |
| @c FIXME-implementors!! It would be more helpful if the [New...] message |
| @c included GDB's numeric thread handle, so you could just go to that |
| @c thread without first checking `info threads'. |
| Whenever @value{GDBN} detects a new thread in your program, it displays |
| the target system's identification for the thread with a message in the |
| form @samp{[New @var{systag}]}, where @var{systag} is a thread identifier |
| whose form varies depending on the particular system. For example, on |
| @sc{gnu}/Linux, you might see |
| |
| @smallexample |
| [New Thread 0x41e02940 (LWP 25582)] |
| @end smallexample |
| |
| @noindent |
| when @value{GDBN} notices a new thread. In contrast, on other systems, |
| the @var{systag} is simply something like @samp{process 368}, with no |
| further qualifier. |
| |
| @c FIXME!! (1) Does the [New...] message appear even for the very first |
| @c thread of a program, or does it only appear for the |
| @c second---i.e.@: when it becomes obvious we have a multithread |
| @c program? |
| @c (2) *Is* there necessarily a first thread always? Or do some |
| @c multithread systems permit starting a program with multiple |
| @c threads ab initio? |
| |
| @anchor{thread numbers} |
| @cindex thread number, per inferior |
| @cindex thread identifier (GDB) |
| For debugging purposes, @value{GDBN} associates its own thread number |
| ---always a single integer---with each thread of an inferior. This |
| number is unique between all threads of an inferior, but not unique |
| between threads of different inferiors. |
| |
| @cindex qualified thread ID |
| You can refer to a given thread in an inferior using the qualified |
| @var{inferior-num}.@var{thread-num} syntax, also known as |
| @dfn{qualified thread ID}, with @var{inferior-num} being the inferior |
| number and @var{thread-num} being the thread number of the given |
| inferior. For example, thread @code{2.3} refers to thread number 3 of |
| inferior 2. If you omit @var{inferior-num} (e.g., @code{thread 3}), |
| then @value{GDBN} infers you're referring to a thread of the current |
| inferior. |
| |
| Until you create a second inferior, @value{GDBN} does not show the |
| @var{inferior-num} part of thread IDs, even though you can always use |
| the full @var{inferior-num}.@var{thread-num} form to refer to threads |
| of inferior 1, the initial inferior. |
| |
| @anchor{thread ID lists} |
| @cindex thread ID lists |
| Some commands accept a space-separated @dfn{thread ID list} as |
| argument. A list element can be: |
| |
| @enumerate |
| @item |
| A thread ID as shown in the first field of the @samp{info threads} |
| display, with or without an inferior qualifier. E.g., @samp{2.1} or |
| @samp{1}. |
| |
| @item |
| A range of thread numbers, again with or without an inferior |
| qualifier, as in @var{inf}.@var{thr1}-@var{thr2} or |
| @var{thr1}-@var{thr2}. E.g., @samp{1.2-4} or @samp{2-4}. |
| |
| @item |
| All threads of an inferior, specified with a star wildcard, with or |
| without an inferior qualifier, as in @var{inf}.@code{*} (e.g., |
| @samp{1.*}) or @code{*}. The former refers to all threads of the |
| given inferior, and the latter form without an inferior qualifier |
| refers to all threads of the current inferior. |
| |
| @end enumerate |
| |
| For example, if the current inferior is 1, and inferior 7 has one |
| thread with ID 7.1, the thread list @samp{1 2-3 4.5 6.7-9 7.*} |
| includes threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads |
| 7 to 9 of inferior 6 and all threads of inferior 7. That is, in |
| expanded qualified form, the same as @samp{1.1 1.2 1.3 4.5 6.7 6.8 6.9 |
| 7.1}. |
| |
| |
| @anchor{global thread numbers} |
| @cindex global thread number |
| @cindex global thread identifier (GDB) |
| In addition to a @emph{per-inferior} number, each thread is also |
| assigned a unique @emph{global} number, also known as @dfn{global |
| thread ID}, a single integer. Unlike the thread number component of |
| the thread ID, no two threads have the same global ID, even when |
| you're debugging multiple inferiors. |
| |
| From @value{GDBN}'s perspective, a process always has at least one |
| thread. In other words, @value{GDBN} assigns a thread number to the |
| program's ``main thread'' even if the program is not multi-threaded. |
| |
| @vindex $_thread@r{, convenience variable} |
| @vindex $_gthread@r{, convenience variable} |
| The debugger convenience variables @samp{$_thread} and |
| @samp{$_gthread} contain, respectively, the per-inferior thread number |
| and the global thread number of the current thread. You may find this |
| useful in writing breakpoint conditional expressions, command scripts, |
| and so forth. @xref{Convenience Vars,, Convenience Variables}, for |
| general information on convenience variables. |
| |
| If @value{GDBN} detects the program is multi-threaded, it augments the |
| usual message about stopping at a breakpoint with the ID and name of |
| the thread that hit the breakpoint. |
| |
| @smallexample |
| Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68 |
| @end smallexample |
| |
| Likewise when the program receives a signal: |
| |
| @smallexample |
| Thread 1 "main" received signal SIGINT, Interrupt. |
| @end smallexample |
| |
| @table @code |
| @kindex info threads |
| @item info threads @r{[}@var{thread-id-list}@r{]} |
| |
| Display information about one or more threads. With no arguments |
| displays information about all threads. You can specify the list of |
| threads that you want to display using the thread ID list syntax |
| (@pxref{thread ID lists}). |
| |
| @value{GDBN} displays for each thread (in this order): |
| |
| @enumerate |
| @item |
| the per-inferior thread number assigned by @value{GDBN} |
| |
| @item |
| the global thread number assigned by @value{GDBN}, if the @samp{-gid} |
| option was specified |
| |
| @item |
| the target system's thread identifier (@var{systag}) |
| |
| @item |
| the thread's name, if one is known. A thread can either be named by |
| the user (see @code{thread name}, below), or, in some cases, by the |
| program itself. |
| |
| @item |
| the current stack frame summary for that thread |
| @end enumerate |
| |
| @noindent |
| An asterisk @samp{*} to the left of the @value{GDBN} thread number |
| indicates the current thread. |
| |
| For example, |
| @end table |
| @c end table here to get a little more width for example |
| |
| @smallexample |
| (@value{GDBP}) info threads |
| Id Target Id Frame |
| * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) |
| 2 process 35 thread 23 0x34e5 in sigpause () |
| 3 process 35 thread 27 0x34e5 in sigpause () |
| at threadtest.c:68 |
| @end smallexample |
| |
| If you're debugging multiple inferiors, @value{GDBN} displays thread |
| IDs using the qualified @var{inferior-num}.@var{thread-num} format. |
| Otherwise, only @var{thread-num} is shown. |
| |
| If you specify the @samp{-gid} option, @value{GDBN} displays a column |
| indicating each thread's global thread ID: |
| |
| @smallexample |
| (@value{GDBP}) info threads |
| Id GId Target Id Frame |
| 1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) |
| 1.2 3 process 35 thread 23 0x34e5 in sigpause () |
| 1.3 4 process 35 thread 27 0x34e5 in sigpause () |
| * 2.1 2 process 65 thread 1 main (argc=1, argv=0x7ffffff8) |
| @end smallexample |
| |
| On Solaris, you can display more information about user threads with a |
| Solaris-specific command: |
| |
| @table @code |
| @item maint info sol-threads |
| @kindex maint info sol-threads |
| @cindex thread info (Solaris) |
| Display info on Solaris user threads. |
| @end table |
| |
| @table @code |
| @kindex thread @var{thread-id} |
| @item thread @var{thread-id} |
| Make thread ID @var{thread-id} the current thread. The command |
| argument @var{thread-id} is the @value{GDBN} thread ID, as shown in |
| the first field of the @samp{info threads} display, with or without an |
| inferior qualifier (e.g., @samp{2.1} or @samp{1}). |
| |
| @value{GDBN} responds by displaying the system identifier of the |
| thread you selected, and its current stack frame summary: |
| |
| @smallexample |
| (@value{GDBP}) thread 2 |
| [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] |
| #0 some_function (ignore=0x0) at example.c:8 |
| 8 printf ("hello\n"); |
| @end smallexample |
| |
| @noindent |
| As with the @samp{[New @dots{}]} message, the form of the text after |
| @samp{Switching to} depends on your system's conventions for identifying |
| threads. |
| |
| @anchor{thread apply all} |
| @kindex thread apply |
| @cindex apply command to several threads |
| @item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command} |
| The @code{thread apply} command allows you to apply the named |
| @var{command} to one or more threads. Specify the threads that you |
| want affected using the thread ID list syntax (@pxref{thread ID |
| lists}), or specify @code{all} to apply to all threads. To apply a |
| command to all threads in descending order, type @kbd{thread apply all |
| @var{command}}. To apply a command to all threads in ascending order, |
| type @kbd{thread apply all -ascending @var{command}}. |
| |
| The @var{flag} arguments control what output to produce and how to handle |
| errors raised when applying @var{command} to a thread. @var{flag} |
| must start with a @code{-} directly followed by one letter in |
| @code{qcs}. If several flags are provided, they must be given |
| individually, such as @code{-c -q}. |
| |
| By default, @value{GDBN} displays some thread information before the |
| output produced by @var{command}, and an error raised during the |
| execution of a @var{command} will abort @code{thread apply}. The |
| following flags can be used to fine-tune this behavior: |
| |
| @table @code |
| @item -c |
| The flag @code{-c}, which stands for @samp{continue}, causes any |
| errors in @var{command} to be displayed, and the execution of |
| @code{thread apply} then continues. |
| @item -s |
| The flag @code{-s}, which stands for @samp{silent}, causes any errors |
| or empty output produced by a @var{command} to be silently ignored. |
| That is, the execution continues, but the thread information and errors |
| are not printed. |
| @item -q |
| The flag @code{-q} (@samp{quiet}) disables printing the thread |
| information. |
| @end table |
| |
| Flags @code{-c} and @code{-s} cannot be used together. |
| |
| @kindex taas |
| @cindex apply command to all threads (ignoring errors and empty output) |
| @item taas [@var{option}]@dots{} @var{command} |
| Shortcut for @code{thread apply all -s [@var{option}]@dots{} @var{command}}. |
| Applies @var{command} on all threads, ignoring errors and empty output. |
| |
| The @code{taas} command accepts the same options as the @code{thread |
| apply all} command. @xref{thread apply all}. |
| |
| @kindex tfaas |
| @cindex apply a command to all frames of all threads (ignoring errors and empty output) |
| @item tfaas [@var{option}]@dots{} @var{command} |
| Shortcut for @code{thread apply all -s -- frame apply all -s [@var{option}]@dots{} @var{command}}. |
| Applies @var{command} on all frames of all threads, ignoring errors |
| and empty output. Note that the flag @code{-s} is specified twice: |
| The first @code{-s} ensures that @code{thread apply} only shows the thread |
| information of the threads for which @code{frame apply} produces |
| some output. The second @code{-s} is needed to ensure that @code{frame |
| apply} shows the frame information of a frame only if the |
| @var{command} successfully produced some output. |
| |
| It can for example be used to print a local variable or a function |
| argument without knowing the thread or frame where this variable or argument |
| is, using: |
| @smallexample |
| (@value{GDBP}) tfaas p some_local_var_i_do_not_remember_where_it_is |
| @end smallexample |
| |
| The @code{tfaas} command accepts the same options as the @code{frame |
| apply} command. @xref{Frame Apply,,frame apply}. |
| |
| @kindex thread name |
| @cindex name a thread |
| @item thread name [@var{name}] |
| This command assigns a name to the current thread. If no argument is |
| given, any existing user-specified name is removed. The thread name |
| appears in the @samp{info threads} display. |
| |
| On some systems, such as @sc{gnu}/Linux, @value{GDBN} is able to |
| determine the name of the thread as given by the OS. On these |
| systems, a name specified with @samp{thread name} will override the |
| system-give name, and removing the user-specified name will cause |
| @value{GDBN} to once again display the system-specified name. |
| |
| @kindex thread find |
| @cindex search for a thread |
| @item thread find [@var{regexp}] |
| Search for and display thread ids whose name or @var{systag} |
| matches the supplied regular expression. |
| |
| As well as being the complement to the @samp{thread name} command, |
| this command also allows you to identify a thread by its target |
| @var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag} |
| is the LWP id. |
| |
| @smallexample |
| (@value{GDBN}) thread find 26688 |
| Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' |
| (@value{GDBN}) info thread 4 |
| Id Target Id Frame |
| 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () |
| @end smallexample |
| |
| @kindex set print thread-events |
| @cindex print messages on thread start and exit |
| @item set print thread-events |
| @itemx set print thread-events on |
| @itemx set print thread-events off |
| The @code{set print thread-events} command allows you to enable or |
| disable printing of messages when @value{GDBN} notices that new threads have |
| started or that threads have exited. By default, these messages will |
| be printed if detection of these events is supported by the target. |
| Note that these messages cannot be disabled on all targets. |
| |
| @kindex show print thread-events |
| @item show print thread-events |
| Show whether messages will be printed when @value{GDBN} detects that threads |
| have started and exited. |
| @end table |
| |
| @xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for |
| more information about how @value{GDBN} behaves when you stop and start |
| programs with multiple threads. |
| |
| @xref{Set Watchpoints,,Setting Watchpoints}, for information about |
| watchpoints in programs with multiple threads. |
| |
| @anchor{set libthread-db-search-path} |
| @table @code |
| @kindex set libthread-db-search-path |
| @cindex search path for @code{libthread_db} |
| @item set libthread-db-search-path @r{[}@var{path}@r{]} |
| If this variable is set, @var{path} is a colon-separated list of |
| directories @value{GDBN} will use to search for @code{libthread_db}. |
| If you omit @var{path}, @samp{libthread-db-search-path} will be reset to |
| its default value (@code{$sdir:$pdir} on @sc{gnu}/Linux and Solaris systems). |
| Internally, the default value comes from the @code{LIBTHREAD_DB_SEARCH_PATH} |
| macro. |
| |
| On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper'' |
| @code{libthread_db} library to obtain information about threads in the |
| inferior process. @value{GDBN} will use @samp{libthread-db-search-path} |
| to find @code{libthread_db}. @value{GDBN} also consults first if inferior |
| specific thread debugging library loading is enabled |
| by @samp{set auto-load libthread-db} (@pxref{libthread_db.so.1 file}). |
| |
| A special entry @samp{$sdir} for @samp{libthread-db-search-path} |
| refers to the default system directories that are |
| normally searched for loading shared libraries. The @samp{$sdir} entry |
| is the only kind not needing to be enabled by @samp{set auto-load libthread-db} |
| (@pxref{libthread_db.so.1 file}). |
| |
| A special entry @samp{$pdir} for @samp{libthread-db-search-path} |
| refers to the directory from which @code{libpthread} |
| was loaded in the inferior process. |
| |
| For any @code{libthread_db} library @value{GDBN} finds in above directories, |
| @value{GDBN} attempts to initialize it with the current inferior process. |
| If this initialization fails (which could happen because of a version |
| mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN} |
| will unload @code{libthread_db}, and continue with the next directory. |
| If none of @code{libthread_db} libraries initialize successfully, |
| @value{GDBN} will issue a warning and thread debugging will be disabled. |
| |
| Setting @code{libthread-db-search-path} is currently implemented |
| only on some platforms. |
| |
| @kindex show libthread-db-search-path |
| @item show libthread-db-search-path |
| Display current libthread_db search path. |
| |
| @kindex set debug libthread-db |
| @kindex show debug libthread-db |
| @cindex debugging @code{libthread_db} |
| @item set debug libthread-db |
| @itemx show debug libthread-db |
| Turns on or off display of @code{libthread_db}-related events. |
| Use @code{1} to enable, @code{0} to disable. |
| @end table |
| |
| @node Forks |
| @section Debugging Forks |
| |
| @cindex fork, debugging programs which call |
| @cindex multiple processes |
| @cindex processes, multiple |
| On most systems, @value{GDBN} has no special support for debugging |
| programs which create additional processes using the @code{fork} |
| function. When a program forks, @value{GDBN} will continue to debug the |
| parent process and the child process will run unimpeded. If you have |
| set a breakpoint in any code which the child then executes, the child |
| will get a @code{SIGTRAP} signal which (unless it catches the signal) |
| will cause it to terminate. |
| |
| However, if you want to debug the child process there is a workaround |
| which isn't too painful. Put a call to @code{sleep} in the code which |
| the child process executes after the fork. It may be useful to sleep |
| only if a certain environment variable is set, or a certain file exists, |
| so that the delay need not occur when you don't want to run @value{GDBN} |
| on the child. While the child is sleeping, use the @code{ps} program to |
| get its process ID. Then tell @value{GDBN} (a new invocation of |
| @value{GDBN} if you are also debugging the parent process) to attach to |
| the child process (@pxref{Attach}). From that point on you can debug |
| the child process just like any other process which you attached to. |
| |
| On some systems, @value{GDBN} provides support for debugging programs |
| that create additional processes using the @code{fork} or @code{vfork} |
| functions. On @sc{gnu}/Linux platforms, this feature is supported |
| with kernel version 2.5.46 and later. |
| |
| The fork debugging commands are supported in native mode and when |
| connected to @code{gdbserver} in either @code{target remote} mode or |
| @code{target extended-remote} mode. |
| |
| By default, when a program forks, @value{GDBN} will continue to debug |
| the parent process and the child process will run unimpeded. |
| |
| If you want to follow the child process instead of the parent process, |
| use the command @w{@code{set follow-fork-mode}}. |
| |
| @table @code |
| @kindex set follow-fork-mode |
| @item set follow-fork-mode @var{mode} |
| Set the debugger response to a program call of @code{fork} or |
| @code{vfork}. A call to @code{fork} or @code{vfork} creates a new |
| process. The @var{mode} argument can be: |
| |
| @table @code |
| @item parent |
| The original process is debugged after a fork. The child process runs |
| unimpeded. This is the default. |
| |
| @item child |
| The new process is debugged after a fork. The parent process runs |
| unimpeded. |
| |
| @end table |
| |
| @kindex show follow-fork-mode |
| @item show follow-fork-mode |
| Display the current debugger response to a @code{fork} or @code{vfork} call. |
| @end table |
| |
| @cindex debugging multiple processes |
| On Linux, if you want to debug both the parent and child processes, use the |
| command @w{@code{set detach-on-fork}}. |
| |
| @table @code |
| @kindex set detach-on-fork |
| @item set detach-on-fork @var{mode} |
| Tells gdb whether to detach one of the processes after a fork, or |
| retain debugger control over them both. |
| |
| @table @code |
| @item on |
| The child process (or parent process, depending on the value of |
| @code{follow-fork-mode}) will be detached and allowed to run |
| independently. This is the default. |
| |
| @item off |
| Both processes will be held under the control of @value{GDBN}. |
| One process (child or parent, depending on the value of |
| @code{follow-fork-mode}) is debugged as usual, while the other |
| is held suspended. |
| |
| @end table |
| |
| @kindex show detach-on-fork |
| @item show detach-on-fork |
| Show whether detach-on-fork mode is on/off. |
| @end table |
| |
| If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN} |
| will retain control of all forked processes (including nested forks). |
| You can list the forked processes under the control of @value{GDBN} by |
| using the @w{@code{info inferiors}} command, and switch from one fork |
| to another by using the @code{inferior} command (@pxref{Inferiors Connections and |
| Programs, ,Debugging Multiple Inferiors Connections and Programs}). |
| |
| To quit debugging one of the forked processes, you can either detach |
| from it by using the @w{@code{detach inferiors}} command (allowing it |
| to run independently), or kill it using the @w{@code{kill inferiors}} |
| command. @xref{Inferiors Connections and Programs, ,Debugging |
| Multiple Inferiors Connections and Programs}. |
| |
| If you ask to debug a child process and a @code{vfork} is followed by an |
| @code{exec}, @value{GDBN} executes the new target up to the first |
| breakpoint in the new target. If you have a breakpoint set on |
| @code{main} in your original program, the breakpoint will also be set on |
| the child process's @code{main}. |
| |
| On some systems, when a child process is spawned by @code{vfork}, you |
| cannot debug the child or parent until an @code{exec} call completes. |
| |
| If you issue a @code{run} command to @value{GDBN} after an @code{exec} |
| call executes, the new target restarts. To restart the parent |
| process, use the @code{file} command with the parent executable name |
| as its argument. By default, after an @code{exec} call executes, |
| @value{GDBN} discards the symbols of the previous executable image. |
| You can change this behaviour with the @w{@code{set follow-exec-mode}} |
| command. |
| |
| @table @code |
| @kindex set follow-exec-mode |
| @item set follow-exec-mode @var{mode} |
| |
| Set debugger response to a program call of @code{exec}. An |
| @code{exec} call replaces the program image of a process. |
| |
| @code{follow-exec-mode} can be: |
| |
| @table @code |
| @item new |
| @value{GDBN} creates a new inferior and rebinds the process to this |
| new inferior. The program the process was running before the |
| @code{exec} call can be restarted afterwards by restarting the |
| original inferior. |
| |
| For example: |
| |
| @smallexample |
| (@value{GDBP}) info inferiors |
| (gdb) info inferior |
| Id Description Executable |
| * 1 <null> prog1 |
| (@value{GDBP}) run |
| process 12020 is executing new program: prog2 |
| Program exited normally. |
| (@value{GDBP}) info inferiors |
| Id Description Executable |
| 1 <null> prog1 |
| * 2 <null> prog2 |
| @end smallexample |
| |
| @item same |
| @value{GDBN} keeps the process bound to the same inferior. The new |
| executable image replaces the previous executable loaded in the |
| inferior. Restarting the inferior after the @code{exec} call, with |
| e.g., the @code{run} command, restarts the executable the process was |
| running after the @code{exec} call. This is the default mode. |
| |
| For example: |
| |
| @smallexample |
| (@value{GDBP}) info inferiors |
| Id Description Executable |
| * 1 <null> prog1 |
| (@value{GDBP}) run |
| process 12020 is executing new program: prog2 |
| Program exited normally. |
| (@value{GDBP}) info inferiors |
| Id Description Executable |
| * 1 <null> prog2 |
| @end smallexample |
| |
| @end table |
| @end table |
| |
| @code{follow-exec-mode} is supported in native mode and |
| @code{target extended-remote} mode. |
| |
| You can use the @code{catch} command to make @value{GDBN} stop whenever |
| a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set |
| Catchpoints, ,Setting Catchpoints}. |
| |
| @node Checkpoint/Restart |
| @section Setting a @emph{Bookmark} to Return to Later |
| |
| @cindex checkpoint |
| @cindex restart |
| @cindex bookmark |
| @cindex snapshot of a process |
| @cindex rewind program state |
| |
| On certain operating systems@footnote{Currently, only |
| @sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a |
| program's state, called a @dfn{checkpoint}, and come back to it |
| later. |
| |
| Returning to a checkpoint effectively undoes everything that has |
| happened in the program since the @code{checkpoint} was saved. This |
| includes changes in memory, registers, and even (within some limits) |
| system state. Effectively, it is like going back in time to the |
| moment when the checkpoint was saved. |
| |
| Thus, if you're stepping thru a program and you think you're |
| getting close to the point where things go wrong, you can save |
| a checkpoint. Then, if you accidentally go too far and miss |
| the critical statement, instead of having to restart your program |
| from the beginning, you can just go back to the checkpoint and |
| start again from there. |
| |
| This can be especially useful if it takes a lot of time or |
| steps to reach the point where you think the bug occurs. |
| |
| To use the @code{checkpoint}/@code{restart} method of debugging: |
| |
| @table @code |
| @kindex checkpoint |
| @item checkpoint |
| Save a snapshot of the debugged program's current execution state. |
| The @code{checkpoint} command takes no arguments, but each checkpoint |
| is assigned a small integer id, similar to a breakpoint id. |
| |
| @kindex info checkpoints |
| @item info checkpoints |
| List the checkpoints that have been saved in the current debugging |
| session. For each checkpoint, the following information will be |
| listed: |
| |
| @table @code |
| @item Checkpoint ID |
| @item Process ID |
| @item Code Address |
| @item Source line, or label |
| @end table |
| |
| @kindex restart @var{checkpoint-id} |
| @item restart @var{checkpoint-id} |
| Restore the program state that was saved as checkpoint number |
| @var{checkpoint-id}. All program variables, registers, stack frames |
| etc.@: will be returned to the values that they had when the checkpoint |
| was saved. In essence, gdb will ``wind back the clock'' to the point |
| in time when the checkpoint was saved. |
| |
| Note that breakpoints, @value{GDBN} variables, command history etc. |
| are not affected by restoring a checkpoint. In general, a checkpoint |
| only restores things that reside in the program being debugged, not in |
| the debugger. |
| |
| @kindex delete checkpoint @var{checkpoint-id} |
| @item delete checkpoint @var{checkpoint-id} |
| Delete the previously-saved checkpoint identified by @var{checkpoint-id}. |
| |
| @end table |
| |
| Returning to a previously saved checkpoint will restore the user state |
| of the program being debugged, plus a significant subset of the system |
| (OS) state, including file pointers. It won't ``un-write'' data from |
| a file, but it will rewind the file pointer to the previous location, |
| so that the previously written data can be overwritten. For files |
| opened in read mode, the pointer will also be restored so that the |
| previously read data can be read again. |
| |
| Of course, characters that have been sent to a printer (or other |
| external device) cannot be ``snatched back'', and characters received |
| from eg.@: a serial device can be removed from internal program buffers, |
| but they cannot be ``pushed back'' into the serial pipeline, ready to |
| be received again. Similarly, the actual contents of files that have |
| been changed cannot be restored (at this time). |
| |
| However, within those constraints, you actually can ``rewind'' your |
| program to a previously saved point in time, and begin debugging it |
| again --- and you can change the course of events so as to debug a |
| different execution path this time. |
| |
| @cindex checkpoints and process id |
| Finally, there is one bit of internal program state that will be |
| different when you return to a checkpoint --- the program's process |
| id. Each checkpoint will have a unique process id (or @var{pid}), |
| and each will be different from the program's original @var{pid}. |
| If your program has saved a local copy of its process id, this could |
| potentially pose a problem. |
| |
| @subsection A Non-obvious Benefit of Using Checkpoints |
| |
| On some systems such as @sc{gnu}/Linux, address space randomization |
| is performed on new processes for security reasons. This makes it |
| difficult or impossible to set a breakpoint, or watchpoint, on an |
| absolute address if you have to restart the program, since the |
| absolute location of a symbol will change from one execution to the |
| next. |
| |
| A checkpoint, however, is an @emph{identical} copy of a process. |
| Therefore if you create a checkpoint at (eg.@:) the start of main, |
| and simply return to that checkpoint instead of restarting the |
| process, you can avoid the effects of address randomization and |
| your symbols will all stay in the same place. |
| |
| @node Stopping |
| @chapter Stopping and Continuing |
| |
| The principal purposes of using a debugger are so that you can stop your |
| program before it terminates; or so that, if your program runs into |
| trouble, you can investigate and find out why. |
| |
| Inside @value{GDBN}, your program may stop for any of several reasons, |
| such as a signal, a breakpoint, or reaching a new line after a |
| @value{GDBN} command such as @code{step}. You may then examine and |
| change variables, set new breakpoints or remove old ones, and then |
| continue execution. Usually, the messages shown by @value{GDBN} provide |
| ample explanation of the status of your program---but you can also |
| explicitly request this information at any time. |
| |
| @table @code |
| @kindex info program |
| @item info program |
| Display information about the status of your program: whether it is |
| running or not, what process it is, and why it stopped. |
| @end table |
| |
| @menu |
| * Breakpoints:: Breakpoints, watchpoints, and catchpoints |
| * Continuing and Stepping:: Resuming execution |
| * Skipping Over Functions and Files:: |
| Skipping over functions and files |
| * Signals:: Signals |
| * Thread Stops:: Stopping and starting multi-thread programs |
| @end menu |
| |
| @node Breakpoints |
| @section Breakpoints, Watchpoints, and Catchpoints |
| |
| @cindex breakpoints |
| A @dfn{breakpoint} makes your program stop whenever a certain point in |
| the program is reached. For each breakpoint, you can add conditions to |
| control in finer detail whether yo
|