This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
|
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
|
|
|
INFO-DIR-SECTION Programming & development tools.
|
INFO-DIR-SECTION Programming & development tools.
|
START-INFO-DIR-ENTRY
|
START-INFO-DIR-ENTRY
|
* Gdb: (gdb). The GNU debugger.
|
* Gdb: (gdb). The GNU debugger.
|
END-INFO-DIR-ENTRY
|
END-INFO-DIR-ENTRY
|
|
|
This file documents the GNU debugger GDB.
|
This file documents the GNU debugger GDB.
|
|
|
This is the Eighth Edition, March 2000, of `Debugging with GDB: the
|
This is the Eighth Edition, March 2000, of `Debugging with GDB: the
|
GNU Source-Level Debugger' for GDB Version 5.0.
|
GNU Source-Level Debugger' for GDB Version 5.0.
|
|
|
Copyright (C) 1988-2000 Free Software Foundation, Inc.
|
Copyright (C) 1988-2000 Free Software Foundation, Inc.
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
Permission is granted to make and distribute verbatim copies of this
|
manual provided the copyright notice and this permission notice are
|
manual provided the copyright notice and this permission notice are
|
preserved on all copies.
|
preserved on all copies.
|
|
|
Permission is granted to copy and distribute modified versions of
|
Permission is granted to copy and distribute modified versions of
|
this manual under the conditions for verbatim copying, provided also
|
this manual under the conditions for verbatim copying, provided also
|
that the entire resulting derived work is distributed under the terms
|
that the entire resulting derived work is distributed under the terms
|
of a permission notice identical to this one.
|
of a permission notice identical to this one.
|
|
|
Permission is granted to copy and distribute translations of this
|
Permission is granted to copy and distribute translations of this
|
manual into another language, under the above conditions for modified
|
manual into another language, under the above conditions for modified
|
versions.
|
versions.
|
|
|
|
|
File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir)
|
File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir)
|
|
|
Debugging with GDB
|
Debugging with GDB
|
******************
|
******************
|
|
|
This file describes GDB, the GNU symbolic debugger.
|
This file describes GDB, the GNU symbolic debugger.
|
|
|
This is the Eighth Edition, March 2000, for GDB Version 5.0.
|
This is the Eighth Edition, March 2000, for GDB Version 5.0.
|
|
|
Copyright (C) 1988-2000 Free Software Foundation, Inc.
|
Copyright (C) 1988-2000 Free Software Foundation, Inc.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Summary:: Summary of GDB
|
* Summary:: Summary of GDB
|
* Sample Session:: A sample GDB session
|
* Sample Session:: A sample GDB session
|
|
|
* Invocation:: Getting in and out of GDB
|
* Invocation:: Getting in and out of GDB
|
* Commands:: GDB commands
|
* Commands:: GDB commands
|
* Running:: Running programs under GDB
|
* Running:: Running programs under GDB
|
* Stopping:: Stopping and continuing
|
* Stopping:: Stopping and continuing
|
* Stack:: Examining the stack
|
* Stack:: Examining the stack
|
* Source:: Examining source files
|
* Source:: Examining source files
|
* Data:: Examining data
|
* Data:: Examining data
|
|
|
* Languages:: Using GDB with different languages
|
* Languages:: Using GDB with different languages
|
|
|
* Symbols:: Examining the symbol table
|
* Symbols:: Examining the symbol table
|
* Altering:: Altering execution
|
* Altering:: Altering execution
|
* GDB Files:: GDB files
|
* GDB Files:: GDB files
|
* Targets:: Specifying a debugging target
|
* Targets:: Specifying a debugging target
|
* Configurations:: Configuration-specific information
|
* Configurations:: Configuration-specific information
|
* Controlling GDB:: Controlling GDB
|
* Controlling GDB:: Controlling GDB
|
* Sequences:: Canned sequences of commands
|
* Sequences:: Canned sequences of commands
|
* Emacs:: Using GDB under GNU Emacs
|
* Emacs:: Using GDB under GNU Emacs
|
* Annotations:: GDB's annotation interface.
|
* Annotations:: GDB's annotation interface.
|
* GDB/MI:: GDB's Machine Interface.
|
* GDB/MI:: GDB's Machine Interface.
|
|
|
* GDB Bugs:: Reporting bugs in GDB
|
* GDB Bugs:: Reporting bugs in GDB
|
* Formatting Documentation:: How to format and print GDB documentation
|
* Formatting Documentation:: How to format and print GDB documentation
|
|
|
* Command Line Editing:: Command Line Editing
|
* Command Line Editing:: Command Line Editing
|
* Using History Interactively:: Using History Interactively
|
* Using History Interactively:: Using History Interactively
|
* Installing GDB:: Installing GDB
|
* Installing GDB:: Installing GDB
|
* Index:: Index
|
* Index:: Index
|
|
|
|
|
File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top
|
File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top
|
|
|
Summary of GDB
|
Summary of GDB
|
**************
|
**************
|
|
|
The purpose of a debugger such as GDB is to allow you to see what is
|
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
|
going on "inside" another program while it executes--or what another
|
program was doing at the moment it crashed.
|
program was doing at the moment it crashed.
|
|
|
GDB can do four main kinds of things (plus other things in support of
|
GDB can do four main kinds of things (plus other things in support of
|
these) to help you catch bugs in the act:
|
these) to help you catch bugs in the act:
|
|
|
* Start your program, specifying anything that might affect its
|
* Start your program, specifying anything that might affect its
|
behavior.
|
behavior.
|
|
|
* Make your program stop on specified conditions.
|
* Make your program stop on specified conditions.
|
|
|
* Examine what has happened, when your program has stopped.
|
* Examine what has happened, when your program has stopped.
|
|
|
* Change things in your program, so you can experiment with
|
* Change things in your program, so you can experiment with
|
correcting the effects of one bug and go on to learn about another.
|
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
|
You can use GDB to debug programs written in C and C++. For more
|
information, see *Note Supported languages: Support. For more
|
information, see *Note Supported languages: Support. For more
|
information, see *Note C and C++: C.
|
information, see *Note C and C++: C.
|
|
|
Support for Modula-2 and Chill is partial. For information on
|
Support for Modula-2 and Chill is partial. For information on
|
Modula-2, see *Note Modula-2: Modula-2. For information on Chill, see
|
Modula-2, see *Note Modula-2: Modula-2. For information on Chill, see
|
*Note Chill::.
|
*Note Chill::.
|
|
|
Debugging Pascal programs which use sets, subranges, file variables,
|
Debugging Pascal programs which use sets, subranges, file variables,
|
or nested functions does not currently work. GDB does not support
|
or nested functions does not currently work. GDB does not support
|
entering expressions, printing values, or similar features using Pascal
|
entering expressions, printing values, or similar features using Pascal
|
syntax.
|
syntax.
|
|
|
GDB can be used to debug programs written in Fortran, although it
|
GDB can be used to debug programs written in Fortran, although it
|
may be necessary to refer to some variables with a trailing underscore.
|
may be necessary to refer to some variables with a trailing underscore.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Free Software:: Freely redistributable software
|
* Free Software:: Freely redistributable software
|
* Contributors:: Contributors to GDB
|
* Contributors:: Contributors to GDB
|
|
|
|
|
File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary
|
File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary
|
|
|
Free software
|
Free software
|
=============
|
=============
|
|
|
GDB is "free software", protected by the GNU General Public License
|
GDB is "free software", protected by the GNU General Public License
|
(GPL). The GPL gives you the freedom to copy or adapt a licensed
|
(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
|
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
|
to modify that copy (which means that they must get access to the
|
source code), and the freedom to distribute further copies. Typical
|
source code), and the freedom to distribute further copies. Typical
|
software companies use copyrights to limit your freedoms; the Free
|
software companies use copyrights to limit your freedoms; the Free
|
Software Foundation uses the GPL to preserve these freedoms.
|
Software Foundation uses the GPL to preserve these freedoms.
|
|
|
Fundamentally, the General Public License is a license which says
|
Fundamentally, the General Public License is a license which says
|
that you have these freedoms and that you cannot take these freedoms
|
that you have these freedoms and that you cannot take these freedoms
|
away from anyone else.
|
away from anyone else.
|
|
|
|
|
File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary
|
File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary
|
|
|
Contributors to GDB
|
Contributors to GDB
|
===================
|
===================
|
|
|
Richard Stallman was the original author of GDB, and of many other
|
Richard Stallman was the original author of GDB, and of many other
|
GNU programs. Many others have contributed to its development. This
|
GNU programs. Many others have contributed to its development. This
|
section attempts to credit major contributors. One of the virtues of
|
section attempts to credit major contributors. One of the virtues of
|
free software is that everyone is free to contribute to it; with
|
free software is that everyone is free to contribute to it; with
|
regret, we cannot actually acknowledge everyone here. The file
|
regret, we cannot actually acknowledge everyone here. The file
|
`ChangeLog' in the GDB distribution approximates a blow-by-blow account.
|
`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.
|
Changes much prior to version 2.0 are lost in the mists of time.
|
|
|
_Plea:_ Additions to this section are particularly welcome. If you
|
_Plea:_ Additions to this section are particularly welcome. If you
|
or your friends (or enemies, to be evenhanded) have been unfairly
|
or your friends (or enemies, to be evenhanded) have been unfairly
|
omitted from this list, we would like to add your names!
|
omitted from this list, we would like to add your names!
|
|
|
So that they may not regard their many labors as thankless, we
|
So that they may not regard their many labors as thankless, we
|
particularly thank those who shepherded GDB through major releases:
|
particularly thank those who shepherded GDB through major releases:
|
Andrew Cagney (release 5.0); Jim Blandy (release 4.18); Jason Molenda
|
Andrew Cagney (release 5.0); Jim Blandy (release 4.18); Jason Molenda
|
(release 4.17); Stan Shebs (release 4.14); Fred Fish (releases 4.16,
|
(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
|
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,
|
(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
|
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).
|
Randy Smith (releases 3.2, 3.1, and 3.0).
|
|
|
Richard Stallman, assisted at various times by Peter TerMaat, Chris
|
Richard Stallman, assisted at various times by Peter TerMaat, Chris
|
Hanson, and Richard Mlynarik, handled releases through 2.8.
|
Hanson, and Richard Mlynarik, handled releases through 2.8.
|
|
|
Michael Tiemann is the author of most of the GNU C++ support in GDB,
|
Michael Tiemann is the author of most of the GNU C++ support in GDB,
|
with significant additional contributions from Per Bothner. James
|
with significant additional contributions from Per Bothner. James
|
Clark wrote the GNU C++ demangler. Early work on C++ was by Peter
|
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).
|
TerMaat (who also did much general update work leading to release 3.0).
|
|
|
GDB 4 uses the BFD subroutine library to examine multiple
|
GDB 4 uses the BFD subroutine library to examine multiple
|
object-file formats; BFD was a joint project of David V.
|
object-file formats; BFD was a joint project of David V.
|
Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
|
Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
|
|
|
David Johnson wrote the original COFF support; Pace Willison did the
|
David Johnson wrote the original COFF support; Pace Willison did the
|
original support for encapsulated COFF.
|
original support for encapsulated COFF.
|
|
|
Brent Benson of Harris Computer Systems contributed DWARF 2 support.
|
Brent Benson of Harris Computer Systems contributed DWARF 2 support.
|
|
|
Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
|
Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
|
Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
|
Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
|
support. Jean-Daniel Fekete contributed Sun 386i support. Chris
|
support. Jean-Daniel Fekete contributed Sun 386i support. Chris
|
Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
|
Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
|
Hasei contributed Sony/News OS 3 support. David Johnson contributed
|
Hasei contributed Sony/News OS 3 support. David Johnson contributed
|
Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
|
Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
|
Jeff Law contributed HP PA and SOM support. Keith Packard contributed
|
Jeff Law contributed HP PA and SOM support. Keith Packard contributed
|
NS32K support. Doug Rabson contributed Acorn Risc Machine support.
|
NS32K support. Doug Rabson contributed Acorn Risc Machine support.
|
Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith
|
Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith
|
contributed Convex support (and Fortran debugging). Jonathan Stone
|
contributed Convex support (and Fortran debugging). Jonathan Stone
|
contributed Pyramid support. Michael Tiemann contributed SPARC support.
|
contributed Pyramid support. Michael Tiemann contributed SPARC support.
|
Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
|
Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
|
Pace Willison contributed Intel 386 support. Jay Vosburgh contributed
|
Pace Willison contributed Intel 386 support. Jay Vosburgh contributed
|
Symmetry support.
|
Symmetry support.
|
|
|
Andreas Schwab contributed M68K Linux support.
|
Andreas Schwab contributed M68K Linux support.
|
|
|
Rich Schaefer and Peter Schauer helped with support of SunOS shared
|
Rich Schaefer and Peter Schauer helped with support of SunOS shared
|
libraries.
|
libraries.
|
|
|
Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
|
Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
|
several machine instruction sets.
|
several machine instruction sets.
|
|
|
Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
|
Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
|
develop remote debugging. Intel Corporation, Wind River Systems, AMD,
|
develop remote debugging. Intel Corporation, Wind River Systems, AMD,
|
and ARM contributed remote debugging modules for the i960, VxWorks,
|
and ARM contributed remote debugging modules for the i960, VxWorks,
|
A29K UDI, and RDI targets, respectively.
|
A29K UDI, and RDI targets, respectively.
|
|
|
Brian Fox is the author of the readline libraries providing
|
Brian Fox is the author of the readline libraries providing
|
command-line editing and command history.
|
command-line editing and command history.
|
|
|
Andrew Beers of SUNY Buffalo wrote the language-switching code, the
|
Andrew Beers of SUNY Buffalo wrote the language-switching code, the
|
Modula-2 support, and contributed the Languages chapter of this manual.
|
Modula-2 support, and contributed the Languages chapter of this manual.
|
|
|
Fred Fish wrote most of the support for Unix System Vr4. He also
|
Fred Fish wrote most of the support for Unix System Vr4. He also
|
enhanced the command-completion support to cover C++ overloaded symbols.
|
enhanced the command-completion support to cover C++ overloaded symbols.
|
|
|
Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and
|
Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and
|
Super-H processors.
|
Super-H processors.
|
|
|
NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx
|
NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx
|
processors.
|
processors.
|
|
|
Mitsubishi sponsored the support for D10V, D30V, and M32R/D
|
Mitsubishi sponsored the support for D10V, D30V, and M32R/D
|
processors.
|
processors.
|
|
|
Toshiba sponsored the support for the TX39 Mips processor.
|
Toshiba sponsored the support for the TX39 Mips processor.
|
|
|
Matsushita sponsored the support for the MN10200 and MN10300
|
Matsushita sponsored the support for the MN10200 and MN10300
|
processors.
|
processors.
|
|
|
Fujitsu sponsored the support for SPARClite and FR30 processors.
|
Fujitsu sponsored the support for SPARClite and FR30 processors.
|
|
|
Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
|
Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
|
watchpoints.
|
watchpoints.
|
|
|
Michael Snyder added support for tracepoints.
|
Michael Snyder added support for tracepoints.
|
|
|
Stu Grossman wrote gdbserver.
|
Stu Grossman wrote gdbserver.
|
|
|
Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly
|
Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly
|
innumerable bug fixes and cleanups throughout GDB.
|
innumerable bug fixes and cleanups throughout GDB.
|
|
|
The following people at the Hewlett-Packard Company contributed
|
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
|
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++
|
(narrow mode), HP's implementation of kernel threads, HP's aC++
|
compiler, and the terminal user interface: Ben Krepp, Richard Title,
|
compiler, and the terminal user interface: Ben Krepp, Richard Title,
|
John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve
|
John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve
|
Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific
|
Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific
|
information in this manual.
|
information in this manual.
|
|
|
Cygnus Solutions has sponsored GDB maintenance and much of its
|
Cygnus Solutions has sponsored GDB maintenance and much of its
|
development since 1991. Cygnus engineers who have worked on GDB
|
development since 1991. Cygnus engineers who have worked on GDB
|
fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
|
fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
|
Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
|
Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
|
Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
|
Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
|
Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
|
Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
|
Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
|
Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
|
addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
|
addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
|
JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
|
JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
|
Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
|
Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
|
Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
|
Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
|
Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
|
Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
|
Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
|
Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
|
Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
|
Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
|
Zuhn have made contributions both large and small.
|
Zuhn have made contributions both large and small.
|
|
|
|
|
File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top
|
File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top
|
|
|
A Sample GDB Session
|
A Sample GDB Session
|
********************
|
********************
|
|
|
You can use this manual at your leisure to read all about GDB.
|
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
|
However, a handful of commands are enough to get started using the
|
debugger. This chapter illustrates those commands.
|
debugger. This chapter illustrates those commands.
|
|
|
One of the preliminary versions of GNU `m4' (a generic macro
|
One of the preliminary versions of GNU `m4' (a generic macro
|
processor) exhibits the following bug: sometimes, when we change its
|
processor) exhibits the following bug: sometimes, when we change its
|
quote strings from the default, the commands used to capture one macro
|
quote strings from the default, the commands used to capture one macro
|
definition within another stop working. In the following short `m4'
|
definition within another stop working. In the following short `m4'
|
session, we define a macro `foo' which expands to `0000'; we then use
|
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,
|
the `m4' built-in `defn' to define `bar' as the same thing. However,
|
when we change the open quote string to `' and the close quote
|
when we change the open quote string to `' and the close quote
|
string to `', the same procedure fails to define a new synonym
|
string to `', the same procedure fails to define a new synonym
|
`baz':
|
`baz':
|
|
|
$ cd gnu/m4
|
$ cd gnu/m4
|
$ ./m4
|
$ ./m4
|
define(foo,0000)
|
define(foo,0000)
|
|
|
foo
|
foo
|
0000
|
0000
|
define(bar,defn(`foo'))
|
define(bar,defn(`foo'))
|
|
|
bar
|
bar
|
0000
|
0000
|
changequote(,)
|
changequote(,)
|
|
|
define(baz,defn(foo))
|
define(baz,defn(foo))
|
baz
|
baz
|
C-d
|
C-d
|
m4: End of input: 0: fatal error: EOF in string
|
m4: End of input: 0: fatal error: EOF in string
|
|
|
Let us use GDB to try to see what is going on.
|
Let us use GDB to try to see what is going on.
|
|
|
$ gdb m4
|
$ gdb m4
|
GDB is free software and you are welcome to distribute copies
|
GDB is free software and you are welcome to distribute copies
|
of it under certain conditions; type "show copying" to see
|
of it under certain conditions; type "show copying" to see
|
the conditions.
|
the conditions.
|
There is absolutely no warranty for GDB; type "show warranty"
|
There is absolutely no warranty for GDB; type "show warranty"
|
for details.
|
for details.
|
|
|
GDB 5.0, Copyright 1999 Free Software Foundation, Inc...
|
GDB 5.0, Copyright 1999 Free Software Foundation, Inc...
|
(gdb)
|
(gdb)
|
|
|
GDB reads only enough symbol data to know where to find the rest when
|
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
|
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
|
tell GDB to use a narrower display width than usual, so that examples
|
fit in this manual.
|
fit in this manual.
|
|
|
(gdb) set width 70
|
(gdb) set width 70
|
|
|
We need to see how the `m4' built-in `changequote' works. Having
|
We need to see how the `m4' built-in `changequote' works. Having
|
looked at the source, we know the relevant subroutine is
|
looked at the source, we know the relevant subroutine is
|
`m4_changequote', so we set a breakpoint there with the GDB `break'
|
`m4_changequote', so we set a breakpoint there with the GDB `break'
|
command.
|
command.
|
|
|
(gdb) break m4_changequote
|
(gdb) break m4_changequote
|
Breakpoint 1 at 0x62f4: file builtin.c, line 879.
|
Breakpoint 1 at 0x62f4: file builtin.c, line 879.
|
|
|
Using the `run' command, we start `m4' running under GDB control; as
|
Using the `run' command, we start `m4' running under GDB control; as
|
long as control does not reach the `m4_changequote' subroutine, the
|
long as control does not reach the `m4_changequote' subroutine, the
|
program runs as usual:
|
program runs as usual:
|
|
|
(gdb) run
|
(gdb) run
|
Starting program: /work/Editorial/gdb/gnu/m4/m4
|
Starting program: /work/Editorial/gdb/gnu/m4/m4
|
define(foo,0000)
|
define(foo,0000)
|
|
|
foo
|
foo
|
0000
|
0000
|
|
|
To trigger the breakpoint, we call `changequote'. GDB suspends
|
To trigger the breakpoint, we call `changequote'. GDB suspends
|
execution of `m4', displaying information about the context where it
|
execution of `m4', displaying information about the context where it
|
stops.
|
stops.
|
|
|
changequote(,)
|
changequote(,)
|
|
|
Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
|
Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
|
at builtin.c:879
|
at builtin.c:879
|
879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
|
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
|
Now we use the command `n' (`next') to advance execution to the next
|
line of the current function.
|
line of the current function.
|
|
|
(gdb) n
|
(gdb) n
|
882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
|
882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
|
: nil,
|
: nil,
|
|
|
`set_quotes' looks like a promising subroutine. We can go into it by
|
`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
|
using the command `s' (`step') instead of `next'. `step' goes to the
|
next line to be executed in _any_ subroutine, so it steps into
|
next line to be executed in _any_ subroutine, so it steps into
|
`set_quotes'.
|
`set_quotes'.
|
|
|
(gdb) s
|
(gdb) s
|
set_quotes (lq=0x34c78 "", rq=0x34c88 "")
|
set_quotes (lq=0x34c78 "", rq=0x34c88 "")
|
at input.c:530
|
at input.c:530
|
530 if (lquote != def_lquote)
|
530 if (lquote != def_lquote)
|
|
|
The display that shows the subroutine where `m4' is now suspended (and
|
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
|
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
|
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
|
spelled `bt'), to see where we are in the stack as a whole: the
|
`backtrace' command displays a stack frame for each active subroutine.
|
`backtrace' command displays a stack frame for each active subroutine.
|
|
|
(gdb) bt
|
(gdb) bt
|
#0 set_quotes (lq=0x34c78 "", rq=0x34c88 "")
|
#0 set_quotes (lq=0x34c78 "", rq=0x34c88 "")
|
at input.c:530
|
at input.c:530
|
#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
|
#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
|
at builtin.c:882
|
at builtin.c:882
|
#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
|
#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
|
#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
|
#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
|
at macro.c:71
|
at macro.c:71
|
#4 0x79dc in expand_input () at macro.c:40
|
#4 0x79dc in expand_input () at macro.c:40
|
#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
|
#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
|
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
|
times, we can use `s'; the next two times we use `n' to avoid falling
|
into the `xstrdup' subroutine.
|
into the `xstrdup' subroutine.
|
|
|
(gdb) s
|
(gdb) s
|
0x3b5c 532 if (rquote != def_rquote)
|
0x3b5c 532 if (rquote != def_rquote)
|
(gdb) s
|
(gdb) s
|
0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
|
0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
|
def_lquote : xstrdup(lq);
|
def_lquote : xstrdup(lq);
|
(gdb) n
|
(gdb) n
|
536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
|
536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
|
: xstrdup(rq);
|
: xstrdup(rq);
|
(gdb) n
|
(gdb) n
|
538 len_lquote = strlen(rquote);
|
538 len_lquote = strlen(rquote);
|
|
|
The last line displayed looks a little odd; we can examine the variables
|
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
|
`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
|
quotes we specified. We use the command `p' (`print') to see their
|
values.
|
values.
|
|
|
(gdb) p lquote
|
(gdb) p lquote
|
$1 = 0x35d40 ""
|
$1 = 0x35d40 ""
|
(gdb) p rquote
|
(gdb) p rquote
|
$2 = 0x35d50 ""
|
$2 = 0x35d50 ""
|
|
|
`lquote' and `rquote' are indeed the new left and right quotes. To
|
`lquote' and `rquote' are indeed the new left and right quotes. To
|
look at some context, we can display ten lines of source surrounding
|
look at some context, we can display ten lines of source surrounding
|
the current line with the `l' (`list') command.
|
the current line with the `l' (`list') command.
|
|
|
(gdb) l
|
(gdb) l
|
533 xfree(rquote);
|
533 xfree(rquote);
|
534
|
534
|
535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
|
535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
|
: xstrdup (lq);
|
: xstrdup (lq);
|
536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
|
536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
|
: xstrdup (rq);
|
: xstrdup (rq);
|
537
|
537
|
538 len_lquote = strlen(rquote);
|
538 len_lquote = strlen(rquote);
|
539 len_rquote = strlen(lquote);
|
539 len_rquote = strlen(lquote);
|
540 }
|
540 }
|
541
|
541
|
542 void
|
542 void
|
|
|
Let us step past the two lines that set `len_lquote' and `len_rquote',
|
Let us step past the two lines that set `len_lquote' and `len_rquote',
|
and then examine the values of those variables.
|
and then examine the values of those variables.
|
|
|
(gdb) n
|
(gdb) n
|
539 len_rquote = strlen(lquote);
|
539 len_rquote = strlen(lquote);
|
(gdb) n
|
(gdb) n
|
540 }
|
540 }
|
(gdb) p len_lquote
|
(gdb) p len_lquote
|
$3 = 9
|
$3 = 9
|
(gdb) p len_rquote
|
(gdb) p len_rquote
|
$4 = 7
|
$4 = 7
|
|
|
That certainly looks wrong, assuming `len_lquote' and `len_rquote' are
|
That certainly looks wrong, assuming `len_lquote' and `len_rquote' are
|
meant to be the lengths of `lquote' and `rquote' respectively. We can
|
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
|
set them to better values using the `p' command, since it can print the
|
value of any expression--and that expression can include subroutine
|
value of any expression--and that expression can include subroutine
|
calls and assignments.
|
calls and assignments.
|
|
|
(gdb) p len_lquote=strlen(lquote)
|
(gdb) p len_lquote=strlen(lquote)
|
$5 = 7
|
$5 = 7
|
(gdb) p len_rquote=strlen(rquote)
|
(gdb) p len_rquote=strlen(rquote)
|
$6 = 9
|
$6 = 9
|
|
|
Is that enough to fix the problem of using the new quotes with the `m4'
|
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'
|
built-in `defn'? We can allow `m4' to continue executing with the `c'
|
(`continue') command, and then try the example that caused trouble
|
(`continue') command, and then try the example that caused trouble
|
initially:
|
initially:
|
|
|
(gdb) c
|
(gdb) c
|
Continuing.
|
Continuing.
|
|
|
define(baz,defn(foo))
|
define(baz,defn(foo))
|
|
|
baz
|
baz
|
0000
|
0000
|
|
|
Success! The new quotes now work just as well as the default ones. The
|
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
|
problem seems to have been just the two typos defining the wrong
|
lengths. We allow `m4' exit by giving it an EOF as input:
|
lengths. We allow `m4' exit by giving it an EOF as input:
|
|
|
C-d
|
C-d
|
Program exited normally.
|
Program exited normally.
|
|
|
The message `Program exited normally.' is from GDB; it indicates `m4'
|
The message `Program exited normally.' is from GDB; it indicates `m4'
|
has finished executing. We can end our GDB session with the GDB `quit'
|
has finished executing. We can end our GDB session with the GDB `quit'
|
command.
|
command.
|
|
|
(gdb) quit
|
(gdb) quit
|
|
|
|
|
File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top
|
File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top
|
|
|
Getting In and Out of GDB
|
Getting In and Out of GDB
|
*************************
|
*************************
|
|
|
This chapter discusses how to start GDB, and how to get out of it.
|
This chapter discusses how to start GDB, and how to get out of it.
|
The essentials are:
|
The essentials are:
|
* type `gdb' to start GDB.
|
* type `gdb' to start GDB.
|
|
|
* type `quit' or `C-d' to exit.
|
* type `quit' or `C-d' to exit.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Invoking GDB:: How to start GDB
|
* Invoking GDB:: How to start GDB
|
* Quitting GDB:: How to quit GDB
|
* Quitting GDB:: How to quit GDB
|
* Shell Commands:: How to use shell commands inside GDB
|
* Shell Commands:: How to use shell commands inside GDB
|
|
|
|
|
File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation
|
File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation
|
|
|
Invoking GDB
|
Invoking GDB
|
============
|
============
|
|
|
Invoke GDB by running the program `gdb'. Once started, GDB reads
|
Invoke GDB by running the program `gdb'. Once started, GDB reads
|
commands from the terminal until you tell it to exit.
|
commands from the terminal until you tell it to exit.
|
|
|
You can also run `gdb' with a variety of arguments and options, to
|
You can also run `gdb' with a variety of arguments and options, to
|
specify more of your debugging environment at the outset.
|
specify more of your debugging environment at the outset.
|
|
|
The command-line options described here are designed to cover a
|
The command-line options described here are designed to cover a
|
variety of situations; in some environments, some of these options may
|
variety of situations; in some environments, some of these options may
|
effectively be unavailable.
|
effectively be unavailable.
|
|
|
The most usual way to start GDB is with one argument, specifying an
|
The most usual way to start GDB is with one argument, specifying an
|
executable program:
|
executable program:
|
|
|
gdb PROGRAM
|
gdb PROGRAM
|
|
|
You can also start with both an executable program and a core file
|
You can also start with both an executable program and a core file
|
specified:
|
specified:
|
|
|
gdb PROGRAM CORE
|
gdb PROGRAM CORE
|
|
|
You can, instead, specify a process ID as a second argument, if you
|
You can, instead, specify a process ID as a second argument, if you
|
want to debug a running process:
|
want to debug a running process:
|
|
|
gdb PROGRAM 1234
|
gdb PROGRAM 1234
|
|
|
would attach GDB to process `1234' (unless you also have a file named
|
would attach GDB to process `1234' (unless you also have a file named
|
`1234'; GDB does check for a core file first).
|
`1234'; GDB does check for a core file first).
|
|
|
Taking advantage of the second command-line argument requires a
|
Taking advantage of the second command-line argument requires a
|
fairly complete operating system; when you use GDB as a remote debugger
|
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
|
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
|
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.
|
unable to attach or to read core dumps.
|
|
|
You can run `gdb' without printing the front material, which
|
You can run `gdb' without printing the front material, which
|
describes GDB's non-warranty, by specifying `-silent':
|
describes GDB's non-warranty, by specifying `-silent':
|
|
|
gdb -silent
|
gdb -silent
|
|
|
You can further control how GDB starts up by using command-line
|
You can further control how GDB starts up by using command-line
|
options. GDB itself can remind you of the options available.
|
options. GDB itself can remind you of the options available.
|
|
|
Type
|
Type
|
|
|
gdb -help
|
gdb -help
|
|
|
to display all available options and briefly describe their use (`gdb
|
to display all available options and briefly describe their use (`gdb
|
-h' is a shorter equivalent).
|
-h' is a shorter equivalent).
|
|
|
All options and command line arguments you give are processed in
|
All options and command line arguments you give are processed in
|
sequential order. The order makes a difference when the `-x' option is
|
sequential order. The order makes a difference when the `-x' option is
|
used.
|
used.
|
|
|
* Menu:
|
* Menu:
|
|
|
* File Options:: Choosing files
|
* File Options:: Choosing files
|
* Mode Options:: Choosing modes
|
* Mode Options:: Choosing modes
|
|
|
|
|
File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB
|
File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB
|
|
|
Choosing files
|
Choosing files
|
--------------
|
--------------
|
|
|
When GDB starts, it reads any arguments other than options as
|
When GDB starts, it reads any arguments other than options as
|
specifying an executable file and core file (or process ID). This is
|
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'
|
the same as if the arguments were specified by the `-se' and `-c'
|
options respectively. (GDB reads the first argument that does not have
|
options respectively. (GDB reads the first argument that does not have
|
an associated option flag as equivalent to the `-se' option followed by
|
an associated option flag as equivalent to the `-se' option followed by
|
that argument; and the second argument that does not have an associated
|
that argument; and the second argument that does not have an associated
|
option flag, if any, as equivalent to the `-c' option followed by that
|
option flag, if any, as equivalent to the `-c' option followed by that
|
argument.)
|
argument.)
|
|
|
If GDB has not been configured to included core file support, such
|
If GDB has not been configured to included core file support, such
|
as for most embedded targets, then it will complain about a second
|
as for most embedded targets, then it will complain about a second
|
argument and ignore it.
|
argument and ignore it.
|
|
|
Many options have both long and short forms; both are shown in the
|
Many options have both long and short forms; both are shown in the
|
following list. GDB also recognizes the long forms if you truncate
|
following list. GDB also recognizes the long forms if you truncate
|
them, so long as enough of the option is present to be unambiguous.
|
them, so long as enough of the option is present to be unambiguous.
|
(If you prefer, you can flag option arguments with `--' rather than
|
(If you prefer, you can flag option arguments with `--' rather than
|
`-', though we illustrate the more usual convention.)
|
`-', though we illustrate the more usual convention.)
|
|
|
`-symbols FILE'
|
`-symbols FILE'
|
`-s FILE'
|
`-s FILE'
|
Read symbol table from file FILE.
|
Read symbol table from file FILE.
|
|
|
`-exec FILE'
|
`-exec FILE'
|
`-e FILE'
|
`-e FILE'
|
Use file FILE as the executable file to execute when appropriate,
|
Use file FILE as the executable file to execute when appropriate,
|
and for examining pure data in conjunction with a core dump.
|
and for examining pure data in conjunction with a core dump.
|
|
|
`-se FILE'
|
`-se FILE'
|
Read symbol table from file FILE and use it as the executable file.
|
Read symbol table from file FILE and use it as the executable file.
|
|
|
`-core FILE'
|
`-core FILE'
|
`-c FILE'
|
`-c FILE'
|
Use file FILE as a core dump to examine.
|
Use file FILE as a core dump to examine.
|
|
|
`-c NUMBER'
|
`-c NUMBER'
|
Connect to process ID NUMBER, as with the `attach' command (unless
|
Connect to process ID NUMBER, as with the `attach' command (unless
|
there is a file in core-dump format named NUMBER, in which case
|
there is a file in core-dump format named NUMBER, in which case
|
`-c' specifies that file as a core dump to read).
|
`-c' specifies that file as a core dump to read).
|
|
|
`-command FILE'
|
`-command FILE'
|
`-x FILE'
|
`-x FILE'
|
Execute GDB commands from file FILE. *Note Command files: Command
|
Execute GDB commands from file FILE. *Note Command files: Command
|
Files.
|
Files.
|
|
|
`-directory DIRECTORY'
|
`-directory DIRECTORY'
|
`-d DIRECTORY'
|
`-d DIRECTORY'
|
Add DIRECTORY to the path to search for source files.
|
Add DIRECTORY to the path to search for source files.
|
|
|
`-m'
|
`-m'
|
`-mapped'
|
`-mapped'
|
_Warning: this option depends on operating system facilities that
|
_Warning: this option depends on operating system facilities that
|
are not supported on all systems._
|
are not supported on all systems._
|
If memory-mapped files are available on your system through the
|
If memory-mapped files are available on your system through the
|
`mmap' system call, you can use this option to have GDB write the
|
`mmap' system call, you can use this option to have GDB write the
|
symbols from your program into a reusable file in the current
|
symbols from your program into a reusable file in the current
|
directory. If the program you are debugging is called
|
directory. If the program you are debugging is called
|
`/tmp/fred', the mapped symbol file is `/tmp/fred.syms'. Future
|
`/tmp/fred', the mapped symbol file is `/tmp/fred.syms'. Future
|
GDB debugging sessions notice the presence of this file, and can
|
GDB debugging sessions notice the presence of this file, and can
|
quickly map in symbol information from it, rather than reading the
|
quickly map in symbol information from it, rather than reading the
|
symbol table from the executable program.
|
symbol table from the executable program.
|
|
|
The `.syms' file is specific to the host machine where GDB is run.
|
The `.syms' file is specific to the host machine where GDB is run.
|
It holds an exact image of the internal GDB symbol table. It
|
It holds an exact image of the internal GDB symbol table. It
|
cannot be shared across multiple host platforms.
|
cannot be shared across multiple host platforms.
|
|
|
`-r'
|
`-r'
|
`-readnow'
|
`-readnow'
|
Read each symbol file's entire symbol table immediately, rather
|
Read each symbol file's entire symbol table immediately, rather
|
than the default, which is to read it incrementally as it is
|
than the default, which is to read it incrementally as it is
|
needed. This makes startup slower, but makes future operations
|
needed. This makes startup slower, but makes future operations
|
faster.
|
faster.
|
|
|
You typically combine the `-mapped' and `-readnow' options in order
|
You typically combine the `-mapped' and `-readnow' options in order
|
to build a `.syms' file that contains complete symbol information.
|
to build a `.syms' file that contains complete symbol information.
|
(*Note Commands to specify files: Files, for information on `.syms'
|
(*Note Commands to specify files: Files, for information on `.syms'
|
files.) A simple GDB invocation to do nothing but build a `.syms' file
|
files.) A simple GDB invocation to do nothing but build a `.syms' file
|
for future use is:
|
for future use is:
|
|
|
gdb -batch -nx -mapped -readnow programname
|
gdb -batch -nx -mapped -readnow programname
|
|
|
|
|
File: gdb.info, Node: Mode Options, Prev: File Options, Up: Invoking GDB
|
File: gdb.info, Node: Mode Options, Prev: File Options, Up: Invoking GDB
|
|
|
Choosing modes
|
Choosing modes
|
--------------
|
--------------
|
|
|
You can run GDB in various alternative modes--for example, in batch
|
You can run GDB in various alternative modes--for example, in batch
|
mode or quiet mode.
|
mode or quiet mode.
|
|
|
`-nx'
|
`-nx'
|
`-n'
|
`-n'
|
Do not execute commands found in any initialization files (normally
|
Do not execute commands found in any initialization files (normally
|
called `.gdbinit', or `gdb.ini' on PCs). Normally, GDB executes
|
called `.gdbinit', or `gdb.ini' on PCs). Normally, GDB executes
|
the commands in these files after all the command options and
|
the commands in these files after all the command options and
|
arguments have been processed. *Note Command files: Command Files.
|
arguments have been processed. *Note Command files: Command Files.
|
|
|
`-quiet'
|
`-quiet'
|
`-silent'
|
`-silent'
|
`-q'
|
`-q'
|
"Quiet". Do not print the introductory and copyright messages.
|
"Quiet". Do not print the introductory and copyright messages.
|
These messages are also suppressed in batch mode.
|
These messages are also suppressed in batch mode.
|
|
|
`-batch'
|
`-batch'
|
Run in batch mode. Exit with status `0' after processing all the
|
Run in batch mode. Exit with status `0' after processing all the
|
command files specified with `-x' (and all commands from
|
command files specified with `-x' (and all commands from
|
initialization files, if not inhibited with `-n'). Exit with
|
initialization files, if not inhibited with `-n'). Exit with
|
nonzero status if an error occurs in executing the GDB commands in
|
nonzero status if an error occurs in executing the GDB commands in
|
the command files.
|
the command files.
|
|
|
Batch mode may be useful for running GDB as a filter, for example
|
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
|
to download and run a program on another computer; in order to
|
make this more useful, the message
|
make this more useful, the message
|
|
|
Program exited normally.
|
Program exited normally.
|
|
|
(which is ordinarily issued whenever a program running under GDB
|
(which is ordinarily issued whenever a program running under GDB
|
control terminates) is not issued when running in batch mode.
|
control terminates) is not issued when running in batch mode.
|
|
|
`-nowindows'
|
`-nowindows'
|
`-nw'
|
`-nw'
|
"No windows". If GDB comes with a graphical user interface (GUI)
|
"No windows". If GDB comes with a graphical user interface (GUI)
|
built in, then this option tells GDB to only use the command-line
|
built in, then this option tells GDB to only use the command-line
|
interface. If no GUI is available, this option has no effect.
|
interface. If no GUI is available, this option has no effect.
|
|
|
`-windows'
|
`-windows'
|
`-w'
|
`-w'
|
If GDB includes a GUI, then this option requires it to be used if
|
If GDB includes a GUI, then this option requires it to be used if
|
possible.
|
possible.
|
|
|
`-cd DIRECTORY'
|
`-cd DIRECTORY'
|
Run GDB using DIRECTORY as its working directory, instead of the
|
Run GDB using DIRECTORY as its working directory, instead of the
|
current directory.
|
current directory.
|
|
|
`-fullname'
|
`-fullname'
|
`-f'
|
`-f'
|
GNU Emacs sets this option when it runs GDB as a subprocess. It
|
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
|
tells GDB to output the full file name and line number in a
|
standard, recognizable fashion each time a stack frame is
|
standard, recognizable fashion each time a stack frame is
|
displayed (which includes each time your program stops). This
|
displayed (which includes each time your program stops). This
|
recognizable format looks like two `\032' characters, followed by
|
recognizable format looks like two `\032' characters, followed by
|
the file name, line number and character position separated by
|
the file name, line number and character position separated by
|
colons, and a newline. The Emacs-to-GDB interface program uses
|
colons, and a newline. The Emacs-to-GDB interface program uses
|
the two `\032' characters as a signal to display the source code
|
the two `\032' characters as a signal to display the source code
|
for the frame.
|
for the frame.
|
|
|
`-epoch'
|
`-epoch'
|
The Epoch Emacs-GDB interface sets this option when it runs GDB as
|
The Epoch Emacs-GDB interface sets this option when it runs GDB as
|
a subprocess. It tells GDB to modify its print routines so as to
|
a subprocess. It tells GDB to modify its print routines so as to
|
allow Epoch to display values of expressions in a separate window.
|
allow Epoch to display values of expressions in a separate window.
|
|
|
`-annotate LEVEL'
|
`-annotate LEVEL'
|
This option sets the "annotation level" inside GDB. Its effect is
|
This option sets the "annotation level" inside GDB. Its effect is
|
identical to using `set annotate LEVEL' (*note Annotations::).
|
identical to using `set annotate LEVEL' (*note Annotations::).
|
Annotation level controls how much information does GDB print
|
Annotation level controls how much information does GDB print
|
together with its prompt, values of expressions, source lines, and
|
together with its prompt, values of expressions, source lines, and
|
other types of output. Level 0 is the normal, level 1 is for use
|
other types of output. Level 0 is the normal, level 1 is for use
|
when GDB is run as a subprocess of GNU Emacs, level 2 is the
|
when GDB is run as a subprocess of GNU Emacs, level 2 is the
|
maximum annotation suitable for programs that control GDB.
|
maximum annotation suitable for programs that control GDB.
|
|
|
`-async'
|
`-async'
|
Use the asynchronous event loop for the command-line interface.
|
Use the asynchronous event loop for the command-line interface.
|
GDB processes all events, such as user keyboard input, via a
|
GDB processes all events, such as user keyboard input, via a
|
special event loop. This allows GDB to accept and process user
|
special event loop. This allows GDB to accept and process user
|
commands in parallel with the debugged process being run(1), so
|
commands in parallel with the debugged process being run(1), so
|
you don't need to wait for control to return to GDB before you
|
you don't need to wait for control to return to GDB before you
|
type the next command. (_Note:_ as of version 5.0, the target
|
type the next command. (_Note:_ as of version 5.0, the target
|
side of the asynchronous operation is not yet in place, so
|
side of the asynchronous operation is not yet in place, so
|
`-async' does not work fully yet.)
|
`-async' does not work fully yet.)
|
|
|
When the standard input is connected to a terminal device, GDB
|
When the standard input is connected to a terminal device, GDB
|
uses the asynchronous event loop by default, unless disabled by the
|
uses the asynchronous event loop by default, unless disabled by the
|
`-noasync' option.
|
`-noasync' option.
|
|
|
`-noasync'
|
`-noasync'
|
Disable the asynchronous event loop for the command-line interface.
|
Disable the asynchronous event loop for the command-line interface.
|
|
|
`-baud BPS'
|
`-baud BPS'
|
`-b BPS'
|
`-b BPS'
|
Set the line speed (baud rate or bits per second) of any serial
|
Set the line speed (baud rate or bits per second) of any serial
|
interface used by GDB for remote debugging.
|
interface used by GDB for remote debugging.
|
|
|
`-tty DEVICE'
|
`-tty DEVICE'
|
`-t DEVICE'
|
`-t DEVICE'
|
Run using DEVICE for your program's standard input and output.
|
Run using DEVICE for your program's standard input and output.
|
|
|
`-interpreter INTERP'
|
`-interpreter INTERP'
|
Use the interpreter INTERP for interface with the controlling
|
Use the interpreter INTERP for interface with the controlling
|
program or device. This option is meant to be set by programs
|
program or device. This option is meant to be set by programs
|
which communicate with GDB using it as a back end. For example,
|
which communicate with GDB using it as a back end. For example,
|
`--interpreter=mi' causes GDB to use the "gdbmi interface" (*note
|
`--interpreter=mi' causes GDB to use the "gdbmi interface" (*note
|
The GDB/MI Interface: GDB/MI.).
|
The GDB/MI Interface: GDB/MI.).
|
|
|
`-write'
|
`-write'
|
Open the executable and core files for both reading and writing.
|
Open the executable and core files for both reading and writing.
|
This is equivalent to the `set write on' command inside GDB (*note
|
This is equivalent to the `set write on' command inside GDB (*note
|
Patching::).
|
Patching::).
|
|
|
`-statistics'
|
`-statistics'
|
This option causes GDB to print statistics about time and memory
|
This option causes GDB to print statistics about time and memory
|
usage after it completes each command and returns to the prompt.
|
usage after it completes each command and returns to the prompt.
|
|
|
`-version'
|
`-version'
|
This option causes GDB to print its version number and no-warranty
|
This option causes GDB to print its version number and no-warranty
|
blurb, and exit.
|
blurb, and exit.
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) GDB built with DJGPP tools for MS-DOS/MS-Windows supports this
|
(1) GDB built with DJGPP tools for MS-DOS/MS-Windows supports this
|
mode of operation, but the event loop is suspended when the debuggee
|
mode of operation, but the event loop is suspended when the debuggee
|
runs.
|
runs.
|
|
|
|
|
File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation
|
File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation
|
|
|
Quitting GDB
|
Quitting GDB
|
============
|
============
|
|
|
`quit [EXPRESSION]'
|
`quit [EXPRESSION]'
|
`q'
|
`q'
|
To exit GDB, use the `quit' command (abbreviated `q'), or type an
|
To exit GDB, use the `quit' command (abbreviated `q'), or type an
|
end-of-file character (usually `C-d'). If you do not supply
|
end-of-file character (usually `C-d'). If you do not supply
|
EXPRESSION, GDB will terminate normally; otherwise it will
|
EXPRESSION, GDB will terminate normally; otherwise it will
|
terminate using the result of EXPRESSION as the error code.
|
terminate using the result of EXPRESSION as the error code.
|
|
|
An interrupt (often `C-c') does not exit from GDB, but rather
|
An interrupt (often `C-c') does not exit from GDB, but rather
|
terminates the action of any GDB command that is in progress and
|
terminates the action of any GDB command that is in progress and
|
returns to GDB command level. It is safe to type the interrupt
|
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
|
character at any time because GDB does not allow it to take effect
|
until a time when it is safe.
|
until a time when it is safe.
|
|
|
If you have been using GDB to control an attached process or device,
|
If you have been using GDB to control an attached process or device,
|
you can release it with the `detach' command (*note Debugging an
|
you can release it with the `detach' command (*note Debugging an
|
already-running process: Attach.).
|
already-running process: Attach.).
|
|
|
|
|
File: gdb.info, Node: Shell Commands, Prev: Quitting GDB, Up: Invocation
|
File: gdb.info, Node: Shell Commands, Prev: Quitting GDB, Up: Invocation
|
|
|
Shell commands
|
Shell commands
|
==============
|
==============
|
|
|
If you need to execute occasional shell commands during your
|
If you need to execute occasional shell commands during your
|
debugging session, there is no need to leave or suspend GDB; you can
|
debugging session, there is no need to leave or suspend GDB; you can
|
just use the `shell' command.
|
just use the `shell' command.
|
|
|
`shell COMMAND STRING'
|
`shell COMMAND STRING'
|
Invoke a standard shell to execute COMMAND STRING. If it exists,
|
Invoke a standard shell to execute COMMAND STRING. If it exists,
|
the environment variable `SHELL' determines which shell to run.
|
the environment variable `SHELL' determines which shell to run.
|
Otherwise GDB uses the default shell (`/bin/sh' on Unix systems,
|
Otherwise GDB uses the default shell (`/bin/sh' on Unix systems,
|
`COMMAND.COM' on MS-DOS, etc.).
|
`COMMAND.COM' on MS-DOS, etc.).
|
|
|
The utility `make' is often needed in development environments. You
|
The utility `make' is often needed in development environments. You
|
do not have to use the `shell' command for this purpose in GDB:
|
do not have to use the `shell' command for this purpose in GDB:
|
|
|
`make MAKE-ARGS'
|
`make MAKE-ARGS'
|
Execute the `make' program with the specified arguments. This is
|
Execute the `make' program with the specified arguments. This is
|
equivalent to `shell make MAKE-ARGS'.
|
equivalent to `shell make MAKE-ARGS'.
|
|
|
|
|
File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top
|
File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top
|
|
|
GDB Commands
|
GDB Commands
|
************
|
************
|
|
|
You can abbreviate a GDB command to the first few letters of the
|
You can abbreviate a GDB command to the first few letters of the
|
command name, if that abbreviation is unambiguous; and you can repeat
|
command name, if that abbreviation is unambiguous; and you can repeat
|
certain GDB commands by typing just . You can also use the
|
certain GDB commands by typing just . You can also use the
|
key to get GDB to fill out the rest of a word in a command (or to show
|
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).
|
you the alternatives available, if there is more than one possibility).
|
|
|
* Menu:
|
* Menu:
|
|
|
* Command Syntax:: How to give commands to GDB
|
* Command Syntax:: How to give commands to GDB
|
* Completion:: Command completion
|
* Completion:: Command completion
|
* Help:: How to ask GDB for help
|
* Help:: How to ask GDB for help
|
|
|
|
|
File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands
|
File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands
|
|
|
Command syntax
|
Command syntax
|
==============
|
==============
|
|
|
A GDB command is a single line of input. There is no limit on how
|
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
|
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
|
arguments whose meaning depends on the command name. For example, the
|
command `step' accepts an argument which is the number of times to
|
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
|
step, as in `step 5'. You can also use the `step' command with no
|
arguments. Some commands do not allow any arguments.
|
arguments. Some commands do not allow any arguments.
|
|
|
GDB command names may always be truncated if that abbreviation is
|
GDB command names may always be truncated if that abbreviation is
|
unambiguous. Other possible command abbreviations are listed in the
|
unambiguous. Other possible command abbreviations are listed in the
|
documentation for individual commands. In some cases, even ambiguous
|
documentation for individual commands. In some cases, even ambiguous
|
abbreviations are allowed; for example, `s' is specially defined as
|
abbreviations are allowed; for example, `s' is specially defined as
|
equivalent to `step' even though there are other commands whose names
|
equivalent to `step' even though there are other commands whose names
|
start with `s'. You can test abbreviations by using them as arguments
|
start with `s'. You can test abbreviations by using them as arguments
|
to the `help' command.
|
to the `help' command.
|
|
|
A blank line as input to GDB (typing just ) means to repeat the
|
A blank line as input to GDB (typing just ) means to repeat the
|
previous command. Certain commands (for example, `run') will not
|
previous command. Certain commands (for example, `run') will not
|
repeat this way; these are commands whose unintentional repetition
|
repeat this way; these are commands whose unintentional repetition
|
might cause trouble and which you are unlikely to want to repeat.
|
might cause trouble and which you are unlikely to want to repeat.
|
|
|
The `list' and `x' commands, when you repeat them with ,
|
The `list' and `x' commands, when you repeat them with ,
|
construct new arguments rather than repeating exactly as typed. This
|
construct new arguments rather than repeating exactly as typed. This
|
permits easy scanning of source or memory.
|
permits easy scanning of source or memory.
|
|
|
GDB can also use in another way: to partition lengthy output,
|
GDB can also use in another way: to partition lengthy output,
|
in a way similar to the common utility `more' (*note Screen size:
|
in a way similar to the common utility `more' (*note Screen size:
|
Screen Size.). Since it is easy to press one too many in this
|
Screen Size.). Since it is easy to press one too many in this
|
situation, GDB disables command repetition after any command that
|
situation, GDB disables command repetition after any command that
|
generates this sort of display.
|
generates this sort of display.
|
|
|
Any text from a `#' to the end of the line is a comment; it does
|
Any text from a `#' to the end of the line is a comment; it does
|
nothing. This is useful mainly in command files (*note Command files:
|
nothing. This is useful mainly in command files (*note Command files:
|
Command Files.).
|
Command Files.).
|
|
|
|
|
File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands
|
File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands
|
|
|
Command completion
|
Command completion
|
==================
|
==================
|
|
|
GDB can fill in the rest of a word in a command for you, if there is
|
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
|
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
|
are for the next word in a command, at any time. This works for GDB
|
commands, GDB subcommands, and the names of symbols in your program.
|
commands, GDB subcommands, and the names of symbols in your program.
|
|
|
Press the key whenever you want GDB to fill out the rest of a
|
Press the 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
|
word. If there is only one possibility, GDB fills in the word, and
|
waits for you to finish the command (or press to enter it). For
|
waits for you to finish the command (or press to enter it). For
|
example, if you type
|
example, if you type
|
|
|
(gdb) info bre
|
(gdb) info bre
|
|
|
GDB fills in the rest of the word `breakpoints', since that is the only
|
GDB fills in the rest of the word `breakpoints', since that is the only
|
`info' subcommand beginning with `bre':
|
`info' subcommand beginning with `bre':
|
|
|
(gdb) info breakpoints
|
(gdb) info breakpoints
|
|
|
You can either press at this point, to run the `info breakpoints'
|
You can either press at this point, to run the `info breakpoints'
|
command, or backspace and enter something else, if `breakpoints' does
|
command, or backspace and enter something else, if `breakpoints' does
|
not look like the command you expected. (If you were sure you wanted
|
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
|
`info breakpoints' in the first place, you might as well just type
|
immediately after `info bre', to exploit command abbreviations
|
immediately after `info bre', to exploit command abbreviations
|
rather than command completion).
|
rather than command completion).
|
|
|
If there is more than one possibility for the next word when you
|
If there is more than one possibility for the next word when you
|
press , GDB sounds a bell. You can either supply more characters
|
press , GDB sounds a bell. You can either supply more characters
|
and try again, or just press a second time; GDB displays all the
|
and try again, or just press a second time; GDB displays all the
|
possible completions for that word. For example, you might want to set
|
possible completions for that word. For example, you might want to set
|
a breakpoint on a subroutine whose name begins with `make_', but when
|
a breakpoint on a subroutine whose name begins with `make_', but when
|
you type `b make_' GDB just sounds the bell. Typing again
|
you type `b make_' GDB just sounds the bell. Typing again
|
displays all the function names in your program that begin with those
|
displays all the function names in your program that begin with those
|
characters, for example:
|
characters, for example:
|
|
|
(gdb) b make_
|
(gdb) b make_
|
GDB sounds bell; press again, to see:
|
GDB sounds bell; press again, to see:
|
make_a_section_from_file make_environ
|
make_a_section_from_file make_environ
|
make_abs_section make_function_type
|
make_abs_section make_function_type
|
make_blockvector make_pointer_type
|
make_blockvector make_pointer_type
|
make_cleanup make_reference_type
|
make_cleanup make_reference_type
|
make_command make_symbol_completion_list
|
make_command make_symbol_completion_list
|
(gdb) b make_
|
(gdb) b make_
|
|
|
After displaying the available possibilities, GDB copies your partial
|
After displaying the available possibilities, GDB copies your partial
|
input (`b make_' in the example) so you can finish the command.
|
input (`b make_' in the example) so you can finish the command.
|
|
|
If you just want to see the list of alternatives in the first place,
|
If you just want to see the list of alternatives in the first place,
|
you can press `M-?' rather than pressing twice. `M-?' means
|
you can press `M-?' rather than pressing twice. `M-?' means
|
` ?'. You can type this either by holding down a key designated
|
` ?'. You can type this either by holding down a key designated
|
as the shift on your keyboard (if there is one) while typing
|
as the shift on your keyboard (if there is one) while typing
|
`?', or as followed by `?'.
|
`?', or as followed by `?'.
|
|
|
Sometimes the string you need, while logically a "word", may contain
|
Sometimes the string you need, while logically a "word", may contain
|
parentheses or other characters that GDB normally excludes from its
|
parentheses or other characters that GDB normally excludes from its
|
notion of a word. To permit word completion to work in this situation,
|
notion of a word. To permit word completion to work in this situation,
|
you may enclose words in `'' (single quote marks) in GDB commands.
|
you may enclose words in `'' (single quote marks) in GDB commands.
|
|
|
The most likely situation where you might need this is in typing the
|
The most likely situation where you might need this is in typing the
|
name of a C++ function. This is because C++ allows function overloading
|
name of a C++ function. This is because C++ allows function overloading
|
(multiple definitions of the same function, distinguished by argument
|
(multiple definitions of the same function, distinguished by argument
|
type). For example, when you want to set a breakpoint you may need to
|
type). For example, when you want to set a breakpoint you may need to
|
distinguish whether you mean the version of `name' that takes an `int'
|
distinguish whether you mean the version of `name' that takes an `int'
|
parameter, `name(int)', or the version that takes a `float' parameter,
|
parameter, `name(int)', or the version that takes a `float' parameter,
|
`name(float)'. To use the word-completion facilities in this
|
`name(float)'. To use the word-completion facilities in this
|
situation, type a single quote `'' at the beginning of the function
|
situation, type a single quote `'' at the beginning of the function
|
name. This alerts GDB that it may need to consider more information
|
name. This alerts GDB that it may need to consider more information
|
than usual when you press or `M-?' to request word completion:
|
than usual when you press or `M-?' to request word completion:
|
|
|
(gdb) b 'bubble( M-?
|
(gdb) b 'bubble( M-?
|
bubble(double,double) bubble(int,int)
|
bubble(double,double) bubble(int,int)
|
(gdb) b 'bubble(
|
(gdb) b 'bubble(
|
|
|
In some cases, GDB can tell that completing a name requires using
|
In some cases, GDB can tell that completing a name requires using
|
quotes. When this happens, GDB inserts the quote for you (while
|
quotes. When this happens, GDB inserts the quote for you (while
|
completing as much as it can) if you do not type the quote in the first
|
completing as much as it can) if you do not type the quote in the first
|
place:
|
place:
|
|
|
(gdb) b bub
|
(gdb) b bub
|
GDB alters your input line to the following, and rings a bell:
|
GDB alters your input line to the following, and rings a bell:
|
(gdb) b 'bubble(
|
(gdb) b 'bubble(
|
|
|
In general, GDB can tell that a quote is needed (and inserts it) if you
|
In general, GDB can tell that a quote is needed (and inserts it) if you
|
have not yet started typing the argument list when you ask for
|
have not yet started typing the argument list when you ask for
|
completion on an overloaded symbol.
|
completion on an overloaded symbol.
|
|
|
For more information about overloaded functions, see *Note C++
|
For more information about overloaded functions, see *Note C++
|
expressions: C plus plus expressions. You can use the command `set
|
expressions: C plus plus expressions. You can use the command `set
|
overload-resolution off' to disable overload resolution; see *Note GDB
|
overload-resolution off' to disable overload resolution; see *Note GDB
|
features for C++: Debugging C plus plus.
|
features for C++: Debugging C plus plus.
|
|
|
|
|
File: gdb.info, Node: Help, Prev: Completion, Up: Commands
|
File: gdb.info, Node: Help, Prev: Completion, Up: Commands
|
|
|
Getting help
|
Getting help
|
============
|
============
|
|
|
You can always ask GDB itself for information on its commands, using
|
You can always ask GDB itself for information on its commands, using
|
the command `help'.
|
the command `help'.
|
|
|
`help'
|
`help'
|
`h'
|
`h'
|
You can use `help' (abbreviated `h') with no arguments to display
|
You can use `help' (abbreviated `h') with no arguments to display
|
a short list of named classes of commands:
|
a short list of named classes of commands:
|
|
|
(gdb) help
|
(gdb) help
|
List of classes of commands:
|
List of classes of commands:
|
|
|
aliases -- Aliases of other commands
|
aliases -- Aliases of other commands
|
breakpoints -- Making program stop at certain points
|
breakpoints -- Making program stop at certain points
|
data -- Examining data
|
data -- Examining data
|
files -- Specifying and examining files
|
files -- Specifying and examining files
|
internals -- Maintenance commands
|
internals -- Maintenance commands
|
obscure -- Obscure features
|
obscure -- Obscure features
|
running -- Running the program
|
running -- Running the program
|
stack -- Examining the stack
|
stack -- Examining the stack
|
status -- Status inquiries
|
status -- Status inquiries
|
support -- Support facilities
|
support -- Support facilities
|
tracepoints -- Tracing of program execution without
|
tracepoints -- Tracing of program execution without
|
|
|
stopping the program
|
stopping the program
|
user-defined -- User-defined commands
|
user-defined -- User-defined commands
|
|
|
Type "help" followed by a class name for a list of
|
Type "help" followed by a class name for a list of
|
commands in that class.
|
commands in that class.
|
Type "help" followed by command name for full
|
Type "help" followed by command name for full
|
documentation.
|
documentation.
|
Command name abbreviations are allowed if unambiguous.
|
Command name abbreviations are allowed if unambiguous.
|
(gdb)
|
(gdb)
|
|
|
`help CLASS'
|
`help CLASS'
|
Using one of the general help classes as an argument, you can get a
|
Using one of the general help classes as an argument, you can get a
|
list of the individual commands in that class. For example, here
|
list of the individual commands in that class. For example, here
|
is the help display for the class `status':
|
is the help display for the class `status':
|
|
|
(gdb) help status
|
(gdb) help status
|
Status inquiries.
|
Status inquiries.
|
|
|
List of commands:
|
List of commands:
|
|
|
info -- Generic command for showing things
|
info -- Generic command for showing things
|
about the program being debugged
|
about the program being debugged
|
show -- Generic command for showing things
|
show -- Generic command for showing things
|
about the debugger
|
about the debugger
|
|
|
Type "help" followed by command name for full
|
Type "help" followed by command name for full
|
documentation.
|
documentation.
|
Command name abbreviations are allowed if unambiguous.
|
Command name abbreviations are allowed if unambiguous.
|
(gdb)
|
(gdb)
|
|
|
`help COMMAND'
|
`help COMMAND'
|
With a command name as `help' argument, GDB displays a short
|
With a command name as `help' argument, GDB displays a short
|
paragraph on how to use that command.
|
paragraph on how to use that command.
|
|
|
`apropos ARGS'
|
`apropos ARGS'
|
The `apropos ARGS' command searches through all of the GDB
|
The `apropos ARGS' command searches through all of the GDB
|
commands, and their documentation, for the regular expression
|
commands, and their documentation, for the regular expression
|
specified in ARGS. It prints out all matches found. For example:
|
specified in ARGS. It prints out all matches found. For example:
|
|
|
apropos reload
|
apropos reload
|
|
|
results in:
|
results in:
|
|
|
set symbol-reloading -- Set dynamic symbol table reloading
|
set symbol-reloading -- Set dynamic symbol table reloading
|
multiple times in one run
|
multiple times in one run
|
show symbol-reloading -- Show dynamic symbol table reloading
|
show symbol-reloading -- Show dynamic symbol table reloading
|
multiple times in one run
|
multiple times in one run
|
|
|
`complete ARGS'
|
`complete ARGS'
|
The `complete ARGS' command lists all the possible completions for
|
The `complete ARGS' command lists all the possible completions for
|
the beginning of a command. Use ARGS to specify the beginning of
|
the beginning of a command. Use ARGS to specify the beginning of
|
the command you want completed. For example:
|
the command you want completed. For example:
|
|
|
complete i
|
complete i
|
|
|
results in:
|
results in:
|
|
|
if
|
if
|
ignore
|
ignore
|
info
|
info
|
inspect
|
inspect
|
|
|
This is intended for use by GNU Emacs.
|
This is intended for use by GNU Emacs.
|
|
|
In addition to `help', you can use the GDB commands `info' and
|
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
|
`show' to inquire about the state of your program, or the state of GDB
|
itself. Each command supports many topics of inquiry; this manual
|
itself. Each command supports many topics of inquiry; this manual
|
introduces each of them in the appropriate context. The listings under
|
introduces each of them in the appropriate context. The listings under
|
`info' and under `show' in the Index point to all the sub-commands.
|
`info' and under `show' in the Index point to all the sub-commands.
|
*Note Index::.
|
*Note Index::.
|
|
|
`info'
|
`info'
|
This command (abbreviated `i') is for describing the state of your
|
This command (abbreviated `i') is for describing the state of your
|
program. For example, you can list the arguments given to your
|
program. For example, you can list the arguments given to your
|
program with `info args', list the registers currently in use with
|
program with `info args', list the registers currently in use with
|
`info registers', or list the breakpoints you have set with `info
|
`info registers', or list the breakpoints you have set with `info
|
breakpoints'. You can get a complete list of the `info'
|
breakpoints'. You can get a complete list of the `info'
|
sub-commands with `help info'.
|
sub-commands with `help info'.
|
|
|
`set'
|
`set'
|
You can assign the result of an expression to an environment
|
You can assign the result of an expression to an environment
|
variable with `set'. For example, you can set the GDB prompt to a
|
variable with `set'. For example, you can set the GDB prompt to a
|
$-sign with `set prompt $'.
|
$-sign with `set prompt $'.
|
|
|
`show'
|
`show'
|
In contrast to `info', `show' is for describing the state of GDB
|
In contrast to `info', `show' is for describing the state of GDB
|
itself. You can change most of the things you can `show', by
|
itself. You can change most of the things you can `show', by
|
using the related command `set'; for example, you can control what
|
using the related command `set'; for example, you can control what
|
number system is used for displays with `set radix', or simply
|
number system is used for displays with `set radix', or simply
|
inquire which is currently in use with `show radix'.
|
inquire which is currently in use with `show radix'.
|
|
|
To display all the settable parameters and their current values,
|
To display all the settable parameters and their current values,
|
you can use `show' with no arguments; you may also use `info set'.
|
you can use `show' with no arguments; you may also use `info set'.
|
Both commands produce the same display.
|
Both commands produce the same display.
|
|
|
Here are three miscellaneous `show' subcommands, all of which are
|
Here are three miscellaneous `show' subcommands, all of which are
|
exceptional in lacking corresponding `set' commands:
|
exceptional in lacking corresponding `set' commands:
|
|
|
`show version'
|
`show version'
|
Show what version of GDB is running. You should include this
|
Show what version of GDB is running. You should include this
|
information in GDB bug-reports. If multiple versions of GDB are
|
information in GDB bug-reports. If multiple versions of GDB are
|
in use at your site, you may need to determine which version of
|
in use at your site, you may need to determine which version of
|
GDB you are running; as GDB evolves, new commands are introduced,
|
GDB you are running; as GDB evolves, new commands are introduced,
|
and old ones may wither away. Also, many system vendors ship
|
and old ones may wither away. Also, many system vendors ship
|
variant versions of GDB, and there are variant versions of GDB in
|
variant versions of GDB, and there are variant versions of GDB in
|
GNU/Linux distributions as well. The version number is the same
|
GNU/Linux distributions as well. The version number is the same
|
as the one announced when you start GDB.
|
as the one announced when you start GDB.
|
|
|
`show copying'
|
`show copying'
|
Display information about permission for copying GDB.
|
Display information about permission for copying GDB.
|
|
|
`show warranty'
|
`show warranty'
|
Display the GNU "NO WARRANTY" statement, or a warranty, if your
|
Display the GNU "NO WARRANTY" statement, or a warranty, if your
|
version of GDB comes with one.
|
version of GDB comes with one.
|
|
|
|
|
File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top
|
File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top
|
|
|
Running Programs Under GDB
|
Running Programs Under GDB
|
**************************
|
**************************
|
|
|
When you run a program under GDB, you must first generate debugging
|
When you run a program under GDB, you must first generate debugging
|
information when you compile it.
|
information when you compile it.
|
|
|
You may start GDB with its arguments, if any, in an environment of
|
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
|
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
|
program's input and output, debug an already running process, or kill a
|
child process.
|
child process.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Compilation:: Compiling for debugging
|
* Compilation:: Compiling for debugging
|
* Starting:: Starting your program
|
* Starting:: Starting your program
|
* Arguments:: Your program's arguments
|
* Arguments:: Your program's arguments
|
* Environment:: Your program's environment
|
* Environment:: Your program's environment
|
|
|
* Working Directory:: Your program's working directory
|
* Working Directory:: Your program's working directory
|
* Input/Output:: Your program's input and output
|
* Input/Output:: Your program's input and output
|
* Attach:: Debugging an already-running process
|
* Attach:: Debugging an already-running process
|
* Kill Process:: Killing the child process
|
* Kill Process:: Killing the child process
|
|
|
* Threads:: Debugging programs with multiple threads
|
* Threads:: Debugging programs with multiple threads
|
* Processes:: Debugging programs with multiple processes
|
* Processes:: Debugging programs with multiple processes
|
|
|
|
|
File: gdb.info, Node: Compilation, Next: Starting, Up: Running
|
File: gdb.info, Node: Compilation, Next: Starting, Up: Running
|
|
|
Compiling for debugging
|
Compiling for debugging
|
=======================
|
=======================
|
|
|
In order to debug a program effectively, you need to generate
|
In order to debug a program effectively, you need to generate
|
debugging information when you compile it. This debugging information
|
debugging information when you compile it. This debugging information
|
is stored in the object file; it describes the data type of each
|
is stored in the object file; it describes the data type of each
|
variable or function and the correspondence between source line numbers
|
variable or function and the correspondence between source line numbers
|
and addresses in the executable code.
|
and addresses in the executable code.
|
|
|
To request debugging information, specify the `-g' option when you
|
To request debugging information, specify the `-g' option when you
|
run the compiler.
|
run the compiler.
|
|
|
Many C compilers are unable to handle the `-g' and `-O' options
|
Many C compilers are unable to handle the `-g' and `-O' options
|
together. Using those compilers, you cannot generate optimized
|
together. Using those compilers, you cannot generate optimized
|
executables containing debugging information.
|
executables containing debugging information.
|
|
|
GCC, the GNU C compiler, supports `-g' with or without `-O', making
|
GCC, the GNU C compiler, supports `-g' with or without `-O', making
|
it possible to debug optimized code. We recommend that you _always_
|
it possible to debug optimized code. We recommend that you _always_
|
use `-g' whenever you compile a program. You may think your program is
|
use `-g' whenever you compile a program. You may think your program is
|
correct, but there is no sense in pushing your luck.
|
correct, but there is no sense in pushing your luck.
|
|
|
When you debug a program compiled with `-g -O', remember that the
|
When you debug a program compiled with `-g -O', remember that the
|
optimizer is rearranging your code; the debugger shows you what is
|
optimizer is rearranging your code; the debugger shows you what is
|
really there. Do not be too surprised when the execution path does not
|
really there. Do not be too surprised when the execution path does not
|
exactly match your source file! An extreme example: if you define a
|
exactly match your source file! An extreme example: if you define a
|
variable, but never use it, GDB never sees that variable--because the
|
variable, but never use it, GDB never sees that variable--because the
|
compiler optimizes it out of existence.
|
compiler optimizes it out of existence.
|
|
|
Some things do not work as well with `-g -O' as with just `-g',
|
Some things do not work as well with `-g -O' as with just `-g',
|
particularly on machines with instruction scheduling. If in doubt,
|
particularly on machines with instruction scheduling. If in doubt,
|
recompile with `-g' alone, and if this fixes the problem, please report
|
recompile with `-g' alone, and if this fixes the problem, please report
|
it to us as a bug (including a test case!).
|
it to us as a bug (including a test case!).
|
|
|
Older versions of the GNU C compiler permitted a variant option
|
Older versions of the GNU C compiler permitted a variant option
|
`-gg' for debugging information. GDB no longer supports this format;
|
`-gg' for debugging information. GDB no longer supports this format;
|
if your GNU C compiler has this option, do not use it.
|
if your GNU C compiler has this option, do not use it.
|
|
|
|
|
File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running
|
File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running
|
|
|
Starting your program
|
Starting your program
|
=====================
|
=====================
|
|
|
`run'
|
`run'
|
`r'
|
`r'
|
Use the `run' command to start your program under GDB. You must
|
Use the `run' command to start your program under GDB. You must
|
first specify the program name (except on VxWorks) with an
|
first specify the program name (except on VxWorks) with an
|
argument to GDB (*note Getting In and Out of GDB: Invocation.), or
|
argument to GDB (*note Getting In and Out of GDB: Invocation.), or
|
by using the `file' or `exec-file' command (*note Commands to
|
by using the `file' or `exec-file' command (*note Commands to
|
specify files: Files.).
|
specify files: Files.).
|
|
|
If you are running your program in an execution environment that
|
If you are running your program in an execution environment that
|
supports processes, `run' creates an inferior process and makes that
|
supports processes, `run' creates an inferior process and makes that
|
process run your program. (In environments without processes, `run'
|
process run your program. (In environments without processes, `run'
|
jumps to the start of your program.)
|
jumps to the start of your program.)
|
|
|
The execution of a program is affected by certain information it
|
The execution of a program is affected by certain information it
|
receives from its superior. GDB provides ways to specify this
|
receives from its superior. GDB provides ways to specify this
|
information, which you must do _before_ starting your program. (You
|
information, which you must do _before_ starting your program. (You
|
can change it after starting your program, but such changes only affect
|
can change it after starting your program, but such changes only affect
|
your program the next time you start it.) This information may be
|
your program the next time you start it.) This information may be
|
divided into four categories:
|
divided into four categories:
|
|
|
The _arguments._
|
The _arguments._
|
Specify the arguments to give your program as the arguments of the
|
Specify the arguments to give your program as the arguments of the
|
`run' command. If a shell is available on your target, the shell
|
`run' command. If a shell is available on your target, the shell
|
is used to pass the arguments, so that you may use normal
|
is used to pass the arguments, so that you may use normal
|
conventions (such as wildcard expansion or variable substitution)
|
conventions (such as wildcard expansion or variable substitution)
|
in describing the arguments. In Unix systems, you can control
|
in describing the arguments. In Unix systems, you can control
|
which shell is used with the `SHELL' environment variable. *Note
|
which shell is used with the `SHELL' environment variable. *Note
|
Your program's arguments: Arguments.
|
Your program's arguments: Arguments.
|
|
|
The _environment._
|
The _environment._
|
Your program normally inherits its environment from GDB, but you
|
Your program normally inherits its environment from GDB, but you
|
can use the GDB commands `set environment' and `unset environment'
|
can use the GDB commands `set environment' and `unset environment'
|
to change parts of the environment that affect your program.
|
to change parts of the environment that affect your program.
|
*Note Your program's environment: Environment.
|
*Note Your program's environment: Environment.
|
|
|
The _working directory._
|
The _working directory._
|
Your program inherits its working directory from GDB. You can set
|
Your program inherits its working directory from GDB. You can set
|
the GDB working directory with the `cd' command in GDB. *Note
|
the GDB working directory with the `cd' command in GDB. *Note
|
Your program's working directory: Working Directory.
|
Your program's working directory: Working Directory.
|
|
|
The _standard input and output._
|
The _standard input and output._
|
Your program normally uses the same device for standard input and
|
Your program normally uses the same device for standard input and
|
standard output as GDB is using. You can redirect input and output
|
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
|
in the `run' command line, or you can use the `tty' command to set
|
a different device for your program. *Note Your program's input
|
a different device for your program. *Note Your program's input
|
and output: Input/Output.
|
and output: Input/Output.
|
|
|
_Warning:_ While input and output redirection work, you cannot use
|
_Warning:_ While input and output redirection work, you cannot use
|
pipes to pass the output of the program you are debugging to
|
pipes to pass the output of the program you are debugging to
|
another program; if you attempt this, GDB is likely to wind up
|
another program; if you attempt this, GDB is likely to wind up
|
debugging the wrong program.
|
debugging the wrong program.
|
|
|
When you issue the `run' command, your program begins to execute
|
When you issue the `run' command, your program begins to execute
|
immediately. *Note Stopping and continuing: Stopping, for discussion
|
immediately. *Note Stopping and continuing: Stopping, for discussion
|
of how to arrange for your program to stop. Once your program has
|
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
|
stopped, you may call functions in your program, using the `print' or
|
`call' commands. *Note Examining Data: Data.
|
`call' commands. *Note Examining Data: Data.
|
|
|
If the modification time of your symbol file has changed since the
|
If the modification time of your symbol file has changed since the
|
last time GDB read its symbols, GDB discards its symbol table, and
|
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
|
reads it again. When it does this, GDB tries to retain your current
|
breakpoints.
|
breakpoints.
|
|
|
|
|
File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running
|
File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running
|
|
|
Your program's arguments
|
Your program's arguments
|
========================
|
========================
|
|
|
The arguments to your program can be specified by the arguments of
|
The arguments to your program can be specified by the arguments of
|
the `run' command. They are passed to a shell, which expands wildcard
|
the `run' command. They are passed to a shell, which expands wildcard
|
characters and performs redirection of I/O, and thence to your program.
|
characters and performs redirection of I/O, and thence to your program.
|
Your `SHELL' environment variable (if it exists) specifies what shell
|
Your `SHELL' environment variable (if it exists) specifies what shell
|
GDB uses. If you do not define `SHELL', GDB uses the default shell
|
GDB uses. If you do not define `SHELL', GDB uses the default shell
|
(`/bin/sh' on Unix).
|
(`/bin/sh' on Unix).
|
|
|
On non-Unix systems, the program is usually invoked directly by GDB,
|
On non-Unix systems, the program is usually invoked directly by GDB,
|
which emulates I/O redirection via the appropriate system calls, and
|
which emulates I/O redirection via the appropriate system calls, and
|
the wildcard characters are expanded by the startup code of the
|
the wildcard characters are expanded by the startup code of the
|
program, not by the shell.
|
program, not by the shell.
|
|
|
`run' with no arguments uses the same arguments used by the previous
|
`run' with no arguments uses the same arguments used by the previous
|
`run', or those set by the `set args' command.
|
`run', or those set by the `set args' command.
|
|
|
`set args'
|
`set args'
|
Specify the arguments to be used the next time your program is
|
Specify the arguments to be used the next time your program is
|
run. If `set args' has no arguments, `run' executes your program
|
run. If `set args' has no arguments, `run' executes your program
|
with no arguments. Once you have run your program with arguments,
|
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
|
using `set args' before the next `run' is the only way to run it
|
again without arguments.
|
again without arguments.
|
|
|
`show args'
|
`show args'
|
Show the arguments to give your program when it is started.
|
Show the arguments to give your program when it is started.
|
|
|
|
|
