Google Git
Sign in
gnu / binutils-gdb / ecbf5d4f9b716c50908f62cbb9917ed42d45a254 / . / gdb / doc / gdb.texinfo
blob: a6f207a41a7fdee1bcd8798a982ec22e682a37a9 [file] [log] [blame]
\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