Руководство по gdb

This file documents the GNU debugger GDB.

This is the Tenth Edition, of Debugging with
GDB: the GNU Source-Level Debugger for GDB
(GDB)
Version 13.1.90.20230516-git.

Copyright © 1988-2023 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.”

Debugging with GDB

This file describes GDB, the GNU symbolic debugger.

This is the Tenth Edition, for GDB
(GDB)
Version 13.1.90.20230516-git.

Copyright (C) 1988-2023 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.

Table of Contents

Summary of GDB

The purpose of a debugger such as GDB is to allow you to see what is
going on “inside” another program while it executes—or what another
program was doing at the moment it crashed.

GDB can do four main kinds of things (plus other things in support of
these) to help you catch bugs in the act:

• Start your program, specifying anything that might affect its behavior.
• Make your program stop on specified conditions.
• Examine what has happened, when your program has stopped.
• Change things in your program, so you can experiment with correcting the
  effects of one bug and go on to learn about another.

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

Support for D is partial. For information on D, see
D.

Support for Modula-2 is partial. For information on Modula-2, see
Modula-2.

Support for OpenCL C is partial. For information on OpenCL C, see
OpenCL C.

Debugging Pascal programs which use sets, subranges, file variables, or
nested functions does not currently work. GDB does not support
entering expressions, printing values, or similar features using Pascal
syntax.

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

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

Free Software

GDB is free software, protected by the 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.

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 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 licensing@gnu.org.

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

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

Contributors to GDB

Richard Stallman was the original author of GDB, and of many
other GNU programs. Many others have contributed to its
development. This section attempts to credit major contributors. One
of the virtues of free software is that everyone is free to contribute
to it; with regret, we cannot actually acknowledge everyone here. The
file ChangeLog in the GDB distribution approximates a
blow-by-blow account.

Changes much prior to version 2.0 are lost in the mists of time.

Plea: Additions to this section are particularly welcome. If you
or your friends (or enemies, to be evenhanded) have been unfairly
omitted from this list, we would like to add your names!

So that they may not regard their many labors as thankless, we
particularly thank those who shepherded GDB through major
releases:
Andrew Cagney (releases 6.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 GNU C++ support
in GDB, with significant additional contributions from Per
Bothner and Daniel Berlin. James Clark wrote the GNU C++
demangler. Early work on C++ was by Peter TerMaat (who also did
much general update work leading to release 3.0).

GDB uses the BFD subroutine library to examine multiple
object-file formats; BFD was a joint project of David V.
Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.

David Johnson wrote the original COFF support; Pace Willison did
the original support for encapsulated COFF.

Brent Benson of Harris Computer Systems contributed DWARF 2 support.

Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
support.
Jean-Daniel Fekete contributed Sun 386i support.
Chris Hanson improved the HP9000 support.
Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
David Johnson contributed Encore Umax support.
Jyrki Kuoppala contributed Altos 3068 support.
Jeff Law contributed HP PA and SOM support.
Keith Packard contributed NS32K support.
Doug Rabson contributed Acorn Risc Machine support.
Bob Rusk contributed Harris Nighthawk CX-UX support.
Chris Smith contributed Convex support (and Fortran debugging).
Jonathan Stone contributed Pyramid support.
Michael Tiemann contributed SPARC support.
Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
Pace Willison contributed Intel 386 support.
Jay Vosburgh contributed Symmetry support.
Marko Mlinar contributed OpenRISC 1000 support.

Andreas Schwab contributed M68K GNU/Linux support.

Rich Schaefer and Peter Schauer helped with support of SunOS shared
libraries.

Jay Fenlason and Roland McGrath ensured that GDB and GAS agree
about several machine instruction sets.

Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM
contributed remote debugging modules for the i960, VxWorks, A29K UDI,
and RDI targets, respectively.

Brian Fox is the author of the readline libraries providing
command-line editing and command history.

Andrew Beers of SUNY Buffalo wrote the language-switching code, the
Modula-2 support, and contributed the Languages chapter of this manual.

Fred Fish wrote most of the support for Unix System Vr4.
He also enhanced the command-completion support to cover C++ overloaded
symbols.

Hitachi America (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 GDB.

The following people at the Hewlett-Packard Company contributed
support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
(narrow mode), HP’s implementation of kernel threads, HP’s aC++
compiler, and the 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 GDB to MS-DOS, for the DJGPP project.
Robert Hoehne made significant contributions to the DJGPP port.

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

Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
Cygnus Solutions, implemented the original GDB/MI interface.

Jim Blandy added support for preprocessor macros, while working for Red
Hat.

Andrew Cagney designed GDB’s architecture vector. Many
people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick
Duffek, Richard Henderson, Mark 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 GDB’s
unwinder framework, this consisting of a fresh new design featuring
frame IDs, independent frame sniffers, and the sentinel frame. Mark
Kettenis implemented the 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 GDB 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.

1 A Sample GDB Session

You can use this manual at your leisure to read all about GDB.
However, a handful of commands are enough to get started using the
debugger. This chapter illustrates those commands.

One of the preliminary versions of GNU m4 (a generic macro
processor) exhibits the following bug: sometimes, when we change its
quote strings from the default, the commands used to capture one macro
definition within another stop working. In the following short m4
session, we define a macro foo which expands to 0000; we
then use the m4 built-in defn to define bar as the
same thing. However, when we change the open quote string to
<QUOTE> and the close quote string to <UNQUOTE>, the same
procedure fails to define a new synonym baz:

$ cd gnu/m4
$ ./m4
define(foo,0000)

foo
0000
define(bar,defn(‘foo’))

bar
0000
changequote(<QUOTE>,<UNQUOTE>)

define(baz,defn(<QUOTE>foo<UNQUOTE>))
baz
Ctrl-d
m4: End of input: 0: fatal error: EOF in string

Let us use GDB to try to see what is going on.

$ gdb m4
GDB is free software and you are welcome to distribute copies
 of it under certain conditions; type "show copying" to see
 the conditions.
There is absolutely no warranty for GDB; type "show warranty"
 for details.

GDB 13.1.90.20230516-git, Copyright 1999 Free Software Foundation, Inc...
(gdb)

GDB reads only enough symbol data to know where to find the
rest when needed; as a result, the first prompt comes up very quickly.
We now tell GDB to use a narrower display width than usual, so
that examples fit in this manual.

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

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

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

(gdb) run
Starting program: /work/Editorial/gdb/gnu/m4/m4
define(foo,0000)

foo
0000

To trigger the breakpoint, we call changequote. GDB
suspends execution of m4, displaying information about the
context where it stops.

changequote(<QUOTE>,<UNQUOTE>)

Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
    at builtin.c:879
879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))

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

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

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

(gdb) s
set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
    at input.c:530
530         if (lquote != def_lquote)

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

(gdb) bt
#0  set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
    at input.c:530
#1  0x6344 in m4_changequote (argc=3, argv=0x33c70)
    at builtin.c:882
#2  0x8174 in expand_macro (sym=0x33320) at macro.c:242
#3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
    at macro.c:71
#4  0x79dc in expand_input () at macro.c:40
#5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195

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

(gdb) s
0x3b5c  532         if (rquote != def_rquote)
(gdb) s
0x3b80  535         lquote = (lq == nil || *lq == '') ?  
def_lquote : xstrdup(lq);
(gdb) n
536         rquote = (rq == nil || *rq == '') ? def_rquote
 : xstrdup(rq);
(gdb) n
538         len_lquote = strlen(rquote);

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

(gdb) p lquote
$1 = 0x35d40 "<QUOTE>"
(gdb) p rquote
$2 = 0x35d50 "<UNQUOTE>"

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

(gdb) l
533             xfree(rquote);
534
535         lquote = (lq == nil || *lq == '') ? def_lquote
 : xstrdup (lq);
536         rquote = (rq == nil || *rq == '') ? def_rquote
 : xstrdup (rq);
537
538         len_lquote = strlen(rquote);
539         len_rquote = strlen(lquote);
540     }
541
542     void

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

(gdb) n
539         len_rquote = strlen(lquote);
(gdb) n
540     }
(gdb) p len_lquote
$3 = 9
(gdb) p len_rquote
$4 = 7

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

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

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

(gdb) c
Continuing.

define(baz,defn(<QUOTE>foo<UNQUOTE>))

baz
0000

Success! The new quotes now work just as well as the default ones. The
problem seems to have been just the two typos defining the wrong
lengths. We allow m4 exit by giving it an EOF as input:

Ctrl-d
Program exited normally.

The message ‘Program exited normally.’ is from GDB; it
indicates m4 has finished executing. We can end our GDB
session with the GDB quit command.

2 Getting In and Out of GDB

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

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

2.1 Invoking GDB

Invoke GDB by running the program gdb. Once started,
GDB reads commands from the terminal until you tell it to exit.

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

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

The most usual way to start GDB is with one argument,
specifying an executable program:

You can also start with both an executable program and a core file
specified:

You can, instead, specify a process ID as a second argument or use option
-p, if you want to debug a running process:

gdb program 1234
gdb -p 1234

would attach GDB to process 1234. With option -p you
can omit the program filename.

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

You can optionally have gdb pass any arguments after the
executable file to the inferior using --args. This option stops
option processing.

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

This will cause gdb to debug gcc, and to set
gcc’s command-line arguments (see Arguments) to ‘-O2 -c foo.c’.

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

You can further control how GDB starts up by using command-line
options. GDB itself can remind you of the options available.

Type

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

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

2.1.1 Choosing Files

When GDB starts, it reads any arguments other than options as
specifying an executable file and core file (or process ID). This is
the same as if the arguments were specified by the ‘-se’ and
‘-c’ (or ‘-p’) options respectively. (GDB reads the
first argument that does not have an associated option flag as
equivalent to the ‘-se’ option followed by that argument; and the
second argument that does not have an associated option flag, if any, as
equivalent to the ‘-c’/‘-p’ option followed by that argument.)
If the second argument begins with a decimal digit, GDB will
first attempt to attach to it as a process, and if that fails, attempt
to open it as a corefile. If you have a corefile whose name begins with
a digit, you can prevent GDB from treating it as a pid by
prefixing it with ./, e.g. ./12345.

If GDB has not been configured to included core file support,
such as for most embedded targets, then it will complain about a second
argument and ignore it.

For the ‘-s’, ‘-e’, and ‘-se’ options, and their long
form equivalents, the method used to search the file system for the
symbol and/or executable file is the same as that used by the
file command. See file.

Many options have both long and short forms; both are shown in the
following list. GDB also recognizes the long forms if you truncate
them, so long as enough of the option is present to be unambiguous.
(If you prefer, you can flag option arguments with ‘—’ rather
than ‘—’, though we illustrate the more usual convention.)

-symbols file

-s file

Read symbol table from file file.

-exec file

-e file

Use file file as the executable file to execute when appropriate,
and for examining pure data in conjunction with a core dump.

-se file

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

-core file

-c file

Use file file as a core dump to examine.

-pid number

-p number

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

-command file

-x file

Execute commands from file file. The contents of this file is
evaluated exactly as the source command would.
See Command files.

-eval-command command

-ex command

Execute a single GDB command.

This option may be used multiple times to call multiple commands. It may
also be interleaved with ‘-command’ as required.

gdb -ex 'target sim' -ex 'load' 
   -x setbreakpoints -ex 'run' a.out

-init-command file

-ix file

Execute commands from file file before loading the inferior (but
after loading gdbinit files).
See Startup.

-init-eval-command command

-iex command

Execute a single GDB command before loading the inferior (but
after loading gdbinit files).
See Startup.

-early-init-command file

-eix file

Execute commands from file very early in the initialization
process, before any output is produced. See Startup.

-early-init-eval-command command

-eiex command

Execute a single GDB command very early in the initialization
process, before any output is produced.

-directory directory

-d directory

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

-r

-readnow

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

--readnever

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.

2.1.2 Choosing Modes

You can run GDB in various alternative modes—for example, in
batch mode or quiet mode.

-nx

-n

Do not execute commands found in any initialization files
(see Initialization Files).

-nh

Do not execute commands found in any home directory initialization
file (see Home directory initialization
file). The system wide and current directory initialization files
are still loaded.

-quiet

-silent

-q

“Quiet”. Do not print the introductory and copyright messages. These
messages are also suppressed in batch mode.

This can also be enabled using set startup-quietly on. The
default is off. Use show startup-quietly to see the
current setting. Place set startup-quietly on into your early
initialization file (see Initialization
Files) to have future GDB sessions startup quietly.

-batch

Run in batch mode. Exit with status 0 after processing all the
command files specified with ‘-x’ (and all commands from
initialization files, if not inhibited with ‘-n’). Exit with
nonzero status if an error occurs in executing the GDB commands
in the command files. Batch mode also disables pagination, sets unlimited
terminal width and height see Screen Size, and acts as if set confirm
off were in effect (see Messages/Warnings).

Batch mode may be useful for running GDB as a filter, for
example to download and run a program on another computer; in order to
make this more useful, the message

(which is ordinarily issued whenever a program running under
GDB control terminates) is not issued when running in batch
mode.

-batch-silent

Run in batch mode exactly like ‘-batch’, but totally silently. All
GDB output to stdout is prevented (stderr is
unaffected). This is much quieter than ‘-silent’ and would be useless
for an interactive session.

This is particularly useful when using targets that give ‘Loading section’
messages, for example.

Note that targets that give their output via GDB, as opposed to
writing directly to stdout, will also be made silent.

-return-child-result

The return code from GDB will be the return code from the child
process (the process being debugged), with the following exceptions:

• GDB 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 ‘-return-child-result’.
• The user quits with an explicit value. E.g., ‘quit 1’.
• The child process never runs, or is not allowed to terminate, in which case
  the exit code will be -1.

This option is useful in conjunction with ‘-batch’ or ‘-batch-silent’,
when GDB is being used as a remote program loader or simulator
interface.

-nowindows

-nw

“No windows”. If GDB comes with a graphical user interface
(GUI) built in, then this option tells GDB to only use the command-line
interface. If no GUI is available, this option has no effect.

-windows

-w

If GDB includes a GUI, then this option requires it to be
used if possible.

-cd directory

Run GDB using directory as its working directory,
instead of the current directory.

-data-directory directory

-D directory

Run GDB using directory as its data directory.
The data directory is where GDB searches for its
auxiliary files. See Data Files.

-fullname

-f

GNU Emacs sets this option when it runs GDB as a
subprocess. It tells GDB to output the full file name and line
number in a standard, recognizable fashion each time a stack frame is
displayed (which includes each time your program stops). This
recognizable format looks like two ‘32’ characters, followed by
the file name, line number and character position separated by colons,
and a newline. The Emacs-to-GDB interface program uses the two
‘32’ characters as a signal to display the source code for the
frame.

-annotate level

This option sets the annotation level inside GDB. Its
effect is identical to using ‘set annotate level’
(see Annotations). The annotation level controls how much
information GDB 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 GDB is run as a subprocess of
GNU Emacs, level 3 is the maximum annotation suitable for programs
that control GDB, and level 2 has been deprecated.

The annotation mechanism has largely been superseded by GDB/MI
(see GDB/MI).

--args

Change interpretation of command line so that arguments following the
executable file are passed as command line arguments to the inferior.
This option stops option processing.

-baud bps

-b bps

Set the line speed (baud rate or bits per second) of any serial
interface used by GDB for remote debugging.

-l timeout

Set the timeout (in seconds) of any communication used by GDB
for remote debugging.

-tty device

-t device

Run using device for your program’s standard input and output.

-tui

Activate the Text User Interface when starting. The Text User
Interface manages several text windows on the terminal, showing
source, assembly, registers and GDB command outputs
(see GDB Text User Interface). Do not use this
option if you run GDB from Emacs (see Using GDB under GNU Emacs).

-interpreter interp

Use the interpreter interp for interface with the controlling
program or device. This option is meant to be set by programs which
communicate with GDB using it as a back end.
See Command Interpreters.

‘—interpreter=mi’ (or ‘—interpreter=mi3’) causes
GDB to use the GDB/MI interface version 3 (see The GDB/MI Interface) included since GDB version 9.1. GDB/MI
version 2 (mi2), included in GDB 6.0 and version 1 (mi1),
included in GDB 5.3, are also available. Earlier GDB/MI
interfaces are no longer supported.

-write

Open the executable and core files for both reading and writing. This
is equivalent to the ‘set write on’ command inside GDB
(see Patching).

-statistics

This option causes GDB to print statistics about time and
memory usage after it completes each command and returns to the prompt.

-version

This option causes GDB to print its version number and
no-warranty blurb, and exit.

-configuration

This option causes GDB to print details about its build-time
configuration parameters, and then exit. These details can be
important when reporting GDB bugs (see GDB Bugs).

2.1.3 What GDB Does During Startup

Here’s the description of what GDB does during session startup:

1. Performs minimal setup required to initialize basic internal state.
2. 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 Initialization Files, for
   details.

3. Executes commands and command files specified by the ‘-eiex’ and
   ‘-eix’ command line options in their specified order. Only a
   restricted set of commands can be used with ‘-eiex’ and
   ‘eix’, see Initialization Files, for details.

4. Sets up the command interpreter as specified by the command line
   (see interpreter).
5. Reads the system wide initialization file and the files from the
   system wide initialization directory, see System Wide Init Files.

6. Reads the initialization file (if any) in your home directory and
   executes all the commands in that file, see Home Directory Init File.

7. Executes commands and command files specified by the ‘-iex’ and
   ‘-ix’ options in their specified order. Usually you should use the
   ‘-ex’ and ‘-x’ options instead, but this way you can apply
   settings before GDB init files get executed and before inferior
   gets loaded.

8. Processes command line options and operands.
9. Reads and executes the commands from the initialization file (if any)
   in the current working directory as long as ‘set auto-load
   local-gdbinit’ is set to ‘on’ (see 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
   GDB. See Init File in the Current Directory during Startup.

10. If the command line specified a program to debug, or a process to
    attach to, or a core file, GDB loads any auto-loaded
    scripts provided for the program or for its loaded shared libraries.
    See Auto-loading.

    If you wish to disable the auto-loading during startup,
    you must do something like the following:

    $ gdb -iex "set auto-load python-scripts off" myprogram
    

    Option ‘-ex’ does not work because the auto-loading is then turned
    off too late.

11. Executes commands and command files specified by the ‘-ex’ and
    ‘-x’ options in their specified order. See Command Files, for
    more details about GDB command files.

12. Reads the command history recorded in the history file.
    See Command History, for more details about the command history and the
    files where GDB records it.

2.1.4 Initialization Files

During startup (see Startup) GDB will execute commands
from several initialization files. These initialization files use the
same syntax as command files (see Command Files) and are
processed by GDB in the same way.

To display the list of initialization files loaded by GDB at
startup, in the order they will be loaded, you can use gdb
--help.

The early initialization file is loaded very early in
GDB’s initialization process, before the interpreter
(see Interpreters) has been initialized, and before the default
target (see Targets) is initialized. Only set or
source commands should be placed into an early initialization
file, and the only set commands that can be used are those that
control how GDB 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 --early-init-command or -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 --early-init-eval-command or -eiex.

In contrast, the general initialization files are processed
later, after GDB has finished its own internal initialization
process, any valid command can be used in these files.

Throughout the rest of this document the term 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. ‘set complaints’) can affect subsequent processing of
command line options and operands.

The following sections describe where GDB looks for the early
initialization and initialization files, and the order that the files
are searched for.

2.1.4.1 Home directory early initialization files

GDB initially looks for an early initialization file in the
users home directory¹. There are a number of locations that GDB will
search in the home directory, these locations are searched in order
and GDB will load the first file that it finds, and
subsequent locations will not be checked.

On non-macOS hosts the locations searched are:

• The file gdb/gdbearlyinit within the directory pointed to by the
  environment variable XDG_CONFIG_HOME, if it is defined.
• The file .config/gdb/gdbearlyinit within the directory pointed to
  by the environment variable HOME, if it is defined.
• The file .gdbearlyinit within the directory pointed to by the
  environment variable HOME, if it is defined.

By contrast, on macOS hosts the locations searched are:

• The file Library/Preferences/gdb/gdbearlyinit within the
  directory pointed to by the environment variable HOME, if it is
  defined.
• The file .gdbearlyinit within the directory pointed to by the
  environment variable HOME, if it is defined.

It is possible to prevent the home directory early initialization file
from being loaded using the ‘-nx’ or ‘-nh’ command line
options, see Choosing Modes.

2.1.4.2 System wide initialization files

There are two locations that are searched for system wide
initialization files. Both of these locations are always checked:

system.gdbinit

This is a single system-wide initialization file. Its location is
specified with the --with-system-gdbinit configure option
(see System-wide configuration). It is loaded first when
GDB starts, before command line options have been processed.

system.gdbinit.d

This is the system-wide initialization directory. Its location is
specified with the --with-system-gdbinit-dir configure option
(see System-wide configuration). Files in this directory are
loaded in alphabetical order immediately after system.gdbinit
(if enabled) when GDB starts, before command line options
have been processed. Files need to have a recognized scripting
language extension (.py/.scm) or be named with a
.gdb extension to be interpreted as regular GDB
commands. GDB will not recurse into any subdirectories of
this directory.

It is possible to prevent the system wide initialization files from
being loaded using the ‘-nx’ command line option, see Choosing Modes.

2.1.4.3 Home directory initialization file

After loading the system wide initialization files GDB will
look for an initialization file in the users home
directory². There are a
number of locations that GDB will search in the home
directory, these locations are searched in order and GDB will
load the first file that it finds, and subsequent locations will not
be checked.

On non-Apple hosts the locations searched are:

$XDG_CONFIG_HOME/gdb/gdbinit

$HOME/.config/gdb/gdbinit

$HOME/.gdbinit

While on Apple hosts the locations searched are:

$HOME/Library/Preferences/gdb/gdbinit

$HOME/.gdbinit

It is possible to prevent the home directory initialization file from
being loaded using the ‘-nx’ or ‘-nh’ command line options,
see Choosing Modes.

The DJGPP port of GDB uses the name gdb.ini instead of
.gdbinit or gdbinit, due to the limitations of file
names imposed by DOS filesystems. The Windows port of GDB
uses the standard name, but if it finds a gdb.ini file in your
home directory, it warns you about that and suggests to rename the
file to the standard name.

2.1.4.4 Local directory initialization file

GDB will check the current directory for a file called
.gdbinit. It is loaded last, after command line options
other than ‘-x’ and ‘-ex’ have been processed. The command
line options ‘-x’ and ‘-ex’ are processed last, after
.gdbinit has been loaded, see 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 ‘-nx’ command line option, see Choosing Modes.

2.2 Quitting GDB

quit [expression]

exit [expression]

q

To exit GDB, use the quit command (abbreviated
q), the exit command, or type an end-of-file
character (usually Ctrl-d). If you do not supply expression,
GDB will terminate normally; otherwise it will terminate using
the result of expression as the error code.

An interrupt (often Ctrl-c) does not exit from GDB, but rather
terminates the action of any GDB command that is in progress and
returns to GDB command level. It is safe to type the interrupt
character at any time because GDB does not allow it to take effect
until a time when it is safe.

If you have been using GDB to control an attached process or
device, you can release it with the detach command
(see Debugging an Already-running Process).

2.3 Shell Commands

If you need to execute occasional shell commands during your
debugging session, there is no need to leave or suspend GDB; you can
just use the shell command.

shell command-string

!command-string

Invoke a standard shell to execute command-string.
Note that no space is needed between ! and command-string.
On GNU and Unix systems, the environment variable SHELL, if it
exists, determines which shell to run. Otherwise GDB uses
the default shell (/bin/sh on GNU and Unix systems,
cmd.exe on MS-Windows, COMMAND.COM on MS-DOS, etc.).

The utility make is often needed in development environments.
You do not have to use the shell command for this purpose in
GDB:

make make-args

Execute the make program with the specified
arguments. This is equivalent to ‘shell make make-args’.

pipe [command] | shell_command

| [command] | shell_command

pipe -d delim command delim shell_command

| -d delim command delim shell_command

Executes command and sends its output to shell_command.
Note that no space is needed around |.
If no command is provided, the last command executed is repeated.

In case the command contains a |, the option -d delim
can be used to specify an alternate delimiter string delim that separates
the command from the shell_command.

Example:

(gdb) p var
$1 = {
  black = 144,
  red = 233,
  green = 377,
  blue = 610,
  white = 987
}

(gdb) pipe p var|wc
      7      19      80
(gdb) |p var|wc -l
7

(gdb) p /x var
$4 = {
  black = 0x90,
  red = 0xe9,
  green = 0x179,
  blue = 0x262,
  white = 0x3db
}
(gdb) ||grep red
  red => 0xe9,

(gdb) | -d ! echo this contains a | charn ! 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)

The convenience variables $_shell_exitcode and $_shell_exitsignal
can be used to examine the exit status of the last shell command launched
by shell, make, pipe and |.
See Convenience Variables.

2.4 Logging Output

You may want to save the output of GDB commands to a file.
There are several commands to control GDB’s logging.

set logging enabled [on|off]

Enable or disable logging.

set logging file file

Change the name of the current logfile. The default logfile is gdb.txt.

set logging overwrite [on|off]

By default, GDB will append to the logfile. Set overwrite if
you want set logging enabled on to overwrite the logfile instead.

set logging redirect [on|off]

By default, GDB output will go to both the terminal and the logfile.
Set redirect if you want output to go only to the log file.

set logging debugredirect [on|off]

By default, GDB debug output will go to both the terminal and the logfile.
Set debugredirect if you want debug output to go only to the log file.

show logging

Show the current values of the logging settings.

You can also redirect the output of a GDB command to a
shell command. See pipe.

3 GDB Commands

You can abbreviate a GDB command to the first few letters of the command
name, if that abbreviation is unambiguous; and you can repeat certain
GDB commands by typing just RET. You can also use the TAB
key to get GDB to fill out the rest of a word in a command (or to
show you the alternatives available, if there is more than one possibility).

3.1 Command Syntax

A GDB command is a single line of input. There is no limit on
how long it can be. It starts with a command name, which is followed by
arguments whose meaning depends on the command name. For example, the
command step accepts an argument which is the number of times to
step, as in ‘step 5’. You can also use the step command
with no arguments. Some commands do not allow any arguments.

GDB command names may always be truncated if that abbreviation is
unambiguous. Other possible command abbreviations are listed in the
documentation for individual commands. In some cases, even ambiguous
abbreviations are allowed; for example, s is specially defined as
equivalent to step even though there are other commands whose
names start with s. You can test abbreviations by using them as
arguments to the help command.

A blank line as input to GDB (typing just RET) means to
repeat the previous command. Certain commands (for example, run)
will not repeat this way; these are commands whose unintentional
repetition might cause trouble and which you are unlikely to want to
repeat. User-defined commands can disable this feature; see
dont-repeat.

The list and x commands, when you repeat them with
RET, construct new arguments rather than repeating
exactly as typed. This permits easy scanning of source or memory.

GDB can also use RET in another way: to partition lengthy
output, in a way similar to the common utility more
(see Screen Size). Since it is easy to press one
RET too many in this situation, GDB disables command
repetition after any command that generates this sort of display.

Any text from a # to the end of the line is a comment; it does
nothing. This is useful mainly in command files (see Command Files).

The Ctrl-o binding is useful for repeating a complex sequence of
commands. This command accepts the current line, like RET, and
then fetches the next line relative to the current line from the history
for editing.

3.2 Command Settings

Many commands change their behavior according to command-specific
variables or settings. These settings can be changed with the
set subcommands. For example, the print command
(see Examining Data) prints arrays differently depending on
settings changeable with the commands set print elements
NUMBER-OF-ELEMENTS and set print array-indexes, among others.

You can change these settings to your preference in the gdbinit files
loaded at GDB startup. See 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:

(GDB) set print elements 10
(GDB) print some_array
$1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...}

The above 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 some_array, then you
must restore the limit back to 200, with set print elements
200.

Some commands allow overriding settings with command options. For
example, the print command supports a number of options that
allow overriding relevant global print settings as set by set
print subcommands. See print options. The example above could be
rewritten as:

(GDB) print -elements 10 -- some_array
$1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...}

Alternatively, you can use the with command to change a setting
temporarily, for the duration of a command invocation.

with setting [value] [-- command]

w setting [value] [-- command]

Temporarily set setting to value for the duration of
command.

setting is any setting you can change with the set
subcommands. value is the value to assign to setting
while running command.

If no command is provided, the last command executed is
repeated.

If a command is provided, it must be preceded by a double dash
(--) separator. This is required because some settings accept
free-form arguments, such as expressions or filenames.

For example, the command

(GDB) with print array on -- print some_array

is equivalent to the following 3 commands:

(GDB) set print array on
(GDB) print some_array
(GDB) set print array off

The with command is particularly useful when you want to
override a setting while running user-defined commands, or commands
defined in Python or Guile. See Extending GDB.

(GDB) with print pretty on -- my_complex_command

To change several settings for the same command, you can nest
with commands. For example, 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.

3.3 Command Completion

GDB can fill in the rest of a word in a command for you, if there is
only one possibility; it can also show you what the valid possibilities
are for the next word in a command, at any time. This works for GDB
commands, GDB subcommands, command options, and the names of symbols
in your program.

Press the TAB key whenever you want GDB to fill out the rest
of a word. If there is only one possibility, GDB fills in the
word, and waits for you to finish the command (or press RET to
enter it). For example, if you type

GDB fills in the rest of the word ‘breakpoints’, since that is
the only info subcommand beginning with ‘bre’:

You can either press RET at this point, to run the info
breakpoints command, or backspace and enter something else, if
‘breakpoints’ does not look like the command you expected. (If you
were sure you wanted info breakpoints in the first place, you
might as well just type RET immediately after ‘info bre’,
to exploit command abbreviations rather than command completion).

If there is more than one possibility for the next word when you press
TAB, GDB sounds a bell. You can either supply more
characters and try again, or just press TAB a second time;
GDB displays all the possible completions for that word. For
example, you might want to set a breakpoint on a subroutine whose name
begins with ‘make_’, but when you type b make_TAB GDB
just sounds the bell. Typing TAB again displays all the
function names in your program that begin with those characters, for
example:

(gdb) b make_TAB

GDB sounds bell; press TAB again, to see:

make_a_section_from_file     make_environ
make_abs_section             make_function_type
make_blockvector             make_pointer_type
make_cleanup                 make_reference_type
make_command                 make_symbol_completion_list
(gdb) b make_

After displaying the available possibilities, GDB copies your
partial input (‘b make_’ in the example) so you can finish the
command.

If the command you are trying to complete expects either a keyword or a
number to follow, then ‘NUMBER’ will be shown among the available
completions, for example:

(gdb) print -elements TABTAB
NUMBER     unlimited
(gdb) print -elements 

Here, the option expects a number (e.g., 100), not literal
NUMBER. Such metasyntactical arguments are always presented in
uppercase.

If you just want to see the list of alternatives in the first place, you
can press M-? rather than pressing TAB twice. M-?
means META ?. You can type this either by holding down a
key designated as the META shift on your keyboard (if there is
one) while typing ?, or as ESC followed by ?.

If the number of possible completions is large, GDB will
print as much of the list as it has collected, as well as a message
indicating that the list may be truncated.

(gdb) b mTABTAB
main
<... the rest of the possible completions ...>
*** List may be truncated, max-completions reached. ***
(gdb) b m

This behavior can be controlled with the following commands:

set max-completions limit

set max-completions unlimited

Set the maximum number of completion candidates. GDB 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.

show max-completions

Show the maximum number of candidates that GDB will collect and show
during completion.

Sometimes the string you need, while logically a “word”, may contain
parentheses or other characters that GDB normally excludes from
its notion of a word. To permit word completion to work in this
situation, you may enclose words in ' (single quote marks) in
GDB commands.

A likely situation where you might need this is in typing an
expression that involves a C++ symbol name with template
parameters. This is because when completing expressions, GDB treats
the ‘<’ character as word delimiter, assuming that it’s the
less-than comparison operator (see C and C++
Operators).

For example, when you want to call a C++ template function
interactively using the print or call commands, you may
need to distinguish whether you mean the version of name that
was specialized for int, name<int>(), or the version
that was specialized for float, name<float>(). To use
the word-completion facilities in this situation, type a single quote
' at the beginning of the function name. This alerts
GDB that it may need to consider more information than usual
when you press TAB or M-? to request word completion:

(gdb) p 'func<M-?
func<int>()    func<float>()
(gdb) p 'func<

When setting breakpoints however (see Location Specifications), you don’t
usually need to type a quote before the function name, because
GDB understands that you want to set a breakpoint on a
function:

(gdb) b func<M-?
func<int>()    func<float>()
(gdb) b func<

This is true even in the case of typing the name of C++ 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 name
that takes an int parameter, name(int), or the version
that takes a float parameter, name(float).

(gdb) b bubble(M-?
bubble(int)    bubble(double)
(gdb) b bubble(douM-?
bubble(double)

See quoting names for a description of other scenarios that
require quoting.

For more information about overloaded functions, see C++ Expressions. You can use the command set
overload-resolution off to disable overload resolution;
see GDB Features for C++.

When completing in an expression which looks up a field in a
structure, GDB also tries³ to
limit completions to the field names available in the type of the
left-hand-side:

(gdb) p gdb_stdout.M-?
magic                to_fputs             to_rewind
to_data              to_isatty            to_write
to_delete            to_put               to_write_async_safe
to_flush             to_read

This is because the gdb_stdout is a variable of the type
struct ui_file that is defined in GDB sources as
follows:

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;
}

3.4 Command options

Some commands accept options starting with a leading dash. For
example, print -pretty. Similarly to command names, you can
abbreviate a GDB option to the first few letters of the
option name, if that abbreviation is unambiguous, and you can also use
the TAB key to get GDB 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).

Some commands take raw input as argument. For example, the print
command processes arbitrary expressions in any of the languages
supported by GDB. 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. print -p (short for print
-pretty or printing negative p?), if you specify any command
option, then you must use a double-dash (--) delimiter to
indicate the end of options.

Some options are described as accepting an argument which can be
either on or off. These are known as boolean
options. Similarly to boolean settings commands—on and
off are the typical values, but any of 1, yes and
enable can also be used as “true” value, and any of 0,
no and 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:

(gdb) print -object on -pretty off -element unlimited -- *myptr
(gdb) p -o -p 0 -e u -- *myptr

You can discover the set of options some command accepts by completing
on - after the command name. For example:

(gdb) print -TABTAB
-address         -max-depth               -object          -static-members
-array           -memory-tag-violations   -pretty          -symbol
-array-indexes   -nibbles                 -raw-values      -union
-elements        -null-stop               -repeats         -vtbl

Completion will in some cases guide you with a suggestion of what kind
of argument an option expects. For example:

(gdb) print -elements TABTAB
NUMBER     unlimited

Here, the option expects a number (e.g., 100), not literal
NUMBER. Such metasyntactical arguments are always presented in
uppercase.

(For more on using the print command, see Examining
Data.)

3.5 Getting Help

You can always ask GDB itself for information on its commands,
using the command help.

help

h

You can use help (abbreviated h) with no arguments to
display a short list of named classes of commands:

(gdb) 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.
(gdb)

help 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 status:

(gdb) help status
Status inquiries.

List of commands:

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.
(gdb)

help command

With a command name as help argument, GDB displays a
short paragraph on how to use that command. If that command has
one or more aliases, GDB 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.
When asking the help for an alias, the documentation for the aliased
command is shown.

A user-defined alias can optionally be documented using the
document command (see document). GDB then
considers this alias as different from the aliased command: this alias
is not listed in the aliased command help output, and asking help for
this alias will show the documentation provided for the alias instead of
the documentation of the aliased command.

apropos [-v] regexp

The apropos command searches through all of the GDB
commands and aliases, and their documentation, for the regular expression specified in
args. It prints out all matches found. The optional flag ‘-v’,
which stands for ‘verbose’, indicates to output the full documentation
of the matching commands and highlight the parts of the documentation
matching regexp. For example:

results in:

alias -- Define a new command that is an alias of an existing command
aliases -- User-defined aliases of other commands

while

apropos -v cut.*thread apply

results in the below output, where ‘cut for ‘thread apply’
is highlighted if styling is enabled.

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'

complete args

The complete args command lists all the possible completions
for the beginning of a command. Use args to specify the beginning of the
command you want completed. For example:

results in:

This is intended for use by GNU Emacs.

In addition to help, you can use the GDB commands info
and show to inquire about the state of your program, or the state
of GDB itself. Each command supports many topics of inquiry; this
manual introduces each of them in the appropriate context. The listings
under info and under show in the Command, Variable, and
Function Index point to all the sub-commands. See Command and Variable Index.

info

This command (abbreviated i) is for describing the state of your
program. For example, you can show the arguments passed to a function
with info args, list the registers currently in use with info
registers, or list the breakpoints you have set with info breakpoints.
You can get a complete list of the info sub-commands with
help info.

set

You can assign the result of an expression to an environment variable with
set. For example, you can set the GDB prompt to a $-sign with
set prompt $.

show

In contrast to info, show is for describing the state of
GDB itself.
You can change most of the things you can show, by using the
related command set; for example, you can control what number
system is used for displays with set radix, or simply inquire
which is currently in use with show radix.

To display all the settable parameters and their current
values, you can use show with no arguments; you may also use
info set. Both commands produce the same display.

Here are several miscellaneous show subcommands, all of which are
exceptional in lacking corresponding set commands:

show version

Show what version of GDB is running. You should include this
information in GDB bug-reports. If multiple versions of
GDB are in use at your site, you may need to determine which
version of GDB you are running; as GDB evolves, new
commands are introduced, and old ones may wither away. Also, many
system vendors ship variant versions of GDB, and there are
variant versions of GDB in GNU/Linux distributions as well.
The version number is the same as the one announced when you start
GDB.

show copying

info copying

Display information about permission for copying GDB.

show warranty

info warranty

Display the GNU “NO WARRANTY” statement, or a warranty,
if your version of GDB comes with one.

show configuration

Display detailed information about the way GDB was configured
when it was built. This displays the optional arguments passed to the
configure script and also configuration parameters detected
automatically by configure. When reporting a GDB
bug (see GDB Bugs), it is important to include this information in
your report.

4 Running Programs Under GDB

When you run a program under GDB, you must first generate
debugging information when you compile it.

You may start GDB 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.

4.1 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 ‘-g’ option when you run
the compiler.

Programs that are to be shipped to your customers are compiled with
optimizations, using the ‘-O’ compiler option. However, some
compilers are unable to handle the ‘-g’ and ‘-O’ options
together. Using those compilers, you cannot generate optimized
executables containing debugging information.

GCC, the GNU C/C++ compiler, supports ‘-g’ with or
without ‘-O’, making it possible to debug optimized code. We
recommend that you always use ‘-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 Optimized Code.

Older versions of the GNU C compiler permitted a variant option
‘-gg’ for debugging information. GDB no longer supports this
format; if your GNU C compiler has this option, do not use it.

GDB knows about preprocessor macros and can show you their
expansion (see Macros). Most compilers do not include information
about preprocessor macros in the debugging information if you specify
the -g flag alone. Version 3.1 and later of GCC,
the GNU C compiler, provides macro information if you are using
the DWARF debugging format, and specify the option -g3.

See Options for Debugging Your Program or GCC in Using the GNU Compiler Collection (GCC), for more
information on GCC 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 GDB.

4.2 Starting your Program

run

r

Use the run command to start your program under GDB.
You must first specify the program name with an argument to
GDB (see Getting In and Out of
GDB), or by using the file or exec-file
command (see Commands to Specify Files).

If you are running your program in an execution environment that
supports processes, run creates an inferior process and makes
that process run your program. In some environments without processes,
run jumps to the start of your program. Other targets,
like ‘remote’, are always running. If you get an error
message like this one:

The "remote" target does not support "run".
Try "help target" or "continue".

then use continue to run your program. You may need load
first (see load).

The execution of a program is affected by certain information it
receives from its superior. GDB provides ways to specify this
information, which you must do 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:

The arguments.

Specify the arguments to give your program as the arguments of the
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
SHELL environment variable. If you do not define SHELL,
GDB uses the default shell (/bin/sh). You can disable
use of any shell with the set startup-with-shell command (see
below for details).

The environment.

Your program normally inherits its environment from GDB, but you can
use the GDB commands set environment and unset
environment to change parts of the environment that affect
your program. See Your Program’s Environment.

The working directory.

You can set your program’s working directory with the command
set cwd. If you do not set any working directory with this
command, your program will inherit GDB’s working directory if
native debugging, or the remote server’s working directory if remote
debugging. See Your Program’s Working
Directory.

The standard input and output.

Your program normally uses the same device for standard input and
standard output as GDB is using. You can redirect input and output
in the run command line, or you can use the tty command to
set a different device for your program.
See Your Program’s Input and Output.

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, GDB is likely to wind up debugging the
wrong program.

When you issue the run command, your program begins to execute
immediately. See 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 print
or call commands. See Examining Data.

If the modification time of your symbol file has changed since the last
time GDB read its symbols, GDB discards its symbol
table, and reads it again. When it does this, GDB tries to retain
your current breakpoints.

start

The name of the main procedure can vary from language to language.
With C or C++, the main procedure name is always 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 ‘start’ command does the equivalent of setting a temporary
breakpoint at the beginning of the main procedure and then invoking
the ‘run’ command.

Some programs contain an 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++, for instance,
constructors for static and global objects are executed before
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
‘start’ command. These arguments will be given verbatim to the
underlying ‘run’ command. Note that the same arguments will be
reused if no argument is provided during subsequent calls to
‘start’ or ‘run’.

It is sometimes necessary to debug the program during elaboration. In
these cases, using the 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 starti command.

starti

The ‘starti’ command does the equivalent of setting a temporary
breakpoint at the first instruction of a program’s execution and then
invoking the ‘run’ command. For programs containing an
elaboration phase, the starti command will stop execution at
the start of the elaboration phase.

set exec-wrapper wrapper

show exec-wrapper

unset exec-wrapper

When ‘exec-wrapper’ is set, the specified wrapper is used to
launch programs for debugging. GDB starts your program
with a shell command of the form exec wrapper
program. Quoting is added to program and its
arguments, but not to wrapper, so you should add quotes if
appropriate for your shell. The wrapper runs until it executes
your program, and then GDB takes control.

You can use any program that eventually calls execve with
its arguments as a wrapper. Several standard Unix utilities do
this, e.g. env and nohup. Any Unix shell script ending
with exec "$@" will also work.

For example, you can use env to pass an environment variable to
the debugged program, without setting the variable in your shell’s
environment:

(gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so'
(gdb) run

This command is available when debugging locally on most targets, excluding
DJGPP, Cygwin, MS Windows, and QNX Neutrino.

set startup-with-shell

set startup-with-shell on

set startup-with-shell off

show startup-with-shell

On Unix systems, by default, if a shell is available on your target,
GDB) uses it to start your program. Arguments of the
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:

(gdb) run
Starting program: ./a.out
During startup program terminated with signal SIGSEGV, Segmentation fault.

which indicates the shell or the wrapper specified with
‘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 .cshrc for C-shell,
$.zshenv for the Z shell, or the file specified in the
BASH_ENV environment variable for BASH.

set auto-connect-native-target

set auto-connect-native-target on

set auto-connect-native-target off

show auto-connect-native-target

By default, if the current inferior is not connected to any target yet
(e.g., with target remote), the run command starts your
program as a native process under GDB, on your local machine.
If you’re sure you don’t want to debug programs on your local machine,
you can tell GDB to not connect to the native target
automatically with the set auto-connect-native-target off
command.

If on, which is the default, and if the current inferior is not
connected to a target already, the run command automaticaly
connects to the native target, if one is available.

If off, and if the current inferior is not connected to a
target already, the run command fails with an error:

(gdb) run
Don't know how to run.  Try "help target".

If the current inferior is already connected to a target, GDB
always uses it with the run command.

In any case, you can explicitly connect to the native target with the
target native command. For example,

(gdb) set auto-connect-native-target off
(gdb) run
Don't know how to run.  Try "help target".
(gdb) target native
(gdb) run
Starting program: ./a.out
[Inferior 1 (process 10421) exited normally]

In case you connected explicitly to the native target,
GDB remains connected even if all inferiors exit, ready for
the next run command. Use the disconnect command to
disconnect.

Examples of other commands that likewise respect the
auto-connect-native-target setting: attach, info
proc, info os.

set disable-randomization

set disable-randomization on

This option (enabled by default in GDB) 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 GNU/Linux.
On GNU/Linux you can get the same behavior using

(gdb) set exec-wrapper setarch `uname -m` -R

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 GDB, that might be because
GDB by default disables the address randomization on platforms, such
as GNU/Linux, which do that for stand-alone programs. Use 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 gcc -fPIE -pie.

Heap (malloc storage), stack and custom mmap areas are always placed randomly
(as long as the randomization is enabled).

show disable-randomization

Show the current setting of the explicit disable of the native randomization of
the virtual address space of the started program.

4.3 Your Program’s Arguments

The arguments to your program can be specified by the arguments of the
run command.
They are passed to a shell, which expands wildcard characters and
performs redirection of I/O, and thence to your program. Your
SHELL environment variable (if it exists) specifies what shell
GDB uses. If you do not define SHELL, GDB uses
the default shell (/bin/sh on Unix).

On non-Unix systems, the program is usually invoked directly by
GDB, 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.

run with no arguments uses the same arguments used by the previous
run, or those set by the set args command.

set args

Specify the arguments to be used the next time your program is run. If
set args has no arguments, run executes your program
with no arguments. Once you have run your program with arguments,
using set args before the next run is the only way to run
it again without arguments.

show args

Show the arguments to give your program when it is started.

4.4 Your Program’s Environment

The 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 GDB over again.

path directory

Add directory to the front of the PATH environment variable
(the search path for executables) that will be passed to your program.
The value of PATH used by GDB does not change.
You may specify several directory names, separated by whitespace or by a
system-dependent separator character (‘:’ on Unix, ‘;’ on
MS-DOS and MS-Windows). If directory is already in the path, it
is moved to the front, so it is searched sooner.

You can use the string ‘$cwd’ to refer to whatever is the current
working directory at the time GDB searches the path. If you
use ‘.’ instead, it refers to the directory where you executed the
path command. GDB replaces ‘.’ in the
directory argument (with the current path) before adding
directory to the search path.

show paths

Display the list of search paths for executables (the PATH
environment variable).

show environment [varname]

Print the value of environment variable varname to be given to
your program when it starts. If you do not supply varname,
print the names and values of all environment variables to be given to
your program. You can abbreviate environment as env.

set environment varname [=value]

Set environment variable varname to value. The value
changes for your program (and the shell GDB uses to launch
it), not for GDB itself. The value may be any string; the
values of environment variables are just strings, and any
interpretation is supplied by your program itself. The value
parameter is optional; if it is eliminated, the variable is set to a
null value.

For example, this command:

tells the debugged program, when subsequently run, that its user is named
‘foo’. (The spaces around ‘=’ are used for clarity here; they
are not actually required.)

Note that on Unix systems, GDB runs your program via a shell,
which also inherits the environment set with set environment.
If necessary, you can avoid that by using the ‘env’ program as a
wrapper instead of using set environment. See set exec-wrapper, for an example doing just that.

Environment variables that are set by the user are also transmitted to
gdbserver to be used when starting the remote inferior.
see QEnvironmentHexEncoded.

unset environment varname

Remove variable varname from the environment to be passed to your
program. This is different from ‘set env varname =’;
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
gdbserver when starting the remote inferior.
see QEnvironmentUnset.

Warning: On Unix systems, GDB runs your program using
the shell indicated by your SHELL environment variable if it
exists (or /bin/sh if not). If your SHELL variable
names a shell that runs an initialization file when started
non-interactively—such as .cshrc for C-shell, $.zshenv
for the Z shell, or the file specified in the 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
.login or .profile.

4.5 Your Program’s Working Directory

Each time you start your program with run, the inferior will be
initialized with the current working directory specified by the
set cwd command. If no directory has been specified by this
command, then the inferior will inherit GDB’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.

set cwd [directory]

Set the inferior’s working directory to directory, which will be
glob-expanded in order to resolve tildes (~). If no
argument has been specified, the command clears the setting and resets
it to an empty state. This setting has no effect on GDB’s
working directory, and it only takes effect the next time you start
the inferior. The ~ in directory is a short for the
home directory, usually pointed to by the HOME environment
variable. On MS-Windows, if HOME is not defined, GDB
uses the concatenation of HOMEDRIVE and HOMEPATH as
fallback.

You can also change GDB’s current working directory by using
the cd command.
See cd command.

show cwd

Show the inferior’s working directory. If no directory has been
specified by set cwd, then the default inferior’s working
directory is the same as GDB’s working directory.

cd [directory]

Set the GDB working directory to directory. If not
given, directory uses ‘~’.

The GDB working directory serves as a default for the
commands that specify files for GDB to operate on.
See Commands to Specify Files.
See set cwd command.

pwd

Print the GDB working directory.

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 GDB supports
the info proc command (see Process Information), you can
use the info proc command to find out the
current working directory of the debuggee.

4.6 Your Program’s Input and Output

By default, the program you run under GDB does input and output to
the same terminal that GDB uses. GDB 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.

info terminal

Displays information recorded by GDB about the terminal modes your
program is using.

You can redirect your program’s input and/or output using shell
redirection with the run command. For example,

starts your program, diverting its output to the file outfile.

Another way to specify where your program should do input and output is
with the tty command. This command accepts a file name as
argument, and causes this file to be the default for future run
commands. It also resets the controlling terminal for the child
process, for future run commands. For example,

directs that processes started with subsequent run commands
default to do input and output on the terminal /dev/ttyb and have
that as their controlling terminal.

An explicit redirection in run overrides the tty command’s
effect on the input/output device, but not its effect on the controlling
terminal.

When you use the tty command or redirect input in the run
command, only the input for your program is affected. The input
for GDB still comes from your terminal. tty is an alias
for set inferior-tty.

You can use the show inferior-tty command to tell GDB to
display the name of the terminal that will be used for future runs of your
program.

set inferior-tty [ tty ]

Set the tty for the program being debugged to tty. Omitting tty
restores the default behavior, which is to use the same terminal as
GDB.

show inferior-tty

Show the current tty for the program being debugged.

4.7 Debugging an Already-running Process

attach process-id

This command attaches to a running process—one that was started
outside GDB. (info files shows your active
targets.) The command takes as argument a process ID. The usual way to
find out the process-id of a Unix process is with the ps utility,
or with the ‘jobs -l’ shell command.

attach does not repeat if you press RET a second time after
executing the command.

To use attach, your program must be running in an environment
which supports processes; for example, 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 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
(see Specifying Source Directories). You can also use
the file command to load the program. See Commands to
Specify Files.

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 GDB, the option exec-file-mismatch specifies how to
handle the mismatch. GDB tries to compare the files by
comparing their build IDs (see build ID), if available.

set exec-file-mismatch ‘ask|warn|off’

Whether to detect mismatch between the current executable file loaded
by GDB and the executable file used to start the process. If
‘ask’, the default, display a warning and ask the user whether to
load the process executable file; if ‘warn’, just display a
warning; if ‘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.

show exec-file-mismatch

Show the current value of exec-file-mismatch.

The first thing GDB does after arranging to debug the specified
process is to stop it. You can examine and modify an attached process
with all the GDB commands that are ordinarily available when
you start processes with 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 continue command after
attaching GDB to the process.

detach

When you have finished debugging the attached process, you can use the
detach command to release it from GDB control. Detaching
the process continues its execution. After the detach command,
that process and GDB become completely independent once more, and you
are ready to attach another process or start one with run.
detach does not repeat if you press RET again after
executing the command.

If you exit GDB while you have an attached process, you detach
that process. If you use the run command, you kill that process.
By default, GDB 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
set confirm command (see Optional Warnings and
Messages).

4.8 Killing the Child Process

kill

Kill the child process in which your program is running under GDB.

This command is useful if you wish to debug a core dump instead of a
running process. GDB ignores any core dump file while your program
is running.

On some operating systems, a program cannot be executed outside GDB
while you have breakpoints set on it inside GDB. You can use the
kill command in this situation to permit running your program
outside the debugger.

The 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 run, GDB notices that the file has changed, and
reads the symbol table again (while trying to preserve your current
breakpoint settings).

4.9 Debugging Multiple Inferiors Connections and Programs

GDB lets you run and debug multiple programs in a single
session. In addition, GDB on some systems may let you run
several programs simultaneously (otherwise you have to exit from one
before starting another). On some systems GDB 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.

GDB represents the state of each program execution with an
object called an 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 info inferiors:

info inferiors

Print a list of all inferiors currently being managed by GDB.
By default all inferiors are printed, but the argument id…
– a space separated list of inferior numbers – can be used to limit
the display to just the requested inferiors.

GDB displays for each inferior (in this order):

1. the inferior number assigned by GDB
2. the target system’s inferior identifier
3. the target connection the inferior is bound to, including the unique
   connection number assigned by GDB, and the protocol used by
   the connection.

4. the name of the executable the inferior is running.

An asterisk ‘*’ preceding the GDB inferior number
indicates the current inferior.

For example,

(gdb) info inferiors
  Num  Description       Connection                      Executable
* 1    process 3401      1 (native)                      goodbye
  2    process 2307      2 (extended-remote host:10000)  hello

To get informations about the current inferior, use inferior:

inferior

Shows information about the current inferior.

For example,

(gdb) inferior
[Current inferior is 1 [process 3401] (helloworld)]

To find out what open target connections exist at any moment, use
info connections:

info connections

Print a list of all open target connections currently being managed by
GDB. By default all connections are printed, but the
argument id… – a space separated list of connections
numbers – can be used to limit the display to just the requested
connections.

GDB displays for each connection (in this order):

1. the connection number assigned by GDB.
2. the protocol used by the connection.
3. a textual description of the protocol used by the connection.

An asterisk ‘*’ preceding the connection number indicates the
connection of the current inferior.

For example,

(gdb) 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

To switch focus between inferiors, use the inferior command:

inferior infno

Make inferior number infno the current inferior. The argument
infno is the inferior number assigned by GDB, as shown
in the first field of the ‘info inferiors’ display.

The debugger convenience variable ‘$_inferior’ contains the
number of the current inferior. You may find this useful in writing
breakpoint conditional expressions, command scripts, and so forth.
See Convenience Variables, for general
information on convenience variables.

You can get multiple executables into a debugging session via the
add-inferior and clone-inferior commands. On some
systems GDB can add inferiors to the debug session
automatically by following calls to fork and exec. To
remove inferiors from the debugging session use the
remove-inferiors command.

add-inferior [ -copies n ] [ -exec executable ] [-no-connection ]

Adds n inferiors to be run using executable as the
executable; 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
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 gdbserver with target remote,
then the new inferior will be connected to the same gdbserver
instance. The ‘-no-connection’ option starts the new inferior
with no connection yet. You can then for example use the target
remote command to connect to some other gdbserver instance,
use run to spawn a local program, etc.

clone-inferior [ -copies n ] [ infno ]

Adds n inferiors ready to execute the same program as inferior
infno; n defaults to 1, and infno defaults to the
number of the current inferior. This command copies the values of the
args, inferior-tty and cwd properties from the
current inferior to the new one. It also propagates changes the user
made to environment variables using the set environment and
unset environment commands. This is a convenient command
when you want to run another instance of the inferior you are debugging.

(gdb) info inferiors
  Num  Description       Connection   Executable
* 1    process 29964     1 (native)   helloworld
(gdb) clone-inferior
Added inferior 2.
1 inferiors added.
(gdb) info inferiors
  Num  Description       Connection   Executable
* 1    process 29964     1 (native)   helloworld
  2    <null>            1 (native)   helloworld

You can now simply switch focus to inferior 2 and run it.

remove-inferiors infno…

Removes the inferior or inferiors infno…. It is not
possible to remove an inferior that is running with this command. For
those, use the kill or detach command first.

To quit debugging one of the running inferiors that is not the current
inferior, you can either detach from it by using the detach inferior command (allowing it to run independently), or kill it
using the kill inferiors command:

detach inferior infno…

Detach from the inferior or inferiors identified by GDB
inferior number(s) infno…. Note that the inferior’s entry
still stays on the list of inferiors shown by info inferiors,
but its Description will show ‘<null>’.

kill inferiors infno…

Kill the inferior or inferiors identified by GDB inferior
number(s) infno…. Note that the inferior’s entry still
stays on the list of inferiors shown by info inferiors, but its
Description will show ‘<null>’.

After the successful completion of a command such as detach,
detach inferiors, kill or kill inferiors, or after
a normal process exit, the inferior is still valid and listed with
info inferiors, ready to be restarted.

To be notified when inferiors are started or exit under GDB’s
control use set print inferior-events:

set print inferior-events

set print inferior-events on

set print inferior-events off

The set print inferior-events command allows you to enable or
disable printing of messages when GDB notices that new
inferiors have started or that inferiors have exited or have been
detached. By default, these messages will be printed.

show print inferior-events

Show whether messages will be printed when GDB detects that
inferiors have started, exited or have been detached.

Many commands will work the same with multiple programs as with a
single program: e.g., print myglobal will simply display the
value of myglobal in the current inferior.

Occasionally, when debugging GDB 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 maint info program-spaces command.

maint info program-spaces

Print a list of all program spaces currently being managed by
GDB.

GDB displays for each program space (in this order):

1. the program space number assigned by GDB
2. the name of the executable loaded into the program space, with e.g.,
   the file command.

3. the name of the core file loaded into the program space, with e.g.,
   the core-file command.

An asterisk ‘*’ preceding the GDB program space number
indicates the current program space.

In addition, below each program space line, GDB prints extra
information that isn’t suitable to display in tabular form. For
example, the list of inferiors bound to the program space.

(gdb) maint info program-spaces
  Id   Executable        Core File
* 1    hello
  2    goodbye
        Bound inferiors: ID 1 (process 21561)

Here we can see that no inferior is running the program hello,
while process 21561 is running the program 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 vfork call. For example,

(gdb) maint info program-spaces
  Id   Executable        Core File
* 1    vfork-test
        Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)

Here, both inferior 2 and inferior 1 are running in the same program
space as a result of inferior 1 having executed a vfork call.

4.10 Debugging Programs with Multiple Threads

In some operating systems, such as GNU/Linux and Solaris, a single program
may have more than one 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.

GDB provides these facilities for debugging multi-thread
programs:

• automatic notification of new threads
• ‘thread thread-id’, a command to switch among threads
• ‘info threads’, a command to inquire about existing threads
• ‘thread apply [thread-id-list | all] args’,
  a command to apply a command to a list of threads
• thread-specific breakpoints
• ‘set print thread-events’, which controls printing of
  messages on thread start and exit.
• ‘set libthread-db-search-path path’, which lets
  the user specify which libthread_db to use if the default choice
  isn’t compatible with the program.

The GDB thread debugging facility allows you to observe all
threads while your program runs—but whenever GDB takes
control, one thread in particular is always the focus of debugging.
This thread is called the current thread. Debugging commands show
program information from the perspective of the current thread.

Whenever GDB detects a new thread in your program, it displays
the target system’s identification for the thread with a message in the
form ‘[New systag]’, where systag is a thread identifier
whose form varies depending on the particular system. For example, on
GNU/Linux, you might see

[New Thread 0x41e02940 (LWP 25582)]

when GDB notices a new thread. In contrast, on other systems,
the systag is simply something like ‘process 368’, with no
further qualifier.

For debugging purposes, GDB 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.

You can refer to a given thread in an inferior using the qualified
inferior-num.thread-num syntax, also known as
qualified thread ID, with inferior-num being the inferior
number and thread-num being the thread number of the given
inferior. For example, thread 2.3 refers to thread number 3 of
inferior 2. If you omit inferior-num (e.g., thread 3),
then GDB infers you’re referring to a thread of the current
inferior.

Until you create a second inferior, GDB does not show the
inferior-num part of thread IDs, even though you can always use
the full inferior-num.thread-num form to refer to threads
of inferior 1, the initial inferior.

Some commands accept a space-separated thread ID list as
argument. A list element can be:

1. A thread ID as shown in the first field of the ‘info threads’
   display, with or without an inferior qualifier. E.g., ‘2.1’ or
   ‘1’.

2. A range of thread numbers, again with or without an inferior
   qualifier, as in inf.thr1—thr2 or
   thr1—thr2. E.g., ‘1.2-4’ or ‘2-4’.

3. All threads of an inferior, specified with a star wildcard, with or
   without an inferior qualifier, as in inf.* (e.g.,
   ‘1.*’) or *. 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.

For example, if the current inferior is 1, and inferior 7 has one
thread with ID 7.1, the thread list ‘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 ‘1.1 1.2 1.3 4.5 6.7 6.8 6.9
7.1’.

In addition to a per-inferior number, each thread is also
assigned a unique global number, also known as 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 GDB’s perspective, a process always has at least one
thread. In other words, GDB assigns a thread number to the
program’s “main thread” even if the program is not multi-threaded.

The debugger convenience variables ‘$_thread’ and
‘$_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. The convenience variable ‘$_inferior_thread_count’
contains the number of live threads in the current inferior.
See Convenience Variables, for general
information on convenience variables.

When running in non-stop mode (see Non-Stop Mode), where new
threads can be created, and existing threads exit, at any time,
‘$_inferior_thread_count’ could return a different value each
time it is evaluated.

If GDB 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.

Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68

Likewise when the program receives a signal:

Thread 1 "main" received signal SIGINT, Interrupt.

info threads [thread-id-list]

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
(see thread ID lists).

GDB displays for each thread (in this order):

1. the per-inferior thread number assigned by GDB
2. the global thread number assigned by GDB, if the ‘-gid’
   option was specified

3. the target system’s thread identifier (systag)
4. the thread’s name, if one is known. A thread can either be named by
   the user (see thread name, below), or, in some cases, by the
   program itself.

5. the current stack frame summary for that thread

An asterisk ‘*’ to the left of the GDB thread number
indicates the current thread.

For example,

(gdb) 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

If you’re debugging multiple inferiors, GDB displays thread
IDs using the qualified inferior-num.thread-num format.
Otherwise, only thread-num is shown.

If you specify the ‘-gid’ option, GDB displays a column
indicating each thread’s global thread ID:

(gdb) 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)

On Solaris, you can display more information about user threads with a
Solaris-specific command:

maint info sol-threads

Display info on Solaris user threads.

thread thread-id

Make thread ID thread-id the current thread. The command
argument thread-id is the GDB thread ID, as shown in
the first field of the ‘info threads’ display, with or without an
inferior qualifier (e.g., ‘2.1’ or ‘1’).

GDB responds by displaying the system identifier of the
thread you selected, and its current stack frame summary:

(gdb) thread 2
[Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))]
#0  some_function (ignore=0x0) at example.c:8
8	    printf ("hellon");

As with the ‘[New …]’ message, the form of the text after
‘Switching to’ depends on your system’s conventions for identifying
threads.

thread apply [thread-id-list | all [-ascending]] [flag]… command

The thread apply command allows you to apply the named
command to one or more threads. Specify the threads that you
want affected using the thread ID list syntax (see thread ID lists), or specify all to apply to all threads. To apply a
command to all threads in descending order, type thread apply all
command. To apply a command to all threads in ascending order,
type thread apply all -ascending command.

The flag arguments control what output to produce and how to handle
errors raised when applying command to a thread. flag
must start with a - directly followed by one letter in
qcs. If several flags are provided, they must be given
individually, such as -c -q.

By default, GDB displays some thread information before the
output produced by command, and an error raised during the
execution of a command will abort thread apply. The
following flags can be used to fine-tune this behavior:

-c

The flag -c, which stands for ‘continue’, causes any
errors in command to be displayed, and the execution of
thread apply then continues.

-s

The flag -s, which stands for ‘silent’, causes any errors
or empty output produced by a command to be silently ignored.
That is, the execution continues, but the thread information and errors
are not printed.

-q

The flag -q (‘quiet’) disables printing the thread
information.

Flags -c and -s cannot be used together.

taas [option]… command

Shortcut for thread apply all -s [option]… command.
Applies command on all threads, ignoring errors and empty output.

The taas command accepts the same options as the thread
apply all command. See thread apply all.

tfaas [option]… command

Shortcut for thread apply all -s -- frame apply all -s [option]… command.
Applies command on all frames of all threads, ignoring errors
and empty output. Note that the flag -s is specified twice:
The first -s ensures that thread apply only shows the thread
information of the threads for which frame apply produces
some output. The second -s is needed to ensure that frame
apply shows the frame information of a frame only if the
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:

(gdb) tfaas p some_local_var_i_do_not_remember_where_it_is

The tfaas command accepts the same options as the frame
apply command. See frame apply.

thread name [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 ‘info threads’ display.

On some systems, such as GNU/Linux, GDB is able to
determine the name of the thread as given by the OS. On these
systems, a name specified with ‘thread name’ will override the
system-give name, and removing the user-specified name will cause
GDB to once again display the system-specified name.

thread find [regexp]

Search for and display thread ids whose name or systag
matches the supplied regular expression.

As well as being the complement to the ‘thread name’ command,
this command also allows you to identify a thread by its target
systag. For instance, on GNU/Linux, the target systag
is the LWP id.

(GDB) thread find 26688
Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
(GDB) info thread 4
  Id   Target Id         Frame 
  4    Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()

set print thread-events

set print thread-events on

set print thread-events off

The set print thread-events command allows you to enable or
disable printing of messages when GDB 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.

show print thread-events

Show whether messages will be printed when GDB detects that threads
have started and exited.

See Stopping and Starting Multi-thread Programs, for
more information about how GDB behaves when you stop and start
programs with multiple threads.

See Setting Watchpoints, for information about
watchpoints in programs with multiple threads.

set libthread-db-search-path [path]

If this variable is set, path is a colon-separated list of
directories GDB will use to search for libthread_db.
If you omit path, ‘libthread-db-search-path’ will be reset to
its default value ($sdir:$pdir on GNU/Linux and Solaris systems).
Internally, the default value comes from the LIBTHREAD_DB_SEARCH_PATH
macro.

On GNU/Linux and Solaris systems, GDB uses a “helper”
libthread_db library to obtain information about threads in the
inferior process. GDB will use ‘libthread-db-search-path’
to find libthread_db. GDB also consults first if inferior
specific thread debugging library loading is enabled
by ‘set auto-load libthread-db’ (see libthread_db.so.1 file).

A special entry ‘$sdir’ for ‘libthread-db-search-path’
refers to the default system directories that are
normally searched for loading shared libraries. The ‘$sdir’ entry
is the only kind not needing to be enabled by ‘set auto-load libthread-db’
(see libthread_db.so.1 file).

A special entry ‘$pdir’ for ‘libthread-db-search-path’
refers to the directory from which libpthread
was loaded in the inferior process.

For any libthread_db library GDB finds in above directories,
GDB attempts to initialize it with the current inferior process.
If this initialization fails (which could happen because of a version
mismatch between libthread_db and libpthread), GDB
will unload libthread_db, and continue with the next directory.
If none of libthread_db libraries initialize successfully,
GDB will issue a warning and thread debugging will be disabled.

Setting libthread-db-search-path is currently implemented
only on some platforms.

show libthread-db-search-path

Display current libthread_db search path.

set debug libthread-db

show debug libthread-db

Turns on or off display of libthread_db-related events.
Use 1 to enable, 0 to disable.

set debug threads [on|off]

show debug threads

When ‘on’ GDB will print additional messages when
threads are created and deleted.

4.11 Debugging Forks

On most systems, GDB has no special support for debugging
programs which create additional processes using the fork
function. When a program forks, GDB 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 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 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 GDB
on the child. While the child is sleeping, use the ps program to
get its process ID. Then tell GDB (a new invocation of
GDB if you are also debugging the parent process) to attach to
the child process (see Attach). From that point on you can debug
the child process just like any other process which you attached to.

On some systems, GDB provides support for debugging programs
that create additional processes using the fork or vfork
functions. On 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 gdbserver in either target remote mode or
target extended-remote mode.

By default, when a program forks, GDB 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 set follow-fork-mode.

set follow-fork-mode mode

Set the debugger response to a program call of fork or
vfork. A call to fork or vfork creates a new
process. The mode argument can be:

parent

The original process is debugged after a fork. The child process runs
unimpeded. This is the default.

child

The new process is debugged after a fork. The parent process runs
unimpeded.

show follow-fork-mode

Display the current debugger response to a fork or vfork call.

On Linux, if you want to debug both the parent and child processes, use the
command set detach-on-fork.

set detach-on-fork mode

Tells gdb whether to detach one of the processes after a fork, or
retain debugger control over them both.

on

The child process (or parent process, depending on the value of
follow-fork-mode) will be detached and allowed to run
independently. This is the default.

off

Both processes will be held under the control of GDB.
One process (child or parent, depending on the value of
follow-fork-mode) is debugged as usual, while the other
is held suspended.

show detach-on-fork

Show whether detach-on-fork mode is on/off.

If you choose to set ‘detach-on-fork’ mode off, then GDB
will retain control of all forked processes (including nested forks).
You can list the forked processes under the control of GDB by
using the info inferiors command, and switch from one fork
to another by using the inferior command (see Debugging Multiple Inferiors Connections and Programs).

To quit debugging one of the forked processes, you can either detach
from it by using the detach inferiors command (allowing it
to run independently), or kill it using the kill inferiors
command. See Debugging
Multiple Inferiors Connections and Programs.

If you ask to debug a child process and a vfork is followed by an
exec, GDB executes the new target up to the first
breakpoint in the new target. If you have a breakpoint set on
main in your original program, the breakpoint will also be set on
the child process’s main.

On some systems, when a child process is spawned by vfork, you
cannot debug the child or parent until an exec call completes.

If you issue a run command to GDB after an exec
call executes, the new target restarts. To restart the parent
process, use the file command with the parent executable name
as its argument. By default, after an exec call executes,
GDB discards the symbols of the previous executable image.
You can change this behaviour with the set follow-exec-mode
command.

set follow-exec-mode mode

Set debugger response to a program call of exec. An
exec call replaces the program image of a process.

follow-exec-mode can be:

new

GDB creates a new inferior and rebinds the process to this
new inferior. The program the process was running before the
exec call can be restarted afterwards by restarting the
original inferior.

For example:

(gdb) info inferiors
(gdb) info inferior
  Id   Description   Executable
* 1    <null>        prog1
(gdb) run
process 12020 is executing new program: prog2
Program exited normally.
(gdb) info inferiors
  Id   Description   Executable
  1    <null>        prog1
* 2    <null>        prog2

same

GDB 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 exec call, with
e.g., the run command, restarts the executable the process was
running after the exec call. This is the default mode.

For example:

(gdb) info inferiors
  Id   Description   Executable
* 1    <null>        prog1
(gdb) run
process 12020 is executing new program: prog2
Program exited normally.
(gdb) info inferiors
  Id   Description   Executable
* 1    <null>        prog2

follow-exec-mode is supported in native mode and
target extended-remote mode.

You can use the catch command to make GDB stop whenever
a fork, vfork, or exec call is made. See Setting Catchpoints.

4.12 Setting a Bookmark to Return to Later

On certain operating systems⁴, GDB is able to save a snapshot of a
program’s state, called a checkpoint, and come back to it
later.

Returning to a checkpoint effectively undoes everything that has
happened in the program since the 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 checkpoint/restart method of debugging:

checkpoint

Save a snapshot of the debugged program’s current execution state.
The checkpoint command takes no arguments, but each checkpoint
is assigned a small integer id, similar to a breakpoint id.

info checkpoints

List the checkpoints that have been saved in the current debugging
session. For each checkpoint, the following information will be
listed:

Checkpoint ID

Process ID

Code Address

Source line, or label

restart checkpoint-id

Restore the program state that was saved as checkpoint number
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, GDB 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.

delete checkpoint checkpoint-id

Delete the previously-saved checkpoint identified by checkpoint-id.

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.

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 pid),
and each will be different from the program’s original pid.
If your program has saved a local copy of its process id, this could
potentially pose a problem.

4.12.1 A Non-obvious Benefit of Using Checkpoints

On some systems such as 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 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.

5 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 GDB, your program may stop for any of several reasons,
such as a signal, a breakpoint, or reaching a new line after a
GDB command such as step. You may then examine and
change variables, set new breakpoints or remove old ones, and then
continue execution. Usually, the messages shown by GDB provide
ample explanation of the status of your program—but you can also
explicitly request this information at any time.

info program

Display information about the status of your program: whether it is
running or not, what process it is, and why it stopped.

5.1 Breakpoints, Watchpoints, and Catchpoints

A 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 your program stops. You can set
breakpoints with the break command and its variants (see Setting Breakpoints), to specify the place where your program
should stop by line number, function name or exact address in the
program.

On some systems, you can set breakpoints in shared libraries before
the executable is run.

A watchpoint is a special breakpoint that stops your program
when the value of an expression changes. The expression may be a value
of a variable, or it could involve values of one or more variables
combined by operators, such as ‘a + b’. This is sometimes called
data breakpoints. You must use a different command to set
watchpoints (see Setting Watchpoints), but aside
from that, you can manage a watchpoint like any other breakpoint: you
enable, disable, and delete both breakpoints and watchpoints using the
same commands.

You can arrange to have values from your program displayed automatically
whenever GDB stops at a breakpoint. See Automatic Display.

A catchpoint is another special breakpoint that stops your program
when a certain kind of event occurs, such as the throwing of a C++
exception or the loading of a library. As with watchpoints, you use a
different command to set a catchpoint (see Setting
Catchpoints), but aside from that, you can manage a catchpoint like any
other breakpoint. (To stop when your program receives a signal, use the
handle command; see Signals.)

GDB assigns a number to each breakpoint, watchpoint, or
catchpoint when you create it; these numbers are successive integers
starting with one. In many of the commands for controlling various
features of breakpoints you use the breakpoint number to say which
breakpoint you want to change. Each breakpoint may be enabled or
disabled; if disabled, it has no effect on your program until you
enable it again.

Some GDB commands accept a space-separated list of breakpoints
on which to operate. A list element can be either a single breakpoint number,
like ‘5’, or a range of such numbers, like ‘5-7’.
When a breakpoint list is given to a command, all breakpoints in that list
are operated on.

5.1.1 Setting Breakpoints

Breakpoints are set with the break command (abbreviated
b). The debugger convenience variable ‘$bpnum’ records the
number of the breakpoint you’ve set most recently:

(gdb) b main
Breakpoint 1 at 0x11c6: file zeoes.c, line 24.
(gdb) p $bpnum
$1 = 1

A breakpoint may be mapped to multiple code locations for example with
inlined functions, Ada generics, C++ templates or overloaded function names.
GDB then indicates the number of code locations in the breakpoint
command output:

(gdb) b some_func
Breakpoint 2 at 0x1179: some_func. (3 locations)
(gdb) p $bpnum
$2 = 2
(gdb)

When your program stops on a breakpoint, the convenience variables
‘$_hit_bpnum’ and ‘$_hit_locno’ are respectively set to the number of
the encountered breakpoint and the number of the breakpoint’s code location:

Thread 1 "zeoes" hit Breakpoint 2.1, some_func () at zeoes.c:8
8	  printf("some funcn");
(gdb) p $_hit_bpnum
$5 = 2
(gdb) p $_hit_locno
$6 = 1
(gdb)

Note that ‘$_hit_bpnum’ and ‘$bpnum’ are not equivalent:
‘$_hit_bpnum’ is set to the breakpoint number last hit, while
‘$bpnum’ is set to the breakpoint number last set.

If the encountered breakpoint has only one code location, ‘$_hit_locno’
is set to 1:

Breakpoint 1, main (argc=1, argv=0x7fffffffe018) at zeoes.c:24
24	  if (argc > 1)
(gdb) p $_hit_bpnum
$3 = 1
(gdb) p $_hit_locno
$4 = 1
(gdb)

The ‘$_hit_bpnum’ and ‘$_hit_locno’ variables can typically be used
in a breakpoint command list.
(see Breakpoint Command Lists). For example, as
part of the breakpoint command list, you can disable completely the
encountered breakpoint using disable $_hit_bpnum or disable the
specific encountered breakpoint location using
disable $_hit_bpnum.$_hit_locno.
If a breakpoint has only one location, ‘$_hit_locno’ is set to 1
and the commands disable $_hit_bpnum and
disable $_hit_bpnum.$_hit_locno both disable the breakpoint.

You can also define aliases to easily disable the last hit location or
last hit breakpoint:

(gdb) alias lld = disable $_hit_bpnum.$_hit_locno
(gdb) alias lbd = disable $_hit_bpnum

break locspec

Set a breakpoint at all the code locations in your program that result
from resolving the given locspec. locspec can specify a
function name, a line number, an address of an instruction, and more.
See Location Specifications, for the various forms of
locspec. The breakpoint will stop your program just before it
executes the instruction at the address of any of the breakpoint’s
code locations.

When using source languages that permit overloading of symbols, such
as C++, a function name may refer to more than one symbol, and
thus more than one place to break. See Ambiguous Expressions, for a discussion of that
situation.

It is also possible to insert a breakpoint that will stop the program
only if a specific thread (see Thread-Specific Breakpoints)
or a specific task (see Ada Tasks) hits that breakpoint.

break

When called without any arguments, break sets a breakpoint at
the next instruction to be executed in the selected stack frame
(see Examining the Stack). In any selected frame but the
innermost, this makes your program stop as soon as control
returns to that frame. This is similar to the effect of a
finish command in the frame inside the selected frame—except
that finish does not leave an active breakpoint. If you use
break without an argument in the innermost frame, GDB stops
the next time it reaches the current location; this may be useful
inside loops.

GDB normally ignores breakpoints when it resumes execution, until at
least one instruction has been executed. If it did not do this, you
would be unable to proceed past a breakpoint without first disabling the
breakpoint. This rule applies whether or not the breakpoint already
existed when your program stopped.

break … if cond

Set a breakpoint with condition cond; evaluate the expression
cond each time the breakpoint is reached, and stop only if the
value is nonzero—that is, if cond evaluates as true.
‘…’ stands for one of the possible arguments described
above (or no argument) specifying where to break. See Break Conditions, for more information on breakpoint conditions.

The breakpoint may be mapped to multiple locations. If the breakpoint
condition cond is invalid at some but not all of the locations,
the locations for which the condition is invalid are disabled. For
example, GDB reports below that two of the three locations
are disabled.

(gdb) break func if a == 10
warning: failed to validate condition at location 0x11ce, disabling:
  No symbol "a" in current context.
warning: failed to validate condition at location 0x11b6, disabling:
  No symbol "a" in current context.
Breakpoint 1 at 0x11b6: func. (3 locations)

Locations that are disabled because of the condition are denoted by an
uppercase N in the output of the info breakpoints
command:

(gdb) info breakpoints
Num     Type           Disp Enb Address            What
1       breakpoint     keep y   <MULTIPLE>
        stop only if a == 10
1.1                         N*  0x00000000000011b6 in ...
1.2                         y   0x00000000000011c2 in ...
1.3                         N*  0x00000000000011ce in ...
(*): Breakpoint condition is invalid at this location.

If the breakpoint condition cond is invalid in the context of
all the locations of the breakpoint, GDB refuses to
define the breakpoint. For example, if variable foo is an
undefined variable:

(gdb) break func if foo
No symbol "foo" in current context.

break … -force-condition if cond

There may be cases where the condition cond is invalid at all
the current locations, but the user knows that it will be valid at a
future location; for example, because of a library load. In such
cases, by using the -force-condition keyword before ‘if’,
GDB can be forced to define the breakpoint with the given
condition expression instead of refusing it.

(gdb) break func -force-condition if foo
warning: failed to validate condition at location 1, disabling:
  No symbol "foo" in current context.
warning: failed to validate condition at location 2, disabling:
  No symbol "foo" in current context.
warning: failed to validate condition at location 3, disabling:
  No symbol "foo" in current context.
Breakpoint 1 at 0x1158: test.c:18. (3 locations)

This causes all the present locations where the breakpoint would
otherwise be inserted, to be disabled, as seen in the example above.
However, if there exist locations at which the condition is valid, the
-force-condition keyword has no effect.

tbreak args

Set a breakpoint enabled only for one stop. The args are the
same as for the break command, and the breakpoint is set in the same
way, but the breakpoint is automatically deleted after the first time your
program stops there. See Disabling Breakpoints.

hbreak args

Set a hardware-assisted breakpoint. The args are the same as for the
break command and the breakpoint is set in the same way, but the
breakpoint requires hardware support and some target hardware may not
have this support. The main purpose of this is EPROM/ROM code
debugging, so you can set a breakpoint at an instruction without
changing the instruction. This can be used with the new trap-generation
provided by SPARClite DSU and most x86-based targets. These targets
will generate traps when a program accesses some data or instruction
address that is assigned to the debug registers. However the hardware
breakpoint registers can take a limited number of breakpoints. For
example, on the DSU, only two data breakpoints can be set at a time, and
GDB will reject this command if more than two are used. Delete
or disable unused hardware breakpoints before setting new ones
(see Disabling Breakpoints).
See Break Conditions.
For remote targets, you can restrict the number of hardware
breakpoints GDB will use, see set remote hardware-breakpoint-limit.

thbreak args

Set a hardware-assisted breakpoint enabled only for one stop. The args
are the same as for the hbreak command and the breakpoint is set in
the same way. However, like the tbreak command,
the breakpoint is automatically deleted after the
first time your program stops there. Also, like the hbreak
command, the breakpoint requires hardware support and some target hardware
may not have this support. See Disabling Breakpoints.
See also Break Conditions.

rbreak regex

Set breakpoints on all functions matching the regular expression
regex. This command sets an unconditional breakpoint on all
matches, printing a list of all breakpoints it set. Once these
breakpoints are set, they are treated just like the breakpoints set with
the break command. You can delete them, disable them, or make
them conditional the same way as any other breakpoint.

In programs using different languages, GDB chooses the syntax
to print the list of all breakpoints it sets according to the
‘set language’ value: using ‘set language auto’
(see Set Language Automatically) means to use the
language of the breakpoint’s function, other values mean to use
the manually specified language (see Set Language Manually).

The syntax of the regular expression is the standard one used with tools
like grep. Note that this is different from the syntax used by
shells, so for instance foo* matches all functions that include
an fo followed by zero or more os. There is an implicit
.* leading and trailing the regular expression you supply, so to
match only functions that begin with foo, use ^foo.

When debugging C++ programs, rbreak is useful for setting
breakpoints on overloaded functions that are not members of any special
classes.

The rbreak command can be used to set breakpoints in
all the functions in a program, like this:

rbreak file:regex

If rbreak is called with a filename qualification, it limits
the search for functions matching the given regular expression to the
specified file. This can be used, for example, to set breakpoints on
every function in a given file:

The colon separating the filename qualifier from the regex may
optionally be surrounded by spaces.

info breakpoints [list…]

info break [list…]

Print a table of all breakpoints, watchpoints, and catchpoints set and
not deleted. Optional argument n means print information only
about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)).
For each breakpoint, following columns are printed:

Breakpoint Numbers

Type

Breakpoint, watchpoint, or catchpoint.

Disposition

Whether the breakpoint is marked to be disabled or deleted when hit.

Enabled or Disabled

Enabled breakpoints are marked with ‘y’. ‘n’ marks breakpoints
that are not enabled.

Address

Where the breakpoint is in your program, as a memory address. For a
pending breakpoint whose address is not yet known, this field will
contain ‘<PENDING>’. Such breakpoint won’t fire until a shared
library that has the symbol or line referred by breakpoint is loaded.
See below for details. A breakpoint with several locations will
have ‘<MULTIPLE>’ in this field—see below for details.

What

Where the breakpoint is in the source for your program, as a file and
line number. For a pending breakpoint, the original string passed to
the breakpoint command will be listed as it cannot be resolved until
the appropriate shared library is loaded in the future.

If a breakpoint is conditional, there are two evaluation modes: “host” and
“target”. If mode is “host”, breakpoint condition evaluation is done by
GDB on the host’s side. If it is “target”, then the condition
is evaluated by the target. The info break command shows
the condition on the line following the affected breakpoint, together with
its condition evaluation mode in between parentheses.

Breakpoint commands, if any, are listed after that. A pending breakpoint is
allowed to have a condition specified for it. The condition is not parsed for
validity until a shared library is loaded that allows the pending
breakpoint to resolve to a valid location.

info break with a breakpoint
number n as argument lists only that breakpoint. The
convenience variable $_ and the default examining-address for
the x command are set to the address of the last breakpoint
listed (see Examining Memory).

info break displays a count of the number of times the breakpoint
has been hit. This is especially useful in conjunction with the
ignore command. You can ignore a large number of breakpoint
hits, look at the breakpoint info to see how many times the breakpoint
was hit, and then run again, ignoring one less than that number. This
will get you quickly to the last hit of that breakpoint.

For a breakpoints with an enable count (xref) greater than 1,
info break also displays that count.

GDB allows you to set any number of breakpoints at the same place in
your program. There is nothing silly or meaningless about this. When
the breakpoints are conditional, this is even useful
(see Break Conditions).

It is possible that a single logical breakpoint is set at several code
locations in your program. See Location Specifications, for
examples.

A breakpoint with multiple code locations is displayed in the
breakpoint table using several rows—one header row, followed by one
row for each code location. The header row has ‘<MULTIPLE>’ in
the address column. Each code location row contains the actual
address, source file, source line and function of its code location.
The number column for a code location is of the form
breakpoint-number.location-number.

For example:

Num     Type           Disp Enb  Address    What
1       breakpoint     keep y    <MULTIPLE>
        stop only if i==1
        breakpoint already hit 1 time
1.1                         y    0x080486a2 in void foo<int>() at t.cc:8
1.2                         y    0x080486ca in void foo<double>() at t.cc:8

You cannot delete the individual locations from a breakpoint. However,
each location can be individually enabled or disabled by passing
breakpoint-number.location-number as argument to the
enable and disable commands. It’s also possible to
enable and disable a range of location-number
locations using a breakpoint-number and two location-numbers,
in increasing order, separated by a hyphen, like
breakpoint-number.location-number1-location-number2,
in which case GDB acts on all the locations in the range (inclusive).
Disabling or enabling the parent breakpoint (see Disabling) affects
all of the locations that belong to that breakpoint.

Locations that are enabled while their parent breakpoint is disabled
won’t trigger a break, and are denoted by y- in the Enb
column. For example:

(gdb) info breakpoints
Num     Type           Disp Enb Address            What
1       breakpoint     keep n   <MULTIPLE>
1.1                         y-  0x00000000000011b6 in ...
1.2                         y-  0x00000000000011c2 in ...
1.3                         n   0x00000000000011ce in ...

It’s quite common to have a breakpoint inside a shared library.
Shared libraries can be loaded and unloaded explicitly,
and possibly repeatedly, as the program is executed. To support
this use case, GDB updates breakpoint locations whenever
any shared library is loaded or unloaded. Typically, you would
set a breakpoint in a shared library at the beginning of your
debugging session, when the library is not loaded, and when the
symbols from the library are not available. When you try to set
breakpoint, GDB will ask you if you want to set
a so called pending breakpoint—breakpoint whose address
is not yet resolved.

After the program is run, whenever a new shared library is loaded,
GDB reevaluates all the breakpoints. When a newly loaded
shared library contains the symbol or line referred to by some
pending breakpoint, that breakpoint is resolved and becomes an
ordinary breakpoint. When a library is unloaded, all breakpoints
that refer to its symbols or source lines become pending again.

This logic works for breakpoints with multiple locations, too. For
example, if you have a breakpoint in a C++ template function, and
a newly loaded shared library has an instantiation of that template,
a new location is added to the list of locations for the breakpoint.

Except for having unresolved address, pending breakpoints do not
differ from regular breakpoints. You can set conditions or commands,
enable and disable them and perform other breakpoint operations.

GDB provides some additional commands for controlling what
happens when the ‘break’ command cannot resolve the location spec
to any code location in your program (see Location Specifications):

set breakpoint pending auto

This is the default behavior. When GDB cannot resolve the
location spec, it queries you whether a pending breakpoint should be
created.

set breakpoint pending on

This indicates that when GDB cannot resolve the location
spec, it should create a pending breakpoint without confirmation.

set breakpoint pending off

This indicates that pending breakpoints are not to be created. If
GDB cannot resolve the location spec, it aborts the
breakpoint creation with an error. This setting does not affect any
pending breakpoints previously created.

show breakpoint pending

Show the current behavior setting for creating pending breakpoints.

The settings above only affect the break command and its
variants. Once a breakpoint is set, it will be automatically updated
as shared libraries are loaded and unloaded.

For some targets, GDB can automatically decide if hardware or
software breakpoints should be used, depending on whether the
breakpoint address is read-only or read-write. This applies to
breakpoints set with the break command as well as to internal
breakpoints set by commands like next and finish. For
breakpoints set with hbreak, GDB will always use hardware
breakpoints.

You can control this automatic behaviour with the following commands:

set breakpoint auto-hw on

This is the default behavior. When GDB sets a breakpoint, it
will try to use the target memory map to decide if software or hardware
breakpoint must be used.

set breakpoint auto-hw off

This indicates GDB should not automatically select breakpoint
type. If the target provides a memory map, GDB will warn when
trying to set software breakpoint at a read-only address.

GDB normally implements breakpoints by replacing the program code
at the breakpoint address with a special instruction, which, when
executed, given control to the debugger. By default, the program
code is so modified only when the program is resumed. As soon as
the program stops, GDB restores the original instructions. This
behaviour guards against leaving breakpoints inserted in the
target should gdb abrubptly disconnect. However, with slow remote
targets, inserting and removing breakpoint can reduce the performance.
This behavior can be controlled with the following commands::

set breakpoint always-inserted off

All breakpoints, including newly added by the user, are inserted in
the target only when the target is resumed. All breakpoints are
removed from the target when it stops. This is the default mode.

set breakpoint always-inserted on

Causes all breakpoints to be inserted in the target at all times. If
the user adds a new breakpoint, or changes an existing breakpoint, the
breakpoints in the target are updated immediately. A breakpoint is
removed from the target only when breakpoint itself is deleted.

GDB handles conditional breakpoints by evaluating these conditions
when a breakpoint breaks. If the condition is true, then the process being
debugged stops, otherwise the process is resumed.

If the target supports evaluating conditions on its end, GDB may
download the breakpoint, together with its conditions, to it.

This feature can be controlled via the following commands:

set breakpoint condition-evaluation host

This option commands GDB to evaluate the breakpoint
conditions on the host’s side. Unconditional breakpoints are sent to
the target which in turn receives the triggers and reports them back to GDB
for condition evaluation. This is the standard evaluation mode.

set breakpoint condition-evaluation target

This option commands GDB to download breakpoint conditions
to the target at the moment of their insertion. The target
is responsible for evaluating the conditional expression and reporting
breakpoint stop events back to GDB whenever the condition
is true. Due to limitations of target-side evaluation, some conditions
cannot be evaluated there, e.g., conditions that depend on local data
that is only known to the host. Examples include
conditional expressions involving convenience variables, complex types
that cannot be handled by the agent expression parser and expressions
that are too long to be sent over to the target, specially when the
target is a remote system. In these cases, the conditions will be
evaluated by GDB.

set breakpoint condition-evaluation auto

This is the default mode. If the target supports evaluating breakpoint
conditions on its end, GDB will download breakpoint conditions to
the target (limitations mentioned previously apply). If the target does
not support breakpoint condition evaluation, then GDB will fallback
to evaluating all these conditions on the host’s side.

GDB itself sometimes sets breakpoints in your program for
special purposes, such as proper handling of longjmp (in C
programs). These internal breakpoints are assigned negative numbers,
starting with -1; ‘info breakpoints’ does not display them.
You can see these breakpoints with the GDB maintenance command
‘maint info breakpoints’ (see maint info breakpoints).

5.1.2 Setting Watchpoints

You can use a watchpoint to stop execution whenever the value of an
expression changes, without having to predict a particular place where
this may happen. (This is sometimes called a data breakpoint.)
The expression may be as simple as the value of a single variable, or
as complex as many variables combined by operators. Examples include:

• A reference to the value of a single variable.
• An address cast to an appropriate data type. For example,
  ‘*(int *)0x12345678’ will watch a 4-byte region at the specified
  address (assuming an int occupies 4 bytes).

• An arbitrarily complex expression, such as ‘a*b + c/d’. The
  expression can use any operators valid in the program’s native
  language (see Languages).

You can set a watchpoint on an expression even if the expression can
not be evaluated yet. For instance, you can set a watchpoint on
‘*global_ptr’ before ‘global_ptr’ is initialized.
GDB will stop when your program sets ‘global_ptr’ and
the expression produces a valid value. If the expression becomes
valid in some other way than changing a variable (e.g. if the memory
pointed to by ‘*global_ptr’ becomes readable as the result of a
malloc call), GDB may not stop until the next time
the expression changes.

Depending on your system, watchpoints may be implemented in software or
hardware. GDB does software watchpointing by single-stepping your
program and testing the variable’s value each time, which is hundreds of
times slower than normal execution. (But this may still be worth it, to
catch errors where you have no clue what part of your program is the
culprit.)

On some systems, such as most PowerPC or x86-based targets,
GDB includes support for hardware watchpoints, which do not
slow down the running of your program.

watch [-l|-location] expr [thread thread-id] [mask maskvalue] [task task-id]

Set a watchpoint for an expression. GDB will break when the
expression expr is written into by the program and its value
changes. The simplest (and the most popular) use of this command is
to watch the value of a single variable:

If the command includes a [thread thread-id]
argument, GDB breaks only when the thread identified by
thread-id changes the value of expr. If any other threads
change the value of expr, GDB will not break. Note
that watchpoints restricted to a single thread in this way only work
with Hardware Watchpoints.

Similarly, if the task argument is given, then the watchpoint
will be specific to the indicated Ada task (see Ada Tasks).

Ordinarily a watchpoint respects the scope of variables in expr
(see below). The -location argument tells GDB to
instead watch the memory referred to by expr. In this case,
GDB will evaluate expr, take the address of the result,
and watch the memory at that address. The type of the result is used
to determine the size of the watched memory. If the expression’s
result does not have an address, then GDB will print an
error.

The [mask maskvalue] argument allows creation
of masked watchpoints, if the current architecture supports this
feature (e.g., PowerPC Embedded architecture, see PowerPC Embedded.) A masked watchpoint specifies a mask in addition
to an address to watch. The mask specifies that some bits of an address
(the bits which are reset in the mask) should be ignored when matching
the address accessed by the inferior against the watchpoint address.
Thus, a masked watchpoint watches many addresses simultaneously—those
addresses whose unmasked bits are identical to the unmasked bits in the
watchpoint address. The mask argument implies -location.
Examples:

(gdb) watch foo mask 0xffff00ff
(gdb) watch *0xdeadbeef mask 0xffffff00

rwatch [-l|-location] expr [thread thread-id] [mask maskvalue]

Set a watchpoint that will break when the value of expr is read
by the program.

awatch [-l|-location] expr [thread thread-id] [mask maskvalue]

Set a watchpoint that will break when expr is either read from
or written into by the program.

info watchpoints [list…]

This command prints a list of watchpoints, using the same format as
info break (see Set Breaks).

If you watch for a change in a numerically entered address you need to
dereference it, as the address itself is just a constant number which will
never change. GDB refuses to create a watchpoint that watches
a never-changing value:

(gdb) watch 0x600850
Cannot watch constant value 0x600850.
(gdb) watch *(int *) 0x600850
Watchpoint 1: *(int *) 6293584

GDB sets a hardware watchpoint if possible. Hardware
watchpoints execute very quickly, and the debugger reports a change in
value at the exact instruction where the change occurs. If GDB
cannot set a hardware watchpoint, it sets a software watchpoint, which
executes more slowly and reports the change in value at the next
statement, not the instruction, after the change occurs.

You can force GDB to use only software watchpoints with the
set can-use-hw-watchpoints 0 command. With this variable set to
zero, GDB will never try to use hardware watchpoints, even if
the underlying system supports them. (Note that hardware-assisted
watchpoints that were set before setting
can-use-hw-watchpoints to zero will still use the hardware
mechanism of watching expression values.)

set can-use-hw-watchpoints

Set whether or not to use hardware watchpoints.

show can-use-hw-watchpoints

Show the current mode of using hardware watchpoints.

For remote targets, you can restrict the number of hardware
watchpoints GDB will use, see set remote hardware-breakpoint-limit.

When you issue the watch command, GDB reports

Hardware watchpoint num: expr

if it was able to set a hardware watchpoint.

Currently, the awatch and rwatch commands can only set
hardware watchpoints, because accesses to data that don’t change the
value of the watched expression cannot be detected without examining
every instruction as it is being executed, and GDB does not do
that currently. If GDB finds that it is unable to set a
hardware breakpoint with the awatch or rwatch command, it
will print a message like this:

Expression cannot be implemented with read/access watchpoint.

Sometimes, GDB cannot set a hardware watchpoint because the
data type of the watched expression is wider than what a hardware
watchpoint on the target machine can handle. For example, some systems
can only watch regions that are up to 4 bytes wide; on such systems you
cannot set hardware watchpoints for an expression that yields a
double-precision floating-point number (which is typically 8 bytes
wide). As a work-around, it might be possible to break the large region
into a series of smaller ones and watch them with separate watchpoints.

If you set too many hardware watchpoints, GDB might be unable
to insert all of them when you resume the execution of your program.
Since the precise number of active watchpoints is unknown until such
time as the program is about to be resumed, GDB might not be
able to warn you about this when you set the watchpoints, and the
warning will be printed only when the program is resumed:

Hardware watchpoint num: Could not insert watchpoint

If this happens, delete or disable some of the watchpoints.

Watching complex expressions that reference many variables can also
exhaust the resources available for hardware-assisted watchpoints.
That’s because GDB needs to watch every variable in the
expression with separately allocated resources.

If you call a function interactively using print or call,
any watchpoints you have set will be inactive until GDB reaches another
kind of breakpoint or the call completes.

GDB automatically deletes watchpoints that watch local
(automatic) variables, or expressions that involve such variables, when
they go out of scope, that is, when the execution leaves the block in
which these variables were defined. In particular, when the program
being debugged terminates, all local variables go out of scope,
and so only watchpoints that watch global variables remain set. If you
rerun the program, you will need to set all such watchpoints again. One
way of doing that would be to set a code breakpoint at the entry to the
main function and when it breaks, set all the watchpoints.

In multi-threaded programs, watchpoints will detect changes to the
watched expression from every thread.

Warning: In multi-threaded programs, software watchpoints
have only limited usefulness. If GDB creates a software
watchpoint, it can only watch the value of an expression in a
single thread. If you are confident that the expression can only
change due to the current thread’s activity (and if you are also
confident that no other thread can become current), then you can use
software watchpoints as usual. However, GDB may not notice
when a non-current thread’s activity changes the expression. (Hardware
watchpoints, in contrast, watch an expression in all threads.)

See set remote hardware-watchpoint-limit.

5.1.3 Setting Catchpoints

You can use catchpoints to cause the debugger to stop for certain
kinds of program events, such as C++ exceptions or the loading of a
shared library. Use the catch command to set a catchpoint.

catch event

Stop when event occurs. The event can be any of the following:

throw [regexp]

rethrow [regexp]

catch [regexp]

The throwing, re-throwing, or catching of a C++ exception.

If regexp is given, then only exceptions whose type matches the
regular expression will be caught.

The convenience variable $_exception is available at an
exception-related catchpoint, on some systems. This holds the
exception being thrown.

There are currently some limitations to C++ exception handling in
GDB:

• The support for these commands is system-dependent. Currently, only
  systems using the ‘gnu-v3’ C++ ABI (see ABI) are
  supported.

• The regular expression feature and the $_exception convenience
  variable rely on the presence of some SDT probes in libstdc++.
  If these probes are not present, then these features cannot be used.
  These probes were first available in the GCC 4.8 release, but whether
  or not they are available in your GCC also depends on how it was
  built.

• The $_exception convenience variable is only valid at the
  instruction at which an exception-related catchpoint is set.

• When an exception-related catchpoint is hit, GDB stops at a
  location in the system library which implements runtime exception
  support for C++, usually libstdc++. You can use up
  (see Selection) to get to your code.

• If you call a function interactively, GDB normally returns
  control to you when the function has finished executing. If the call
  raises an exception, however, the call may bypass the mechanism that
  returns control to you and cause your program either to abort or to
  simply continue running until it hits a breakpoint, catches a signal
  that GDB is listening for, or exits. This is the case even if
  you set a catchpoint for the exception; catchpoints on exceptions are
  disabled within interactive calls. See Calling, for information on
  controlling this with set unwind-on-terminating-exception.

• You cannot raise an exception interactively.
• You cannot install an exception handler interactively.

exception [name]

An Ada exception being raised. If an exception name is specified
at the end of the command (eg catch exception Program_Error),
the debugger will stop only when this specific exception is raised.
Otherwise, the debugger stops execution when any Ada exception is raised.

When inserting an exception catchpoint on a user-defined exception whose
name is identical to one of the exceptions defined by the language, the
fully qualified name must be used as the exception name. Otherwise,
GDB will assume that it should stop on the pre-defined exception
rather than the user-defined one. For instance, assuming an exception
called Constraint_Error is defined in package Pck, then
the command to use to catch such exceptions is catch exception
Pck.Constraint_Error.

The convenience variable $_ada_exception holds the address of
the exception being thrown. This can be useful when setting a
condition for such a catchpoint.

exception unhandled

An exception that was raised but is not handled by the program. The
convenience variable $_ada_exception is set as for catch
exception.

handlers [name]

An Ada exception being handled. If an exception name is
specified at the end of the command
(eg catch handlers Program_Error), the debugger will stop
only when this specific exception is handled.
Otherwise, the debugger stops execution when any Ada exception is handled.

When inserting a handlers catchpoint on a user-defined
exception whose name is identical to one of the exceptions
defined by the language, the fully qualified name must be used
as the exception name. Otherwise, GDB will assume that it
should stop on the pre-defined exception rather than the
user-defined one. For instance, assuming an exception called
Constraint_Error is defined in package Pck, then the
command to use to catch such exceptions handling is
catch handlers Pck.Constraint_Error.

The convenience variable $_ada_exception is set as for
catch exception.

assert

A failed Ada assertion. Note that the convenience variable
$_ada_exception is not set by this catchpoint.

exec

A call to exec.

syscall

syscall [name | number | group:groupname | g:groupname] …

A call to or return from a system call, a.k.a. syscall. A
syscall is a mechanism for application programs to request a service
from the operating system (OS) or one of the OS system services.
GDB can catch some or all of the syscalls issued by the
debuggee, and show the related information for each syscall. If no
argument is specified, calls to and returns from all system calls
will be caught.

name can be any system call name that is valid for the
underlying OS. Just what syscalls are valid depends on the OS. On
GNU and Unix systems, you can find the full list of valid syscall
names on /usr/include/asm/unistd.h.

Normally, GDB knows in advance which syscalls are valid for
each OS, so you can use the GDB command-line completion
facilities (see command completion) to list the
available choices.

You may also specify the system call numerically. A syscall’s
number is the value passed to the OS’s syscall dispatcher to
identify the requested service. When you specify the syscall by its
name, GDB uses its database of syscalls to convert the name
into the corresponding numeric code, but using the number directly
may be useful if GDB’s database does not have the complete
list of syscalls on your system (e.g., because GDB lags
behind the OS upgrades).

You may specify a group of related syscalls to be caught at once using
the group: syntax (g: is a shorter equivalent). For
instance, on some platforms GDB allows you to catch all
network related syscalls, by passing the argument group:network
to catch syscall. Note that not all syscall groups are
available in every system. You can use the command completion
facilities (see command completion) to list the
syscall groups available on your environment.

The example below illustrates how this command works if you don’t provide
arguments to it:

(gdb) catch syscall
Catchpoint 1 (syscall)
(gdb) r
Starting program: /tmp/catch-syscall

Catchpoint 1 (call to syscall 'close'), 
	   0xffffe424 in __kernel_vsyscall ()
(gdb) c
Continuing.

Catchpoint 1 (returned from syscall 'close'), 
	0xffffe424 in __kernel_vsyscall ()
(gdb)

Here is an example of catching a system call by name:

(gdb) catch syscall chroot
Catchpoint 1 (syscall 'chroot' [61])
(gdb) r
Starting program: /tmp/catch-syscall

Catchpoint 1 (call to syscall 'chroot'), 
		   0xffffe424 in __kernel_vsyscall ()
(gdb) c
Continuing.

Catchpoint 1 (returned from syscall 'chroot'), 
	0xffffe424 in __kernel_vsyscall ()
(gdb)

An example of specifying a system call numerically. In the case
below, the syscall number has a corresponding entry in the XML
file, so GDB finds its name and prints it:

(gdb) catch syscall 252
Catchpoint 1 (syscall(s) 'exit_group')
(gdb) r
Starting program: /tmp/catch-syscall

Catchpoint 1 (call to syscall 'exit_group'), 
		   0xffffe424 in __kernel_vsyscall ()
(gdb) c
Continuing.

Program exited normally.
(gdb)

Here is an example of catching a syscall group:

(gdb) catch syscall group:process
Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7]
'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190]
'exit_group' [252] 'waitid' [284] 'unshare' [310])
(gdb) r
Starting program: /tmp/catch-syscall

Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 ()
   from /lib64/ld-linux-x86-64.so.2

(gdb) c
Continuing.

However, there can be situations when there is no corresponding name
in XML file for that syscall number. In this case, GDB prints
a warning message saying that it was not able to find the syscall name,
but the catchpoint will be set anyway. See the example below:

(gdb) catch syscall 764
warning: The number '764' does not represent a known syscall.
Catchpoint 2 (syscall 764)
(gdb)

If you configure GDB using the ‘—without-expat’ option,
it will not be able to display syscall names. Also, if your
architecture does not have an XML file describing its system calls,
you will not be able to see the syscall names. It is important to
notice that these two features are used for accessing the syscall
name database. In either case, you will see a warning like this:

(gdb) catch syscall
warning: Could not open "syscalls/i386-linux.xml"
warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
GDB will not be able to display syscall names.
Catchpoint 1 (syscall)
(gdb)

Of course, the file name will change depending on your architecture and system.

Still using the example above, you can also try to catch a syscall by its
number. In this case, you would see something like:

(gdb) catch syscall 252
Catchpoint 1 (syscall(s) 252)

Again, in this case GDB would not be able to display syscall’s names.

fork

A call to fork.

vfork

A call to vfork.

load [regexp]

unload [regexp]

The loading or unloading of a shared library. If regexp is
given, then the catchpoint will stop only if the regular expression
matches one of the affected libraries.

signal [signal… | ‘all’]

The delivery of a signal.

With no arguments, this catchpoint will catch any signal that is not
used internally by GDB, specifically, all signals except
‘SIGTRAP’ and ‘SIGINT’.

With the argument ‘all’, all signals, including those used by
GDB, will be caught. This argument cannot be used with other
signal names.

Otherwise, the arguments are a list of signal names as given to
handle (see Signals). Only signals specified in this list
will be caught.

One reason that catch signal can be more useful than
handle is that you can attach commands and conditions to the
catchpoint.

When a signal is caught by a catchpoint, the signal’s stop and
print settings, as specified by handle, are ignored.
However, whether the signal is still delivered to the inferior depends
on the pass setting; this can be changed in the catchpoint’s
commands.

tcatch event

Set a catchpoint that is enabled only for one stop. The catchpoint is
automatically deleted after the first time the event is caught.

Use the info break command to list the current catchpoints.

5.1.4 Deleting Breakpoints

It is often necessary to eliminate a breakpoint, watchpoint, or
catchpoint once it has done its job and you no longer want your program
to stop there. This is called deleting the breakpoint. A
breakpoint that has been deleted no longer exists; it is forgotten.

With the clear command you can delete breakpoints according to
where they are in your program. With the delete command you can
delete individual breakpoints, watchpoints, or catchpoints by specifying
their breakpoint numbers.

It is not necessary to delete a breakpoint to proceed past it. GDB
automatically ignores breakpoints on the first instruction to be executed
when you continue execution without changing the execution address.

clear

Delete any breakpoints at the next instruction to be executed in the
selected stack frame (see Selecting a Frame). When
the innermost frame is selected, this is a good way to delete a
breakpoint where your program just stopped.

clear locspec

Delete any breakpoint with a code location that corresponds to
locspec. See Location Specifications, for the various forms
of locspec. Which code locations correspond to locspec
depends on the form used in the location specification locspec:

linenum

filename:linenum

-line linenum

-source filename -line linenum

If locspec specifies a line number, with or without a file name,
the command deletes any breakpoint with a code location that is at or
within the specified line linenum in files that match the
specified filename. If filename is omitted, it defaults
to the current source file.

*address

If locspec specifies an address, the command deletes any
breakpoint with a code location that is at the given address.

function

-function function

If locspec specifies a function, the command deletes any
breakpoint with a code location that is at the entry to any function
whose name matches function.

Ambiguity in names of files and functions can be resolved as described
in Location Specifications.

delete [breakpoints] [list…]

Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
list specified as argument. If no argument is specified, delete all
breakpoints (GDB asks confirmation, unless you have set
confirm off). You can abbreviate this command as d.

5.1.5 Disabling Breakpoints

Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
prefer to disable it. This makes the breakpoint inoperative as if
it had been deleted, but remembers the information on the breakpoint so
that you can enable it again later.

You disable and enable breakpoints, watchpoints, and catchpoints with
the enable and disable commands, optionally specifying
one or more breakpoint numbers as arguments. Use info break to
print a list of all breakpoints, watchpoints, and catchpoints if you
do not know which numbers to use.

Disabling and enabling a breakpoint that has multiple locations
affects all of its locations.

A breakpoint, watchpoint, or catchpoint can have any of several
different states of enablement:

• Enabled. The breakpoint stops your program. A breakpoint set
  with the break command starts out in this state.
• Disabled. The breakpoint has no effect on your program.
• Enabled once. The breakpoint stops your program, but then becomes
  disabled.
• Enabled for a count. The breakpoint stops your program for the next
  N times, then becomes disabled.
• Enabled for deletion. The breakpoint stops your program, but
  immediately after it does so it is deleted permanently. A breakpoint
  set with the tbreak command starts out in this state.

You can use the following commands to enable or disable breakpoints,
watchpoints, and catchpoints:

disable [breakpoints] [list…]

Disable the specified breakpoints—or all breakpoints, if none are
listed. A disabled breakpoint has no effect but is not forgotten. All
options such as ignore-counts, conditions and commands are remembered in
case the breakpoint is enabled again later. You may abbreviate
disable as dis.

enable [breakpoints] [list…]

Enable the specified breakpoints (or all defined breakpoints). They
become effective once again in stopping your program.

enable [breakpoints] once list…

Enable the specified breakpoints temporarily. GDB disables any
of these breakpoints immediately after stopping your program.

enable [breakpoints] count count list…

Enable the specified breakpoints temporarily. GDB records
count with each of the specified breakpoints, and decrements a
breakpoint’s count when it is hit. When any count reaches 0,
GDB disables that breakpoint. If a breakpoint has an ignore
count (see Break Conditions), that will be
decremented to 0 before count is affected.

enable [breakpoints] delete list…

Enable the specified breakpoints to work once, then die. GDB
deletes any of these breakpoints as soon as your program stops there.
Breakpoints set by the tbreak command start out in this state.

Except for a breakpoint set with tbreak (see Setting Breakpoints), breakpoints that you set are initially enabled;
subsequently, they become disabled or enabled only when you use one of
the commands above. (The command until can set and delete a
breakpoint of its own, but it does not change the state of your other
breakpoints; see Continuing and
Stepping.)

5.1.6 Break Conditions

The simplest sort of breakpoint breaks every time your program reaches a
specified place. You can also specify a condition for a
breakpoint. A condition is just a Boolean expression in your
programming language (see Expressions). A breakpoint with
a condition evaluates the expression each time your program reaches it,
and your program stops only if the condition is true.

This is the converse of using assertions for program validation; in that
situation, you want to stop when the assertion is violated—that is,
when the condition is false. In C, if you want to test an assertion expressed
by the condition assert, you should set the condition
‘! assert’ on the appropriate breakpoint.

Conditions are also accepted for watchpoints; you may not need them,
since a watchpoint is inspecting the value of an expression anyhow—but
it might be simpler, say, to just set a watchpoint on a variable name,
and specify a condition that tests whether the new value is an interesting
one.

Break conditions can have side effects, and may even call functions in
your program. This can be useful, for example, to activate functions
that log program progress, or to use your own print functions to
format special data structures. The effects are completely predictable
unless there is another enabled breakpoint at the same address. (In
that case, GDB might see the other breakpoint first and stop your
program without checking the condition of this one.) Note that
breakpoint commands are usually more convenient and flexible than break
conditions for the
purpose of performing side effects when a breakpoint is reached
(see Breakpoint Command Lists).

Breakpoint conditions can also be evaluated on the target’s side if
the target supports it. Instead of evaluating the conditions locally,
GDB encodes the expression into an agent expression
(see Agent Expressions) suitable for execution on the target,
independently of GDB. Global variables become raw memory
locations, locals become stack accesses, and so forth.

In this case, GDB will only be notified of a breakpoint trigger
when its condition evaluates to true. This mechanism may provide faster
response times depending on the performance characteristics of the target
since it does not need to keep GDB informed about
every breakpoint trigger, even those with false conditions.

Break conditions can be specified when a breakpoint is set, by using
‘if’ in the arguments to the break command. See Setting Breakpoints. They can also be changed at any time
with the condition command.

You can also use the if keyword with the watch command.
The catch command does not recognize the if keyword;
condition is the only way to impose a further condition on a
catchpoint.

condition bnum expression

Specify expression as the break condition for breakpoint,
watchpoint, or catchpoint number bnum. After you set a condition,
breakpoint bnum stops your program only if the value of
expression is true (nonzero, in C). When you use
condition, GDB checks expression immediately for
syntactic correctness, and to determine whether symbols in it have
referents in the context of your breakpoint. If expression uses
symbols not referenced in the context of the breakpoint, GDB
prints an error message:

No symbol "foo" in current context.

GDB does
not actually evaluate expression at the time the condition
command (or a command that sets a breakpoint with a condition, like
break if …) is given, however. See Expressions.

condition -force bnum expression

When the -force flag is used, define the condition even if
expression is invalid at all the current locations of breakpoint
bnum. This is similar to the -force-condition option
of the break command.

condition bnum

Remove the condition from breakpoint number bnum. It becomes
an ordinary unconditional breakpoint.

A special case of a breakpoint condition is to stop only when the
breakpoint has been reached a certain number of times. This is so
useful that there is a special way to do it, using the ignore
count of the breakpoint. Every breakpoint has an ignore count, which
is an integer. Most of the time, the ignore count is zero, and
therefore has no effect. But if your program reaches a breakpoint whose
ignore count is positive, then instead of stopping, it just decrements
the ignore count by one and continues. As a result, if the ignore count
value is n, the breakpoint does not stop the next n times
your program reaches it.

ignore bnum count

Set the ignore count of breakpoint number bnum to count.
The next count times the breakpoint is reached, your program’s
execution does not stop; other than to decrement the ignore count, GDB
takes no action.

To make the breakpoint stop the next time it is reached, specify
a count of zero.

When you use continue to resume execution of your program from a
breakpoint, you can specify an ignore count directly as an argument to
continue, rather than using ignore. See Continuing and Stepping.

If a breakpoint has a positive ignore count and a condition, the
condition is not checked. Once the ignore count reaches zero,
GDB resumes checking the condition.

You could achieve the effect of the ignore count with a condition such
as ‘$foo— <= 0’ using a debugger convenience variable that
is decremented each time. See Convenience
Variables.

Ignore counts apply to breakpoints, watchpoints, and catchpoints.

5.1.7 Breakpoint Command Lists

You can give any breakpoint (or watchpoint or catchpoint) a series of
commands to execute when your program stops due to that breakpoint. For
example, you might want to print the values of certain expressions, or
enable other breakpoints.

commands [list…]

… command-list …

end

Specify a list of commands for the given breakpoints. The commands
themselves appear on the following lines. Type a line containing just
end to terminate the commands.

To remove all commands from a breakpoint, type commands and
follow it immediately with end; that is, give no commands.

With no argument, commands refers to the last breakpoint,
watchpoint, or catchpoint set (not to the breakpoint most recently
encountered). If the most recent breakpoints were set with a single
command, then the commands will apply to all the breakpoints
set by that command. This applies to breakpoints set by
rbreak, and also applies when a single break command
creates multiple breakpoints (see Ambiguous
Expressions).

Pressing RET as a means of repeating the last GDB command is
disabled within a command-list.

Inside a command list, you can use the command
disable $_hit_bpnum to disable the encountered breakpoint.

If your breakpoint has several code locations, the command
disable $_hit_bpnum.$_hit_locno will disable the specific breakpoint
code location encountered. If the breakpoint has only one location,
this command will disable the encountered breakpoint.

You can use breakpoint commands to start your program up again. Simply
use the continue command, or step, or any other command
that resumes execution.

Any other commands in the command list, after a command that resumes
execution, are ignored. This is because any time you resume execution
(even with a simple next or step), you may encounter
another breakpoint—which could have its own command list, leading to
ambiguities about which list to execute.

If the first command you specify in a command list is silent, the
usual message about stopping at a breakpoint is not printed. This may
be desirable for breakpoints that are to print a specific message and
then continue. If none of the remaining commands print anything, you
see no sign that the breakpoint was reached. silent is
meaningful only at the beginning of a breakpoint command list.

The commands echo, output, and printf allow you to
print precisely controlled output, and are often useful in silent
breakpoints. See Commands for Controlled Output.

For example, here is how you could use breakpoint commands to print the
value of x at entry to foo whenever x is positive.

break foo if x>0
commands
silent
printf "x is %dn",x
cont
end

One application for breakpoint commands is to compensate for one bug so
you can test for another. Put a breakpoint just after the erroneous line
of code, give it a condition to detect the case in which something
erroneous has been done, and give it commands to assign correct values
to any variables that need them. End with the continue command
so that your program does not stop, and start with the silent
command so that no output is produced. Here is an example:

break 403
commands
silent
set x = y + 4
cont
end

5.1.8 Dynamic Printf

The dynamic printf command dprintf combines a breakpoint with
formatted printing of your program’s data to give you the effect of
inserting printf calls into your program on-the-fly, without
having to recompile it.

In its most basic form, the output goes to the GDB console. However,
you can set the variable dprintf-style for alternate handling.
For instance, you can ask to format the output by calling your
program’s printf function. This has the advantage that the
characters go to the program’s output device, so they can recorded in
redirects to files and so forth.

If you are doing remote debugging with a stub or agent, you can also
ask to have the printf handled by the remote agent. In addition to
ensuring that the output goes to the remote program’s device along
with any other output the program might produce, you can also ask that
the dprintf remain active even after disconnecting from the remote
target. Using the stub/agent is also more efficient, as it can do
everything without needing to communicate with GDB.

dprintf locspec,template,expression[,expression…]

Whenever execution reaches a code location that results from resolving
locspec, print the values of one or more expressions under
the control of the string template. To print several values,
separate them with commas.

set dprintf-style style

Set the dprintf output to be handled in one of several different
styles enumerated below. A change of style affects all existing
dynamic printfs immediately. (If you need individual control over the
print commands, simply define normal breakpoints with
explicitly-supplied command lists.)

gdb

Handle the output using the GDB printf command.

call

Handle the output by calling a function in your program (normally
printf).

agent

Have the remote debugging agent (such as gdbserver) handle
the output itself. This style is only available for agents that
support running commands on the target.

set dprintf-function function

Set the function to call if the dprintf style is call. By
default its value is printf. You may set it to any expression.
that GDB can evaluate to a function, as per the call
command.

set dprintf-channel channel

Set a “channel” for dprintf. If set to a non-empty value,
GDB will evaluate it as an expression and pass the result as
a first argument to the dprintf-function, in the manner of
fprintf and similar functions. Otherwise, the dprintf format
string will be the first argument, in the manner of printf.

As an example, if you wanted dprintf output to go to a logfile
that is a standard I/O stream assigned to the variable mylog,
you could do the following:

(gdb) set dprintf-style call
(gdb) set dprintf-function fprintf
(gdb) set dprintf-channel mylog
(gdb) dprintf 25,"at line 25, glob=%dn",glob
Dprintf 1 at 0x123456: file main.c, line 25.
(gdb) info break
1       dprintf        keep y   0x00123456 in main at main.c:25
        call (void) fprintf (mylog,"at line 25, glob=%dn",glob)
        continue
(gdb)

Note that the info break displays the dynamic printf commands
as normal breakpoint commands; you can thus easily see the effect of
the variable settings.

set disconnected-dprintf on

set disconnected-dprintf off

Choose whether dprintf commands should continue to run if
GDB has disconnected from the target. This only applies
if the dprintf-style is agent.

show disconnected-dprintf off

Show the current choice for disconnected dprintf.

GDB does not check the validity of function and channel,
relying on you to supply values that are meaningful for the contexts
in which they are being used. For instance, the function and channel
may be the values of local variables, but if that is the case, then
all enabled dynamic prints must be at locations within the scope of
those locals. If evaluation fails, GDB will report an error.

5.1.9 How to save breakpoints to a file

To save breakpoint definitions to a file use the save breakpoints command.

save breakpoints [filename]

This command saves all current breakpoint definitions together with
their commands and ignore counts, into a file filename
suitable for use in a later debugging session. This includes all
types of breakpoints (breakpoints, watchpoints, catchpoints,
tracepoints). To read the saved breakpoint definitions, use the
source command (see Command Files). Note that watchpoints
with expressions involving local variables may fail to be recreated
because it may not be possible to access the context where the
watchpoint is valid anymore. Because the saved breakpoint definitions
are simply a sequence of GDB commands that recreate the
breakpoints, you can edit the file in your favorite editing program,
and remove the breakpoint definitions you’re not interested in, or
that can no longer be recreated.

5.1.10 Static Probe Points

GDB supports SDT probes in the code. SDT stands
for Statically Defined Tracing, and the probes are designed to have a tiny
runtime code and data footprint, and no dynamic relocations.

Currently, the following types of probes are supported on
ELF-compatible systems:

• SystemTap (http://sourceware.org/systemtap/)
  SDT probes⁵. SystemTap probes are usable
  from assembly, C and C++ languages⁶.

• DTrace (http://oss.oracle.com/projects/DTrace)
  USDT probes. DTrace probes are usable from C and
  C++ languages.

Some SystemTap probes have an associated semaphore variable;
for instance, this happens automatically if you defined your probe
using a DTrace-style .d file. If your probe has a semaphore,
GDB will automatically enable it when you specify a
breakpoint using the ‘-probe-stap’ notation. But, if you put a
breakpoint at a probe’s location by some other method (e.g.,
break file:line), then GDB will not automatically set
the semaphore. DTrace probes do not support semaphores.

You can examine the available static static probes using info
probes, with optional arguments:

info probes [type] [provider [name [objfile]]]

If given, type is either stap for listing
SystemTap probes or dtrace for listing DTrace
probes. If omitted all probes are listed regardless of their types.

If given, provider is a regular expression used to match against provider
names when selecting which probes to list. If omitted, probes by all
probes from all providers are listed.

If given, name is a regular expression to match against probe names
when selecting which probes to list. If omitted, probe names are not
considered when deciding whether to display them.

If given, objfile is a regular expression used to select which
object files (executable or shared libraries) to examine. If not
given, all object files are considered.

info probes all

List the available static probes, from all types.

Some probe points can be enabled and/or disabled. The effect of
enabling or disabling a probe depends on the type of probe being
handled. Some DTrace probes can be enabled or
disabled, but SystemTap probes cannot be disabled.

You can enable (or disable) one or more probes using the following
commands, with optional arguments:

enable probes [provider [name [objfile]]]

If given, provider is a regular expression used to match against
provider names when selecting which probes to enable. If omitted,
all probes from all providers are enabled.

If given, name is a regular expression to match against probe
names when selecting which probes to enable. If omitted, probe names
are not considered when deciding whether to enable them.

If given, objfile is a regular expression used to select which
object files (executable or shared libraries) to examine. If not
given, all object files are considered.

disable probes [provider [name [objfile]]]

See the enable probes command above for a description of the
optional arguments accepted by this command.

A probe may specify up to twelve arguments. These are available at the
point at which the probe is defined—that is, when the current PC is
at the probe’s location. The arguments are available using the
convenience variables (see Convenience Vars)
$_probe_arg0…$_probe_arg11. In SystemTap
probes each probe argument is an integer of the appropriate size;
types are not preserved. In DTrace probes types are preserved
provided that they are recognized as such by GDB; otherwise
the value of the probe argument will be a long integer. The
convenience variable $_probe_argc holds the number of arguments
at the current probe point.

These variables are always available, but attempts to access them at
any location other than a probe point will cause GDB to give
an error message.

5.1.11 “Cannot insert breakpoints”

If you request too many active hardware-assisted breakpoints and
watchpoints, you will see this error message:

Stopped; cannot insert breakpoints.
You may have requested too many hardware breakpoints and watchpoints.

This message is printed when you attempt to resume the program, since
only then GDB knows exactly how many hardware breakpoints and
watchpoints it needs to insert.

When this message is printed, you need to disable or remove some of the
hardware-assisted breakpoints and watchpoints, and then continue.

5.1.12 “Breakpoint address adjusted…”

Some processor architectures place constraints on the addresses at
which breakpoints may be placed. For architectures thus constrained,
GDB will attempt to adjust the breakpoint’s address to comply
with the constraints dictated by the architecture.

One example of such an architecture is the Fujitsu FR-V. The FR-V is
a VLIW architecture in which a number of RISC-like instructions may be
bundled together for parallel execution. The FR-V architecture
constrains the location of a breakpoint instruction within such a
bundle to the instruction with the lowest address. GDB
honors this constraint by adjusting a breakpoint’s address to the
first in the bundle.

It is not uncommon for optimized code to have bundles which contain
instructions from different source statements, thus it may happen that
a breakpoint’s address will be adjusted from one source statement to
another. Since this adjustment may significantly alter GDB’s
breakpoint related behavior from what the user expects, a warning is
printed when the breakpoint is first set and also when the breakpoint
is hit.

A warning like the one below is printed when setting a breakpoint
that’s been subject to address adjustment:

warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.

Such warnings are printed both for user settable and GDB’s
internal breakpoints. If you see one of these warnings, you should
verify that a breakpoint set at the adjusted address will have the
desired affect. If not, the breakpoint in question may be removed and
other breakpoints may be set which will have the desired behavior.
E.g., it may be sufficient to place the breakpoint at a later
instruction. A conditional breakpoint may also be useful in some
cases to prevent the breakpoint from triggering too often.

GDB will also issue a warning when stopping at one of these
adjusted breakpoints:

warning: Breakpoint 1 address previously adjusted from 0x00010414
to 0x00010410.

When this warning is encountered, it may be too late to take remedial
action except in cases where the breakpoint is hit earlier or more
frequently than expected.

5.2 Continuing and Stepping

Continuing means resuming program execution until your program
completes normally. In contrast, stepping means executing just
one more “step” of your program, where “step” may mean either one
line of source code, or one machine instruction (depending on what
particular command you use). Either when continuing or when stepping,
your program may stop even sooner, due to a breakpoint or a signal. (If
it stops due to a signal, you may want to use handle, or use
‘signal 0’ to resume execution (see Signals),
or you may step into the signal’s handler (see stepping and signal handlers).)

continue [ignore-count]

c [ignore-count]

fg [ignore-count]

Resume program execution, at the address where your program last stopped;
any breakpoints set at that address are bypassed. The optional argument
ignore-count allows you to specify a further number of times to
ignore a breakpoint at this location; its effect is like that of
ignore (see Break Conditions).

The argument ignore-count is meaningful only when your program
stopped due to a breakpoint. At other times, the argument to
continue is ignored.

The synonyms c and fg (for foreground, as the
debugged program is deemed to be the foreground program) are provided
purely for convenience, and have exactly the same behavior as
continue.

To resume execution at a different place, you can use return
(see Returning from a Function) to go back to the
calling function; or jump (see Continuing at a
Different Address) to go to an arbitrary location in your program.

A typical technique for using stepping is to set a breakpoint
(see Breakpoints; Watchpoints; and Catchpoints) at the
beginning of the function or the section of your program where a problem
is believed to lie, run your program until it stops at that breakpoint,
and then step through the suspect area, examining the variables that are
interesting, until you see the problem happen.

step

Continue running your program until control reaches a different source
line, then stop it and return control to GDB. This command is
abbreviated s.

Warning: If you use the step command while control is
within a function that was compiled without debugging information,
execution proceeds until control reaches a function that does have
debugging information. Likewise, it will not step into a function which
is compiled without debugging information. To step through functions
without debugging information, use the stepi command, described
below.

The step command only stops at the first instruction of a source
line. This prevents the multiple stops that could otherwise occur in
switch statements, for loops, etc. step continues
to stop if a function that has debugging information is called within
the line. In other words, step steps inside any functions
called within the line.

Also, the step command only enters a function if there is line
number information for the function. Otherwise it acts like the
next command. This avoids problems when using cc -gl
on MIPS machines. Previously, step entered subroutines if there
was any debugging information about the routine.

step count

Continue running as in step, but do so count times. If a
breakpoint is reached, or a signal not related to stepping occurs before
count steps, stepping stops right away.

next [count]

Continue to the next source line in the current (innermost) stack frame.
This is similar to step, but function calls that appear within
the line of code are executed without stopping. Execution stops when
control reaches a different line of code at the original stack level
that was executing when you gave the next command. This command
is abbreviated n.

An argument count is a repeat count, as for step.

The next command only stops at the first instruction of a
source line. This prevents multiple stops that could otherwise occur in
switch statements, for loops, etc.

set step-mode

set step-mode on

The set step-mode on command causes the step command to
stop at the first instruction of a function which contains no debug line
information rather than stepping over it.

This is useful in cases where you may be interested in inspecting the
machine instructions of a function which has no symbolic info and do not
want GDB to automatically skip over this function.

set step-mode off

Causes the step command to step over any functions which contains no
debug information. This is the default.

show step-mode

Show whether GDB will stop in or step over functions without
source line debug information.

finish

Continue running until just after function in the selected stack frame
returns. Print the returned value (if any). This command can be
abbreviated as fin.

Contrast this with the return command (see Returning from a Function).

set print finish [on|off]

show print finish

By default the finish command will show the value that is
returned by the function. This can be disabled using set print
finish off. When disabled, the value is still entered into the value
history (see Value History), but not displayed.

until

u

Continue running until a source line past the current line, in the
current stack frame, is reached. This command is used to avoid single
stepping through a loop more than once. It is like the next
command, except that when until encounters a jump, it
automatically continues execution until the program counter is greater
than the address of the jump.

This means that when you reach the end of a loop after single stepping
though it, until makes your program continue execution until it
exits the loop. In contrast, a next command at the end of a loop
simply steps back to the beginning of the loop, which forces you to step
through the next iteration.

until always stops your program if it attempts to exit the current
stack frame.

until may produce somewhat counterintuitive results if the order
of machine code does not match the order of the source lines. For
example, in the following excerpt from a debugging session, the f
(frame) command shows that execution is stopped at line
206; yet when we use until, we get to line 195:

(gdb) f
#0  main (argc=4, argv=0xf7fffae8) at m4.c:206
206                 expand_input();
(gdb) until
195             for ( ; argc > 0; NEXTARG) {

This happened because, for execution efficiency, the compiler had
generated code for the loop closure test at the end, rather than the
start, of the loop—even though the test in a C for-loop is
written before the body of the loop. The until command appeared
to step back to the beginning of the loop when it advanced to this
expression; however, it has not really gone to an earlier
statement—not in terms of the actual machine code.

until with no argument works by means of single
instruction stepping, and hence is slower than until with an
argument.

until locspec

u locspec

Continue running your program until either it reaches a code location
that results from resolving locspec, or the current stack frame
returns. locspec is any of the forms described in Location Specifications.
This form of the command uses temporary breakpoints, and
hence is quicker than until without an argument. The specified
location is actually reached only if it is in the current frame. This
implies that until can be used to skip over recursive function
invocations. For instance in the code below, if the current location is
line 96, issuing until 99 will execute the program up to
line 99 in the same invocation of factorial, i.e., after the inner
invocations have returned.

94	int factorial (int value)
95	{
96	    if (value > 1) {
97            value *= factorial (value - 1);
98	    }
99	    return (value);
100     }

advance locspec

Continue running your program until either it reaches a code location
that results from resolving locspec, or the current stack frame
returns. locspec is any of the forms described in Location Specifications. This command is similar to until, but
advance will not skip over recursive function calls, and the
target code location doesn’t have to be in the same frame as the
current one.

stepi

stepi arg

si

Execute one machine instruction, then stop and return to the debugger.

It is often useful to do ‘display/i $pc’ when stepping by machine
instructions. This makes GDB automatically display the next
instruction to be executed, each time your program stops. See Automatic Display.

An argument is a repeat count, as in step.

nexti

nexti arg

ni

Execute one machine instruction, but if it is a function call,
proceed until the function returns.

An argument is a repeat count, as in next.

By default, and if available, GDB makes use of
target-assisted range stepping. In other words, whenever you
use a stepping command (e.g., step, next), GDB
tells the target to step the corresponding range of instruction
addresses instead of issuing multiple single-steps. This speeds up
line stepping, particularly for remote targets. Ideally, there should
be no reason you would want to turn range stepping off. However, it’s
possible that a bug in the debug info, a bug in the remote stub (for
remote targets), or even a bug in GDB could make line
stepping behave incorrectly when target-assisted range stepping is
enabled. You can use the following command to turn off range stepping
if necessary:

set range-stepping

show range-stepping

Control whether range stepping is enabled.

If on, and the target supports it, GDB tells the
target to step a range of addresses itself, instead of issuing
multiple single-steps. If off, GDB always issues
single-steps, even if range stepping is supported by the target. The
default is on.

5.3 Skipping Over Functions and Files

The program you are debugging may contain some functions which are
uninteresting to debug. The skip command lets you tell GDB to
skip a function, all functions in a file or a particular function in
a particular file when stepping.

For example, consider the following C function:

101     int func()
102     {
103         foo(boring());
104         bar(boring());
105     }

Suppose you wish to step into the functions foo and bar, but you
are not interested in stepping through boring. If you run step
at line 103, you’ll enter boring(), but if you run next, you’ll
step over both foo and boring!

One solution is to step into boring and use the finish
command to immediately exit it. But this can become tedious if boring
is called from many places.

A more flexible solution is to execute skip boring. This instructs
GDB never to step into boring. Now when you execute
step at line 103, you’ll step over boring and directly into
foo.

Functions may be skipped by providing either a function name, linespec
(see Location Specifications), regular expression that matches the function’s
name, file name or a glob-style pattern that matches the file name.

On Posix systems the form of the regular expression is
“Extended Regular Expressions”. See for example ‘man 7 regex’
on GNU/Linux systems. On non-Posix systems the form of the regular
expression is whatever is provided by the regcomp function of
the underlying system.
See for example ‘man 7 glob’ on GNU/Linux systems for a
description of glob-style patterns.

skip [options]

The basic form of the skip command takes zero or more options
that specify what to skip.
The options argument is any useful combination of the following:

-file file

-fi file

Functions in file will be skipped over when stepping.

-gfile file-glob-pattern

-gfi file-glob-pattern

Functions in files matching file-glob-pattern will be skipped
over when stepping.

(gdb) skip -gfi utils/*.c

-function linespec

-fu linespec

Functions named by linespec or the function containing the line
named by linespec will be skipped over when stepping.
See Location Specifications.

-rfunction regexp

-rfu regexp

Functions whose name matches regexp will be skipped over when stepping.

This form is useful for complex function names.
For example, there is generally no need to step into C++ std::string
constructors or destructors. Plus with C++ templates it can be hard to
write out the full name of the function, and often it doesn’t matter what
the template arguments are. Specifying the function to be skipped as a
regular expression makes this easier.

(gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?1 *(

If you want to skip every templated C++ constructor and destructor
in the std namespace you can do:

(gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?1 *(

If no options are specified, the function you’re currently debugging
will be skipped.

skip function [linespec]

After running this command, the function named by linespec or the
function containing the line named by linespec will be skipped over when
stepping. See Location Specifications.

If you do not specify linespec, the function you’re currently debugging
will be skipped.

(If you have a function called file that you want to skip, use
skip function file.)

skip file [filename]

After running this command, any function whose source lives in filename
will be skipped over when stepping.

(gdb) skip file boring.c
File boring.c will be skipped when stepping.

If you do not specify filename, functions whose source lives in the file
you’re currently debugging will be skipped.

Skips can be listed, deleted, disabled, and enabled, much like breakpoints.
These are the commands for managing your list of skips:

info skip [range]

Print details about the specified skip(s). If range is not specified,
print a table with details about all functions and files marked for skipping.
info skip prints the following information about each skip:

Identifier

A number identifying this skip.

Enabled or Disabled

Enabled skips are marked with ‘y’.
Disabled skips are marked with ‘n’.

Glob

If the file name is a ‘glob’ pattern this is ‘y’.
Otherwise it is ‘n’.

File

The name or ‘glob’ pattern of the file to be skipped.
If no file is specified this is ‘<none>’.

RE

If the function name is a ‘regular expression’ this is ‘y’.
Otherwise it is ‘n’.

Function

The name or regular expression of the function to skip.
If no function is specified this is ‘<none>’.

skip delete [range]

Delete the specified skip(s). If range is not specified, delete all
skips.

skip enable [range]

Enable the specified skip(s). If range is not specified, enable all
skips.

skip disable [range]

Disable the specified skip(s). If range is not specified, disable all
skips.

set debug skip [on|off]

Set whether to print the debug output about skipping files and functions.

show debug skip

Show whether the debug output about skipping files and functions is printed.

5.4 Signals

A signal is an asynchronous event that can happen in a program. The
operating system defines the possible kinds of signals, and gives each
kind a name and a number. For example, in Unix SIGINT is the
signal a program gets when you type an interrupt character (often Ctrl-c);
SIGSEGV is the signal a program gets from referencing a place in
memory far away from all the areas in use; SIGALRM occurs when
the alarm clock timer goes off (which happens only if your program has
requested an alarm).

Some signals, including SIGALRM, are a normal part of the
functioning of your program. Others, such as SIGSEGV, indicate
errors; these signals are fatal (they kill your program immediately) if the
program has not specified in advance some other way to handle the signal.
SIGINT does not indicate an error in your program, but it is normally
fatal so it can carry out the purpose of the interrupt: to kill the program.

GDB has the ability to detect any occurrence of a signal in your
program. You can tell GDB in advance what to do for each kind of
signal.

Normally, GDB is set up to let the non-erroneous signals like
SIGALRM be silently passed to your program
(so as not to interfere with their role in the program’s functioning)
but to stop your program immediately whenever an error signal happens.
You can change these settings with the handle command.

info signals

info handle

Print a table of all the kinds of signals and how GDB has been told to
handle each one. You can use this to see the signal numbers of all
the defined types of signals.

info signals sig

Similar, but print information only about the specified signal number.

info handle is an alias for info signals.

catch signal [signal… | ‘all’]

Set a catchpoint for the indicated signals. See Set Catchpoints,
for details about this command.

handle signal [keywords…]

Change the way GDB handles signal signal. The signal
can be the number of a signal or its name (with or without the
‘SIG’ at the beginning); a list of signal numbers of the form
‘low—high’; or the word ‘all’, meaning all the
known signals. Optional arguments keywords, described below,
say what change to make.

The keywords allowed by the handle command can be abbreviated.
Their full names are:

nostop

GDB should not stop your program when this signal happens. It may
still print a message telling you that the signal has come in.

stop

GDB should stop your program when this signal happens. This implies
the print keyword as well.

print

GDB should print a message when this signal happens.

noprint

GDB should not mention the occurrence of the signal at all. This
implies the nostop keyword as well.

pass

noignore

GDB should allow your program to see this signal; your program
can handle the signal, or else it may terminate if the signal is fatal
and not handled. pass and noignore are synonyms.

nopass

ignore

GDB should not allow your program to see this signal.
nopass and ignore are synonyms.