This is gdb.info, produced by makeinfo version 4.13 from ./gdb.texinfo.
|
This is gdb.info, produced by makeinfo version 4.13 from ./gdb.texinfo.
|
|
|
INFO-DIR-SECTION Software development
|
INFO-DIR-SECTION Software development
|
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
|
|
|
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
2010 Free Software Foundation, Inc.
|
2010 Free Software Foundation, Inc.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being "Free Software" and "Free Software Needs Free
|
Invariant Sections being "Free Software" and "Free Software Needs Free
|
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
with the Back-Cover Texts as in (a) below.
|
with the Back-Cover Texts as in (a) below.
|
|
|
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
developing GNU and promoting software freedom."
|
developing GNU and promoting software freedom."
|
|
|
This file documents the GNU debugger GDB.
|
This file documents the GNU debugger GDB.
|
|
|
This is the Ninth Edition, of `Debugging with GDB: the GNU
|
This is the Ninth Edition, of `Debugging with GDB: the GNU
|
Source-Level Debugger' for GDB (GDB) Version 7.2-or32-1.0rc3.
|
Source-Level Debugger' for GDB (GDB) Version 7.2-or32-1.0rc3.
|
|
|
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
2010 Free Software Foundation, Inc.
|
2010 Free Software Foundation, Inc.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being "Free Software" and "Free Software Needs Free
|
Invariant Sections being "Free Software" and "Free Software Needs Free
|
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
with the Back-Cover Texts as in (a) below.
|
with the Back-Cover Texts as in (a) below.
|
|
|
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
developing GNU and promoting software freedom."
|
developing GNU and promoting software freedom."
|
|
|
|
|
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 Ninth Edition, for GDB (GDB) Version 7.2-or32-1.0rc3.
|
This is the Ninth Edition, for GDB (GDB) Version 7.2-or32-1.0rc3.
|
|
|
Copyright (C) 1988-2010 Free Software Foundation, Inc.
|
Copyright (C) 1988-2010 Free Software Foundation, Inc.
|
|
|
This edition of the GDB manual is dedicated to the memory of Fred
|
This edition of the GDB manual is dedicated to the memory of Fred
|
Fish. Fred was a long-standing contributor to GDB and to Free software
|
Fish. Fred was a long-standing contributor to GDB and to Free software
|
in general. We will miss him.
|
in general. We will miss him.
|
|
|
* 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
|
* Reverse Execution:: Running programs backward
|
* Reverse Execution:: Running programs backward
|
* Process Record and Replay:: Recording inferior's execution and replaying it
|
* Process Record and Replay:: Recording inferior's execution and replaying it
|
* Stack:: Examining the stack
|
* Stack:: Examining the stack
|
* Source:: Examining source files
|
* Source:: Examining source files
|
* Data:: Examining data
|
* Data:: Examining data
|
* Optimized Code:: Debugging optimized code
|
* Optimized Code:: Debugging optimized code
|
* Macros:: Preprocessor Macros
|
* Macros:: Preprocessor Macros
|
* Tracepoints:: Debugging remote targets non-intrusively
|
* Tracepoints:: Debugging remote targets non-intrusively
|
* Overlays:: Debugging programs that use overlays
|
* Overlays:: Debugging programs that use overlays
|
|
|
* 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
|
* Remote Debugging:: Debugging remote programs
|
* Remote Debugging:: Debugging remote programs
|
* Configurations:: Configuration-specific information
|
* Configurations:: Configuration-specific information
|
* Controlling GDB:: Controlling GDB
|
* Controlling GDB:: Controlling GDB
|
* Extending GDB:: Extending GDB
|
* Extending GDB:: Extending GDB
|
* Interpreters:: Command Interpreters
|
* Interpreters:: Command Interpreters
|
* TUI:: GDB Text User Interface
|
* TUI:: GDB Text User Interface
|
* Emacs:: Using GDB under GNU Emacs
|
* Emacs:: Using GDB under GNU Emacs
|
* GDB/MI:: GDB's Machine Interface.
|
* GDB/MI:: GDB's Machine Interface.
|
* Annotations:: GDB's annotation interface.
|
* Annotations:: GDB's annotation interface.
|
* JIT Interface:: Using the JIT debugging interface.
|
* JIT Interface:: Using the JIT debugging interface.
|
|
|
* GDB Bugs:: Reporting bugs in GDB
|
* GDB Bugs:: Reporting bugs in GDB
|
|
|
* Command Line Editing:: Command Line Editing
|
* Command Line Editing:: Command Line Editing
|
* Using History Interactively:: Using History Interactively
|
* Using History Interactively:: Using History Interactively
|
* Formatting Documentation:: How to format and print GDB documentation
|
* Formatting Documentation:: How to format and print GDB documentation
|
* Installing GDB:: Installing GDB
|
* Installing GDB:: Installing GDB
|
* Maintenance Commands:: Maintenance Commands
|
* Maintenance Commands:: Maintenance Commands
|
* Remote Protocol:: GDB Remote Serial Protocol
|
* Remote Protocol:: GDB Remote Serial Protocol
|
* Agent Expressions:: The GDB Agent Expression Mechanism
|
* Agent Expressions:: The GDB Agent Expression Mechanism
|
* Target Descriptions:: How targets can describe themselves to
|
* Target Descriptions:: How targets can describe themselves to
|
GDB
|
GDB
|
* Operating System Information:: Getting additional information from
|
* Operating System Information:: Getting additional information from
|
the operating system
|
the operating system
|
* Trace File Format:: GDB trace file format
|
* Trace File Format:: GDB trace file format
|
* Copying:: GNU General Public License says
|
* Copying:: GNU General Public License says
|
how you can copy and share GDB
|
how you can copy and share GDB
|
* GNU Free Documentation License:: The license for this documentation
|
* GNU Free Documentation License:: The license for this documentation
|
* 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: Supported Languages. For
|
information, see *note Supported Languages: Supported Languages. For
|
more information, see *note C and C++: C.
|
more information, see *note C and C++: C.
|
|
|
Support for D is partial. For information on D, see *note D: D.
|
Support for D is partial. For information on D, see *note D: D.
|
|
|
Support for Modula-2 is partial. For information on Modula-2, see
|
Support for Modula-2 is partial. For information on Modula-2, see
|
*note Modula-2: Modula-2.
|
*note Modula-2: Modula-2.
|
|
|
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.
|
|
|
GDB can be used to debug programs written in Objective-C, using
|
GDB can be used to debug programs written in Objective-C, using
|
either the Apple/NeXT or the GNU Objective-C runtime.
|
either the Apple/NeXT or the GNU Objective-C runtime.
|
|
|
* 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.
|
|
|
Free Software Needs Free Documentation
|
Free Software Needs Free Documentation
|
======================================
|
======================================
|
|
|
The biggest deficiency in the free software community today is not in
|
The biggest deficiency in the free software community today is not in
|
the software--it is the lack of good free documentation that we can
|
the software--it is the lack of good free documentation that we can
|
include with the free software. Many of our most important programs do
|
include with the free software. Many of our most important programs do
|
not come with free reference manuals and free introductory texts.
|
not come with free reference manuals and free introductory texts.
|
Documentation is an essential part of any software package; when an
|
Documentation is an essential part of any software package; when an
|
important free software package does not come with a free manual and a
|
important free software package does not come with a free manual and a
|
free tutorial, that is a major gap. We have many such gaps today.
|
free tutorial, that is a major gap. We have many such gaps today.
|
|
|
Consider Perl, for instance. The tutorial manuals that people
|
Consider Perl, for instance. The tutorial manuals that people
|
normally use are non-free. How did this come about? Because the
|
normally use are non-free. How did this come about? Because the
|
authors of those manuals published them with restrictive terms--no
|
authors of those manuals published them with restrictive terms--no
|
copying, no modification, source files not available--which exclude
|
copying, no modification, source files not available--which exclude
|
them from the free software world.
|
them from the free software world.
|
|
|
That wasn't the first time this sort of thing happened, and it was
|
That wasn't the first time this sort of thing happened, and it was
|
far from the last. Many times we have heard a GNU user eagerly
|
far from the last. Many times we have heard a GNU user eagerly
|
describe a manual that he is writing, his intended contribution to the
|
describe a manual that he is writing, his intended contribution to the
|
community, only to learn that he had ruined everything by signing a
|
community, only to learn that he had ruined everything by signing a
|
publication contract to make it non-free.
|
publication contract to make it non-free.
|
|
|
Free documentation, like free software, is a matter of freedom, not
|
Free documentation, like free software, is a matter of freedom, not
|
price. The problem with the non-free manual is not that publishers
|
price. The problem with the non-free manual is not that publishers
|
charge a price for printed copies--that in itself is fine. (The Free
|
charge a price for printed copies--that in itself is fine. (The Free
|
Software Foundation sells printed copies of manuals, too.) The problem
|
Software Foundation sells printed copies of manuals, too.) The problem
|
is the restrictions on the use of the manual. Free manuals are
|
is the restrictions on the use of the manual. Free manuals are
|
available in source code form, and give you permission to copy and
|
available in source code form, and give you permission to copy and
|
modify. Non-free manuals do not allow this.
|
modify. Non-free manuals do not allow this.
|
|
|
The criteria of freedom for a free manual are roughly the same as for
|
The criteria of freedom for a free manual are roughly the same as for
|
free software. Redistribution (including the normal kinds of
|
free software. Redistribution (including the normal kinds of
|
commercial redistribution) must be permitted, so that the manual can
|
commercial redistribution) must be permitted, so that the manual can
|
accompany every copy of the program, both on-line and on paper.
|
accompany every copy of the program, both on-line and on paper.
|
|
|
Permission for modification of the technical content is crucial too.
|
Permission for modification of the technical content is crucial too.
|
When people modify the software, adding or changing features, if they
|
When people modify the software, adding or changing features, if they
|
are conscientious they will change the manual too--so they can provide
|
are conscientious they will change the manual too--so they can provide
|
accurate and clear documentation for the modified program. A manual
|
accurate and clear documentation for the modified program. A manual
|
that leaves you no choice but to write a new manual to document a
|
that leaves you no choice but to write a new manual to document a
|
changed version of the program is not really available to our community.
|
changed version of the program is not really available to our community.
|
|
|
Some kinds of limits on the way modification is handled are
|
Some kinds of limits on the way modification is handled are
|
acceptable. For example, requirements to preserve the original
|
acceptable. For example, requirements to preserve the original
|
author's copyright notice, the distribution terms, or the list of
|
author's copyright notice, the distribution terms, or the list of
|
authors, are ok. It is also no problem to require modified versions to
|
authors, are ok. It is also no problem to require modified versions to
|
include notice that they were modified. Even entire sections that may
|
include notice that they were modified. Even entire sections that may
|
not be deleted or changed are acceptable, as long as they deal with
|
not be deleted or changed are acceptable, as long as they deal with
|
nontechnical topics (like this one). These kinds of restrictions are
|
nontechnical topics (like this one). These kinds of restrictions are
|
acceptable because they don't obstruct the community's normal use of
|
acceptable because they don't obstruct the community's normal use of
|
the manual.
|
the manual.
|
|
|
However, it must be possible to modify all the _technical_ content
|
However, it must be possible to modify all the _technical_ content
|
of the manual, and then distribute the result in all the usual media,
|
of the manual, and then distribute the result in all the usual media,
|
through all the usual channels. Otherwise, the restrictions obstruct
|
through all the usual channels. Otherwise, the restrictions obstruct
|
the use of the manual, it is not free, and we need another manual to
|
the use of the manual, it is not free, and we need another manual to
|
replace it.
|
replace it.
|
|
|
Please spread the word about this issue. Our community continues to
|
Please spread the word about this issue. Our community continues to
|
lose manuals to proprietary publishing. If we spread the word that
|
lose manuals to proprietary publishing. If we spread the word that
|
free software needs free reference manuals and free tutorials, perhaps
|
free software needs free reference manuals and free tutorials, perhaps
|
the next person who wants to contribute by writing documentation will
|
the next person who wants to contribute by writing documentation will
|
realize, before it is too late, that only free manuals contribute to
|
realize, before it is too late, that only free manuals contribute to
|
the free software community.
|
the free software community.
|
|
|
If you are writing documentation, please insist on publishing it
|
If you are writing documentation, please insist on publishing it
|
under the GNU Free Documentation License or another free documentation
|
under the GNU Free Documentation License or another free documentation
|
license. Remember that this decision requires your approval--you don't
|
license. Remember that this decision requires your approval--you don't
|
have to let the publisher decide. Some commercial publishers will use
|
have to let the publisher decide. Some commercial publishers will use
|
a free license if you insist, but they will not propose the option; it
|
a free license if you insist, but they will not propose the option; it
|
is up to you to raise the issue and say firmly that this is what you
|
is up to you to raise the issue and say firmly that this is what you
|
want. If the publisher you are dealing with refuses, please try other
|
want. If the publisher you are dealing with refuses, please try other
|
publishers. If you're not sure whether a proposed license is free,
|
publishers. If you're not sure whether a proposed license is free,
|
write to .
|
write to .
|
|
|
You can encourage commercial publishers to sell more free, copylefted
|
You can encourage commercial publishers to sell more free, copylefted
|
manuals and tutorials by buying them, and particularly by buying copies
|
manuals and tutorials by buying them, and particularly by buying copies
|
from the publishers that paid for their writing or for major
|
from the publishers that paid for their writing or for major
|
improvements. Meanwhile, try to avoid buying non-free documentation at
|
improvements. Meanwhile, try to avoid buying non-free documentation at
|
all. Check the distribution terms of a manual before you buy it, and
|
all. Check the distribution terms of a manual before you buy it, and
|
insist that whoever seeks your business must respect your freedom.
|
insist that whoever seeks your business must respect your freedom.
|
Check the history of the book, and try to reward the publishers that
|
Check the history of the book, and try to reward the publishers that
|
have paid or pay the authors to work on it.
|
have paid or pay the authors to work on it.
|
|
|
The Free Software Foundation maintains a list of free documentation
|
The Free Software Foundation maintains a list of free documentation
|
published by other publishers, at
|
published by other publishers, at
|
`http://www.fsf.org/doc/other-free-books.html'.
|
`http://www.fsf.org/doc/other-free-books.html'.
|
|
|
|
|
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 GNU
|
Richard Stallman was the original author of GDB, and of many other GNU
|
programs. Many others have contributed to its development. This
|
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 (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim
|
Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim
|
Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs
|
Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs
|
(release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10,
|
(release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10,
|
and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5,
|
and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5,
|
and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim
|
and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim
|
Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2,
|
Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2,
|
3.1, and 3.0).
|
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 and Daniel
|
with significant additional contributions from Per Bothner and Daniel
|
Berlin. James Clark wrote the GNU C++ demangler. Early work on C++
|
Berlin. James Clark wrote the GNU C++ demangler. Early work on C++
|
was by Peter TerMaat (who also did much general update work leading to
|
was by Peter TerMaat (who also did much general update work leading to
|
release 3.0).
|
release 3.0).
|
|
|
GDB uses the BFD subroutine library to examine multiple object-file
|
GDB uses the BFD subroutine library to examine multiple object-file
|
formats; BFD was a joint project of David V. Henkel-Wallace, Rich
|
formats; BFD was a joint project of David V. Henkel-Wallace, Rich
|
Pixley, Steve Chamberlain, and John Gilmore.
|
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. Marko Mlinar contributed OpenRISC 1000 support.
|
Symmetry support. Marko Mlinar contributed OpenRISC 1000 support.
|
|
|
Andreas Schwab contributed M68K GNU/Linux support.
|
Andreas Schwab contributed M68K GNU/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 (now Renesas America), Ltd. sponsored the support for
|
Hitachi America (now Renesas America), Ltd. sponsored the support for
|
H8/300, H8/500, and Super-H processors.
|
H8/300, H8/500, and 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 (now Renesas) sponsored the support for D10V, D30V, and
|
Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and
|
M32R/D processors.
|
M32R/D 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 Text User Interface (nee Terminal User Interface):
|
compiler, and the Text User Interface (nee Terminal User Interface):
|
Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
|
Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
|
Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
|
Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
|
provided HP-specific information in this manual.
|
provided HP-specific information in this manual.
|
|
|
DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert
|
DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert
|
Hoehne made significant contributions to the DJGPP port.
|
Hoehne made significant contributions to the DJGPP port.
|
|
|
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.
|
|
|
Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
|
Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
|
Cygnus Solutions, implemented the original GDB/MI interface.
|
Cygnus Solutions, implemented the original GDB/MI interface.
|
|
|
Jim Blandy added support for preprocessor macros, while working for
|
Jim Blandy added support for preprocessor macros, while working for
|
Red Hat.
|
Red Hat.
|
|
|
Andrew Cagney designed GDB's architecture vector. Many people
|
Andrew Cagney designed GDB's architecture vector. Many people
|
including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek,
|
including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek,
|
Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto,
|
Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto,
|
Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna
|
Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna
|
Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration
|
Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration
|
of old architectures to this new framework.
|
of old architectures to this new framework.
|
|
|
Andrew Cagney completely re-designed and re-implemented GDB's
|
Andrew Cagney completely re-designed and re-implemented GDB's
|
unwinder framework, this consisting of a fresh new design featuring
|
unwinder framework, this consisting of a fresh new design featuring
|
frame IDs, independent frame sniffers, and the sentinel frame. Mark
|
frame IDs, independent frame sniffers, and the sentinel frame. Mark
|
Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind
|
Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind
|
unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad
|
unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad
|
unwinders. The architecture-specific changes, each involving a
|
unwinders. The architecture-specific changes, each involving a
|
complete rewrite of the architecture's frame code, were carried out by
|
complete rewrite of the architecture's frame code, were carried out by
|
Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
|
Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
|
Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
|
Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
|
Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
|
Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
|
Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
|
Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
|
Weigand.
|
Weigand.
|
|
|
Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
|
Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
|
Tensilica, Inc. contributed support for Xtensa processors. Others who
|
Tensilica, Inc. contributed support for Xtensa processors. Others who
|
have worked on the Xtensa port of GDB in the past include Steve Tjiang,
|
have worked on the Xtensa port of GDB in the past include Steve Tjiang,
|
John Newlin, and Scott Foehner.
|
John Newlin, and Scott Foehner.
|
|
|
Michael Eager and staff of Xilinx, Inc., contributed support for the
|
Michael Eager and staff of Xilinx, Inc., contributed support for the
|
Xilinx MicroBlaze architecture.
|
Xilinx MicroBlaze architecture.
|
|
|
The original port to the OpenRISC 1000 is believed to be due to
|
The original port to the OpenRISC 1000 is believed to be due to
|
Alessandro Forin and Per Bothner. More recent ports have been the work
|
Alessandro Forin and Per Bothner. More recent ports have been the work
|
of Jeremy Bennett.
|
of Jeremy Bennett.
|
|
|
|
|
File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top
|
File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top
|
|
|
1 A Sample GDB Session
|
1 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
|
Ctrl-d
|
Ctrl-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 7.2-or32-1.0rc3, Copyright 1999 Free Software Foundation, Inc...
|
GDB 7.2-or32-1.0rc3, 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:
|
|
|
Ctrl-d
|
Ctrl-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
|
|
|
2 Getting In and Out of GDB
|
2 Getting In and Out of GDB
|
***************************
|
***************************
|
|
|
This chapter discusses how to start GDB, and how to get out of it. The
|
This chapter discusses how to start GDB, and how to get out of it. The
|
essentials are:
|
essentials are:
|
* type `gdb' to start GDB.
|
* type `gdb' to start GDB.
|
|
|
* type `quit' or `Ctrl-d' to exit.
|
* type `quit' or `Ctrl-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
|
* Logging Output:: How to log GDB's output to a file
|
* Logging Output:: How to log GDB's output to a file
|
|
|
|
|
File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation
|
File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation
|
|
|
2.1 Invoking GDB
|
2.1 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 optionally have `gdb' pass any arguments after the
|
You can optionally have `gdb' pass any arguments after the
|
executable file to the inferior using `--args'. This option stops
|
executable file to the inferior using `--args'. This option stops
|
option processing.
|
option processing.
|
gdb --args gcc -O2 -c foo.c
|
gdb --args gcc -O2 -c foo.c
|
This will cause `gdb' to debug `gcc', and to set `gcc''s
|
This will cause `gdb' to debug `gcc', and to set `gcc''s
|
command-line arguments (*note Arguments::) to `-O2 -c foo.c'.
|
command-line arguments (*note Arguments::) to `-O2 -c foo.c'.
|
|
|
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
|
* Startup:: What GDB does during startup
|
* Startup:: What GDB does during startup
|
|
|
|
|
File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB
|
File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB
|
|
|
2.1.1 Choosing Files
|
2.1.1 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' (or
|
the same as if the arguments were specified by the `-se' and `-c' (or
|
`-p') options respectively. (GDB reads the first argument that does
|
`-p') options respectively. (GDB reads the first argument that does
|
not have an associated option flag as equivalent to the `-se' option
|
not have an associated option flag as equivalent to the `-se' option
|
followed by that argument; and the second argument that does not have
|
followed by that argument; and the second argument that does not have
|
an associated option flag, if any, as equivalent to the `-c'/`-p'
|
an associated option flag, if any, as equivalent to the `-c'/`-p'
|
option followed by that argument.) If the second argument begins with
|
option followed by that argument.) If the second argument begins with
|
a decimal digit, GDB will first attempt to attach to it as a process,
|
a decimal digit, GDB will first attempt to attach to it as a process,
|
and if that fails, attempt to open it as a corefile. If you have a
|
and if that fails, attempt to open it as a corefile. If you have a
|
corefile whose name begins with a digit, you can prevent GDB from
|
corefile whose name begins with a digit, you can prevent GDB from
|
treating it as a pid by prefixing it with `./', e.g. `./12345'.
|
treating it as a pid by prefixing it with `./', e.g. `./12345'.
|
|
|
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.
|
|
|
`-pid NUMBER'
|
`-pid NUMBER'
|
`-p NUMBER'
|
`-p NUMBER'
|
Connect to process ID NUMBER, as with the `attach' command.
|
Connect to process ID NUMBER, as with the `attach' command.
|
|
|
`-command FILE'
|
`-command FILE'
|
`-x FILE'
|
`-x FILE'
|
Execute commands from file FILE. The contents of this file is
|
Execute commands from file FILE. The contents of this file is
|
evaluated exactly as the `source' command would. *Note Command
|
evaluated exactly as the `source' command would. *Note Command
|
files: Command Files.
|
files: Command Files.
|
|
|
`-eval-command COMMAND'
|
`-eval-command COMMAND'
|
`-ex COMMAND'
|
`-ex COMMAND'
|
Execute a single GDB command.
|
Execute a single GDB command.
|
|
|
This option may be used multiple times to call multiple commands.
|
This option may be used multiple times to call multiple commands.
|
It may also be interleaved with `-command' as required.
|
It may also be interleaved with `-command' as required.
|
|
|
gdb -ex 'target sim' -ex 'load' \
|
gdb -ex 'target sim' -ex 'load' \
|
-x setbreakpoints -ex 'run' a.out
|
-x setbreakpoints -ex 'run' a.out
|
|
|
`-directory DIRECTORY'
|
`-directory DIRECTORY'
|
`-d DIRECTORY'
|
`-d DIRECTORY'
|
Add DIRECTORY to the path to search for source and script files.
|
Add DIRECTORY to the path to search for source and script files.
|
|
|
`-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.
|
|
|
|
|
|
|
File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB
|
File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB
|
|
|
2.1.2 Choosing Modes
|
2.1.2 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.
|
Do not execute commands found in any initialization files.
|
Normally, GDB executes the commands in these files after all the
|
Normally, GDB executes the commands in these files after all the
|
command options and arguments have been processed. *Note Command
|
command options and arguments have been processed. *Note Command
|
Files: Command Files.
|
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. Batch mode also disables pagination, sets
|
the command files. Batch mode also disables pagination, sets
|
unlimited terminal width and height *note Screen Size::, and acts
|
unlimited terminal width and height *note Screen Size::, and acts
|
as if `set confirm off' were in effect (*note Messages/Warnings::).
|
as if `set confirm off' were in effect (*note Messages/Warnings::).
|
|
|
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.
|
|
|
`-batch-silent'
|
`-batch-silent'
|
Run in batch mode exactly like `-batch', but totally silently. All
|
Run in batch mode exactly like `-batch', but totally silently. All
|
GDB output to `stdout' is prevented (`stderr' is unaffected).
|
GDB output to `stdout' is prevented (`stderr' is unaffected).
|
This is much quieter than `-silent' and would be useless for an
|
This is much quieter than `-silent' and would be useless for an
|
interactive session.
|
interactive session.
|
|
|
This is particularly useful when using targets that give `Loading
|
This is particularly useful when using targets that give `Loading
|
section' messages, for example.
|
section' messages, for example.
|
|
|
Note that targets that give their output via GDB, as opposed to
|
Note that targets that give their output via GDB, as opposed to
|
writing directly to `stdout', will also be made silent.
|
writing directly to `stdout', will also be made silent.
|
|
|
`-return-child-result'
|
`-return-child-result'
|
The return code from GDB will be the return code from the child
|
The return code from GDB will be the return code from the child
|
process (the process being debugged), with the following
|
process (the process being debugged), with the following
|
exceptions:
|
exceptions:
|
|
|
* GDB exits abnormally. E.g., due to an incorrect argument or
|
* GDB exits abnormally. E.g., due to an incorrect argument or
|
an internal error. In this case the exit code is the same as
|
an internal error. In this case the exit code is the same as
|
it would have been without `-return-child-result'.
|
it would have been without `-return-child-result'.
|
|
|
* The user quits with an explicit value. E.g., `quit 1'.
|
* The user quits with an explicit value. E.g., `quit 1'.
|
|
|
* The child process never runs, or is not allowed to terminate,
|
* The child process never runs, or is not allowed to terminate,
|
in which case the exit code will be -1.
|
in which case the exit code will be -1.
|
|
|
This option is useful in conjunction with `-batch' or
|
This option is useful in conjunction with `-batch' or
|
`-batch-silent', when GDB is being used as a remote program loader
|
`-batch-silent', when GDB is being used as a remote program loader
|
or simulator interface.
|
or simulator interface.
|
|
|
`-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::).
|
The annotation LEVEL controls how much information GDB prints
|
The annotation LEVEL controls how much information GDB prints
|
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 3 is the
|
when GDB is run as a subprocess of GNU Emacs, level 3 is the
|
maximum annotation suitable for programs that control GDB, and
|
maximum annotation suitable for programs that control GDB, and
|
level 2 has been deprecated.
|
level 2 has been deprecated.
|
|
|
The annotation mechanism has largely been superseded by GDB/MI
|
The annotation mechanism has largely been superseded by GDB/MI
|
(*note GDB/MI::).
|
(*note GDB/MI::).
|
|
|
`--args'
|
`--args'
|
Change interpretation of command line so that arguments following
|
Change interpretation of command line so that arguments following
|
the executable file are passed as command line arguments to the
|
the executable file are passed as command line arguments to the
|
inferior. This option stops option processing.
|
inferior. This option stops option processing.
|
|
|
`-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.
|
|
|
`-l TIMEOUT'
|
`-l TIMEOUT'
|
Set the timeout (in seconds) of any communication used by GDB for
|
Set the timeout (in seconds) of any communication used by GDB for
|
remote debugging.
|
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.
|
|
|
`-tui'
|
`-tui'
|
Activate the "Text User Interface" when starting. The Text User
|
Activate the "Text User Interface" when starting. The Text User
|
Interface manages several text windows on the terminal, showing
|
Interface manages several text windows on the terminal, showing
|
source, assembly, registers and GDB command outputs (*note GDB
|
source, assembly, registers and GDB command outputs (*note GDB
|
Text User Interface: TUI.). Alternatively, the Text User
|
Text User Interface: TUI.). Alternatively, the Text User
|
Interface can be enabled by invoking the program `gdbtui'. Do not
|
Interface can be enabled by invoking the program `gdbtui'. Do not
|
use this option if you run GDB from Emacs (*note Using GDB under
|
use this option if you run GDB from Emacs (*note Using GDB under
|
GNU Emacs: Emacs.).
|
GNU Emacs: Emacs.).
|
|
|
`-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. *Note Command
|
which communicate with GDB using it as a back end. *Note Command
|
Interpreters: Interpreters.
|
Interpreters: Interpreters.
|
|
|
`--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the
|
`--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the
|
"GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included
|
"GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included
|
since GDB version 6.0. The previous GDB/MI interface, included in
|
since GDB version 6.0. The previous GDB/MI interface, included in
|
GDB version 5.3 and selected with `--interpreter=mi1', is
|
GDB version 5.3 and selected with `--interpreter=mi1', is
|
deprecated. Earlier GDB/MI interfaces are no longer supported.
|
deprecated. Earlier GDB/MI interfaces are no longer supported.
|
|
|
`-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.
|
|
|
|
|
|
|
File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB
|
File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB
|
|
|
2.1.3 What GDB Does During Startup
|
2.1.3 What GDB Does During Startup
|
----------------------------------
|
----------------------------------
|
|
|
Here's the description of what GDB does during session startup:
|
Here's the description of what GDB does during session startup:
|
|
|
1. Sets up the command interpreter as specified by the command line
|
1. Sets up the command interpreter as specified by the command line
|
(*note interpreter: Mode Options.).
|
(*note interpreter: Mode Options.).
|
|
|
2. Reads the system-wide "init file" (if `--with-system-gdbinit' was
|
2. Reads the system-wide "init file" (if `--with-system-gdbinit' was
|
used when building GDB; *note System-wide configuration and
|
used when building GDB; *note System-wide configuration and
|
settings: System-wide configuration.) and executes all the
|
settings: System-wide configuration.) and executes all the
|
commands in that file.
|
commands in that file.
|
|
|
3. Reads the init file (if any) in your home directory(1) and
|
3. Reads the init file (if any) in your home directory(1) and
|
executes all the commands in that file.
|
executes all the commands in that file.
|
|
|
4. Processes command line options and operands.
|
4. Processes command line options and operands.
|
|
|
5. Reads and executes the commands from init file (if any) in the
|
5. Reads and executes the commands from init file (if any) in the
|
current working directory. This is only done if the current
|
current working directory. This is only done if the current
|
directory is different from your home directory. Thus, you can
|
directory is different from your home directory. Thus, you can
|
have more than one init file, one generic in your home directory,
|
have more than one init file, one generic in your home directory,
|
and another, specific to the program you are debugging, in the
|
and another, specific to the program you are debugging, in the
|
directory where you invoke GDB.
|
directory where you invoke GDB.
|
|
|
6. Reads command files specified by the `-x' option. *Note Command
|
6. Reads command files specified by the `-x' option. *Note Command
|
Files::, for more details about GDB command files.
|
Files::, for more details about GDB command files.
|
|
|
7. Reads the command history recorded in the "history file". *Note
|
7. Reads the command history recorded in the "history file". *Note
|
Command History::, for more details about the command history and
|
Command History::, for more details about the command history and
|
the files where GDB records it.
|
the files where GDB records it.
|
|
|
Init files use the same syntax as "command files" (*note Command
|
Init files use the same syntax as "command files" (*note Command
|
Files::) and are processed by GDB in the same way. The init file in
|
Files::) and are processed by GDB in the same way. The init file in
|
your home directory can set options (such as `set complaints') that
|
your home directory can set options (such as `set complaints') that
|
affect subsequent processing of command line options and operands.
|
affect subsequent processing of command line options and operands.
|
Init files are not executed if you use the `-nx' option (*note Choosing
|
Init files are not executed if you use the `-nx' option (*note Choosing
|
Modes: Mode Options.).
|
Modes: Mode Options.).
|
|
|
To display the list of init files loaded by gdb at startup, you can
|
To display the list of init files loaded by gdb at startup, you can
|
use `gdb --help'.
|
use `gdb --help'.
|
|
|
The GDB init files are normally called `.gdbinit'. The DJGPP port
|
The GDB init files are normally called `.gdbinit'. The DJGPP port
|
of GDB uses the name `gdb.ini', due to the limitations of file names
|
of GDB uses the name `gdb.ini', due to the limitations of file names
|
imposed by DOS filesystems. The Windows ports of GDB use the standard
|
imposed by DOS filesystems. The Windows ports of GDB use the standard
|
name, but if they find a `gdb.ini' file, they warn you about that and
|
name, but if they find a `gdb.ini' file, they warn you about that and
|
suggest to rename the file to the standard name.
|
suggest to rename the file to the standard name.
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) On DOS/Windows systems, the home directory is the one pointed to
|
(1) On DOS/Windows systems, the home directory is the one pointed to
|
by the `HOME' environment variable.
|
by the `HOME' environment variable.
|
|
|
|
|
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
|
|
|
2.2 Quitting GDB
|
2.2 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 `Ctrl-d'). If you do not supply
|
end-of-file character (usually `Ctrl-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 `Ctrl-c') does not exit from GDB, but rather
|
An interrupt (often `Ctrl-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, Next: Logging Output, Prev: Quitting GDB, Up: Invocation
|
File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation
|
|
|
2.3 Shell Commands
|
2.3 Shell Commands
|
==================
|
==================
|
|
|
If you need to execute occasional shell commands during your debugging
|
If you need to execute occasional shell commands during your debugging
|
session, there is no need to leave or suspend GDB; you can just use the
|
session, there is no need to leave or suspend GDB; you can just use the
|
`shell' command.
|
`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: Logging Output, Prev: Shell Commands, Up: Invocation
|
File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation
|
|
|
2.4 Logging Output
|
2.4 Logging Output
|
==================
|
==================
|
|
|
You may want to save the output of GDB commands to a file. There are
|
You may want to save the output of GDB commands to a file. There are
|
several commands to control GDB's logging.
|
several commands to control GDB's logging.
|
|
|
`set logging on'
|
`set logging on'
|
Enable logging.
|
Enable logging.
|
|
|
`set logging off'
|
`set logging off'
|
Disable logging.
|
Disable logging.
|
|
|
`set logging file FILE'
|
`set logging file FILE'
|
Change the name of the current logfile. The default logfile is
|
Change the name of the current logfile. The default logfile is
|
`gdb.txt'.
|
`gdb.txt'.
|
|
|
`set logging overwrite [on|off]'
|
`set logging overwrite [on|off]'
|
By default, GDB will append to the logfile. Set `overwrite' if
|
By default, GDB will append to the logfile. Set `overwrite' if
|
you want `set logging on' to overwrite the logfile instead.
|
you want `set logging on' to overwrite the logfile instead.
|
|
|
`set logging redirect [on|off]'
|
`set logging redirect [on|off]'
|
By default, GDB output will go to both the terminal and the
|
By default, GDB output will go to both the terminal and the
|
logfile. Set `redirect' if you want output to go only to the log
|
logfile. Set `redirect' if you want output to go only to the log
|
file.
|
file.
|
|
|
`show logging'
|
`show logging'
|
Show the current values of the logging settings.
|
Show the current values of the logging settings.
|
|
|
|
|
File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top
|
File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top
|
|
|
3 GDB Commands
|
3 GDB Commands
|
**************
|
**************
|
|
|
You can abbreviate a GDB command to the first few letters of the command
|
You can abbreviate a GDB command to the first few letters of the command
|
name, if that abbreviation is unambiguous; and you can repeat certain
|
name, if that abbreviation is unambiguous; and you can repeat certain
|
GDB commands by typing just . You can also use the key to
|
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 you the
|
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).
|
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
|
|
|
3.1 Command Syntax
|
3.1 Command Syntax
|
==================
|
==================
|
|
|
A GDB command is a single line of input. There is no limit on how long
|
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
|
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.
|
User-defined commands can disable this feature; see *note dont-repeat:
|
User-defined commands can disable this feature; see *note dont-repeat:
|
Define.
|
Define.
|
|
|
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.).
|
|
|
The `Ctrl-o' binding is useful for repeating a complex sequence of
|
The `Ctrl-o' binding is useful for repeating a complex sequence of
|
commands. This command accepts the current line, like , and then
|
commands. This command accepts the current line, like , and then
|
fetches the next line relative to the current line from the history for
|
fetches the next line relative to the current line from the history for
|
editing.
|
editing.
|
|
|
|
|
File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands
|
File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands
|
|
|
3.2 Command Completion
|
3.2 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
|
name of a C++ function. This is because C++ allows function
|
overloading (multiple definitions of the same function, distinguished
|
overloading (multiple definitions of the same function, distinguished
|
by argument type). For example, when you want to set a breakpoint you
|
by argument type). For example, when you want to set a breakpoint you
|
may need to distinguish whether you mean the version of `name' that
|
may need to distinguish whether you mean the version of `name' that
|
takes an `int' parameter, `name(int)', or the version that takes a
|
takes an `int' parameter, `name(int)', or the version that takes a
|
`float' parameter, `name(float)'. To use the word-completion
|
`float' parameter, `name(float)'. To use the word-completion
|
facilities in this situation, type a single quote `'' at the beginning
|
facilities in this situation, type a single quote `'' at the beginning
|
of the function name. This alerts GDB that it may need to consider
|
of the function name. This alerts GDB that it may need to consider
|
more information than usual when you press or `M-?' to request
|
more information than usual when you press or `M-?' to request
|
word completion:
|
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.
|
|
|
When completing in an expression which looks up a field in a
|
When completing in an expression which looks up a field in a
|
structure, GDB also tries(1) to limit completions to the field names
|
structure, GDB also tries(1) to limit completions to the field names
|
available in the type of the left-hand-side:
|
available in the type of the left-hand-side:
|
|
|
(gdb) p gdb_stdout.M-?
|
(gdb) p gdb_stdout.M-?
|
magic to_delete to_fputs to_put to_rewind
|
magic to_delete to_fputs to_put to_rewind
|
to_data to_flush to_isatty to_read to_write
|
to_data to_flush to_isatty to_read to_write
|
|
|
This is because the `gdb_stdout' is a variable of the type `struct
|
This is because the `gdb_stdout' is a variable of the type `struct
|
ui_file' that is defined in GDB sources as follows:
|
ui_file' that is defined in GDB sources as follows:
|
|
|
struct ui_file
|
struct ui_file
|
{
|
{
|
int *magic;
|
int *magic;
|
ui_file_flush_ftype *to_flush;
|
ui_file_flush_ftype *to_flush;
|
ui_file_write_ftype *to_write;
|
ui_file_write_ftype *to_write;
|
ui_file_fputs_ftype *to_fputs;
|
ui_file_fputs_ftype *to_fputs;
|
ui_file_read_ftype *to_read;
|
ui_file_read_ftype *to_read;
|
ui_file_delete_ftype *to_delete;
|
ui_file_delete_ftype *to_delete;
|
ui_file_isatty_ftype *to_isatty;
|
ui_file_isatty_ftype *to_isatty;
|
ui_file_rewind_ftype *to_rewind;
|
ui_file_rewind_ftype *to_rewind;
|
ui_file_put_ftype *to_put;
|
ui_file_put_ftype *to_put;
|
void *to_data;
|
void *to_data;
|
}
|
}
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) The completer can be confused by certain kinds of invalid
|
(1) The completer can be confused by certain kinds of invalid
|
expressions. Also, it only examines the static type of the expression,
|
expressions. Also, it only examines the static type of the expression,
|
not the dynamic type.
|
not the dynamic type.
|
|
|
|
|
File: gdb.info, Node: Help, Prev: Completion, Up: Commands
|
File: gdb.info, Node: Help, Prev: Completion, Up: Commands
|
|
|
3.3 Getting Help
|
3.3 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' command searches through all of the GDB commands,
|
The `apropos' command searches through all of the GDB commands,
|
and their documentation, for the regular expression specified in
|
and their documentation, for the regular expression specified in
|
ARGS. It prints out all matches found. For example:
|
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 show the arguments passed to a
|
program. For example, you can show the arguments passed to a
|
function with `info args', list the registers currently in use
|
function with `info args', list the registers currently in use
|
with `info registers', or list the breakpoints you have set with
|
with `info registers', or list the breakpoints you have set with
|
`info breakpoints'. You can get a complete list of the `info'
|
`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'
|
`info copying'
|
`info copying'
|
Display information about permission for copying GDB.
|
Display information about permission for copying GDB.
|
|
|
`show warranty'
|
`show warranty'
|
`info warranty'
|
`info 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
|
|
|
4 Running Programs Under GDB
|
4 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
|
|
|
* Inferiors and Programs:: Debugging multiple inferiors and programs
|
* Inferiors and Programs:: Debugging multiple inferiors and programs
|
* Threads:: Debugging programs with multiple threads
|
* Threads:: Debugging programs with multiple threads
|
* Forks:: Debugging forks
|
* Forks:: Debugging forks
|
* Checkpoint/Restart:: Setting a _bookmark_ to return to later
|
* Checkpoint/Restart:: Setting a _bookmark_ to return to later
|
|
|
|
|
File: gdb.info, Node: Compilation, Next: Starting, Up: Running
|
File: gdb.info, Node: Compilation, Next: Starting, Up: Running
|
|
|
4.1 Compiling for Debugging
|
4.1 Compiling for Debugging
|
===========================
|
===========================
|
|
|
In order to debug a program effectively, you need to generate debugging
|
In order to debug a program effectively, you need to generate debugging
|
information when you compile it. This debugging information is stored
|
information when you compile it. This debugging information is stored
|
in the object file; it describes the data type of each variable or
|
in the object file; it describes the data type of each variable or
|
function and the correspondence between source line numbers and
|
function and the correspondence between source line numbers and
|
addresses in the executable code.
|
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.
|
|
|
Programs that are to be shipped to your customers are compiled with
|
Programs that are to be shipped to your customers are compiled with
|
optimizations, using the `-O' compiler option. However, some compilers
|
optimizations, using the `-O' compiler option. However, some compilers
|
are unable to handle the `-g' and `-O' options together. Using those
|
are unable to handle the `-g' and `-O' options together. Using those
|
compilers, you cannot generate optimized executables containing
|
compilers, you cannot generate optimized executables containing
|
debugging information.
|
debugging information.
|
|
|
GCC, the GNU C/C++ compiler, supports `-g' with or without `-O',
|
GCC, the GNU C/C++ compiler, supports `-g' with or without `-O',
|
making it possible to debug optimized code. We recommend that you
|
making it possible to debug optimized code. We recommend that you
|
_always_ use `-g' whenever you compile a program. You may think your
|
_always_ use `-g' whenever you compile a program. You may think your
|
program is correct, but there is no sense in pushing your luck. For
|
program is correct, but there is no sense in pushing your luck. For
|
more information, see *note Optimized Code::.
|
more information, see *note Optimized Code::.
|
|
|
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.
|
|
|
GDB knows about preprocessor macros and can show you their expansion
|
GDB knows about preprocessor macros and can show you their expansion
|
(*note Macros::). Most compilers do not include information about
|
(*note Macros::). Most compilers do not include information about
|
preprocessor macros in the debugging information if you specify the
|
preprocessor macros in the debugging information if you specify the
|
`-g' flag alone, because this information is rather large. Version 3.1
|
`-g' flag alone, because this information is rather large. Version 3.1
|
and later of GCC, the GNU C compiler, provides macro information if you
|
and later of GCC, the GNU C compiler, provides macro information if you
|
specify the options `-gdwarf-2' and `-g3'; the former option requests
|
specify the options `-gdwarf-2' and `-g3'; the former option requests
|
debugging information in the Dwarf 2 format, and the latter requests
|
debugging information in the Dwarf 2 format, and the latter requests
|
"extra information". In the future, we hope to find more compact ways
|
"extra information". In the future, we hope to find more compact ways
|
to represent macro information, so that it can be included with `-g'
|
to represent macro information, so that it can be included with `-g'
|
alone.
|
alone.
|
|
|
|
|
File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running
|
File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running
|
|
|
4.2 Starting your Program
|
4.2 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 some environments without processes,
|
process run your program. In some environments without processes,
|
`run' jumps to the start of your program. Other targets, like
|
`run' jumps to the start of your program. Other targets, like
|
`remote', are always running. If you get an error message like this
|
`remote', are always running. If you get an error message like this
|
one:
|
one:
|
|
|
The "remote" target does not support "run".
|
The "remote" target does not support "run".
|
Try "help target" or "continue".
|
Try "help target" or "continue".
|
|
|
then use `continue' to run your program. You may need `load' first
|
then use `continue' to run your program. You may need `load' first
|
(*note load::).
|
(*note load::).
|
|
|
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.
|
|
|
`start'
|
`start'
|
The name of the main procedure can vary from language to language.
|
The name of the main procedure can vary from language to language.
|
With C or C++, the main procedure name is always `main', but other
|
With C or C++, the main procedure name is always `main', but other
|
languages such as Ada do not require a specific name for their
|
languages such as Ada do not require a specific name for their
|
main procedure. The debugger provides a convenient way to start
|
main procedure. The debugger provides a convenient way to start
|
the execution of the program and to stop at the beginning of the
|
the execution of the program and to stop at the beginning of the
|
main procedure, depending on the language used.
|
main procedure, depending on the language used.
|
|
|
The `start' command does the equivalent of setting a temporary
|
The `start' command does the equivalent of setting a temporary
|
breakpoint at the beginning of the main procedure and then invoking
|
breakpoint at the beginning of the main procedure and then invoking
|
the `run' command.
|
the `run' command.
|
|
|
Some programs contain an "elaboration" phase where some startup
|
Some programs contain an "elaboration" phase where some startup
|
code is executed before the main procedure is called. This
|
code is executed before the main procedure is called. This
|
depends on the languages used to write your program. In C++, for
|
depends on the languages used to write your program. In C++, for
|
instance, constructors for static and global objects are executed
|
instance, constructors for static and global objects are executed
|
before `main' is called. It is therefore possible that the
|
before `main' is called. It is therefore possible that the
|
debugger stops before reaching the main procedure. However, the
|
debugger stops before reaching the main procedure. However, the
|
temporary breakpoint will remain to halt execution.
|
temporary breakpoint will remain to halt execution.
|
|
|
Specify the arguments to give to your program as arguments to the
|
Specify the arguments to give to your program as arguments to the
|
`start' command. These arguments will be given verbatim to the
|
`start' command. These arguments will be given verbatim to the
|
underlying `run' command. Note that the same arguments will be
|
underlying `run' command. Note that the same arguments will be
|
reused if no argument is provided during subsequent calls to
|
reused if no argument is provided during subsequent calls to
|
`start' or `run'.
|
`start' or `run'.
|
|
|
It is sometimes necessary to debug the program during elaboration.
|
It is sometimes necessary to debug the program during elaboration.
|
In these cases, using the `start' command would stop the execution
|
In these cases, using the `start' command would stop the execution
|
of your program too late, as the program would have already
|
of your program too late, as the program would have already
|
completed the elaboration phase. Under these circumstances,
|
completed the elaboration phase. Under these circumstances,
|
insert breakpoints in your elaboration code before running your
|
insert breakpoints in your elaboration code before running your
|
program.
|
program.
|
|
|
`set exec-wrapper WRAPPER'
|
`set exec-wrapper WRAPPER'
|
`show exec-wrapper'
|
`show exec-wrapper'
|
`unset exec-wrapper'
|
`unset exec-wrapper'
|
When `exec-wrapper' is set, the specified wrapper is used to
|
When `exec-wrapper' is set, the specified wrapper is used to
|
launch programs for debugging. GDB starts your program with a
|
launch programs for debugging. GDB starts your program with a
|
shell command of the form `exec WRAPPER PROGRAM'. Quoting is
|
shell command of the form `exec WRAPPER PROGRAM'. Quoting is
|
added to PROGRAM and its arguments, but not to WRAPPER, so you
|
added to PROGRAM and its arguments, but not to WRAPPER, so you
|
should add quotes if appropriate for your shell. The wrapper runs
|
should add quotes if appropriate for your shell. The wrapper runs
|
until it executes your program, and then GDB takes control.
|
until it executes your program, and then GDB takes control.
|
|
|
You can use any program that eventually calls `execve' with its
|
You can use any program that eventually calls `execve' with its
|
arguments as a wrapper. Several standard Unix utilities do this,
|
arguments as a wrapper. Several standard Unix utilities do this,
|
e.g. `env' and `nohup'. Any Unix shell script ending with `exec
|
e.g. `env' and `nohup'. Any Unix shell script ending with `exec
|
"$@"' will also work.
|
"$@"' will also work.
|
|
|
For example, you can use `env' to pass an environment variable to
|
For example, you can use `env' to pass an environment variable to
|
the debugged program, without setting the variable in your shell's
|
the debugged program, without setting the variable in your shell's
|
environment:
|
environment:
|
|
|
(gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so'
|
(gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so'
|
(gdb) run
|
(gdb) run
|
|
|
This command is available when debugging locally on most targets,
|
This command is available when debugging locally on most targets,
|
excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino.
|
excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino.
|
|
|
`set disable-randomization'
|
`set disable-randomization'
|
`set disable-randomization on'
|
`set disable-randomization on'
|
This option (enabled by default in GDB) will turn off the native
|
This option (enabled by default in GDB) will turn off the native
|
randomization of the virtual address space of the started program.
|
randomization of the virtual address space of the started program.
|
This option is useful for multiple debugging sessions to make the
|
This option is useful for multiple debugging sessions to make the
|
execution better reproducible and memory addresses reusable across
|
execution better reproducible and memory addresses reusable across
|
debugging sessions.
|
debugging sessions.
|
|
|
This feature is implemented only on GNU/Linux. You can get the
|
This feature is implemented only on GNU/Linux. You can get the
|
same behavior using
|
same behavior using
|
|
|
(gdb) set exec-wrapper setarch `uname -m` -R
|
(gdb) set exec-wrapper setarch `uname -m` -R
|
|
|
`set disable-randomization off'
|
`set disable-randomization off'
|
Leave the behavior of the started executable unchanged. Some bugs
|
Leave the behavior of the started executable unchanged. Some bugs
|
rear their ugly heads only when the program is loaded at certain
|
rear their ugly heads only when the program is loaded at certain
|
addresses. If your bug disappears when you run the program under
|
addresses. If your bug disappears when you run the program under
|
GDB, that might be because GDB by default disables the address
|
GDB, that might be because GDB by default disables the address
|
randomization on platforms, such as GNU/Linux, which do that for
|
randomization on platforms, such as GNU/Linux, which do that for
|
stand-alone programs. Use `set disable-randomization off' to try
|
stand-alone programs. Use `set disable-randomization off' to try
|
to reproduce such elusive bugs.
|
to reproduce such elusive bugs.
|
|
|
The virtual address space randomization is implemented only on
|
The virtual address space randomization is implemented only on
|
GNU/Linux. It protects the programs against some kinds of
|
GNU/Linux. It protects the programs against some kinds of
|
security attacks. In these cases the attacker needs to know the
|
security attacks. In these cases the attacker needs to know the
|
exact location of a concrete executable code. Randomizing its
|
exact location of a concrete executable code. Randomizing its
|
location makes it impossible to inject jumps misusing a code at
|
location makes it impossible to inject jumps misusing a code at
|
its expected addresses.
|
its expected addresses.
|
|
|
Prelinking shared libraries provides a startup performance
|
Prelinking shared libraries provides a startup performance
|
advantage but it makes addresses in these libraries predictable
|
advantage but it makes addresses in these libraries predictable
|
for privileged processes by having just unprivileged access at the
|
for privileged processes by having just unprivileged access at the
|
target system. Reading the shared library binary gives enough
|
target system. Reading the shared library binary gives enough
|
information for assembling the malicious code misusing it. Still
|
information for assembling the malicious code misusing it. Still
|
even a prelinked shared library can get loaded at a new random
|
even a prelinked shared library can get loaded at a new random
|
address just requiring the regular relocation process during the
|
address just requiring the regular relocation process during the
|
startup. Shared libraries not already prelinked are always loaded
|
startup. Shared libraries not already prelinked are always loaded
|
at a randomly chosen address.
|
at a randomly chosen address.
|
|
|
Position independent executables (PIE) contain position
|
Position independent executables (PIE) contain position
|
independent code similar to the shared libraries and therefore
|
independent code similar to the shared libraries and therefore
|
such executables get loaded at a randomly chosen address upon
|
such executables get loaded at a randomly chosen address upon
|
startup. PIE executables always load even already prelinked
|
startup. PIE executables always load even already prelinked
|
shared libraries at a random address. You can build such
|
shared libraries at a random address. You can build such
|
executable using `gcc -fPIE -pie'.
|
executable using `gcc -fPIE -pie'.
|
|
|
Heap (malloc storage), stack and custom mmap areas are always
|
Heap (malloc storage), stack and custom mmap areas are always
|
placed randomly (as long as the randomization is enabled).
|
placed randomly (as long as the randomization is enabled).
|
|
|
`show disable-randomization'
|
`show disable-randomization'
|
Show the current setting of the explicit disable of the native
|
Show the current setting of the explicit disable of the native
|
randomization of the virtual address space of the started program.
|
randomization of the virtual address space of the started program.
|
|
|
|
|
|
|
File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running
|
File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running
|
|
|
4.3 Your Program's Arguments
|
4.3 Your Program's Arguments
|
============================
|
============================
|
|
|
The arguments to your program can be specified by the arguments of the
|
The arguments to your program can be specified by the arguments of the
|
`run' command. They are passed to a shell, which expands wildcard
|
`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.
|
|
|
|
|
File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running
|
File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running
|
|
|
4.4 Your Program's Environment
|
4.4 Your Program's Environment
|
==============================
|
==============================
|
|
|
The "environment" consists of a set of environment variables and their
|
The "environment" consists of a set of environment variables and their
|
values. Environment variables conventionally record such things as
|
values. Environment variables conventionally record such things as
|
your user name, your home directory, your terminal type, and your search
|
your user name, your home directory, your terminal type, and your search
|
path for programs to run. Usually you set up environment variables with
|
path for programs to run. Usually you set up environment variables with
|
the shell and they are inherited by all the other programs you run.
|
the shell and they are inherited by all the other programs you run.
|
When debugging, it can be useful to try running your program with a
|
When debugging, it can be useful to try running your program with a
|
modified environment without having to start GDB over again.
|
modified environment without having to start GDB over again.
|
|
|
`path DIRECTORY'
|
`path DIRECTORY'
|
Add DIRECTORY to the front of the `PATH' environment variable (the
|
Add DIRECTORY to the front of the `PATH' environment variable (the
|
search path for executables) that will be passed to your program.
|
search path for executables) that will be passed to your program.
|
The value of `PATH' used by GDB does not change. You may specify
|
The value of `PATH' used by GDB does not change. You may specify
|
several directory names, separated by whitespace or by a
|
several directory names, separated by whitespace or by a
|
system-dependent separator character (`:' on Unix, `;' on MS-DOS
|
system-dependent separator character (`:' on Unix, `;' on MS-DOS
|
and MS-Windows). If DIRECTORY is already in the path, it is moved
|
and MS-Windows). If DIRECTORY is already in the path, it is moved
|
to the front, so it is searched sooner.
|
to the front, so it is searched sooner.
|
|
|
You can use the string `$cwd' to refer to whatever is the current
|
You can use the string `$cwd' to refer to whatever is the current
|
working directory at the time GDB searches the path. If you use
|
working directory at the time GDB searches the path. If you use
|
`.' instead, it refers to the directory where you executed the
|
`.' instead, it refers to the directory where you executed the
|
`path' command. GDB replaces `.' in the DIRECTORY argument (with
|
`path' command. GDB replaces `.' in the DIRECTORY argument (with
|
the current path) before adding DIRECTORY to the search path.
|
the current path) before adding DIRECTORY to the search path.
|
|
|
`show paths'
|
`show paths'
|
Display the list of search paths for executables (the `PATH'
|
Display the list of search paths for executables (the `PATH'
|
environment variable).
|
environment variable).
|
|
|
`show environment [VARNAME]'
|
`show environment [VARNAME]'
|
Print the value of environment variable VARNAME to be given to
|
Print the value of environment variable VARNAME to be given to
|
your program when it starts. If you do not supply VARNAME, print
|
your program when it starts. If you do not supply VARNAME, print
|
the names and values of all environment variables to be given to
|
the names and values of all environment variables to be given to
|
your program. You can abbreviate `environment' as `env'.
|
your program. You can abbreviate `environment' as `env'.
|
|
|
`set environment VARNAME [=VALUE]'
|
`set environment VARNAME [=VALUE]'
|
Set environment variable VARNAME to VALUE. The value changes for
|
Set environment variable VARNAME to VALUE. The value changes for
|
your program only, not for GDB itself. VALUE may be any string;
|
your program only, not for GDB itself. VALUE may be any string;
|
the values of environment variables are just strings, and any
|
the values of environment variables are just strings, and any
|
interpretation is supplied by your program itself. The VALUE
|
interpretation is supplied by your program itself. The VALUE
|
parameter is optional; if it is eliminated, the variable is set to
|
parameter is optional; if it is eliminated, the variable is set to
|
a null value.
|
a null value.
|
|
|
For example, this command:
|
For example, this command:
|
|
|
set env USER = foo
|
set env USER = foo
|
|
|
tells the debugged program, when subsequently run, that its user
|
tells the debugged program, when subsequently run, that its user
|
is named `foo'. (The spaces around `=' are used for clarity here;
|
is named `foo'. (The spaces around `=' are used for clarity here;
|
they are not actually required.)
|
they are not actually required.)
|
|
|
`unset environment VARNAME'
|
`unset environment VARNAME'
|
Remove variable VARNAME from the environment to be passed to your
|
Remove variable VARNAME from the environment to be passed to your
|
program. This is different from `set env VARNAME ='; `unset
|
program. This is different from `set env VARNAME ='; `unset
|
environment' removes the variable from the environment, rather
|
environment' removes the variable from the environment, rather
|
than assigning it an empty value.
|
than assigning it an empty value.
|
|
|
_Warning:_ On Unix systems, GDB runs your program using the shell
|
_Warning:_ On Unix systems, GDB runs your program using the shell
|
indicated by your `SHELL' environment variable if it exists (or
|
indicated by your `SHELL' environment variable if it exists (or
|
`/bin/sh' if not). If your `SHELL' variable names a shell that runs an
|
`/bin/sh' if not). If your `SHELL' variable names a shell that runs an
|
initialization file--such as `.cshrc' for C-shell, or `.bashrc' for
|
initialization file--such as `.cshrc' for C-shell, or `.bashrc' for
|
BASH--any variables you set in that file affect your program. You may
|
BASH--any variables you set in that file affect your program. You may
|
wish to move setting of environment variables to files that are only
|
wish to move setting of environment variables to files that are only
|
run when you sign on, such as `.login' or `.profile'.
|
run when you sign on, such as `.login' or `.profile'.
|
|
|
|
|
File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running
|
File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running
|
|
|
4.5 Your Program's Working Directory
|
4.5 Your Program's Working Directory
|
====================================
|
====================================
|
|
|
Each time you start your program with `run', it inherits its working
|
Each time you start your program with `run', it inherits its working
|
directory from the current working directory of GDB. The GDB working
|
directory from the current working directory of GDB. The GDB working
|
directory is initially whatever it inherited from its parent process
|
directory is initially whatever it inherited from its parent process
|
(typically the shell), but you can specify a new working directory in
|
(typically the shell), but you can specify a new working directory in
|
GDB with the `cd' command.
|
GDB with the `cd' command.
|
|
|
The GDB working directory also serves as a default for the commands
|
The GDB working directory also serves as a default for the commands
|
that specify files for GDB to operate on. *Note Commands to Specify
|
that specify files for GDB to operate on. *Note Commands to Specify
|
Files: Files.
|
Files: Files.
|
|
|
`cd DIRECTORY'
|
`cd DIRECTORY'
|
Set the GDB working directory to DIRECTORY.
|
Set the GDB working directory to DIRECTORY.
|
|
|
`pwd'
|
`pwd'
|
Print the GDB working directory.
|
Print the GDB working directory.
|
|
|
It is generally impossible to find the current working directory of
|
It is generally impossible to find the current working directory of
|
the process being debugged (since a program can change its directory
|
the process being debugged (since a program can change its directory
|
during its run). If you work on a system where GDB is configured with
|
during its run). If you work on a system where GDB is configured with
|
the `/proc' support, you can use the `info proc' command (*note SVR4
|
the `/proc' support, you can use the `info proc' command (*note SVR4
|
Process Information::) to find out the current working directory of the
|
Process Information::) to find out the current working directory of the
|
debuggee.
|
debuggee.
|
|
|
|
|
File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running
|
File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running
|
|
|
4.6 Your Program's Input and Output
|
4.6 Your Program's Input and Output
|
===================================
|
===================================
|
|
|
By default, the program you run under GDB does input and output to the
|
By default, the program you run under GDB does input and output to the
|
same terminal that GDB uses. GDB switches the terminal to its own
|
same terminal that GDB uses. GDB switches the terminal to its own
|
terminal modes to interact with you, but it records the terminal modes
|
terminal modes to interact with you, but it records the terminal modes
|
your program was using and switches back to them when you continue
|
your program was using and switches back to them when you continue
|
running your program.
|
running your program.
|
|
|
`info terminal'
|
`info terminal'
|
Displays information recorded by GDB about the terminal modes your
|
Displays information recorded by GDB about the terminal modes your
|
program is using.
|
program is using.
|
|
|
You can redirect your program's input and/or output using shell
|
You can redirect your program's input and/or output using shell
|
redirection with the `run' command. For example,
|
redirection with the `run' command. For example,
|
|
|
run > outfile
|
run > outfile
|
|
|
starts your program, diverting its output to the file `outfile'.
|
starts your program, diverting its output to the file `outfile'.
|
|
|
Another way to specify where your program should do input and output
|
Another way to specify where your program should do input and output
|
is with the `tty' command. This command accepts a file name as
|
is with the `tty' command. This command accepts a file name as
|
argument, and causes this file to be the default for future `run'
|
argument, and causes this file to be the default for future `run'
|
commands. It also resets the controlling terminal for the child
|
commands. It also resets the controlling terminal for the child
|
process, for future `run' commands. For example,
|
process, for future `run' commands. For example,
|
|
|
tty /dev/ttyb
|
tty /dev/ttyb
|
|
|
directs that processes started with subsequent `run' commands default
|
directs that processes started with subsequent `run' commands default
|
to do input and output on the terminal `/dev/ttyb' and have that as
|
to do input and output on the terminal `/dev/ttyb' and have that as
|
their controlling terminal.
|
their controlling terminal.
|
|
|
An explicit redirection in `run' overrides the `tty' command's
|
An explicit redirection in `run' overrides the `tty' command's
|
effect on the input/output device, but not its effect on the controlling
|
effect on the input/output device, but not its effect on the controlling
|
terminal.
|
terminal.
|
|
|
When you use the `tty' command or redirect input in the `run'
|
When you use the `tty' command or redirect input in the `run'
|
command, only the input _for your program_ is affected. The input for
|
command, only the input _for your program_ is affected. The input for
|
GDB still comes from your terminal. `tty' is an alias for `set
|
GDB still comes from your terminal. `tty' is an alias for `set
|
inferior-tty'.
|
inferior-tty'.
|
|
|
You can use the `show inferior-tty' command to tell GDB to display
|
You can use the `show inferior-tty' command to tell GDB to display
|
the name of the terminal that will be used for future runs of your
|
the name of the terminal that will be used for future runs of your
|
program.
|
program.
|
|
|
`set inferior-tty /dev/ttyb'
|
`set inferior-tty /dev/ttyb'
|
Set the tty for the program being debugged to /dev/ttyb.
|
Set the tty for the program being debugged to /dev/ttyb.
|
|
|
`show inferior-tty'
|
`show inferior-tty'
|
Show the current tty for the program being debugged.
|
Show the current tty for the program being debugged.
|
|
|
|
|
File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running
|
File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running
|
|
|
4.7 Debugging an Already-running Process
|
4.7 Debugging an Already-running Process
|
========================================
|
========================================
|
|
|
`attach PROCESS-ID'
|
`attach PROCESS-ID'
|
This command attaches to a running process--one that was started
|
This command attaches to a running process--one that was started
|
outside GDB. (`info files' shows your active targets.) The
|
outside GDB. (`info files' shows your active targets.) The
|
command takes as argument a process ID. The usual way to find out
|
command takes as argument a process ID. The usual way to find out
|
the PROCESS-ID of a Unix process is with the `ps' utility, or with
|
the PROCESS-ID of a Unix process is with the `ps' utility, or with
|
the `jobs -l' shell command.
|
the `jobs -l' shell command.
|
|
|
`attach' does not repeat if you press a second time after
|
`attach' does not repeat if you press a second time after
|
executing the command.
|
executing the command.
|
|
|
To use `attach', your program must be running in an environment
|
To use `attach', your program must be running in an environment
|
which supports processes; for example, `attach' does not work for
|
which supports processes; for example, `attach' does not work for
|
programs on bare-board targets that lack an operating system. You must
|
programs on bare-board targets that lack an operating system. You must
|
also have permission to send the process a signal.
|
also have permission to send the process a signal.
|
|
|
When you use `attach', the debugger finds the program running in the
|
When you use `attach', the debugger finds the program running in the
|
process first by looking in the current working directory, then (if the
|
process first by looking in the current working directory, then (if the
|
program is not found) by using the source file search path (*note
|
program is not found) by using the source file search path (*note
|
Specifying Source Directories: Source Path.). You can also use the
|
Specifying Source Directories: Source Path.). You can also use the
|
`file' command to load the program. *Note Commands to Specify Files:
|
`file' command to load the program. *Note Commands to Specify Files:
|
Files.
|
Files.
|
|
|
The first thing GDB does after arranging to debug the specified
|
The first thing GDB does after arranging to debug the specified
|
process is to stop it. You can examine and modify an attached process
|
process is to stop it. You can examine and modify an attached process
|
with all the GDB commands that are ordinarily available when you start
|
with all the GDB commands that are ordinarily available when you start
|
processes with `run'. You can insert breakpoints; you can step and
|
processes with `run'. You can insert breakpoints; you can step and
|
continue; you can modify storage. If you would rather the process
|
continue; you can modify storage. If you would rather the process
|
continue running, you may use the `continue' command after attaching
|
continue running, you may use the `continue' command after attaching
|
GDB to the process.
|
GDB to the process.
|
|
|
`detach'
|
`detach'
|
When you have finished debugging the attached process, you can use
|
When you have finished debugging the attached process, you can use
|
the `detach' command to release it from GDB control. Detaching
|
the `detach' command to release it from GDB control. Detaching
|
the process continues its execution. After the `detach' command,
|
the process continues its execution. After the `detach' command,
|
that process and GDB become completely independent once more, and
|
that process and GDB become completely independent once more, and
|
you are ready to `attach' another process or start one with `run'.
|
you are ready to `attach' another process or start one with `run'.
|
`detach' does not repeat if you press again after executing
|
`detach' does not repeat if you press again after executing
|
the command.
|
the command.
|
|
|
If you exit GDB while you have an attached process, you detach that
|
If you exit GDB while you have an attached process, you detach that
|
process. If you use the `run' command, you kill that process. By
|
process. If you use the `run' command, you kill that process. By
|
default, GDB asks for confirmation if you try to do either of these
|
default, GDB asks for confirmation if you try to do either of these
|
things; you can control whether or not you need to confirm by using the
|
things; you can control whether or not you need to confirm by using the
|
`set confirm' command (*note Optional Warnings and Messages:
|
`set confirm' command (*note Optional Warnings and Messages:
|
Messages/Warnings.).
|
Messages/Warnings.).
|
|
|
|
|
File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running
|
File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running
|
|
|
4.8 Killing the Child Process
|
4.8 Killing the Child Process
|
=============================
|
=============================
|
|
|
`kill'
|
`kill'
|
Kill the child process in which your program is running under GDB.
|
Kill the child process in which your program is running under GDB.
|
|
|
This command is useful if you wish to debug a core dump instead of a
|
This command is useful if you wish to debug a core dump instead of a
|
running process. GDB ignores any core dump file while your program is
|
running process. GDB ignores any core dump file while your program is
|
running.
|
running.
|
|
|
On some operating systems, a program cannot be executed outside GDB
|
On some operating systems, a program cannot be executed outside GDB
|
while you have breakpoints set on it inside GDB. You can use the
|
while you have breakpoints set on it inside GDB. You can use the
|
`kill' command in this situation to permit running your program outside
|
`kill' command in this situation to permit running your program outside
|
the debugger.
|
the debugger.
|
|
|
The `kill' command is also useful if you wish to recompile and
|
The `kill' command is also useful if you wish to recompile and
|
relink your program, since on many systems it is impossible to modify an
|
relink your program, since on many systems it is impossible to modify an
|
executable file while it is running in a process. In this case, when
|
executable file while it is running in a process. In this case, when
|
you next type `run', GDB notices that the file has changed, and reads
|
you next type `run', GDB notices that the file has changed, and reads
|
the symbol table again (while trying to preserve your current
|
the symbol table again (while trying to preserve your current
|
breakpoint settings).
|
breakpoint settings).
|
|
|
|
|
File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running
|
File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running
|
|
|
4.9 Debugging Multiple Inferiors and Programs
|
4.9 Debugging Multiple Inferiors and Programs
|
=============================================
|
=============================================
|
|
|
GDB lets you run and debug multiple programs in a single session. In
|
GDB lets you run and debug multiple programs in a single session. In
|
addition, GDB on some systems may let you run several programs
|
addition, GDB on some systems may let you run several programs
|
simultaneously (otherwise you have to exit from one before starting
|
simultaneously (otherwise you have to exit from one before starting
|
another). In the most general case, you can have multiple threads of
|
another). In the most general case, you can have multiple threads of
|
execution in each of multiple processes, launched from multiple
|
execution in each of multiple processes, launched from multiple
|
executables.
|
executables.
|
|
|
GDB represents the state of each program execution with an object
|
GDB represents the state of each program execution with an object
|
called an "inferior". An inferior typically corresponds to a process,
|
called an "inferior". An inferior typically corresponds to a process,
|
but is more general and applies also to targets that do not have
|
but is more general and applies also to targets that do not have
|
processes. Inferiors may be created before a process runs, and may be
|
processes. Inferiors may be created before a process runs, and may be
|
retained after a process exits. Inferiors have unique identifiers that
|
retained after a process exits. Inferiors have unique identifiers that
|
are different from process ids. Usually each inferior will also have
|
are different from process ids. Usually each inferior will also have
|
its own distinct address space, although some embedded targets may have
|
its own distinct address space, although some embedded targets may have
|
several inferiors running in different parts of a single address space.
|
several inferiors running in different parts of a single address space.
|
Each inferior may in turn have multiple threads running in it.
|
Each inferior may in turn have multiple threads running in it.
|
|
|
To find out what inferiors exist at any moment, use `info inferiors':
|
To find out what inferiors exist at any moment, use `info inferiors':
|
|
|
`info inferiors'
|
`info inferiors'
|
Print a list of all inferiors currently being managed by GDB.
|
Print a list of all inferiors currently being managed by GDB.
|
|
|
GDB displays for each inferior (in this order):
|
GDB displays for each inferior (in this order):
|
|
|
1. the inferior number assigned by GDB
|
1. the inferior number assigned by GDB
|
|
|
2. the target system's inferior identifier
|
2. the target system's inferior identifier
|
|
|
3. the name of the executable the inferior is running.
|
3. the name of the executable the inferior is running.
|
|
|
|
|
An asterisk `*' preceding the GDB inferior number indicates the
|
An asterisk `*' preceding the GDB inferior number indicates the
|
current inferior.
|
current inferior.
|
|
|
For example,
|
For example,
|
|
|
(gdb) info inferiors
|
(gdb) info inferiors
|
Num Description Executable
|
Num Description Executable
|
2 process 2307 hello
|
2 process 2307 hello
|
* 1 process 3401 goodbye
|
* 1 process 3401 goodbye
|
|
|
To switch focus between inferiors, use the `inferior' command:
|
To switch focus between inferiors, use the `inferior' command:
|
|
|
`inferior INFNO'
|
`inferior INFNO'
|
Make inferior number INFNO the current inferior. The argument
|
Make inferior number INFNO the current inferior. The argument
|
INFNO is the inferior number assigned by GDB, as shown in the
|
INFNO is the inferior number assigned by GDB, as shown in the
|
first field of the `info inferiors' display.
|
first field of the `info inferiors' display.
|
|
|
You can get multiple executables into a debugging session via the
|
You can get multiple executables into a debugging session via the
|
`add-inferior' and `clone-inferior' commands. On some systems GDB can
|
`add-inferior' and `clone-inferior' commands. On some systems GDB can
|
add inferiors to the debug session automatically by following calls to
|
add inferiors to the debug session automatically by following calls to
|
`fork' and `exec'. To remove inferiors from the debugging session use
|
`fork' and `exec'. To remove inferiors from the debugging session use
|
the `remove-inferior' command.
|
the `remove-inferior' command.
|
|
|
`add-inferior [ -copies N ] [ -exec EXECUTABLE ]'
|
`add-inferior [ -copies N ] [ -exec EXECUTABLE ]'
|
Adds N inferiors to be run using EXECUTABLE as the executable. N
|
Adds N inferiors to be run using EXECUTABLE as the executable. N
|
defaults to 1. If no executable is specified, the inferiors
|
defaults to 1. If no executable is specified, the inferiors
|
begins empty, with no program. You can still assign or change the
|
begins empty, with no program. You can still assign or change the
|
program assigned to the inferior at any time by using the `file'
|
program assigned to the inferior at any time by using the `file'
|
command with the executable name as its argument.
|
command with the executable name as its argument.
|
|
|
`clone-inferior [ -copies N ] [ INFNO ]'
|
`clone-inferior [ -copies N ] [ INFNO ]'
|
Adds N inferiors ready to execute the same program as inferior
|
Adds N inferiors ready to execute the same program as inferior
|
INFNO. N defaults to 1. INFNO defaults to the number of the
|
INFNO. N defaults to 1. INFNO defaults to the number of the
|
current inferior. This is a convenient command when you want to
|
current inferior. This is a convenient command when you want to
|
run another instance of the inferior you are debugging.
|
run another instance of the inferior you are debugging.
|
|
|
(gdb) info inferiors
|
(gdb) info inferiors
|
Num Description Executable
|
Num Description Executable
|
* 1 process 29964 helloworld
|
* 1 process 29964 helloworld
|
(gdb) clone-inferior
|
(gdb) clone-inferior
|
Added inferior 2.
|
Added inferior 2.
|
1 inferiors added.
|
1 inferiors added.
|
(gdb) info inferiors
|
(gdb) info inferiors
|
Num Description Executable
|
Num Description Executable
|
2 helloworld
|
2 helloworld
|
* 1 process 29964 helloworld
|
* 1 process 29964 helloworld
|
|
|
You can now simply switch focus to inferior 2 and run it.
|
You can now simply switch focus to inferior 2 and run it.
|
|
|
`remove-inferior INFNO'
|
`remove-inferior INFNO'
|
Removes the inferior INFNO. It is not possible to remove an
|
Removes the inferior INFNO. It is not possible to remove an
|
inferior that is running with this command. For those, use the
|
inferior that is running with this command. For those, use the
|
`kill' or `detach' command first.
|
`kill' or `detach' command first.
|
|
|
|
|
To quit debugging one of the running inferiors that is not the
|
To quit debugging one of the running inferiors that is not the
|
current inferior, you can either detach from it by using the
|
current inferior, you can either detach from it by using the
|
`detach inferior' command (allowing it to run independently), or kill it
|
`detach inferior' command (allowing it to run independently), or kill it
|
using the `kill inferior' command:
|
using the `kill inferior' command:
|
|
|
`detach inferior INFNO'
|
`detach inferior INFNO'
|
Detach from the inferior identified by GDB inferior number INFNO.
|
Detach from the inferior identified by GDB inferior number INFNO.
|
Note that the inferior's entry still stays on the list of
|
Note that the inferior's entry still stays on the list of
|
inferiors shown by `info inferiors', but its Description will show
|
inferiors shown by `info inferiors', but its Description will show
|
`'.
|
`'.
|
|
|
`kill inferior INFNO'
|
`kill inferior INFNO'
|
Kill the inferior identified by GDB inferior number INFNO. Note
|
Kill the inferior identified by GDB inferior number INFNO. Note
|
that the inferior's entry still stays on the list of inferiors
|
that the inferior's entry still stays on the list of inferiors
|
shown by `info inferiors', but its Description will show `'.
|
shown by `info inferiors', but its Description will show `'.
|
|
|
After the successful completion of a command such as `detach',
|
After the successful completion of a command such as `detach',
|
`detach inferior', `kill' or `kill inferior', or after a normal process
|
`detach inferior', `kill' or `kill inferior', or after a normal process
|
exit, the inferior is still valid and listed with `info inferiors',
|
exit, the inferior is still valid and listed with `info inferiors',
|
ready to be restarted.
|
ready to be restarted.
|
|
|
To be notified when inferiors are started or exit under GDB's
|
To be notified when inferiors are started or exit under GDB's
|
control use `set print inferior-events':
|
control use `set print inferior-events':
|
|
|
`set print inferior-events'
|
`set print inferior-events'
|
`set print inferior-events on'
|
`set print inferior-events on'
|
`set print inferior-events off'
|
`set print inferior-events off'
|
The `set print inferior-events' command allows you to enable or
|
The `set print inferior-events' command allows you to enable or
|
disable printing of messages when GDB notices that new inferiors
|
disable printing of messages when GDB notices that new inferiors
|
have started or that inferiors have exited or have been detached.
|
have started or that inferiors have exited or have been detached.
|
By default, these messages will not be printed.
|
By default, these messages will not be printed.
|
|
|
`show print inferior-events'
|
`show print inferior-events'
|
Show whether messages will be printed when GDB detects that
|
Show whether messages will be printed when GDB detects that
|
inferiors have started, exited or have been detached.
|
inferiors have started, exited or have been detached.
|
|
|
Many commands will work the same with multiple programs as with a
|
Many commands will work the same with multiple programs as with a
|
single program: e.g., `print myglobal' will simply display the value of
|
single program: e.g., `print myglobal' will simply display the value of
|
`myglobal' in the current inferior.
|
`myglobal' in the current inferior.
|
|
|
Occasionaly, when debugging GDB itself, it may be useful to get more
|
Occasionaly, when debugging GDB itself, it may be useful to get more
|
info about the relationship of inferiors, programs, address spaces in a
|
info about the relationship of inferiors, programs, address spaces in a
|
debug session. You can do that with the `maint info program-spaces'
|
debug session. You can do that with the `maint info program-spaces'
|
command.
|
command.
|
|
|
`maint info program-spaces'
|
`maint info program-spaces'
|
Print a list of all program spaces currently being managed by GDB.
|
Print a list of all program spaces currently being managed by GDB.
|
|
|
GDB displays for each program space (in this order):
|
GDB displays for each program space (in this order):
|
|
|
1. the program space number assigned by GDB
|
1. the program space number assigned by GDB
|
|
|
2. the name of the executable loaded into the program space,
|
2. the name of the executable loaded into the program space,
|
with e.g., the `file' command.
|
with e.g., the `file' command.
|
|
|
|
|
An asterisk `*' preceding the GDB program space number indicates
|
An asterisk `*' preceding the GDB program space number indicates
|
the current program space.
|
the current program space.
|
|
|
In addition, below each program space line, GDB prints extra
|
In addition, below each program space line, GDB prints extra
|
information that isn't suitable to display in tabular form. For
|
information that isn't suitable to display in tabular form. For
|
example, the list of inferiors bound to the program space.
|
example, the list of inferiors bound to the program space.
|
|
|
(gdb) maint info program-spaces
|
(gdb) maint info program-spaces
|
Id Executable
|
Id Executable
|
2 goodbye
|
2 goodbye
|
Bound inferiors: ID 1 (process 21561)
|
Bound inferiors: ID 1 (process 21561)
|
* 1 hello
|
* 1 hello
|
|
|
Here we can see that no inferior is running the program `hello',
|
Here we can see that no inferior is running the program `hello',
|
while `process 21561' is running the program `goodbye'. On some
|
while `process 21561' is running the program `goodbye'. On some
|
targets, it is possible that multiple inferiors are bound to the
|
targets, it is possible that multiple inferiors are bound to the
|
same program space. The most common example is that of debugging
|
same program space. The most common example is that of debugging
|
both the parent and child processes of a `vfork' call. For
|
both the parent and child processes of a `vfork' call. For
|
example,
|
example,
|
|
|
(gdb) maint info program-spaces
|
(gdb) maint info program-spaces
|
Id Executable
|
Id Executable
|
* 1 vfork-test
|
* 1 vfork-test
|
Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
|
Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
|
|
|
Here, both inferior 2 and inferior 1 are running in the same
|
Here, both inferior 2 and inferior 1 are running in the same
|
program space as a result of inferior 1 having executed a `vfork'
|
program space as a result of inferior 1 having executed a `vfork'
|
call.
|
call.
|
|
|
|
|
File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running
|
File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running
|
|
|
4.10 Debugging Programs with Multiple Threads
|
4.10 Debugging Programs with Multiple Threads
|
=============================================
|
=============================================
|
|
|
In some operating systems, such as HP-UX and Solaris, a single program
|
In some operating systems, such as HP-UX and Solaris, a single program
|
may have more than one "thread" of execution. The precise semantics of
|
may have more than one "thread" of execution. The precise semantics of
|
threads differ from one operating system to another, but in general the
|
threads differ from one operating system to another, but in general the
|
threads of a single program are akin to multiple processes--except that
|
threads of a single program are akin to multiple processes--except that
|
they share one address space (that is, they can all examine and modify
|
they share one address space (that is, they can all examine and modify
|
the same variables). On the other hand, each thread has its own
|
the same variables). On the other hand, each thread has its own
|
registers and execution stack, and perhaps private memory.
|
registers and execution stack, and perhaps private memory.
|
|
|
GDB provides these facilities for debugging multi-thread programs:
|
GDB provides these facilities for debugging multi-thread programs:
|
|
|
* automatic notification of new threads
|
* automatic notification of new threads
|
|
|
* `thread THREADNO', a command to switch among threads
|
* `thread THREADNO', a command to switch among threads
|
|
|
* `info threads', a command to inquire about existing threads
|
* `info threads', a command to inquire about existing threads
|
|
|
* `thread apply [THREADNO] [ALL] ARGS', a command to apply a command
|
* `thread apply [THREADNO] [ALL] ARGS', a command to apply a command
|
to a list of threads
|
to a list of threads
|
|
|
* thread-specific breakpoints
|
* thread-specific breakpoints
|
|
|
* `set print thread-events', which controls printing of messages on
|
* `set print thread-events', which controls printing of messages on
|
thread start and exit.
|
thread start and exit.
|
|
|
* `set libthread-db-search-path PATH', which lets the user specify
|
* `set libthread-db-search-path PATH', which lets the user specify
|
which `libthread_db' to use if the default choice isn't compatible
|
which `libthread_db' to use if the default choice isn't compatible
|
with the program.
|
with the program.
|
|
|
_Warning:_ These facilities are not yet available on every GDB
|
_Warning:_ These facilities are not yet available on every GDB
|
configuration where the operating system supports threads. If
|
configuration where the operating system supports threads. If
|
your GDB does not support threads, these commands have no effect.
|
your GDB does not support threads, these commands have no effect.
|
For example, a system without thread support shows no output from
|
For example, a system without thread support shows no output from
|
`info threads', and always rejects the `thread' command, like this:
|
`info threads', and always rejects the `thread' command, like this:
|
|
|
(gdb) info threads
|
(gdb) info threads
|
(gdb) thread 1
|
(gdb) thread 1
|
Thread ID 1 not known. Use the "info threads" command to
|
Thread ID 1 not known. Use the "info threads" command to
|
see the IDs of currently known threads.
|
see the IDs of currently known threads.
|
|
|
The GDB thread debugging facility allows you to observe all threads
|
The GDB thread debugging facility allows you to observe all threads
|
while your program runs--but whenever GDB takes control, one thread in
|
while your program runs--but whenever GDB takes control, one thread in
|
particular is always the focus of debugging. This thread is called the
|
particular is always the focus of debugging. This thread is called the
|
"current thread". Debugging commands show program information from the
|
"current thread". Debugging commands show program information from the
|
perspective of the current thread.
|
perspective of the current thread.
|
|
|
Whenever GDB detects a new thread in your program, it displays the
|
Whenever GDB detects a new thread in your program, it displays the
|
target system's identification for the thread with a message in the
|
target system's identification for the thread with a message in the
|
form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies
|
form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies
|
depending on the particular system. For example, on GNU/Linux, you
|
depending on the particular system. For example, on GNU/Linux, you
|
might see
|
might see
|
|
|
[New Thread 46912507313328 (LWP 25582)]
|
[New Thread 46912507313328 (LWP 25582)]
|
|
|
when GDB notices a new thread. In contrast, on an SGI system, the
|
when GDB notices a new thread. In contrast, on an SGI system, the
|
SYSTAG is simply something like `process 368', with no further
|
SYSTAG is simply something like `process 368', with no further
|
qualifier.
|
qualifier.
|
|
|
For debugging purposes, GDB associates its own thread number--always
|
For debugging purposes, GDB associates its own thread number--always
|
a single integer--with each thread in your program.
|
a single integer--with each thread in your program.
|
|
|
`info threads'
|
`info threads'
|
Display a summary of all threads currently in your program. GDB
|
Display a summary of all threads currently in your program. GDB
|
displays for each thread (in this order):
|
displays for each thread (in this order):
|
|
|
1. the thread number assigned by GDB
|
1. the thread number assigned by GDB
|
|
|
2. the target system's thread identifier (SYSTAG)
|
2. the target system's thread identifier (SYSTAG)
|
|
|
3. the current stack frame summary for that thread
|
3. the current stack frame summary for that thread
|
|
|
An asterisk `*' to the left of the GDB thread number indicates the
|
An asterisk `*' to the left of the GDB thread number indicates the
|
current thread.
|
current thread.
|
|
|
For example,
|
For example,
|
|
|
(gdb) info threads
|
(gdb) info threads
|
3 process 35 thread 27 0x34e5 in sigpause ()
|
3 process 35 thread 27 0x34e5 in sigpause ()
|
2 process 35 thread 23 0x34e5 in sigpause ()
|
2 process 35 thread 23 0x34e5 in sigpause ()
|
* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
|
* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
|
at threadtest.c:68
|
at threadtest.c:68
|
|
|
On HP-UX systems:
|
On HP-UX systems:
|
|
|
For debugging purposes, GDB associates its own thread number--a
|
For debugging purposes, GDB associates its own thread number--a
|
small integer assigned in thread-creation order--with each thread in
|
small integer assigned in thread-creation order--with each thread in
|
your program.
|
your program.
|
|
|
Whenever GDB detects a new thread in your program, it displays both
|
Whenever GDB detects a new thread in your program, it displays both
|
GDB's thread number and the target system's identification for the
|
GDB's thread number and the target system's identification for the
|
thread with a message in the form `[New SYSTAG]'. SYSTAG is a thread
|
thread with a message in the form `[New SYSTAG]'. SYSTAG is a thread
|
identifier whose form varies depending on the particular system. For
|
identifier whose form varies depending on the particular system. For
|
example, on HP-UX, you see
|
example, on HP-UX, you see
|
|
|
[New thread 2 (system thread 26594)]
|
[New thread 2 (system thread 26594)]
|
|
|
when GDB notices a new thread.
|
when GDB notices a new thread.
|
|
|
`info threads'
|
`info threads'
|
Display a summary of all threads currently in your program. GDB
|
Display a summary of all threads currently in your program. GDB
|
displays for each thread (in this order):
|
displays for each thread (in this order):
|
|
|
1. the thread number assigned by GDB
|
1. the thread number assigned by GDB
|
|
|
2. the target system's thread identifier (SYSTAG)
|
2. the target system's thread identifier (SYSTAG)
|
|
|
3. the current stack frame summary for that thread
|
3. the current stack frame summary for that thread
|
|
|
An asterisk `*' to the left of the GDB thread number indicates the
|
An asterisk `*' to the left of the GDB thread number indicates the
|
current thread.
|
current thread.
|
|
|
For example,
|
For example,
|
|
|
(gdb) info threads
|
(gdb) info threads
|
* 3 system thread 26607 worker (wptr=0x7b09c318 "@") \
|
* 3 system thread 26607 worker (wptr=0x7b09c318 "@") \
|
|
|
at quicksort.c:137
|
at quicksort.c:137
|
2 system thread 26606 0x7b0030d8 in __ksleep () \
|
2 system thread 26606 0x7b0030d8 in __ksleep () \
|
|
|
from /usr/lib/libc.2
|
from /usr/lib/libc.2
|
1 system thread 27905 0x7b003498 in _brk () \
|
1 system thread 27905 0x7b003498 in _brk () \
|
|
|
from /usr/lib/libc.2
|
from /usr/lib/libc.2
|
|
|
On Solaris, you can display more information about user threads with
|
On Solaris, you can display more information about user threads with
|
a Solaris-specific command:
|
a Solaris-specific command:
|
|
|
`maint info sol-threads'
|
`maint info sol-threads'
|
Display info on Solaris user threads.
|
Display info on Solaris user threads.
|
|
|
`thread THREADNO'
|
`thread THREADNO'
|
Make thread number THREADNO the current thread. The command
|
Make thread number THREADNO the current thread. The command
|
argument THREADNO is the internal GDB thread number, as shown in
|
argument THREADNO is the internal GDB thread number, as shown in
|
the first field of the `info threads' display. GDB responds by
|
the first field of the `info threads' display. GDB responds by
|
displaying the system identifier of the thread you selected, and
|
displaying the system identifier of the thread you selected, and
|
its current stack frame summary:
|
its current stack frame summary:
|
|
|
(gdb) thread 2
|
(gdb) thread 2
|
[Switching to process 35 thread 23]
|
[Switching to process 35 thread 23]
|
0x34e5 in sigpause ()
|
0x34e5 in sigpause ()
|
|
|
As with the `[New ...]' message, the form of the text after
|
As with the `[New ...]' message, the form of the text after
|
`Switching to' depends on your system's conventions for identifying
|
`Switching to' depends on your system's conventions for identifying
|
threads.
|
threads.
|
|
|
The debugger convenience variable `$_thread' contains the number
|
The debugger convenience variable `$_thread' contains the number
|
of the current thread. You may find this useful in writing
|
of the current thread. You may find this useful in writing
|
breakpoint conditional expressions, command scripts, and so forth.
|
breakpoint conditional expressions, command scripts, and so forth.
|
See *Note Convenience Variables: Convenience Vars, for general
|
See *Note Convenience Variables: Convenience Vars, for general
|
information on convenience variables.
|
information on convenience variables.
|
|
|
`thread apply [THREADNO] [ALL] COMMAND'
|
`thread apply [THREADNO] [ALL] COMMAND'
|
The `thread apply' command allows you to apply the named COMMAND
|
The `thread apply' command allows you to apply the named COMMAND
|
to one or more threads. Specify the numbers of the threads that
|
to one or more threads. Specify the numbers of the threads that
|
you want affected with the command argument THREADNO. It can be a
|
you want affected with the command argument THREADNO. It can be a
|
single thread number, one of the numbers shown in the first field
|
single thread number, one of the numbers shown in the first field
|
of the `info threads' display; or it could be a range of thread
|
of the `info threads' display; or it could be a range of thread
|
numbers, as in `2-4'. To apply a command to all threads, type
|
numbers, as in `2-4'. To apply a command to all threads, type
|
`thread apply all COMMAND'.
|
`thread apply all COMMAND'.
|
|
|
`set print thread-events'
|
`set print thread-events'
|
`set print thread-events on'
|
`set print thread-events on'
|
`set print thread-events off'
|
`set print thread-events off'
|
The `set print thread-events' command allows you to enable or
|
The `set print thread-events' command allows you to enable or
|
disable printing of messages when GDB notices that new threads have
|
disable printing of messages when GDB notices that new threads have
|
started or that threads have exited. By default, these messages
|
started or that threads have exited. By default, these messages
|
will be printed if detection of these events is supported by the
|
will be printed if detection of these events is supported by the
|
target. Note that these messages cannot be disabled on all
|
target. Note that these messages cannot be disabled on all
|
targets.
|
targets.
|
|
|
`show print thread-events'
|
`show print thread-events'
|
Show whether messages will be printed when GDB detects that threads
|
Show whether messages will be printed when GDB detects that threads
|
have started and exited.
|
have started and exited.
|
|
|
*Note Stopping and Starting Multi-thread Programs: Thread Stops, for
|
*Note Stopping and Starting Multi-thread Programs: Thread Stops, for
|
more information about how GDB behaves when you stop and start programs
|
more information about how GDB behaves when you stop and start programs
|
with multiple threads.
|
with multiple threads.
|
|
|
*Note Setting Watchpoints: Set Watchpoints, for information about
|
*Note Setting Watchpoints: Set Watchpoints, for information about
|
watchpoints in programs with multiple threads.
|
watchpoints in programs with multiple threads.
|
|
|
`set libthread-db-search-path [PATH]'
|
`set libthread-db-search-path [PATH]'
|
If this variable is set, PATH is a colon-separated list of
|
If this variable is set, PATH is a colon-separated list of
|
directories GDB will use to search for `libthread_db'. If you
|
directories GDB will use to search for `libthread_db'. If you
|
omit PATH, `libthread-db-search-path' will be reset to an empty
|
omit PATH, `libthread-db-search-path' will be reset to an empty
|
list.
|
list.
|
|
|
On GNU/Linux and Solaris systems, GDB uses a "helper"
|
On GNU/Linux and Solaris systems, GDB uses a "helper"
|
`libthread_db' library to obtain information about threads in the
|
`libthread_db' library to obtain information about threads in the
|
inferior process. GDB will use `libthread-db-search-path' to find
|
inferior process. GDB will use `libthread-db-search-path' to find
|
`libthread_db'. If that fails, GDB will continue with default
|
`libthread_db'. If that fails, GDB will continue with default
|
system shared library directories, and finally the directory from
|
system shared library directories, and finally the directory from
|
which `libpthread' was loaded in the inferior process.
|
which `libpthread' was loaded in the inferior process.
|
|
|
For any `libthread_db' library GDB finds in above directories, GDB
|
For any `libthread_db' library GDB finds in above directories, GDB
|
attempts to initialize it with the current inferior process. If
|
attempts to initialize it with the current inferior process. If
|
this initialization fails (which could happen because of a version
|
this initialization fails (which could happen because of a version
|
mismatch between `libthread_db' and `libpthread'), GDB will unload
|
mismatch between `libthread_db' and `libpthread'), GDB will unload
|
`libthread_db', and continue with the next directory. If none of
|
`libthread_db', and continue with the next directory. If none of
|
`libthread_db' libraries initialize successfully, GDB will issue a
|
`libthread_db' libraries initialize successfully, GDB will issue a
|
warning and thread debugging will be disabled.
|
warning and thread debugging will be disabled.
|
|
|
Setting `libthread-db-search-path' is currently implemented only
|
Setting `libthread-db-search-path' is currently implemented only
|
on some platforms.
|
on some platforms.
|
|
|
`show libthread-db-search-path'
|
`show libthread-db-search-path'
|
Display current libthread_db search path.
|
Display current libthread_db search path.
|
|
|
|
|
File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running
|
File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running
|
|
|
4.11 Debugging Forks
|
4.11 Debugging Forks
|
====================
|
====================
|
|
|
On most systems, GDB has no special support for debugging programs
|
On most systems, GDB has no special support for debugging programs
|
which create additional processes using the `fork' function. When a
|
which create additional processes using the `fork' function. When a
|
program forks, GDB will continue to debug the parent process and the
|
program forks, GDB will continue to debug the parent process and the
|
child process will run unimpeded. If you have set a breakpoint in any
|
child process will run unimpeded. If you have set a breakpoint in any
|
code which the child then executes, the child will get a `SIGTRAP'
|
code which the child then executes, the child will get a `SIGTRAP'
|
signal which (unless it catches the signal) will cause it to terminate.
|
signal which (unless it catches the signal) will cause it to terminate.
|
|
|
However, if you want to debug the child process there is a workaround
|
However, if you want to debug the child process there is a workaround
|
which isn't too painful. Put a call to `sleep' in the code which the
|
which isn't too painful. Put a call to `sleep' in the code which the
|
child process executes after the fork. It may be useful to sleep only
|
child process executes after the fork. It may be useful to sleep only
|
if a certain environment variable is set, or a certain file exists, so
|
if a certain environment variable is set, or a certain file exists, so
|
that the delay need not occur when you don't want to run GDB on the
|
that the delay need not occur when you don't want to run GDB on the
|
child. While the child is sleeping, use the `ps' program to get its
|
child. While the child is sleeping, use the `ps' program to get its
|
process ID. Then tell GDB (a new invocation of GDB if you are also
|
process ID. Then tell GDB (a new invocation of GDB if you are also
|
debugging the parent process) to attach to the child process (*note
|
debugging the parent process) to attach to the child process (*note
|
Attach::). From that point on you can debug the child process just
|
Attach::). From that point on you can debug the child process just
|
like any other process which you attached to.
|
like any other process which you attached to.
|
|
|
On some systems, GDB provides support for debugging programs that
|
On some systems, GDB provides support for debugging programs that
|
create additional processes using the `fork' or `vfork' functions.
|
create additional processes using the `fork' or `vfork' functions.
|
Currently, the only platforms with this feature are HP-UX (11.x and
|
Currently, the only platforms with this feature are HP-UX (11.x and
|
later only?) and GNU/Linux (kernel version 2.5.60 and later).
|
later only?) and GNU/Linux (kernel version 2.5.60 and later).
|
|
|
By default, when a program forks, GDB will continue to debug the
|
By default, when a program forks, GDB will continue to debug the
|
parent process and the child process will run unimpeded.
|
parent process and the child process will run unimpeded.
|
|
|
If you want to follow the child process instead of the parent
|
If you want to follow the child process instead of the parent
|
process, use the command `set follow-fork-mode'.
|
process, use the command `set follow-fork-mode'.
|
|
|
`set follow-fork-mode MODE'
|
`set follow-fork-mode MODE'
|
Set the debugger response to a program call of `fork' or `vfork'.
|
Set the debugger response to a program call of `fork' or `vfork'.
|
A call to `fork' or `vfork' creates a new process. The MODE
|
A call to `fork' or `vfork' creates a new process. The MODE
|
argument can be:
|
argument can be:
|
|
|
`parent'
|
`parent'
|
The original process is debugged after a fork. The child
|
The original process is debugged after a fork. The child
|
process runs unimpeded. This is the default.
|
process runs unimpeded. This is the default.
|
|
|
`child'
|
`child'
|
The new process is debugged after a fork. The parent process
|
The new process is debugged after a fork. The parent process
|
runs unimpeded.
|
runs unimpeded.
|
|
|
|
|
`show follow-fork-mode'
|
`show follow-fork-mode'
|
Display the current debugger response to a `fork' or `vfork' call.
|
Display the current debugger response to a `fork' or `vfork' call.
|
|
|
On Linux, if you want to debug both the parent and child processes,
|
On Linux, if you want to debug both the parent and child processes,
|
use the command `set detach-on-fork'.
|
use the command `set detach-on-fork'.
|
|
|
`set detach-on-fork MODE'
|
`set detach-on-fork MODE'
|
Tells gdb whether to detach one of the processes after a fork, or
|
Tells gdb whether to detach one of the processes after a fork, or
|
retain debugger control over them both.
|
retain debugger control over them both.
|
|
|
`on'
|
`on'
|
The child process (or parent process, depending on the value
|
The child process (or parent process, depending on the value
|
of `follow-fork-mode') will be detached and allowed to run
|
of `follow-fork-mode') will be detached and allowed to run
|
independently. This is the default.
|
independently. This is the default.
|
|
|
`off'
|
`off'
|
Both processes will be held under the control of GDB. One
|
Both processes will be held under the control of GDB. One
|
process (child or parent, depending on the value of
|
process (child or parent, depending on the value of
|
`follow-fork-mode') is debugged as usual, while the other is
|
`follow-fork-mode') is debugged as usual, while the other is
|
held suspended.
|
held suspended.
|
|
|
|
|
`show detach-on-fork'
|
`show detach-on-fork'
|
Show whether detach-on-fork mode is on/off.
|
Show whether detach-on-fork mode is on/off.
|
|
|
If you choose to set `detach-on-fork' mode off, then GDB will retain
|
If you choose to set `detach-on-fork' mode off, then GDB will retain
|
control of all forked processes (including nested forks). You can list
|
control of all forked processes (including nested forks). You can list
|
the forked processes under the control of GDB by using the
|
the forked processes under the control of GDB by using the
|
`info inferiors' command, and switch from one fork to another by using
|
`info inferiors' command, and switch from one fork to another by using
|
the `inferior' command (*note Debugging Multiple Inferiors and
|
the `inferior' command (*note Debugging Multiple Inferiors and
|
Programs: Inferiors and Programs.).
|
Programs: Inferiors and Programs.).
|
|
|
To quit debugging one of the forked processes, you can either detach
|
To quit debugging one of the forked processes, you can either detach
|
from it by using the `detach inferior' command (allowing it to run
|
from it by using the `detach inferior' command (allowing it to run
|
independently), or kill it using the `kill inferior' command. *Note
|
independently), or kill it using the `kill inferior' command. *Note
|
Debugging Multiple Inferiors and Programs: Inferiors and Programs.
|
Debugging Multiple Inferiors and Programs: Inferiors and Programs.
|
|
|
If you ask to debug a child process and a `vfork' is followed by an
|
If you ask to debug a child process and a `vfork' is followed by an
|
`exec', GDB executes the new target up to the first breakpoint in the
|
`exec', GDB executes the new target up to the first breakpoint in the
|
new target. If you have a breakpoint set on `main' in your original
|
new target. If you have a breakpoint set on `main' in your original
|
program, the breakpoint will also be set on the child process's `main'.
|
program, the breakpoint will also be set on the child process's `main'.
|
|
|
On some systems, when a child process is spawned by `vfork', you
|
On some systems, when a child process is spawned by `vfork', you
|
cannot debug the child or parent until an `exec' call completes.
|
cannot debug the child or parent until an `exec' call completes.
|
|
|
If you issue a `run' command to GDB after an `exec' call executes,
|
If you issue a `run' command to GDB after an `exec' call executes,
|
the new target restarts. To restart the parent process, use the `file'
|
the new target restarts. To restart the parent process, use the `file'
|
command with the parent executable name as its argument. By default,
|
command with the parent executable name as its argument. By default,
|
after an `exec' call executes, GDB discards the symbols of the previous
|
after an `exec' call executes, GDB discards the symbols of the previous
|
executable image. You can change this behaviour with the
|
executable image. You can change this behaviour with the
|
`set follow-exec-mode' command.
|
`set follow-exec-mode' command.
|
|
|
`set follow-exec-mode MODE'
|
`set follow-exec-mode MODE'
|
Set debugger response to a program call of `exec'. An `exec' call
|
Set debugger response to a program call of `exec'. An `exec' call
|
replaces the program image of a process.
|
replaces the program image of a process.
|
|
|
`follow-exec-mode' can be:
|
`follow-exec-mode' can be:
|
|
|
`new'
|
`new'
|
GDB creates a new inferior and rebinds the process to this
|
GDB creates a new inferior and rebinds the process to this
|
new inferior. The program the process was running before the
|
new inferior. The program the process was running before the
|
`exec' call can be restarted afterwards by restarting the
|
`exec' call can be restarted afterwards by restarting the
|
original inferior.
|
original inferior.
|
|
|
For example:
|
For example:
|
|
|
(gdb) info inferiors
|
(gdb) info inferiors
|
(gdb) info inferior
|
(gdb) info inferior
|
Id Description Executable
|
Id Description Executable
|
* 1 prog1
|
* 1 prog1
|
(gdb) run
|
(gdb) run
|
process 12020 is executing new program: prog2
|
process 12020 is executing new program: prog2
|
Program exited normally.
|
Program exited normally.
|
(gdb) info inferiors
|
(gdb) info inferiors
|
Id Description Executable
|
Id Description Executable
|
* 2 prog2
|
* 2 prog2
|
1 prog1
|
1 prog1
|
|
|
`same'
|
`same'
|
GDB keeps the process bound to the same inferior. The new
|
GDB keeps the process bound to the same inferior. The new
|
executable image replaces the previous executable loaded in
|
executable image replaces the previous executable loaded in
|
the inferior. Restarting the inferior after the `exec' call,
|
the inferior. Restarting the inferior after the `exec' call,
|
with e.g., the `run' command, restarts the executable the
|
with e.g., the `run' command, restarts the executable the
|
process was running after the `exec' call. This is the
|
process was running after the `exec' call. This is the
|
default mode.
|
default mode.
|
|
|
For example:
|
For example:
|
|
|
(gdb) info inferiors
|
(gdb) info inferiors
|
Id Description Executable
|
Id Description Executable
|
* 1 prog1
|
* 1 prog1
|
(gdb) run
|
(gdb) run
|
process 12020 is executing new program: prog2
|
process 12020 is executing new program: prog2
|
Program exited normally.
|
Program exited normally.
|
(gdb) info inferiors
|
(gdb) info inferiors
|
Id Description Executable
|
Id Description Executable
|
* 1 prog2
|
* 1 prog2
|
|
|
|
|
You can use the `catch' command to make GDB stop whenever a `fork',
|
You can use the `catch' command to make GDB stop whenever a `fork',
|
`vfork', or `exec' call is made. *Note Setting Catchpoints: Set
|
`vfork', or `exec' call is made. *Note Setting Catchpoints: Set
|
Catchpoints.
|
Catchpoints.
|
|
|
|
|
File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running
|
File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running
|
|
|
4.12 Setting a _Bookmark_ to Return to Later
|
4.12 Setting a _Bookmark_ to Return to Later
|
============================================
|
============================================
|
|
|
On certain operating systems(1), GDB is able to save a "snapshot" of a
|
On certain operating systems(1), GDB is able to save a "snapshot" of a
|
program's state, called a "checkpoint", and come back to it later.
|
program's state, called a "checkpoint", and come back to it later.
|
|
|
Returning to a checkpoint effectively undoes everything that has
|
Returning to a checkpoint effectively undoes everything that has
|
happened in the program since the `checkpoint' was saved. This
|
happened in the program since the `checkpoint' was saved. This
|
includes changes in memory, registers, and even (within some limits)
|
includes changes in memory, registers, and even (within some limits)
|
system state. Effectively, it is like going back in time to the moment
|
system state. Effectively, it is like going back in time to the moment
|
when the checkpoint was saved.
|
when the checkpoint was saved.
|
|
|
Thus, if you're stepping thru a program and you think you're getting
|
Thus, if you're stepping thru a program and you think you're getting
|
close to the point where things go wrong, you can save a checkpoint.
|
close to the point where things go wrong, you can save a checkpoint.
|
Then, if you accidentally go too far and miss the critical statement,
|
Then, if you accidentally go too far and miss the critical statement,
|
instead of having to restart your program from the beginning, you can
|
instead of having to restart your program from the beginning, you can
|
just go back to the checkpoint and start again from there.
|
just go back to the checkpoint and start again from there.
|
|
|
This can be especially useful if it takes a lot of time or steps to
|
This can be especially useful if it takes a lot of time or steps to
|
reach the point where you think the bug occurs.
|
reach the point where you think the bug occurs.
|
|
|
To use the `checkpoint'/`restart' method of debugging:
|
To use the `checkpoint'/`restart' method of debugging:
|
|
|
`checkpoint'
|
`checkpoint'
|
Save a snapshot of the debugged program's current execution state.
|
Save a snapshot of the debugged program's current execution state.
|
The `checkpoint' command takes no arguments, but each checkpoint
|
The `checkpoint' command takes no arguments, but each checkpoint
|
is assigned a small integer id, similar to a breakpoint id.
|
is assigned a small integer id, similar to a breakpoint id.
|
|
|
`info checkpoints'
|
`info checkpoints'
|
List the checkpoints that have been saved in the current debugging
|
List the checkpoints that have been saved in the current debugging
|
session. For each checkpoint, the following information will be
|
session. For each checkpoint, the following information will be
|
listed:
|
listed:
|
|
|
`Checkpoint ID'
|
`Checkpoint ID'
|
|
|
`Process ID'
|
`Process ID'
|
|
|
`Code Address'
|
`Code Address'
|
|
|
`Source line, or label'
|
`Source line, or label'
|
|
|
`restart CHECKPOINT-ID'
|
`restart CHECKPOINT-ID'
|
Restore the program state that was saved as checkpoint number
|
Restore the program state that was saved as checkpoint number
|
CHECKPOINT-ID. All program variables, registers, stack frames
|
CHECKPOINT-ID. All program variables, registers, stack frames
|
etc. will be returned to the values that they had when the
|
etc. will be returned to the values that they had when the
|
checkpoint was saved. In essence, gdb will "wind back the clock"
|
checkpoint was saved. In essence, gdb will "wind back the clock"
|
to the point in time when the checkpoint was saved.
|
to the point in time when the checkpoint was saved.
|
|
|
Note that breakpoints, GDB variables, command history etc. are
|
Note that breakpoints, GDB variables, command history etc. are
|
not affected by restoring a checkpoint. In general, a checkpoint
|
not affected by restoring a checkpoint. In general, a checkpoint
|
only restores things that reside in the program being debugged,
|
only restores things that reside in the program being debugged,
|
not in the debugger.
|
not in the debugger.
|
|
|
`delete checkpoint CHECKPOINT-ID'
|
`delete checkpoint CHECKPOINT-ID'
|
Delete the previously-saved checkpoint identified by CHECKPOINT-ID.
|
Delete the previously-saved checkpoint identified by CHECKPOINT-ID.
|
|
|
|
|
Returning to a previously saved checkpoint will restore the user
|
Returning to a previously saved checkpoint will restore the user
|
state of the program being debugged, plus a significant subset of the
|
state of the program being debugged, plus a significant subset of the
|
system (OS) state, including file pointers. It won't "un-write" data
|
system (OS) state, including file pointers. It won't "un-write" data
|
from a file, but it will rewind the file pointer to the previous
|
from a file, but it will rewind the file pointer to the previous
|
location, so that the previously written data can be overwritten. For
|
location, so that the previously written data can be overwritten. For
|
files opened in read mode, the pointer will also be restored so that the
|
files opened in read mode, the pointer will also be restored so that the
|
previously read data can be read again.
|
previously read data can be read again.
|
|
|
Of course, characters that have been sent to a printer (or other
|
Of course, characters that have been sent to a printer (or other
|
external device) cannot be "snatched back", and characters received
|
external device) cannot be "snatched back", and characters received
|
from eg. a serial device can be removed from internal program buffers,
|
from eg. a serial device can be removed from internal program buffers,
|
but they cannot be "pushed back" into the serial pipeline, ready to be
|
but they cannot be "pushed back" into the serial pipeline, ready to be
|
received again. Similarly, the actual contents of files that have been
|
received again. Similarly, the actual contents of files that have been
|
changed cannot be restored (at this time).
|
changed cannot be restored (at this time).
|
|
|
However, within those constraints, you actually can "rewind" your
|
However, within those constraints, you actually can "rewind" your
|
program to a previously saved point in time, and begin debugging it
|
program to a previously saved point in time, and begin debugging it
|
again -- and you can change the course of events so as to debug a
|
again -- and you can change the course of events so as to debug a
|
different execution path this time.
|
different execution path this time.
|
|
|
Finally, there is one bit of internal program state that will be
|
Finally, there is one bit of internal program state that will be
|
different when you return to a checkpoint -- the program's process id.
|
different when you return to a checkpoint -- the program's process id.
|
Each checkpoint will have a unique process id (or PID), and each will
|
Each checkpoint will have a unique process id (or PID), and each will
|
be different from the program's original PID. If your program has
|
be different from the program's original PID. If your program has
|
saved a local copy of its process id, this could potentially pose a
|
saved a local copy of its process id, this could potentially pose a
|
problem.
|
problem.
|
|
|
4.12.1 A Non-obvious Benefit of Using Checkpoints
|
4.12.1 A Non-obvious Benefit of Using Checkpoints
|
-------------------------------------------------
|
-------------------------------------------------
|
|
|
On some systems such as GNU/Linux, address space randomization is
|
On some systems such as GNU/Linux, address space randomization is
|
performed on new processes for security reasons. This makes it
|
performed on new processes for security reasons. This makes it
|
difficult or impossible to set a breakpoint, or watchpoint, on an
|
difficult or impossible to set a breakpoint, or watchpoint, on an
|
absolute address if you have to restart the program, since the absolute
|
absolute address if you have to restart the program, since the absolute
|
location of a symbol will change from one execution to the next.
|
location of a symbol will change from one execution to the next.
|
|
|
A checkpoint, however, is an _identical_ copy of a process.
|
A checkpoint, however, is an _identical_ copy of a process.
|
Therefore if you create a checkpoint at (eg.) the start of main, and
|
Therefore if you create a checkpoint at (eg.) the start of main, and
|
simply return to that checkpoint instead of restarting the process, you
|
simply return to that checkpoint instead of restarting the process, you
|
can avoid the effects of address randomization and your symbols will
|
can avoid the effects of address randomization and your symbols will
|
all stay in the same place.
|
all stay in the same place.
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) Currently, only GNU/Linux.
|
(1) Currently, only GNU/Linux.
|
|
|
|
|
File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top
|
File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top
|
|
|
5 Stopping and Continuing
|
5 Stopping and Continuing
|
*************************
|
*************************
|
|
|
The principal purposes of using a debugger are so that you can stop your
|
The principal purposes of using a debugger are so that you can stop your
|
program before it terminates; or so that, if your program runs into
|
program before it terminates; or so that, if your program runs into
|
trouble, you can investigate and find out why.
|
trouble, you can investigate and find out why.
|
|
|
Inside GDB, your program may stop for any of several reasons, such
|
Inside GDB, your program may stop for any of several reasons, such
|
as a signal, a breakpoint, or reaching a new line after a GDB command
|
as a signal, a breakpoint, or reaching a new line after a GDB command
|
such as `step'. You may then examine and change variables, set new
|
such as `step'. You may then examine and change variables, set new
|
breakpoints or remove old ones, and then continue execution. Usually,
|
breakpoints or remove old ones, and then continue execution. Usually,
|
the messages shown by GDB provide ample explanation of the status of
|
the messages shown by GDB provide ample explanation of the status of
|
your program--but you can also explicitly request this information at
|
your program--but you can also explicitly request this information at
|
any time.
|
any time.
|
|
|
`info program'
|
`info program'
|
Display information about the status of your program: whether it is
|
Display information about the status of your program: whether it is
|
running or not, what process it is, and why it stopped.
|
running or not, what process it is, and why it stopped.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Breakpoints:: Breakpoints, watchpoints, and catchpoints
|
* Breakpoints:: Breakpoints, watchpoints, and catchpoints
|
* Continuing and Stepping:: Resuming execution
|
* Continuing and Stepping:: Resuming execution
|
* Signals:: Signals
|
* Signals:: Signals
|
* Thread Stops:: Stopping and starting multi-thread programs
|
* Thread Stops:: Stopping and starting multi-thread programs
|
|
|
|
|
File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping
|
File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping
|
|
|
5.1 Breakpoints, Watchpoints, and Catchpoints
|
5.1 Breakpoints, Watchpoints, and Catchpoints
|
=============================================
|
=============================================
|
|
|
A "breakpoint" makes your program stop whenever a certain point in the
|
A "breakpoint" makes your program stop whenever a certain point in the
|
program is reached. For each breakpoint, you can add conditions to
|
program is reached. For each breakpoint, you can add conditions to
|
control in finer detail whether your program stops. You can set
|
control in finer detail whether your program stops. You can set
|
breakpoints with the `break' command and its variants (*note Setting
|
breakpoints with the `break' command and its variants (*note Setting
|
Breakpoints: Set Breaks.), to specify the place where your program
|
Breakpoints: Set Breaks.), to specify the place where your program
|
should stop by line number, function name or exact address in the
|
should stop by line number, function name or exact address in the
|
program.
|
program.
|
|
|
On some systems, you can set breakpoints in shared libraries before
|
On some systems, you can set breakpoints in shared libraries before
|
the executable is run. There is a minor limitation on HP-UX systems:
|
the executable is run. There is a minor limitation on HP-UX systems:
|
you must wait until the executable is run in order to set breakpoints
|
you must wait until the executable is run in order to set breakpoints
|
in shared library routines that are not called directly by the program
|
in shared library routines that are not called directly by the program
|
(for example, routines that are arguments in a `pthread_create' call).
|
(for example, routines that are arguments in a `pthread_create' call).
|
|
|
A "watchpoint" is a special breakpoint that stops your program when
|
A "watchpoint" is a special breakpoint that stops your program when
|
the value of an expression changes. The expression may be a value of a
|
the value of an expression changes. The expression may be a value of a
|
variable, or it could involve values of one or more variables combined
|
variable, or it could involve values of one or more variables combined
|
by operators, such as `a + b'. This is sometimes called "data
|
by operators, such as `a + b'. This is sometimes called "data
|
breakpoints". You must use a different command to set watchpoints
|
breakpoints". You must use a different command to set watchpoints
|
(*note Setting Watchpoints: Set Watchpoints.), but aside from that, you
|
(*note Setting Watchpoints: Set Watchpoints.), but aside from that, you
|
can manage a watchpoint like any other breakpoint: you enable, disable,
|
can manage a watchpoint like any other breakpoint: you enable, disable,
|
and delete both breakpoints and watchpoints using the same commands.
|
and delete both breakpoints and watchpoints using the same commands.
|
|
|
You can arrange to have values from your program displayed
|
You can arrange to have values from your program displayed
|
automatically whenever GDB stops at a breakpoint. *Note Automatic
|
automatically whenever GDB stops at a breakpoint. *Note Automatic
|
Display: Auto Display.
|
Display: Auto Display.
|
|
|
A "catchpoint" is another special breakpoint that stops your program
|
A "catchpoint" is another special breakpoint that stops your program
|
when a certain kind of event occurs, such as the throwing of a C++
|
when a certain kind of event occurs, such as the throwing of a C++
|
exception or the loading of a library. As with watchpoints, you use a
|
exception or the loading of a library. As with watchpoints, you use a
|
different command to set a catchpoint (*note Setting Catchpoints: Set
|
different command to set a catchpoint (*note Setting Catchpoints: Set
|
Catchpoints.), but aside from that, you can manage a catchpoint like any
|
Catchpoints.), but aside from that, you can manage a catchpoint like any
|
other breakpoint. (To stop when your program receives a signal, use the
|
other breakpoint. (To stop when your program receives a signal, use the
|
`handle' command; see *note Signals: Signals.)
|
`handle' command; see *note Signals: Signals.)
|
|
|
GDB assigns a number to each breakpoint, watchpoint, or catchpoint
|
GDB assigns a number to each breakpoint, watchpoint, or catchpoint
|
when you create it; these numbers are successive integers starting with
|
when you create it; these numbers are successive integers starting with
|
one. In many of the commands for controlling various features of
|
one. In many of the commands for controlling various features of
|
breakpoints you use the breakpoint number to say which breakpoint you
|
breakpoints you use the breakpoint number to say which breakpoint you
|
want to change. Each breakpoint may be "enabled" or "disabled"; if
|
want to change. Each breakpoint may be "enabled" or "disabled"; if
|
disabled, it has no effect on your program until you enable it again.
|
disabled, it has no effect on your program until you enable it again.
|
|
|
Some GDB commands accept a range of breakpoints on which to operate.
|
Some GDB commands accept a range of breakpoints on which to operate.
|
A breakpoint range is either a single breakpoint number, like `5', or
|
A breakpoint range is either a single breakpoint number, like `5', or
|
two such numbers, in increasing order, separated by a hyphen, like
|
two such numbers, in increasing order, separated by a hyphen, like
|
`5-7'. When a breakpoint range is given to a command, all breakpoints
|
`5-7'. When a breakpoint range is given to a command, all breakpoints
|
in that range are operated on.
|
in that range are operated on.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Set Breaks:: Setting breakpoints
|
* Set Breaks:: Setting breakpoints
|
* Set Watchpoints:: Setting watchpoints
|
* Set Watchpoints:: Setting watchpoints
|
* Set Catchpoints:: Setting catchpoints
|
* Set Catchpoints:: Setting catchpoints
|
* Delete Breaks:: Deleting breakpoints
|
* Delete Breaks:: Deleting breakpoints
|
* Disabling:: Disabling breakpoints
|
* Disabling:: Disabling breakpoints
|
* Conditions:: Break conditions
|
* Conditions:: Break conditions
|
* Break Commands:: Breakpoint command lists
|
* Break Commands:: Breakpoint command lists
|
* Save Breakpoints:: How to save breakpoints in a file
|
* Save Breakpoints:: How to save breakpoints in a file
|
* Error in Breakpoints:: ``Cannot insert breakpoints''
|
* Error in Breakpoints:: ``Cannot insert breakpoints''
|
* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
|
* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
|
|
|
|
|
File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints
|
File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints
|
|
|
5.1.1 Setting Breakpoints
|
5.1.1 Setting Breakpoints
|
-------------------------
|
-------------------------
|
|
|
Breakpoints are set with the `break' command (abbreviated `b'). The
|
Breakpoints are set with the `break' command (abbreviated `b'). The
|
debugger convenience variable `$bpnum' records the number of the
|
debugger convenience variable `$bpnum' records the number of the
|
breakpoint you've set most recently; see *note Convenience Variables:
|
breakpoint you've set most recently; see *note Convenience Variables:
|
Convenience Vars, for a discussion of what you can do with convenience
|
Convenience Vars, for a discussion of what you can do with convenience
|
variables.
|
variables.
|
|
|
`break LOCATION'
|
`break LOCATION'
|
Set a breakpoint at the given LOCATION, which can specify a
|
Set a breakpoint at the given LOCATION, which can specify a
|
function name, a line number, or an address of an instruction.
|
function name, a line number, or an address of an instruction.
|
(*Note Specify Location::, for a list of all the possible ways to
|
(*Note Specify Location::, for a list of all the possible ways to
|
specify a LOCATION.) The breakpoint will stop your program just
|
specify a LOCATION.) The breakpoint will stop your program just
|
before it executes any of the code in the specified LOCATION.
|
before it executes any of the code in the specified LOCATION.
|
|
|
When using source languages that permit overloading of symbols,
|
When using source languages that permit overloading of symbols,
|
such as C++, a function name may refer to more than one possible
|
such as C++, a function name may refer to more than one possible
|
place to break. *Note Ambiguous Expressions: Ambiguous
|
place to break. *Note Ambiguous Expressions: Ambiguous
|
Expressions, for a discussion of that situation.
|
Expressions, for a discussion of that situation.
|
|
|
It is also possible to insert a breakpoint that will stop the
|
It is also possible to insert a breakpoint that will stop the
|
program only if a specific thread (*note Thread-Specific
|
program only if a specific thread (*note Thread-Specific
|
Breakpoints::) or a specific task (*note Ada Tasks::) hits that
|
Breakpoints::) or a specific task (*note Ada Tasks::) hits that
|
breakpoint.
|
breakpoint.
|
|
|
`break'
|
`break'
|
When called without any arguments, `break' sets a breakpoint at
|
When called without any arguments, `break' sets a breakpoint at
|
the next instruction to be executed in the selected stack frame
|
the next instruction to be executed in the selected stack frame
|
(*note Examining the Stack: Stack.). In any selected frame but the
|
(*note Examining the Stack: Stack.). In any selected frame but the
|
innermost, this makes your program stop as soon as control returns
|
innermost, this makes your program stop as soon as control returns
|
to that frame. This is similar to the effect of a `finish'
|
to that frame. This is similar to the effect of a `finish'
|
command in the frame inside the selected frame--except that
|
command in the frame inside the selected frame--except that
|
`finish' does not leave an active breakpoint. If you use `break'
|
`finish' does not leave an active breakpoint. If you use `break'
|
without an argument in the innermost frame, GDB stops the next
|
without an argument in the innermost frame, GDB stops the next
|
time it reaches the current location; this may be useful inside
|
time it reaches the current location; this may be useful inside
|
loops.
|
loops.
|
|
|
GDB normally ignores breakpoints when it resumes execution, until
|
GDB normally ignores breakpoints when it resumes execution, until
|
at least one instruction has been executed. If it did not do
|
at least one instruction has been executed. If it did not do
|
this, you would be unable to proceed past a breakpoint without
|
this, you would be unable to proceed past a breakpoint without
|
first disabling the breakpoint. This rule applies whether or not
|
first disabling the breakpoint. This rule applies whether or not
|
the breakpoint already existed when your program stopped.
|
the breakpoint already existed when your program stopped.
|
|
|
`break ... if COND'
|
`break ... if COND'
|
Set a breakpoint with condition COND; evaluate the expression COND
|
Set a breakpoint with condition COND; evaluate the expression COND
|
each time the breakpoint is reached, and stop only if the value is
|
each time the breakpoint is reached, and stop only if the value is
|
nonzero--that is, if COND evaluates as true. `...' stands for one
|
nonzero--that is, if COND evaluates as true. `...' stands for one
|
of the possible arguments described above (or no argument)
|
of the possible arguments described above (or no argument)
|
specifying where to break. *Note Break Conditions: Conditions,
|
specifying where to break. *Note Break Conditions: Conditions,
|
for more information on breakpoint conditions.
|
for more information on breakpoint conditions.
|
|
|
`tbreak ARGS'
|
`tbreak ARGS'
|
Set a breakpoint enabled only for one stop. ARGS are the same as
|
Set a breakpoint enabled only for one stop. ARGS are the same as
|
for the `break' command, and the breakpoint is set in the same
|
for the `break' command, and the breakpoint is set in the same
|
way, but the breakpoint is automatically deleted after the first
|
way, but the breakpoint is automatically deleted after the first
|
time your program stops there. *Note Disabling Breakpoints:
|
time your program stops there. *Note Disabling Breakpoints:
|
Disabling.
|
Disabling.
|
|
|
`hbreak ARGS'
|
`hbreak ARGS'
|
Set a hardware-assisted breakpoint. ARGS are the same as for the
|
Set a hardware-assisted breakpoint. ARGS are the same as for the
|
`break' command and the breakpoint is set in the same way, but the
|
`break' command and the breakpoint is set in the same way, but the
|
breakpoint requires hardware support and some target hardware may
|
breakpoint requires hardware support and some target hardware may
|
not have this support. The main purpose of this is EPROM/ROM code
|
not have this support. The main purpose of this is EPROM/ROM code
|
debugging, so you can set a breakpoint at an instruction without
|
debugging, so you can set a breakpoint at an instruction without
|
changing the instruction. This can be used with the new
|
changing the instruction. This can be used with the new
|
trap-generation provided by SPARClite DSU and most x86-based
|
trap-generation provided by SPARClite DSU and most x86-based
|
targets. These targets will generate traps when a program
|
targets. These targets will generate traps when a program
|
accesses some data or instruction address that is assigned to the
|
accesses some data or instruction address that is assigned to the
|
debug registers. However the hardware breakpoint registers can
|
debug registers. However the hardware breakpoint registers can
|
take a limited number of breakpoints. For example, on the DSU,
|
take a limited number of breakpoints. For example, on the DSU,
|
only two data breakpoints can be set at a time, and GDB will
|
only two data breakpoints can be set at a time, and GDB will
|
reject this command if more than two are used. Delete or disable
|
reject this command if more than two are used. Delete or disable
|
unused hardware breakpoints before setting new ones (*note
|
unused hardware breakpoints before setting new ones (*note
|
Disabling Breakpoints: Disabling.). *Note Break Conditions:
|
Disabling Breakpoints: Disabling.). *Note Break Conditions:
|
Conditions. For remote targets, you can restrict the number of
|
Conditions. For remote targets, you can restrict the number of
|
hardware breakpoints GDB will use, see *note set remote
|
hardware breakpoints GDB will use, see *note set remote
|
hardware-breakpoint-limit::.
|
hardware-breakpoint-limit::.
|
|
|
`thbreak ARGS'
|
`thbreak ARGS'
|
Set a hardware-assisted breakpoint enabled only for one stop. ARGS
|
Set a hardware-assisted breakpoint enabled only for one stop. ARGS
|
are the same as for the `hbreak' command and the breakpoint is set
|
are the same as for the `hbreak' command and the breakpoint is set
|
in the same way. However, like the `tbreak' command, the
|
in the same way. However, like the `tbreak' command, the
|
breakpoint is automatically deleted after the first time your
|
breakpoint is automatically deleted after the first time your
|
program stops there. Also, like the `hbreak' command, the
|
program stops there. Also, like the `hbreak' command, the
|
breakpoint requires hardware support and some target hardware may
|
breakpoint requires hardware support and some target hardware may
|
not have this support. *Note Disabling Breakpoints: Disabling.
|
not have this support. *Note Disabling Breakpoints: Disabling.
|
See also *note Break Conditions: Conditions.
|
See also *note Break Conditions: Conditions.
|
|
|
`rbreak REGEX'
|
`rbreak REGEX'
|
Set breakpoints on all functions matching the regular expression
|
Set breakpoints on all functions matching the regular expression
|
REGEX. This command sets an unconditional breakpoint on all
|
REGEX. This command sets an unconditional breakpoint on all
|
matches, printing a list of all breakpoints it set. Once these
|
matches, printing a list of all breakpoints it set. Once these
|
breakpoints are set, they are treated just like the breakpoints
|
breakpoints are set, they are treated just like the breakpoints
|
set with the `break' command. You can delete them, disable them,
|
set with the `break' command. You can delete them, disable them,
|
or make them conditional the same way as any other breakpoint.
|
or make them conditional the same way as any other breakpoint.
|
|
|
The syntax of the regular expression is the standard one used with
|
The syntax of the regular expression is the standard one used with
|
tools like `grep'. Note that this is different from the syntax
|
tools like `grep'. Note that this is different from the syntax
|
used by shells, so for instance `foo*' matches all functions that
|
used by shells, so for instance `foo*' matches all functions that
|
include an `fo' followed by zero or more `o's. There is an
|
include an `fo' followed by zero or more `o's. There is an
|
implicit `.*' leading and trailing the regular expression you
|
implicit `.*' leading and trailing the regular expression you
|
supply, so to match only functions that begin with `foo', use
|
supply, so to match only functions that begin with `foo', use
|
`^foo'.
|
`^foo'.
|
|
|
When debugging C++ programs, `rbreak' is useful for setting
|
When debugging C++ programs, `rbreak' is useful for setting
|
breakpoints on overloaded functions that are not members of any
|
breakpoints on overloaded functions that are not members of any
|
special classes.
|
special classes.
|
|
|
The `rbreak' command can be used to set breakpoints in *all* the
|
The `rbreak' command can be used to set breakpoints in *all* the
|
functions in a program, like this:
|
functions in a program, like this:
|
|
|
(gdb) rbreak .
|
(gdb) rbreak .
|
|
|
`rbreak FILE:REGEX'
|
`rbreak FILE:REGEX'
|
If `rbreak' is called with a filename qualification, it limits the
|
If `rbreak' is called with a filename qualification, it limits the
|
search for functions matching the given regular expression to the
|
search for functions matching the given regular expression to the
|
specified FILE. This can be used, for example, to set breakpoints
|
specified FILE. This can be used, for example, to set breakpoints
|
on every function in a given file:
|
on every function in a given file:
|
|
|
(gdb) rbreak file.c:.
|
(gdb) rbreak file.c:.
|
|
|
The colon separating the filename qualifier from the regex may
|
The colon separating the filename qualifier from the regex may
|
optionally be surrounded by spaces.
|
optionally be surrounded by spaces.
|
|
|
`info breakpoints [N]'
|
`info breakpoints [N]'
|
`info break [N]'
|
`info break [N]'
|
Print a table of all breakpoints, watchpoints, and catchpoints set
|
Print a table of all breakpoints, watchpoints, and catchpoints set
|
and not deleted. Optional argument N means print information only
|
and not deleted. Optional argument N means print information only
|
about the specified breakpoint (or watchpoint or catchpoint). For
|
about the specified breakpoint (or watchpoint or catchpoint). For
|
each breakpoint, following columns are printed:
|
each breakpoint, following columns are printed:
|
|
|
_Breakpoint Numbers_
|
_Breakpoint Numbers_
|
|
|
_Type_
|
_Type_
|
Breakpoint, watchpoint, or catchpoint.
|
Breakpoint, watchpoint, or catchpoint.
|
|
|
_Disposition_
|
_Disposition_
|
Whether the breakpoint is marked to be disabled or deleted
|
Whether the breakpoint is marked to be disabled or deleted
|
when hit.
|
when hit.
|
|
|
_Enabled or Disabled_
|
_Enabled or Disabled_
|
Enabled breakpoints are marked with `y'. `n' marks
|
Enabled breakpoints are marked with `y'. `n' marks
|
breakpoints that are not enabled.
|
breakpoints that are not enabled.
|
|
|
_Address_
|
_Address_
|
Where the breakpoint is in your program, as a memory address.
|
Where the breakpoint is in your program, as a memory address.
|
For a pending breakpoint whose address is not yet known, this
|
For a pending breakpoint whose address is not yet known, this
|
field will contain `'. Such breakpoint won't fire
|
field will contain `'. Such breakpoint won't fire
|
until a shared library that has the symbol or line referred
|
until a shared library that has the symbol or line referred
|
by breakpoint is loaded. See below for details. A
|
by breakpoint is loaded. See below for details. A
|
breakpoint with several locations will have `' in
|
breakpoint with several locations will have `' in
|
this field--see below for details.
|
this field--see below for details.
|
|
|
_What_
|
_What_
|
Where the breakpoint is in the source for your program, as a
|
Where the breakpoint is in the source for your program, as a
|
file and line number. For a pending breakpoint, the original
|
file and line number. For a pending breakpoint, the original
|
string passed to the breakpoint command will be listed as it
|
string passed to the breakpoint command will be listed as it
|
cannot be resolved until the appropriate shared library is
|
cannot be resolved until the appropriate shared library is
|
loaded in the future.
|
loaded in the future.
|
|
|
If a breakpoint is conditional, `info break' shows the condition on
|
If a breakpoint is conditional, `info break' shows the condition on
|
the line following the affected breakpoint; breakpoint commands,
|
the line following the affected breakpoint; breakpoint commands,
|
if any, are listed after that. A pending breakpoint is allowed to
|
if any, are listed after that. A pending breakpoint is allowed to
|
have a condition specified for it. The condition is not parsed
|
have a condition specified for it. The condition is not parsed
|
for validity until a shared library is loaded that allows the
|
for validity until a shared library is loaded that allows the
|
pending breakpoint to resolve to a valid location.
|
pending breakpoint to resolve to a valid location.
|
|
|
`info break' with a breakpoint number N as argument lists only
|
`info break' with a breakpoint number N as argument lists only
|
that breakpoint. The convenience variable `$_' and the default
|
that breakpoint. The convenience variable `$_' and the default
|
examining-address for the `x' command are set to the address of
|
examining-address for the `x' command are set to the address of
|
the last breakpoint listed (*note Examining Memory: Memory.).
|
the last breakpoint listed (*note Examining Memory: Memory.).
|
|
|
`info break' displays a count of the number of times the breakpoint
|
`info break' displays a count of the number of times the breakpoint
|
has been hit. This is especially useful in conjunction with the
|
has been hit. This is especially useful in conjunction with the
|
`ignore' command. You can ignore a large number of breakpoint
|
`ignore' command. You can ignore a large number of breakpoint
|
hits, look at the breakpoint info to see how many times the
|
hits, look at the breakpoint info to see how many times the
|
breakpoint was hit, and then run again, ignoring one less than
|
breakpoint was hit, and then run again, ignoring one less than
|
that number. This will get you quickly to the last hit of that
|
that number. This will get you quickly to the last hit of that
|
breakpoint.
|
breakpoint.
|
|
|
GDB allows you to set any number of breakpoints at the same place in
|
GDB allows you to set any number of breakpoints at the same place in
|
your program. There is nothing silly or meaningless about this. When
|
your program. There is nothing silly or meaningless about this. When
|
the breakpoints are conditional, this is even useful (*note Break
|
the breakpoints are conditional, this is even useful (*note Break
|
Conditions: Conditions.).
|
Conditions: Conditions.).
|
|
|
It is possible that a breakpoint corresponds to several locations in
|
It is possible that a breakpoint corresponds to several locations in
|
your program. Examples of this situation are:
|
your program. Examples of this situation are:
|
|
|
* For a C++ constructor, the GCC compiler generates several
|
* For a C++ constructor, the GCC compiler generates several
|
instances of the function body, used in different cases.
|
instances of the function body, used in different cases.
|
|
|
* For a C++ template function, a given line in the function can
|
* For a C++ template function, a given line in the function can
|
correspond to any number of instantiations.
|
correspond to any number of instantiations.
|
|
|
* For an inlined function, a given source line can correspond to
|
* For an inlined function, a given source line can correspond to
|
several places where that function is inlined.
|
several places where that function is inlined.
|
|
|
In all those cases, GDB will insert a breakpoint at all the relevant
|
In all those cases, GDB will insert a breakpoint at all the relevant
|
locations(1).
|
locations(1).
|
|
|
A breakpoint with multiple locations is displayed in the breakpoint
|
A breakpoint with multiple locations is displayed in the breakpoint
|
table using several rows--one header row, followed by one row for each
|
table using several rows--one header row, followed by one row for each
|
breakpoint location. The header row has `' in the address
|
breakpoint location. The header row has `' in the address
|
column. The rows for individual locations contain the actual addresses
|
column. The rows for individual locations contain the actual addresses
|
for locations, and show the functions to which those locations belong.
|
for locations, and show the functions to which those locations belong.
|
The number column for a location is of the form
|
The number column for a location is of the form
|
BREAKPOINT-NUMBER.LOCATION-NUMBER.
|
BREAKPOINT-NUMBER.LOCATION-NUMBER.
|
|
|
For example:
|
For example:
|
|
|
Num Type Disp Enb Address What
|
Num Type Disp Enb Address What
|
1 breakpoint keep y
|
1 breakpoint keep y
|
stop only if i==1
|
stop only if i==1
|
breakpoint already hit 1 time
|
breakpoint already hit 1 time
|
1.1 y 0x080486a2 in void foo() at t.cc:8
|
1.1 y 0x080486a2 in void foo() at t.cc:8
|
1.2 y 0x080486ca in void foo() at t.cc:8
|
1.2 y 0x080486ca in void foo() at t.cc:8
|
|
|
Each location can be individually enabled or disabled by passing
|
Each location can be individually enabled or disabled by passing
|
BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and
|
BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and
|
`disable' commands. Note that you cannot delete the individual
|
`disable' commands. Note that you cannot delete the individual
|
locations from the list, you can only delete the entire list of
|
locations from the list, you can only delete the entire list of
|
locations that belong to their parent breakpoint (with the `delete NUM'
|
locations that belong to their parent breakpoint (with the `delete NUM'
|
command, where NUM is the number of the parent breakpoint, 1 in the
|
command, where NUM is the number of the parent breakpoint, 1 in the
|
above example). Disabling or enabling the parent breakpoint (*note
|
above example). Disabling or enabling the parent breakpoint (*note
|
Disabling::) affects all of the locations that belong to that
|
Disabling::) affects all of the locations that belong to that
|
breakpoint.
|
breakpoint.
|
|
|
It's quite common to have a breakpoint inside a shared library.
|
It's quite common to have a breakpoint inside a shared library.
|
Shared libraries can be loaded and unloaded explicitly, and possibly
|
Shared libraries can be loaded and unloaded explicitly, and possibly
|
repeatedly, as the program is executed. To support this use case, GDB
|
repeatedly, as the program is executed. To support this use case, GDB
|
updates breakpoint locations whenever any shared library is loaded or
|
updates breakpoint locations whenever any shared library is loaded or
|
unloaded. Typically, you would set a breakpoint in a shared library at
|
unloaded. Typically, you would set a breakpoint in a shared library at
|
the beginning of your debugging session, when the library is not
|
the beginning of your debugging session, when the library is not
|
loaded, and when the symbols from the library are not available. When
|
loaded, and when the symbols from the library are not available. When
|
you try to set breakpoint, GDB will ask you if you want to set a so
|
you try to set breakpoint, GDB will ask you if you want to set a so
|
called "pending breakpoint"--breakpoint whose address is not yet
|
called "pending breakpoint"--breakpoint whose address is not yet
|
resolved.
|
resolved.
|
|
|
After the program is run, whenever a new shared library is loaded,
|
After the program is run, whenever a new shared library is loaded,
|
GDB reevaluates all the breakpoints. When a newly loaded shared
|
GDB reevaluates all the breakpoints. When a newly loaded shared
|
library contains the symbol or line referred to by some pending
|
library contains the symbol or line referred to by some pending
|
breakpoint, that breakpoint is resolved and becomes an ordinary
|
breakpoint, that breakpoint is resolved and becomes an ordinary
|
breakpoint. When a library is unloaded, all breakpoints that refer to
|
breakpoint. When a library is unloaded, all breakpoints that refer to
|
its symbols or source lines become pending again.
|
its symbols or source lines become pending again.
|
|
|
This logic works for breakpoints with multiple locations, too. For
|
This logic works for breakpoints with multiple locations, too. For
|
example, if you have a breakpoint in a C++ template function, and a
|
example, if you have a breakpoint in a C++ template function, and a
|
newly loaded shared library has an instantiation of that template, a
|
newly loaded shared library has an instantiation of that template, a
|
new location is added to the list of locations for the breakpoint.
|
new location is added to the list of locations for the breakpoint.
|
|
|
Except for having unresolved address, pending breakpoints do not
|
Except for having unresolved address, pending breakpoints do not
|
differ from regular breakpoints. You can set conditions or commands,
|
differ from regular breakpoints. You can set conditions or commands,
|
enable and disable them and perform other breakpoint operations.
|
enable and disable them and perform other breakpoint operations.
|
|
|
GDB provides some additional commands for controlling what happens
|
GDB provides some additional commands for controlling what happens
|
when the `break' command cannot resolve breakpoint address
|
when the `break' command cannot resolve breakpoint address
|
specification to an address:
|
specification to an address:
|
|
|
`set breakpoint pending auto'
|
`set breakpoint pending auto'
|
This is the default behavior. When GDB cannot find the breakpoint
|
This is the default behavior. When GDB cannot find the breakpoint
|
location, it queries you whether a pending breakpoint should be
|
location, it queries you whether a pending breakpoint should be
|
created.
|
created.
|
|
|
`set breakpoint pending on'
|
`set breakpoint pending on'
|
This indicates that an unrecognized breakpoint location should
|
This indicates that an unrecognized breakpoint location should
|
automatically result in a pending breakpoint being created.
|
automatically result in a pending breakpoint being created.
|
|
|
`set breakpoint pending off'
|
`set breakpoint pending off'
|
This indicates that pending breakpoints are not to be created. Any
|
This indicates that pending breakpoints are not to be created. Any
|
unrecognized breakpoint location results in an error. This
|
unrecognized breakpoint location results in an error. This
|
setting does not affect any pending breakpoints previously created.
|
setting does not affect any pending breakpoints previously created.
|
|
|
`show breakpoint pending'
|
`show breakpoint pending'
|
Show the current behavior setting for creating pending breakpoints.
|
Show the current behavior setting for creating pending breakpoints.
|
|
|
The settings above only affect the `break' command and its variants.
|
The settings above only affect the `break' command and its variants.
|
Once breakpoint is set, it will be automatically updated as shared
|
Once breakpoint is set, it will be automatically updated as shared
|
libraries are loaded and unloaded.
|
libraries are loaded and unloaded.
|
|
|
For some targets, GDB can automatically decide if hardware or
|
For some targets, GDB can automatically decide if hardware or
|
software breakpoints should be used, depending on whether the
|
software breakpoints should be used, depending on whether the
|
breakpoint address is read-only or read-write. This applies to
|
breakpoint address is read-only or read-write. This applies to
|
breakpoints set with the `break' command as well as to internal
|
breakpoints set with the `break' command as well as to internal
|
breakpoints set by commands like `next' and `finish'. For breakpoints
|
breakpoints set by commands like `next' and `finish'. For breakpoints
|
set with `hbreak', GDB will always use hardware breakpoints.
|
set with `hbreak', GDB will always use hardware breakpoints.
|
|
|
You can control this automatic behaviour with the following
|
You can control this automatic behaviour with the following
|
commands::
|
commands::
|
|
|
`set breakpoint auto-hw on'
|
`set breakpoint auto-hw on'
|
This is the default behavior. When GDB sets a breakpoint, it will
|
This is the default behavior. When GDB sets a breakpoint, it will
|
try to use the target memory map to decide if software or hardware
|
try to use the target memory map to decide if software or hardware
|
breakpoint must be used.
|
breakpoint must be used.
|
|
|
`set breakpoint auto-hw off'
|
`set breakpoint auto-hw off'
|
This indicates GDB should not automatically select breakpoint
|
This indicates GDB should not automatically select breakpoint
|
type. If the target provides a memory map, GDB will warn when
|
type. If the target provides a memory map, GDB will warn when
|
trying to set software breakpoint at a read-only address.
|
trying to set software breakpoint at a read-only address.
|
|
|
GDB normally implements breakpoints by replacing the program code at
|
GDB normally implements breakpoints by replacing the program code at
|
the breakpoint address with a special instruction, which, when
|
the breakpoint address with a special instruction, which, when
|
executed, given control to the debugger. By default, the program code
|
executed, given control to the debugger. By default, the program code
|
is so modified only when the program is resumed. As soon as the
|
is so modified only when the program is resumed. As soon as the
|
program stops, GDB restores the original instructions. This behaviour
|
program stops, GDB restores the original instructions. This behaviour
|
guards against leaving breakpoints inserted in the target should gdb
|
guards against leaving breakpoints inserted in the target should gdb
|
abrubptly disconnect. However, with slow remote targets, inserting and
|
abrubptly disconnect. However, with slow remote targets, inserting and
|
removing breakpoint can reduce the performance. This behavior can be
|
removing breakpoint can reduce the performance. This behavior can be
|
controlled with the following commands::
|
controlled with the following commands::
|
|
|
`set breakpoint always-inserted off'
|
`set breakpoint always-inserted off'
|
All breakpoints, including newly added by the user, are inserted in
|
All breakpoints, including newly added by the user, are inserted in
|
the target only when the target is resumed. All breakpoints are
|
the target only when the target is resumed. All breakpoints are
|
removed from the target when it stops.
|
removed from the target when it stops.
|
|
|
`set breakpoint always-inserted on'
|
`set breakpoint always-inserted on'
|
Causes all breakpoints to be inserted in the target at all times.
|
Causes all breakpoints to be inserted in the target at all times.
|
If the user adds a new breakpoint, or changes an existing
|
If the user adds a new breakpoint, or changes an existing
|
breakpoint, the breakpoints in the target are updated immediately.
|
breakpoint, the breakpoints in the target are updated immediately.
|
A breakpoint is removed from the target only when breakpoint
|
A breakpoint is removed from the target only when breakpoint
|
itself is removed.
|
itself is removed.
|
|
|
`set breakpoint always-inserted auto'
|
`set breakpoint always-inserted auto'
|
This is the default mode. If GDB is controlling the inferior in
|
This is the default mode. If GDB is controlling the inferior in
|
non-stop mode (*note Non-Stop Mode::), gdb behaves as if
|
non-stop mode (*note Non-Stop Mode::), gdb behaves as if
|
`breakpoint always-inserted' mode is on. If GDB is controlling
|
`breakpoint always-inserted' mode is on. If GDB is controlling
|
the inferior in all-stop mode, GDB behaves as if `breakpoint
|
the inferior in all-stop mode, GDB behaves as if `breakpoint
|
always-inserted' mode is off.
|
always-inserted' mode is off.
|
|
|
GDB itself sometimes sets breakpoints in your program for special
|
GDB itself sometimes sets breakpoints in your program for special
|
purposes, such as proper handling of `longjmp' (in C programs). These
|
purposes, such as proper handling of `longjmp' (in C programs). These
|
internal breakpoints are assigned negative numbers, starting with `-1';
|
internal breakpoints are assigned negative numbers, starting with `-1';
|
`info breakpoints' does not display them. You can see these
|
`info breakpoints' does not display them. You can see these
|
breakpoints with the GDB maintenance command `maint info breakpoints'
|
breakpoints with the GDB maintenance command `maint info breakpoints'
|
(*note maint info breakpoints::).
|
(*note maint info breakpoints::).
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) As of this writing, multiple-location breakpoints work only if
|
(1) As of this writing, multiple-location breakpoints work only if
|
there's line number information for all the locations. This means that
|
there's line number information for all the locations. This means that
|
they will generally not work in system libraries, unless you have debug
|
they will generally not work in system libraries, unless you have debug
|
info with line numbers for them.
|
info with line numbers for them.
|
|
|
|
|
File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints
|
File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints
|
|
|
5.1.2 Setting Watchpoints
|
5.1.2 Setting Watchpoints
|
-------------------------
|
-------------------------
|
|
|
You can use a watchpoint to stop execution whenever the value of an
|
You can use a watchpoint to stop execution whenever the value of an
|
expression changes, without having to predict a particular place where
|
expression changes, without having to predict a particular place where
|
this may happen. (This is sometimes called a "data breakpoint".) The
|
this may happen. (This is sometimes called a "data breakpoint".) The
|
expression may be as simple as the value of a single variable, or as
|
expression may be as simple as the value of a single variable, or as
|
complex as many variables combined by operators. Examples include:
|
complex as many variables combined by operators. Examples include:
|
|
|
* A reference to the value of a single variable.
|
* A reference to the value of a single variable.
|
|
|
* An address cast to an appropriate data type. For example, `*(int
|
* An address cast to an appropriate data type. For example, `*(int
|
*)0x12345678' will watch a 4-byte region at the specified address
|
*)0x12345678' will watch a 4-byte region at the specified address
|
(assuming an `int' occupies 4 bytes).
|
(assuming an `int' occupies 4 bytes).
|
|
|
* An arbitrarily complex expression, such as `a*b + c/d'. The
|
* An arbitrarily complex expression, such as `a*b + c/d'. The
|
expression can use any operators valid in the program's native
|
expression can use any operators valid in the program's native
|
language (*note Languages::).
|
language (*note Languages::).
|
|
|
You can set a watchpoint on an expression even if the expression can
|
You can set a watchpoint on an expression even if the expression can
|
not be evaluated yet. For instance, you can set a watchpoint on
|
not be evaluated yet. For instance, you can set a watchpoint on
|
`*global_ptr' before `global_ptr' is initialized. GDB will stop when
|
`*global_ptr' before `global_ptr' is initialized. GDB will stop when
|
your program sets `global_ptr' and the expression produces a valid
|
your program sets `global_ptr' and the expression produces a valid
|
value. If the expression becomes valid in some other way than changing
|
value. If the expression becomes valid in some other way than changing
|
a variable (e.g. if the memory pointed to by `*global_ptr' becomes
|
a variable (e.g. if the memory pointed to by `*global_ptr' becomes
|
readable as the result of a `malloc' call), GDB may not stop until the
|
readable as the result of a `malloc' call), GDB may not stop until the
|
next time the expression changes.
|
next time the expression changes.
|
|
|
Depending on your system, watchpoints may be implemented in software
|
Depending on your system, watchpoints may be implemented in software
|
or hardware. GDB does software watchpointing by single-stepping your
|
or hardware. GDB does software watchpointing by single-stepping your
|
program and testing the variable's value each time, which is hundreds of
|
program and testing the variable's value each time, which is hundreds of
|
times slower than normal execution. (But this may still be worth it, to
|
times slower than normal execution. (But this may still be worth it, to
|
catch errors where you have no clue what part of your program is the
|
catch errors where you have no clue what part of your program is the
|
culprit.)
|
culprit.)
|
|
|
On some systems, such as HP-UX, PowerPC, GNU/Linux and most other
|
On some systems, such as HP-UX, PowerPC, GNU/Linux and most other
|
x86-based targets, GDB includes support for hardware watchpoints, which
|
x86-based targets, GDB includes support for hardware watchpoints, which
|
do not slow down the running of your program.
|
do not slow down the running of your program.
|
|
|
`watch EXPR [thread THREADNUM]'
|
`watch EXPR [thread THREADNUM]'
|
Set a watchpoint for an expression. GDB will break when the
|
Set a watchpoint for an expression. GDB will break when the
|
expression EXPR is written into by the program and its value
|
expression EXPR is written into by the program and its value
|
changes. The simplest (and the most popular) use of this command
|
changes. The simplest (and the most popular) use of this command
|
is to watch the value of a single variable:
|
is to watch the value of a single variable:
|
|
|
(gdb) watch foo
|
(gdb) watch foo
|
|
|
If the command includes a `[thread THREADNUM]' clause, GDB breaks
|
If the command includes a `[thread THREADNUM]' clause, GDB breaks
|
only when the thread identified by THREADNUM changes the value of
|
only when the thread identified by THREADNUM changes the value of
|
EXPR. If any other threads change the value of EXPR, GDB will not
|
EXPR. If any other threads change the value of EXPR, GDB will not
|
break. Note that watchpoints restricted to a single thread in
|
break. Note that watchpoints restricted to a single thread in
|
this way only work with Hardware Watchpoints.
|
this way only work with Hardware Watchpoints.
|
|
|
`rwatch EXPR [thread THREADNUM]'
|
`rwatch EXPR [thread THREADNUM]'
|
Set a watchpoint that will break when the value of EXPR is read by
|
Set a watchpoint that will break when the value of EXPR is read by
|
the program.
|
the program.
|
|
|
`awatch EXPR [thread THREADNUM]'
|
`awatch EXPR [thread THREADNUM]'
|
Set a watchpoint that will break when EXPR is either read from or
|
Set a watchpoint that will break when EXPR is either read from or
|
written into by the program.
|
written into by the program.
|
|
|
`info watchpoints'
|
`info watchpoints'
|
This command prints a list of watchpoints, using the same format as
|
This command prints a list of watchpoints, using the same format as
|
`info break' (*note Set Breaks::).
|
`info break' (*note Set Breaks::).
|
|
|
If you watch for a change in a numerically entered address you need
|
If you watch for a change in a numerically entered address you need
|
to dereference it, as the address itself is just a constant number
|
to dereference it, as the address itself is just a constant number
|
which will never change. GDB refuses to create a watchpoint that
|
which will never change. GDB refuses to create a watchpoint that
|
watches a never-changing value:
|
watches a never-changing value:
|
|
|
(gdb) watch 0x600850
|
(gdb) watch 0x600850
|
Cannot watch constant value 0x600850.
|
Cannot watch constant value 0x600850.
|
(gdb) watch *(int *) 0x600850
|
(gdb) watch *(int *) 0x600850
|
Watchpoint 1: *(int *) 6293584
|
Watchpoint 1: *(int *) 6293584
|
|
|
GDB sets a "hardware watchpoint" if possible. Hardware watchpoints
|
GDB sets a "hardware watchpoint" if possible. Hardware watchpoints
|
execute very quickly, and the debugger reports a change in value at the
|
execute very quickly, and the debugger reports a change in value at the
|
exact instruction where the change occurs. If GDB cannot set a
|
exact instruction where the change occurs. If GDB cannot set a
|
hardware watchpoint, it sets a software watchpoint, which executes more
|
hardware watchpoint, it sets a software watchpoint, which executes more
|
slowly and reports the change in value at the next _statement_, not the
|
slowly and reports the change in value at the next _statement_, not the
|
instruction, after the change occurs.
|
instruction, after the change occurs.
|
|
|
You can force GDB to use only software watchpoints with the `set
|
You can force GDB to use only software watchpoints with the `set
|
can-use-hw-watchpoints 0' command. With this variable set to zero, GDB
|
can-use-hw-watchpoints 0' command. With this variable set to zero, GDB
|
will never try to use hardware watchpoints, even if the underlying
|
will never try to use hardware watchpoints, even if the underlying
|
system supports them. (Note that hardware-assisted watchpoints that
|
system supports them. (Note that hardware-assisted watchpoints that
|
were set _before_ setting `can-use-hw-watchpoints' to zero will still
|
were set _before_ setting `can-use-hw-watchpoints' to zero will still
|
use the hardware mechanism of watching expression values.)
|
use the hardware mechanism of watching expression values.)
|
|
|
`set can-use-hw-watchpoints'
|
`set can-use-hw-watchpoints'
|
Set whether or not to use hardware watchpoints.
|
Set whether or not to use hardware watchpoints.
|
|
|
`show can-use-hw-watchpoints'
|
`show can-use-hw-watchpoints'
|
Show the current mode of using hardware watchpoints.
|
Show the current mode of using hardware watchpoints.
|
|
|
For remote targets, you can restrict the number of hardware
|
For remote targets, you can restrict the number of hardware
|
watchpoints GDB will use, see *note set remote
|
watchpoints GDB will use, see *note set remote
|
hardware-breakpoint-limit::.
|
hardware-breakpoint-limit::.
|
|
|
When you issue the `watch' command, GDB reports
|
When you issue the `watch' command, GDB reports
|
|
|
Hardware watchpoint NUM: EXPR
|
Hardware watchpoint NUM: EXPR
|
|
|
if it was able to set a hardware watchpoint.
|
if it was able to set a hardware watchpoint.
|
|
|
Currently, the `awatch' and `rwatch' commands can only set hardware
|
Currently, the `awatch' and `rwatch' commands can only set hardware
|
watchpoints, because accesses to data that don't change the value of
|
watchpoints, because accesses to data that don't change the value of
|
the watched expression cannot be detected without examining every
|
the watched expression cannot be detected without examining every
|
instruction as it is being executed, and GDB does not do that
|
instruction as it is being executed, and GDB does not do that
|
currently. If GDB finds that it is unable to set a hardware breakpoint
|
currently. If GDB finds that it is unable to set a hardware breakpoint
|
with the `awatch' or `rwatch' command, it will print a message like
|
with the `awatch' or `rwatch' command, it will print a message like
|
this:
|
this:
|
|
|
Expression cannot be implemented with read/access watchpoint.
|
Expression cannot be implemented with read/access watchpoint.
|
|
|
Sometimes, GDB cannot set a hardware watchpoint because the data
|
Sometimes, GDB cannot set a hardware watchpoint because the data
|
type of the watched expression is wider than what a hardware watchpoint
|
type of the watched expression is wider than what a hardware watchpoint
|
on the target machine can handle. For example, some systems can only
|
on the target machine can handle. For example, some systems can only
|
watch regions that are up to 4 bytes wide; on such systems you cannot
|
watch regions that are up to 4 bytes wide; on such systems you cannot
|
set hardware watchpoints for an expression that yields a
|
set hardware watchpoints for an expression that yields a
|
double-precision floating-point number (which is typically 8 bytes
|
double-precision floating-point number (which is typically 8 bytes
|
wide). As a work-around, it might be possible to break the large region
|
wide). As a work-around, it might be possible to break the large region
|
into a series of smaller ones and watch them with separate watchpoints.
|
into a series of smaller ones and watch them with separate watchpoints.
|
|
|
If you set too many hardware watchpoints, GDB might be unable to
|
If you set too many hardware watchpoints, GDB might be unable to
|
insert all of them when you resume the execution of your program.
|
insert all of them when you resume the execution of your program.
|
Since the precise number of active watchpoints is unknown until such
|
Since the precise number of active watchpoints is unknown until such
|
time as the program is about to be resumed, GDB might not be able to
|
time as the program is about to be resumed, GDB might not be able to
|
warn you about this when you set the watchpoints, and the warning will
|
warn you about this when you set the watchpoints, and the warning will
|
be printed only when the program is resumed:
|
be printed only when the program is resumed:
|
|
|
Hardware watchpoint NUM: Could not insert watchpoint
|
Hardware watchpoint NUM: Could not insert watchpoint
|
|
|
If this happens, delete or disable some of the watchpoints.
|
If this happens, delete or disable some of the watchpoints.
|
|
|
Watching complex expressions that reference many variables can also
|
Watching complex expressions that reference many variables can also
|
exhaust the resources available for hardware-assisted watchpoints.
|
exhaust the resources available for hardware-assisted watchpoints.
|
That's because GDB needs to watch every variable in the expression with
|
That's because GDB needs to watch every variable in the expression with
|
separately allocated resources.
|
separately allocated resources.
|
|
|
If you call a function interactively using `print' or `call', any
|
If you call a function interactively using `print' or `call', any
|
watchpoints you have set will be inactive until GDB reaches another
|
watchpoints you have set will be inactive until GDB reaches another
|
kind of breakpoint or the call completes.
|
kind of breakpoint or the call completes.
|
|
|
GDB automatically deletes watchpoints that watch local (automatic)
|
GDB automatically deletes watchpoints that watch local (automatic)
|
variables, or expressions that involve such variables, when they go out
|
variables, or expressions that involve such variables, when they go out
|
of scope, that is, when the execution leaves the block in which these
|
of scope, that is, when the execution leaves the block in which these
|
variables were defined. In particular, when the program being debugged
|
variables were defined. In particular, when the program being debugged
|
terminates, _all_ local variables go out of scope, and so only
|
terminates, _all_ local variables go out of scope, and so only
|
watchpoints that watch global variables remain set. If you rerun the
|
watchpoints that watch global variables remain set. If you rerun the
|
program, you will need to set all such watchpoints again. One way of
|
program, you will need to set all such watchpoints again. One way of
|
doing that would be to set a code breakpoint at the entry to the `main'
|
doing that would be to set a code breakpoint at the entry to the `main'
|
function and when it breaks, set all the watchpoints.
|
function and when it breaks, set all the watchpoints.
|
|
|
In multi-threaded programs, watchpoints will detect changes to the
|
In multi-threaded programs, watchpoints will detect changes to the
|
watched expression from every thread.
|
watched expression from every thread.
|
|
|
_Warning:_ In multi-threaded programs, software watchpoints have
|
_Warning:_ In multi-threaded programs, software watchpoints have
|
only limited usefulness. If GDB creates a software watchpoint, it
|
only limited usefulness. If GDB creates a software watchpoint, it
|
can only watch the value of an expression _in a single thread_.
|
can only watch the value of an expression _in a single thread_.
|
If you are confident that the expression can only change due to
|
If you are confident that the expression can only change due to
|
the current thread's activity (and if you are also confident that
|
the current thread's activity (and if you are also confident that
|
no other thread can become current), then you can use software
|
no other thread can become current), then you can use software
|
watchpoints as usual. However, GDB may not notice when a
|
watchpoints as usual. However, GDB may not notice when a
|
non-current thread's activity changes the expression. (Hardware
|
non-current thread's activity changes the expression. (Hardware
|
watchpoints, in contrast, watch an expression in all threads.)
|
watchpoints, in contrast, watch an expression in all threads.)
|
|
|
*Note set remote hardware-watchpoint-limit::.
|
*Note set remote hardware-watchpoint-limit::.
|
|
|
|
|
File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints
|
File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints
|
|
|
5.1.3 Setting Catchpoints
|
5.1.3 Setting Catchpoints
|
-------------------------
|
-------------------------
|
|
|
You can use "catchpoints" to cause the debugger to stop for certain
|
You can use "catchpoints" to cause the debugger to stop for certain
|
kinds of program events, such as C++ exceptions or the loading of a
|
kinds of program events, such as C++ exceptions or the loading of a
|
shared library. Use the `catch' command to set a catchpoint.
|
shared library. Use the `catch' command to set a catchpoint.
|
|
|
`catch EVENT'
|
`catch EVENT'
|
Stop when EVENT occurs. EVENT can be any of the following:
|
Stop when EVENT occurs. EVENT can be any of the following:
|
`throw'
|
`throw'
|
The throwing of a C++ exception.
|
The throwing of a C++ exception.
|
|
|
`catch'
|
`catch'
|
The catching of a C++ exception.
|
The catching of a C++ exception.
|
|
|
`exception'
|
`exception'
|
An Ada exception being raised. If an exception name is
|
An Ada exception being raised. If an exception name is
|
specified at the end of the command (eg `catch exception
|
specified at the end of the command (eg `catch exception
|
Program_Error'), the debugger will stop only when this
|
Program_Error'), the debugger will stop only when this
|
specific exception is raised. Otherwise, the debugger stops
|
specific exception is raised. Otherwise, the debugger stops
|
execution when any Ada exception is raised.
|
execution when any Ada exception is raised.
|
|
|
When inserting an exception catchpoint on a user-defined
|
When inserting an exception catchpoint on a user-defined
|
exception whose name is identical to one of the exceptions
|
exception whose name is identical to one of the exceptions
|
defined by the language, the fully qualified name must be
|
defined by the language, the fully qualified name must be
|
used as the exception name. Otherwise, GDB will assume that
|
used as the exception name. Otherwise, GDB will assume that
|
it should stop on the pre-defined exception rather than the
|
it should stop on the pre-defined exception rather than the
|
user-defined one. For instance, assuming an exception called
|
user-defined one. For instance, assuming an exception called
|
`Constraint_Error' is defined in package `Pck', then the
|
`Constraint_Error' is defined in package `Pck', then the
|
command to use to catch such exceptions is `catch exception
|
command to use to catch such exceptions is `catch exception
|
Pck.Constraint_Error'.
|
Pck.Constraint_Error'.
|
|
|
`exception unhandled'
|
`exception unhandled'
|
An exception that was raised but is not handled by the
|
An exception that was raised but is not handled by the
|
program.
|
program.
|
|
|
`assert'
|
`assert'
|
A failed Ada assertion.
|
A failed Ada assertion.
|
|
|
`exec'
|
`exec'
|
A call to `exec'. This is currently only available for HP-UX
|
A call to `exec'. This is currently only available for HP-UX
|
and GNU/Linux.
|
and GNU/Linux.
|
|
|
`syscall'
|
`syscall'
|
`syscall [NAME | NUMBER] ...'
|
`syscall [NAME | NUMBER] ...'
|
A call to or return from a system call, a.k.a. "syscall". A
|
A call to or return from a system call, a.k.a. "syscall". A
|
syscall is a mechanism for application programs to request a
|
syscall is a mechanism for application programs to request a
|
service from the operating system (OS) or one of the OS
|
service from the operating system (OS) or one of the OS
|
system services. GDB can catch some or all of the syscalls
|
system services. GDB can catch some or all of the syscalls
|
issued by the debuggee, and show the related information for
|
issued by the debuggee, and show the related information for
|
each syscall. If no argument is specified, calls to and
|
each syscall. If no argument is specified, calls to and
|
returns from all system calls will be caught.
|
returns from all system calls will be caught.
|
|
|
NAME can be any system call name that is valid for the
|
NAME can be any system call name that is valid for the
|
underlying OS. Just what syscalls are valid depends on the
|
underlying OS. Just what syscalls are valid depends on the
|
OS. On GNU and Unix systems, you can find the full list of
|
OS. On GNU and Unix systems, you can find the full list of
|
valid syscall names on `/usr/include/asm/unistd.h'.
|
valid syscall names on `/usr/include/asm/unistd.h'.
|
|
|
Normally, GDB knows in advance which syscalls are valid for
|
Normally, GDB knows in advance which syscalls are valid for
|
each OS, so you can use the GDB command-line completion
|
each OS, so you can use the GDB command-line completion
|
facilities (*note command completion: Completion.) to list the
|
facilities (*note command completion: Completion.) to list the
|
available choices.
|
available choices.
|
|
|
You may also specify the system call numerically. A syscall's
|
You may also specify the system call numerically. A syscall's
|
number is the value passed to the OS's syscall dispatcher to
|
number is the value passed to the OS's syscall dispatcher to
|
identify the requested service. When you specify the syscall
|
identify the requested service. When you specify the syscall
|
by its name, GDB uses its database of syscalls to convert the
|
by its name, GDB uses its database of syscalls to convert the
|
name into the corresponding numeric code, but using the
|
name into the corresponding numeric code, but using the
|
number directly may be useful if GDB's database does not have
|
number directly may be useful if GDB's database does not have
|
the complete list of syscalls on your system (e.g., because
|
the complete list of syscalls on your system (e.g., because
|
GDB lags behind the OS upgrades).
|
GDB lags behind the OS upgrades).
|
|
|
The example below illustrates how this command works if you
|
The example below illustrates how this command works if you
|
don't provide arguments to it:
|
don't provide arguments to it:
|
|
|
(gdb) catch syscall
|
(gdb) catch syscall
|
Catchpoint 1 (syscall)
|
Catchpoint 1 (syscall)
|
(gdb) r
|
(gdb) r
|
Starting program: /tmp/catch-syscall
|
Starting program: /tmp/catch-syscall
|
|
|
Catchpoint 1 (call to syscall 'close'), \
|
Catchpoint 1 (call to syscall 'close'), \
|
0xffffe424 in __kernel_vsyscall ()
|
0xffffe424 in __kernel_vsyscall ()
|
(gdb) c
|
(gdb) c
|
Continuing.
|
Continuing.
|
|
|
Catchpoint 1 (returned from syscall 'close'), \
|
Catchpoint 1 (returned from syscall 'close'), \
|
0xffffe424 in __kernel_vsyscall ()
|
0xffffe424 in __kernel_vsyscall ()
|
(gdb)
|
(gdb)
|
|
|
Here is an example of catching a system call by name:
|
Here is an example of catching a system call by name:
|
|
|
(gdb) catch syscall chroot
|
(gdb) catch syscall chroot
|
Catchpoint 1 (syscall 'chroot' [61])
|
Catchpoint 1 (syscall 'chroot' [61])
|
(gdb) r
|
(gdb) r
|
Starting program: /tmp/catch-syscall
|
Starting program: /tmp/catch-syscall
|
|
|
Catchpoint 1 (call to syscall 'chroot'), \
|
Catchpoint 1 (call to syscall 'chroot'), \
|
0xffffe424 in __kernel_vsyscall ()
|
0xffffe424 in __kernel_vsyscall ()
|
(gdb) c
|
(gdb) c
|
Continuing.
|
Continuing.
|
|
|
Catchpoint 1 (returned from syscall 'chroot'), \
|
Catchpoint 1 (returned from syscall 'chroot'), \
|
0xffffe424 in __kernel_vsyscall ()
|
0xffffe424 in __kernel_vsyscall ()
|
(gdb)
|
(gdb)
|
|
|
An example of specifying a system call numerically. In the
|
An example of specifying a system call numerically. In the
|
case below, the syscall number has a corresponding entry in
|
case below, the syscall number has a corresponding entry in
|
the XML file, so GDB finds its name and prints it:
|
the XML file, so GDB finds its name and prints it:
|
|
|
(gdb) catch syscall 252
|
(gdb) catch syscall 252
|
Catchpoint 1 (syscall(s) 'exit_group')
|
Catchpoint 1 (syscall(s) 'exit_group')
|
(gdb) r
|
(gdb) r
|
Starting program: /tmp/catch-syscall
|
Starting program: /tmp/catch-syscall
|
|
|
Catchpoint 1 (call to syscall 'exit_group'), \
|
Catchpoint 1 (call to syscall 'exit_group'), \
|
0xffffe424 in __kernel_vsyscall ()
|
0xffffe424 in __kernel_vsyscall ()
|
(gdb) c
|
(gdb) c
|
Continuing.
|
Continuing.
|
|
|
Program exited normally.
|
Program exited normally.
|
(gdb)
|
(gdb)
|
|
|
However, there can be situations when there is no
|
However, there can be situations when there is no
|
corresponding name in XML file for that syscall number. In
|
corresponding name in XML file for that syscall number. In
|
this case, GDB prints a warning message saying that it was
|
this case, GDB prints a warning message saying that it was
|
not able to find the syscall name, but the catchpoint will be
|
not able to find the syscall name, but the catchpoint will be
|
set anyway. See the example below:
|
set anyway. See the example below:
|
|
|
(gdb) catch syscall 764
|
(gdb) catch syscall 764
|
warning: The number '764' does not represent a known syscall.
|
warning: The number '764' does not represent a known syscall.
|
Catchpoint 2 (syscall 764)
|
Catchpoint 2 (syscall 764)
|
(gdb)
|
(gdb)
|
|
|
If you configure GDB using the `--without-expat' option, it
|
If you configure GDB using the `--without-expat' option, it
|
will not be able to display syscall names. Also, if your
|
will not be able to display syscall names. Also, if your
|
architecture does not have an XML file describing its system
|
architecture does not have an XML file describing its system
|
calls, you will not be able to see the syscall names. It is
|
calls, you will not be able to see the syscall names. It is
|
important to notice that these two features are used for
|
important to notice that these two features are used for
|
accessing the syscall name database. In either case, you
|
accessing the syscall name database. In either case, you
|
will see a warning like this:
|
will see a warning like this:
|
|
|
(gdb) catch syscall
|
(gdb) catch syscall
|
warning: Could not open "syscalls/i386-linux.xml"
|
warning: Could not open "syscalls/i386-linux.xml"
|
warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
|
warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
|
GDB will not be able to display syscall names.
|
GDB will not be able to display syscall names.
|
Catchpoint 1 (syscall)
|
Catchpoint 1 (syscall)
|
(gdb)
|
(gdb)
|
|
|
Of course, the file name will change depending on your
|
Of course, the file name will change depending on your
|
architecture and system.
|
architecture and system.
|
|
|
Still using the example above, you can also try to catch a
|
Still using the example above, you can also try to catch a
|
syscall by its number. In this case, you would see something
|
syscall by its number. In this case, you would see something
|
like:
|
like:
|
|
|
(gdb) catch syscall 252
|
(gdb) catch syscall 252
|
Catchpoint 1 (syscall(s) 252)
|
Catchpoint 1 (syscall(s) 252)
|
|
|
Again, in this case GDB would not be able to display
|
Again, in this case GDB would not be able to display
|
syscall's names.
|
syscall's names.
|
|
|
`fork'
|
`fork'
|
A call to `fork'. This is currently only available for HP-UX
|
A call to `fork'. This is currently only available for HP-UX
|
and GNU/Linux.
|
and GNU/Linux.
|
|
|
`vfork'
|
`vfork'
|
A call to `vfork'. This is currently only available for HP-UX
|
A call to `vfork'. This is currently only available for HP-UX
|
and GNU/Linux.
|
and GNU/Linux.
|
|
|
|
|
`tcatch EVENT'
|
`tcatch EVENT'
|
Set a catchpoint that is enabled only for one stop. The
|
Set a catchpoint that is enabled only for one stop. The
|
catchpoint is automatically deleted after the first time the event
|
catchpoint is automatically deleted after the first time the event
|
is caught.
|
is caught.
|
|
|
|
|
Use the `info break' command to list the current catchpoints.
|
Use the `info break' command to list the current catchpoints.
|
|
|
There are currently some limitations to C++ exception handling
|
There are currently some limitations to C++ exception handling
|
(`catch throw' and `catch catch') in GDB:
|
(`catch throw' and `catch catch') in GDB:
|
|
|
* If you call a function interactively, GDB normally returns control
|
* If you call a function interactively, GDB normally returns control
|
to you when the function has finished executing. If the call
|
to you when the function has finished executing. If the call
|
raises an exception, however, the call may bypass the mechanism
|
raises an exception, however, the call may bypass the mechanism
|
that returns control to you and cause your program either to abort
|
that returns control to you and cause your program either to abort
|
or to simply continue running until it hits a breakpoint, catches
|
or to simply continue running until it hits a breakpoint, catches
|
a signal that GDB is listening for, or exits. This is the case
|
a signal that GDB is listening for, or exits. This is the case
|
even if you set a catchpoint for the exception; catchpoints on
|
even if you set a catchpoint for the exception; catchpoints on
|
exceptions are disabled within interactive calls.
|
exceptions are disabled within interactive calls.
|
|
|
* You cannot raise an exception interactively.
|
* You cannot raise an exception interactively.
|
|
|
* You cannot install an exception handler interactively.
|
* You cannot install an exception handler interactively.
|
|
|
Sometimes `catch' is not the best way to debug exception handling:
|
Sometimes `catch' is not the best way to debug exception handling:
|
if you need to know exactly where an exception is raised, it is better
|
if you need to know exactly where an exception is raised, it is better
|
to stop _before_ the exception handler is called, since that way you
|
to stop _before_ the exception handler is called, since that way you
|
can see the stack before any unwinding takes place. If you set a
|
can see the stack before any unwinding takes place. If you set a
|
breakpoint in an exception handler instead, it may not be easy to find
|
breakpoint in an exception handler instead, it may not be easy to find
|
out where the exception was raised.
|
out where the exception was raised.
|
|
|
To stop just before an exception handler is called, you need some
|
To stop just before an exception handler is called, you need some
|
knowledge of the implementation. In the case of GNU C++, exceptions are
|
knowledge of the implementation. In the case of GNU C++, exceptions are
|
raised by calling a library function named `__raise_exception' which
|
raised by calling a library function named `__raise_exception' which
|
has the following ANSI C interface:
|
has the following ANSI C interface:
|
|
|
/* ADDR is where the exception identifier is stored.
|
/* ADDR is where the exception identifier is stored.
|
ID is the exception identifier. */
|
ID is the exception identifier. */
|
void __raise_exception (void **addr, void *id);
|
void __raise_exception (void **addr, void *id);
|
|
|
To make the debugger catch all exceptions before any stack unwinding
|
To make the debugger catch all exceptions before any stack unwinding
|
takes place, set a breakpoint on `__raise_exception' (*note
|
takes place, set a breakpoint on `__raise_exception' (*note
|
Breakpoints; Watchpoints; and Exceptions: Breakpoints.).
|
Breakpoints; Watchpoints; and Exceptions: Breakpoints.).
|
|
|
With a conditional breakpoint (*note Break Conditions: Conditions.)
|
With a conditional breakpoint (*note Break Conditions: Conditions.)
|
that depends on the value of ID, you can stop your program when a
|
that depends on the value of ID, you can stop your program when a
|
specific exception is raised. You can use multiple conditional
|
specific exception is raised. You can use multiple conditional
|
breakpoints to stop your program when any of a number of exceptions are
|
breakpoints to stop your program when any of a number of exceptions are
|
raised.
|
raised.
|
|
|
|
|
File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints
|
File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints
|
|
|
5.1.4 Deleting Breakpoints
|
5.1.4 Deleting Breakpoints
|
--------------------------
|
--------------------------
|
|
|
It is often necessary to eliminate a breakpoint, watchpoint, or
|
It is often necessary to eliminate a breakpoint, watchpoint, or
|
catchpoint once it has done its job and you no longer want your program
|
catchpoint once it has done its job and you no longer want your program
|
to stop there. This is called "deleting" the breakpoint. A breakpoint
|
to stop there. This is called "deleting" the breakpoint. A breakpoint
|
that has been deleted no longer exists; it is forgotten.
|
that has been deleted no longer exists; it is forgotten.
|
|
|
With the `clear' command you can delete breakpoints according to
|
With the `clear' command you can delete breakpoints according to
|
where they are in your program. With the `delete' command you can
|
where they are in your program. With the `delete' command you can
|
delete individual breakpoints, watchpoints, or catchpoints by specifying
|
delete individual breakpoints, watchpoints, or catchpoints by specifying
|
their breakpoint numbers.
|
their breakpoint numbers.
|
|
|
It is not necessary to delete a breakpoint to proceed past it. GDB
|
It is not necessary to delete a breakpoint to proceed past it. GDB
|
automatically ignores breakpoints on the first instruction to be
|
automatically ignores breakpoints on the first instruction to be
|
executed when you continue execution without changing the execution
|
executed when you continue execution without changing the execution
|
address.
|
address.
|
|
|
`clear'
|
`clear'
|
Delete any breakpoints at the next instruction to be executed in
|
Delete any breakpoints at the next instruction to be executed in
|
the selected stack frame (*note Selecting a Frame: Selection.).
|
the selected stack frame (*note Selecting a Frame: Selection.).
|
When the innermost frame is selected, this is a good way to delete
|
When the innermost frame is selected, this is a good way to delete
|
a breakpoint where your program just stopped.
|
a breakpoint where your program just stopped.
|
|
|
`clear LOCATION'
|
`clear LOCATION'
|
Delete any breakpoints set at the specified LOCATION. *Note
|
Delete any breakpoints set at the specified LOCATION. *Note
|
Specify Location::, for the various forms of LOCATION; the most
|
Specify Location::, for the various forms of LOCATION; the most
|
useful ones are listed below:
|
useful ones are listed below:
|
|
|
`clear FUNCTION'
|
`clear FUNCTION'
|
`clear FILENAME:FUNCTION'
|
`clear FILENAME:FUNCTION'
|
Delete any breakpoints set at entry to the named FUNCTION.
|
Delete any breakpoints set at entry to the named FUNCTION.
|
|
|
`clear LINENUM'
|
`clear LINENUM'
|
`clear FILENAME:LINENUM'
|
`clear FILENAME:LINENUM'
|
Delete any breakpoints set at or within the code of the
|
Delete any breakpoints set at or within the code of the
|
specified LINENUM of the specified FILENAME.
|
specified LINENUM of the specified FILENAME.
|
|
|
`delete [breakpoints] [RANGE...]'
|
`delete [breakpoints] [RANGE...]'
|
Delete the breakpoints, watchpoints, or catchpoints of the
|
Delete the breakpoints, watchpoints, or catchpoints of the
|
breakpoint ranges specified as arguments. If no argument is
|
breakpoint ranges specified as arguments. If no argument is
|
specified, delete all breakpoints (GDB asks confirmation, unless
|
specified, delete all breakpoints (GDB asks confirmation, unless
|
you have `set confirm off'). You can abbreviate this command as
|
you have `set confirm off'). You can abbreviate this command as
|
`d'.
|
`d'.
|
|
|
|
|
File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints
|
File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints
|
|
|
5.1.5 Disabling Breakpoints
|
5.1.5 Disabling Breakpoints
|
---------------------------
|
---------------------------
|
|
|
Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
|
Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
|
prefer to "disable" it. This makes the breakpoint inoperative as if it
|
prefer to "disable" it. This makes the breakpoint inoperative as if it
|
had been deleted, but remembers the information on the breakpoint so
|
had been deleted, but remembers the information on the breakpoint so
|
that you can "enable" it again later.
|
that you can "enable" it again later.
|
|
|
You disable and enable breakpoints, watchpoints, and catchpoints with
|
You disable and enable breakpoints, watchpoints, and catchpoints with
|
the `enable' and `disable' commands, optionally specifying one or more
|
the `enable' and `disable' commands, optionally specifying one or more
|
breakpoint numbers as arguments. Use `info break' to print a list of
|
breakpoint numbers as arguments. Use `info break' to print a list of
|
all breakpoints, watchpoints, and catchpoints if you do not know which
|
all breakpoints, watchpoints, and catchpoints if you do not know which
|
numbers to use.
|
numbers to use.
|
|
|
Disabling and enabling a breakpoint that has multiple locations
|
Disabling and enabling a breakpoint that has multiple locations
|
affects all of its locations.
|
affects all of its locations.
|
|
|
A breakpoint, watchpoint, or catchpoint can have any of four
|
A breakpoint, watchpoint, or catchpoint can have any of four
|
different states of enablement:
|
different states of enablement:
|
|
|
* Enabled. The breakpoint stops your program. A breakpoint set
|
* Enabled. The breakpoint stops your program. A breakpoint set
|
with the `break' command starts out in this state.
|
with the `break' command starts out in this state.
|
|
|
* Disabled. The breakpoint has no effect on your program.
|
* Disabled. The breakpoint has no effect on your program.
|
|
|
* Enabled once. The breakpoint stops your program, but then becomes
|
* Enabled once. The breakpoint stops your program, but then becomes
|
disabled.
|
disabled.
|
|
|
* Enabled for deletion. The breakpoint stops your program, but
|
* Enabled for deletion. The breakpoint stops your program, but
|
immediately after it does so it is deleted permanently. A
|
immediately after it does so it is deleted permanently. A
|
breakpoint set with the `tbreak' command starts out in this state.
|
breakpoint set with the `tbreak' command starts out in this state.
|
|
|
You can use the following commands to enable or disable breakpoints,
|
You can use the following commands to enable or disable breakpoints,
|
watchpoints, and catchpoints:
|
watchpoints, and catchpoints:
|
|
|
`disable [breakpoints] [RANGE...]'
|
`disable [breakpoints] [RANGE...]'
|
Disable the specified breakpoints--or all breakpoints, if none are
|
Disable the specified breakpoints--or all breakpoints, if none are
|
listed. A disabled breakpoint has no effect but is not forgotten.
|
listed. A disabled breakpoint has no effect but is not forgotten.
|
All options such as ignore-counts, conditions and commands are
|
All options such as ignore-counts, conditions and commands are
|
remembered in case the breakpoint is enabled again later. You may
|
remembered in case the breakpoint is enabled again later. You may
|
abbreviate `disable' as `dis'.
|
abbreviate `disable' as `dis'.
|
|
|
`enable [breakpoints] [RANGE...]'
|
`enable [breakpoints] [RANGE...]'
|
Enable the specified breakpoints (or all defined breakpoints).
|
Enable the specified breakpoints (or all defined breakpoints).
|
They become effective once again in stopping your program.
|
They become effective once again in stopping your program.
|
|
|
`enable [breakpoints] once RANGE...'
|
`enable [breakpoints] once RANGE...'
|
Enable the specified breakpoints temporarily. GDB disables any of
|
Enable the specified breakpoints temporarily. GDB disables any of
|
these breakpoints immediately after stopping your program.
|
these breakpoints immediately after stopping your program.
|
|
|
`enable [breakpoints] delete RANGE...'
|
`enable [breakpoints] delete RANGE...'
|
Enable the specified breakpoints to work once, then die. GDB
|
Enable the specified breakpoints to work once, then die. GDB
|
deletes any of these breakpoints as soon as your program stops
|
deletes any of these breakpoints as soon as your program stops
|
there. Breakpoints set by the `tbreak' command start out in this
|
there. Breakpoints set by the `tbreak' command start out in this
|
state.
|
state.
|
|
|
Except for a breakpoint set with `tbreak' (*note Setting
|
Except for a breakpoint set with `tbreak' (*note Setting
|
Breakpoints: Set Breaks.), breakpoints that you set are initially
|
Breakpoints: Set Breaks.), breakpoints that you set are initially
|
enabled; subsequently, they become disabled or enabled only when you
|
enabled; subsequently, they become disabled or enabled only when you
|
use one of the commands above. (The command `until' can set and delete
|
use one of the commands above. (The command `until' can set and delete
|
a breakpoint of its own, but it does not change the state of your other
|
a breakpoint of its own, but it does not change the state of your other
|
breakpoints; see *note Continuing and Stepping: Continuing and
|
breakpoints; see *note Continuing and Stepping: Continuing and
|
Stepping.)
|
Stepping.)
|
|
|
|
|
File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints
|
File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints
|
|
|
5.1.6 Break Conditions
|
5.1.6 Break Conditions
|
----------------------
|
----------------------
|
|
|
The simplest sort of breakpoint breaks every time your program reaches a
|
The simplest sort of breakpoint breaks every time your program reaches a
|
specified place. You can also specify a "condition" for a breakpoint.
|
specified place. You can also specify a "condition" for a breakpoint.
|
A condition is just a Boolean expression in your programming language
|
A condition is just a Boolean expression in your programming language
|
(*note Expressions: Expressions.). A breakpoint with a condition
|
(*note Expressions: Expressions.). A breakpoint with a condition
|
evaluates the expression each time your program reaches it, and your
|
evaluates the expression each time your program reaches it, and your
|
program stops only if the condition is _true_.
|
program stops only if the condition is _true_.
|
|
|
This is the converse of using assertions for program validation; in
|
This is the converse of using assertions for program validation; in
|
that situation, you want to stop when the assertion is violated--that
|
that situation, you want to stop when the assertion is violated--that
|
is, when the condition is false. In C, if you want to test an
|
is, when the condition is false. In C, if you want to test an
|
assertion expressed by the condition ASSERT, you should set the
|
assertion expressed by the condition ASSERT, you should set the
|
condition `! ASSERT' on the appropriate breakpoint.
|
condition `! ASSERT' on the appropriate breakpoint.
|
|
|
Conditions are also accepted for watchpoints; you may not need them,
|
Conditions are also accepted for watchpoints; you may not need them,
|
since a watchpoint is inspecting the value of an expression anyhow--but
|
since a watchpoint is inspecting the value of an expression anyhow--but
|
it might be simpler, say, to just set a watchpoint on a variable name,
|
it might be simpler, say, to just set a watchpoint on a variable name,
|
and specify a condition that tests whether the new value is an
|
and specify a condition that tests whether the new value is an
|
interesting one.
|
interesting one.
|
|
|
Break conditions can have side effects, and may even call functions
|
Break conditions can have side effects, and may even call functions
|
in your program. This can be useful, for example, to activate functions
|
in your program. This can be useful, for example, to activate functions
|
that log program progress, or to use your own print functions to format
|
that log program progress, or to use your own print functions to format
|
special data structures. The effects are completely predictable unless
|
special data structures. The effects are completely predictable unless
|
there is another enabled breakpoint at the same address. (In that
|
there is another enabled breakpoint at the same address. (In that
|
case, GDB might see the other breakpoint first and stop your program
|
case, GDB might see the other breakpoint first and stop your program
|
without checking the condition of this one.) Note that breakpoint
|
without checking the condition of this one.) Note that breakpoint
|
commands are usually more convenient and flexible than break conditions
|
commands are usually more convenient and flexible than break conditions
|
for the purpose of performing side effects when a breakpoint is reached
|
for the purpose of performing side effects when a breakpoint is reached
|
(*note Breakpoint Command Lists: Break Commands.).
|
(*note Breakpoint Command Lists: Break Commands.).
|
|
|
Break conditions can be specified when a breakpoint is set, by using
|
Break conditions can be specified when a breakpoint is set, by using
|
`if' in the arguments to the `break' command. *Note Setting
|
`if' in the arguments to the `break' command. *Note Setting
|
Breakpoints: Set Breaks. They can also be changed at any time with the
|
Breakpoints: Set Breaks. They can also be changed at any time with the
|
`condition' command.
|
`condition' command.
|
|
|
You can also use the `if' keyword with the `watch' command. The
|
You can also use the `if' keyword with the `watch' command. The
|
`catch' command does not recognize the `if' keyword; `condition' is the
|
`catch' command does not recognize the `if' keyword; `condition' is the
|
only way to impose a further condition on a catchpoint.
|
only way to impose a further condition on a catchpoint.
|
|
|
`condition BNUM EXPRESSION'
|
`condition BNUM EXPRESSION'
|
Specify EXPRESSION as the break condition for breakpoint,
|
Specify EXPRESSION as the break condition for breakpoint,
|
watchpoint, or catchpoint number BNUM. After you set a condition,
|
watchpoint, or catchpoint number BNUM. After you set a condition,
|
breakpoint BNUM stops your program only if the value of EXPRESSION
|
breakpoint BNUM stops your program only if the value of EXPRESSION
|
is true (nonzero, in C). When you use `condition', GDB checks
|
is true (nonzero, in C). When you use `condition', GDB checks
|
EXPRESSION immediately for syntactic correctness, and to determine
|
EXPRESSION immediately for syntactic correctness, and to determine
|
whether symbols in it have referents in the context of your
|
whether symbols in it have referents in the context of your
|
breakpoint. If EXPRESSION uses symbols not referenced in the
|
breakpoint. If EXPRESSION uses symbols not referenced in the
|
context of the breakpoint, GDB prints an error message:
|
context of the breakpoint, GDB prints an error message:
|
|
|
No symbol "foo" in current context.
|
No symbol "foo" in current context.
|
|
|
GDB does not actually evaluate EXPRESSION at the time the
|
GDB does not actually evaluate EXPRESSION at the time the
|
`condition' command (or a command that sets a breakpoint with a
|
`condition' command (or a command that sets a breakpoint with a
|
condition, like `break if ...') is given, however. *Note
|
condition, like `break if ...') is given, however. *Note
|
Expressions: Expressions.
|
Expressions: Expressions.
|
|
|
`condition BNUM'
|
`condition BNUM'
|
Remove the condition from breakpoint number BNUM. It becomes an
|
Remove the condition from breakpoint number BNUM. It becomes an
|
ordinary unconditional breakpoint.
|
ordinary unconditional breakpoint.
|
|
|
A special case of a breakpoint condition is to stop only when the
|
A special case of a breakpoint condition is to stop only when the
|
breakpoint has been reached a certain number of times. This is so
|
breakpoint has been reached a certain number of times. This is so
|
useful that there is a special way to do it, using the "ignore count"
|
useful that there is a special way to do it, using the "ignore count"
|
of the breakpoint. Every breakpoint has an ignore count, which is an
|
of the breakpoint. Every breakpoint has an ignore count, which is an
|
integer. Most of the time, the ignore count is zero, and therefore has
|
integer. Most of the time, the ignore count is zero, and therefore has
|
no effect. But if your program reaches a breakpoint whose ignore count
|
no effect. But if your program reaches a breakpoint whose ignore count
|
is positive, then instead of stopping, it just decrements the ignore
|
is positive, then instead of stopping, it just decrements the ignore
|
count by one and continues. As a result, if the ignore count value is
|
count by one and continues. As a result, if the ignore count value is
|
N, the breakpoint does not stop the next N times your program reaches
|
N, the breakpoint does not stop the next N times your program reaches
|
it.
|
it.
|
|
|
`ignore BNUM COUNT'
|
`ignore BNUM COUNT'
|
Set the ignore count of breakpoint number BNUM to COUNT. The next
|
Set the ignore count of breakpoint number BNUM to COUNT. The next
|
COUNT times the breakpoint is reached, your program's execution
|
COUNT times the breakpoint is reached, your program's execution
|
does not stop; other than to decrement the ignore count, GDB takes
|
does not stop; other than to decrement the ignore count, GDB takes
|
no action.
|
no action.
|
|
|
To make the breakpoint stop the next time it is reached, specify a
|
To make the breakpoint stop the next time it is reached, specify a
|
count of zero.
|
count of zero.
|
|
|
When you use `continue' to resume execution of your program from a
|
When you use `continue' to resume execution of your program from a
|
breakpoint, you can specify an ignore count directly as an
|
breakpoint, you can specify an ignore count directly as an
|
argument to `continue', rather than using `ignore'. *Note
|
argument to `continue', rather than using `ignore'. *Note
|
Continuing and Stepping: Continuing and Stepping.
|
Continuing and Stepping: Continuing and Stepping.
|
|
|
If a breakpoint has a positive ignore count and a condition, the
|
If a breakpoint has a positive ignore count and a condition, the
|
condition is not checked. Once the ignore count reaches zero, GDB
|
condition is not checked. Once the ignore count reaches zero, GDB
|
resumes checking the condition.
|
resumes checking the condition.
|
|
|
You could achieve the effect of the ignore count with a condition
|
You could achieve the effect of the ignore count with a condition
|
such as `$foo-- <= 0' using a debugger convenience variable that
|
such as `$foo-- <= 0' using a debugger convenience variable that
|
is decremented each time. *Note Convenience Variables:
|
is decremented each time. *Note Convenience Variables:
|
Convenience Vars.
|
Convenience Vars.
|
|
|
Ignore counts apply to breakpoints, watchpoints, and catchpoints.
|
Ignore counts apply to breakpoints, watchpoints, and catchpoints.
|
|
|
|
|
File: gdb.info, Node: Break Commands, Next: Save Breakpoints, Prev: Conditions, Up: Breakpoints
|
File: gdb.info, Node: Break Commands, Next: Save Breakpoints, Prev: Conditions, Up: Breakpoints
|
|
|
5.1.7 Breakpoint Command Lists
|
5.1.7 Breakpoint Command Lists
|
------------------------------
|
------------------------------
|
|
|
You can give any breakpoint (or watchpoint or catchpoint) a series of
|
You can give any breakpoint (or watchpoint or catchpoint) a series of
|
commands to execute when your program stops due to that breakpoint. For
|
commands to execute when your program stops due to that breakpoint. For
|
example, you might want to print the values of certain expressions, or
|
example, you might want to print the values of certain expressions, or
|
enable other breakpoints.
|
enable other breakpoints.
|
|
|
`commands [RANGE...]'
|
`commands [RANGE...]'
|
`... COMMAND-LIST ...'
|
`... COMMAND-LIST ...'
|
`end'
|
`end'
|
Specify a list of commands for the given breakpoints. The commands
|
Specify a list of commands for the given breakpoints. The commands
|
themselves appear on the following lines. Type a line containing
|
themselves appear on the following lines. Type a line containing
|
just `end' to terminate the commands.
|
just `end' to terminate the commands.
|
|
|
To remove all commands from a breakpoint, type `commands' and
|
To remove all commands from a breakpoint, type `commands' and
|
follow it immediately with `end'; that is, give no commands.
|
follow it immediately with `end'; that is, give no commands.
|
|
|
With no argument, `commands' refers to the last breakpoint,
|
With no argument, `commands' refers to the last breakpoint,
|
watchpoint, or catchpoint set (not to the breakpoint most recently
|
watchpoint, or catchpoint set (not to the breakpoint most recently
|
encountered). If the most recent breakpoints were set with a
|
encountered). If the most recent breakpoints were set with a
|
single command, then the `commands' will apply to all the
|
single command, then the `commands' will apply to all the
|
breakpoints set by that command. This applies to breakpoints set
|
breakpoints set by that command. This applies to breakpoints set
|
by `rbreak', and also applies when a single `break' command
|
by `rbreak', and also applies when a single `break' command
|
creates multiple breakpoints (*note Ambiguous Expressions:
|
creates multiple breakpoints (*note Ambiguous Expressions:
|
Ambiguous Expressions.).
|
Ambiguous Expressions.).
|
|
|
Pressing as a means of repeating the last GDB command is
|
Pressing as a means of repeating the last GDB command is
|
disabled within a COMMAND-LIST.
|
disabled within a COMMAND-LIST.
|
|
|
You can use breakpoint commands to start your program up again.
|
You can use breakpoint commands to start your program up again.
|
Simply use the `continue' command, or `step', or any other command that
|
Simply use the `continue' command, or `step', or any other command that
|
resumes execution.
|
resumes execution.
|
|
|
Any other commands in the command list, after a command that resumes
|
Any other commands in the command list, after a command that resumes
|
execution, are ignored. This is because any time you resume execution
|
execution, are ignored. This is because any time you resume execution
|
(even with a simple `next' or `step'), you may encounter another
|
(even with a simple `next' or `step'), you may encounter another
|
breakpoint--which could have its own command list, leading to
|
breakpoint--which could have its own command list, leading to
|
ambiguities about which list to execute.
|
ambiguities about which list to execute.
|
|
|
If the first command you specify in a command list is `silent', the
|
If the first command you specify in a command list is `silent', the
|
usual message about stopping at a breakpoint is not printed. This may
|
usual message about stopping at a breakpoint is not printed. This may
|
be desirable for breakpoints that are to print a specific message and
|
be desirable for breakpoints that are to print a specific message and
|
then continue. If none of the remaining commands print anything, you
|
then continue. If none of the remaining commands print anything, you
|
see no sign that the breakpoint was reached. `silent' is meaningful
|
see no sign that the breakpoint was reached. `silent' is meaningful
|
only at the beginning of a breakpoint command list.
|
only at the beginning of a breakpoint command list.
|
|
|
The commands `echo', `output', and `printf' allow you to print
|
The commands `echo', `output', and `printf' allow you to print
|
precisely controlled output, and are often useful in silent
|
precisely controlled output, and are often useful in silent
|
breakpoints. *Note Commands for Controlled Output: Output.
|
breakpoints. *Note Commands for Controlled Output: Output.
|
|
|
For example, here is how you could use breakpoint commands to print
|
For example, here is how you could use breakpoint commands to print
|
the value of `x' at entry to `foo' whenever `x' is positive.
|
the value of `x' at entry to `foo' whenever `x' is positive.
|
|
|
break foo if x>0
|
break foo if x>0
|
commands
|
commands
|
silent
|
silent
|
printf "x is %d\n",x
|
printf "x is %d\n",x
|
cont
|
cont
|
end
|
end
|
|
|
One application for breakpoint commands is to compensate for one bug
|
One application for breakpoint commands is to compensate for one bug
|
so you can test for another. Put a breakpoint just after the erroneous
|
so you can test for another. Put a breakpoint just after the erroneous
|
line of code, give it a condition to detect the case in which something
|
line of code, give it a condition to detect the case in which something
|
erroneous has been done, and give it commands to assign correct values
|
erroneous has been done, and give it commands to assign correct values
|
to any variables that need them. End with the `continue' command so
|
to any variables that need them. End with the `continue' command so
|
that your program does not stop, and start with the `silent' command so
|
that your program does not stop, and start with the `silent' command so
|
that no output is produced. Here is an example:
|
that no output is produced. Here is an example:
|
|
|
break 403
|
break 403
|
commands
|
commands
|
silent
|
silent
|
set x = y + 4
|
set x = y + 4
|
cont
|
cont
|
end
|
end
|
|
|
|
|
File: gdb.info, Node: Save Breakpoints, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints
|
File: gdb.info, Node: Save Breakpoints, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints
|
|
|
5.1.8 How to save breakpoints to a file
|
5.1.8 How to save breakpoints to a file
|
---------------------------------------
|
---------------------------------------
|
|
|
To save breakpoint definitions to a file use the `save breakpoints'
|
To save breakpoint definitions to a file use the `save breakpoints'
|
command.
|
command.
|
|
|
`save breakpoints [FILENAME]'
|
`save breakpoints [FILENAME]'
|
This command saves all current breakpoint definitions together with
|
This command saves all current breakpoint definitions together with
|
their commands and ignore counts, into a file `FILENAME' suitable
|
their commands and ignore counts, into a file `FILENAME' suitable
|
for use in a later debugging session. This includes all types of
|
for use in a later debugging session. This includes all types of
|
breakpoints (breakpoints, watchpoints, catchpoints, tracepoints).
|
breakpoints (breakpoints, watchpoints, catchpoints, tracepoints).
|
To read the saved breakpoint definitions, use the `source' command
|
To read the saved breakpoint definitions, use the `source' command
|
(*note Command Files::). Note that watchpoints with expressions
|
(*note Command Files::). Note that watchpoints with expressions
|
involving local variables may fail to be recreated because it may
|
involving local variables may fail to be recreated because it may
|
not be possible to access the context where the watchpoint is
|
not be possible to access the context where the watchpoint is
|
valid anymore. Because the saved breakpoint definitions are
|
valid anymore. Because the saved breakpoint definitions are
|
simply a sequence of GDB commands that recreate the breakpoints,
|
simply a sequence of GDB commands that recreate the breakpoints,
|
you can edit the file in your favorite editing program, and remove
|
you can edit the file in your favorite editing program, and remove
|
the breakpoint definitions you're not interested in, or that can
|
the breakpoint definitions you're not interested in, or that can
|
no longer be recreated.
|
no longer be recreated.
|
|
|
|
|
File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Save Breakpoints, Up: Breakpoints
|
File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Save Breakpoints, Up: Breakpoints
|
|
|
5.1.9 "Cannot insert breakpoints"
|
5.1.9 "Cannot insert breakpoints"
|
---------------------------------
|
---------------------------------
|
|
|
If you request too many active hardware-assisted breakpoints and
|
If you request too many active hardware-assisted breakpoints and
|
watchpoints, you will see this error message:
|
watchpoints, you will see this error message:
|
|
|
Stopped; cannot insert breakpoints.
|
Stopped; cannot insert breakpoints.
|
You may have requested too many hardware breakpoints and watchpoints.
|
You may have requested too many hardware breakpoints and watchpoints.
|
|
|
This message is printed when you attempt to resume the program, since
|
This message is printed when you attempt to resume the program, since
|
only then GDB knows exactly how many hardware breakpoints and
|
only then GDB knows exactly how many hardware breakpoints and
|
watchpoints it needs to insert.
|
watchpoints it needs to insert.
|
|
|
When this message is printed, you need to disable or remove some of
|
When this message is printed, you need to disable or remove some of
|
the hardware-assisted breakpoints and watchpoints, and then continue.
|
the hardware-assisted breakpoints and watchpoints, and then continue.
|
|
|
|
|
File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints
|
File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints
|
|
|
5.1.10 "Breakpoint address adjusted..."
|
5.1.10 "Breakpoint address adjusted..."
|
---------------------------------------
|
---------------------------------------
|
|
|
Some processor architectures place constraints on the addresses at
|
Some processor architectures place constraints on the addresses at
|
which breakpoints may be placed. For architectures thus constrained,
|
which breakpoints may be placed. For architectures thus constrained,
|
GDB will attempt to adjust the breakpoint's address to comply with the
|
GDB will attempt to adjust the breakpoint's address to comply with the
|
constraints dictated by the architecture.
|
constraints dictated by the architecture.
|
|
|
One example of such an architecture is the Fujitsu FR-V. The FR-V is
|
One example of such an architecture is the Fujitsu FR-V. The FR-V is
|
a VLIW architecture in which a number of RISC-like instructions may be
|
a VLIW architecture in which a number of RISC-like instructions may be
|
bundled together for parallel execution. The FR-V architecture
|
bundled together for parallel execution. The FR-V architecture
|
constrains the location of a breakpoint instruction within such a
|
constrains the location of a breakpoint instruction within such a
|
bundle to the instruction with the lowest address. GDB honors this
|
bundle to the instruction with the lowest address. GDB honors this
|
constraint by adjusting a breakpoint's address to the first in the
|
constraint by adjusting a breakpoint's address to the first in the
|
bundle.
|
bundle.
|
|
|
It is not uncommon for optimized code to have bundles which contain
|
It is not uncommon for optimized code to have bundles which contain
|
instructions from different source statements, thus it may happen that
|
instructions from different source statements, thus it may happen that
|
a breakpoint's address will be adjusted from one source statement to
|
a breakpoint's address will be adjusted from one source statement to
|
another. Since this adjustment may significantly alter GDB's
|
another. Since this adjustment may significantly alter GDB's
|
breakpoint related behavior from what the user expects, a warning is
|
breakpoint related behavior from what the user expects, a warning is
|
printed when the breakpoint is first set and also when the breakpoint
|
printed when the breakpoint is first set and also when the breakpoint
|
is hit.
|
is hit.
|
|
|
A warning like the one below is printed when setting a breakpoint
|
A warning like the one below is printed when setting a breakpoint
|
that's been subject to address adjustment:
|
that's been subject to address adjustment:
|
|
|
warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
|
warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
|
|
|
Such warnings are printed both for user settable and GDB's internal
|
Such warnings are printed both for user settable and GDB's internal
|
breakpoints. If you see one of these warnings, you should verify that
|
breakpoints. If you see one of these warnings, you should verify that
|
a breakpoint set at the adjusted address will have the desired affect.
|
a breakpoint set at the adjusted address will have the desired affect.
|
If not, the breakpoint in question may be removed and other breakpoints
|
If not, the breakpoint in question may be removed and other breakpoints
|
may be set which will have the desired behavior. E.g., it may be
|
may be set which will have the desired behavior. E.g., it may be
|
sufficient to place the breakpoint at a later instruction. A
|
sufficient to place the breakpoint at a later instruction. A
|
conditional breakpoint may also be useful in some cases to prevent the
|
conditional breakpoint may also be useful in some cases to prevent the
|
breakpoint from triggering too often.
|
breakpoint from triggering too often.
|
|
|
GDB will also issue a warning when stopping at one of these adjusted
|
GDB will also issue a warning when stopping at one of these adjusted
|
breakpoints:
|
breakpoints:
|
|
|
warning: Breakpoint 1 address previously adjusted from 0x00010414
|
warning: Breakpoint 1 address previously adjusted from 0x00010414
|
to 0x00010410.
|
to 0x00010410.
|
|
|
When this warning is encountered, it may be too late to take remedial
|
When this warning is encountered, it may be too late to take remedial
|
action except in cases where the breakpoint is hit earlier or more
|
action except in cases where the breakpoint is hit earlier or more
|
frequently than expected.
|
frequently than expected.
|
|
|
|
|
File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping
|
File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping
|
|
|
5.2 Continuing and Stepping
|
5.2 Continuing and Stepping
|
===========================
|
===========================
|
|
|
"Continuing" means resuming program execution until your program
|
"Continuing" means resuming program execution until your program
|
completes normally. In contrast, "stepping" means executing just one
|
completes normally. In contrast, "stepping" means executing just one
|
more "step" of your program, where "step" may mean either one line of
|
more "step" of your program, where "step" may mean either one line of
|
source code, or one machine instruction (depending on what particular
|
source code, or one machine instruction (depending on what particular
|
command you use). Either when continuing or when stepping, your
|
command you use). Either when continuing or when stepping, your
|
program may stop even sooner, due to a breakpoint or a signal. (If it
|
program may stop even sooner, due to a breakpoint or a signal. (If it
|
stops due to a signal, you may want to use `handle', or use `signal 0'
|
stops due to a signal, you may want to use `handle', or use `signal 0'
|
to resume execution. *Note Signals: Signals.)
|
to resume execution. *Note Signals: Signals.)
|
|
|
`continue [IGNORE-COUNT]'
|
`continue [IGNORE-COUNT]'
|
`c [IGNORE-COUNT]'
|
`c [IGNORE-COUNT]'
|
`fg [IGNORE-COUNT]'
|
`fg [IGNORE-COUNT]'
|
Resume program execution, at the address where your program last
|
Resume program execution, at the address where your program last
|
stopped; any breakpoints set at that address are bypassed. The
|
stopped; any breakpoints set at that address are bypassed. The
|
optional argument IGNORE-COUNT allows you to specify a further
|
optional argument IGNORE-COUNT allows you to specify a further
|
number of times to ignore a breakpoint at this location; its
|
number of times to ignore a breakpoint at this location; its
|
effect is like that of `ignore' (*note Break Conditions:
|
effect is like that of `ignore' (*note Break Conditions:
|
Conditions.).
|
Conditions.).
|
|
|
The argument IGNORE-COUNT is meaningful only when your program
|
The argument IGNORE-COUNT is meaningful only when your program
|
stopped due to a breakpoint. At other times, the argument to
|
stopped due to a breakpoint. At other times, the argument to
|
`continue' is ignored.
|
`continue' is ignored.
|
|
|
The synonyms `c' and `fg' (for "foreground", as the debugged
|
The synonyms `c' and `fg' (for "foreground", as the debugged
|
program is deemed to be the foreground program) are provided
|
program is deemed to be the foreground program) are provided
|
purely for convenience, and have exactly the same behavior as
|
purely for convenience, and have exactly the same behavior as
|
`continue'.
|
`continue'.
|
|
|
To resume execution at a different place, you can use `return'
|
To resume execution at a different place, you can use `return'
|
(*note Returning from a Function: Returning.) to go back to the calling
|
(*note Returning from a Function: Returning.) to go back to the calling
|
function; or `jump' (*note Continuing at a Different Address: Jumping.)
|
function; or `jump' (*note Continuing at a Different Address: Jumping.)
|
to go to an arbitrary location in your program.
|
to go to an arbitrary location in your program.
|
|
|
A typical technique for using stepping is to set a breakpoint (*note
|
A typical technique for using stepping is to set a breakpoint (*note
|
Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the
|
Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the
|
beginning of the function or the section of your program where a problem
|
beginning of the function or the section of your program where a problem
|
is believed to lie, run your program until it stops at that breakpoint,
|
is believed to lie, run your program until it stops at that breakpoint,
|
and then step through the suspect area, examining the variables that are
|
and then step through the suspect area, examining the variables that are
|
interesting, until you see the problem happen.
|
interesting, until you see the problem happen.
|
|
|
`step'
|
`step'
|
Continue running your program until control reaches a different
|
Continue running your program until control reaches a different
|
source line, then stop it and return control to GDB. This command
|
source line, then stop it and return control to GDB. This command
|
is abbreviated `s'.
|
is abbreviated `s'.
|
|
|
_Warning:_ If you use the `step' command while control is
|
_Warning:_ If you use the `step' command while control is
|
within a function that was compiled without debugging
|
within a function that was compiled without debugging
|
information, execution proceeds until control reaches a
|
information, execution proceeds until control reaches a
|
function that does have debugging information. Likewise, it
|
function that does have debugging information. Likewise, it
|
will not step into a function which is compiled without
|
will not step into a function which is compiled without
|
debugging information. To step through functions without
|
debugging information. To step through functions without
|
debugging information, use the `stepi' command, described
|
debugging information, use the `stepi' command, described
|
below.
|
below.
|
|
|
The `step' command only stops at the first instruction of a source
|
The `step' command only stops at the first instruction of a source
|
line. This prevents the multiple stops that could otherwise occur
|
line. This prevents the multiple stops that could otherwise occur
|
in `switch' statements, `for' loops, etc. `step' continues to
|
in `switch' statements, `for' loops, etc. `step' continues to
|
stop if a function that has debugging information is called within
|
stop if a function that has debugging information is called within
|
the line. In other words, `step' _steps inside_ any functions
|
the line. In other words, `step' _steps inside_ any functions
|
called within the line.
|
called within the line.
|
|
|
Also, the `step' command only enters a function if there is line
|
Also, the `step' command only enters a function if there is line
|
number information for the function. Otherwise it acts like the
|
number information for the function. Otherwise it acts like the
|
`next' command. This avoids problems when using `cc -gl' on MIPS
|
`next' command. This avoids problems when using `cc -gl' on MIPS
|
machines. Previously, `step' entered subroutines if there was any
|
machines. Previously, `step' entered subroutines if there was any
|
debugging information about the routine.
|
debugging information about the routine.
|
|
|
`step COUNT'
|
`step COUNT'
|
Continue running as in `step', but do so COUNT times. If a
|
Continue running as in `step', but do so COUNT times. If a
|
breakpoint is reached, or a signal not related to stepping occurs
|
breakpoint is reached, or a signal not related to stepping occurs
|
before COUNT steps, stepping stops right away.
|
before COUNT steps, stepping stops right away.
|
|
|
`next [COUNT]'
|
`next [COUNT]'
|
Continue to the next source line in the current (innermost) stack
|
Continue to the next source line in the current (innermost) stack
|
frame. This is similar to `step', but function calls that appear
|
frame. This is similar to `step', but function calls that appear
|
within the line of code are executed without stopping. Execution
|
within the line of code are executed without stopping. Execution
|
stops when control reaches a different line of code at the
|
stops when control reaches a different line of code at the
|
original stack level that was executing when you gave the `next'
|
original stack level that was executing when you gave the `next'
|
command. This command is abbreviated `n'.
|
command. This command is abbreviated `n'.
|
|
|
An argument COUNT is a repeat count, as for `step'.
|
An argument COUNT is a repeat count, as for `step'.
|
|
|
The `next' command only stops at the first instruction of a source
|
The `next' command only stops at the first instruction of a source
|
line. This prevents multiple stops that could otherwise occur in
|
line. This prevents multiple stops that could otherwise occur in
|
`switch' statements, `for' loops, etc.
|
`switch' statements, `for' loops, etc.
|
|
|
`set step-mode'
|
`set step-mode'
|
`set step-mode on'
|
`set step-mode on'
|
The `set step-mode on' command causes the `step' command to stop
|
The `set step-mode on' command causes the `step' command to stop
|
at the first instruction of a function which contains no debug line
|
at the first instruction of a function which contains no debug line
|
information rather than stepping over it.
|
information rather than stepping over it.
|
|
|
This is useful in cases where you may be interested in inspecting
|
This is useful in cases where you may be interested in inspecting
|
the machine instructions of a function which has no symbolic info
|
the machine instructions of a function which has no symbolic info
|
and do not want GDB to automatically skip over this function.
|
and do not want GDB to automatically skip over this function.
|
|
|
`set step-mode off'
|
`set step-mode off'
|
Causes the `step' command to step over any functions which
|
Causes the `step' command to step over any functions which
|
contains no debug information. This is the default.
|
contains no debug information. This is the default.
|
|
|
`show step-mode'
|
`show step-mode'
|
Show whether GDB will stop in or step over functions without
|
Show whether GDB will stop in or step over functions without
|
source line debug information.
|
source line debug information.
|
|
|
`finish'
|
`finish'
|
Continue running until just after function in the selected stack
|
Continue running until just after function in the selected stack
|
frame returns. Print the returned value (if any). This command
|
frame returns. Print the returned value (if any). This command
|
can be abbreviated as `fin'.
|
can be abbreviated as `fin'.
|
|
|
Contrast this with the `return' command (*note Returning from a
|
Contrast this with the `return' command (*note Returning from a
|
Function: Returning.).
|
Function: Returning.).
|
|
|
`until'
|
`until'
|
`u'
|
`u'
|
Continue running until a source line past the current line, in the
|
Continue running until a source line past the current line, in the
|
current stack frame, is reached. This command is used to avoid
|
current stack frame, is reached. This command is used to avoid
|
single stepping through a loop more than once. It is like the
|
single stepping through a loop more than once. It is like the
|
`next' command, except that when `until' encounters a jump, it
|
`next' command, except that when `until' encounters a jump, it
|
automatically continues execution until the program counter is
|
automatically continues execution until the program counter is
|
greater than the address of the jump.
|
greater than the address of the jump.
|
|
|
This means that when you reach the end of a loop after single
|
This means that when you reach the end of a loop after single
|
stepping though it, `until' makes your program continue execution
|
stepping though it, `until' makes your program continue execution
|
until it exits the loop. In contrast, a `next' command at the end
|
until it exits the loop. In contrast, a `next' command at the end
|
of a loop simply steps back to the beginning of the loop, which
|
of a loop simply steps back to the beginning of the loop, which
|
forces you to step through the next iteration.
|
forces you to step through the next iteration.
|
|
|
`until' always stops your program if it attempts to exit the
|
`until' always stops your program if it attempts to exit the
|
current stack frame.
|
current stack frame.
|
|
|
`until' may produce somewhat counterintuitive results if the order
|
`until' may produce somewhat counterintuitive results if the order
|
of machine code does not match the order of the source lines. For
|
of machine code does not match the order of the source lines. For
|
example, in the following excerpt from a debugging session, the `f'
|
example, in the following excerpt from a debugging session, the `f'
|
(`frame') command shows that execution is stopped at line `206';
|
(`frame') command shows that execution is stopped at line `206';
|
yet when we use `until', we get to line `195':
|
yet when we use `until', we get to line `195':
|
|
|
(gdb) f
|
(gdb) f
|
#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
|
#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
|
206 expand_input();
|
206 expand_input();
|
(gdb) until
|
(gdb) until
|
195 for ( ; argc > 0; NEXTARG) {
|
195 for ( ; argc > 0; NEXTARG) {
|
|
|
This happened because, for execution efficiency, the compiler had
|
This happened because, for execution efficiency, the compiler had
|
generated code for the loop closure test at the end, rather than
|
generated code for the loop closure test at the end, rather than
|
the start, of the loop--even though the test in a C `for'-loop is
|
the start, of the loop--even though the test in a C `for'-loop is
|
written before the body of the loop. The `until' command appeared
|
written before the body of the loop. The `until' command appeared
|
to step back to the beginning of the loop when it advanced to this
|
to step back to the beginning of the loop when it advanced to this
|
expression; however, it has not really gone to an earlier
|
expression; however, it has not really gone to an earlier
|
statement--not in terms of the actual machine code.
|
statement--not in terms of the actual machine code.
|
|
|
`until' with no argument works by means of single instruction
|
`until' with no argument works by means of single instruction
|
stepping, and hence is slower than `until' with an argument.
|
stepping, and hence is slower than `until' with an argument.
|
|
|
`until LOCATION'
|
`until LOCATION'
|
`u LOCATION'
|
`u LOCATION'
|
Continue running your program until either the specified location
|
Continue running your program until either the specified location
|
is reached, or the current stack frame returns. LOCATION is any of
|
is reached, or the current stack frame returns. LOCATION is any of
|
the forms described in *note Specify Location::. This form of the
|
the forms described in *note Specify Location::. This form of the
|
command uses temporary breakpoints, and hence is quicker than
|
command uses temporary breakpoints, and hence is quicker than
|
`until' without an argument. The specified location is actually
|
`until' without an argument. The specified location is actually
|
reached only if it is in the current frame. This implies that
|
reached only if it is in the current frame. This implies that
|
`until' can be used to skip over recursive function invocations.
|
`until' can be used to skip over recursive function invocations.
|
For instance in the code below, if the current location is line
|
For instance in the code below, if the current location is line
|
`96', issuing `until 99' will execute the program up to line `99'
|
`96', issuing `until 99' will execute the program up to line `99'
|
in the same invocation of factorial, i.e., after the inner
|
in the same invocation of factorial, i.e., after the inner
|
invocations have returned.
|
invocations have returned.
|
|
|
94 int factorial (int value)
|
94 int factorial (int value)
|
95 {
|
95 {
|
96 if (value > 1) {
|
96 if (value > 1) {
|
97 value *= factorial (value - 1);
|
97 value *= factorial (value - 1);
|
98 }
|
98 }
|
99 return (value);
|
99 return (value);
|
100 }
|
100 }
|
|
|
`advance LOCATION'
|
`advance LOCATION'
|
Continue running the program up to the given LOCATION. An
|
Continue running the program up to the given LOCATION. An
|
argument is required, which should be of one of the forms
|
argument is required, which should be of one of the forms
|
described in *note Specify Location::. Execution will also stop
|
described in *note Specify Location::. Execution will also stop
|
upon exit from the current stack frame. This command is similar
|
upon exit from the current stack frame. This command is similar
|
to `until', but `advance' will not skip over recursive function
|
to `until', but `advance' will not skip over recursive function
|
calls, and the target location doesn't have to be in the same
|
calls, and the target location doesn't have to be in the same
|
frame as the current one.
|
frame as the current one.
|
|
|
`stepi'
|
`stepi'
|
`stepi ARG'
|
`stepi ARG'
|
`si'
|
`si'
|
Execute one machine instruction, then stop and return to the
|
Execute one machine instruction, then stop and return to the
|
debugger.
|
debugger.
|
|
|
It is often useful to do `display/i $pc' when stepping by machine
|
It is often useful to do `display/i $pc' when stepping by machine
|
instructions. This makes GDB automatically display the next
|
instructions. This makes GDB automatically display the next
|
instruction to be executed, each time your program stops. *Note
|
instruction to be executed, each time your program stops. *Note
|
Automatic Display: Auto Display.
|
Automatic Display: Auto Display.
|
|
|
An argument is a repeat count, as in `step'.
|
An argument is a repeat count, as in `step'.
|
|
|
`nexti'
|
`nexti'
|
`nexti ARG'
|
`nexti ARG'
|
`ni'
|
`ni'
|
Execute one machine instruction, but if it is a function call,
|
Execute one machine instruction, but if it is a function call,
|
proceed until the function returns.
|
proceed until the function returns.
|
|
|
An argument is a repeat count, as in `next'.
|
An argument is a repeat count, as in `next'.
|
|
|
|
|
File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping
|
File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping
|
|
|
5.3 Signals
|
5.3 Signals
|
===========
|
===========
|
|
|
A signal is an asynchronous event that can happen in a program. The
|
A signal is an asynchronous event that can happen in a program. The
|
operating system defines the possible kinds of signals, and gives each
|
operating system defines the possible kinds of signals, and gives each
|
kind a name and a number. For example, in Unix `SIGINT' is the signal
|
kind a name and a number. For example, in Unix `SIGINT' is the signal
|
a program gets when you type an interrupt character (often `Ctrl-c');
|
a program gets when you type an interrupt character (often `Ctrl-c');
|
`SIGSEGV' is the signal a program gets from referencing a place in
|
`SIGSEGV' is the signal a program gets from referencing a place in
|
memory far away from all the areas in use; `SIGALRM' occurs when the
|
memory far away from all the areas in use; `SIGALRM' occurs when the
|
alarm clock timer goes off (which happens only if your program has
|
alarm clock timer goes off (which happens only if your program has
|
requested an alarm).
|
requested an alarm).
|
|
|
Some signals, including `SIGALRM', are a normal part of the
|
Some signals, including `SIGALRM', are a normal part of the
|
functioning of your program. Others, such as `SIGSEGV', indicate
|
functioning of your program. Others, such as `SIGSEGV', indicate
|
errors; these signals are "fatal" (they kill your program immediately)
|
errors; these signals are "fatal" (they kill your program immediately)
|
if the program has not specified in advance some other way to handle
|
if the program has not specified in advance some other way to handle
|
the signal. `SIGINT' does not indicate an error in your program, but
|
the signal. `SIGINT' does not indicate an error in your program, but
|
it is normally fatal so it can carry out the purpose of the interrupt:
|
it is normally fatal so it can carry out the purpose of the interrupt:
|
to kill the program.
|
to kill the program.
|
|
|
GDB has the ability to detect any occurrence of a signal in your
|
GDB has the ability to detect any occurrence of a signal in your
|
program. You can tell GDB in advance what to do for each kind of
|
program. You can tell GDB in advance what to do for each kind of
|
signal.
|
signal.
|
|
|
Normally, GDB is set up to let the non-erroneous signals like
|
Normally, GDB is set up to let the non-erroneous signals like
|
`SIGALRM' be silently passed to your program (so as not to interfere
|
`SIGALRM' be silently passed to your program (so as not to interfere
|
with their role in the program's functioning) but to stop your program
|
with their role in the program's functioning) but to stop your program
|
immediately whenever an error signal happens. You can change these
|
immediately whenever an error signal happens. You can change these
|
settings with the `handle' command.
|
settings with the `handle' command.
|
|
|
`info signals'
|
`info signals'
|
`info handle'
|
`info handle'
|
Print a table of all the kinds of signals and how GDB has been
|
Print a table of all the kinds of signals and how GDB has been
|
told to handle each one. You can use this to see the signal
|
told to handle each one. You can use this to see the signal
|
numbers of all the defined types of signals.
|
numbers of all the defined types of signals.
|
|
|
`info signals SIG'
|
`info signals SIG'
|
Similar, but print information only about the specified signal
|
Similar, but print information only about the specified signal
|
number.
|
number.
|
|
|
`info handle' is an alias for `info signals'.
|
`info handle' is an alias for `info signals'.
|
|
|
`handle SIGNAL [KEYWORDS...]'
|
`handle SIGNAL [KEYWORDS...]'
|
Change the way GDB handles signal SIGNAL. SIGNAL can be the
|
Change the way GDB handles signal SIGNAL. SIGNAL can be the
|
number of a signal or its name (with or without the `SIG' at the
|
number of a signal or its name (with or without the `SIG' at the
|
beginning); a list of signal numbers of the form `LOW-HIGH'; or
|
beginning); a list of signal numbers of the form `LOW-HIGH'; or
|
the word `all', meaning all the known signals. Optional arguments
|
the word `all', meaning all the known signals. Optional arguments
|
KEYWORDS, described below, say what change to make.
|
KEYWORDS, described below, say what change to make.
|
|
|
The keywords allowed by the `handle' command can be abbreviated.
|
The keywords allowed by the `handle' command can be abbreviated.
|
Their full names are:
|
Their full names are:
|
|
|
`nostop'
|
`nostop'
|
GDB should not stop your program when this signal happens. It may
|
GDB should not stop your program when this signal happens. It may
|
still print a message telling you that the signal has come in.
|
still print a message telling you that the signal has come in.
|
|
|
`stop'
|
`stop'
|
GDB should stop your program when this signal happens. This
|
GDB should stop your program when this signal happens. This
|
implies the `print' keyword as well.
|
implies the `print' keyword as well.
|
|
|
`print'
|
`print'
|
GDB should print a message when this signal happens.
|
GDB should print a message when this signal happens.
|
|
|
`noprint'
|
`noprint'
|
GDB should not mention the occurrence of the signal at all. This
|
GDB should not mention the occurrence of the signal at all. This
|
implies the `nostop' keyword as well.
|
implies the `nostop' keyword as well.
|
|
|
`pass'
|
`pass'
|
`noignore'
|
`noignore'
|
GDB should allow your program to see this signal; your program can
|
GDB should allow your program to see this signal; your program can
|
handle the signal, or else it may terminate if the signal is fatal
|
handle the signal, or else it may terminate if the signal is fatal
|
and not handled. `pass' and `noignore' are synonyms.
|
and not handled. `pass' and `noignore' are synonyms.
|
|
|
`nopass'
|
`nopass'
|
`ignore'
|
`ignore'
|
GDB should not allow your program to see this signal. `nopass'
|
GDB should not allow your program to see this signal. `nopass'
|
and `ignore' are synonyms.
|
and `ignore' are synonyms.
|
|
|
When a signal stops your program, the signal is not visible to the
|
When a signal stops your program, the signal is not visible to the
|
program until you continue. Your program sees the signal then, if
|
program until you continue. Your program sees the signal then, if
|
`pass' is in effect for the signal in question _at that time_. In
|
`pass' is in effect for the signal in question _at that time_. In
|
other words, after GDB reports a signal, you can use the `handle'
|
other words, after GDB reports a signal, you can use the `handle'
|
command with `pass' or `nopass' to control whether your program sees
|
command with `pass' or `nopass' to control whether your program sees
|
that signal when you continue.
|
that signal when you continue.
|
|
|
The default is set to `nostop', `noprint', `pass' for non-erroneous
|
The default is set to `nostop', `noprint', `pass' for non-erroneous
|
signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop',
|
signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop',
|
`print', `pass' for the erroneous signals.
|
`print', `pass' for the erroneous signals.
|
|
|
You can also use the `signal' command to prevent your program from
|
You can also use the `signal' command to prevent your program from
|
seeing a signal, or cause it to see a signal it normally would not see,
|
seeing a signal, or cause it to see a signal it normally would not see,
|
or to give it any signal at any time. For example, if your program
|
or to give it any signal at any time. For example, if your program
|
stopped due to some sort of memory reference error, you might store
|
stopped due to some sort of memory reference error, you might store
|
correct values into the erroneous variables and continue, hoping to see
|
correct values into the erroneous variables and continue, hoping to see
|
more execution; but your program would probably terminate immediately as
|
more execution; but your program would probably terminate immediately as
|
a result of the fatal signal once it saw the signal. To prevent this,
|
a result of the fatal signal once it saw the signal. To prevent this,
|
you can continue with `signal 0'. *Note Giving your Program a Signal:
|
you can continue with `signal 0'. *Note Giving your Program a Signal:
|
Signaling.
|
Signaling.
|
|
|
On some targets, GDB can inspect extra signal information associated
|
On some targets, GDB can inspect extra signal information associated
|
with the intercepted signal, before it is actually delivered to the
|
with the intercepted signal, before it is actually delivered to the
|
program being debugged. This information is exported by the
|
program being debugged. This information is exported by the
|
convenience variable `$_siginfo', and consists of data that is passed
|
convenience variable `$_siginfo', and consists of data that is passed
|
by the kernel to the signal handler at the time of the receipt of a
|
by the kernel to the signal handler at the time of the receipt of a
|
signal. The data type of the information itself is target dependent.
|
signal. The data type of the information itself is target dependent.
|
You can see the data type using the `ptype $_siginfo' command. On Unix
|
You can see the data type using the `ptype $_siginfo' command. On Unix
|
systems, it typically corresponds to the standard `siginfo_t' type, as
|
systems, it typically corresponds to the standard `siginfo_t' type, as
|
defined in the `signal.h' system header.
|
defined in the `signal.h' system header.
|
|
|
Here's an example, on a GNU/Linux system, printing the stray
|
Here's an example, on a GNU/Linux system, printing the stray
|
referenced address that raised a segmentation fault.
|
referenced address that raised a segmentation fault.
|
|
|
(gdb) continue
|
(gdb) continue
|
Program received signal SIGSEGV, Segmentation fault.
|
Program received signal SIGSEGV, Segmentation fault.
|
0x0000000000400766 in main ()
|
0x0000000000400766 in main ()
|
69 *(int *)p = 0;
|
69 *(int *)p = 0;
|
(gdb) ptype $_siginfo
|
(gdb) ptype $_siginfo
|
type = struct {
|
type = struct {
|
int si_signo;
|
int si_signo;
|
int si_errno;
|
int si_errno;
|
int si_code;
|
int si_code;
|
union {
|
union {
|
int _pad[28];
|
int _pad[28];
|
struct {...} _kill;
|
struct {...} _kill;
|
struct {...} _timer;
|
struct {...} _timer;
|
struct {...} _rt;
|
struct {...} _rt;
|
struct {...} _sigchld;
|
struct {...} _sigchld;
|
struct {...} _sigfault;
|
struct {...} _sigfault;
|
struct {...} _sigpoll;
|
struct {...} _sigpoll;
|
} _sifields;
|
} _sifields;
|
}
|
}
|
(gdb) ptype $_siginfo._sifields._sigfault
|
(gdb) ptype $_siginfo._sifields._sigfault
|
type = struct {
|
type = struct {
|
void *si_addr;
|
void *si_addr;
|
}
|
}
|
(gdb) p $_siginfo._sifields._sigfault.si_addr
|
(gdb) p $_siginfo._sifields._sigfault.si_addr
|
$1 = (void *) 0x7ffff7ff7000
|
$1 = (void *) 0x7ffff7ff7000
|
|
|
Depending on target support, `$_siginfo' may also be writable.
|
Depending on target support, `$_siginfo' may also be writable.
|
|
|
|
|
File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping
|
File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping
|
|
|
5.4 Stopping and Starting Multi-thread Programs
|
5.4 Stopping and Starting Multi-thread Programs
|
===============================================
|
===============================================
|
|
|
GDB supports debugging programs with multiple threads (*note Debugging
|
GDB supports debugging programs with multiple threads (*note Debugging
|
Programs with Multiple Threads: Threads.). There are two modes of
|
Programs with Multiple Threads: Threads.). There are two modes of
|
controlling execution of your program within the debugger. In the
|
controlling execution of your program within the debugger. In the
|
default mode, referred to as "all-stop mode", when any thread in your
|
default mode, referred to as "all-stop mode", when any thread in your
|
program stops (for example, at a breakpoint or while being stepped),
|
program stops (for example, at a breakpoint or while being stepped),
|
all other threads in the program are also stopped by GDB. On some
|
all other threads in the program are also stopped by GDB. On some
|
targets, GDB also supports "non-stop mode", in which other threads can
|
targets, GDB also supports "non-stop mode", in which other threads can
|
continue to run freely while you examine the stopped thread in the
|
continue to run freely while you examine the stopped thread in the
|
debugger.
|
debugger.
|
|
|
* Menu:
|
* Menu:
|
|
|
* All-Stop Mode:: All threads stop when GDB takes control
|
* All-Stop Mode:: All threads stop when GDB takes control
|
* Non-Stop Mode:: Other threads continue to execute
|
* Non-Stop Mode:: Other threads continue to execute
|
* Background Execution:: Running your program asynchronously
|
* Background Execution:: Running your program asynchronously
|
* Thread-Specific Breakpoints:: Controlling breakpoints
|
* Thread-Specific Breakpoints:: Controlling breakpoints
|
* Interrupted System Calls:: GDB may interfere with system calls
|
* Interrupted System Calls:: GDB may interfere with system calls
|
* Observer Mode:: GDB does not alter program behavior
|
* Observer Mode:: GDB does not alter program behavior
|
|
|
|
|
File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops
|
File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops
|
|
|
5.4.1 All-Stop Mode
|
5.4.1 All-Stop Mode
|
-------------------
|
-------------------
|
|
|
In all-stop mode, whenever your program stops under GDB for any reason,
|
In all-stop mode, whenever your program stops under GDB for any reason,
|
_all_ threads of execution stop, not just the current thread. This
|
_all_ threads of execution stop, not just the current thread. This
|
allows you to examine the overall state of the program, including
|
allows you to examine the overall state of the program, including
|
switching between threads, without worrying that things may change
|
switching between threads, without worrying that things may change
|
underfoot.
|
underfoot.
|
|
|
Conversely, whenever you restart the program, _all_ threads start
|
Conversely, whenever you restart the program, _all_ threads start
|
executing. _This is true even when single-stepping_ with commands like
|
executing. _This is true even when single-stepping_ with commands like
|
`step' or `next'.
|
`step' or `next'.
|
|
|
In particular, GDB cannot single-step all threads in lockstep.
|
In particular, GDB cannot single-step all threads in lockstep.
|
Since thread scheduling is up to your debugging target's operating
|
Since thread scheduling is up to your debugging target's operating
|
system (not controlled by GDB), other threads may execute more than one
|
system (not controlled by GDB), other threads may execute more than one
|
statement while the current thread completes a single step. Moreover,
|
statement while the current thread completes a single step. Moreover,
|
in general other threads stop in the middle of a statement, rather than
|
in general other threads stop in the middle of a statement, rather than
|
at a clean statement boundary, when the program stops.
|
at a clean statement boundary, when the program stops.
|
|
|
You might even find your program stopped in another thread after
|
You might even find your program stopped in another thread after
|
continuing or even single-stepping. This happens whenever some other
|
continuing or even single-stepping. This happens whenever some other
|
thread runs into a breakpoint, a signal, or an exception before the
|
thread runs into a breakpoint, a signal, or an exception before the
|
first thread completes whatever you requested.
|
first thread completes whatever you requested.
|
|
|
Whenever GDB stops your program, due to a breakpoint or a signal, it
|
Whenever GDB stops your program, due to a breakpoint or a signal, it
|
automatically selects the thread where that breakpoint or signal
|
automatically selects the thread where that breakpoint or signal
|
happened. GDB alerts you to the context switch with a message such as
|
happened. GDB alerts you to the context switch with a message such as
|
`[Switching to Thread N]' to identify the thread.
|
`[Switching to Thread N]' to identify the thread.
|
|
|
On some OSes, you can modify GDB's default behavior by locking the
|
On some OSes, you can modify GDB's default behavior by locking the
|
OS scheduler to allow only a single thread to run.
|
OS scheduler to allow only a single thread to run.
|
|
|
`set scheduler-locking MODE'
|
`set scheduler-locking MODE'
|
Set the scheduler locking mode. If it is `off', then there is no
|
Set the scheduler locking mode. If it is `off', then there is no
|
locking and any thread may run at any time. If `on', then only the
|
locking and any thread may run at any time. If `on', then only the
|
current thread may run when the inferior is resumed. The `step'
|
current thread may run when the inferior is resumed. The `step'
|
mode optimizes for single-stepping; it prevents other threads from
|
mode optimizes for single-stepping; it prevents other threads from
|
preempting the current thread while you are stepping, so that the
|
preempting the current thread while you are stepping, so that the
|
focus of debugging does not change unexpectedly. Other threads
|
focus of debugging does not change unexpectedly. Other threads
|
only rarely (or never) get a chance to run when you step. They
|
only rarely (or never) get a chance to run when you step. They
|
are more likely to run when you `next' over a function call, and
|
are more likely to run when you `next' over a function call, and
|
they are completely free to run when you use commands like
|
they are completely free to run when you use commands like
|
`continue', `until', or `finish'. However, unless another thread
|
`continue', `until', or `finish'. However, unless another thread
|
hits a breakpoint during its timeslice, GDB does not change the
|
hits a breakpoint during its timeslice, GDB does not change the
|
current thread away from the thread that you are debugging.
|
current thread away from the thread that you are debugging.
|
|
|
`show scheduler-locking'
|
`show scheduler-locking'
|
Display the current scheduler locking mode.
|
Display the current scheduler locking mode.
|
|
|
By default, when you issue one of the execution commands such as
|
By default, when you issue one of the execution commands such as
|
`continue', `next' or `step', GDB allows only threads of the current
|
`continue', `next' or `step', GDB allows only threads of the current
|
inferior to run. For example, if GDB is attached to two inferiors,
|
inferior to run. For example, if GDB is attached to two inferiors,
|
each with two threads, the `continue' command resumes only the two
|
each with two threads, the `continue' command resumes only the two
|
threads of the current inferior. This is useful, for example, when you
|
threads of the current inferior. This is useful, for example, when you
|
debug a program that forks and you want to hold the parent stopped (so
|
debug a program that forks and you want to hold the parent stopped (so
|
that, for instance, it doesn't run to exit), while you debug the child.
|
that, for instance, it doesn't run to exit), while you debug the child.
|
In other situations, you may not be interested in inspecting the
|
In other situations, you may not be interested in inspecting the
|
current state of any of the processes GDB is attached to, and you may
|
current state of any of the processes GDB is attached to, and you may
|
want to resume them all until some breakpoint is hit. In the latter
|
want to resume them all until some breakpoint is hit. In the latter
|
case, you can instruct GDB to allow all threads of all the inferiors to
|
case, you can instruct GDB to allow all threads of all the inferiors to
|
run with the `set schedule-multiple' command.
|
run with the `set schedule-multiple' command.
|
|
|
`set schedule-multiple'
|
`set schedule-multiple'
|
Set the mode for allowing threads of multiple processes to be
|
Set the mode for allowing threads of multiple processes to be
|
resumed when an execution command is issued. When `on', all
|
resumed when an execution command is issued. When `on', all
|
threads of all processes are allowed to run. When `off', only the
|
threads of all processes are allowed to run. When `off', only the
|
threads of the current process are resumed. The default is `off'.
|
threads of the current process are resumed. The default is `off'.
|
The `scheduler-locking' mode takes precedence when set to `on', or
|
The `scheduler-locking' mode takes precedence when set to `on', or
|
while you are stepping and set to `step'.
|
while you are stepping and set to `step'.
|
|
|
`show schedule-multiple'
|
`show schedule-multiple'
|
Display the current mode for resuming the execution of threads of
|
Display the current mode for resuming the execution of threads of
|
multiple processes.
|
multiple processes.
|
|
|
|
|
File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops
|
File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops
|
|
|
5.4.2 Non-Stop Mode
|
5.4.2 Non-Stop Mode
|
-------------------
|
-------------------
|
|
|
For some multi-threaded targets, GDB supports an optional mode of
|
For some multi-threaded targets, GDB supports an optional mode of
|
operation in which you can examine stopped program threads in the
|
operation in which you can examine stopped program threads in the
|
debugger while other threads continue to execute freely. This
|
debugger while other threads continue to execute freely. This
|
minimizes intrusion when debugging live systems, such as programs where
|
minimizes intrusion when debugging live systems, such as programs where
|
some threads have real-time constraints or must continue to respond to
|
some threads have real-time constraints or must continue to respond to
|
external events. This is referred to as "non-stop" mode.
|
external events. This is referred to as "non-stop" mode.
|
|
|
In non-stop mode, when a thread stops to report a debugging event,
|
In non-stop mode, when a thread stops to report a debugging event,
|
_only_ that thread is stopped; GDB does not stop other threads as well,
|
_only_ that thread is stopped; GDB does not stop other threads as well,
|
in contrast to the all-stop mode behavior. Additionally, execution
|
in contrast to the all-stop mode behavior. Additionally, execution
|
commands such as `continue' and `step' apply by default only to the
|
commands such as `continue' and `step' apply by default only to the
|
current thread in non-stop mode, rather than all threads as in all-stop
|
current thread in non-stop mode, rather than all threads as in all-stop
|
mode. This allows you to control threads explicitly in ways that are
|
mode. This allows you to control threads explicitly in ways that are
|
not possible in all-stop mode -- for example, stepping one thread while
|
not possible in all-stop mode -- for example, stepping one thread while
|
allowing others to run freely, stepping one thread while holding all
|
allowing others to run freely, stepping one thread while holding all
|
others stopped, or stepping several threads independently and
|
others stopped, or stepping several threads independently and
|
simultaneously.
|
simultaneously.
|
|
|
To enter non-stop mode, use this sequence of commands before you run
|
To enter non-stop mode, use this sequence of commands before you run
|
or attach to your program:
|
or attach to your program:
|
|
|
# Enable the async interface.
|
# Enable the async interface.
|
set target-async 1
|
set target-async 1
|
|
|
# If using the CLI, pagination breaks non-stop.
|
# If using the CLI, pagination breaks non-stop.
|
set pagination off
|
set pagination off
|
|
|
# Finally, turn it on!
|
# Finally, turn it on!
|
set non-stop on
|
set non-stop on
|
|
|
You can use these commands to manipulate the non-stop mode setting:
|
You can use these commands to manipulate the non-stop mode setting:
|
|
|
`set non-stop on'
|
`set non-stop on'
|
Enable selection of non-stop mode.
|
Enable selection of non-stop mode.
|
|
|
`set non-stop off'
|
`set non-stop off'
|
Disable selection of non-stop mode.
|
Disable selection of non-stop mode.
|
|
|
`show non-stop'
|
`show non-stop'
|
Show the current non-stop enablement setting.
|
Show the current non-stop enablement setting.
|
|
|
Note these commands only reflect whether non-stop mode is enabled,
|
Note these commands only reflect whether non-stop mode is enabled,
|
not whether the currently-executing program is being run in non-stop
|
not whether the currently-executing program is being run in non-stop
|
mode. In particular, the `set non-stop' preference is only consulted
|
mode. In particular, the `set non-stop' preference is only consulted
|
when GDB starts or connects to the target program, and it is generally
|
when GDB starts or connects to the target program, and it is generally
|
not possible to switch modes once debugging has started. Furthermore,
|
not possible to switch modes once debugging has started. Furthermore,
|
since not all targets support non-stop mode, even when you have enabled
|
since not all targets support non-stop mode, even when you have enabled
|
non-stop mode, GDB may still fall back to all-stop operation by default.
|
non-stop mode, GDB may still fall back to all-stop operation by default.
|
|
|
In non-stop mode, all execution commands apply only to the current
|
In non-stop mode, all execution commands apply only to the current
|
thread by default. That is, `continue' only continues one thread. To
|
thread by default. That is, `continue' only continues one thread. To
|
continue all threads, issue `continue -a' or `c -a'.
|
continue all threads, issue `continue -a' or `c -a'.
|
|
|
You can use GDB's background execution commands (*note Background
|
You can use GDB's background execution commands (*note Background
|
Execution::) to run some threads in the background while you continue
|
Execution::) to run some threads in the background while you continue
|
to examine or step others from GDB. The MI execution commands (*note
|
to examine or step others from GDB. The MI execution commands (*note
|
GDB/MI Program Execution::) are always executed asynchronously in
|
GDB/MI Program Execution::) are always executed asynchronously in
|
non-stop mode.
|
non-stop mode.
|
|
|
Suspending execution is done with the `interrupt' command when
|
Suspending execution is done with the `interrupt' command when
|
running in the background, or `Ctrl-c' during foreground execution. In
|
running in the background, or `Ctrl-c' during foreground execution. In
|
all-stop mode, this stops the whole process; but in non-stop mode the
|
all-stop mode, this stops the whole process; but in non-stop mode the
|
interrupt applies only to the current thread. To stop the whole
|
interrupt applies only to the current thread. To stop the whole
|
program, use `interrupt -a'.
|
program, use `interrupt -a'.
|
|
|
Other execution commands do not currently support the `-a' option.
|
Other execution commands do not currently support the `-a' option.
|
|
|
In non-stop mode, when a thread stops, GDB doesn't automatically make
|
In non-stop mode, when a thread stops, GDB doesn't automatically make
|
that thread current, as it does in all-stop mode. This is because the
|
that thread current, as it does in all-stop mode. This is because the
|
thread stop notifications are asynchronous with respect to GDB's
|
thread stop notifications are asynchronous with respect to GDB's
|
command interpreter, and it would be confusing if GDB unexpectedly
|
command interpreter, and it would be confusing if GDB unexpectedly
|
changed to a different thread just as you entered a command to operate
|
changed to a different thread just as you entered a command to operate
|
on the previously current thread.
|
on the previously current thread.
|
|
|
|
|
File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops
|
File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops
|
|
|
5.4.3 Background Execution
|
5.4.3 Background Execution
|
--------------------------
|
--------------------------
|
|
|
GDB's execution commands have two variants: the normal foreground
|
GDB's execution commands have two variants: the normal foreground
|
(synchronous) behavior, and a background (asynchronous) behavior. In
|
(synchronous) behavior, and a background (asynchronous) behavior. In
|
foreground execution, GDB waits for the program to report that some
|
foreground execution, GDB waits for the program to report that some
|
thread has stopped before prompting for another command. In background
|
thread has stopped before prompting for another command. In background
|
execution, GDB immediately gives a command prompt so that you can issue
|
execution, GDB immediately gives a command prompt so that you can issue
|
other commands while your program runs.
|
other commands while your program runs.
|
|
|
You need to explicitly enable asynchronous mode before you can use
|
You need to explicitly enable asynchronous mode before you can use
|
background execution commands. You can use these commands to
|
background execution commands. You can use these commands to
|
manipulate the asynchronous mode setting:
|
manipulate the asynchronous mode setting:
|
|
|
`set target-async on'
|
`set target-async on'
|
Enable asynchronous mode.
|
Enable asynchronous mode.
|
|
|
`set target-async off'
|
`set target-async off'
|
Disable asynchronous mode.
|
Disable asynchronous mode.
|
|
|
`show target-async'
|
`show target-async'
|
Show the current target-async setting.
|
Show the current target-async setting.
|
|
|
If the target doesn't support async mode, GDB issues an error
|
If the target doesn't support async mode, GDB issues an error
|
message if you attempt to use the background execution commands.
|
message if you attempt to use the background execution commands.
|
|
|
To specify background execution, add a `&' to the command. For
|
To specify background execution, add a `&' to the command. For
|
example, the background form of the `continue' command is `continue&',
|
example, the background form of the `continue' command is `continue&',
|
or just `c&'. The execution commands that accept background execution
|
or just `c&'. The execution commands that accept background execution
|
are:
|
are:
|
|
|
`run'
|
`run'
|
*Note Starting your Program: Starting.
|
*Note Starting your Program: Starting.
|
|
|
`attach'
|
`attach'
|
*Note Debugging an Already-running Process: Attach.
|
*Note Debugging an Already-running Process: Attach.
|
|
|
`step'
|
`step'
|
*Note step: Continuing and Stepping.
|
*Note step: Continuing and Stepping.
|
|
|
`stepi'
|
`stepi'
|
*Note stepi: Continuing and Stepping.
|
*Note stepi: Continuing and Stepping.
|
|
|
`next'
|
`next'
|
*Note next: Continuing and Stepping.
|
*Note next: Continuing and Stepping.
|
|
|
`nexti'
|
`nexti'
|
*Note nexti: Continuing and Stepping.
|
*Note nexti: Continuing and Stepping.
|
|
|
`continue'
|
`continue'
|
*Note continue: Continuing and Stepping.
|
*Note continue: Continuing and Stepping.
|
|
|
`finish'
|
`finish'
|
*Note finish: Continuing and Stepping.
|
*Note finish: Continuing and Stepping.
|
|
|
`until'
|
`until'
|
*Note until: Continuing and Stepping.
|
*Note until: Continuing and Stepping.
|
|
|
|
|
Background execution is especially useful in conjunction with
|
Background execution is especially useful in conjunction with
|
non-stop mode for debugging programs with multiple threads; see *note
|
non-stop mode for debugging programs with multiple threads; see *note
|
Non-Stop Mode::. However, you can also use these commands in the
|
Non-Stop Mode::. However, you can also use these commands in the
|
normal all-stop mode with the restriction that you cannot issue another
|
normal all-stop mode with the restriction that you cannot issue another
|
execution command until the previous one finishes. Examples of
|
execution command until the previous one finishes. Examples of
|
commands that are valid in all-stop mode while the program is running
|
commands that are valid in all-stop mode while the program is running
|
include `help' and `info break'.
|
include `help' and `info break'.
|
|
|
You can interrupt your program while it is running in the background
|
You can interrupt your program while it is running in the background
|
by using the `interrupt' command.
|
by using the `interrupt' command.
|
|
|
`interrupt'
|
`interrupt'
|
`interrupt -a'
|
`interrupt -a'
|
Suspend execution of the running program. In all-stop mode,
|
Suspend execution of the running program. In all-stop mode,
|
`interrupt' stops the whole process, but in non-stop mode, it stops
|
`interrupt' stops the whole process, but in non-stop mode, it stops
|
only the current thread. To stop the whole program in non-stop
|
only the current thread. To stop the whole program in non-stop
|
mode, use `interrupt -a'.
|
mode, use `interrupt -a'.
|
|
|
|
|
File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops
|
File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops
|
|
|
5.4.4 Thread-Specific Breakpoints
|
5.4.4 Thread-Specific Breakpoints
|
---------------------------------
|
---------------------------------
|
|
|
When your program has multiple threads (*note Debugging Programs with
|
When your program has multiple threads (*note Debugging Programs with
|
Multiple Threads: Threads.), you can choose whether to set breakpoints
|
Multiple Threads: Threads.), you can choose whether to set breakpoints
|
on all threads, or on a particular thread.
|
on all threads, or on a particular thread.
|
|
|
`break LINESPEC thread THREADNO'
|
`break LINESPEC thread THREADNO'
|
`break LINESPEC thread THREADNO if ...'
|
`break LINESPEC thread THREADNO if ...'
|
LINESPEC specifies source lines; there are several ways of writing
|
LINESPEC specifies source lines; there are several ways of writing
|
them (*note Specify Location::), but the effect is always to
|
them (*note Specify Location::), but the effect is always to
|
specify some source line.
|
specify some source line.
|
|
|
Use the qualifier `thread THREADNO' with a breakpoint command to
|
Use the qualifier `thread THREADNO' with a breakpoint command to
|
specify that you only want GDB to stop the program when a
|
specify that you only want GDB to stop the program when a
|
particular thread reaches this breakpoint. THREADNO is one of the
|
particular thread reaches this breakpoint. THREADNO is one of the
|
numeric thread identifiers assigned by GDB, shown in the first
|
numeric thread identifiers assigned by GDB, shown in the first
|
column of the `info threads' display.
|
column of the `info threads' display.
|
|
|
If you do not specify `thread THREADNO' when you set a breakpoint,
|
If you do not specify `thread THREADNO' when you set a breakpoint,
|
the breakpoint applies to _all_ threads of your program.
|
the breakpoint applies to _all_ threads of your program.
|
|
|
You can use the `thread' qualifier on conditional breakpoints as
|
You can use the `thread' qualifier on conditional breakpoints as
|
well; in this case, place `thread THREADNO' before or after the
|
well; in this case, place `thread THREADNO' before or after the
|
breakpoint condition, like this:
|
breakpoint condition, like this:
|
|
|
(gdb) break frik.c:13 thread 28 if bartab > lim
|
(gdb) break frik.c:13 thread 28 if bartab > lim
|
|
|
|
|
|
|
File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops
|
File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops
|
|
|
5.4.5 Interrupted System Calls
|
5.4.5 Interrupted System Calls
|
------------------------------
|
------------------------------
|
|
|
There is an unfortunate side effect when using GDB to debug
|
There is an unfortunate side effect when using GDB to debug
|
multi-threaded programs. If one thread stops for a breakpoint, or for
|
multi-threaded programs. If one thread stops for a breakpoint, or for
|
some other reason, and another thread is blocked in a system call, then
|
some other reason, and another thread is blocked in a system call, then
|
the system call may return prematurely. This is a consequence of the
|
the system call may return prematurely. This is a consequence of the
|
interaction between multiple threads and the signals that GDB uses to
|
interaction between multiple threads and the signals that GDB uses to
|
implement breakpoints and other events that stop execution.
|
implement breakpoints and other events that stop execution.
|
|
|
To handle this problem, your program should check the return value of
|
To handle this problem, your program should check the return value of
|
each system call and react appropriately. This is good programming
|
each system call and react appropriately. This is good programming
|
style anyways.
|
style anyways.
|
|
|
For example, do not write code like this:
|
For example, do not write code like this:
|
|
|
sleep (10);
|
sleep (10);
|
|
|
The call to `sleep' will return early if a different thread stops at
|
The call to `sleep' will return early if a different thread stops at
|
a breakpoint or for some other reason.
|
a breakpoint or for some other reason.
|
|
|
Instead, write this:
|
Instead, write this:
|
|
|
int unslept = 10;
|
int unslept = 10;
|
while (unslept > 0)
|
while (unslept > 0)
|
unslept = sleep (unslept);
|
unslept = sleep (unslept);
|
|
|
A system call is allowed to return early, so the system is still
|
A system call is allowed to return early, so the system is still
|
conforming to its specification. But GDB does cause your
|
conforming to its specification. But GDB does cause your
|
multi-threaded program to behave differently than it would without GDB.
|
multi-threaded program to behave differently than it would without GDB.
|
|
|
Also, GDB uses internal breakpoints in the thread library to monitor
|
Also, GDB uses internal breakpoints in the thread library to monitor
|
certain events such as thread creation and thread destruction. When
|
certain events such as thread creation and thread destruction. When
|
such an event happens, a system call in another thread may return
|
such an event happens, a system call in another thread may return
|
prematurely, even though your program does not appear to stop.
|
prematurely, even though your program does not appear to stop.
|
|
|
|
|
File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops
|
File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops
|
|
|
5.4.6 Observer Mode
|
5.4.6 Observer Mode
|
-------------------
|
-------------------
|
|
|
If you want to build on non-stop mode and observe program behavior
|
If you want to build on non-stop mode and observe program behavior
|
without any chance of disruption by GDB, you can set variables to
|
without any chance of disruption by GDB, you can set variables to
|
disable all of the debugger's attempts to modify state, whether by
|
disable all of the debugger's attempts to modify state, whether by
|
writing memory, inserting breakpoints, etc. These operate at a low
|
writing memory, inserting breakpoints, etc. These operate at a low
|
level, intercepting operations from all commands.
|
level, intercepting operations from all commands.
|
|
|
When all of these are set to `off', then GDB is said to be "observer
|
When all of these are set to `off', then GDB is said to be "observer
|
mode". As a convenience, the variable `observer' can be set to disable
|
mode". As a convenience, the variable `observer' can be set to disable
|
these, plus enable non-stop mode.
|
these, plus enable non-stop mode.
|
|
|
Note that GDB will not prevent you from making nonsensical
|
Note that GDB will not prevent you from making nonsensical
|
combinations of these settings. For instance, if you have enabled
|
combinations of these settings. For instance, if you have enabled
|
`may-insert-breakpoints' but disabled `may-write-memory', then
|
`may-insert-breakpoints' but disabled `may-write-memory', then
|
breakpoints that work by writing trap instructions into the code stream
|
breakpoints that work by writing trap instructions into the code stream
|
will still not be able to be placed.
|
will still not be able to be placed.
|
|
|
`set observer on'
|
`set observer on'
|
`set observer off'
|
`set observer off'
|
When set to `on', this disables all the permission variables below
|
When set to `on', this disables all the permission variables below
|
(except for `insert-fast-tracepoints'), plus enables non-stop
|
(except for `insert-fast-tracepoints'), plus enables non-stop
|
debugging. Setting this to `off' switches back to normal
|
debugging. Setting this to `off' switches back to normal
|
debugging, though remaining in non-stop mode.
|
debugging, though remaining in non-stop mode.
|
|
|
`show observer'
|
`show observer'
|
Show whether observer mode is on or off.
|
Show whether observer mode is on or off.
|
|
|
`set may-write-registers on'
|
`set may-write-registers on'
|
`set may-write-registers off'
|
`set may-write-registers off'
|
This controls whether GDB will attempt to alter the values of
|
This controls whether GDB will attempt to alter the values of
|
registers, such as with assignment expressions in `print', or the
|
registers, such as with assignment expressions in `print', or the
|
`jump' command. It defaults to `on'.
|
`jump' command. It defaults to `on'.
|
|
|
`show may-write-registers'
|
`show may-write-registers'
|
Show the current permission to write registers.
|
Show the current permission to write registers.
|
|
|
`set may-write-memory on'
|
`set may-write-memory on'
|
`set may-write-memory off'
|
`set may-write-memory off'
|
This controls whether GDB will attempt to alter the contents of
|
This controls whether GDB will attempt to alter the contents of
|
memory, such as with assignment expressions in `print'. It
|
memory, such as with assignment expressions in `print'. It
|
defaults to `on'.
|
defaults to `on'.
|
|
|
`show may-write-memory'
|
`show may-write-memory'
|
Show the current permission to write memory.
|
Show the current permission to write memory.
|
|
|
`set may-insert-breakpoints on'
|
`set may-insert-breakpoints on'
|
`set may-insert-breakpoints off'
|
`set may-insert-breakpoints off'
|
This controls whether GDB will attempt to insert breakpoints.
|
This controls whether GDB will attempt to insert breakpoints.
|
This affects all breakpoints, including internal breakpoints
|
This affects all breakpoints, including internal breakpoints
|
defined by GDB. It defaults to `on'.
|
defined by GDB. It defaults to `on'.
|
|
|
`show may-insert-breakpoints'
|
`show may-insert-breakpoints'
|
Show the current permission to insert breakpoints.
|
Show the current permission to insert breakpoints.
|
|
|
`set may-insert-tracepoints on'
|
`set may-insert-tracepoints on'
|
`set may-insert-tracepoints off'
|
`set may-insert-tracepoints off'
|
This controls whether GDB will attempt to insert (regular)
|
This controls whether GDB will attempt to insert (regular)
|
tracepoints at the beginning of a tracing experiment. It affects
|
tracepoints at the beginning of a tracing experiment. It affects
|
only non-fast tracepoints, fast tracepoints being under the
|
only non-fast tracepoints, fast tracepoints being under the
|
control of `may-insert-fast-tracepoints'. It defaults to `on'.
|
control of `may-insert-fast-tracepoints'. It defaults to `on'.
|
|
|
`show may-insert-tracepoints'
|
`show may-insert-tracepoints'
|
Show the current permission to insert tracepoints.
|
Show the current permission to insert tracepoints.
|
|
|
`set may-insert-fast-tracepoints on'
|
`set may-insert-fast-tracepoints on'
|
`set may-insert-fast-tracepoints off'
|
`set may-insert-fast-tracepoints off'
|
This controls whether GDB will attempt to insert fast tracepoints
|
This controls whether GDB will attempt to insert fast tracepoints
|
at the beginning of a tracing experiment. It affects only fast
|
at the beginning of a tracing experiment. It affects only fast
|
tracepoints, regular (non-fast) tracepoints being under the
|
tracepoints, regular (non-fast) tracepoints being under the
|
control of `may-insert-tracepoints'. It defaults to `on'.
|
control of `may-insert-tracepoints'. It defaults to `on'.
|
|
|
`show may-insert-fast-tracepoints'
|
`show may-insert-fast-tracepoints'
|
Show the current permission to insert fast tracepoints.
|
Show the current permission to insert fast tracepoints.
|
|
|
`set may-interrupt on'
|
`set may-interrupt on'
|
`set may-interrupt off'
|
`set may-interrupt off'
|
This controls whether GDB will attempt to interrupt or stop
|
This controls whether GDB will attempt to interrupt or stop
|
program execution. When this variable is `off', the `interrupt'
|
program execution. When this variable is `off', the `interrupt'
|
command will have no effect, nor will `Ctrl-c'. It defaults to
|
command will have no effect, nor will `Ctrl-c'. It defaults to
|
`on'.
|
`on'.
|
|
|
`show may-interrupt'
|
`show may-interrupt'
|
Show the current permission to interrupt or stop the program.
|
Show the current permission to interrupt or stop the program.
|
|
|
|
|
|
|
File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top
|
File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top
|
|
|
6 Running programs backward
|
6 Running programs backward
|
***************************
|
***************************
|
|
|
When you are debugging a program, it is not unusual to realize that you
|
When you are debugging a program, it is not unusual to realize that you
|
have gone too far, and some event of interest has already happened. If
|
have gone too far, and some event of interest has already happened. If
|
the target environment supports it, GDB can allow you to "rewind" the
|
the target environment supports it, GDB can allow you to "rewind" the
|
program by running it backward.
|
program by running it backward.
|
|
|
A target environment that supports reverse execution should be able
|
A target environment that supports reverse execution should be able
|
to "undo" the changes in machine state that have taken place as the
|
to "undo" the changes in machine state that have taken place as the
|
program was executing normally. Variables, registers etc. should
|
program was executing normally. Variables, registers etc. should
|
revert to their previous values. Obviously this requires a great deal
|
revert to their previous values. Obviously this requires a great deal
|
of sophistication on the part of the target environment; not all target
|
of sophistication on the part of the target environment; not all target
|
environments can support reverse execution.
|
environments can support reverse execution.
|
|
|
When a program is executed in reverse, the instructions that have
|
When a program is executed in reverse, the instructions that have
|
most recently been executed are "un-executed", in reverse order. The
|
most recently been executed are "un-executed", in reverse order. The
|
program counter runs backward, following the previous thread of
|
program counter runs backward, following the previous thread of
|
execution in reverse. As each instruction is "un-executed", the values
|
execution in reverse. As each instruction is "un-executed", the values
|
of memory and/or registers that were changed by that instruction are
|
of memory and/or registers that were changed by that instruction are
|
reverted to their previous states. After executing a piece of source
|
reverted to their previous states. After executing a piece of source
|
code in reverse, all side effects of that code should be "undone", and
|
code in reverse, all side effects of that code should be "undone", and
|
all variables should be returned to their prior values(1).
|
all variables should be returned to their prior values(1).
|
|
|
If you are debugging in a target environment that supports reverse
|
If you are debugging in a target environment that supports reverse
|
execution, GDB provides the following commands.
|
execution, GDB provides the following commands.
|
|
|
`reverse-continue [IGNORE-COUNT]'
|
`reverse-continue [IGNORE-COUNT]'
|
`rc [IGNORE-COUNT]'
|
`rc [IGNORE-COUNT]'
|
Beginning at the point where your program last stopped, start
|
Beginning at the point where your program last stopped, start
|
executing in reverse. Reverse execution will stop for breakpoints
|
executing in reverse. Reverse execution will stop for breakpoints
|
and synchronous exceptions (signals), just like normal execution.
|
and synchronous exceptions (signals), just like normal execution.
|
Behavior of asynchronous signals depends on the target environment.
|
Behavior of asynchronous signals depends on the target environment.
|
|
|
`reverse-step [COUNT]'
|
`reverse-step [COUNT]'
|
Run the program backward until control reaches the start of a
|
Run the program backward until control reaches the start of a
|
different source line; then stop it, and return control to GDB.
|
different source line; then stop it, and return control to GDB.
|
|
|
Like the `step' command, `reverse-step' will only stop at the
|
Like the `step' command, `reverse-step' will only stop at the
|
beginning of a source line. It "un-executes" the previously
|
beginning of a source line. It "un-executes" the previously
|
executed source line. If the previous source line included calls
|
executed source line. If the previous source line included calls
|
to debuggable functions, `reverse-step' will step (backward) into
|
to debuggable functions, `reverse-step' will step (backward) into
|
the called function, stopping at the beginning of the _last_
|
the called function, stopping at the beginning of the _last_
|
statement in the called function (typically a return statement).
|
statement in the called function (typically a return statement).
|
|
|
Also, as with the `step' command, if non-debuggable functions are
|
Also, as with the `step' command, if non-debuggable functions are
|
called, `reverse-step' will run thru them backward without
|
called, `reverse-step' will run thru them backward without
|
stopping.
|
stopping.
|
|
|
`reverse-stepi [COUNT]'
|
`reverse-stepi [COUNT]'
|
Reverse-execute one machine instruction. Note that the instruction
|
Reverse-execute one machine instruction. Note that the instruction
|
to be reverse-executed is _not_ the one pointed to by the program
|
to be reverse-executed is _not_ the one pointed to by the program
|
counter, but the instruction executed prior to that one. For
|
counter, but the instruction executed prior to that one. For
|
instance, if the last instruction was a jump, `reverse-stepi' will
|
instance, if the last instruction was a jump, `reverse-stepi' will
|
take you back from the destination of the jump to the jump
|
take you back from the destination of the jump to the jump
|
instruction itself.
|
instruction itself.
|
|
|
`reverse-next [COUNT]'
|
`reverse-next [COUNT]'
|
Run backward to the beginning of the previous line executed in the
|
Run backward to the beginning of the previous line executed in the
|
current (innermost) stack frame. If the line contains function
|
current (innermost) stack frame. If the line contains function
|
calls, they will be "un-executed" without stopping. Starting from
|
calls, they will be "un-executed" without stopping. Starting from
|
the first line of a function, `reverse-next' will take you back to
|
the first line of a function, `reverse-next' will take you back to
|
the caller of that function, _before_ the function was called,
|
the caller of that function, _before_ the function was called,
|
just as the normal `next' command would take you from the last
|
just as the normal `next' command would take you from the last
|
line of a function back to its return to its caller (2).
|
line of a function back to its return to its caller (2).
|
|
|
`reverse-nexti [COUNT]'
|
`reverse-nexti [COUNT]'
|
Like `nexti', `reverse-nexti' executes a single instruction in
|
Like `nexti', `reverse-nexti' executes a single instruction in
|
reverse, except that called functions are "un-executed" atomically.
|
reverse, except that called functions are "un-executed" atomically.
|
That is, if the previously executed instruction was a return from
|
That is, if the previously executed instruction was a return from
|
another function, `reverse-nexti' will continue to execute in
|
another function, `reverse-nexti' will continue to execute in
|
reverse until the call to that function (from the current stack
|
reverse until the call to that function (from the current stack
|
frame) is reached.
|
frame) is reached.
|
|
|
`reverse-finish'
|
`reverse-finish'
|
Just as the `finish' command takes you to the point where the
|
Just as the `finish' command takes you to the point where the
|
current function returns, `reverse-finish' takes you to the point
|
current function returns, `reverse-finish' takes you to the point
|
where it was called. Instead of ending up at the end of the
|
where it was called. Instead of ending up at the end of the
|
current function invocation, you end up at the beginning.
|
current function invocation, you end up at the beginning.
|
|
|
`set exec-direction'
|
`set exec-direction'
|
Set the direction of target execution.
|
Set the direction of target execution.
|
|
|
`set exec-direction reverse'
|
`set exec-direction reverse'
|
GDB will perform all execution commands in reverse, until the
|
GDB will perform all execution commands in reverse, until the
|
exec-direction mode is changed to "forward". Affected commands
|
exec-direction mode is changed to "forward". Affected commands
|
include `step, stepi, next, nexti, continue, and finish'. The
|
include `step, stepi, next, nexti, continue, and finish'. The
|
`return' command cannot be used in reverse mode.
|
`return' command cannot be used in reverse mode.
|
|
|
`set exec-direction forward'
|
`set exec-direction forward'
|
GDB will perform all execution commands in the normal fashion.
|
GDB will perform all execution commands in the normal fashion.
|
This is the default.
|
This is the default.
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) Note that some side effects are easier to undo than others. For
|
(1) Note that some side effects are easier to undo than others. For
|
instance, memory and registers are relatively easy, but device I/O is
|
instance, memory and registers are relatively easy, but device I/O is
|
hard. Some targets may be able undo things like device I/O, and some
|
hard. Some targets may be able undo things like device I/O, and some
|
may not.
|
may not.
|
|
|
The contract between GDB and the reverse executing target requires
|
The contract between GDB and the reverse executing target requires
|
only that the target do something reasonable when GDB tells it to
|
only that the target do something reasonable when GDB tells it to
|
execute backwards, and then report the results back to GDB. Whatever
|
execute backwards, and then report the results back to GDB. Whatever
|
the target reports back to GDB, GDB will report back to the user. GDB
|
the target reports back to GDB, GDB will report back to the user. GDB
|
assumes that the memory and registers that the target reports are in a
|
assumes that the memory and registers that the target reports are in a
|
consistant state, but GDB accepts whatever it is given.
|
consistant state, but GDB accepts whatever it is given.
|
|
|
(2) Unless the code is too heavily optimized.
|
(2) Unless the code is too heavily optimized.
|
|
|
|
|
File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top
|
File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top
|
|
|
7 Recording Inferior's Execution and Replaying It
|
7 Recording Inferior's Execution and Replaying It
|
*************************************************
|
*************************************************
|
|
|
On some platforms, GDB provides a special "process record and replay"
|
On some platforms, GDB provides a special "process record and replay"
|
target that can record a log of the process execution, and replay it
|
target that can record a log of the process execution, and replay it
|
later with both forward and reverse execution commands.
|
later with both forward and reverse execution commands.
|
|
|
When this target is in use, if the execution log includes the record
|
When this target is in use, if the execution log includes the record
|
for the next instruction, GDB will debug in "replay mode". In the
|
for the next instruction, GDB will debug in "replay mode". In the
|
replay mode, the inferior does not really execute code instructions.
|
replay mode, the inferior does not really execute code instructions.
|
Instead, all the events that normally happen during code execution are
|
Instead, all the events that normally happen during code execution are
|
taken from the execution log. While code is not really executed in
|
taken from the execution log. While code is not really executed in
|
replay mode, the values of registers (including the program counter
|
replay mode, the values of registers (including the program counter
|
register) and the memory of the inferior are still changed as they
|
register) and the memory of the inferior are still changed as they
|
normally would. Their contents are taken from the execution log.
|
normally would. Their contents are taken from the execution log.
|
|
|
If the record for the next instruction is not in the execution log,
|
If the record for the next instruction is not in the execution log,
|
GDB will debug in "record mode". In this mode, the inferior executes
|
GDB will debug in "record mode". In this mode, the inferior executes
|
normally, and GDB records the execution log for future replay.
|
normally, and GDB records the execution log for future replay.
|
|
|
The process record and replay target supports reverse execution
|
The process record and replay target supports reverse execution
|
(*note Reverse Execution::), even if the platform on which the inferior
|
(*note Reverse Execution::), even if the platform on which the inferior
|
runs does not. However, the reverse execution is limited in this case
|
runs does not. However, the reverse execution is limited in this case
|
by the range of the instructions recorded in the execution log. In
|
by the range of the instructions recorded in the execution log. In
|
other words, reverse execution on platforms that don't support it
|
other words, reverse execution on platforms that don't support it
|
directly can only be done in the replay mode.
|
directly can only be done in the replay mode.
|
|
|
When debugging in the reverse direction, GDB will work in replay
|
When debugging in the reverse direction, GDB will work in replay
|
mode as long as the execution log includes the record for the previous
|
mode as long as the execution log includes the record for the previous
|
instruction; otherwise, it will work in record mode, if the platform
|
instruction; otherwise, it will work in record mode, if the platform
|
supports reverse execution, or stop if not.
|
supports reverse execution, or stop if not.
|
|
|
For architecture environments that support process record and replay,
|
For architecture environments that support process record and replay,
|
GDB provides the following commands:
|
GDB provides the following commands:
|
|
|
`target record'
|
`target record'
|
This command starts the process record and replay target. The
|
This command starts the process record and replay target. The
|
process record and replay target can only debug a process that is
|
process record and replay target can only debug a process that is
|
already running. Therefore, you need first to start the process
|
already running. Therefore, you need first to start the process
|
with the `run' or `start' commands, and then start the recording
|
with the `run' or `start' commands, and then start the recording
|
with the `target record' command.
|
with the `target record' command.
|
|
|
Both `record' and `rec' are aliases of `target record'.
|
Both `record' and `rec' are aliases of `target record'.
|
|
|
Displaced stepping (*note displaced stepping: Maintenance
|
Displaced stepping (*note displaced stepping: Maintenance
|
Commands.) will be automatically disabled when process record and
|
Commands.) will be automatically disabled when process record and
|
replay target is started. That's because the process record and
|
replay target is started. That's because the process record and
|
replay target doesn't support displaced stepping.
|
replay target doesn't support displaced stepping.
|
|
|
If the inferior is in the non-stop mode (*note Non-Stop Mode::) or
|
If the inferior is in the non-stop mode (*note Non-Stop Mode::) or
|
in the asynchronous execution mode (*note Background Execution::),
|
in the asynchronous execution mode (*note Background Execution::),
|
the process record and replay target cannot be started because it
|
the process record and replay target cannot be started because it
|
doesn't support these two modes.
|
doesn't support these two modes.
|
|
|
`record stop'
|
`record stop'
|
Stop the process record and replay target. When process record and
|
Stop the process record and replay target. When process record and
|
replay target stops, the entire execution log will be deleted and
|
replay target stops, the entire execution log will be deleted and
|
the inferior will either be terminated, or will remain in its
|
the inferior will either be terminated, or will remain in its
|
final state.
|
final state.
|
|
|
When you stop the process record and replay target in record mode
|
When you stop the process record and replay target in record mode
|
(at the end of the execution log), the inferior will be stopped at
|
(at the end of the execution log), the inferior will be stopped at
|
the next instruction that would have been recorded. In other
|
the next instruction that would have been recorded. In other
|
words, if you record for a while and then stop recording, the
|
words, if you record for a while and then stop recording, the
|
inferior process will be left in the same state as if the
|
inferior process will be left in the same state as if the
|
recording never happened.
|
recording never happened.
|
|
|
On the other hand, if the process record and replay target is
|
On the other hand, if the process record and replay target is
|
stopped while in replay mode (that is, not at the end of the
|
stopped while in replay mode (that is, not at the end of the
|
execution log, but at some earlier point), the inferior process
|
execution log, but at some earlier point), the inferior process
|
will become "live" at that earlier state, and it will then be
|
will become "live" at that earlier state, and it will then be
|
possible to continue the usual "live" debugging of the process
|
possible to continue the usual "live" debugging of the process
|
from that state.
|
from that state.
|
|
|
When the inferior process exits, or GDB detaches from it, process
|
When the inferior process exits, or GDB detaches from it, process
|
record and replay target will automatically stop itself.
|
record and replay target will automatically stop itself.
|
|
|
`record save FILENAME'
|
`record save FILENAME'
|
Save the execution log to a file `FILENAME'. Default filename is
|
Save the execution log to a file `FILENAME'. Default filename is
|
`gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the
|
`gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the
|
inferior.
|
inferior.
|
|
|
`record restore FILENAME'
|
`record restore FILENAME'
|
Restore the execution log from a file `FILENAME'. File must have
|
Restore the execution log from a file `FILENAME'. File must have
|
been created with `record save'.
|
been created with `record save'.
|
|
|
`set record insn-number-max LIMIT'
|
`set record insn-number-max LIMIT'
|
Set the limit of instructions to be recorded. Default value is
|
Set the limit of instructions to be recorded. Default value is
|
200000.
|
200000.
|
|
|
If LIMIT is a positive number, then GDB will start deleting
|
If LIMIT is a positive number, then GDB will start deleting
|
instructions from the log once the number of the record
|
instructions from the log once the number of the record
|
instructions becomes greater than LIMIT. For every new recorded
|
instructions becomes greater than LIMIT. For every new recorded
|
instruction, GDB will delete the earliest recorded instruction to
|
instruction, GDB will delete the earliest recorded instruction to
|
keep the number of recorded instructions at the limit. (Since
|
keep the number of recorded instructions at the limit. (Since
|
deleting recorded instructions loses information, GDB lets you
|
deleting recorded instructions loses information, GDB lets you
|
control what happens when the limit is reached, by means of the
|
control what happens when the limit is reached, by means of the
|
`stop-at-limit' option, described below.)
|
`stop-at-limit' option, described below.)
|
|
|
If LIMIT is zero, GDB will never delete recorded instructions from
|
If LIMIT is zero, GDB will never delete recorded instructions from
|
the execution log. The number of recorded instructions is
|
the execution log. The number of recorded instructions is
|
unlimited in this case.
|
unlimited in this case.
|
|
|
`show record insn-number-max'
|
`show record insn-number-max'
|
Show the limit of instructions to be recorded.
|
Show the limit of instructions to be recorded.
|
|
|
`set record stop-at-limit'
|
`set record stop-at-limit'
|
Control the behavior when the number of recorded instructions
|
Control the behavior when the number of recorded instructions
|
reaches the limit. If ON (the default), GDB will stop when the
|
reaches the limit. If ON (the default), GDB will stop when the
|
limit is reached for the first time and ask you whether you want
|
limit is reached for the first time and ask you whether you want
|
to stop the inferior or continue running it and recording the
|
to stop the inferior or continue running it and recording the
|
execution log. If you decide to continue recording, each new
|
execution log. If you decide to continue recording, each new
|
recorded instruction will cause the oldest one to be deleted.
|
recorded instruction will cause the oldest one to be deleted.
|
|
|
If this option is OFF, GDB will automatically delete the oldest
|
If this option is OFF, GDB will automatically delete the oldest
|
record to make room for each new one, without asking.
|
record to make room for each new one, without asking.
|
|
|
`show record stop-at-limit'
|
`show record stop-at-limit'
|
Show the current setting of `stop-at-limit'.
|
Show the current setting of `stop-at-limit'.
|
|
|
`set record memory-query'
|
`set record memory-query'
|
Control the behavior when GDB is unable to record memory changes
|
Control the behavior when GDB is unable to record memory changes
|
caused by an instruction. If ON, GDB will query whether to stop
|
caused by an instruction. If ON, GDB will query whether to stop
|
the inferior in that case.
|
the inferior in that case.
|
|
|
If this option is OFF (the default), GDB will automatically ignore
|
If this option is OFF (the default), GDB will automatically ignore
|
the effect of such instructions on memory. Later, when GDB
|
the effect of such instructions on memory. Later, when GDB
|
replays this execution log, it will mark the log of this
|
replays this execution log, it will mark the log of this
|
instruction as not accessible, and it will not affect the replay
|
instruction as not accessible, and it will not affect the replay
|
results.
|
results.
|
|
|
`show record memory-query'
|
`show record memory-query'
|
Show the current setting of `memory-query'.
|
Show the current setting of `memory-query'.
|
|
|
`info record'
|
`info record'
|
Show various statistics about the state of process record and its
|
Show various statistics about the state of process record and its
|
in-memory execution log buffer, including:
|
in-memory execution log buffer, including:
|
|
|
* Whether in record mode or replay mode.
|
* Whether in record mode or replay mode.
|
|
|
* Lowest recorded instruction number (counting from when the
|
* Lowest recorded instruction number (counting from when the
|
current execution log started recording instructions).
|
current execution log started recording instructions).
|
|
|
* Highest recorded instruction number.
|
* Highest recorded instruction number.
|
|
|
* Current instruction about to be replayed (if in replay mode).
|
* Current instruction about to be replayed (if in replay mode).
|
|
|
* Number of instructions contained in the execution log.
|
* Number of instructions contained in the execution log.
|
|
|
* Maximum number of instructions that may be contained in the
|
* Maximum number of instructions that may be contained in the
|
execution log.
|
execution log.
|
|
|
`record delete'
|
`record delete'
|
When record target runs in replay mode ("in the past"), delete the
|
When record target runs in replay mode ("in the past"), delete the
|
subsequent execution log and begin to record a new execution log
|
subsequent execution log and begin to record a new execution log
|
starting from the current address. This means you will abandon
|
starting from the current address. This means you will abandon
|
the previously recorded "future" and begin recording a new
|
the previously recorded "future" and begin recording a new
|
"future".
|
"future".
|
|
|
|
|
File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top
|
File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top
|
|
|
8 Examining the Stack
|
8 Examining the Stack
|
*********************
|
*********************
|
|
|
When your program has stopped, the first thing you need to know is
|
When your program has stopped, the first thing you need to know is
|
where it stopped and how it got there.
|
where it stopped and how it got there.
|
|
|
Each time your program performs a function call, information about
|
Each time your program performs a function call, information about
|
the call is generated. That information includes the location of the
|
the call is generated. That information includes the location of the
|
call in your program, the arguments of the call, and the local
|
call in your program, the arguments of the call, and the local
|
variables of the function being called. The information is saved in a
|
variables of the function being called. The information is saved in a
|
block of data called a "stack frame". The stack frames are allocated
|
block of data called a "stack frame". The stack frames are allocated
|
in a region of memory called the "call stack".
|
in a region of memory called the "call stack".
|
|
|
When your program stops, the GDB commands for examining the stack
|
When your program stops, the GDB commands for examining the stack
|
allow you to see all of this information.
|
allow you to see all of this information.
|
|
|
One of the stack frames is "selected" by GDB and many GDB commands
|
One of the stack frames is "selected" by GDB and many GDB commands
|
refer implicitly to the selected frame. In particular, whenever you
|
refer implicitly to the selected frame. In particular, whenever you
|
ask GDB for the value of a variable in your program, the value is found
|
ask GDB for the value of a variable in your program, the value is found
|
in the selected frame. There are special GDB commands to select
|
in the selected frame. There are special GDB commands to select
|
whichever frame you are interested in. *Note Selecting a Frame:
|
whichever frame you are interested in. *Note Selecting a Frame:
|
Selection.
|
Selection.
|
|
|
When your program stops, GDB automatically selects the currently
|
When your program stops, GDB automatically selects the currently
|
executing frame and describes it briefly, similar to the `frame'
|
executing frame and describes it briefly, similar to the `frame'
|
command (*note Information about a Frame: Frame Info.).
|
command (*note Information about a Frame: Frame Info.).
|
|
|
* Menu:
|
* Menu:
|
|
|
* Frames:: Stack frames
|
* Frames:: Stack frames
|
* Backtrace:: Backtraces
|
* Backtrace:: Backtraces
|
* Selection:: Selecting a frame
|
* Selection:: Selecting a frame
|
* Frame Info:: Information on a frame
|
* Frame Info:: Information on a frame
|
|
|
|
|
File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack
|
File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack
|
|
|
8.1 Stack Frames
|
8.1 Stack Frames
|
================
|
================
|
|
|
The call stack is divided up into contiguous pieces called "stack
|
The call stack is divided up into contiguous pieces called "stack
|
frames", or "frames" for short; each frame is the data associated with
|
frames", or "frames" for short; each frame is the data associated with
|
one call to one function. The frame contains the arguments given to
|
one call to one function. The frame contains the arguments given to
|
the function, the function's local variables, and the address at which
|
the function, the function's local variables, and the address at which
|
the function is executing.
|
the function is executing.
|
|
|
When your program is started, the stack has only one frame, that of
|
When your program is started, the stack has only one frame, that of
|
the function `main'. This is called the "initial" frame or the
|
the function `main'. This is called the "initial" frame or the
|
"outermost" frame. Each time a function is called, a new frame is
|
"outermost" frame. Each time a function is called, a new frame is
|
made. Each time a function returns, the frame for that function
|
made. Each time a function returns, the frame for that function
|
invocation is eliminated. If a function is recursive, there can be
|
invocation is eliminated. If a function is recursive, there can be
|
many frames for the same function. The frame for the function in which
|
many frames for the same function. The frame for the function in which
|
execution is actually occurring is called the "innermost" frame. This
|
execution is actually occurring is called the "innermost" frame. This
|
is the most recently created of all the stack frames that still exist.
|
is the most recently created of all the stack frames that still exist.
|
|
|
Inside your program, stack frames are identified by their addresses.
|
Inside your program, stack frames are identified by their addresses.
|
A stack frame consists of many bytes, each of which has its own
|
A stack frame consists of many bytes, each of which has its own
|
address; each kind of computer has a convention for choosing one byte
|
address; each kind of computer has a convention for choosing one byte
|
whose address serves as the address of the frame. Usually this address
|
whose address serves as the address of the frame. Usually this address
|
is kept in a register called the "frame pointer register" (*note $fp:
|
is kept in a register called the "frame pointer register" (*note $fp:
|
Registers.) while execution is going on in that frame.
|
Registers.) while execution is going on in that frame.
|
|
|
GDB assigns numbers to all existing stack frames, starting with zero
|
GDB assigns numbers to all existing stack frames, starting with zero
|
for the innermost frame, one for the frame that called it, and so on
|
for the innermost frame, one for the frame that called it, and so on
|
upward. These numbers do not really exist in your program; they are
|
upward. These numbers do not really exist in your program; they are
|
assigned by GDB to give you a way of designating stack frames in GDB
|
assigned by GDB to give you a way of designating stack frames in GDB
|
commands.
|
commands.
|
|
|
Some compilers provide a way to compile functions so that they
|
Some compilers provide a way to compile functions so that they
|
operate without stack frames. (For example, the GCC option
|
operate without stack frames. (For example, the GCC option
|
`-fomit-frame-pointer'
|
`-fomit-frame-pointer'
|
generates functions without a frame.) This is occasionally done
|
generates functions without a frame.) This is occasionally done
|
with heavily used library functions to save the frame setup time. GDB
|
with heavily used library functions to save the frame setup time. GDB
|
has limited facilities for dealing with these function invocations. If
|
has limited facilities for dealing with these function invocations. If
|
the innermost function invocation has no stack frame, GDB nevertheless
|
the innermost function invocation has no stack frame, GDB nevertheless
|
regards it as though it had a separate frame, which is numbered zero as
|
regards it as though it had a separate frame, which is numbered zero as
|
usual, allowing correct tracing of the function call chain. However,
|
usual, allowing correct tracing of the function call chain. However,
|
GDB has no provision for frameless functions elsewhere in the stack.
|
GDB has no provision for frameless functions elsewhere in the stack.
|
|
|
`frame ARGS'
|
`frame ARGS'
|
The `frame' command allows you to move from one stack frame to
|
The `frame' command allows you to move from one stack frame to
|
another, and to print the stack frame you select. ARGS may be
|
another, and to print the stack frame you select. ARGS may be
|
either the address of the frame or the stack frame number.
|
either the address of the frame or the stack frame number.
|
Without an argument, `frame' prints the current stack frame.
|
Without an argument, `frame' prints the current stack frame.
|
|
|
`select-frame'
|
`select-frame'
|
The `select-frame' command allows you to move from one stack frame
|
The `select-frame' command allows you to move from one stack frame
|
to another without printing the frame. This is the silent version
|
to another without printing the frame. This is the silent version
|
of `frame'.
|
of `frame'.
|
|
|
|
|
File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack
|
File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack
|
|
|
8.2 Backtraces
|
8.2 Backtraces
|
==============
|
==============
|
|
|
A backtrace is a summary of how your program got where it is. It shows
|
A backtrace is a summary of how your program got where it is. It shows
|
one line per frame, for many frames, starting with the currently
|
one line per frame, for many frames, starting with the currently
|
executing frame (frame zero), followed by its caller (frame one), and
|
executing frame (frame zero), followed by its caller (frame one), and
|
on up the stack.
|
on up the stack.
|
|
|
`backtrace'
|
`backtrace'
|
`bt'
|
`bt'
|
Print a backtrace of the entire stack: one line per frame for all
|
Print a backtrace of the entire stack: one line per frame for all
|
frames in the stack.
|
frames in the stack.
|
|
|
You can stop the backtrace at any time by typing the system
|
You can stop the backtrace at any time by typing the system
|
interrupt character, normally `Ctrl-c'.
|
interrupt character, normally `Ctrl-c'.
|
|
|
`backtrace N'
|
`backtrace N'
|
`bt N'
|
`bt N'
|
Similar, but print only the innermost N frames.
|
Similar, but print only the innermost N frames.
|
|
|
`backtrace -N'
|
`backtrace -N'
|
`bt -N'
|
`bt -N'
|
Similar, but print only the outermost N frames.
|
Similar, but print only the outermost N frames.
|
|
|
`backtrace full'
|
`backtrace full'
|
`bt full'
|
`bt full'
|
`bt full N'
|
`bt full N'
|
`bt full -N'
|
`bt full -N'
|
Print the values of the local variables also. N specifies the
|
Print the values of the local variables also. N specifies the
|
number of frames to print, as described above.
|
number of frames to print, as described above.
|
|
|
The names `where' and `info stack' (abbreviated `info s') are
|
The names `where' and `info stack' (abbreviated `info s') are
|
additional aliases for `backtrace'.
|
additional aliases for `backtrace'.
|
|
|
In a multi-threaded program, GDB by default shows the backtrace only
|
In a multi-threaded program, GDB by default shows the backtrace only
|
for the current thread. To display the backtrace for several or all of
|
for the current thread. To display the backtrace for several or all of
|
the threads, use the command `thread apply' (*note thread apply:
|
the threads, use the command `thread apply' (*note thread apply:
|
Threads.). For example, if you type `thread apply all backtrace', GDB
|
Threads.). For example, if you type `thread apply all backtrace', GDB
|
will display the backtrace for all the threads; this is handy when you
|
will display the backtrace for all the threads; this is handy when you
|
debug a core dump of a multi-threaded program.
|
debug a core dump of a multi-threaded program.
|
|
|
Each line in the backtrace shows the frame number and the function
|
Each line in the backtrace shows the frame number and the function
|
name. The program counter value is also shown--unless you use `set
|
name. The program counter value is also shown--unless you use `set
|
print address off'. The backtrace also shows the source file name and
|
print address off'. The backtrace also shows the source file name and
|
line number, as well as the arguments to the function. The program
|
line number, as well as the arguments to the function. The program
|
counter value is omitted if it is at the beginning of the code for that
|
counter value is omitted if it is at the beginning of the code for that
|
line number.
|
line number.
|
|
|
Here is an example of a backtrace. It was made with the command `bt
|
Here is an example of a backtrace. It was made with the command `bt
|
3', so it shows the innermost three frames.
|
3', so it shows the innermost three frames.
|
|
|
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
|
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
|
at builtin.c:993
|
at builtin.c:993
|
#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
|
#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
|
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
|
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
|
at macro.c:71
|
at macro.c:71
|
(More stack frames follow...)
|
(More stack frames follow...)
|
|
|
The display for frame zero does not begin with a program counter value,
|
The display for frame zero does not begin with a program counter value,
|
indicating that your program has stopped at the beginning of the code
|
indicating that your program has stopped at the beginning of the code
|
for line `993' of `builtin.c'.
|
for line `993' of `builtin.c'.
|
|
|
The value of parameter `data' in frame 1 has been replaced by `...'.
|
The value of parameter `data' in frame 1 has been replaced by `...'.
|
By default, GDB prints the value of a parameter only if it is a scalar
|
By default, GDB prints the value of a parameter only if it is a scalar
|
(integer, pointer, enumeration, etc). See command `set print
|
(integer, pointer, enumeration, etc). See command `set print
|
frame-arguments' in *note Print Settings:: for more details on how to
|
frame-arguments' in *note Print Settings:: for more details on how to
|
configure the way function parameter values are printed.
|
configure the way function parameter values are printed.
|
|
|
If your program was compiled with optimizations, some compilers will
|
If your program was compiled with optimizations, some compilers will
|
optimize away arguments passed to functions if those arguments are
|
optimize away arguments passed to functions if those arguments are
|
never used after the call. Such optimizations generate code that
|
never used after the call. Such optimizations generate code that
|
passes arguments through registers, but doesn't store those arguments
|
passes arguments through registers, but doesn't store those arguments
|
in the stack frame. GDB has no way of displaying such arguments in
|
in the stack frame. GDB has no way of displaying such arguments in
|
stack frames other than the innermost one. Here's what such a
|
stack frames other than the innermost one. Here's what such a
|
backtrace might look like:
|
backtrace might look like:
|
|
|
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
|
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
|
at builtin.c:993
|
at builtin.c:993
|
#1 0x6e38 in expand_macro (sym=) at macro.c:242
|
#1 0x6e38 in expand_macro (sym=) at macro.c:242
|
#2 0x6840 in expand_token (obs=0x0, t=, td=0xf7fffb08)
|
#2 0x6840 in expand_token (obs=0x0, t=, td=0xf7fffb08)
|
at macro.c:71
|
at macro.c:71
|
(More stack frames follow...)
|
(More stack frames follow...)
|
|
|
The values of arguments that were not saved in their stack frames are
|
The values of arguments that were not saved in their stack frames are
|
shown as `'.
|
shown as `'.
|
|
|
If you need to display the values of such optimized-out arguments,
|
If you need to display the values of such optimized-out arguments,
|
either deduce that from other variables whose values depend on the one
|
either deduce that from other variables whose values depend on the one
|
you are interested in, or recompile without optimizations.
|
you are interested in, or recompile without optimizations.
|
|
|
Most programs have a standard user entry point--a place where system
|
Most programs have a standard user entry point--a place where system
|
libraries and startup code transition into user code. For C this is
|
libraries and startup code transition into user code. For C this is
|
`main'(1). When GDB finds the entry function in a backtrace it will
|
`main'(1). When GDB finds the entry function in a backtrace it will
|
terminate the backtrace, to avoid tracing into highly system-specific
|
terminate the backtrace, to avoid tracing into highly system-specific
|
(and generally uninteresting) code.
|
(and generally uninteresting) code.
|
|
|
If you need to examine the startup code, or limit the number of
|
If you need to examine the startup code, or limit the number of
|
levels in a backtrace, you can change this behavior:
|
levels in a backtrace, you can change this behavior:
|
|
|
`set backtrace past-main'
|
`set backtrace past-main'
|
`set backtrace past-main on'
|
`set backtrace past-main on'
|
Backtraces will continue past the user entry point.
|
Backtraces will continue past the user entry point.
|
|
|
`set backtrace past-main off'
|
`set backtrace past-main off'
|
Backtraces will stop when they encounter the user entry point.
|
Backtraces will stop when they encounter the user entry point.
|
This is the default.
|
This is the default.
|
|
|
`show backtrace past-main'
|
`show backtrace past-main'
|
Display the current user entry point backtrace policy.
|
Display the current user entry point backtrace policy.
|
|
|
`set backtrace past-entry'
|
`set backtrace past-entry'
|
`set backtrace past-entry on'
|
`set backtrace past-entry on'
|
Backtraces will continue past the internal entry point of an
|
Backtraces will continue past the internal entry point of an
|
application. This entry point is encoded by the linker when the
|
application. This entry point is encoded by the linker when the
|
application is built, and is likely before the user entry point
|
application is built, and is likely before the user entry point
|
`main' (or equivalent) is called.
|
`main' (or equivalent) is called.
|
|
|
`set backtrace past-entry off'
|
`set backtrace past-entry off'
|
Backtraces will stop when they encounter the internal entry point
|
Backtraces will stop when they encounter the internal entry point
|
of an application. This is the default.
|
of an application. This is the default.
|
|
|
`show backtrace past-entry'
|
`show backtrace past-entry'
|
Display the current internal entry point backtrace policy.
|
Display the current internal entry point backtrace policy.
|
|
|
`set backtrace limit N'
|
`set backtrace limit N'
|
`set backtrace limit 0'
|
`set backtrace limit 0'
|
Limit the backtrace to N levels. A value of zero means unlimited.
|
Limit the backtrace to N levels. A value of zero means unlimited.
|
|
|
`show backtrace limit'
|
`show backtrace limit'
|
Display the current limit on backtrace levels.
|
Display the current limit on backtrace levels.
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) Note that embedded programs (the so-called "free-standing"
|
(1) Note that embedded programs (the so-called "free-standing"
|
environment) are not required to have a `main' function as the entry
|
environment) are not required to have a `main' function as the entry
|
point. They could even have multiple entry points.
|
point. They could even have multiple entry points.
|
|
|
|
|
File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack
|
File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack
|
|
|
8.3 Selecting a Frame
|
8.3 Selecting a Frame
|
=====================
|
=====================
|
|
|
Most commands for examining the stack and other data in your program
|
Most commands for examining the stack and other data in your program
|
work on whichever stack frame is selected at the moment. Here are the
|
work on whichever stack frame is selected at the moment. Here are the
|
commands for selecting a stack frame; all of them finish by printing a
|
commands for selecting a stack frame; all of them finish by printing a
|
brief description of the stack frame just selected.
|
brief description of the stack frame just selected.
|
|
|
`frame N'
|
`frame N'
|
`f N'
|
`f N'
|
Select frame number N. Recall that frame zero is the innermost
|
Select frame number N. Recall that frame zero is the innermost
|
(currently executing) frame, frame one is the frame that called the
|
(currently executing) frame, frame one is the frame that called the
|
innermost one, and so on. The highest-numbered frame is the one
|
innermost one, and so on. The highest-numbered frame is the one
|
for `main'.
|
for `main'.
|
|
|
`frame ADDR'
|
`frame ADDR'
|
`f ADDR'
|
`f ADDR'
|
Select the frame at address ADDR. This is useful mainly if the
|
Select the frame at address ADDR. This is useful mainly if the
|
chaining of stack frames has been damaged by a bug, making it
|
chaining of stack frames has been damaged by a bug, making it
|
impossible for GDB to assign numbers properly to all frames. In
|
impossible for GDB to assign numbers properly to all frames. In
|
addition, this can be useful when your program has multiple stacks
|
addition, this can be useful when your program has multiple stacks
|
and switches between them.
|
and switches between them.
|
|
|
On the SPARC architecture, `frame' needs two addresses to select
|
On the SPARC architecture, `frame' needs two addresses to select
|
an arbitrary frame: a frame pointer and a stack pointer.
|
an arbitrary frame: a frame pointer and a stack pointer.
|
|
|
On the MIPS and Alpha architecture, it needs two addresses: a stack
|
On the MIPS and Alpha architecture, it needs two addresses: a stack
|
pointer and a program counter.
|
pointer and a program counter.
|
|
|
On the 29k architecture, it needs three addresses: a register stack
|
On the 29k architecture, it needs three addresses: a register stack
|
pointer, a program counter, and a memory stack pointer.
|
pointer, a program counter, and a memory stack pointer.
|
|
|
`up N'
|
`up N'
|
Move N frames up the stack. For positive numbers N, this advances
|
Move N frames up the stack. For positive numbers N, this advances
|
toward the outermost frame, to higher frame numbers, to frames
|
toward the outermost frame, to higher frame numbers, to frames
|
that have existed longer. N defaults to one.
|
that have existed longer. N defaults to one.
|
|
|
`down N'
|
`down N'
|
Move N frames down the stack. For positive numbers N, this
|
Move N frames down the stack. For positive numbers N, this
|
advances toward the innermost frame, to lower frame numbers, to
|
advances toward the innermost frame, to lower frame numbers, to
|
frames that were created more recently. N defaults to one. You
|
frames that were created more recently. N defaults to one. You
|
may abbreviate `down' as `do'.
|
may abbreviate `down' as `do'.
|
|
|
All of these commands end by printing two lines of output describing
|
All of these commands end by printing two lines of output describing
|
the frame. The first line shows the frame number, the function name,
|
the frame. The first line shows the frame number, the function name,
|
the arguments, and the source file and line number of execution in that
|
the arguments, and the source file and line number of execution in that
|
frame. The second line shows the text of that source line.
|
frame. The second line shows the text of that source line.
|
|
|
For example:
|
For example:
|
|
|
(gdb) up
|
(gdb) up
|
#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
|
#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
|
at env.c:10
|
at env.c:10
|
10 read_input_file (argv[i]);
|
10 read_input_file (argv[i]);
|
|
|
After such a printout, the `list' command with no arguments prints
|
After such a printout, the `list' command with no arguments prints
|
ten lines centered on the point of execution in the frame. You can
|
ten lines centered on the point of execution in the frame. You can
|
also edit the program at the point of execution with your favorite
|
also edit the program at the point of execution with your favorite
|
editing program by typing `edit'. *Note Printing Source Lines: List,
|
editing program by typing `edit'. *Note Printing Source Lines: List,
|
for details.
|
for details.
|
|
|
`up-silently N'
|
`up-silently N'
|
`down-silently N'
|
`down-silently N'
|
These two commands are variants of `up' and `down', respectively;
|
These two commands are variants of `up' and `down', respectively;
|
they differ in that they do their work silently, without causing
|
they differ in that they do their work silently, without causing
|
display of the new frame. They are intended primarily for use in
|
display of the new frame. They are intended primarily for use in
|
GDB command scripts, where the output might be unnecessary and
|
GDB command scripts, where the output might be unnecessary and
|
distracting.
|
distracting.
|
|
|
|
|
File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack
|
File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack
|
|
|
8.4 Information About a Frame
|
8.4 Information About a Frame
|
=============================
|
=============================
|
|
|
There are several other commands to print information about the selected
|
There are several other commands to print information about the selected
|
stack frame.
|
stack frame.
|
|
|
`frame'
|
`frame'
|
`f'
|
`f'
|
When used without any argument, this command does not change which
|
When used without any argument, this command does not change which
|
frame is selected, but prints a brief description of the currently
|
frame is selected, but prints a brief description of the currently
|
selected stack frame. It can be abbreviated `f'. With an
|
selected stack frame. It can be abbreviated `f'. With an
|
argument, this command is used to select a stack frame. *Note
|
argument, this command is used to select a stack frame. *Note
|
Selecting a Frame: Selection.
|
Selecting a Frame: Selection.
|
|
|
`info frame'
|
`info frame'
|
`info f'
|
`info f'
|
This command prints a verbose description of the selected stack
|
This command prints a verbose description of the selected stack
|
frame, including:
|
frame, including:
|
|
|
* the address of the frame
|
* the address of the frame
|
|
|
* the address of the next frame down (called by this frame)
|
* the address of the next frame down (called by this frame)
|
|
|
* the address of the next frame up (caller of this frame)
|
* the address of the next frame up (caller of this frame)
|
|
|
* the language in which the source code corresponding to this
|
* the language in which the source code corresponding to this
|
frame is written
|
frame is written
|
|
|
* the address of the frame's arguments
|
* the address of the frame's arguments
|
|
|
* the address of the frame's local variables
|
* the address of the frame's local variables
|
|
|
* the program counter saved in it (the address of execution in
|
* the program counter saved in it (the address of execution in
|
the caller frame)
|
the caller frame)
|
|
|
* which registers were saved in the frame
|
* which registers were saved in the frame
|
|
|
The verbose description is useful when something has gone wrong
|
The verbose description is useful when something has gone wrong
|
that has made the stack format fail to fit the usual conventions.
|
that has made the stack format fail to fit the usual conventions.
|
|
|
`info frame ADDR'
|
`info frame ADDR'
|
`info f ADDR'
|
`info f ADDR'
|
Print a verbose description of the frame at address ADDR, without
|
Print a verbose description of the frame at address ADDR, without
|
selecting that frame. The selected frame remains unchanged by this
|
selecting that frame. The selected frame remains unchanged by this
|
command. This requires the same kind of address (more than one
|
command. This requires the same kind of address (more than one
|
for some architectures) that you specify in the `frame' command.
|
for some architectures) that you specify in the `frame' command.
|
*Note Selecting a Frame: Selection.
|
*Note Selecting a Frame: Selection.
|
|
|
`info args'
|
`info args'
|
Print the arguments of the selected frame, each on a separate line.
|
Print the arguments of the selected frame, each on a separate line.
|
|
|
`info locals'
|
`info locals'
|
Print the local variables of the selected frame, each on a separate
|
Print the local variables of the selected frame, each on a separate
|
line. These are all variables (declared either static or
|
line. These are all variables (declared either static or
|
automatic) accessible at the point of execution of the selected
|
automatic) accessible at the point of execution of the selected
|
frame.
|
frame.
|
|
|
`info catch'
|
`info catch'
|
Print a list of all the exception handlers that are active in the
|
Print a list of all the exception handlers that are active in the
|
current stack frame at the current point of execution. To see
|
current stack frame at the current point of execution. To see
|
other exception handlers, visit the associated frame (using the
|
other exception handlers, visit the associated frame (using the
|
`up', `down', or `frame' commands); then type `info catch'. *Note
|
`up', `down', or `frame' commands); then type `info catch'. *Note
|
Setting Catchpoints: Set Catchpoints.
|
Setting Catchpoints: Set Catchpoints.
|
|
|
|
|
|
|
File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top
|
File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top
|
|
|
9 Examining Source Files
|
9 Examining Source Files
|
************************
|
************************
|
|
|
GDB can print parts of your program's source, since the debugging
|
GDB can print parts of your program's source, since the debugging
|
information recorded in the program tells GDB what source files were
|
information recorded in the program tells GDB what source files were
|
used to build it. When your program stops, GDB spontaneously prints
|
used to build it. When your program stops, GDB spontaneously prints
|
the line where it stopped. Likewise, when you select a stack frame
|
the line where it stopped. Likewise, when you select a stack frame
|
(*note Selecting a Frame: Selection.), GDB prints the line where
|
(*note Selecting a Frame: Selection.), GDB prints the line where
|
execution in that frame has stopped. You can print other portions of
|
execution in that frame has stopped. You can print other portions of
|
source files by explicit command.
|
source files by explicit command.
|
|
|
If you use GDB through its GNU Emacs interface, you may prefer to
|
If you use GDB through its GNU Emacs interface, you may prefer to
|
use Emacs facilities to view source; see *note Using GDB under GNU
|
use Emacs facilities to view source; see *note Using GDB under GNU
|
Emacs: Emacs.
|
Emacs: Emacs.
|
|
|
* Menu:
|
* Menu:
|
|
|
* List:: Printing source lines
|
* List:: Printing source lines
|
* Specify Location:: How to specify code locations
|
* Specify Location:: How to specify code locations
|
* Edit:: Editing source files
|
* Edit:: Editing source files
|
* Search:: Searching source files
|
* Search:: Searching source files
|
* Source Path:: Specifying source directories
|
* Source Path:: Specifying source directories
|
* Machine Code:: Source and machine code
|
* Machine Code:: Source and machine code
|
|
|
|
|
File: gdb.info, Node: List, Next: Specify Location, Up: Source
|
File: gdb.info, Node: List, Next: Specify Location, Up: Source
|
|
|
9.1 Printing Source Lines
|
9.1 Printing Source Lines
|
=========================
|
=========================
|
|
|
To print lines from a source file, use the `list' command (abbreviated
|
To print lines from a source file, use the `list' command (abbreviated
|
`l'). By default, ten lines are printed. There are several ways to
|
`l'). By default, ten lines are printed. There are several ways to
|
specify what part of the file you want to print; see *note Specify
|
specify what part of the file you want to print; see *note Specify
|
Location::, for the full list.
|
Location::, for the full list.
|
|
|
Here are the forms of the `list' command most commonly used:
|
Here are the forms of the `list' command most commonly used:
|
|
|
`list LINENUM'
|
`list LINENUM'
|
Print lines centered around line number LINENUM in the current
|
Print lines centered around line number LINENUM in the current
|
source file.
|
source file.
|
|
|
`list FUNCTION'
|
`list FUNCTION'
|
Print lines centered around the beginning of function FUNCTION.
|
Print lines centered around the beginning of function FUNCTION.
|
|
|
`list'
|
`list'
|
Print more lines. If the last lines printed were printed with a
|
Print more lines. If the last lines printed were printed with a
|
`list' command, this prints lines following the last lines
|
`list' command, this prints lines following the last lines
|
printed; however, if the last line printed was a solitary line
|
printed; however, if the last line printed was a solitary line
|
printed as part of displaying a stack frame (*note Examining the
|
printed as part of displaying a stack frame (*note Examining the
|
Stack: Stack.), this prints lines centered around that line.
|
Stack: Stack.), this prints lines centered around that line.
|
|
|
`list -'
|
`list -'
|
Print lines just before the lines last printed.
|
Print lines just before the lines last printed.
|
|
|
By default, GDB prints ten source lines with any of these forms of
|
By default, GDB prints ten source lines with any of these forms of
|
the `list' command. You can change this using `set listsize':
|
the `list' command. You can change this using `set listsize':
|
|
|
`set listsize COUNT'
|
`set listsize COUNT'
|
Make the `list' command display COUNT source lines (unless the
|
Make the `list' command display COUNT source lines (unless the
|
`list' argument explicitly specifies some other number).
|
`list' argument explicitly specifies some other number).
|
|
|
`show listsize'
|
`show listsize'
|
Display the number of lines that `list' prints.
|
Display the number of lines that `list' prints.
|
|
|
Repeating a `list' command with discards the argument, so it
|
Repeating a `list' command with discards the argument, so it
|
is equivalent to typing just `list'. This is more useful than listing
|
is equivalent to typing just `list'. This is more useful than listing
|
the same lines again. An exception is made for an argument of `-';
|
the same lines again. An exception is made for an argument of `-';
|
that argument is preserved in repetition so that each repetition moves
|
that argument is preserved in repetition so that each repetition moves
|
up in the source file.
|
up in the source file.
|
|
|
In general, the `list' command expects you to supply zero, one or two
|
In general, the `list' command expects you to supply zero, one or two
|
"linespecs". Linespecs specify source lines; there are several ways of
|
"linespecs". Linespecs specify source lines; there are several ways of
|
writing them (*note Specify Location::), but the effect is always to
|
writing them (*note Specify Location::), but the effect is always to
|
specify some source line.
|
specify some source line.
|
|
|
Here is a complete description of the possible arguments for `list':
|
Here is a complete description of the possible arguments for `list':
|
|
|
`list LINESPEC'
|
`list LINESPEC'
|
Print lines centered around the line specified by LINESPEC.
|
Print lines centered around the line specified by LINESPEC.
|
|
|
`list FIRST,LAST'
|
`list FIRST,LAST'
|
Print lines from FIRST to LAST. Both arguments are linespecs.
|
Print lines from FIRST to LAST. Both arguments are linespecs.
|
When a `list' command has two linespecs, and the source file of
|
When a `list' command has two linespecs, and the source file of
|
the second linespec is omitted, this refers to the same source
|
the second linespec is omitted, this refers to the same source
|
file as the first linespec.
|
file as the first linespec.
|
|
|
`list ,LAST'
|
`list ,LAST'
|
Print lines ending with LAST.
|
Print lines ending with LAST.
|
|
|
`list FIRST,'
|
`list FIRST,'
|
Print lines starting with FIRST.
|
Print lines starting with FIRST.
|
|
|
`list +'
|
`list +'
|
Print lines just after the lines last printed.
|
Print lines just after the lines last printed.
|
|
|
`list -'
|
`list -'
|
Print lines just before the lines last printed.
|
Print lines just before the lines last printed.
|
|
|
`list'
|
`list'
|
As described in the preceding table.
|
As described in the preceding table.
|
|
|
|
|
File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source
|
File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source
|
|
|
9.2 Specifying a Location
|
9.2 Specifying a Location
|
=========================
|
=========================
|
|
|
Several GDB commands accept arguments that specify a location of your
|
Several GDB commands accept arguments that specify a location of your
|
program's code. Since GDB is a source-level debugger, a location
|
program's code. Since GDB is a source-level debugger, a location
|
usually specifies some line in the source code; for that reason,
|
usually specifies some line in the source code; for that reason,
|
locations are also known as "linespecs".
|
locations are also known as "linespecs".
|
|
|
Here are all the different ways of specifying a code location that
|
Here are all the different ways of specifying a code location that
|
GDB understands:
|
GDB understands:
|
|
|
`LINENUM'
|
`LINENUM'
|
Specifies the line number LINENUM of the current source file.
|
Specifies the line number LINENUM of the current source file.
|
|
|
`-OFFSET'
|
`-OFFSET'
|
`+OFFSET'
|
`+OFFSET'
|
Specifies the line OFFSET lines before or after the "current
|
Specifies the line OFFSET lines before or after the "current
|
line". For the `list' command, the current line is the last one
|
line". For the `list' command, the current line is the last one
|
printed; for the breakpoint commands, this is the line at which
|
printed; for the breakpoint commands, this is the line at which
|
execution stopped in the currently selected "stack frame" (*note
|
execution stopped in the currently selected "stack frame" (*note
|
Frames: Frames, for a description of stack frames.) When used as
|
Frames: Frames, for a description of stack frames.) When used as
|
the second of the two linespecs in a `list' command, this
|
the second of the two linespecs in a `list' command, this
|
specifies the line OFFSET lines up or down from the first linespec.
|
specifies the line OFFSET lines up or down from the first linespec.
|
|
|
`FILENAME:LINENUM'
|
`FILENAME:LINENUM'
|
Specifies the line LINENUM in the source file FILENAME.
|
Specifies the line LINENUM in the source file FILENAME.
|
|
|
`FUNCTION'
|
`FUNCTION'
|
Specifies the line that begins the body of the function FUNCTION.
|
Specifies the line that begins the body of the function FUNCTION.
|
For example, in C, this is the line with the open brace.
|
For example, in C, this is the line with the open brace.
|
|
|
`FILENAME:FUNCTION'
|
`FILENAME:FUNCTION'
|
Specifies the line that begins the body of the function FUNCTION
|
Specifies the line that begins the body of the function FUNCTION
|
in the file FILENAME. You only need the file name with a function
|
in the file FILENAME. You only need the file name with a function
|
name to avoid ambiguity when there are identically named functions
|
name to avoid ambiguity when there are identically named functions
|
in different source files.
|
in different source files.
|
|
|
`*ADDRESS'
|
`*ADDRESS'
|
Specifies the program address ADDRESS. For line-oriented
|
Specifies the program address ADDRESS. For line-oriented
|
commands, such as `list' and `edit', this specifies a source line
|
commands, such as `list' and `edit', this specifies a source line
|
that contains ADDRESS. For `break' and other breakpoint oriented
|
that contains ADDRESS. For `break' and other breakpoint oriented
|
commands, this can be used to set breakpoints in parts of your
|
commands, this can be used to set breakpoints in parts of your
|
program which do not have debugging information or source files.
|
program which do not have debugging information or source files.
|
|
|
Here ADDRESS may be any expression valid in the current working
|
Here ADDRESS may be any expression valid in the current working
|
language (*note working language: Languages.) that specifies a code
|
language (*note working language: Languages.) that specifies a code
|
address. In addition, as a convenience, GDB extends the semantics
|
address. In addition, as a convenience, GDB extends the semantics
|
of expressions used in locations to cover the situations that
|
of expressions used in locations to cover the situations that
|
frequently happen during debugging. Here are the various forms of
|
frequently happen during debugging. Here are the various forms of
|
ADDRESS:
|
ADDRESS:
|
|
|
`EXPRESSION'
|
`EXPRESSION'
|
Any expression valid in the current working language.
|
Any expression valid in the current working language.
|
|
|
`FUNCADDR'
|
`FUNCADDR'
|
An address of a function or procedure derived from its name.
|
An address of a function or procedure derived from its name.
|
In C, C++, Java, Objective-C, Fortran, minimal, and assembly,
|
In C, C++, Java, Objective-C, Fortran, minimal, and assembly,
|
this is simply the function's name FUNCTION (and actually a
|
this is simply the function's name FUNCTION (and actually a
|
special case of a valid expression). In Pascal and Modula-2,
|
special case of a valid expression). In Pascal and Modula-2,
|
this is `&FUNCTION'. In Ada, this is `FUNCTION'Address'
|
this is `&FUNCTION'. In Ada, this is `FUNCTION'Address'
|
(although the Pascal form also works).
|
(although the Pascal form also works).
|
|
|
This form specifies the address of the function's first
|
This form specifies the address of the function's first
|
instruction, before the stack frame and arguments have been
|
instruction, before the stack frame and arguments have been
|
set up.
|
set up.
|
|
|
`'FILENAME'::FUNCADDR'
|
`'FILENAME'::FUNCADDR'
|
Like FUNCADDR above, but also specifies the name of the source
|
Like FUNCADDR above, but also specifies the name of the source
|
file explicitly. This is useful if the name of the function
|
file explicitly. This is useful if the name of the function
|
does not specify the function unambiguously, e.g., if there
|
does not specify the function unambiguously, e.g., if there
|
are several functions with identical names in different
|
are several functions with identical names in different
|
source files.
|
source files.
|
|
|
|
|
|
|
File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source
|
File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source
|
|
|
9.3 Editing Source Files
|
9.3 Editing Source Files
|
========================
|
========================
|
|
|
To edit the lines in a source file, use the `edit' command. The
|
To edit the lines in a source file, use the `edit' command. The
|
editing program of your choice is invoked with the current line set to
|
editing program of your choice is invoked with the current line set to
|
the active line in the program. Alternatively, there are several ways
|
the active line in the program. Alternatively, there are several ways
|
to specify what part of the file you want to print if you want to see
|
to specify what part of the file you want to print if you want to see
|
other parts of the program:
|
other parts of the program:
|
|
|
`edit LOCATION'
|
`edit LOCATION'
|
Edit the source file specified by `location'. Editing starts at
|
Edit the source file specified by `location'. Editing starts at
|
that LOCATION, e.g., at the specified source line of the specified
|
that LOCATION, e.g., at the specified source line of the specified
|
file. *Note Specify Location::, for all the possible forms of the
|
file. *Note Specify Location::, for all the possible forms of the
|
LOCATION argument; here are the forms of the `edit' command most
|
LOCATION argument; here are the forms of the `edit' command most
|
commonly used:
|
commonly used:
|
|
|
`edit NUMBER'
|
`edit NUMBER'
|
Edit the current source file with NUMBER as the active line
|
Edit the current source file with NUMBER as the active line
|
number.
|
number.
|
|
|
`edit FUNCTION'
|
`edit FUNCTION'
|
Edit the file containing FUNCTION at the beginning of its
|
Edit the file containing FUNCTION at the beginning of its
|
definition.
|
definition.
|
|
|
|
|
9.3.1 Choosing your Editor
|
9.3.1 Choosing your Editor
|
--------------------------
|
--------------------------
|
|
|
You can customize GDB to use any editor you want (1). By default, it
|
You can customize GDB to use any editor you want (1). By default, it
|
is `/bin/ex', but you can change this by setting the environment
|
is `/bin/ex', but you can change this by setting the environment
|
variable `EDITOR' before using GDB. For example, to configure GDB to
|
variable `EDITOR' before using GDB. For example, to configure GDB to
|
use the `vi' editor, you could use these commands with the `sh' shell:
|
use the `vi' editor, you could use these commands with the `sh' shell:
|
EDITOR=/usr/bin/vi
|
EDITOR=/usr/bin/vi
|
export EDITOR
|
export EDITOR
|
gdb ...
|
gdb ...
|
or in the `csh' shell,
|
or in the `csh' shell,
|
setenv EDITOR /usr/bin/vi
|
setenv EDITOR /usr/bin/vi
|
gdb ...
|
gdb ...
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) The only restriction is that your editor (say `ex'), recognizes
|
(1) The only restriction is that your editor (say `ex'), recognizes
|
the following command-line syntax:
|
the following command-line syntax:
|
ex +NUMBER file
|
ex +NUMBER file
|
The optional numeric value +NUMBER specifies the number of the line
|
The optional numeric value +NUMBER specifies the number of the line
|
in the file where to start editing.
|
in the file where to start editing.
|
|
|
|
|
File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source
|
File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source
|
|
|
9.4 Searching Source Files
|
9.4 Searching Source Files
|
==========================
|
==========================
|
|
|
There are two commands for searching through the current source file
|
There are two commands for searching through the current source file
|
for a regular expression.
|
for a regular expression.
|
|
|
`forward-search REGEXP'
|
`forward-search REGEXP'
|
`search REGEXP'
|
`search REGEXP'
|
The command `forward-search REGEXP' checks each line, starting
|
The command `forward-search REGEXP' checks each line, starting
|
with the one following the last line listed, for a match for
|
with the one following the last line listed, for a match for
|
REGEXP. It lists the line that is found. You can use the synonym
|
REGEXP. It lists the line that is found. You can use the synonym
|
`search REGEXP' or abbreviate the command name as `fo'.
|
`search REGEXP' or abbreviate the command name as `fo'.
|
|
|
`reverse-search REGEXP'
|
`reverse-search REGEXP'
|
The command `reverse-search REGEXP' checks each line, starting
|
The command `reverse-search REGEXP' checks each line, starting
|
with the one before the last line listed and going backward, for a
|
with the one before the last line listed and going backward, for a
|
match for REGEXP. It lists the line that is found. You can
|
match for REGEXP. It lists the line that is found. You can
|
abbreviate this command as `rev'.
|
abbreviate this command as `rev'.
|
|
|
|
|
File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source
|
File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source
|
|
|
9.5 Specifying Source Directories
|
9.5 Specifying Source Directories
|
=================================
|
=================================
|
|
|
Executable programs sometimes do not record the directories of the
|
Executable programs sometimes do not record the directories of the
|
source files from which they were compiled, just the names. Even when
|
source files from which they were compiled, just the names. Even when
|
they do, the directories could be moved between the compilation and
|
they do, the directories could be moved between the compilation and
|
your debugging session. GDB has a list of directories to search for
|
your debugging session. GDB has a list of directories to search for
|
source files; this is called the "source path". Each time GDB wants a
|
source files; this is called the "source path". Each time GDB wants a
|
source file, it tries all the directories in the list, in the order
|
source file, it tries all the directories in the list, in the order
|
they are present in the list, until it finds a file with the desired
|
they are present in the list, until it finds a file with the desired
|
name.
|
name.
|
|
|
For example, suppose an executable references the file
|
For example, suppose an executable references the file
|
`/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The
|
`/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The
|
file is first looked up literally; if this fails,
|
file is first looked up literally; if this fails,
|
`/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails,
|
`/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails,
|
`/mnt/cross/foo.c' is opened; if this fails, an error message is
|
`/mnt/cross/foo.c' is opened; if this fails, an error message is
|
printed. GDB does not look up the parts of the source file name, such
|
printed. GDB does not look up the parts of the source file name, such
|
as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of
|
as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of
|
the source path are not searched: if the source path is `/mnt/cross',
|
the source path are not searched: if the source path is `/mnt/cross',
|
and the binary refers to `foo.c', GDB would not find it under
|
and the binary refers to `foo.c', GDB would not find it under
|
`/mnt/cross/usr/src/foo-1.0/lib'.
|
`/mnt/cross/usr/src/foo-1.0/lib'.
|
|
|
Plain file names, relative file names with leading directories, file
|
Plain file names, relative file names with leading directories, file
|
names containing dots, etc. are all treated as described above; for
|
names containing dots, etc. are all treated as described above; for
|
instance, if the source path is `/mnt/cross', and the source file is
|
instance, if the source path is `/mnt/cross', and the source file is
|
recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then
|
recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then
|
`/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'.
|
`/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'.
|
|
|
Note that the executable search path is _not_ used to locate the
|
Note that the executable search path is _not_ used to locate the
|
source files.
|
source files.
|
|
|
Whenever you reset or rearrange the source path, GDB clears out any
|
Whenever you reset or rearrange the source path, GDB clears out any
|
information it has cached about where source files are found and where
|
information it has cached about where source files are found and where
|
each line is in the file.
|
each line is in the file.
|
|
|
When you start GDB, its source path includes only `cdir' and `cwd',
|
When you start GDB, its source path includes only `cdir' and `cwd',
|
in that order. To add other directories, use the `directory' command.
|
in that order. To add other directories, use the `directory' command.
|
|
|
The search path is used to find both program source files and GDB
|
The search path is used to find both program source files and GDB
|
script files (read using the `-command' option and `source' command).
|
script files (read using the `-command' option and `source' command).
|
|
|
In addition to the source path, GDB provides a set of commands that
|
In addition to the source path, GDB provides a set of commands that
|
manage a list of source path substitution rules. A "substitution rule"
|
manage a list of source path substitution rules. A "substitution rule"
|
specifies how to rewrite source directories stored in the program's
|
specifies how to rewrite source directories stored in the program's
|
debug information in case the sources were moved to a different
|
debug information in case the sources were moved to a different
|
directory between compilation and debugging. A rule is made of two
|
directory between compilation and debugging. A rule is made of two
|
strings, the first specifying what needs to be rewritten in the path,
|
strings, the first specifying what needs to be rewritten in the path,
|
and the second specifying how it should be rewritten. In *note set
|
and the second specifying how it should be rewritten. In *note set
|
substitute-path::, we name these two parts FROM and TO respectively.
|
substitute-path::, we name these two parts FROM and TO respectively.
|
GDB does a simple string replacement of FROM with TO at the start of
|
GDB does a simple string replacement of FROM with TO at the start of
|
the directory part of the source file name, and uses that result
|
the directory part of the source file name, and uses that result
|
instead of the original file name to look up the sources.
|
instead of the original file name to look up the sources.
|
|
|
Using the previous example, suppose the `foo-1.0' tree has been
|
Using the previous example, suppose the `foo-1.0' tree has been
|
moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace
|
moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace
|
`/usr/src' in all source path names with `/mnt/cross'. The first
|
`/usr/src' in all source path names with `/mnt/cross'. The first
|
lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the
|
lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the
|
original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source
|
original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source
|
path substitution rule, use the `set substitute-path' command (*note
|
path substitution rule, use the `set substitute-path' command (*note
|
set substitute-path::).
|
set substitute-path::).
|
|
|
To avoid unexpected substitution results, a rule is applied only if
|
To avoid unexpected substitution results, a rule is applied only if
|
the FROM part of the directory name ends at a directory separator. For
|
the FROM part of the directory name ends at a directory separator. For
|
instance, a rule substituting `/usr/source' into `/mnt/cross' will be
|
instance, a rule substituting `/usr/source' into `/mnt/cross' will be
|
applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'.
|
applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'.
|
And because the substitution is applied only at the beginning of the
|
And because the substitution is applied only at the beginning of the
|
directory name, this rule will not be applied to
|
directory name, this rule will not be applied to
|
`/root/usr/source/baz.c' either.
|
`/root/usr/source/baz.c' either.
|
|
|
In many cases, you can achieve the same result using the `directory'
|
In many cases, you can achieve the same result using the `directory'
|
command. However, `set substitute-path' can be more efficient in the
|
command. However, `set substitute-path' can be more efficient in the
|
case where the sources are organized in a complex tree with multiple
|
case where the sources are organized in a complex tree with multiple
|
subdirectories. With the `directory' command, you need to add each
|
subdirectories. With the `directory' command, you need to add each
|
subdirectory of your project. If you moved the entire tree while
|
subdirectory of your project. If you moved the entire tree while
|
preserving its internal organization, then `set substitute-path' allows
|
preserving its internal organization, then `set substitute-path' allows
|
you to direct the debugger to all the sources with one single command.
|
you to direct the debugger to all the sources with one single command.
|
|
|
`set substitute-path' is also more than just a shortcut command.
|
`set substitute-path' is also more than just a shortcut command.
|
The source path is only used if the file at the original location no
|
The source path is only used if the file at the original location no
|
longer exists. On the other hand, `set substitute-path' modifies the
|
longer exists. On the other hand, `set substitute-path' modifies the
|
debugger behavior to look at the rewritten location instead. So, if
|
debugger behavior to look at the rewritten location instead. So, if
|
for any reason a source file that is not relevant to your executable is
|
for any reason a source file that is not relevant to your executable is
|
located at the original location, a substitution rule is the only
|
located at the original location, a substitution rule is the only
|
method available to point GDB at the new location.
|
method available to point GDB at the new location.
|
|
|
You can configure a default source path substitution rule by
|
You can configure a default source path substitution rule by
|
configuring GDB with the `--with-relocated-sources=DIR' option. The DIR
|
configuring GDB with the `--with-relocated-sources=DIR' option. The DIR
|
should be the name of a directory under GDB's configured prefix (set
|
should be the name of a directory under GDB's configured prefix (set
|
with `--prefix' or `--exec-prefix'), and directory names in debug
|
with `--prefix' or `--exec-prefix'), and directory names in debug
|
information under DIR will be adjusted automatically if the installed
|
information under DIR will be adjusted automatically if the installed
|
GDB is moved to a new location. This is useful if GDB, libraries or
|
GDB is moved to a new location. This is useful if GDB, libraries or
|
executables with debug information and corresponding source code are
|
executables with debug information and corresponding source code are
|
being moved together.
|
being moved together.
|
|
|
`directory DIRNAME ...'
|
`directory DIRNAME ...'
|
|
|
`dir DIRNAME ...'
|
`dir DIRNAME ...'
|
Add directory DIRNAME to the front of the source path. Several
|
Add directory DIRNAME to the front of the source path. Several
|
directory names may be given to this command, separated by `:'
|
directory names may be given to this command, separated by `:'
|
(`;' on MS-DOS and MS-Windows, where `:' usually appears as part
|
(`;' on MS-DOS and MS-Windows, where `:' usually appears as part
|
of absolute file names) or whitespace. You may specify a
|
of absolute file names) or whitespace. You may specify a
|
directory that is already in the source path; this moves it
|
directory that is already in the source path; this moves it
|
forward, so GDB searches it sooner.
|
forward, so GDB searches it sooner.
|
|
|
You can use the string `$cdir' to refer to the compilation
|
You can use the string `$cdir' to refer to the compilation
|
directory (if one is recorded), and `$cwd' to refer to the current
|
directory (if one is recorded), and `$cwd' to refer to the current
|
working directory. `$cwd' is not the same as `.'--the former
|
working directory. `$cwd' is not the same as `.'--the former
|
tracks the current working directory as it changes during your GDB
|
tracks the current working directory as it changes during your GDB
|
session, while the latter is immediately expanded to the current
|
session, while the latter is immediately expanded to the current
|
directory at the time you add an entry to the source path.
|
directory at the time you add an entry to the source path.
|
|
|
`directory'
|
`directory'
|
Reset the source path to its default value (`$cdir:$cwd' on Unix
|
Reset the source path to its default value (`$cdir:$cwd' on Unix
|
systems). This requires confirmation.
|
systems). This requires confirmation.
|
|
|
`show directories'
|
`show directories'
|
Print the source path: show which directories it contains.
|
Print the source path: show which directories it contains.
|
|
|
`set substitute-path FROM TO'
|
`set substitute-path FROM TO'
|
Define a source path substitution rule, and add it at the end of
|
Define a source path substitution rule, and add it at the end of
|
the current list of existing substitution rules. If a rule with
|
the current list of existing substitution rules. If a rule with
|
the same FROM was already defined, then the old rule is also
|
the same FROM was already defined, then the old rule is also
|
deleted.
|
deleted.
|
|
|
For example, if the file `/foo/bar/baz.c' was moved to
|
For example, if the file `/foo/bar/baz.c' was moved to
|
`/mnt/cross/baz.c', then the command
|
`/mnt/cross/baz.c', then the command
|
|
|
(gdb) set substitute-path /usr/src /mnt/cross
|
(gdb) set substitute-path /usr/src /mnt/cross
|
|
|
will tell GDB to replace `/usr/src' with `/mnt/cross', which will
|
will tell GDB to replace `/usr/src' with `/mnt/cross', which will
|
allow GDB to find the file `baz.c' even though it was moved.
|
allow GDB to find the file `baz.c' even though it was moved.
|
|
|
In the case when more than one substitution rule have been defined,
|
In the case when more than one substitution rule have been defined,
|
the rules are evaluated one by one in the order where they have
|
the rules are evaluated one by one in the order where they have
|
been defined. The first one matching, if any, is selected to
|
been defined. The first one matching, if any, is selected to
|
perform the substitution.
|
perform the substitution.
|
|
|
For instance, if we had entered the following commands:
|
For instance, if we had entered the following commands:
|
|
|
(gdb) set substitute-path /usr/src/include /mnt/include
|
(gdb) set substitute-path /usr/src/include /mnt/include
|
(gdb) set substitute-path /usr/src /mnt/src
|
(gdb) set substitute-path /usr/src /mnt/src
|
|
|
GDB would then rewrite `/usr/src/include/defs.h' into
|
GDB would then rewrite `/usr/src/include/defs.h' into
|
`/mnt/include/defs.h' by using the first rule. However, it would
|
`/mnt/include/defs.h' by using the first rule. However, it would
|
use the second rule to rewrite `/usr/src/lib/foo.c' into
|
use the second rule to rewrite `/usr/src/lib/foo.c' into
|
`/mnt/src/lib/foo.c'.
|
`/mnt/src/lib/foo.c'.
|
|
|
`unset substitute-path [path]'
|
`unset substitute-path [path]'
|
If a path is specified, search the current list of substitution
|
If a path is specified, search the current list of substitution
|
rules for a rule that would rewrite that path. Delete that rule
|
rules for a rule that would rewrite that path. Delete that rule
|
if found. A warning is emitted by the debugger if no rule could
|
if found. A warning is emitted by the debugger if no rule could
|
be found.
|
be found.
|
|
|
If no path is specified, then all substitution rules are deleted.
|
If no path is specified, then all substitution rules are deleted.
|
|
|
`show substitute-path [path]'
|
`show substitute-path [path]'
|
If a path is specified, then print the source path substitution
|
If a path is specified, then print the source path substitution
|
rule which would rewrite that path, if any.
|
rule which would rewrite that path, if any.
|
|
|
If no path is specified, then print all existing source path
|
If no path is specified, then print all existing source path
|
substitution rules.
|
substitution rules.
|
|
|
|
|
If your source path is cluttered with directories that are no longer
|
If your source path is cluttered with directories that are no longer
|
of interest, GDB may sometimes cause confusion by finding the wrong
|
of interest, GDB may sometimes cause confusion by finding the wrong
|
versions of source. You can correct the situation as follows:
|
versions of source. You can correct the situation as follows:
|
|
|
1. Use `directory' with no argument to reset the source path to its
|
1. Use `directory' with no argument to reset the source path to its
|
default value.
|
default value.
|
|
|
2. Use `directory' with suitable arguments to reinstall the
|
2. Use `directory' with suitable arguments to reinstall the
|
directories you want in the source path. You can add all the
|
directories you want in the source path. You can add all the
|
directories in one command.
|
directories in one command.
|
|
|
|
|
File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source
|
File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source
|
|
|
9.6 Source and Machine Code
|
9.6 Source and Machine Code
|
===========================
|
===========================
|
|
|
You can use the command `info line' to map source lines to program
|
You can use the command `info line' to map source lines to program
|
addresses (and vice versa), and the command `disassemble' to display a
|
addresses (and vice versa), and the command `disassemble' to display a
|
range of addresses as machine instructions. You can use the command
|
range of addresses as machine instructions. You can use the command
|
`set disassemble-next-line' to set whether to disassemble next source
|
`set disassemble-next-line' to set whether to disassemble next source
|
line when execution stops. When run under GNU Emacs mode, the `info
|
line when execution stops. When run under GNU Emacs mode, the `info
|
line' command causes the arrow to point to the line specified. Also,
|
line' command causes the arrow to point to the line specified. Also,
|
`info line' prints addresses in symbolic form as well as hex.
|
`info line' prints addresses in symbolic form as well as hex.
|
|
|
`info line LINESPEC'
|
`info line LINESPEC'
|
Print the starting and ending addresses of the compiled code for
|
Print the starting and ending addresses of the compiled code for
|
source line LINESPEC. You can specify source lines in any of the
|
source line LINESPEC. You can specify source lines in any of the
|
ways documented in *note Specify Location::.
|
ways documented in *note Specify Location::.
|
|
|
For example, we can use `info line' to discover the location of the
|
For example, we can use `info line' to discover the location of the
|
object code for the first line of function `m4_changequote':
|
object code for the first line of function `m4_changequote':
|
|
|
(gdb) info line m4_changequote
|
(gdb) info line m4_changequote
|
Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
|
Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
|
|
|
We can also inquire (using `*ADDR' as the form for LINESPEC) what
|
We can also inquire (using `*ADDR' as the form for LINESPEC) what
|
source line covers a particular address:
|
source line covers a particular address:
|
(gdb) info line *0x63ff
|
(gdb) info line *0x63ff
|
Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
|
Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
|
|
|
After `info line', the default address for the `x' command is
|
After `info line', the default address for the `x' command is
|
changed to the starting address of the line, so that `x/i' is
|
changed to the starting address of the line, so that `x/i' is
|
sufficient to begin examining the machine code (*note Examining Memory:
|
sufficient to begin examining the machine code (*note Examining Memory:
|
Memory.). Also, this address is saved as the value of the convenience
|
Memory.). Also, this address is saved as the value of the convenience
|
variable `$_' (*note Convenience Variables: Convenience Vars.).
|
variable `$_' (*note Convenience Variables: Convenience Vars.).
|
|
|
`disassemble'
|
`disassemble'
|
`disassemble /m'
|
`disassemble /m'
|
`disassemble /r'
|
`disassemble /r'
|
This specialized command dumps a range of memory as machine
|
This specialized command dumps a range of memory as machine
|
instructions. It can also print mixed source+disassembly by
|
instructions. It can also print mixed source+disassembly by
|
specifying the `/m' modifier and print the raw instructions in hex
|
specifying the `/m' modifier and print the raw instructions in hex
|
as well as in symbolic form by specifying the `/r'. The default
|
as well as in symbolic form by specifying the `/r'. The default
|
memory range is the function surrounding the program counter of
|
memory range is the function surrounding the program counter of
|
the selected frame. A single argument to this command is a
|
the selected frame. A single argument to this command is a
|
program counter value; GDB dumps the function surrounding this
|
program counter value; GDB dumps the function surrounding this
|
value. When two arguments are given, they should be separated by
|
value. When two arguments are given, they should be separated by
|
a comma, possibly surrounded by whitespace. The arguments specify
|
a comma, possibly surrounded by whitespace. The arguments specify
|
a range of addresses to dump, in one of two forms:
|
a range of addresses to dump, in one of two forms:
|
|
|
`START,END'
|
`START,END'
|
the addresses from START (inclusive) to END (exclusive)
|
the addresses from START (inclusive) to END (exclusive)
|
|
|
`START,+LENGTH'
|
`START,+LENGTH'
|
the addresses from START (inclusive) to `START+LENGTH'
|
the addresses from START (inclusive) to `START+LENGTH'
|
(exclusive).
|
(exclusive).
|
|
|
When 2 arguments are specified, the name of the function is also
|
When 2 arguments are specified, the name of the function is also
|
printed (since there could be several functions in the given
|
printed (since there could be several functions in the given
|
range).
|
range).
|
|
|
The argument(s) can be any expression yielding a numeric value,
|
The argument(s) can be any expression yielding a numeric value,
|
such as `0x32c4', `&main+10' or `$pc - 8'.
|
such as `0x32c4', `&main+10' or `$pc - 8'.
|
|
|
If the range of memory being disassembled contains current program
|
If the range of memory being disassembled contains current program
|
counter, the instruction at that location is shown with a `=>'
|
counter, the instruction at that location is shown with a `=>'
|
marker.
|
marker.
|
|
|
The following example shows the disassembly of a range of addresses
|
The following example shows the disassembly of a range of addresses
|
of HP PA-RISC 2.0 code:
|
of HP PA-RISC 2.0 code:
|
|
|
(gdb) disas 0x32c4, 0x32e4
|
(gdb) disas 0x32c4, 0x32e4
|
Dump of assembler code from 0x32c4 to 0x32e4:
|
Dump of assembler code from 0x32c4 to 0x32e4:
|
0x32c4 : addil 0,dp
|
0x32c4 : addil 0,dp
|
0x32c8 : ldw 0x22c(sr0,r1),r26
|
0x32c8 : ldw 0x22c(sr0,r1),r26
|
0x32cc : ldil 0x3000,r31
|
0x32cc : ldil 0x3000,r31
|
0x32d0 : ble 0x3f8(sr4,r31)
|
0x32d0 : ble 0x3f8(sr4,r31)
|
0x32d4 : ldo 0(r31),rp
|
0x32d4 : ldo 0(r31),rp
|
0x32d8 : addil -0x800,dp
|
0x32d8 : addil -0x800,dp
|
0x32dc : ldo 0x588(r1),r26
|
0x32dc : ldo 0x588(r1),r26
|
0x32e0 : ldil 0x3000,r31
|
0x32e0 : ldil 0x3000,r31
|
End of assembler dump.
|
End of assembler dump.
|
|
|
Here is an example showing mixed source+assembly for Intel x86, when
|
Here is an example showing mixed source+assembly for Intel x86, when
|
the program is stopped just after function prologue:
|
the program is stopped just after function prologue:
|
|
|
(gdb) disas /m main
|
(gdb) disas /m main
|
Dump of assembler code for function main:
|
Dump of assembler code for function main:
|
5 {
|
5 {
|
0x08048330 <+0>: push %ebp
|
0x08048330 <+0>: push %ebp
|
0x08048331 <+1>: mov %esp,%ebp
|
0x08048331 <+1>: mov %esp,%ebp
|
0x08048333 <+3>: sub $0x8,%esp
|
0x08048333 <+3>: sub $0x8,%esp
|
0x08048336 <+6>: and $0xfffffff0,%esp
|
0x08048336 <+6>: and $0xfffffff0,%esp
|
0x08048339 <+9>: sub $0x10,%esp
|
0x08048339 <+9>: sub $0x10,%esp
|
|
|
6 printf ("Hello.\n");
|
6 printf ("Hello.\n");
|
=> 0x0804833c <+12>: movl $0x8048440,(%esp)
|
=> 0x0804833c <+12>: movl $0x8048440,(%esp)
|
0x08048343 <+19>: call 0x8048284
|
0x08048343 <+19>: call 0x8048284
|
|
|
7 return 0;
|
7 return 0;
|
8 }
|
8 }
|
0x08048348 <+24>: mov $0x0,%eax
|
0x08048348 <+24>: mov $0x0,%eax
|
0x0804834d <+29>: leave
|
0x0804834d <+29>: leave
|
0x0804834e <+30>: ret
|
0x0804834e <+30>: ret
|
|
|
End of assembler dump.
|
End of assembler dump.
|
|
|
Here is another example showing raw instructions in hex for AMD
|
Here is another example showing raw instructions in hex for AMD
|
x86-64,
|
x86-64,
|
|
|
(gdb) disas /r 0x400281,+10
|
(gdb) disas /r 0x400281,+10
|
Dump of assembler code from 0x400281 to 0x40028b:
|
Dump of assembler code from 0x400281 to 0x40028b:
|
0x0000000000400281: 38 36 cmp %dh,(%rsi)
|
0x0000000000400281: 38 36 cmp %dh,(%rsi)
|
0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
|
0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
|
0x0000000000400288: 6f outsl %ds:(%rsi),(%dx)
|
0x0000000000400288: 6f outsl %ds:(%rsi),(%dx)
|
0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al
|
0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al
|
End of assembler dump.
|
End of assembler dump.
|
|
|
Some architectures have more than one commonly-used set of
|
Some architectures have more than one commonly-used set of
|
instruction mnemonics or other syntax.
|
instruction mnemonics or other syntax.
|
|
|
For programs that were dynamically linked and use shared libraries,
|
For programs that were dynamically linked and use shared libraries,
|
instructions that call functions or branch to locations in the shared
|
instructions that call functions or branch to locations in the shared
|
libraries might show a seemingly bogus location--it's actually a
|
libraries might show a seemingly bogus location--it's actually a
|
location of the relocation table. On some architectures, GDB might be
|
location of the relocation table. On some architectures, GDB might be
|
able to resolve these to actual function names.
|
able to resolve these to actual function names.
|
|
|
`set disassembly-flavor INSTRUCTION-SET'
|
`set disassembly-flavor INSTRUCTION-SET'
|
Select the instruction set to use when disassembling the program
|
Select the instruction set to use when disassembling the program
|
via the `disassemble' or `x/i' commands.
|
via the `disassemble' or `x/i' commands.
|
|
|
Currently this command is only defined for the Intel x86 family.
|
Currently this command is only defined for the Intel x86 family.
|
You can set INSTRUCTION-SET to either `intel' or `att'. The
|
You can set INSTRUCTION-SET to either `intel' or `att'. The
|
default is `att', the AT&T flavor used by default by Unix
|
default is `att', the AT&T flavor used by default by Unix
|
assemblers for x86-based targets.
|
assemblers for x86-based targets.
|
|
|
`show disassembly-flavor'
|
`show disassembly-flavor'
|
Show the current setting of the disassembly flavor.
|
Show the current setting of the disassembly flavor.
|
|
|
`set disassemble-next-line'
|
`set disassemble-next-line'
|
`show disassemble-next-line'
|
`show disassemble-next-line'
|
Control whether or not GDB will disassemble the next source line
|
Control whether or not GDB will disassemble the next source line
|
or instruction when execution stops. If ON, GDB will display
|
or instruction when execution stops. If ON, GDB will display
|
disassembly of the next source line when execution of the program
|
disassembly of the next source line when execution of the program
|
being debugged stops. This is _in addition_ to displaying the
|
being debugged stops. This is _in addition_ to displaying the
|
source line itself, which GDB always does if possible. If the
|
source line itself, which GDB always does if possible. If the
|
next source line cannot be displayed for some reason (e.g., if GDB
|
next source line cannot be displayed for some reason (e.g., if GDB
|
cannot find the source file, or there's no line info in the debug
|
cannot find the source file, or there's no line info in the debug
|
info), GDB will display disassembly of the next _instruction_
|
info), GDB will display disassembly of the next _instruction_
|
instead of showing the next source line. If AUTO, GDB will
|
instead of showing the next source line. If AUTO, GDB will
|
display disassembly of next instruction only if the source line
|
display disassembly of next instruction only if the source line
|
cannot be displayed. This setting causes GDB to display some
|
cannot be displayed. This setting causes GDB to display some
|
feedback when you step through a function with no line info or
|
feedback when you step through a function with no line info or
|
whose source file is unavailable. The default is OFF, which means
|
whose source file is unavailable. The default is OFF, which means
|
never display the disassembly of the next line or instruction.
|
never display the disassembly of the next line or instruction.
|
|
|
|
|
File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top
|
File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top
|
|
|
10 Examining Data
|
10 Examining Data
|
*****************
|
*****************
|
|
|
The usual way to examine data in your program is with the `print'
|
The usual way to examine data in your program is with the `print'
|
command (abbreviated `p'), or its synonym `inspect'. It evaluates and
|
command (abbreviated `p'), or its synonym `inspect'. It evaluates and
|
prints the value of an expression of the language your program is
|
prints the value of an expression of the language your program is
|
written in (*note Using GDB with Different Languages: Languages.). It
|
written in (*note Using GDB with Different Languages: Languages.). It
|
may also print the expression using a Python-based pretty-printer
|
may also print the expression using a Python-based pretty-printer
|
(*note Pretty Printing::).
|
(*note Pretty Printing::).
|
|
|
`print EXPR'
|
`print EXPR'
|
`print /F EXPR'
|
`print /F EXPR'
|
EXPR is an expression (in the source language). By default the
|
EXPR is an expression (in the source language). By default the
|
value of EXPR is printed in a format appropriate to its data type;
|
value of EXPR is printed in a format appropriate to its data type;
|
you can choose a different format by specifying `/F', where F is a
|
you can choose a different format by specifying `/F', where F is a
|
letter specifying the format; see *note Output Formats: Output
|
letter specifying the format; see *note Output Formats: Output
|
Formats.
|
Formats.
|
|
|
`print'
|
`print'
|
`print /F'
|
`print /F'
|
If you omit EXPR, GDB displays the last value again (from the
|
If you omit EXPR, GDB displays the last value again (from the
|
"value history"; *note Value History: Value History.). This
|
"value history"; *note Value History: Value History.). This
|
allows you to conveniently inspect the same value in an
|
allows you to conveniently inspect the same value in an
|
alternative format.
|
alternative format.
|
|
|
A more low-level way of examining data is with the `x' command. It
|
A more low-level way of examining data is with the `x' command. It
|
examines data in memory at a specified address and prints it in a
|
examines data in memory at a specified address and prints it in a
|
specified format. *Note Examining Memory: Memory.
|
specified format. *Note Examining Memory: Memory.
|
|
|
If you are interested in information about types, or about how the
|
If you are interested in information about types, or about how the
|
fields of a struct or a class are declared, use the `ptype EXP' command
|
fields of a struct or a class are declared, use the `ptype EXP' command
|
rather than `print'. *Note Examining the Symbol Table: Symbols.
|
rather than `print'. *Note Examining the Symbol Table: Symbols.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Expressions:: Expressions
|
* Expressions:: Expressions
|
* Ambiguous Expressions:: Ambiguous Expressions
|
* Ambiguous Expressions:: Ambiguous Expressions
|
* Variables:: Program variables
|
* Variables:: Program variables
|
* Arrays:: Artificial arrays
|
* Arrays:: Artificial arrays
|
* Output Formats:: Output formats
|
* Output Formats:: Output formats
|
* Memory:: Examining memory
|
* Memory:: Examining memory
|
* Auto Display:: Automatic display
|
* Auto Display:: Automatic display
|
* Print Settings:: Print settings
|
* Print Settings:: Print settings
|
* Pretty Printing:: Python pretty printing
|
* Pretty Printing:: Python pretty printing
|
* Value History:: Value history
|
* Value History:: Value history
|
* Convenience Vars:: Convenience variables
|
* Convenience Vars:: Convenience variables
|
* Registers:: Registers
|
* Registers:: Registers
|
* Floating Point Hardware:: Floating point hardware
|
* Floating Point Hardware:: Floating point hardware
|
* Vector Unit:: Vector Unit
|
* Vector Unit:: Vector Unit
|
* OS Information:: Auxiliary data provided by operating system
|
* OS Information:: Auxiliary data provided by operating system
|
* Memory Region Attributes:: Memory region attributes
|
* Memory Region Attributes:: Memory region attributes
|
* Dump/Restore Files:: Copy between memory and a file
|
* Dump/Restore Files:: Copy between memory and a file
|
* Core File Generation:: Cause a program dump its core
|
* Core File Generation:: Cause a program dump its core
|
* Character Sets:: Debugging programs that use a different
|
* Character Sets:: Debugging programs that use a different
|
character set than GDB does
|
character set than GDB does
|
* Caching Remote Data:: Data caching for remote targets
|
* Caching Remote Data:: Data caching for remote targets
|
* Searching Memory:: Searching memory for a sequence of bytes
|
* Searching Memory:: Searching memory for a sequence of bytes
|
|
|
|
|
File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data
|
File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data
|
|
|
10.1 Expressions
|
10.1 Expressions
|
================
|
================
|
|
|
`print' and many other GDB commands accept an expression and compute
|
`print' and many other GDB commands accept an expression and compute
|
its value. Any kind of constant, variable or operator defined by the
|
its value. Any kind of constant, variable or operator defined by the
|
programming language you are using is valid in an expression in GDB.
|
programming language you are using is valid in an expression in GDB.
|
This includes conditional expressions, function calls, casts, and
|
This includes conditional expressions, function calls, casts, and
|
string constants. It also includes preprocessor macros, if you
|
string constants. It also includes preprocessor macros, if you
|
compiled your program to include this information; see *note
|
compiled your program to include this information; see *note
|
Compilation::.
|
Compilation::.
|
|
|
GDB supports array constants in expressions input by the user. The
|
GDB supports array constants in expressions input by the user. The
|
syntax is {ELEMENT, ELEMENT...}. For example, you can use the command
|
syntax is {ELEMENT, ELEMENT...}. For example, you can use the command
|
`print {1, 2, 3}' to create an array of three integers. If you pass an
|
`print {1, 2, 3}' to create an array of three integers. If you pass an
|
array to a function or assign it to a program variable, GDB copies the
|
array to a function or assign it to a program variable, GDB copies the
|
array to memory that is `malloc'ed in the target program.
|
array to memory that is `malloc'ed in the target program.
|
|
|
Because C is so widespread, most of the expressions shown in
|
Because C is so widespread, most of the expressions shown in
|
examples in this manual are in C. *Note Using GDB with Different
|
examples in this manual are in C. *Note Using GDB with Different
|
Languages: Languages, for information on how to use expressions in other
|
Languages: Languages, for information on how to use expressions in other
|
languages.
|
languages.
|
|
|
In this section, we discuss operators that you can use in GDB
|
In this section, we discuss operators that you can use in GDB
|
expressions regardless of your programming language.
|
expressions regardless of your programming language.
|
|
|
Casts are supported in all languages, not just in C, because it is so
|
Casts are supported in all languages, not just in C, because it is so
|
useful to cast a number into a pointer in order to examine a structure
|
useful to cast a number into a pointer in order to examine a structure
|
at that address in memory.
|
at that address in memory.
|
|
|
GDB supports these operators, in addition to those common to
|
GDB supports these operators, in addition to those common to
|
programming languages:
|
programming languages:
|
|
|
`@'
|
`@'
|
`@' is a binary operator for treating parts of memory as arrays.
|
`@' is a binary operator for treating parts of memory as arrays.
|
*Note Artificial Arrays: Arrays, for more information.
|
*Note Artificial Arrays: Arrays, for more information.
|
|
|
`::'
|
`::'
|
`::' allows you to specify a variable in terms of the file or
|
`::' allows you to specify a variable in terms of the file or
|
function where it is defined. *Note Program Variables: Variables.
|
function where it is defined. *Note Program Variables: Variables.
|
|
|
`{TYPE} ADDR'
|
`{TYPE} ADDR'
|
Refers to an object of type TYPE stored at address ADDR in memory.
|
Refers to an object of type TYPE stored at address ADDR in memory.
|
ADDR may be any expression whose value is an integer or pointer
|
ADDR may be any expression whose value is an integer or pointer
|
(but parentheses are required around binary operators, just as in
|
(but parentheses are required around binary operators, just as in
|
a cast). This construct is allowed regardless of what kind of
|
a cast). This construct is allowed regardless of what kind of
|
data is normally supposed to reside at ADDR.
|
data is normally supposed to reside at ADDR.
|
|
|
|
|
File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data
|
File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data
|
|
|
10.2 Ambiguous Expressions
|
10.2 Ambiguous Expressions
|
==========================
|
==========================
|
|
|
Expressions can sometimes contain some ambiguous elements. For
|
Expressions can sometimes contain some ambiguous elements. For
|
instance, some programming languages (notably Ada, C++ and Objective-C)
|
instance, some programming languages (notably Ada, C++ and Objective-C)
|
permit a single function name to be defined several times, for
|
permit a single function name to be defined several times, for
|
application in different contexts. This is called "overloading".
|
application in different contexts. This is called "overloading".
|
Another example involving Ada is generics. A "generic package" is
|
Another example involving Ada is generics. A "generic package" is
|
similar to C++ templates and is typically instantiated several times,
|
similar to C++ templates and is typically instantiated several times,
|
resulting in the same function name being defined in different contexts.
|
resulting in the same function name being defined in different contexts.
|
|
|
In some cases and depending on the language, it is possible to adjust
|
In some cases and depending on the language, it is possible to adjust
|
the expression to remove the ambiguity. For instance in C++, you can
|
the expression to remove the ambiguity. For instance in C++, you can
|
specify the signature of the function you want to break on, as in
|
specify the signature of the function you want to break on, as in
|
`break FUNCTION(TYPES)'. In Ada, using the fully qualified name of
|
`break FUNCTION(TYPES)'. In Ada, using the fully qualified name of
|
your function often makes the expression unambiguous as well.
|
your function often makes the expression unambiguous as well.
|
|
|
When an ambiguity that needs to be resolved is detected, the debugger
|
When an ambiguity that needs to be resolved is detected, the debugger
|
has the capability to display a menu of numbered choices for each
|
has the capability to display a menu of numbered choices for each
|
possibility, and then waits for the selection with the prompt `>'. The
|
possibility, and then waits for the selection with the prompt `>'. The
|
first option is always `[0] cancel', and typing `0 ' aborts the
|
first option is always `[0] cancel', and typing `0 ' aborts the
|
current command. If the command in which the expression was used
|
current command. If the command in which the expression was used
|
allows more than one choice to be selected, the next option in the menu
|
allows more than one choice to be selected, the next option in the menu
|
is `[1] all', and typing `1 ' selects all possible choices.
|
is `[1] all', and typing `1 ' selects all possible choices.
|
|
|
For example, the following session excerpt shows an attempt to set a
|
For example, the following session excerpt shows an attempt to set a
|
breakpoint at the overloaded symbol `String::after'. We choose three
|
breakpoint at the overloaded symbol `String::after'. We choose three
|
particular definitions of that function name:
|
particular definitions of that function name:
|
|
|
(gdb) b String::after
|
(gdb) b String::after
|
[0] cancel
|
[0] cancel
|
[1] all
|
[1] all
|
[2] file:String.cc; line number:867
|
[2] file:String.cc; line number:867
|
[3] file:String.cc; line number:860
|
[3] file:String.cc; line number:860
|
[4] file:String.cc; line number:875
|
[4] file:String.cc; line number:875
|
[5] file:String.cc; line number:853
|
[5] file:String.cc; line number:853
|
[6] file:String.cc; line number:846
|
[6] file:String.cc; line number:846
|
[7] file:String.cc; line number:735
|
[7] file:String.cc; line number:735
|
> 2 4 6
|
> 2 4 6
|
Breakpoint 1 at 0xb26c: file String.cc, line 867.
|
Breakpoint 1 at 0xb26c: file String.cc, line 867.
|
Breakpoint 2 at 0xb344: file String.cc, line 875.
|
Breakpoint 2 at 0xb344: file String.cc, line 875.
|
Breakpoint 3 at 0xafcc: file String.cc, line 846.
|
Breakpoint 3 at 0xafcc: file String.cc, line 846.
|
Multiple breakpoints were set.
|
Multiple breakpoints were set.
|
Use the "delete" command to delete unwanted
|
Use the "delete" command to delete unwanted
|
breakpoints.
|
breakpoints.
|
(gdb)
|
(gdb)
|
|
|
`set multiple-symbols MODE'
|
`set multiple-symbols MODE'
|
This option allows you to adjust the debugger behavior when an
|
This option allows you to adjust the debugger behavior when an
|
expression is ambiguous.
|
expression is ambiguous.
|
|
|
By default, MODE is set to `all'. If the command with which the
|
By default, MODE is set to `all'. If the command with which the
|
expression is used allows more than one choice, then GDB
|
expression is used allows more than one choice, then GDB
|
automatically selects all possible choices. For instance,
|
automatically selects all possible choices. For instance,
|
inserting a breakpoint on a function using an ambiguous name
|
inserting a breakpoint on a function using an ambiguous name
|
results in a breakpoint inserted on each possible match. However,
|
results in a breakpoint inserted on each possible match. However,
|
if a unique choice must be made, then GDB uses the menu to help
|
if a unique choice must be made, then GDB uses the menu to help
|
you disambiguate the expression. For instance, printing the
|
you disambiguate the expression. For instance, printing the
|
address of an overloaded function will result in the use of the
|
address of an overloaded function will result in the use of the
|
menu.
|
menu.
|
|
|
When MODE is set to `ask', the debugger always uses the menu when
|
When MODE is set to `ask', the debugger always uses the menu when
|
an ambiguity is detected.
|
an ambiguity is detected.
|
|
|
Finally, when MODE is set to `cancel', the debugger reports an
|
Finally, when MODE is set to `cancel', the debugger reports an
|
error due to the ambiguity and the command is aborted.
|
error due to the ambiguity and the command is aborted.
|
|
|
`show multiple-symbols'
|
`show multiple-symbols'
|
Show the current value of the `multiple-symbols' setting.
|
Show the current value of the `multiple-symbols' setting.
|
|
|
|
|
File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data
|
File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data
|
|
|
10.3 Program Variables
|
10.3 Program Variables
|
======================
|
======================
|
|
|
The most common kind of expression to use is the name of a variable in
|
The most common kind of expression to use is the name of a variable in
|
your program.
|
your program.
|
|
|
Variables in expressions are understood in the selected stack frame
|
Variables in expressions are understood in the selected stack frame
|
(*note Selecting a Frame: Selection.); they must be either:
|
(*note Selecting a Frame: Selection.); they must be either:
|
|
|
* global (or file-static)
|
* global (or file-static)
|
|
|
or
|
or
|
|
|
* visible according to the scope rules of the programming language
|
* visible according to the scope rules of the programming language
|
from the point of execution in that frame
|
from the point of execution in that frame
|
|
|
This means that in the function
|
This means that in the function
|
|
|
foo (a)
|
foo (a)
|
int a;
|
int a;
|
{
|
{
|
bar (a);
|
bar (a);
|
{
|
{
|
int b = test ();
|
int b = test ();
|
bar (b);
|
bar (b);
|
}
|
}
|
}
|
}
|
|
|
you can examine and use the variable `a' whenever your program is
|
you can examine and use the variable `a' whenever your program is
|
executing within the function `foo', but you can only use or examine
|
executing within the function `foo', but you can only use or examine
|
the variable `b' while your program is executing inside the block where
|
the variable `b' while your program is executing inside the block where
|
`b' is declared.
|
`b' is declared.
|
|
|
There is an exception: you can refer to a variable or function whose
|
There is an exception: you can refer to a variable or function whose
|
scope is a single source file even if the current execution point is not
|
scope is a single source file even if the current execution point is not
|
in this file. But it is possible to have more than one such variable or
|
in this file. But it is possible to have more than one such variable or
|
function with the same name (in different source files). If that
|
function with the same name (in different source files). If that
|
happens, referring to that name has unpredictable effects. If you wish,
|
happens, referring to that name has unpredictable effects. If you wish,
|
you can specify a static variable in a particular function or file,
|
you can specify a static variable in a particular function or file,
|
using the colon-colon (`::') notation:
|
using the colon-colon (`::') notation:
|
|
|
FILE::VARIABLE
|
FILE::VARIABLE
|
FUNCTION::VARIABLE
|
FUNCTION::VARIABLE
|
|
|
Here FILE or FUNCTION is the name of the context for the static
|
Here FILE or FUNCTION is the name of the context for the static
|
VARIABLE. In the case of file names, you can use quotes to make sure
|
VARIABLE. In the case of file names, you can use quotes to make sure
|
GDB parses the file name as a single word--for example, to print a
|
GDB parses the file name as a single word--for example, to print a
|
global value of `x' defined in `f2.c':
|
global value of `x' defined in `f2.c':
|
|
|
(gdb) p 'f2.c'::x
|
(gdb) p 'f2.c'::x
|
|
|
This use of `::' is very rarely in conflict with the very similar
|
This use of `::' is very rarely in conflict with the very similar
|
use of the same notation in C++. GDB also supports use of the C++
|
use of the same notation in C++. GDB also supports use of the C++
|
scope resolution operator in GDB expressions.
|
scope resolution operator in GDB expressions.
|
|
|
_Warning:_ Occasionally, a local variable may appear to have the
|
_Warning:_ Occasionally, a local variable may appear to have the
|
wrong value at certain points in a function--just after entry to a
|
wrong value at certain points in a function--just after entry to a
|
new scope, and just before exit.
|
new scope, and just before exit.
|
You may see this problem when you are stepping by machine
|
You may see this problem when you are stepping by machine
|
instructions. This is because, on most machines, it takes more than
|
instructions. This is because, on most machines, it takes more than
|
one instruction to set up a stack frame (including local variable
|
one instruction to set up a stack frame (including local variable
|
definitions); if you are stepping by machine instructions, variables
|
definitions); if you are stepping by machine instructions, variables
|
may appear to have the wrong values until the stack frame is completely
|
may appear to have the wrong values until the stack frame is completely
|
built. On exit, it usually also takes more than one machine
|
built. On exit, it usually also takes more than one machine
|
instruction to destroy a stack frame; after you begin stepping through
|
instruction to destroy a stack frame; after you begin stepping through
|
that group of instructions, local variable definitions may be gone.
|
that group of instructions, local variable definitions may be gone.
|
|
|
This may also happen when the compiler does significant
|
This may also happen when the compiler does significant
|
optimizations. To be sure of always seeing accurate values, turn off
|
optimizations. To be sure of always seeing accurate values, turn off
|
all optimization when compiling.
|
all optimization when compiling.
|
|
|
Another possible effect of compiler optimizations is to optimize
|
Another possible effect of compiler optimizations is to optimize
|
unused variables out of existence, or assign variables to registers (as
|
unused variables out of existence, or assign variables to registers (as
|
opposed to memory addresses). Depending on the support for such cases
|
opposed to memory addresses). Depending on the support for such cases
|
offered by the debug info format used by the compiler, GDB might not be
|
offered by the debug info format used by the compiler, GDB might not be
|
able to display values for such local variables. If that happens, GDB
|
able to display values for such local variables. If that happens, GDB
|
will print a message like this:
|
will print a message like this:
|
|
|
No symbol "foo" in current context.
|
No symbol "foo" in current context.
|
|
|
To solve such problems, either recompile without optimizations, or
|
To solve such problems, either recompile without optimizations, or
|
use a different debug info format, if the compiler supports several such
|
use a different debug info format, if the compiler supports several such
|
formats. For example, GCC, the GNU C/C++ compiler, usually supports
|
formats. For example, GCC, the GNU C/C++ compiler, usually supports
|
the `-gstabs+' option. `-gstabs+' produces debug info in a format that
|
the `-gstabs+' option. `-gstabs+' produces debug info in a format that
|
is superior to formats such as COFF. You may be able to use DWARF 2
|
is superior to formats such as COFF. You may be able to use DWARF 2
|
(`-gdwarf-2'), which is also an effective form for debug info. *Note
|
(`-gdwarf-2'), which is also an effective form for debug info. *Note
|
Options for Debugging Your Program or GCC: (gcc.info)Debugging Options.
|
Options for Debugging Your Program or GCC: (gcc.info)Debugging Options.
|
*Note C and C++: C, for more information about debug info formats that
|
*Note C and C++: C, for more information about debug info formats that
|
are best suited to C++ programs.
|
are best suited to C++ programs.
|
|
|
If you ask to print an object whose contents are unknown to GDB,
|
If you ask to print an object whose contents are unknown to GDB,
|
e.g., because its data type is not completely specified by the debug
|
e.g., because its data type is not completely specified by the debug
|
information, GDB will say `'. *Note incomplete type:
|
information, GDB will say `'. *Note incomplete type:
|
Symbols, for more about this.
|
Symbols, for more about this.
|
|
|
Strings are identified as arrays of `char' values without specified
|
Strings are identified as arrays of `char' values without specified
|
signedness. Arrays of either `signed char' or `unsigned char' get
|
signedness. Arrays of either `signed char' or `unsigned char' get
|
printed as arrays of 1 byte sized integers. `-fsigned-char' or
|
printed as arrays of 1 byte sized integers. `-fsigned-char' or
|
`-funsigned-char' GCC options have no effect as GDB defines literal
|
`-funsigned-char' GCC options have no effect as GDB defines literal
|
string type `"char"' as `char' without a sign. For program code
|
string type `"char"' as `char' without a sign. For program code
|
|
|
char var0[] = "A";
|
char var0[] = "A";
|
signed char var1[] = "A";
|
signed char var1[] = "A";
|
|
|
You get during debugging
|
You get during debugging
|
(gdb) print var0
|
(gdb) print var0
|
$1 = "A"
|
$1 = "A"
|
(gdb) print var1
|
(gdb) print var1
|
$2 = {65 'A', 0 '\0'}
|
$2 = {65 'A', 0 '\0'}
|
|
|
|
|
File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data
|
File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data
|
|
|
10.4 Artificial Arrays
|
10.4 Artificial Arrays
|
======================
|
======================
|
|
|
It is often useful to print out several successive objects of the same
|
It is often useful to print out several successive objects of the same
|
type in memory; a section of an array, or an array of dynamically
|
type in memory; a section of an array, or an array of dynamically
|
determined size for which only a pointer exists in the program.
|
determined size for which only a pointer exists in the program.
|
|
|
You can do this by referring to a contiguous span of memory as an
|
You can do this by referring to a contiguous span of memory as an
|
"artificial array", using the binary operator `@'. The left operand of
|
"artificial array", using the binary operator `@'. The left operand of
|
`@' should be the first element of the desired array and be an
|
`@' should be the first element of the desired array and be an
|
individual object. The right operand should be the desired length of
|
individual object. The right operand should be the desired length of
|
the array. The result is an array value whose elements are all of the
|
the array. The result is an array value whose elements are all of the
|
type of the left argument. The first element is actually the left
|
type of the left argument. The first element is actually the left
|
argument; the second element comes from bytes of memory immediately
|
argument; the second element comes from bytes of memory immediately
|
following those that hold the first element, and so on. Here is an
|
following those that hold the first element, and so on. Here is an
|
example. If a program says
|
example. If a program says
|
|
|
int *array = (int *) malloc (len * sizeof (int));
|
int *array = (int *) malloc (len * sizeof (int));
|
|
|
you can print the contents of `array' with
|
you can print the contents of `array' with
|
|
|
p *array@len
|
p *array@len
|
|
|
The left operand of `@' must reside in memory. Array values made
|
The left operand of `@' must reside in memory. Array values made
|
with `@' in this way behave just like other arrays in terms of
|
with `@' in this way behave just like other arrays in terms of
|
subscripting, and are coerced to pointers when used in expressions.
|
subscripting, and are coerced to pointers when used in expressions.
|
Artificial arrays most often appear in expressions via the value history
|
Artificial arrays most often appear in expressions via the value history
|
(*note Value History: Value History.), after printing one out.
|
(*note Value History: Value History.), after printing one out.
|
|
|
Another way to create an artificial array is to use a cast. This
|
Another way to create an artificial array is to use a cast. This
|
re-interprets a value as if it were an array. The value need not be in
|
re-interprets a value as if it were an array. The value need not be in
|
memory:
|
memory:
|
(gdb) p/x (short[2])0x12345678
|
(gdb) p/x (short[2])0x12345678
|
$1 = {0x1234, 0x5678}
|
$1 = {0x1234, 0x5678}
|
|
|
As a convenience, if you leave the array length out (as in
|
As a convenience, if you leave the array length out (as in
|
`(TYPE[])VALUE') GDB calculates the size to fill the value (as
|
`(TYPE[])VALUE') GDB calculates the size to fill the value (as
|
`sizeof(VALUE)/sizeof(TYPE)':
|
`sizeof(VALUE)/sizeof(TYPE)':
|
(gdb) p/x (short[])0x12345678
|
(gdb) p/x (short[])0x12345678
|
$2 = {0x1234, 0x5678}
|
$2 = {0x1234, 0x5678}
|
|
|
Sometimes the artificial array mechanism is not quite enough; in
|
Sometimes the artificial array mechanism is not quite enough; in
|
moderately complex data structures, the elements of interest may not
|
moderately complex data structures, the elements of interest may not
|
actually be adjacent--for example, if you are interested in the values
|
actually be adjacent--for example, if you are interested in the values
|
of pointers in an array. One useful work-around in this situation is
|
of pointers in an array. One useful work-around in this situation is
|
to use a convenience variable (*note Convenience Variables: Convenience
|
to use a convenience variable (*note Convenience Variables: Convenience
|
Vars.) as a counter in an expression that prints the first interesting
|
Vars.) as a counter in an expression that prints the first interesting
|
value, and then repeat that expression via . For instance,
|
value, and then repeat that expression via . For instance,
|
suppose you have an array `dtab' of pointers to structures, and you are
|
suppose you have an array `dtab' of pointers to structures, and you are
|
interested in the values of a field `fv' in each structure. Here is an
|
interested in the values of a field `fv' in each structure. Here is an
|
example of what you might type:
|
example of what you might type:
|
|
|
set $i = 0
|
set $i = 0
|
p dtab[$i++]->fv
|
p dtab[$i++]->fv
|
|
|
|
|
...
|
...
|
|
|
|
|
File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data
|
File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data
|
|
|
10.5 Output Formats
|
10.5 Output Formats
|
===================
|
===================
|
|
|
By default, GDB prints a value according to its data type. Sometimes
|
By default, GDB prints a value according to its data type. Sometimes
|
this is not what you want. For example, you might want to print a
|
this is not what you want. For example, you might want to print a
|
number in hex, or a pointer in decimal. Or you might want to view data
|
number in hex, or a pointer in decimal. Or you might want to view data
|
in memory at a certain address as a character string or as an
|
in memory at a certain address as a character string or as an
|
instruction. To do these things, specify an "output format" when you
|
instruction. To do these things, specify an "output format" when you
|
print a value.
|
print a value.
|
|
|
The simplest use of output formats is to say how to print a value
|
The simplest use of output formats is to say how to print a value
|
already computed. This is done by starting the arguments of the
|
already computed. This is done by starting the arguments of the
|
`print' command with a slash and a format letter. The format letters
|
`print' command with a slash and a format letter. The format letters
|
supported are:
|
supported are:
|
|
|
`x'
|
`x'
|
Regard the bits of the value as an integer, and print the integer
|
Regard the bits of the value as an integer, and print the integer
|
in hexadecimal.
|
in hexadecimal.
|
|
|
`d'
|
`d'
|
Print as integer in signed decimal.
|
Print as integer in signed decimal.
|
|
|
`u'
|
`u'
|
Print as integer in unsigned decimal.
|
Print as integer in unsigned decimal.
|
|
|
`o'
|
`o'
|
Print as integer in octal.
|
Print as integer in octal.
|
|
|
`t'
|
`t'
|
Print as integer in binary. The letter `t' stands for "two". (1)
|
Print as integer in binary. The letter `t' stands for "two". (1)
|
|
|
`a'
|
`a'
|
Print as an address, both absolute in hexadecimal and as an offset
|
Print as an address, both absolute in hexadecimal and as an offset
|
from the nearest preceding symbol. You can use this format used
|
from the nearest preceding symbol. You can use this format used
|
to discover where (in what function) an unknown address is located:
|
to discover where (in what function) an unknown address is located:
|
|
|
(gdb) p/a 0x54320
|
(gdb) p/a 0x54320
|
$3 = 0x54320 <_initialize_vx+396>
|
$3 = 0x54320 <_initialize_vx+396>
|
|
|
The command `info symbol 0x54320' yields similar results. *Note
|
The command `info symbol 0x54320' yields similar results. *Note
|
info symbol: Symbols.
|
info symbol: Symbols.
|
|
|
`c'
|
`c'
|
Regard as an integer and print it as a character constant. This
|
Regard as an integer and print it as a character constant. This
|
prints both the numerical value and its character representation.
|
prints both the numerical value and its character representation.
|
The character representation is replaced with the octal escape
|
The character representation is replaced with the octal escape
|
`\nnn' for characters outside the 7-bit ASCII range.
|
`\nnn' for characters outside the 7-bit ASCII range.
|
|
|
Without this format, GDB displays `char', `unsigned char', and
|
Without this format, GDB displays `char', `unsigned char', and
|
`signed char' data as character constants. Single-byte members of
|
`signed char' data as character constants. Single-byte members of
|
vectors are displayed as integer data.
|
vectors are displayed as integer data.
|
|
|
`f'
|
`f'
|
Regard the bits of the value as a floating point number and print
|
Regard the bits of the value as a floating point number and print
|
using typical floating point syntax.
|
using typical floating point syntax.
|
|
|
`s'
|
`s'
|
Regard as a string, if possible. With this format, pointers to
|
Regard as a string, if possible. With this format, pointers to
|
single-byte data are displayed as null-terminated strings and
|
single-byte data are displayed as null-terminated strings and
|
arrays of single-byte data are displayed as fixed-length strings.
|
arrays of single-byte data are displayed as fixed-length strings.
|
Other values are displayed in their natural types.
|
Other values are displayed in their natural types.
|
|
|
Without this format, GDB displays pointers to and arrays of
|
Without this format, GDB displays pointers to and arrays of
|
`char', `unsigned char', and `signed char' as strings.
|
`char', `unsigned char', and `signed char' as strings.
|
Single-byte members of a vector are displayed as an integer array.
|
Single-byte members of a vector are displayed as an integer array.
|
|
|
`r'
|
`r'
|
Print using the `raw' formatting. By default, GDB will use a
|
Print using the `raw' formatting. By default, GDB will use a
|
Python-based pretty-printer, if one is available (*note Pretty
|
Python-based pretty-printer, if one is available (*note Pretty
|
Printing::). This typically results in a higher-level display of
|
Printing::). This typically results in a higher-level display of
|
the value's contents. The `r' format bypasses any Python
|
the value's contents. The `r' format bypasses any Python
|
pretty-printer which might exist.
|
pretty-printer which might exist.
|
|
|
For example, to print the program counter in hex (*note
|
For example, to print the program counter in hex (*note
|
Registers::), type
|
Registers::), type
|
|
|
p/x $pc
|
p/x $pc
|
|
|
Note that no space is required before the slash; this is because command
|
Note that no space is required before the slash; this is because command
|
names in GDB cannot contain a slash.
|
names in GDB cannot contain a slash.
|
|
|
To reprint the last value in the value history with a different
|
To reprint the last value in the value history with a different
|
format, you can use the `print' command with just a format and no
|
format, you can use the `print' command with just a format and no
|
expression. For example, `p/x' reprints the last value in hex.
|
expression. For example, `p/x' reprints the last value in hex.
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) `b' cannot be used because these format letters are also used
|
(1) `b' cannot be used because these format letters are also used
|
with the `x' command, where `b' stands for "byte"; see *note Examining
|
with the `x' command, where `b' stands for "byte"; see *note Examining
|
Memory: Memory.
|
Memory: Memory.
|
|
|
|
|
File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data
|
File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data
|
|
|
10.6 Examining Memory
|
10.6 Examining Memory
|
=====================
|
=====================
|
|
|
You can use the command `x' (for "examine") to examine memory in any of
|
You can use the command `x' (for "examine") to examine memory in any of
|
several formats, independently of your program's data types.
|
several formats, independently of your program's data types.
|
|
|
`x/NFU ADDR'
|
`x/NFU ADDR'
|
`x ADDR'
|
`x ADDR'
|
`x'
|
`x'
|
Use the `x' command to examine memory.
|
Use the `x' command to examine memory.
|
|
|
N, F, and U are all optional parameters that specify how much memory
|
N, F, and U are all optional parameters that specify how much memory
|
to display and how to format it; ADDR is an expression giving the
|
to display and how to format it; ADDR is an expression giving the
|
address where you want to start displaying memory. If you use defaults
|
address where you want to start displaying memory. If you use defaults
|
for NFU, you need not type the slash `/'. Several commands set
|
for NFU, you need not type the slash `/'. Several commands set
|
convenient defaults for ADDR.
|
convenient defaults for ADDR.
|
|
|
N, the repeat count
|
N, the repeat count
|
The repeat count is a decimal integer; the default is 1. It
|
The repeat count is a decimal integer; the default is 1. It
|
specifies how much memory (counting by units U) to display.
|
specifies how much memory (counting by units U) to display.
|
|
|
F, the display format
|
F, the display format
|
The display format is one of the formats used by `print' (`x',
|
The display format is one of the formats used by `print' (`x',
|
`d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for
|
`d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for
|
machine instructions). The default is `x' (hexadecimal)
|
machine instructions). The default is `x' (hexadecimal)
|
initially. The default changes each time you use either `x' or
|
initially. The default changes each time you use either `x' or
|
`print'.
|
`print'.
|
|
|
U, the unit size
|
U, the unit size
|
The unit size is any of
|
The unit size is any of
|
|
|
`b'
|
`b'
|
Bytes.
|
Bytes.
|
|
|
`h'
|
`h'
|
Halfwords (two bytes).
|
Halfwords (two bytes).
|
|
|
`w'
|
`w'
|
Words (four bytes). This is the initial default.
|
Words (four bytes). This is the initial default.
|
|
|
`g'
|
`g'
|
Giant words (eight bytes).
|
Giant words (eight bytes).
|
|
|
Each time you specify a unit size with `x', that size becomes the
|
Each time you specify a unit size with `x', that size becomes the
|
default unit the next time you use `x'. For the `i' format, the
|
default unit the next time you use `x'. For the `i' format, the
|
unit size is ignored and is normally not written. For the `s'
|
unit size is ignored and is normally not written. For the `s'
|
format, the unit size defaults to `b', unless it is explicitly
|
format, the unit size defaults to `b', unless it is explicitly
|
given. Use `x /hs' to display 16-bit char strings and `x /ws' to
|
given. Use `x /hs' to display 16-bit char strings and `x /ws' to
|
display 32-bit strings. The next use of `x /s' will again display
|
display 32-bit strings. The next use of `x /s' will again display
|
8-bit strings. Note that the results depend on the programming
|
8-bit strings. Note that the results depend on the programming
|
language of the current compilation unit. If the language is C,
|
language of the current compilation unit. If the language is C,
|
the `s' modifier will use the UTF-16 encoding while `w' will use
|
the `s' modifier will use the UTF-16 encoding while `w' will use
|
UTF-32. The encoding is set by the programming language and cannot
|
UTF-32. The encoding is set by the programming language and cannot
|
be altered.
|
be altered.
|
|
|
ADDR, starting display address
|
ADDR, starting display address
|
ADDR is the address where you want GDB to begin displaying memory.
|
ADDR is the address where you want GDB to begin displaying memory.
|
The expression need not have a pointer value (though it may); it
|
The expression need not have a pointer value (though it may); it
|
is always interpreted as an integer address of a byte of memory.
|
is always interpreted as an integer address of a byte of memory.
|
*Note Expressions: Expressions, for more information on
|
*Note Expressions: Expressions, for more information on
|
expressions. The default for ADDR is usually just after the last
|
expressions. The default for ADDR is usually just after the last
|
address examined--but several other commands also set the default
|
address examined--but several other commands also set the default
|
address: `info breakpoints' (to the address of the last breakpoint
|
address: `info breakpoints' (to the address of the last breakpoint
|
listed), `info line' (to the starting address of a line), and
|
listed), `info line' (to the starting address of a line), and
|
`print' (if you use it to display a value from memory).
|
`print' (if you use it to display a value from memory).
|
|
|
For example, `x/3uh 0x54320' is a request to display three halfwords
|
For example, `x/3uh 0x54320' is a request to display three halfwords
|
(`h') of memory, formatted as unsigned decimal integers (`u'), starting
|
(`h') of memory, formatted as unsigned decimal integers (`u'), starting
|
at address `0x54320'. `x/4xw $sp' prints the four words (`w') of
|
at address `0x54320'. `x/4xw $sp' prints the four words (`w') of
|
memory above the stack pointer (here, `$sp'; *note Registers:
|
memory above the stack pointer (here, `$sp'; *note Registers:
|
Registers.) in hexadecimal (`x').
|
Registers.) in hexadecimal (`x').
|
|
|
Since the letters indicating unit sizes are all distinct from the
|
Since the letters indicating unit sizes are all distinct from the
|
letters specifying output formats, you do not have to remember whether
|
letters specifying output formats, you do not have to remember whether
|
unit size or format comes first; either order works. The output
|
unit size or format comes first; either order works. The output
|
specifications `4xw' and `4wx' mean exactly the same thing. (However,
|
specifications `4xw' and `4wx' mean exactly the same thing. (However,
|
the count N must come first; `wx4' does not work.)
|
the count N must come first; `wx4' does not work.)
|
|
|
Even though the unit size U is ignored for the formats `s' and `i',
|
Even though the unit size U is ignored for the formats `s' and `i',
|
you might still want to use a count N; for example, `3i' specifies that
|
you might still want to use a count N; for example, `3i' specifies that
|
you want to see three machine instructions, including any operands.
|
you want to see three machine instructions, including any operands.
|
For convenience, especially when used with the `display' command, the
|
For convenience, especially when used with the `display' command, the
|
`i' format also prints branch delay slot instructions, if any, beyond
|
`i' format also prints branch delay slot instructions, if any, beyond
|
the count specified, which immediately follow the last instruction that
|
the count specified, which immediately follow the last instruction that
|
is within the count. The command `disassemble' gives an alternative
|
is within the count. The command `disassemble' gives an alternative
|
way of inspecting machine instructions; see *note Source and Machine
|
way of inspecting machine instructions; see *note Source and Machine
|
Code: Machine Code.
|
Code: Machine Code.
|
|
|
All the defaults for the arguments to `x' are designed to make it
|
All the defaults for the arguments to `x' are designed to make it
|
easy to continue scanning memory with minimal specifications each time
|
easy to continue scanning memory with minimal specifications each time
|
you use `x'. For example, after you have inspected three machine
|
you use `x'. For example, after you have inspected three machine
|
instructions with `x/3i ADDR', you can inspect the next seven with just
|
instructions with `x/3i ADDR', you can inspect the next seven with just
|
`x/7'. If you use to repeat the `x' command, the repeat count N
|
`x/7'. If you use to repeat the `x' command, the repeat count N
|
is used again; the other arguments default as for successive uses of
|
is used again; the other arguments default as for successive uses of
|
`x'.
|
`x'.
|
|
|
When examining machine instructions, the instruction at current
|
When examining machine instructions, the instruction at current
|
program counter is shown with a `=>' marker. For example:
|
program counter is shown with a `=>' marker. For example:
|
|
|
(gdb) x/5i $pc-6
|
(gdb) x/5i $pc-6
|
0x804837f : mov %esp,%ebp
|
0x804837f : mov %esp,%ebp
|
0x8048381 : push %ecx
|
0x8048381 : push %ecx
|
0x8048382 : sub $0x4,%esp
|
0x8048382 : sub $0x4,%esp
|
=> 0x8048385 : movl $0x8048460,(%esp)
|
=> 0x8048385 : movl $0x8048460,(%esp)
|
0x804838c : call 0x80482d4
|
0x804838c : call 0x80482d4
|
|
|
The addresses and contents printed by the `x' command are not saved
|
The addresses and contents printed by the `x' command are not saved
|
in the value history because there is often too much of them and they
|
in the value history because there is often too much of them and they
|
would get in the way. Instead, GDB makes these values available for
|
would get in the way. Instead, GDB makes these values available for
|
subsequent use in expressions as values of the convenience variables
|
subsequent use in expressions as values of the convenience variables
|
`$_' and `$__'. After an `x' command, the last address examined is
|
`$_' and `$__'. After an `x' command, the last address examined is
|
available for use in expressions in the convenience variable `$_'. The
|
available for use in expressions in the convenience variable `$_'. The
|
contents of that address, as examined, are available in the convenience
|
contents of that address, as examined, are available in the convenience
|
variable `$__'.
|
variable `$__'.
|
|
|
If the `x' command has a repeat count, the address and contents saved
|
If the `x' command has a repeat count, the address and contents saved
|
are from the last memory unit printed; this is not the same as the last
|
are from the last memory unit printed; this is not the same as the last
|
address printed if several units were printed on the last line of
|
address printed if several units were printed on the last line of
|
output.
|
output.
|
|
|
When you are debugging a program running on a remote target machine
|
When you are debugging a program running on a remote target machine
|
(*note Remote Debugging::), you may wish to verify the program's image
|
(*note Remote Debugging::), you may wish to verify the program's image
|
in the remote machine's memory against the executable file you
|
in the remote machine's memory against the executable file you
|
downloaded to the target. The `compare-sections' command is provided
|
downloaded to the target. The `compare-sections' command is provided
|
for such situations.
|
for such situations.
|
|
|
`compare-sections [SECTION-NAME]'
|
`compare-sections [SECTION-NAME]'
|
Compare the data of a loadable section SECTION-NAME in the
|
Compare the data of a loadable section SECTION-NAME in the
|
executable file of the program being debugged with the same
|
executable file of the program being debugged with the same
|
section in the remote machine's memory, and report any mismatches.
|
section in the remote machine's memory, and report any mismatches.
|
With no arguments, compares all loadable sections. This command's
|
With no arguments, compares all loadable sections. This command's
|
availability depends on the target's support for the `"qCRC"'
|
availability depends on the target's support for the `"qCRC"'
|
remote request.
|
remote request.
|
|
|
|
|
File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data
|
File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data
|
|
|
10.7 Automatic Display
|
10.7 Automatic Display
|
======================
|
======================
|
|
|
If you find that you want to print the value of an expression frequently
|
If you find that you want to print the value of an expression frequently
|
(to see how it changes), you might want to add it to the "automatic
|
(to see how it changes), you might want to add it to the "automatic
|
display list" so that GDB prints its value each time your program stops.
|
display list" so that GDB prints its value each time your program stops.
|
Each expression added to the list is given a number to identify it; to
|
Each expression added to the list is given a number to identify it; to
|
remove an expression from the list, you specify that number. The
|
remove an expression from the list, you specify that number. The
|
automatic display looks like this:
|
automatic display looks like this:
|
|
|
2: foo = 38
|
2: foo = 38
|
3: bar[5] = (struct hack *) 0x3804
|
3: bar[5] = (struct hack *) 0x3804
|
|
|
This display shows item numbers, expressions and their current values.
|
This display shows item numbers, expressions and their current values.
|
As with displays you request manually using `x' or `print', you can
|
As with displays you request manually using `x' or `print', you can
|
specify the output format you prefer; in fact, `display' decides
|
specify the output format you prefer; in fact, `display' decides
|
whether to use `print' or `x' depending your format specification--it
|
whether to use `print' or `x' depending your format specification--it
|
uses `x' if you specify either the `i' or `s' format, or a unit size;
|
uses `x' if you specify either the `i' or `s' format, or a unit size;
|
otherwise it uses `print'.
|
otherwise it uses `print'.
|
|
|
`display EXPR'
|
`display EXPR'
|
Add the expression EXPR to the list of expressions to display each
|
Add the expression EXPR to the list of expressions to display each
|
time your program stops. *Note Expressions: Expressions.
|
time your program stops. *Note Expressions: Expressions.
|
|
|
`display' does not repeat if you press again after using it.
|
`display' does not repeat if you press again after using it.
|
|
|
`display/FMT EXPR'
|
`display/FMT EXPR'
|
For FMT specifying only a display format and not a size or count,
|
For FMT specifying only a display format and not a size or count,
|
add the expression EXPR to the auto-display list but arrange to
|
add the expression EXPR to the auto-display list but arrange to
|
display it each time in the specified format FMT. *Note Output
|
display it each time in the specified format FMT. *Note Output
|
Formats: Output Formats.
|
Formats: Output Formats.
|
|
|
`display/FMT ADDR'
|
`display/FMT ADDR'
|
For FMT `i' or `s', or including a unit-size or a number of units,
|
For FMT `i' or `s', or including a unit-size or a number of units,
|
add the expression ADDR as a memory address to be examined each
|
add the expression ADDR as a memory address to be examined each
|
time your program stops. Examining means in effect doing `x/FMT
|
time your program stops. Examining means in effect doing `x/FMT
|
ADDR'. *Note Examining Memory: Memory.
|
ADDR'. *Note Examining Memory: Memory.
|
|
|
For example, `display/i $pc' can be helpful, to see the machine
|
For example, `display/i $pc' can be helpful, to see the machine
|
instruction about to be executed each time execution stops (`$pc' is a
|
instruction about to be executed each time execution stops (`$pc' is a
|
common name for the program counter; *note Registers: Registers.).
|
common name for the program counter; *note Registers: Registers.).
|
|
|
`undisplay DNUMS...'
|
`undisplay DNUMS...'
|
`delete display DNUMS...'
|
`delete display DNUMS...'
|
Remove item numbers DNUMS from the list of expressions to display.
|
Remove item numbers DNUMS from the list of expressions to display.
|
|
|
`undisplay' does not repeat if you press after using it.
|
`undisplay' does not repeat if you press after using it.
|
(Otherwise you would just get the error `No display number ...'.)
|
(Otherwise you would just get the error `No display number ...'.)
|
|
|
`disable display DNUMS...'
|
`disable display DNUMS...'
|
Disable the display of item numbers DNUMS. A disabled display
|
Disable the display of item numbers DNUMS. A disabled display
|
item is not printed automatically, but is not forgotten. It may be
|
item is not printed automatically, but is not forgotten. It may be
|
enabled again later.
|
enabled again later.
|
|
|
`enable display DNUMS...'
|
`enable display DNUMS...'
|
Enable display of item numbers DNUMS. It becomes effective once
|
Enable display of item numbers DNUMS. It becomes effective once
|
again in auto display of its expression, until you specify
|
again in auto display of its expression, until you specify
|
otherwise.
|
otherwise.
|
|
|
`display'
|
`display'
|
Display the current values of the expressions on the list, just as
|
Display the current values of the expressions on the list, just as
|
is done when your program stops.
|
is done when your program stops.
|
|
|
`info display'
|
`info display'
|
Print the list of expressions previously set up to display
|
Print the list of expressions previously set up to display
|
automatically, each one with its item number, but without showing
|
automatically, each one with its item number, but without showing
|
the values. This includes disabled expressions, which are marked
|
the values. This includes disabled expressions, which are marked
|
as such. It also includes expressions which would not be
|
as such. It also includes expressions which would not be
|
displayed right now because they refer to automatic variables not
|
displayed right now because they refer to automatic variables not
|
currently available.
|
currently available.
|
|
|
If a display expression refers to local variables, then it does not
|
If a display expression refers to local variables, then it does not
|
make sense outside the lexical context for which it was set up. Such an
|
make sense outside the lexical context for which it was set up. Such an
|
expression is disabled when execution enters a context where one of its
|
expression is disabled when execution enters a context where one of its
|
variables is not defined. For example, if you give the command
|
variables is not defined. For example, if you give the command
|
`display last_char' while inside a function with an argument
|
`display last_char' while inside a function with an argument
|
`last_char', GDB displays this argument while your program continues to
|
`last_char', GDB displays this argument while your program continues to
|
stop inside that function. When it stops elsewhere--where there is no
|
stop inside that function. When it stops elsewhere--where there is no
|
variable `last_char'--the display is disabled automatically. The next
|
variable `last_char'--the display is disabled automatically. The next
|
time your program stops where `last_char' is meaningful, you can enable
|
time your program stops where `last_char' is meaningful, you can enable
|
the display expression once again.
|
the display expression once again.
|
|
|
|
|
File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data
|
File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data
|
|
|
10.8 Print Settings
|
10.8 Print Settings
|
===================
|
===================
|
|
|
GDB provides the following ways to control how arrays, structures, and
|
GDB provides the following ways to control how arrays, structures, and
|
symbols are printed.
|
symbols are printed.
|
|
|
These settings are useful for debugging programs in any language:
|
These settings are useful for debugging programs in any language:
|
|
|
`set print address'
|
`set print address'
|
`set print address on'
|
`set print address on'
|
GDB prints memory addresses showing the location of stack traces,
|
GDB prints memory addresses showing the location of stack traces,
|
structure values, pointer values, breakpoints, and so forth, even
|
structure values, pointer values, breakpoints, and so forth, even
|
when it also displays the contents of those addresses. The default
|
when it also displays the contents of those addresses. The default
|
is `on'. For example, this is what a stack frame display looks
|
is `on'. For example, this is what a stack frame display looks
|
like with `set print address on':
|
like with `set print address on':
|
|
|
(gdb) f
|
(gdb) f
|
#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
|
#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
|
at input.c:530
|
at input.c:530
|
530 if (lquote != def_lquote)
|
530 if (lquote != def_lquote)
|
|
|
`set print address off'
|
`set print address off'
|
Do not print addresses when displaying their contents. For
|
Do not print addresses when displaying their contents. For
|
example, this is the same stack frame displayed with `set print
|
example, this is the same stack frame displayed with `set print
|
address off':
|
address off':
|
|
|
(gdb) set print addr off
|
(gdb) set print addr off
|
(gdb) f
|
(gdb) f
|
#0 set_quotes (lq="<<", rq=">>") at input.c:530
|
#0 set_quotes (lq="<<", rq=">>") at input.c:530
|
530 if (lquote != def_lquote)
|
530 if (lquote != def_lquote)
|
|
|
You can use `set print address off' to eliminate all machine
|
You can use `set print address off' to eliminate all machine
|
dependent displays from the GDB interface. For example, with
|
dependent displays from the GDB interface. For example, with
|
`print address off', you should get the same text for backtraces on
|
`print address off', you should get the same text for backtraces on
|
all machines--whether or not they involve pointer arguments.
|
all machines--whether or not they involve pointer arguments.
|
|
|
`show print address'
|
`show print address'
|
Show whether or not addresses are to be printed.
|
Show whether or not addresses are to be printed.
|
|
|
When GDB prints a symbolic address, it normally prints the closest
|
When GDB prints a symbolic address, it normally prints the closest
|
earlier symbol plus an offset. If that symbol does not uniquely
|
earlier symbol plus an offset. If that symbol does not uniquely
|
identify the address (for example, it is a name whose scope is a single
|
identify the address (for example, it is a name whose scope is a single
|
source file), you may need to clarify. One way to do this is with
|
source file), you may need to clarify. One way to do this is with
|
`info line', for example `info line *0x4537'. Alternately, you can set
|
`info line', for example `info line *0x4537'. Alternately, you can set
|
GDB to print the source file and line number when it prints a symbolic
|
GDB to print the source file and line number when it prints a symbolic
|
address:
|
address:
|
|
|
`set print symbol-filename on'
|
`set print symbol-filename on'
|
Tell GDB to print the source file name and line number of a symbol
|
Tell GDB to print the source file name and line number of a symbol
|
in the symbolic form of an address.
|
in the symbolic form of an address.
|
|
|
`set print symbol-filename off'
|
`set print symbol-filename off'
|
Do not print source file name and line number of a symbol. This
|
Do not print source file name and line number of a symbol. This
|
is the default.
|
is the default.
|
|
|
`show print symbol-filename'
|
`show print symbol-filename'
|
Show whether or not GDB will print the source file name and line
|
Show whether or not GDB will print the source file name and line
|
number of a symbol in the symbolic form of an address.
|
number of a symbol in the symbolic form of an address.
|
|
|
Another situation where it is helpful to show symbol filenames and
|
Another situation where it is helpful to show symbol filenames and
|
line numbers is when disassembling code; GDB shows you the line number
|
line numbers is when disassembling code; GDB shows you the line number
|
and source file that corresponds to each instruction.
|
and source file that corresponds to each instruction.
|
|
|
Also, you may wish to see the symbolic form only if the address being
|
Also, you may wish to see the symbolic form only if the address being
|
printed is reasonably close to the closest earlier symbol:
|
printed is reasonably close to the closest earlier symbol:
|
|
|
`set print max-symbolic-offset MAX-OFFSET'
|
`set print max-symbolic-offset MAX-OFFSET'
|
Tell GDB to only display the symbolic form of an address if the
|
Tell GDB to only display the symbolic form of an address if the
|
offset between the closest earlier symbol and the address is less
|
offset between the closest earlier symbol and the address is less
|
than MAX-OFFSET. The default is 0, which tells GDB to always
|
than MAX-OFFSET. The default is 0, which tells GDB to always
|
print the symbolic form of an address if any symbol precedes it.
|
print the symbolic form of an address if any symbol precedes it.
|
|
|
`show print max-symbolic-offset'
|
`show print max-symbolic-offset'
|
Ask how large the maximum offset is that GDB prints in a symbolic
|
Ask how large the maximum offset is that GDB prints in a symbolic
|
address.
|
address.
|
|
|
If you have a pointer and you are not sure where it points, try `set
|
If you have a pointer and you are not sure where it points, try `set
|
print symbol-filename on'. Then you can determine the name and source
|
print symbol-filename on'. Then you can determine the name and source
|
file location of the variable where it points, using `p/a POINTER'.
|
file location of the variable where it points, using `p/a POINTER'.
|
This interprets the address in symbolic form. For example, here GDB
|
This interprets the address in symbolic form. For example, here GDB
|
shows that a variable `ptt' points at another variable `t', defined in
|
shows that a variable `ptt' points at another variable `t', defined in
|
`hi2.c':
|
`hi2.c':
|
|
|
(gdb) set print symbol-filename on
|
(gdb) set print symbol-filename on
|
(gdb) p/a ptt
|
(gdb) p/a ptt
|
$4 = 0xe008
|
$4 = 0xe008
|
|
|
_Warning:_ For pointers that point to a local variable, `p/a' does
|
_Warning:_ For pointers that point to a local variable, `p/a' does
|
not show the symbol name and filename of the referent, even with
|
not show the symbol name and filename of the referent, even with
|
the appropriate `set print' options turned on.
|
the appropriate `set print' options turned on.
|
|
|
Other settings control how different kinds of objects are printed:
|
Other settings control how different kinds of objects are printed:
|
|
|
`set print array'
|
`set print array'
|
`set print array on'
|
`set print array on'
|
Pretty print arrays. This format is more convenient to read, but
|
Pretty print arrays. This format is more convenient to read, but
|
uses more space. The default is off.
|
uses more space. The default is off.
|
|
|
`set print array off'
|
`set print array off'
|
Return to compressed format for arrays.
|
Return to compressed format for arrays.
|
|
|
`show print array'
|
`show print array'
|
Show whether compressed or pretty format is selected for displaying
|
Show whether compressed or pretty format is selected for displaying
|
arrays.
|
arrays.
|
|
|
`set print array-indexes'
|
`set print array-indexes'
|
`set print array-indexes on'
|
`set print array-indexes on'
|
Print the index of each element when displaying arrays. May be
|
Print the index of each element when displaying arrays. May be
|
more convenient to locate a given element in the array or quickly
|
more convenient to locate a given element in the array or quickly
|
find the index of a given element in that printed array. The
|
find the index of a given element in that printed array. The
|
default is off.
|
default is off.
|
|
|
`set print array-indexes off'
|
`set print array-indexes off'
|
Stop printing element indexes when displaying arrays.
|
Stop printing element indexes when displaying arrays.
|
|
|
`show print array-indexes'
|
`show print array-indexes'
|
Show whether the index of each element is printed when displaying
|
Show whether the index of each element is printed when displaying
|
arrays.
|
arrays.
|
|
|
`set print elements NUMBER-OF-ELEMENTS'
|
`set print elements NUMBER-OF-ELEMENTS'
|
Set a limit on how many elements of an array GDB will print. If
|
Set a limit on how many elements of an array GDB will print. If
|
GDB is printing a large array, it stops printing after it has
|
GDB is printing a large array, it stops printing after it has
|
printed the number of elements set by the `set print elements'
|
printed the number of elements set by the `set print elements'
|
command. This limit also applies to the display of strings. When
|
command. This limit also applies to the display of strings. When
|
GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS
|
GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS
|
to zero means that the printing is unlimited.
|
to zero means that the printing is unlimited.
|
|
|
`show print elements'
|
`show print elements'
|
Display the number of elements of a large array that GDB will
|
Display the number of elements of a large array that GDB will
|
print. If the number is 0, then the printing is unlimited.
|
print. If the number is 0, then the printing is unlimited.
|
|
|
`set print frame-arguments VALUE'
|
`set print frame-arguments VALUE'
|
This command allows to control how the values of arguments are
|
This command allows to control how the values of arguments are
|
printed when the debugger prints a frame (*note Frames::). The
|
printed when the debugger prints a frame (*note Frames::). The
|
possible values are:
|
possible values are:
|
|
|
`all'
|
`all'
|
The values of all arguments are printed.
|
The values of all arguments are printed.
|
|
|
`scalars'
|
`scalars'
|
Print the value of an argument only if it is a scalar. The
|
Print the value of an argument only if it is a scalar. The
|
value of more complex arguments such as arrays, structures,
|
value of more complex arguments such as arrays, structures,
|
unions, etc, is replaced by `...'. This is the default.
|
unions, etc, is replaced by `...'. This is the default.
|
Here is an example where only scalar arguments are shown:
|
Here is an example where only scalar arguments are shown:
|
|
|
#1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green)
|
#1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green)
|
at frame-args.c:23
|
at frame-args.c:23
|
|
|
`none'
|
`none'
|
None of the argument values are printed. Instead, the value
|
None of the argument values are printed. Instead, the value
|
of each argument is replaced by `...'. In this case, the
|
of each argument is replaced by `...'. In this case, the
|
example above now becomes:
|
example above now becomes:
|
|
|
#1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...)
|
#1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...)
|
at frame-args.c:23
|
at frame-args.c:23
|
|
|
By default, only scalar arguments are printed. This command can
|
By default, only scalar arguments are printed. This command can
|
be used to configure the debugger to print the value of all
|
be used to configure the debugger to print the value of all
|
arguments, regardless of their type. However, it is often
|
arguments, regardless of their type. However, it is often
|
advantageous to not print the value of more complex parameters.
|
advantageous to not print the value of more complex parameters.
|
For instance, it reduces the amount of information printed in each
|
For instance, it reduces the amount of information printed in each
|
frame, making the backtrace more readable. Also, it improves
|
frame, making the backtrace more readable. Also, it improves
|
performance when displaying Ada frames, because the computation of
|
performance when displaying Ada frames, because the computation of
|
large arguments can sometimes be CPU-intensive, especially in
|
large arguments can sometimes be CPU-intensive, especially in
|
large applications. Setting `print frame-arguments' to `scalars'
|
large applications. Setting `print frame-arguments' to `scalars'
|
(the default) or `none' avoids this computation, thus speeding up
|
(the default) or `none' avoids this computation, thus speeding up
|
the display of each Ada frame.
|
the display of each Ada frame.
|
|
|
`show print frame-arguments'
|
`show print frame-arguments'
|
Show how the value of arguments should be displayed when printing
|
Show how the value of arguments should be displayed when printing
|
a frame.
|
a frame.
|
|
|
`set print repeats'
|
`set print repeats'
|
Set the threshold for suppressing display of repeated array
|
Set the threshold for suppressing display of repeated array
|
elements. When the number of consecutive identical elements of an
|
elements. When the number of consecutive identical elements of an
|
array exceeds the threshold, GDB prints the string `"
|
array exceeds the threshold, GDB prints the string `"
|
times>"', where N is the number of identical repetitions, instead
|
times>"', where N is the number of identical repetitions, instead
|
of displaying the identical elements themselves. Setting the
|
of displaying the identical elements themselves. Setting the
|
threshold to zero will cause all elements to be individually
|
threshold to zero will cause all elements to be individually
|
printed. The default threshold is 10.
|
printed. The default threshold is 10.
|
|
|
`show print repeats'
|
`show print repeats'
|
Display the current threshold for printing repeated identical
|
Display the current threshold for printing repeated identical
|
elements.
|
elements.
|
|
|
`set print null-stop'
|
`set print null-stop'
|
Cause GDB to stop printing the characters of an array when the
|
Cause GDB to stop printing the characters of an array when the
|
first NULL is encountered. This is useful when large arrays
|
first NULL is encountered. This is useful when large arrays
|
actually contain only short strings. The default is off.
|
actually contain only short strings. The default is off.
|
|
|
`show print null-stop'
|
`show print null-stop'
|
Show whether GDB stops printing an array on the first NULL
|
Show whether GDB stops printing an array on the first NULL
|
character.
|
character.
|
|
|
`set print pretty on'
|
`set print pretty on'
|
Cause GDB to print structures in an indented format with one member
|
Cause GDB to print structures in an indented format with one member
|
per line, like this:
|
per line, like this:
|
|
|
$1 = {
|
$1 = {
|
next = 0x0,
|
next = 0x0,
|
flags = {
|
flags = {
|
sweet = 1,
|
sweet = 1,
|
sour = 1
|
sour = 1
|
},
|
},
|
meat = 0x54 "Pork"
|
meat = 0x54 "Pork"
|
}
|
}
|
|
|
`set print pretty off'
|
`set print pretty off'
|
Cause GDB to print structures in a compact format, like this:
|
Cause GDB to print structures in a compact format, like this:
|
|
|
$1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \
|
$1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \
|
meat = 0x54 "Pork"}
|
meat = 0x54 "Pork"}
|
|
|
This is the default format.
|
This is the default format.
|
|
|
`show print pretty'
|
`show print pretty'
|
Show which format GDB is using to print structures.
|
Show which format GDB is using to print structures.
|
|
|
`set print sevenbit-strings on'
|
`set print sevenbit-strings on'
|
Print using only seven-bit characters; if this option is set, GDB
|
Print using only seven-bit characters; if this option is set, GDB
|
displays any eight-bit characters (in strings or character values)
|
displays any eight-bit characters (in strings or character values)
|
using the notation `\'NNN. This setting is best if you are
|
using the notation `\'NNN. This setting is best if you are
|
working in English (ASCII) and you use the high-order bit of
|
working in English (ASCII) and you use the high-order bit of
|
characters as a marker or "meta" bit.
|
characters as a marker or "meta" bit.
|
|
|
`set print sevenbit-strings off'
|
`set print sevenbit-strings off'
|
Print full eight-bit characters. This allows the use of more
|
Print full eight-bit characters. This allows the use of more
|
international character sets, and is the default.
|
international character sets, and is the default.
|
|
|
`show print sevenbit-strings'
|
`show print sevenbit-strings'
|
Show whether or not GDB is printing only seven-bit characters.
|
Show whether or not GDB is printing only seven-bit characters.
|
|
|
`set print union on'
|
`set print union on'
|
Tell GDB to print unions which are contained in structures and
|
Tell GDB to print unions which are contained in structures and
|
other unions. This is the default setting.
|
other unions. This is the default setting.
|
|
|
`set print union off'
|
`set print union off'
|
Tell GDB not to print unions which are contained in structures and
|
Tell GDB not to print unions which are contained in structures and
|
other unions. GDB will print `"{...}"' instead.
|
other unions. GDB will print `"{...}"' instead.
|
|
|
`show print union'
|
`show print union'
|
Ask GDB whether or not it will print unions which are contained in
|
Ask GDB whether or not it will print unions which are contained in
|
structures and other unions.
|
structures and other unions.
|
|
|
For example, given the declarations
|
For example, given the declarations
|
|
|
typedef enum {Tree, Bug} Species;
|
typedef enum {Tree, Bug} Species;
|
typedef enum {Big_tree, Acorn, Seedling} Tree_forms;
|
typedef enum {Big_tree, Acorn, Seedling} Tree_forms;
|
typedef enum {Caterpillar, Cocoon, Butterfly}
|
typedef enum {Caterpillar, Cocoon, Butterfly}
|
Bug_forms;
|
Bug_forms;
|
|
|
struct thing {
|
struct thing {
|
Species it;
|
Species it;
|
union {
|
union {
|
Tree_forms tree;
|
Tree_forms tree;
|
Bug_forms bug;
|
Bug_forms bug;
|
} form;
|
} form;
|
};
|
};
|
|
|
struct thing foo = {Tree, {Acorn}};
|
struct thing foo = {Tree, {Acorn}};
|
|
|
with `set print union on' in effect `p foo' would print
|
with `set print union on' in effect `p foo' would print
|
|
|
$1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}
|
$1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}
|
|
|
and with `set print union off' in effect it would print
|
and with `set print union off' in effect it would print
|
|
|
$1 = {it = Tree, form = {...}}
|
$1 = {it = Tree, form = {...}}
|
|
|
`set print union' affects programs written in C-like languages and
|
`set print union' affects programs written in C-like languages and
|
in Pascal.
|
in Pascal.
|
|
|
These settings are of interest when debugging C++ programs:
|
These settings are of interest when debugging C++ programs:
|
|
|
`set print demangle'
|
`set print demangle'
|
`set print demangle on'
|
`set print demangle on'
|
Print C++ names in their source form rather than in the encoded
|
Print C++ names in their source form rather than in the encoded
|
("mangled") form passed to the assembler and linker for type-safe
|
("mangled") form passed to the assembler and linker for type-safe
|
linkage. The default is on.
|
linkage. The default is on.
|
|
|
`show print demangle'
|
`show print demangle'
|
Show whether C++ names are printed in mangled or demangled form.
|
Show whether C++ names are printed in mangled or demangled form.
|
|
|
`set print asm-demangle'
|
`set print asm-demangle'
|
`set print asm-demangle on'
|
`set print asm-demangle on'
|
Print C++ names in their source form rather than their mangled
|
Print C++ names in their source form rather than their mangled
|
form, even in assembler code printouts such as instruction
|
form, even in assembler code printouts such as instruction
|
disassemblies. The default is off.
|
disassemblies. The default is off.
|
|
|
`show print asm-demangle'
|
`show print asm-demangle'
|
Show whether C++ names in assembly listings are printed in mangled
|
Show whether C++ names in assembly listings are printed in mangled
|
or demangled form.
|
or demangled form.
|
|
|
`set demangle-style STYLE'
|
`set demangle-style STYLE'
|
Choose among several encoding schemes used by different compilers
|
Choose among several encoding schemes used by different compilers
|
to represent C++ names. The choices for STYLE are currently:
|
to represent C++ names. The choices for STYLE are currently:
|
|
|
`auto'
|
`auto'
|
Allow GDB to choose a decoding style by inspecting your
|
Allow GDB to choose a decoding style by inspecting your
|
program.
|
program.
|
|
|
`gnu'
|
`gnu'
|
Decode based on the GNU C++ compiler (`g++') encoding
|
Decode based on the GNU C++ compiler (`g++') encoding
|
algorithm. This is the default.
|
algorithm. This is the default.
|
|
|
`hp'
|
`hp'
|
Decode based on the HP ANSI C++ (`aCC') encoding algorithm.
|
Decode based on the HP ANSI C++ (`aCC') encoding algorithm.
|
|
|
`lucid'
|
`lucid'
|
Decode based on the Lucid C++ compiler (`lcc') encoding
|
Decode based on the Lucid C++ compiler (`lcc') encoding
|
algorithm.
|
algorithm.
|
|
|
`arm'
|
`arm'
|
Decode using the algorithm in the `C++ Annotated Reference
|
Decode using the algorithm in the `C++ Annotated Reference
|
Manual'. *Warning:* this setting alone is not sufficient to
|
Manual'. *Warning:* this setting alone is not sufficient to
|
allow debugging `cfront'-generated executables. GDB would
|
allow debugging `cfront'-generated executables. GDB would
|
require further enhancement to permit that.
|
require further enhancement to permit that.
|
|
|
If you omit STYLE, you will see a list of possible formats.
|
If you omit STYLE, you will see a list of possible formats.
|
|
|
`show demangle-style'
|
`show demangle-style'
|
Display the encoding style currently in use for decoding C++
|
Display the encoding style currently in use for decoding C++
|
symbols.
|
symbols.
|
|
|
`set print object'
|
`set print object'
|
`set print object on'
|
`set print object on'
|
When displaying a pointer to an object, identify the _actual_
|
When displaying a pointer to an object, identify the _actual_
|
(derived) type of the object rather than the _declared_ type, using
|
(derived) type of the object rather than the _declared_ type, using
|
the virtual function table.
|
the virtual function table.
|
|
|
`set print object off'
|
`set print object off'
|
Display only the declared type of objects, without reference to the
|
Display only the declared type of objects, without reference to the
|
virtual function table. This is the default setting.
|
virtual function table. This is the default setting.
|
|
|
`show print object'
|
`show print object'
|
Show whether actual, or declared, object types are displayed.
|
Show whether actual, or declared, object types are displayed.
|
|
|
`set print static-members'
|
`set print static-members'
|
`set print static-members on'
|
`set print static-members on'
|
Print static members when displaying a C++ object. The default is
|
Print static members when displaying a C++ object. The default is
|
on.
|
on.
|
|
|
`set print static-members off'
|
`set print static-members off'
|
Do not print static members when displaying a C++ object.
|
Do not print static members when displaying a C++ object.
|
|
|
`show print static-members'
|
`show print static-members'
|
Show whether C++ static members are printed or not.
|
Show whether C++ static members are printed or not.
|
|
|
`set print pascal_static-members'
|
`set print pascal_static-members'
|
`set print pascal_static-members on'
|
`set print pascal_static-members on'
|
Print static members when displaying a Pascal object. The default
|
Print static members when displaying a Pascal object. The default
|
is on.
|
is on.
|
|
|
`set print pascal_static-members off'
|
`set print pascal_static-members off'
|
Do not print static members when displaying a Pascal object.
|
Do not print static members when displaying a Pascal object.
|
|
|
`show print pascal_static-members'
|
`show print pascal_static-members'
|
Show whether Pascal static members are printed or not.
|
Show whether Pascal static members are printed or not.
|
|
|
`set print vtbl'
|
`set print vtbl'
|
`set print vtbl on'
|
`set print vtbl on'
|
Pretty print C++ virtual function tables. The default is off.
|
Pretty print C++ virtual function tables. The default is off.
|
(The `vtbl' commands do not work on programs compiled with the HP
|
(The `vtbl' commands do not work on programs compiled with the HP
|
ANSI C++ compiler (`aCC').)
|
ANSI C++ compiler (`aCC').)
|
|
|
`set print vtbl off'
|
`set print vtbl off'
|
Do not pretty print C++ virtual function tables.
|
Do not pretty print C++ virtual function tables.
|
|
|
`show print vtbl'
|
`show print vtbl'
|
Show whether C++ virtual function tables are pretty printed, or
|
Show whether C++ virtual function tables are pretty printed, or
|
not.
|
not.
|
|
|
|
|
File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data
|
File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data
|
|
|
10.9 Pretty Printing
|
10.9 Pretty Printing
|
====================
|
====================
|
|
|
GDB provides a mechanism to allow pretty-printing of values using
|
GDB provides a mechanism to allow pretty-printing of values using
|
Python code. It greatly simplifies the display of complex objects.
|
Python code. It greatly simplifies the display of complex objects.
|
This mechanism works for both MI and the CLI.
|
This mechanism works for both MI and the CLI.
|
|
|
For example, here is how a C++ `std::string' looks without a
|
For example, here is how a C++ `std::string' looks without a
|
pretty-printer:
|
pretty-printer:
|
|
|
(gdb) print s
|
(gdb) print s
|
$1 = {
|
$1 = {
|
static npos = 4294967295,
|
static npos = 4294967295,
|
_M_dataplus = {
|
_M_dataplus = {
|
> = {
|
> = {
|
<__gnu_cxx::new_allocator> = {
|
<__gnu_cxx::new_allocator> = {
|
},
|
},
|
},
|
},
|
members of std::basic_string,
|
members of std::basic_string,
|
std::allocator >::_Alloc_hider:
|
std::allocator >::_Alloc_hider:
|
_M_p = 0x804a014 "abcd"
|
_M_p = 0x804a014 "abcd"
|
}
|
}
|
}
|
}
|
|
|
With a pretty-printer for `std::string' only the contents are
|
With a pretty-printer for `std::string' only the contents are
|
printed:
|
printed:
|
|
|
(gdb) print s
|
(gdb) print s
|
$2 = "abcd"
|
$2 = "abcd"
|
|
|
For implementing pretty printers for new types you should read the
|
For implementing pretty printers for new types you should read the
|
Python API details (*note Pretty Printing API::).
|
Python API details (*note Pretty Printing API::).
|
|
|
|
|
File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data
|
File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data
|
|
|
10.10 Value History
|
10.10 Value History
|
===================
|
===================
|
|
|
Values printed by the `print' command are saved in the GDB "value
|
Values printed by the `print' command are saved in the GDB "value
|
history". This allows you to refer to them in other expressions.
|
history". This allows you to refer to them in other expressions.
|
Values are kept until the symbol table is re-read or discarded (for
|
Values are kept until the symbol table is re-read or discarded (for
|
example with the `file' or `symbol-file' commands). When the symbol
|
example with the `file' or `symbol-file' commands). When the symbol
|
table changes, the value history is discarded, since the values may
|
table changes, the value history is discarded, since the values may
|
contain pointers back to the types defined in the symbol table.
|
contain pointers back to the types defined in the symbol table.
|
|
|
The values printed are given "history numbers" by which you can
|
The values printed are given "history numbers" by which you can
|
refer to them. These are successive integers starting with one.
|
refer to them. These are successive integers starting with one.
|
`print' shows you the history number assigned to a value by printing
|
`print' shows you the history number assigned to a value by printing
|
`$NUM = ' before the value; here NUM is the history number.
|
`$NUM = ' before the value; here NUM is the history number.
|
|
|
To refer to any previous value, use `$' followed by the value's
|
To refer to any previous value, use `$' followed by the value's
|
history number. The way `print' labels its output is designed to
|
history number. The way `print' labels its output is designed to
|
remind you of this. Just `$' refers to the most recent value in the
|
remind you of this. Just `$' refers to the most recent value in the
|
history, and `$$' refers to the value before that. `$$N' refers to the
|
history, and `$$' refers to the value before that. `$$N' refers to the
|
Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is
|
Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is
|
equivalent to `$$', and `$$0' is equivalent to `$'.
|
equivalent to `$$', and `$$0' is equivalent to `$'.
|
|
|
For example, suppose you have just printed a pointer to a structure
|
For example, suppose you have just printed a pointer to a structure
|
and want to see the contents of the structure. It suffices to type
|
and want to see the contents of the structure. It suffices to type
|
|
|
p *$
|
p *$
|
|
|
If you have a chain of structures where the component `next' points
|
If you have a chain of structures where the component `next' points
|
to the next one, you can print the contents of the next one with this:
|
to the next one, you can print the contents of the next one with this:
|
|
|
p *$.next
|
p *$.next
|
|
|
You can print successive links in the chain by repeating this
|
You can print successive links in the chain by repeating this
|
command--which you can do by just typing .
|
command--which you can do by just typing .
|
|
|
Note that the history records values, not expressions. If the value
|
Note that the history records values, not expressions. If the value
|
of `x' is 4 and you type these commands:
|
of `x' is 4 and you type these commands:
|
|
|
print x
|
print x
|
set x=5
|
set x=5
|
|
|
then the value recorded in the value history by the `print' command
|
then the value recorded in the value history by the `print' command
|
remains 4 even though the value of `x' has changed.
|
remains 4 even though the value of `x' has changed.
|
|
|
`show values'
|
`show values'
|
Print the last ten values in the value history, with their item
|
Print the last ten values in the value history, with their item
|
numbers. This is like `p $$9' repeated ten times, except that
|
numbers. This is like `p $$9' repeated ten times, except that
|
`show values' does not change the history.
|
`show values' does not change the history.
|
|
|
`show values N'
|
`show values N'
|
Print ten history values centered on history item number N.
|
Print ten history values centered on history item number N.
|
|
|
`show values +'
|
`show values +'
|
Print ten history values just after the values last printed. If
|
Print ten history values just after the values last printed. If
|
no more values are available, `show values +' produces no display.
|
no more values are available, `show values +' produces no display.
|
|
|
Pressing to repeat `show values N' has exactly the same effect
|
Pressing to repeat `show values N' has exactly the same effect
|
as `show values +'.
|
as `show values +'.
|
|
|
|
|
File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data
|
File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data
|
|
|
10.11 Convenience Variables
|
10.11 Convenience Variables
|
===========================
|
===========================
|
|
|
GDB provides "convenience variables" that you can use within GDB to
|
GDB provides "convenience variables" that you can use within GDB to
|
hold on to a value and refer to it later. These variables exist
|
hold on to a value and refer to it later. These variables exist
|
entirely within GDB; they are not part of your program, and setting a
|
entirely within GDB; they are not part of your program, and setting a
|
convenience variable has no direct effect on further execution of your
|
convenience variable has no direct effect on further execution of your
|
program. That is why you can use them freely.
|
program. That is why you can use them freely.
|
|
|
Convenience variables are prefixed with `$'. Any name preceded by
|
Convenience variables are prefixed with `$'. Any name preceded by
|
`$' can be used for a convenience variable, unless it is one of the
|
`$' can be used for a convenience variable, unless it is one of the
|
predefined machine-specific register names (*note Registers:
|
predefined machine-specific register names (*note Registers:
|
Registers.). (Value history references, in contrast, are _numbers_
|
Registers.). (Value history references, in contrast, are _numbers_
|
preceded by `$'. *Note Value History: Value History.)
|
preceded by `$'. *Note Value History: Value History.)
|
|
|
You can save a value in a convenience variable with an assignment
|
You can save a value in a convenience variable with an assignment
|
expression, just as you would set a variable in your program. For
|
expression, just as you would set a variable in your program. For
|
example:
|
example:
|
|
|
set $foo = *object_ptr
|
set $foo = *object_ptr
|
|
|
would save in `$foo' the value contained in the object pointed to by
|
would save in `$foo' the value contained in the object pointed to by
|
`object_ptr'.
|
`object_ptr'.
|
|
|
Using a convenience variable for the first time creates it, but its
|
Using a convenience variable for the first time creates it, but its
|
value is `void' until you assign a new value. You can alter the value
|
value is `void' until you assign a new value. You can alter the value
|
with another assignment at any time.
|
with another assignment at any time.
|
|
|
Convenience variables have no fixed types. You can assign a
|
Convenience variables have no fixed types. You can assign a
|
convenience variable any type of value, including structures and
|
convenience variable any type of value, including structures and
|
arrays, even if that variable already has a value of a different type.
|
arrays, even if that variable already has a value of a different type.
|
The convenience variable, when used as an expression, has the type of
|
The convenience variable, when used as an expression, has the type of
|
its current value.
|
its current value.
|
|
|
`show convenience'
|
`show convenience'
|
Print a list of convenience variables used so far, and their
|
Print a list of convenience variables used so far, and their
|
values. Abbreviated `show conv'.
|
values. Abbreviated `show conv'.
|
|
|
`init-if-undefined $VARIABLE = EXPRESSION'
|
`init-if-undefined $VARIABLE = EXPRESSION'
|
Set a convenience variable if it has not already been set. This
|
Set a convenience variable if it has not already been set. This
|
is useful for user-defined commands that keep some state. It is
|
is useful for user-defined commands that keep some state. It is
|
similar, in concept, to using local static variables with
|
similar, in concept, to using local static variables with
|
initializers in C (except that convenience variables are global).
|
initializers in C (except that convenience variables are global).
|
It can also be used to allow users to override default values used
|
It can also be used to allow users to override default values used
|
in a command script.
|
in a command script.
|
|
|
If the variable is already defined then the expression is not
|
If the variable is already defined then the expression is not
|
evaluated so any side-effects do not occur.
|
evaluated so any side-effects do not occur.
|
|
|
One of the ways to use a convenience variable is as a counter to be
|
One of the ways to use a convenience variable is as a counter to be
|
incremented or a pointer to be advanced. For example, to print a field
|
incremented or a pointer to be advanced. For example, to print a field
|
from successive elements of an array of structures:
|
from successive elements of an array of structures:
|
|
|
set $i = 0
|
set $i = 0
|
print bar[$i++]->contents
|
print bar[$i++]->contents
|
|
|
Repeat that command by typing .
|
Repeat that command by typing .
|
|
|
Some convenience variables are created automatically by GDB and given
|
Some convenience variables are created automatically by GDB and given
|
values likely to be useful.
|
values likely to be useful.
|
|
|
`$_'
|
`$_'
|
The variable `$_' is automatically set by the `x' command to the
|
The variable `$_' is automatically set by the `x' command to the
|
last address examined (*note Examining Memory: Memory.). Other
|
last address examined (*note Examining Memory: Memory.). Other
|
commands which provide a default address for `x' to examine also
|
commands which provide a default address for `x' to examine also
|
set `$_' to that address; these commands include `info line' and
|
set `$_' to that address; these commands include `info line' and
|
`info breakpoint'. The type of `$_' is `void *' except when set
|
`info breakpoint'. The type of `$_' is `void *' except when set
|
by the `x' command, in which case it is a pointer to the type of
|
by the `x' command, in which case it is a pointer to the type of
|
`$__'.
|
`$__'.
|
|
|
`$__'
|
`$__'
|
The variable `$__' is automatically set by the `x' command to the
|
The variable `$__' is automatically set by the `x' command to the
|
value found in the last address examined. Its type is chosen to
|
value found in the last address examined. Its type is chosen to
|
match the format in which the data was printed.
|
match the format in which the data was printed.
|
|
|
`$_exitcode'
|
`$_exitcode'
|
The variable `$_exitcode' is automatically set to the exit code
|
The variable `$_exitcode' is automatically set to the exit code
|
when the program being debugged terminates.
|
when the program being debugged terminates.
|
|
|
`$_sdata'
|
`$_sdata'
|
The variable `$_sdata' contains extra collected static tracepoint
|
The variable `$_sdata' contains extra collected static tracepoint
|
data. *Note Tracepoint Action Lists: Tracepoint Actions. Note
|
data. *Note Tracepoint Action Lists: Tracepoint Actions. Note
|
that `$_sdata' could be empty, if not inspecting a trace buffer, or
|
that `$_sdata' could be empty, if not inspecting a trace buffer, or
|
if extra static tracepoint data has not been collected.
|
if extra static tracepoint data has not been collected.
|
|
|
`$_siginfo'
|
`$_siginfo'
|
The variable `$_siginfo' contains extra signal information (*note
|
The variable `$_siginfo' contains extra signal information (*note
|
extra signal information::). Note that `$_siginfo' could be
|
extra signal information::). Note that `$_siginfo' could be
|
empty, if the application has not yet received any signals. For
|
empty, if the application has not yet received any signals. For
|
example, it will be empty before you execute the `run' command.
|
example, it will be empty before you execute the `run' command.
|
|
|
`$_tlb'
|
`$_tlb'
|
The variable `$_tlb' is automatically set when debugging
|
The variable `$_tlb' is automatically set when debugging
|
applications running on MS-Windows in native mode or connected to
|
applications running on MS-Windows in native mode or connected to
|
gdbserver that supports the `qGetTIBAddr' request. *Note General
|
gdbserver that supports the `qGetTIBAddr' request. *Note General
|
Query Packets::. This variable contains the address of the thread
|
Query Packets::. This variable contains the address of the thread
|
information block.
|
information block.
|
|
|
|
|
On HP-UX systems, if you refer to a function or variable name that
|
On HP-UX systems, if you refer to a function or variable name that
|
begins with a dollar sign, GDB searches for a user or system name
|
begins with a dollar sign, GDB searches for a user or system name
|
first, before it searches for a convenience variable.
|
first, before it searches for a convenience variable.
|
|
|
GDB also supplies some "convenience functions". These have a syntax
|
GDB also supplies some "convenience functions". These have a syntax
|
similar to convenience variables. A convenience function can be used
|
similar to convenience variables. A convenience function can be used
|
in an expression just like an ordinary function; however, a convenience
|
in an expression just like an ordinary function; however, a convenience
|
function is implemented internally to GDB.
|
function is implemented internally to GDB.
|
|
|
`help function'
|
`help function'
|
Print a list of all convenience functions.
|
Print a list of all convenience functions.
|
|
|
|
|
