1989-01-31 17:56:40 +00:00
|
|
|
\input texinfo
|
1989-09-30 00:00:00 +00:00
|
|
|
@setfilename gdb.info
|
1989-01-31 17:56:40 +00:00
|
|
|
@settitle GDB, The GNU Debugger
|
1989-09-30 00:00:00 +00:00
|
|
|
@synindex ky cp
|
1989-01-31 17:56:40 +00:00
|
|
|
@ifinfo
|
|
|
|
This file documents the GNU debugger GDB.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
Copyright (C) 1988, 1989 Free Software Foundation, Inc.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
|
|
this manual provided the copyright notice and this permission notice
|
|
|
|
are preserved on all copies.
|
|
|
|
|
|
|
|
@ignore
|
|
|
|
Permission is granted to process this file through Tex and print the
|
|
|
|
results, provided the printed document carries copying permission
|
|
|
|
notice identical to this one except for the removal of this paragraph
|
|
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
|
|
|
|
@end ignore
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
|
|
manual under the conditions for verbatim copying, provided also that the
|
1989-09-30 00:00:00 +00:00
|
|
|
section entitled ``GNU General Public License'' is included exactly as
|
|
|
|
in the original, and provided that the entire resulting derived work is
|
|
|
|
distributed under the terms of a permission notice identical to this
|
|
|
|
one.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
|
|
into another language, under the above conditions for modified versions,
|
1989-09-30 00:00:00 +00:00
|
|
|
except that the section entitled ``GNU General Public License'' may be
|
|
|
|
included in a translation approved by the author instead of in the
|
|
|
|
original English.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end ifinfo
|
|
|
|
|
|
|
|
@setchapternewpage odd
|
|
|
|
@settitle GDB Manual
|
|
|
|
@titlepage
|
|
|
|
@sp 6
|
1990-12-17 18:23:17 +00:00
|
|
|
@center @titlefont{GDB}
|
1989-01-31 17:56:40 +00:00
|
|
|
@sp 1
|
|
|
|
@center The GNU Source-Level Debugger
|
|
|
|
@sp 4
|
1990-11-09 18:30:56 +00:00
|
|
|
@center Third Edition, GDB version 4.0
|
1989-01-31 17:56:40 +00:00
|
|
|
@sp 1
|
1990-12-17 18:23:17 +00:00
|
|
|
@center December 1990
|
1989-01-31 17:56:40 +00:00
|
|
|
@sp 5
|
|
|
|
@center Richard M. Stallman
|
1990-12-17 18:23:17 +00:00
|
|
|
@center (Revised by Cygnus Support)
|
1989-01-31 17:56:40 +00:00
|
|
|
@page
|
1990-12-19 13:30:35 +00:00
|
|
|
@hfill Cygnus Support
|
|
|
|
@par@hskip -@parfillskip@hfill $Revision$
|
|
|
|
@par@hskip -@parfillskip@hfill @TeX{}info @texinfoversion
|
1989-01-31 17:56:40 +00:00
|
|
|
@vskip 0pt plus 1filll
|
1990-12-17 18:23:17 +00:00
|
|
|
Copyright @copyright{} 1988, 1989, 1990 Free Software Foundation, Inc.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
|
|
this manual provided the copyright notice and this permission notice
|
|
|
|
are preserved on all copies.
|
|
|
|
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
|
|
manual under the conditions for verbatim copying, provided also that the
|
1989-09-30 00:00:00 +00:00
|
|
|
section entitled ``GNU General Public License'' is included exactly as
|
|
|
|
in the original, and provided that the entire resulting derived work is
|
|
|
|
distributed under the terms of a permission notice identical to this
|
|
|
|
one.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
|
|
into another language, under the above conditions for modified versions,
|
1989-09-30 00:00:00 +00:00
|
|
|
except that the section entitled ``GNU General Public License'' may be
|
|
|
|
included in a translation approved by the author instead of in the
|
|
|
|
original English.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end titlepage
|
|
|
|
@page
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Top, Top, Top, (DIR)
|
1989-01-31 17:56:40 +00:00
|
|
|
@unnumbered Summary of GDB
|
|
|
|
|
|
|
|
The purpose of a debugger such as GDB is to allow you to execute another
|
|
|
|
program while examining what is going on inside it. We call the other
|
|
|
|
program ``your program'' or ``the program being debugged''.
|
|
|
|
|
|
|
|
GDB can do four kinds of things (plus other things in support of these):
|
|
|
|
|
|
|
|
@enumerate
|
|
|
|
@item
|
|
|
|
Start the program, specifying anything that might affect its behavior.
|
|
|
|
|
|
|
|
@item
|
|
|
|
Make the program stop on specified conditions.
|
|
|
|
|
|
|
|
@item
|
|
|
|
Examine what has happened, when the program has stopped, so that you
|
|
|
|
can see bugs happen.
|
|
|
|
|
|
|
|
@item
|
|
|
|
Change things in the program, so you can correct the effects of one bug
|
|
|
|
and go on to learn about another without having to recompile first.
|
|
|
|
@end enumerate
|
|
|
|
|
|
|
|
GDB can be used to debug programs written in C and C++. Pascal support
|
|
|
|
is being implemented, and Fortran support will be added when a GNU
|
|
|
|
Fortran compiler is written.
|
|
|
|
|
|
|
|
@menu
|
1989-09-30 00:00:00 +00:00
|
|
|
* License:: The GNU General Public License gives you permission
|
1989-01-31 17:56:40 +00:00
|
|
|
to redistribute GDB on certain terms; and also
|
|
|
|
explains that there is no warranty.
|
1989-09-30 00:00:00 +00:00
|
|
|
* User Interface:: GDB command syntax and input and output conventions.
|
1989-01-31 17:56:40 +00:00
|
|
|
* Files:: Specifying files for GDB to operate on.
|
|
|
|
* Options:: GDB arguments and options.
|
|
|
|
* Compilation::Compiling your program so you can debug it.
|
|
|
|
* Running:: Running your program under GDB.
|
|
|
|
* Stopping:: Making your program stop. Why it may stop. What to do then.
|
|
|
|
* Stack:: Examining your program's stack.
|
|
|
|
* Source:: Examining your program's source files.
|
|
|
|
* Data:: Examining data in your program.
|
|
|
|
* Symbols:: Examining the debugger's symbol table.
|
|
|
|
* Altering:: Altering things in your program.
|
|
|
|
* Sequences:: Canned command sequences for repeated use.
|
|
|
|
* Emacs:: Using GDB through GNU Emacs.
|
|
|
|
* Remote:: Remote kernel debugging across a serial line.
|
1990-12-19 13:30:35 +00:00
|
|
|
* GDB Bugs:: How to report bugs (if you want to get them fixed).
|
1989-01-31 17:56:40 +00:00
|
|
|
* Commands:: Index of GDB commands.
|
|
|
|
* Concepts:: Index of GDB concepts.
|
|
|
|
@end menu
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node License, User Interface, Top, Top
|
|
|
|
@unnumbered GNU GENERAL PUBLIC LICENSE
|
|
|
|
@center Version 1, February 1989
|
|
|
|
|
|
|
|
@display
|
|
|
|
Copyright @copyright{} 1989 Free Software Foundation, Inc.
|
|
|
|
675 Mass Ave, Cambridge, MA 02139, USA
|
|
|
|
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
|
|
of this license document, but changing it is not allowed.
|
|
|
|
@end display
|
|
|
|
|
|
|
|
@unnumberedsec Preamble
|
|
|
|
|
|
|
|
The license agreements of most software companies try to keep users
|
|
|
|
at the mercy of those companies. By contrast, our General Public
|
|
|
|
License is intended to guarantee your freedom to share and change free
|
|
|
|
software---to make sure the software is free for all its users. The
|
|
|
|
General Public License applies to the Free Software Foundation's
|
|
|
|
software and to any other program whose authors commit to using it.
|
|
|
|
You can use it for your programs, too.
|
|
|
|
|
|
|
|
When we speak of free software, we are referring to freedom, not
|
|
|
|
price. Specifically, the General Public License is designed to make
|
|
|
|
sure that you have the freedom to give away or sell copies of free
|
|
|
|
software, that you receive source code or can get it if you want it,
|
|
|
|
that you can change the software or use pieces of it in new free
|
|
|
|
programs; and that you know you can do these things.
|
|
|
|
|
|
|
|
To protect your rights, we need to make restrictions that forbid
|
|
|
|
anyone to deny you these rights or to ask you to surrender the rights.
|
|
|
|
These restrictions translate to certain responsibilities for you if you
|
|
|
|
distribute copies of the software, or if you modify it.
|
|
|
|
|
|
|
|
For example, if you distribute copies of a such a program, whether
|
|
|
|
gratis or for a fee, you must give the recipients all the rights that
|
|
|
|
you have. You must make sure that they, too, receive or can get the
|
|
|
|
source code. And you must tell them their rights.
|
|
|
|
|
|
|
|
We protect your rights with two steps: (1) copyright the software, and
|
|
|
|
(2) offer you this license which gives you legal permission to copy,
|
|
|
|
distribute and/or modify the software.
|
|
|
|
|
|
|
|
Also, for each author's protection and ours, we want to make certain
|
|
|
|
that everyone understands that there is no warranty for this free
|
|
|
|
software. If the software is modified by someone else and passed on, we
|
|
|
|
want its recipients to know that what they have is not the original, so
|
|
|
|
that any problems introduced by others will not reflect on the original
|
|
|
|
authors' reputations.
|
|
|
|
|
|
|
|
The precise terms and conditions for copying, distribution and
|
|
|
|
modification follow.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@iftex
|
|
|
|
@unnumberedsec TERMS AND CONDITIONS
|
|
|
|
@end iftex
|
|
|
|
@ifinfo
|
|
|
|
@center TERMS AND CONDITIONS
|
|
|
|
@end ifinfo
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@enumerate
|
|
|
|
@item
|
1989-09-30 00:00:00 +00:00
|
|
|
This License Agreement applies to any program or other work which
|
|
|
|
contains a notice placed by the copyright holder saying it may be
|
|
|
|
distributed under the terms of this General Public License. The
|
|
|
|
``Program'', below, refers to any such program or work, and a ``work based
|
|
|
|
on the Program'' means either the Program or any work containing the
|
|
|
|
Program or a portion of it, either verbatim or with modifications. Each
|
|
|
|
licensee is addressed as ``you''.
|
|
|
|
|
|
|
|
@item
|
|
|
|
You may copy and distribute verbatim copies of the Program's source
|
|
|
|
code as you receive it, in any medium, provided that you conspicuously and
|
|
|
|
appropriately publish on each copy an appropriate copyright notice and
|
|
|
|
disclaimer of warranty; keep intact all the notices that refer to this
|
|
|
|
General Public License and to the absence of any warranty; and give any
|
|
|
|
other recipients of the Program a copy of this General Public License
|
|
|
|
along with the Program. You may charge a fee for the physical act of
|
|
|
|
transferring a copy.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item
|
1989-09-30 00:00:00 +00:00
|
|
|
You may modify your copy or copies of the Program or any portion of
|
|
|
|
it, and copy and distribute such modifications under the terms of Paragraph
|
|
|
|
1 above, provided that you also do the following:
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
1989-09-30 00:00:00 +00:00
|
|
|
cause the modified files to carry prominent notices stating that
|
|
|
|
you changed the files and the date of any change; and
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item
|
|
|
|
cause the whole of any work that you distribute or publish, that
|
1989-09-30 00:00:00 +00:00
|
|
|
in whole or in part contains the Program or any part thereof, either
|
|
|
|
with or without modifications, to be licensed at no charge to all
|
|
|
|
third parties under the terms of this General Public License (except
|
|
|
|
that you may choose to grant warranty protection to some or all
|
|
|
|
third parties, at your option).
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item
|
1989-09-30 00:00:00 +00:00
|
|
|
If the modified program normally reads commands interactively when
|
|
|
|
run, you must cause it, when started running for such interactive use
|
|
|
|
in the simplest and most usual way, to print or display an
|
|
|
|
announcement including an appropriate copyright notice and a notice
|
|
|
|
that there is no warranty (or else, saying that you provide a
|
|
|
|
warranty) and that users may redistribute the program under these
|
|
|
|
conditions, and telling the user how to view a copy of this General
|
|
|
|
Public License.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item
|
1989-09-30 00:00:00 +00:00
|
|
|
You may charge a fee for the physical act of transferring a
|
|
|
|
copy, and you may at your option offer warranty protection in
|
|
|
|
exchange for a fee.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end itemize
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
Mere aggregation of another independent work with the Program (or its
|
1989-01-31 17:56:40 +00:00
|
|
|
derivative) on a volume of a storage or distribution medium does not bring
|
1989-09-30 00:00:00 +00:00
|
|
|
the other work under the scope of these terms.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item
|
1989-09-30 00:00:00 +00:00
|
|
|
You may copy and distribute the Program (or a portion or derivative of
|
|
|
|
it, under Paragraph 2) in object code or executable form under the terms of
|
|
|
|
Paragraphs 1 and 2 above provided that you also do one of the following:
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
|
|
accompany it with the complete corresponding machine-readable
|
|
|
|
source code, which must be distributed under the terms of
|
|
|
|
Paragraphs 1 and 2 above; or,
|
|
|
|
|
|
|
|
@item
|
|
|
|
accompany it with a written offer, valid for at least three
|
1989-09-30 00:00:00 +00:00
|
|
|
years, to give any third party free (except for a nominal charge
|
|
|
|
for the cost of distribution) a complete machine-readable copy of the
|
1989-01-31 17:56:40 +00:00
|
|
|
corresponding source code, to be distributed under the terms of
|
|
|
|
Paragraphs 1 and 2 above; or,
|
|
|
|
|
|
|
|
@item
|
|
|
|
accompany it with the information you received as to where the
|
|
|
|
corresponding source code may be obtained. (This alternative is
|
|
|
|
allowed only for noncommercial distribution and only if you
|
|
|
|
received the program in object code or executable form alone.)
|
|
|
|
@end itemize
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
Source code for a work means the preferred form of the work for making
|
|
|
|
modifications to it. For an executable file, complete source code means
|
|
|
|
all the source code for all modules it contains; but, as a special
|
|
|
|
exception, it need not include source code for modules which are standard
|
|
|
|
libraries that accompany the operating system on which the executable
|
|
|
|
file runs, or for standard header files or definitions files that
|
|
|
|
accompany that operating system.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item
|
1989-09-30 00:00:00 +00:00
|
|
|
You may not copy, modify, sublicense, distribute or transfer the
|
|
|
|
Program except as expressly provided under this General Public License.
|
|
|
|
Any attempt otherwise to copy, modify, sublicense, distribute or transfer
|
|
|
|
the Program is void, and will automatically terminate your rights to use
|
|
|
|
the Program under this License. However, parties who have received
|
|
|
|
copies, or rights to use copies, from you under this General Public
|
|
|
|
License will not have their licenses terminated so long as such parties
|
|
|
|
remain in full compliance.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item
|
1989-09-30 00:00:00 +00:00
|
|
|
By copying, distributing or modifying the Program (or any work based
|
|
|
|
on the Program) you indicate your acceptance of this license to do so,
|
|
|
|
and all its terms and conditions.
|
|
|
|
|
|
|
|
@item
|
|
|
|
Each time you redistribute the Program (or any work based on the
|
|
|
|
Program), the recipient automatically receives a license from the original
|
|
|
|
licensor to copy, distribute or modify the Program subject to these
|
|
|
|
terms and conditions. You may not impose any further restrictions on the
|
|
|
|
recipients' exercise of the rights granted herein.
|
|
|
|
|
|
|
|
@item
|
|
|
|
The Free Software Foundation may publish revised and/or new versions
|
|
|
|
of the General Public License from time to time. Such new versions will
|
|
|
|
be similar in spirit to the present version, but may differ in detail to
|
|
|
|
address new problems or concerns.
|
|
|
|
|
|
|
|
Each version is given a distinguishing version number. If the Program
|
|
|
|
specifies a version number of the license which applies to it and ``any
|
|
|
|
later version'', you have the option of following the terms and conditions
|
|
|
|
either of that version or of any later version published by the Free
|
|
|
|
Software Foundation. If the Program does not specify a version number of
|
|
|
|
the license, you may choose any version ever published by the Free Software
|
|
|
|
Foundation.
|
|
|
|
|
|
|
|
@item
|
|
|
|
If you wish to incorporate parts of the Program into other free
|
|
|
|
programs whose distribution conditions are different, write to the author
|
|
|
|
to ask for permission. For software which is copyrighted by the Free
|
|
|
|
Software Foundation, write to the Free Software Foundation; we sometimes
|
|
|
|
make exceptions for this. Our decision will be guided by the two goals
|
|
|
|
of preserving the free status of all derivatives of our free software and
|
|
|
|
of promoting the sharing and reuse of software generally.
|
|
|
|
|
|
|
|
@iftex
|
|
|
|
@heading NO WARRANTY
|
|
|
|
@end iftex
|
|
|
|
@ifinfo
|
|
|
|
@center NO WARRANTY
|
|
|
|
@end ifinfo
|
|
|
|
|
|
|
|
@item
|
|
|
|
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
|
|
|
|
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
|
|
|
|
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
|
|
|
|
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
|
|
|
|
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
|
|
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
|
|
|
|
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
|
|
|
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
|
|
|
|
REPAIR OR CORRECTION.
|
|
|
|
|
|
|
|
@item
|
|
|
|
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
|
|
|
|
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
|
|
|
|
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
|
|
|
|
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
|
|
|
|
ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
|
|
|
|
LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
|
|
|
|
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
|
|
|
|
WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
|
|
|
|
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end enumerate
|
|
|
|
|
|
|
|
@iftex
|
1989-09-30 00:00:00 +00:00
|
|
|
@heading END OF TERMS AND CONDITIONS
|
1989-01-31 17:56:40 +00:00
|
|
|
@end iftex
|
1989-09-30 00:00:00 +00:00
|
|
|
@ifinfo
|
|
|
|
@center END OF TERMS AND CONDITIONS
|
|
|
|
@end ifinfo
|
|
|
|
|
|
|
|
@page
|
|
|
|
@unnumberedsec Appendix: How to Apply These Terms to Your New Programs
|
|
|
|
|
|
|
|
If you develop a new program, and you want it to be of the greatest
|
|
|
|
possible use to humanity, the best way to achieve this is to make it
|
|
|
|
free software which everyone can redistribute and change under these
|
|
|
|
terms.
|
|
|
|
|
|
|
|
To do so, attach the following notices to the program. It is safest to
|
|
|
|
attach them to the start of each source file to most effectively convey
|
|
|
|
the exclusion of warranty; and each file should have at least the
|
|
|
|
``copyright'' line and a pointer to where the full notice is found.
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
@var{one line to give the program's name and a brief idea of what it does.}
|
|
|
|
Copyright (C) 19@var{yy} @var{name of author}
|
|
|
|
|
|
|
|
This program is free software; you can redistribute it and/or modify
|
|
|
|
it under the terms of the GNU General Public License as published by
|
|
|
|
the Free Software Foundation; either version 1, or (at your option)
|
|
|
|
any later version.
|
|
|
|
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
GNU General Public License for more details.
|
|
|
|
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
|
|
along with this program; if not, write to the Free Software
|
|
|
|
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
Also add information on how to contact you by electronic and paper mail.
|
|
|
|
|
|
|
|
If the program is interactive, make it output a short notice like this
|
|
|
|
when it starts in an interactive mode:
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
|
|
|
|
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
|
|
|
|
This is free software, and you are welcome to redistribute it
|
|
|
|
under certain conditions; type `show c' for details.
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
The hypothetical commands `show w' and `show c' should show the
|
|
|
|
appropriate parts of the General Public License. Of course, the
|
|
|
|
commands you use may be called something other than `show w' and `show
|
|
|
|
c'; they could even be mouse-clicks or menu items---whatever suits your
|
|
|
|
program.
|
|
|
|
|
|
|
|
You should also get your employer (if you work as a programmer) or your
|
|
|
|
school, if any, to sign a ``copyright disclaimer'' for the program, if
|
|
|
|
necessary. Here a sample; alter the names:
|
|
|
|
|
|
|
|
@example
|
|
|
|
Yoyodyne, Inc., hereby disclaims all copyright interest in the
|
|
|
|
program `Gnomovision' (a program to direct compilers to make passes
|
|
|
|
at assemblers) written by James Hacker.
|
|
|
|
|
|
|
|
@var{signature of Ty Coon}, 1 April 1989
|
|
|
|
Ty Coon, President of Vice
|
|
|
|
@end example
|
|
|
|
|
|
|
|
That's all there is to it!
|
|
|
|
|
|
|
|
@node User Interface, Files, License, Top
|
|
|
|
@chapter GDB Input and Output Conventions
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
GDB is invoked with the shell command @samp{gdb}. Once started, it reads
|
|
|
|
commands from the terminal until you tell it to exit.
|
|
|
|
|
|
|
|
A GDB command is a single line of input. There is no limit on how long
|
|
|
|
it can be. It starts with a command name, which is followed by arguments
|
1989-09-30 00:00:00 +00:00
|
|
|
whose meaning depends on the command name. For example, the command
|
|
|
|
@samp{step} accepts an argument which is the number of times to step,
|
|
|
|
as in @samp{step 5}. You can also use the @samp{step} command with
|
|
|
|
no arguments. Some command names do not allow any arguments.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex abbreviation
|
1989-01-31 17:56:40 +00:00
|
|
|
GDB command names may always be abbreviated if the abbreviation is
|
|
|
|
unambiguous. Sometimes even ambiguous abbreviations are allowed; for
|
|
|
|
example, @samp{s} is specially defined as equivalent to @samp{step}
|
|
|
|
even though there are other commands whose names start with @samp{s}.
|
|
|
|
Possible command abbreviations are often stated in the documentation
|
|
|
|
of the individual commands.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex repeating commands
|
1989-01-31 17:56:40 +00:00
|
|
|
A blank line as input to GDB means to repeat the previous command verbatim.
|
|
|
|
Certain commands do not allow themselves to be repeated this way; these are
|
|
|
|
commands for which unintentional repetition might cause trouble and which
|
|
|
|
you are unlikely to want to repeat. Certain others (@samp{list} and
|
|
|
|
@samp{x}) act differently when repeated because that is more useful.
|
|
|
|
|
|
|
|
A line of input starting with @samp{#} is a comment; it does nothing.
|
|
|
|
This is useful mainly in command files (@xref{Command Files}).
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex prompt
|
|
|
|
GDB indicates its readiness to read a command by printing a string
|
|
|
|
called the @dfn{prompt}. This string is normally @samp{(gdb)}. You can
|
|
|
|
change the prompt string with the @samp{set prompt} command. For
|
|
|
|
instance, when debugging GDB with GDB, it is useful to change the prompt
|
|
|
|
in one of the GDBs so that you tell which one you are talking to.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@table @code
|
1990-12-19 13:30:35 +00:00
|
|
|
@item set prompt @var{newprompt}
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex set prompt
|
1990-11-09 18:30:56 +00:00
|
|
|
Directs GDB to use @samp{newprompt} as its prompt string henceforth.
|
|
|
|
@kindex show prompt
|
|
|
|
@item show prompt
|
|
|
|
Prints the line: Gdb's prompt is: @samp{your-prompt}
|
1989-01-31 17:56:40 +00:00
|
|
|
@end table
|
|
|
|
|
|
|
|
@cindex exiting GDB
|
|
|
|
@kindex quit
|
1990-12-19 13:30:35 +00:00
|
|
|
To exit GDB, use the @samp{quit} command (abbreviated @samp{q}), or type
|
|
|
|
an end-of-file character (usually @ctrl{d}). An interrupt (often
|
|
|
|
@ctrl{c}) will not exit from GDB, but rather will terminate the action
|
1989-01-31 17:56:40 +00:00
|
|
|
of any GDB command that is in progress and return to GDB command level.
|
1990-12-19 13:30:35 +00:00
|
|
|
It is safe to type the interrupt character at any time because GDB does
|
|
|
|
not allow it to take effect until a time when it is safe.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1990-11-09 18:30:56 +00:00
|
|
|
@cindex readline
|
|
|
|
@cindex command line editing
|
|
|
|
@cindex history substitution
|
|
|
|
GDB now reads its input commands via the @code{readline} interface.
|
1990-12-19 13:30:35 +00:00
|
|
|
This GNU library provides consistant behaviour for programs which
|
|
|
|
provide a command line interface to the user. From the point
|
|
|
|
of view of the user, the advantages are @samp{emacs}-style or @samp{vi}-style
|
1990-11-09 18:30:56 +00:00
|
|
|
inline editing of commands, @samp{csh}-like history substitution,
|
|
|
|
and a storage and recall of command history across debugging sessions.
|
|
|
|
|
|
|
|
You may control the behavior of command line editing in GDB with the
|
|
|
|
following commands:
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@kindex set editing
|
|
|
|
@item set editing
|
|
|
|
@itemx set editing on
|
|
|
|
Enable command line editing (enabled by default).
|
|
|
|
|
|
|
|
@item set editing off
|
|
|
|
Disable command line editing.
|
|
|
|
|
|
|
|
@kindex info editing
|
|
|
|
@item info editing
|
|
|
|
Display the current settings relating to command line editing, and also
|
|
|
|
display the last ten commands in the command history.
|
|
|
|
|
|
|
|
@item info editing @var{n}
|
|
|
|
Print ten commands centered on command number @var{n}.
|
|
|
|
|
|
|
|
@item info editing +
|
|
|
|
Print ten commands just after the commands last printed.
|
|
|
|
|
|
|
|
@kindex set history file
|
1990-12-19 13:30:35 +00:00
|
|
|
@item set history file @var{filename}
|
1990-11-09 18:30:56 +00:00
|
|
|
Set the name of the GDB command history file to @samp{filename}. This is
|
|
|
|
the file from which GDB will read an initial command history
|
|
|
|
list or to which it will write this list when it exits. This list is
|
|
|
|
accessed through history expansion or through the history
|
|
|
|
command editing characters listed below. This file defaults to the
|
|
|
|
value of the environmental variable @code{GDBHISTFILE}, or to
|
|
|
|
@code{./.gdb_history} if this variable is not set.
|
|
|
|
|
|
|
|
@kindex set history write
|
|
|
|
@item set history write
|
|
|
|
@itemx set history write on
|
1990-12-19 13:30:35 +00:00
|
|
|
Make GDB record command history in a file, whose name may be specified with the
|
|
|
|
@samp{set history file} command. By default, this option is disabled.
|
1990-11-09 18:30:56 +00:00
|
|
|
|
|
|
|
@item set history write off
|
1990-12-19 13:30:35 +00:00
|
|
|
Make GDB stop recording command history in a file.
|
1990-11-09 18:30:56 +00:00
|
|
|
|
|
|
|
@kindex set history size
|
|
|
|
@item set history size @var{size}
|
|
|
|
Set the number of commands which GDB will keep in its history list.
|
|
|
|
This defaults to the value of the environmental variable
|
|
|
|
@code{HISTSIZE}, or to 256 if this variable is not set.
|
1990-12-17 18:23:17 +00:00
|
|
|
@end table
|
1990-11-09 18:30:56 +00:00
|
|
|
|
|
|
|
@cindex history expansion
|
|
|
|
|
|
|
|
The commands to control history expansion are:
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
|
|
|
|
@kindex set history expansion
|
|
|
|
@item set history expansion on
|
|
|
|
@itemx set history expansion
|
1990-12-19 13:30:35 +00:00
|
|
|
Enable history expansion. History expansion is off by default.
|
1990-11-09 18:30:56 +00:00
|
|
|
|
|
|
|
@item set history expansion off
|
1990-12-19 13:30:35 +00:00
|
|
|
Disable history expansion.
|
1990-11-09 18:30:56 +00:00
|
|
|
|
|
|
|
@end table
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
Because of the additional meaning of `@code{!}' to GDB (as the logical
|
|
|
|
not operator in C), history expansion is off by default. If you decide
|
|
|
|
to enable history expansion with the @samp{set history expansion on}
|
|
|
|
command, you will need to follow @samp{!} (when it is part of an
|
|
|
|
expression) with a space or a tab to prevent it from being expanded.
|
|
|
|
|
|
|
|
|
1990-11-09 18:30:56 +00:00
|
|
|
The @code{readline} code comes with more complete documentation of
|
|
|
|
editing and history expansion features. Users unfamiliar with @samp{emacs}
|
1990-12-19 13:30:35 +00:00
|
|
|
or @samp{vi} may wish to read it. @xref{Command Line Editing}.
|
1990-11-09 18:30:56 +00:00
|
|
|
|
|
|
|
Occasionally it is useful to execute a shell command from within GDB.
|
|
|
|
This can be done with the @samp{shell} command.
|
|
|
|
|
|
|
|
@table @code
|
1990-12-19 13:30:35 +00:00
|
|
|
@item shell @var{command string}
|
1990-11-09 18:30:56 +00:00
|
|
|
@kindex shell
|
|
|
|
@cindex shell escape
|
1990-12-19 13:30:35 +00:00
|
|
|
Directs GDB to invoke an inferior shell to execute @var{command string}.
|
1990-11-09 18:30:56 +00:00
|
|
|
The environment variable @code{SHELL} is used if it exists, otherwise GDB
|
|
|
|
uses @samp{/bin/sh}.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@item make @var{target}
|
|
|
|
@kindex make
|
|
|
|
@cindex calling make
|
|
|
|
Causes GDB to execute an inferior @code{make} program with the specified
|
|
|
|
arguments. This is equivalent to @samp{shell make @var{target}}.
|
|
|
|
@end table
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex screen size
|
|
|
|
@cindex pauses in output
|
|
|
|
Certain commands to GDB may produce large amounts of information output
|
|
|
|
to the screen. To help you read all of it, GDB pauses and asks you for
|
|
|
|
input at the end of each page of output. Type @key{RET} when you want
|
|
|
|
to continue the output. Normally GDB knows the size of the screen from
|
1990-12-19 13:30:35 +00:00
|
|
|
the termcap data base together with the value of the @code{TERM}
|
|
|
|
environment variable and the @code{stty rows} and @code{stty cols}
|
|
|
|
settings. If this is not correct, you can override it with
|
1990-11-09 18:30:56 +00:00
|
|
|
the @samp{set screen-height} and @samp{set screen-width} commands:
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
@table @code
|
1990-11-09 18:30:56 +00:00
|
|
|
@item set screen-height @var{lpp}
|
|
|
|
@item set screen-width @var{cpl}
|
|
|
|
@kindex set screen-height
|
|
|
|
@kindex set screen-width
|
|
|
|
Specify a screen height of @var{lpp} lines and a screen width of
|
|
|
|
@var{cpl} characters.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
If you specify a height of zero lines, GDB will not pause during output
|
|
|
|
no matter how long the output is. This is useful if output is to a file
|
|
|
|
or to an editor buffer.
|
|
|
|
@end table
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
By default, GDB is silent about its inner workings. If you are running
|
|
|
|
on a slow machine, you may want to use the @samp{set verbose} command.
|
|
|
|
It will make GDB tell you when it does a lengthy internal operation, so
|
|
|
|
you won't think it has crashed.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
Currently, the messages controlled by @samp{set verbose} are those which
|
|
|
|
announce that the symbol table for a source file is being read
|
|
|
|
(@pxref{File Commands}, in the description of the command
|
|
|
|
@samp{symbol-file}).
|
|
|
|
@c The following is the right way to do it, but emacs 18.55 doesn't support
|
|
|
|
@c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo
|
|
|
|
@c is released.
|
|
|
|
@ignore
|
|
|
|
see @samp{symbol-file} in @ref{File Commands}).
|
|
|
|
@end ignore
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@table @code
|
|
|
|
@kindex set verbose
|
|
|
|
@item set verbose on
|
|
|
|
Enables GDB's output of certain informational messages.
|
|
|
|
|
|
|
|
@item set verbose off
|
|
|
|
Disables GDB's output of certain informational messages.
|
|
|
|
|
|
|
|
@end table
|
|
|
|
|
|
|
|
By default, GDB asks what sometimes seem to be a lot of stupid
|
|
|
|
questions. For example, if you try to run a program which is already
|
|
|
|
running:
|
|
|
|
@example
|
|
|
|
|
|
|
|
(gdb) run
|
|
|
|
The program being debugged has been started already.
|
|
|
|
Start it from the beginning? (y or n)
|
|
|
|
@end example
|
|
|
|
|
|
|
|
If you're willing to unflinchingly face the consequences of your own
|
|
|
|
commands, you can disable this ``feature'':
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@kindex set stupidity
|
|
|
|
@cindex flinching
|
|
|
|
@cindex verifying commands with serious side effects
|
|
|
|
@item set stupidity off
|
|
|
|
Disables stupid questions.
|
|
|
|
|
|
|
|
@item set stupidity on
|
|
|
|
Enables stupid questions (the default).
|
|
|
|
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Files, Compilation, User Interface, Top
|
1989-01-31 17:56:40 +00:00
|
|
|
@chapter Specifying GDB's Files
|
|
|
|
|
|
|
|
@cindex core dump file
|
|
|
|
@cindex executable file
|
|
|
|
@cindex symbol table
|
1989-09-30 00:00:00 +00:00
|
|
|
GDB needs to know the file name of the program to be debugged, both in
|
|
|
|
order to read its symbol table and in order to start the program. To
|
|
|
|
debug a core dump of a previous run, GDB must be told the file name of
|
|
|
|
the core dump.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@menu
|
|
|
|
* Arguments: File Arguments. Specifying files with arguments
|
|
|
|
(when you start GDB).
|
|
|
|
* Commands: File Commands. Specifying files with GDB commands.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node File Arguments, File Commands, Files, Files
|
|
|
|
@section Specifying Files with Arguments
|
|
|
|
|
|
|
|
The usual way to specify the executable and core dump file names is with
|
|
|
|
two command arguments given when you start GDB. The first argument is used
|
|
|
|
as the file for execution and symbols, and the second argument (if any) is
|
|
|
|
used as the core dump file name. Thus,
|
|
|
|
|
|
|
|
@example
|
|
|
|
gdb progm core
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
specifies @file{progm} as the executable program and @file{core} as a core
|
|
|
|
dump file to examine. (You do not need to have a core dump file if what
|
|
|
|
you plan to do is debug the program interactively.)
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@xref{Options}, for full information on options and arguments for
|
|
|
|
invoking GDB.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@node File Commands,, File Arguments, Files
|
|
|
|
@section Specifying Files with Commands
|
|
|
|
|
|
|
|
Usually you specify the files for GDB to work with by giving arguments when
|
|
|
|
you invoke GDB. But occasionally it is necessary to change to a different
|
|
|
|
file during a GDB session. Or you may run GDB and forget to specify the
|
|
|
|
files you want to use. In these situations the GDB commands to specify new
|
|
|
|
files are useful.
|
|
|
|
|
|
|
|
@table @code
|
1990-12-19 13:30:35 +00:00
|
|
|
@item file @var{filename}
|
|
|
|
@kindex file
|
|
|
|
Use @var{file} as the program to be debugged. It is read for its
|
|
|
|
symbols, for getting the contents of pure memory, and it is the program
|
|
|
|
executed when you use the @samp{run} command. If you do not specify a
|
|
|
|
directory and the file is not found in GDB's working directory, GDB will
|
|
|
|
use the environment variable @code{PATH} as a list of directories to
|
|
|
|
search, just as the shell does when looking for a program to run.
|
|
|
|
|
|
|
|
@samp{file} with no argument makes both executable file and symbol
|
|
|
|
table become unspecified.
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@item exec-file @var{filename}
|
|
|
|
@kindex exec-file
|
1990-12-19 13:30:35 +00:00
|
|
|
Specify that the program to be run (but not the symbol table) is found
|
|
|
|
in @var{filename}. GDB will search the environment variable @code{PATH}
|
|
|
|
if necessary to locate the program.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item symbol-file @var{filename}
|
|
|
|
@kindex symbol-file
|
1990-12-19 13:30:35 +00:00
|
|
|
Read symbol table information from file @var{filename}. @code{PATH} is
|
|
|
|
searched when necessary. Use the @samp{file} command to get both symbol
|
|
|
|
table and program to run from the same file.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@samp{symbol-file} with no argument clears out GDB's symbol table.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
On some systems, the @samp{symbol-file} command does not actually read
|
|
|
|
the symbol table in full right away. Instead, it scans the symbol table
|
|
|
|
quickly to find which source files and which symbols are present. The
|
|
|
|
details are read later, one source file at a time, when they are needed.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
The purpose of this two-stage reading strategy is to make GDB start up
|
1990-12-19 13:30:35 +00:00
|
|
|
faster. For the most part, it is invisible except for occasional pauses
|
|
|
|
while the symbol table details for a particular source file are being
|
|
|
|
read. (The @samp{set verbose} command can turn these pauses into
|
|
|
|
messages if desired. @xref{User Interface}).
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
When the symbol table is stored in COFF format, @samp{symbol-file} does
|
|
|
|
read the symbol table data in full right away. We haven't bothered to
|
1990-12-19 13:30:35 +00:00
|
|
|
implement the two-stage strategy for COFF yet.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@item core @var{filename}
|
|
|
|
@kindex core
|
1989-01-31 17:56:40 +00:00
|
|
|
Specify the whereabouts of a core dump file to be used as the
|
|
|
|
``contents of memory''. Note that the core dump contains only the
|
|
|
|
writable parts of memory; the read-only parts must come from the
|
|
|
|
executable file.
|
|
|
|
|
|
|
|
@samp{core-file} with no argument specifies that no core file is
|
|
|
|
to be used.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
Note that the core file is ignored when your program is actually running
|
|
|
|
under GDB. So, if you have been running the program and you wish to
|
|
|
|
debug a core file instead, you must kill the subprocess in which the
|
|
|
|
program is running. To do this, use the @samp{kill} command
|
|
|
|
(@pxref{Kill Process}).
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@item add-file @var{filename} @var{address}
|
1990-12-19 13:30:35 +00:00
|
|
|
@itemx load @var{filename} @var{address}
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex add-file
|
1990-12-19 13:30:35 +00:00
|
|
|
@kindex load
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex dynamic linking
|
|
|
|
The @samp{add-file} command reads additional symbol table information
|
|
|
|
from the file @var{filename}. You would use this when that file has
|
|
|
|
been dynamically loaded into the program that is running. @var{address}
|
|
|
|
should be the memory address at which the file has been loaded; GDB cannot
|
|
|
|
figure this out for itself.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
When debugging with some targets (@pxref{Targets}), this command will
|
|
|
|
also cause the file to be dynamically loaded into the target system.
|
|
|
|
@comment FIXME: "some" is obnoxious. Currently this is only VxWorks.
|
|
|
|
@comment ---pesch 18dec1990
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
The symbol table of the file @var{filename} is added to the symbol table
|
|
|
|
originally read with the @samp{symbol-file} command. You can use the
|
|
|
|
@samp{add-file} command any number of times; the new symbol data thus
|
|
|
|
read keeps adding to the old. The @samp{symbol-file} command forgets
|
1990-12-19 13:30:35 +00:00
|
|
|
all the symbol data GDB has read.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item info files
|
|
|
|
@kindex info files
|
|
|
|
Print the names of the executable and core dump files currently in
|
1990-12-19 13:30:35 +00:00
|
|
|
use by GDB, and the file from which symbols were loaded, as well as the
|
|
|
|
stack of current targets (@pxref{Targets}).
|
|
|
|
|
|
|
|
@end table
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
While all three file-specifying commands allow both absolute and relative
|
|
|
|
file names as arguments, GDB always converts the file name to an absolute
|
|
|
|
one and remembers it that way.
|
|
|
|
|
|
|
|
The @samp{symbol-file} command causes GDB to forget the contents of its
|
|
|
|
convenience variables, the value history, and all breakpoints and
|
|
|
|
auto-display expressions. This is because they may contain pointers to the
|
|
|
|
internal data recording symbols and data types, which are part of the old
|
|
|
|
symbol table data being discarded inside GDB.
|
|
|
|
|
1990-11-09 18:30:56 +00:00
|
|
|
@kindex shared-library
|
|
|
|
@kindex share
|
|
|
|
@cindex shared libraries
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
GDB supports the SunOS shared library format. Symbols from a shared
|
1990-11-09 18:30:56 +00:00
|
|
|
library cannot be referenced before the shared library has been linked
|
|
|
|
with the program. (That is to say, after one types @samp{run} and
|
1990-12-19 13:30:35 +00:00
|
|
|
the function @code{main()} has been entered; or when examining core
|
|
|
|
files.) Once the shared library has been linked in, you can use the
|
|
|
|
following commands:
|
1990-11-09 18:30:56 +00:00
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@table @code
|
|
|
|
@item sharedlibrary @var{regex}
|
|
|
|
@itemx share @var{regex}
|
1990-11-09 18:30:56 +00:00
|
|
|
Load shared object library symbols for files matching a UNIX regular
|
|
|
|
expresssion.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@item share
|
|
|
|
@itemx sharedlibrary
|
1990-11-09 18:30:56 +00:00
|
|
|
Load symbols for all shared libraries.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@item info share
|
|
|
|
@itemx info sharedlibrary
|
1990-11-09 18:30:56 +00:00
|
|
|
@kindex info sharedlibrary
|
1990-12-19 13:30:35 +00:00
|
|
|
@kindex info share
|
1990-11-09 18:30:56 +00:00
|
|
|
Print the names of the shared libraries which are currently loaded.
|
1990-12-17 18:23:17 +00:00
|
|
|
@end table
|
1990-11-09 18:30:56 +00:00
|
|
|
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@node Compilation, Targets, Files, Top
|
1989-01-31 17:56:40 +00:00
|
|
|
@chapter Compiling Your Program for Debugging
|
|
|
|
|
|
|
|
In order to debug a program effectively, you need to ask for debugging
|
|
|
|
information when you compile it. This information in the object file
|
|
|
|
describes the data type of each variable or function and the correspondence
|
|
|
|
between source line numbers and addresses in the executable code.
|
|
|
|
|
|
|
|
To request debugging information, specify the @samp{-g} option when you run
|
|
|
|
the compiler.
|
|
|
|
|
|
|
|
The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options
|
|
|
|
together. This means that you cannot ask for optimization if you ask for
|
|
|
|
debugger information.
|
|
|
|
|
|
|
|
The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it
|
|
|
|
possible to debug optimized code. We recommend that you @emph{always} use
|
|
|
|
@samp{-g} whenever you compile a program. You may think the program is
|
|
|
|
correct, but there's no sense in pushing your luck.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
Some things do not work as well with @samp{-g -O} as with just
|
|
|
|
@samp{-g}, particularly on machines with instruction scheduling. If in
|
|
|
|
doubt, recompile with @samp{-g} alone, and if this fixes the problem,
|
|
|
|
please report it as a bug (including a test case---@pxref{GDB Bugs}).
|
|
|
|
|
|
|
|
Older versions of the GNU C compiler, GCC, permitted a variant option
|
|
|
|
@samp{-gg} for debugging information. GDB no longer supports this format;
|
|
|
|
if your GNU C compiler has this option, do not use it.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-11-05 21:02:37 +00:00
|
|
|
@ignore
|
|
|
|
@comment As far as I know, there are no cases in which GDB will
|
|
|
|
@comment produce strange output in this case. (but no promises).
|
1989-09-30 00:00:00 +00:00
|
|
|
If your program includes archives made with the @code{ar} program, and
|
|
|
|
if the object files used as input to @code{ar} were compiled without the
|
|
|
|
@samp{-g} option and have names longer than 15 characters, GDB will get
|
|
|
|
confused reading the program's symbol table. No error message will be
|
|
|
|
given, but GDB may behave strangely. The reason for this problem is a
|
|
|
|
deficiency in the Unix archive file format, which cannot represent file
|
|
|
|
names longer than 15 characters.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
To avoid this problem, compile the archive members with the @samp{-g}
|
|
|
|
option or use shorter file names. Alternatively, use a version of GNU
|
|
|
|
@code{ar} dated more recently than August 1989.
|
1989-11-05 21:02:37 +00:00
|
|
|
@end ignore
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@node Targets, Running, Compilation, Top
|
|
|
|
@chapter Specifying a Debugging Target
|
|
|
|
@cindex debugging target
|
|
|
|
@kindex target
|
|
|
|
Often, you will be able to run GDB in the same host environment as the
|
|
|
|
program you are debugging; in that case, the debugging target is
|
|
|
|
specified as a side effect of the @samp{file} or @samp{core} commands.
|
|
|
|
When you need more flexibility---for example, running GDB on a
|
|
|
|
physically separate host, controlling standalone systems over a
|
|
|
|
serial port, or realtime systems over a TCP/IP connection---you can use
|
|
|
|
the @samp{target} command.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item target @var{type} @var{parameters}
|
|
|
|
Connects the GDB host environment to a target machine or process. A
|
|
|
|
target is typically a protocol for talking to debugging facilities. You
|
|
|
|
use the argument @var{type} to specify the type or protocol of the
|
|
|
|
target machine; for example, @samp{target child} for Unix child processes, or
|
|
|
|
@samp{target vxworks} for a TCP/IP link to a VxWorks system.
|
|
|
|
|
|
|
|
Further @var{parameters} are interpreted by the target protocol, but
|
|
|
|
typically include things like device names or host names to connect
|
|
|
|
with, process numbers, and baud rates. Executing
|
|
|
|
@example
|
|
|
|
target @var{type}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent{}(without any parameters) will issue a message about what
|
|
|
|
parameters are required for that target type.
|
|
|
|
|
|
|
|
@end table
|
|
|
|
|
|
|
|
Targets are managed as a stack, so that you may (for example) specify
|
|
|
|
a core file as a target without abandoning a running program; when
|
|
|
|
you're done with the core file, you can return to the previous target
|
|
|
|
using @samp{detach}. The related command @samp{attach} provides you
|
|
|
|
with an alternative way of stacking a new target. @xref{Attach}.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item info targets
|
|
|
|
Displays the names of all targets available.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
To display the targets currently stacked, use the @samp{info files}
|
|
|
|
command (@pxref{File Commands}).
|
|
|
|
|
|
|
|
@node Running, Stopping, Targets, Top
|
1989-01-31 17:56:40 +00:00
|
|
|
@chapter Running Your Program Under GDB
|
|
|
|
|
|
|
|
@cindex running
|
|
|
|
@kindex run
|
1990-12-19 13:30:35 +00:00
|
|
|
To start your program under GDB, use the @samp{run} command. Except on
|
|
|
|
VxWorks, the program must already have been specified using the
|
|
|
|
@samp{file} or @samp{exec-file} command, or with an argument to GDB
|
|
|
|
(@pxref{Files}); what @samp{run} does is create an inferior process,
|
|
|
|
load the program into it, and set it in motion.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
The execution of a program is affected by certain information it
|
|
|
|
receives from its superior. GDB provides ways to specify this
|
|
|
|
information, which you must do @i{before} starting the program. (You
|
|
|
|
can change it after starting the program, but such changes do not affect
|
|
|
|
the program unless you start it over again.) This information may be
|
|
|
|
divided into three categories:
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@table @asis
|
|
|
|
@item The @i{arguments.}
|
|
|
|
You specify the arguments to give the program as the arguments of the
|
1989-09-30 00:00:00 +00:00
|
|
|
@samp{run} command.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item The @i{environment.}
|
|
|
|
The program normally inherits its environment from GDB, but you can
|
|
|
|
use the GDB commands @samp{set environment} and
|
|
|
|
@samp{unset environment} to change parts of the environment that will
|
|
|
|
be given to the program.@refill
|
|
|
|
|
|
|
|
@item The @i{working directory.}
|
|
|
|
The program inherits its working directory from GDB. You can set GDB's
|
|
|
|
working directory with the @samp{cd} command in GDB.
|
|
|
|
@end table
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
When you issue the @samp{run} command, your program begins to execute
|
|
|
|
immediately. @xref{Stopping}, for discussion of how to arrange for your
|
|
|
|
program to stop.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
Note that once your program has been started by the @samp{run} command,
|
|
|
|
you may evaluate expressions that involve calls to functions in the
|
1990-12-19 13:30:35 +00:00
|
|
|
inferior, using the @samp{print} or @samp{call} commands. @xref{Data}.
|
|
|
|
|
|
|
|
If your program's timestamp has changed since the last time GDB read its
|
|
|
|
symbols, GDB will discard its symbol table and re-read it from your
|
|
|
|
program. In this process, it tries to retain your current breakpoints.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@menu
|
|
|
|
* Arguments:: Specifying the arguments for your program.
|
|
|
|
* Environment:: Specifying the environment for your program.
|
|
|
|
* Working Directory:: Specifying the working directory for giving
|
|
|
|
to your program when it is run.
|
|
|
|
* Input/Output:: Specifying the program's standard input and output.
|
|
|
|
* Attach:: Debugging a process started outside GDB.
|
1989-09-30 00:00:00 +00:00
|
|
|
* Kill Process:: Getting rid of the child process running your program.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Arguments, Environment, Running, Running
|
|
|
|
@section Your Program's Arguments
|
|
|
|
|
|
|
|
@cindex arguments (to your program)
|
1989-09-30 00:00:00 +00:00
|
|
|
The arguments to your program are specified by the arguments of the
|
1989-01-31 17:56:40 +00:00
|
|
|
@samp{run} command. They are passed to a shell, which expands wildcard
|
|
|
|
characters and performs redirection of I/O, and thence to the program.
|
|
|
|
|
|
|
|
@samp{run} with no arguments uses the same arguments used by the previous
|
|
|
|
@samp{run}.
|
|
|
|
|
|
|
|
@kindex set args
|
|
|
|
The command @samp{set args} can be used to specify the arguments to be used
|
|
|
|
the next time the program is run. If @samp{set args} has no arguments, it
|
|
|
|
means to use no arguments the next time the program is run. If you have
|
|
|
|
run your program with arguments and want to run it again with no arguments,
|
|
|
|
this is the only way to do so.
|
|
|
|
|
|
|
|
@node Environment, Working Directory, Arguments, Running
|
|
|
|
@section Your Program's Environment
|
|
|
|
|
|
|
|
@cindex environment (of your program)
|
|
|
|
The @dfn{environment} consists of a set of @dfn{environment variables} and
|
|
|
|
their values. Environment variables conventionally record such things as
|
|
|
|
your user name, your home directory, your terminal type, and your search
|
|
|
|
path for programs to run. Usually you set up environment variables with
|
|
|
|
the shell and they are inherited by all the other programs you run. When
|
|
|
|
debugging, it can be useful to try running the program with different
|
|
|
|
environments without having to start the debugger over again.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item info environment @var{varname}
|
|
|
|
@kindex info environment
|
|
|
|
Print the value of environment variable @var{varname} to be given to
|
|
|
|
your program when it is started. This command can be abbreviated
|
|
|
|
@samp{i env @var{varname}}.
|
|
|
|
|
|
|
|
@item info environment
|
|
|
|
Print the names and values of all environment variables to be given to
|
|
|
|
your program when it is started. This command can be abbreviated
|
|
|
|
@samp{i env}.
|
|
|
|
|
|
|
|
@item set environment @var{varname} @var{value}
|
1989-09-30 00:00:00 +00:00
|
|
|
@itemx set environment @var{varname} = @var{value}
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex set environment
|
|
|
|
Sets environment variable @var{varname} to @var{value}, for your program
|
|
|
|
only, not for GDB itself. @var{value} may be any string; the values of
|
|
|
|
environment variables are just strings, and any interpretation is
|
|
|
|
supplied by your program itself. The @var{value} parameter is optional;
|
|
|
|
if it is eliminated, the variable is set to a null value. This command
|
1990-12-19 13:30:35 +00:00
|
|
|
can be abbreviated as @samp{set e}.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
For example, this command:
|
|
|
|
|
|
|
|
@example
|
|
|
|
set env USER = foo
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
tells the program, when subsequently run, to assume it is being run
|
|
|
|
on behalf of the user named @samp{foo}.
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@item delete environment @var{varname}
|
1989-09-30 00:00:00 +00:00
|
|
|
@itemx unset environment @var{varname}
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex delete environment
|
|
|
|
@kindex unset environment
|
1989-09-30 00:00:00 +00:00
|
|
|
Remove variable @var{varname} from the environment to be passed to your
|
|
|
|
program. This is different from @samp{set env @var{varname}@ =} because
|
|
|
|
@samp{delete environment} leaves the variable with no value, which is
|
|
|
|
distinguishable from an empty value. This command can be abbreviated
|
|
|
|
@samp{d e}.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Working Directory, Input/Output, Environment, Running
|
|
|
|
@section Your Program's Working Directory
|
|
|
|
|
|
|
|
@cindex working directory (of your program)
|
1989-09-30 00:00:00 +00:00
|
|
|
Each time you start your program with @samp{run}, it inherits its
|
|
|
|
working directory from the current working directory of GDB. GDB's
|
|
|
|
working directory is initially whatever it inherited from its parent
|
|
|
|
process (typically the shell), but you can specify a new working
|
|
|
|
directory in GDB with the @samp{cd} command.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
The GDB working directory also serves as a default for the commands
|
|
|
|
that specify files for GDB to operate on. @xref{Files}.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item cd @var{directory}
|
|
|
|
@kindex cd
|
|
|
|
Set GDB's working directory to @var{directory}.
|
|
|
|
|
|
|
|
@item pwd
|
|
|
|
@kindex pwd
|
|
|
|
Print GDB's working directory.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Input/Output, Attach, Working Directory, Running
|
|
|
|
@section Your Program's Input and Output
|
|
|
|
|
|
|
|
@cindex redirection
|
|
|
|
@cindex controlling terminal
|
|
|
|
By default, the program you run under GDB does input and output to the same
|
|
|
|
terminal that GDB uses.
|
|
|
|
|
|
|
|
You can redirect the program's input and/or output using @samp{sh}-style
|
|
|
|
redirection commands in the @samp{run} command. For example,
|
|
|
|
|
|
|
|
@example
|
|
|
|
run > outfile
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
starts the program, diverting its output to the file @file{outfile}.
|
|
|
|
|
|
|
|
@kindex tty
|
1989-09-30 00:00:00 +00:00
|
|
|
Another way to specify where the program should do input and output is
|
|
|
|
with the @samp{tty} command. This command accepts a file name as
|
|
|
|
argument, and causes this file to be the default for future @samp{run}
|
|
|
|
commands. It also resets the controlling terminal for the child
|
|
|
|
process, for future @samp{run} commands. For example,
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
tty /dev/ttyb
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
1989-09-30 00:00:00 +00:00
|
|
|
directs that processes started with subsequent @samp{run} commands
|
|
|
|
default to do input and output on the terminal @file{/dev/ttyb} and have
|
|
|
|
that as their controlling terminal.
|
|
|
|
|
|
|
|
An explicit redirection in @samp{run} overrides the @samp{tty} command's
|
|
|
|
effect on input/output redirection, but not its effect on the
|
|
|
|
controlling terminal.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
When you use the @samp{tty} command or redirect input in the @samp{run}
|
1989-09-30 00:00:00 +00:00
|
|
|
command, only the @emph{input for your program} is affected. The input
|
|
|
|
for GDB still comes from your terminal.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Attach, Kill Process, Input/Output, Running
|
1989-01-31 17:56:40 +00:00
|
|
|
@section Debugging an Already-Running Process
|
|
|
|
@kindex detach
|
|
|
|
@kindex attach
|
|
|
|
@cindex attach
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@table @code
|
|
|
|
@item attach @var{process--id}
|
|
|
|
@itemx attach @var{device}
|
|
|
|
This command attaches to another target, of the same type as your last
|
|
|
|
@samp{target} command (@samp{info files} will show your target stack).
|
|
|
|
The command may take as argument a process ID or a device file.
|
|
|
|
|
|
|
|
You specify a process ID to debug an already-running process that was
|
|
|
|
started outside of GDB. (The usual way to find out the process-id of
|
|
|
|
the process is with the @code{ps} utility, or with the @code{jobs -l}
|
|
|
|
shell command.) In this case, you must have permission to send the
|
|
|
|
process a signal, and it must have the same effective user ID as the
|
|
|
|
debugger.
|
|
|
|
@end table
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
When using @samp{attach}, you should first use the @samp{file} command
|
|
|
|
to specify the program running in the process and load its symbol table.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
The first thing GDB does after arranging to debug the process is to stop
|
|
|
|
it. You can examine and modify an attached process with all the GDB
|
|
|
|
commands that ordinarily available when you start processes with
|
|
|
|
@samp{run}. You can insert breakpoints; you can step and continue; you
|
|
|
|
can modify storage. If you would rather the process continue running,
|
1989-09-30 00:00:00 +00:00
|
|
|
you may use the @samp{continue} command after attaching GDB to the
|
|
|
|
process.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
When you have finished debugging the attached process, you can use the
|
1989-01-31 17:56:40 +00:00
|
|
|
@samp{detach} command to release it from GDB's control. Detaching
|
|
|
|
the process continues its execution. After the @samp{detach} command,
|
|
|
|
that process and GDB become completely independent once more, and you
|
|
|
|
are ready to @samp{attach} another process or start one with @samp{run}.
|
|
|
|
|
|
|
|
If you exit GDB or use the @samp{run} command while you have an attached
|
1990-12-19 13:30:35 +00:00
|
|
|
process, you kill that process. By default, you will be asked for
|
|
|
|
confirmation if you try to do either of these things; you can control
|
|
|
|
whether or not this happens by using the @samp{set stupidity} command
|
|
|
|
(@pxref{User Interface}).
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
The @samp{attach} command is also used to debug a remote machine via a
|
1990-09-05 17:54:31 +00:00
|
|
|
serial connection. @xref{Remote}, for more info.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
@node Kill Process,, Attach, Running
|
|
|
|
@section Killing the Child Process
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item kill
|
|
|
|
@kindex kill
|
|
|
|
Kill the child process in which the program being debugged is running
|
|
|
|
under GDB.
|
1990-12-19 13:30:35 +00:00
|
|
|
@end table
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
This command is useful if you wish to debug a core dump instead. GDB
|
|
|
|
ignores any core dump file if it is actually running the program, so the
|
|
|
|
@samp{kill} command is the only sure way to make sure the core dump file
|
|
|
|
is used once again.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
On some operating systems, you can't execute your program in another
|
|
|
|
process while it is active inside GDB. The @samp{kill} command is also
|
|
|
|
useful in this situation, if you wish to run the program outside the
|
|
|
|
debugger.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
The @samp{kill} command is also useful if you wish to recompile and
|
|
|
|
relink the program, since on many systems it is impossible to modify an
|
1990-12-19 13:30:35 +00:00
|
|
|
executable file which is running in a process. In this case, when you
|
|
|
|
next type @samp{run}, GDB will notice that the file has changed, and
|
|
|
|
will re-read the symbol table (while trying to preserve your current
|
|
|
|
breakpoint settings).
|
1989-09-30 00:00:00 +00:00
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@node Stopping, Stack, Running, Top
|
|
|
|
@chapter Stopping and Continuing
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
When you run a program normally, it runs until it terminates. The
|
|
|
|
principal purpose of using a debugger is so that you can stop it before
|
|
|
|
that point; or so that if the program runs into trouble you can
|
|
|
|
investigate and find out why.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@menu
|
|
|
|
* Signals:: Fatal signals in your program just stop it;
|
|
|
|
then you can use GDB to see what is going on.
|
|
|
|
* Breakpoints:: Breakpoints let you stop your program when it
|
|
|
|
reaches a specified point in the code.
|
1990-11-09 18:30:56 +00:00
|
|
|
an expression changes.
|
1989-01-31 17:56:40 +00:00
|
|
|
* Continuing:: Resuming execution until the next signal or breakpoint.
|
|
|
|
* Stepping:: Stepping runs the program a short distance and
|
|
|
|
then stops it wherever it has come to.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Signals, Breakpoints, Stopping, Stopping
|
|
|
|
@section Signals
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex signals
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
A signal is an asynchronous event that can happen in a program. The
|
|
|
|
operating system defines the possible kinds of signals, and gives each kind
|
|
|
|
a name and a number. For example, @code{SIGINT} is the signal a program
|
|
|
|
gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program
|
|
|
|
gets from referencing a place in memory far away from all the areas in use;
|
|
|
|
@code{SIGALRM} occurs when the alarm clock timer goes off (which happens
|
|
|
|
only if the program has requested an alarm).
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex fatal signals
|
1989-01-31 17:56:40 +00:00
|
|
|
Some signals, including @code{SIGALRM}, are a normal part of the
|
|
|
|
functioning of the program. Others, such as @code{SIGSEGV}, indicate
|
|
|
|
errors; these signals are @dfn{fatal} (kill the program immediately) if the
|
|
|
|
program has not specified in advance some other way to handle the signal.
|
|
|
|
@code{SIGINT} does not indicate an error in the program, but it is normally
|
|
|
|
fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program.
|
|
|
|
|
|
|
|
GDB has the ability to detect any occurrence of a signal in the program
|
|
|
|
running under GDB's control. You can tell GDB in advance what to do for
|
|
|
|
each kind of signal.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex handling signals
|
1989-01-31 17:56:40 +00:00
|
|
|
Normally, GDB is set up to ignore non-erroneous signals like @code{SIGALRM}
|
|
|
|
(so as not to interfere with their role in the functioning of the program)
|
|
|
|
but to stop the program immediately whenever an error signal happens.
|
1990-09-05 17:54:31 +00:00
|
|
|
You can change these settings with the @samp{handle} command.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item info signal
|
|
|
|
@kindex info signal
|
|
|
|
Print a table of all the kinds of signals and how GDB has been told to
|
|
|
|
handle each one. You can use this to see the signal numbers of all
|
|
|
|
the defined types of signals.
|
|
|
|
|
1990-09-05 17:54:31 +00:00
|
|
|
@item handle @var{signal} @var{keywords}@dots{}
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex handle
|
1990-09-05 17:54:31 +00:00
|
|
|
Change the way GDB handles signal @var{signal}. @var{signal} can be the
|
|
|
|
number of a signal or its name (with or without the @samp{SIG} at the
|
|
|
|
beginning). The @var{keywords} say what change to make.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end table
|
|
|
|
|
|
|
|
The keywords allowed by the handle command can be abbreviated. Their full
|
|
|
|
names are
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item stop
|
|
|
|
GDB should stop the program when this signal happens. This implies
|
|
|
|
the @samp{print} keyword as well.
|
|
|
|
|
|
|
|
@item print
|
|
|
|
GDB should print a message when this signal happens.
|
|
|
|
|
|
|
|
@item nostop
|
|
|
|
GDB should not stop the program when this signal happens. It may
|
|
|
|
still print a message telling you that the signal has come in.
|
|
|
|
|
|
|
|
@item noprint
|
|
|
|
GDB should not mention the occurrence of the signal at all. This
|
|
|
|
implies the @samp{nostop} keyword as well.
|
|
|
|
|
|
|
|
@item pass
|
|
|
|
GDB should allow the program to see this signal; the program will be
|
|
|
|
able to handle the signal, or may be terminated if the signal is fatal
|
|
|
|
and not handled.
|
|
|
|
|
|
|
|
@item nopass
|
|
|
|
GDB should not allow the program to see this signal.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
When a signal has been set to stop the program, the program cannot see the
|
|
|
|
signal until you continue. It will see the signal then, if @samp{pass} is
|
|
|
|
in effect for the signal in question @i{at that time}. In other words,
|
|
|
|
after GDB reports a signal, you can use the @samp{handle} command with
|
|
|
|
@samp{pass} or @samp{nopass} to control whether that signal will be seen by
|
|
|
|
the program when you later continue it.
|
|
|
|
|
|
|
|
You can also use the @samp{signal} command to prevent the program from
|
|
|
|
seeing a signal, or cause it to see a signal it normally would not see,
|
|
|
|
or to give it any signal at any time. @xref{Signaling}.
|
|
|
|
|
1990-11-09 18:30:56 +00:00
|
|
|
@node Breakpoints, Watchpoints Continuing, Signals, Stopping
|
1989-01-31 17:56:40 +00:00
|
|
|
@section Breakpoints
|
|
|
|
|
|
|
|
@cindex breakpoints
|
|
|
|
A @dfn{breakpoint} makes your program stop whenever a certain point in the
|
|
|
|
program is reached. You set breakpoints explicitly with GDB commands,
|
|
|
|
specifying the place where the program should stop by line number, function
|
|
|
|
name or exact address in the program. You can add various other conditions
|
|
|
|
to control whether the program will stop.
|
|
|
|
|
|
|
|
Each breakpoint is assigned a number when it is created; these numbers are
|
|
|
|
successive integers starting with 1. In many of the commands for controlling
|
|
|
|
various features of breakpoints you use the breakpoint number to say which
|
|
|
|
breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
|
|
|
|
@dfn{disabled}; if disabled, it has no effect on the program until you
|
|
|
|
enable it again.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@table @code
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex info break
|
|
|
|
@kindex $_
|
1990-12-19 13:30:35 +00:00
|
|
|
@item info break
|
1989-01-31 17:56:40 +00:00
|
|
|
The command @samp{info break} prints a list of all breakpoints set and not
|
1989-09-30 00:00:00 +00:00
|
|
|
deleted, showing their numbers, where in the program they are, and any
|
1989-01-31 17:56:40 +00:00
|
|
|
special features in use for them. Disabled breakpoints are included in the
|
|
|
|
list, but marked as disabled. @samp{info break} with a breakpoint number
|
1989-09-30 00:00:00 +00:00
|
|
|
as argument lists only that breakpoint. The convenience variable @code{$_}
|
1989-01-31 17:56:40 +00:00
|
|
|
and the default examining-address for the @samp{x} command are set to the
|
|
|
|
address of the last breakpoint listed (@pxref{Memory}).
|
|
|
|
|
1990-11-09 18:30:56 +00:00
|
|
|
@kindex info watch
|
|
|
|
@item info watch
|
|
|
|
This command prints a list of watchpoints.
|
1990-12-19 13:30:35 +00:00
|
|
|
|
|
|
|
@cindex watchpoints
|
|
|
|
A @dfn{watchpoint} is a special breakpoint that stops your program when
|
|
|
|
the value of an expression changes. You can use a watchpoint to stop
|
|
|
|
execution whenever the value of an expression changes, without having to
|
|
|
|
predict a particular place in the inferior process where this may
|
|
|
|
happen. Aside from the different syntax in setting a watchpoint, it is
|
|
|
|
managed exactly like any other breakpoint and is enabled, disabled, and
|
|
|
|
deleted exactly like any other breakpoint.
|
|
|
|
|
|
|
|
|
|
|
|
|
1990-12-17 18:23:17 +00:00
|
|
|
@end table
|
1990-11-09 18:30:56 +00:00
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@menu
|
|
|
|
* Set Breaks:: How to establish breakpoints.
|
1989-09-30 00:00:00 +00:00
|
|
|
* Delete Breaks:: How to remove breakpoints no longer needed.
|
1989-01-31 17:56:40 +00:00
|
|
|
* Disabling:: How to disable breakpoints (turn them off temporarily).
|
|
|
|
* Conditions:: Making extra conditions on whether to stop.
|
|
|
|
* Break Commands:: Commands to be executed at a breakpoint.
|
|
|
|
* Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do.
|
|
|
|
@end menu
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Set Breaks, Delete Breaks, Breakpoints, Breakpoints
|
1989-01-31 17:56:40 +00:00
|
|
|
@subsection Setting Breakpoints
|
|
|
|
|
|
|
|
@kindex break
|
1990-11-09 18:30:56 +00:00
|
|
|
@kindex watch
|
1989-01-31 17:56:40 +00:00
|
|
|
Breakpoints are set with the @samp{break} command (abbreviated @samp{b}).
|
1990-11-09 18:30:56 +00:00
|
|
|
Watchpoints are set with the @samp{watch} command.
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
You have several ways to say where the breakpoint should go.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item break @var{function}
|
|
|
|
Set a breakpoint at entry to function @var{function}.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@item break @var{+offset}
|
|
|
|
@itemx break @var{-offset}
|
|
|
|
Set a breakpoint some number of lines forward or back from the position
|
|
|
|
at which execution stopped in the currently selected frame.
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@item break @var{linenum}
|
|
|
|
Set a breakpoint at line @var{linenum} in the current source file.
|
|
|
|
That file is the last file whose source text was printed. This
|
|
|
|
breakpoint will stop the program just before it executes any of the
|
|
|
|
code on that line.
|
|
|
|
|
|
|
|
@item break @var{filename}:@var{linenum}
|
|
|
|
Set a breakpoint at line @var{linenum} in source file @var{filename}.
|
|
|
|
|
|
|
|
@item break @var{filename}:@var{function}
|
|
|
|
Set a breakpoint at entry to function @var{function} found in file
|
1989-09-30 00:00:00 +00:00
|
|
|
@var{filename}. Specifying a file name as well as a function name is
|
1989-01-31 17:56:40 +00:00
|
|
|
superfluous except when multiple files contain similarly named
|
|
|
|
functions.
|
|
|
|
|
|
|
|
@item break *@var{address}
|
|
|
|
Set a breakpoint at address @var{address}. You can use this to set
|
|
|
|
breakpoints in parts of the program which do not have debugging
|
|
|
|
information or source files.
|
|
|
|
|
|
|
|
@item break
|
|
|
|
Set a breakpoint at the next instruction to be executed in the selected
|
|
|
|
stack frame (@pxref{Stack}). In any selected frame but the innermost,
|
|
|
|
this will cause the program to stop as soon as control returns to that
|
|
|
|
frame. This is equivalent to a @samp{finish} command in the frame
|
1989-09-30 00:00:00 +00:00
|
|
|
inside the selected frame. If this is done in the innermost frame, GDB
|
1989-01-31 17:56:40 +00:00
|
|
|
will stop the next time it reaches the current location; this may be
|
1989-09-30 00:00:00 +00:00
|
|
|
useful inside of loops.
|
|
|
|
|
|
|
|
GDB normally ignores breakpoints when it resumes execution, until at
|
|
|
|
least one instruction has been executed. If it did not do this, you
|
|
|
|
would be unable to proceed past a breakpoint without first disabling the
|
|
|
|
breakpoint. This rule applies whether or not the breakpoint already
|
|
|
|
existed when the program stopped.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item break @dots{} if @var{cond}
|
|
|
|
Set a breakpoint with condition @var{cond}; evaluate the expression
|
|
|
|
@var{cond} each time the breakpoint is reached, and stop only if the
|
|
|
|
value is nonzero. @samp{@dots{}} stands for one of the possible
|
|
|
|
arguments described above (or no argument) specifying where to break.
|
|
|
|
@xref{Conditions}, for more information on breakpoint conditions.
|
|
|
|
|
|
|
|
@item tbreak @var{args}
|
|
|
|
@kindex tbreak
|
|
|
|
Set a breakpoint enabled only for one stop. @var{args} are the
|
|
|
|
same as in the @samp{break} command, and the breakpoint is set in the same
|
1989-09-30 00:00:00 +00:00
|
|
|
way, but the breakpoint is automatically disabled the first time it
|
|
|
|
is hit. @xref{Disabling}.
|
1990-11-09 18:30:56 +00:00
|
|
|
|
1990-12-17 18:23:17 +00:00
|
|
|
@item rbreak @var{regex}
|
|
|
|
@kindex rbreak
|
|
|
|
Set a breakpoint on all functions matching @var{regex}. This is
|
|
|
|
useful for setting breakpoints on overloaded functions that are not
|
|
|
|
members of any special classes. This command sets an unconditional
|
|
|
|
breakpoint on all matches, printing a list of all breakpoints it set.
|
|
|
|
Once these breakpoints are set, they are treated just like the
|
|
|
|
breakpoints set with the @samp{break} command. They can be deleted,
|
|
|
|
disabled, made conditional, etc., in the standard ways.
|
|
|
|
|
1990-11-09 18:30:56 +00:00
|
|
|
@kindex watch
|
1990-12-19 13:30:35 +00:00
|
|
|
@item watch @var{expr}
|
1990-11-09 18:30:56 +00:00
|
|
|
Set a watchpoint for an expression.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end table
|
|
|
|
|
|
|
|
GDB allows you to set any number of breakpoints at the same place in the
|
|
|
|
program. There is nothing silly or meaningless about this. When the
|
|
|
|
breakpoints are conditional, this is even useful (@pxref{Conditions}).
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Delete Breaks, Disabling, Set Breaks, Breakpoints
|
|
|
|
@subsection Deleting Breakpoints
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1990-11-09 18:30:56 +00:00
|
|
|
@cindex clearing breakpoints and watchpoints
|
|
|
|
@cindex deleting breakpoints and watchpoints
|
1989-01-31 17:56:40 +00:00
|
|
|
It is often necessary to eliminate a breakpoint once it has done its job
|
|
|
|
and you no longer want the program to stop there. This is called
|
1989-09-30 00:00:00 +00:00
|
|
|
@dfn{deleting} the breakpoint. A breakpoint that has been deleted no
|
|
|
|
longer exists in any sense; it is forgotten.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
With the @samp{clear} command you can delete breakpoints according to where
|
|
|
|
they are in the program. With the @samp{delete} command you can delete
|
1989-01-31 17:56:40 +00:00
|
|
|
individual breakpoints by specifying their breakpoint numbers.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@b{It is not necessary to delete a breakpoint to proceed past it.} GDB
|
1989-01-31 17:56:40 +00:00
|
|
|
automatically ignores breakpoints in the first instruction to be executed
|
1989-09-30 00:00:00 +00:00
|
|
|
when you continue execution without changing the execution address.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item clear
|
|
|
|
@kindex clear
|
1989-09-30 00:00:00 +00:00
|
|
|
Delete any breakpoints at the next instruction to be executed in the
|
1989-01-31 17:56:40 +00:00
|
|
|
selected stack frame (@pxref{Selection}). When the innermost frame
|
1989-09-30 00:00:00 +00:00
|
|
|
is selected, this is a good way to delete a breakpoint that the program
|
1989-01-31 17:56:40 +00:00
|
|
|
just stopped at.
|
|
|
|
|
|
|
|
@item clear @var{function}
|
|
|
|
@itemx clear @var{filename}:@var{function}
|
1989-09-30 00:00:00 +00:00
|
|
|
Delete any breakpoints set at entry to the function @var{function}.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item clear @var{linenum}
|
1989-09-30 00:00:00 +00:00
|
|
|
@itemx clear @var{filename}:@var{linenum}
|
|
|
|
Delete any breakpoints set at or within the code of the specified line.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item delete @var{bnums}@dots{}
|
|
|
|
@kindex delete
|
|
|
|
Delete the breakpoints of the numbers specified as arguments.
|
|
|
|
@end table
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Disabling, Conditions, Delete Breaks, Breakpoints
|
1989-01-31 17:56:40 +00:00
|
|
|
@subsection Disabling Breakpoints
|
|
|
|
|
|
|
|
@cindex disabled breakpoints
|
|
|
|
@cindex enabled breakpoints
|
1989-09-30 00:00:00 +00:00
|
|
|
Rather than deleting a breakpoint, you might prefer to @dfn{disable} it.
|
|
|
|
This makes the breakpoint inoperative as if it had been deleted, but
|
1989-01-31 17:56:40 +00:00
|
|
|
remembers the information on the breakpoint so that you can @dfn{enable}
|
|
|
|
it again later.
|
|
|
|
|
|
|
|
You disable and enable breakpoints with the @samp{enable} and
|
|
|
|
@samp{disable} commands, specifying one or more breakpoint numbers as
|
|
|
|
arguments. Use @samp{info break} to print a list of breakpoints if you
|
|
|
|
don't know which breakpoint numbers to use.
|
|
|
|
|
|
|
|
A breakpoint can have any of four different states of enablement:
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
|
|
Enabled. The breakpoint will stop the program. A breakpoint made
|
|
|
|
with the @samp{break} command starts out in this state.
|
|
|
|
@item
|
|
|
|
Disabled. The breakpoint has no effect on the program.
|
|
|
|
@item
|
|
|
|
Enabled once. The breakpoint will stop the program, but
|
|
|
|
when it does so it will become disabled. A breakpoint made
|
|
|
|
with the @samp{tbreak} command starts out in this state.
|
|
|
|
@item
|
|
|
|
Enabled for deletion. The breakpoint will stop the program, but
|
|
|
|
immediately after it does so it will be deleted permanently.
|
|
|
|
@end itemize
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
You can use the following commands to enable or disable a breakpoint:
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item disable breakpoints @var{bnums}@dots{}
|
1989-09-30 00:00:00 +00:00
|
|
|
@itemx disable @var{bnums}@dots{}
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex disable breakpoints
|
|
|
|
@kindex disable
|
|
|
|
Disable the specified breakpoints. A disabled breakpoint has no
|
|
|
|
effect but is not forgotten. All options such as ignore-counts,
|
|
|
|
conditions and commands are remembered in case the breakpoint is
|
|
|
|
enabled again later.
|
|
|
|
|
|
|
|
@item enable breakpoints @var{bnums}@dots{}
|
1989-09-30 00:00:00 +00:00
|
|
|
@itemx enable @var{bnums}@dots{}
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex enable breakpoints
|
|
|
|
@kindex enable
|
|
|
|
Enable the specified breakpoints. They become effective once again in
|
|
|
|
stopping the program, until you specify otherwise.
|
|
|
|
|
|
|
|
@item enable breakpoints once @var{bnums}@dots{}
|
1989-09-30 00:00:00 +00:00
|
|
|
@itemx enable once @var{bnums}@dots{}
|
1989-01-31 17:56:40 +00:00
|
|
|
Enable the specified breakpoints temporarily. Each will be disabled
|
|
|
|
again the next time it stops the program (unless you have used one of
|
|
|
|
these commands to specify a different state before that time comes).
|
|
|
|
|
|
|
|
@item enable breakpoints delete @var{bnums}@dots{}
|
1989-09-30 00:00:00 +00:00
|
|
|
@itemx enable delete @var{bnums}@dots{}
|
1989-01-31 17:56:40 +00:00
|
|
|
Enable the specified breakpoints to work once and then die. Each of
|
|
|
|
the breakpoints will be deleted the next time it stops the program
|
|
|
|
(unless you have used one of these commands to specify a different
|
|
|
|
state before that time comes).
|
|
|
|
@end table
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
Save for a breakpoint set with @samp{tbreak} (@pxref{Set Breaks},
|
|
|
|
breakpoints that you set are enabled or disabled only when you use one
|
|
|
|
of the commands above. (The command @samp{until} can set and delete a
|
|
|
|
breakpoint on its own, but it will not change the state of your
|
|
|
|
breakpoints).
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@node Conditions, Break Commands, Disabling, Breakpoints
|
|
|
|
@subsection Break Conditions
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex conditional breakpoints
|
|
|
|
@cindex breakpoint conditions
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
The simplest sort of breakpoint breaks every time the program reaches a
|
1989-09-30 00:00:00 +00:00
|
|
|
specified place. You can also specify a @dfn{condition} for a
|
|
|
|
breakpoint. A condition is just a boolean expression in your
|
|
|
|
programming language. (@xref{Expressions}). A breakpoint with a
|
|
|
|
condition evaluates the expression each time the program reaches it, and
|
|
|
|
the program stops only if the condition is true.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
Break conditions may have side effects, and may even call functions in your
|
|
|
|
program. These may sound like strange things to do, but their effects are
|
|
|
|
completely predictable unless there is another enabled breakpoint at the
|
|
|
|
same address. (In that case, GDB might see the other breakpoint first and
|
|
|
|
stop the program without checking the condition of this one.) Note that
|
|
|
|
breakpoint commands are usually more convenient and flexible for the
|
|
|
|
purpose of performing side effects when a breakpoint is reached
|
|
|
|
(@pxref{Break Commands}).
|
|
|
|
|
|
|
|
Break conditions can be specified when a breakpoint is set, by using
|
|
|
|
@samp{if} in the arguments to the @samp{break} command. @xref{Set Breaks}.
|
|
|
|
They can also be changed at any time with the @samp{condition} command:
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item condition @var{bnum} @var{expression}
|
|
|
|
@kindex condition
|
|
|
|
Specify @var{expression} as the break condition for breakpoint number
|
|
|
|
@var{bnum}. From now on, this breakpoint will stop the program only if
|
|
|
|
the value of @var{expression} is true (nonzero, in C). @var{expression}
|
|
|
|
is not evaluated at the time the @samp{condition} command is given.
|
|
|
|
@xref{Expressions}.
|
|
|
|
|
|
|
|
@item condition @var{bnum}
|
|
|
|
Remove the condition from breakpoint number @var{bnum}. It becomes
|
|
|
|
an ordinary unconditional breakpoint.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@cindex ignore count (of breakpoint)
|
1989-09-30 00:00:00 +00:00
|
|
|
A special case of a breakpoint condition is to stop only when the
|
|
|
|
breakpoint has been reached a certain number of times. This is so
|
|
|
|
useful that there is a special way to do it, using the @dfn{ignore
|
|
|
|
count} of the breakpoint. Every breakpoint has an ignore count, which
|
|
|
|
is an integer. Most of the time, the ignore count is zero, and
|
|
|
|
therefore has no effect. But if the program reaches a breakpoint whose
|
|
|
|
ignore count is positive, then instead of stopping, it just decrements
|
|
|
|
the ignore count by one and continues. As a result, if the ignore count
|
|
|
|
value is @var{n}, the breakpoint will not stop the next @var{n} times it
|
|
|
|
is reached.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item ignore @var{bnum} @var{count}
|
|
|
|
@kindex ignore
|
|
|
|
Set the ignore count of breakpoint number @var{bnum} to @var{count}.
|
1990-12-19 13:30:35 +00:00
|
|
|
The next @var{count} times the breakpoint is reached, your program's
|
|
|
|
execution will not stop; other than to decrement the ignore count, GDB
|
|
|
|
takes no action.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
To make the breakpoint stop the next time it is reached, specify
|
|
|
|
a count of zero.
|
|
|
|
|
|
|
|
@item cont @var{count}
|
|
|
|
Continue execution of the program, setting the ignore count of the
|
|
|
|
breakpoint that the program stopped at to @var{count} minus one.
|
1989-09-30 00:00:00 +00:00
|
|
|
Thus, the program will not stop at this breakpoint until the
|
|
|
|
@var{count}'th time it is reached.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
This command is allowed only when the program stopped due to a
|
|
|
|
breakpoint. At other times, the argument to @samp{cont} is ignored.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
If a breakpoint has a positive ignore count and a condition, the condition
|
|
|
|
is not checked. Once the ignore count reaches zero, the condition will
|
|
|
|
start to be checked.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
Note that you could achieve the effect of the ignore count with a
|
|
|
|
condition such as @w{@samp{$foo-- <= 0}} using a debugger convenience
|
|
|
|
variable that is decremented each time. @xref{Convenience Vars}.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@node Break Commands, Error in Breakpoints, Conditions, Breakpoints
|
|
|
|
@subsection Commands Executed on Breaking
|
|
|
|
|
|
|
|
@cindex breakpoint commands
|
|
|
|
You can give any breakpoint a series of commands to execute when the
|
|
|
|
program stops due to that breakpoint. For example, you might want to
|
|
|
|
print the values of certain expressions, or enable other breakpoints.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item commands @var{bnum}
|
|
|
|
Specify commands for breakpoint number @var{bnum}. The commands
|
|
|
|
themselves appear on the following lines. Type a line containing just
|
|
|
|
@samp{end} to terminate the commands.
|
|
|
|
|
|
|
|
To remove all commands from a breakpoint, use the command
|
|
|
|
@samp{commands} and follow it immediately by @samp{end}; that is, give
|
|
|
|
no commands.
|
|
|
|
|
|
|
|
With no arguments, @samp{commands} refers to the last breakpoint set.
|
|
|
|
@end table
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
You can use breakpoint commands to start the program up again.
|
1989-01-31 17:56:40 +00:00
|
|
|
Simply use the @samp{cont} command, or @samp{step}, or any other command
|
|
|
|
to resume execution. However, any remaining breakpoint commands are
|
1989-09-30 00:00:00 +00:00
|
|
|
ignored. When the program stops again, GDB will act according to the
|
|
|
|
cause of that stop.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@kindex silent
|
|
|
|
If the first command specified is @samp{silent}, the usual message about
|
|
|
|
stopping at a breakpoint is not printed. This may be desirable for
|
|
|
|
breakpoints that are to print a specific message and then continue.
|
|
|
|
If the remaining commands too print nothing, you will see no sign that
|
|
|
|
the breakpoint was reached at all. @samp{silent} is not really a command;
|
|
|
|
it is meaningful only at the beginning of the commands for a breakpoint.
|
|
|
|
|
|
|
|
The commands @samp{echo} and @samp{output} that allow you to print precisely
|
|
|
|
controlled output are often useful in silent breakpoints. @xref{Output}.
|
|
|
|
|
|
|
|
For example, here is how you could use breakpoint commands to print the
|
1989-09-30 00:00:00 +00:00
|
|
|
value of @code{x} at entry to @code{foo} whenever it is positive.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
break foo if x>0
|
1989-09-30 00:00:00 +00:00
|
|
|
commands
|
1989-01-31 17:56:40 +00:00
|
|
|
silent
|
|
|
|
echo x is\040
|
|
|
|
output x
|
|
|
|
echo \n
|
|
|
|
cont
|
|
|
|
end
|
|
|
|
@end example
|
|
|
|
|
|
|
|
One application for breakpoint commands is to correct one bug so you can
|
|
|
|
test another. Put a breakpoint just after the erroneous line of code, give
|
|
|
|
it a condition to detect the case in which something erroneous has been
|
|
|
|
done, and give it commands to assign correct values to any variables that
|
|
|
|
need them. End with the @samp{cont} command so that the program does not
|
|
|
|
stop, and start with the @samp{silent} command so that no output is
|
|
|
|
produced. Here is an example:
|
|
|
|
|
|
|
|
@example
|
|
|
|
break 403
|
1989-09-30 00:00:00 +00:00
|
|
|
commands
|
1989-01-31 17:56:40 +00:00
|
|
|
silent
|
|
|
|
set x = y + 4
|
|
|
|
cont
|
|
|
|
end
|
|
|
|
@end example
|
|
|
|
|
|
|
|
One deficiency in the operation of automatically continuing breakpoints
|
|
|
|
under Unix appears when your program uses raw mode for the terminal.
|
|
|
|
GDB switches back to its own terminal modes (not raw) before executing
|
|
|
|
commands, and then must switch back to raw mode when your program is
|
|
|
|
continued. This causes any pending terminal input to be lost.
|
|
|
|
|
|
|
|
In the GNU system, this will be fixed by changing the behavior of
|
|
|
|
terminal modes.
|
|
|
|
|
|
|
|
Under Unix, when you have this problem, you might be able to get around
|
|
|
|
it by putting your actions into the breakpoint condition instead of
|
|
|
|
commands. For example
|
|
|
|
|
|
|
|
@example
|
|
|
|
condition 5 (x = y + 4), 0
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
1989-09-30 00:00:00 +00:00
|
|
|
specifies a condition expression (@xref{Expressions}) that will change
|
|
|
|
@code{x} as needed, then always have the value 0 so the program will not
|
|
|
|
stop. Loss of input is avoided here because break conditions are
|
|
|
|
evaluated without changing the terminal modes. When you want to have
|
|
|
|
nontrivial conditions for performing the side effects, the operators
|
|
|
|
@samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@node Error in Breakpoints,, Break Commands, Breakpoints
|
|
|
|
@subsection ``Cannot Insert Breakpoints'' Error
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
Under some operating systems, breakpoints cannot be used in a program if
|
|
|
|
any other process is running that program. Attempting to run or
|
1990-12-19 13:30:35 +00:00
|
|
|
continue a program with a breakpoint in this case will cause GDB to
|
|
|
|
stop that program.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
When this happens, you have three ways to proceed:
|
|
|
|
|
|
|
|
@enumerate
|
|
|
|
@item
|
|
|
|
Remove or disable the breakpoints, then continue.
|
|
|
|
|
|
|
|
@item
|
|
|
|
Suspend GDB, and copy the file containing the program to a new name.
|
|
|
|
Resume GDB and use the @samp{exec-file} command to specify that GDB
|
|
|
|
should run the program under that name. Then start the program again.
|
|
|
|
|
|
|
|
@item
|
1989-09-30 00:00:00 +00:00
|
|
|
Relink the program so that the text segment is nonsharable, using the
|
|
|
|
linker option @samp{-N}. The operating system limitation may not apply
|
|
|
|
to nonsharable executables.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end enumerate
|
|
|
|
|
|
|
|
@node Continuing, Stepping, Breakpoints, Stopping
|
|
|
|
@section Continuing
|
|
|
|
|
|
|
|
After your program stops, most likely you will want it to run some more if
|
|
|
|
the bug you are looking for has not happened yet.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item cont
|
|
|
|
@kindex cont
|
|
|
|
Continue running the program at the place where it stopped.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
If the program stopped at a breakpoint, the place to continue running
|
|
|
|
is the address of the breakpoint. You might expect that continuing would
|
|
|
|
just stop at the same breakpoint immediately. In fact, @samp{cont}
|
|
|
|
takes special care to prevent that from happening. You do not need
|
1989-09-30 00:00:00 +00:00
|
|
|
to delete the breakpoint to proceed through it after stopping at it.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
You can, however, specify an ignore-count for the breakpoint that the
|
|
|
|
program stopped at, by means of an argument to the @samp{cont} command.
|
|
|
|
@xref{Conditions}.
|
|
|
|
|
|
|
|
If the program stopped because of a signal other than @code{SIGINT} or
|
|
|
|
@code{SIGTRAP}, continuing will cause the program to see that signal.
|
|
|
|
You may not want this to happen. For example, if the program stopped
|
|
|
|
due to some sort of memory reference error, you might store correct
|
|
|
|
values into the erroneous variables and continue, hoping to see more
|
|
|
|
execution; but the program would probably terminate immediately as
|
|
|
|
a result of the fatal signal once it sees the signal. To prevent this,
|
|
|
|
you can continue with @samp{signal 0}. @xref{Signaling}. You can
|
|
|
|
also act in advance to prevent the program from seeing certain kinds
|
|
|
|
of signals, using the @samp{handle} command (@pxref{Signals}).
|
|
|
|
|
|
|
|
@node Stepping,, Continuing, Stopping
|
|
|
|
@section Stepping
|
|
|
|
|
|
|
|
@cindex stepping
|
|
|
|
@dfn{Stepping} means setting your program in motion for a limited time, so
|
|
|
|
that control will return automatically to the debugger after one line of
|
|
|
|
code or one machine instruction. Breakpoints are active during stepping
|
|
|
|
and the program will stop for them even if it has not gone as far as the
|
|
|
|
stepping command specifies.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item step
|
|
|
|
@kindex step
|
1989-09-30 00:00:00 +00:00
|
|
|
Continue running the program until control reaches a different line,
|
|
|
|
then stop it and return control to the debugger. This command is
|
|
|
|
abbreviated @samp{s}.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
This command may be given when control is within a function for which
|
1989-01-31 17:56:40 +00:00
|
|
|
there is no debugging information. In that case, execution will proceed
|
1989-09-30 00:00:00 +00:00
|
|
|
until control reaches a different function, or is about to return from
|
|
|
|
this function. An argument repeats this action.
|
|
|
|
|
|
|
|
@item step @var{count}
|
|
|
|
Continue running as in @samp{step}, but do so @var{count} times. If a
|
|
|
|
breakpoint is reached or a signal not related to stepping occurs before
|
|
|
|
@var{count} steps, stepping stops right away.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item next
|
|
|
|
@kindex next
|
|
|
|
Similar to @samp{step}, but any function calls appearing within the line of
|
|
|
|
code are executed without stopping. Execution stops when control reaches a
|
|
|
|
different line of code at the stack level which was executing when the
|
|
|
|
@samp{next} command was given. This command is abbreviated @samp{n}.
|
|
|
|
|
|
|
|
An argument is a repeat count, as in @samp{step}.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@samp{next} within a function without debugging information acts as does
|
1989-01-31 17:56:40 +00:00
|
|
|
@samp{step}, but any function calls appearing within the code of the
|
1989-09-30 00:00:00 +00:00
|
|
|
function are executed without stopping.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item finish
|
|
|
|
@kindex finish
|
1989-09-30 00:00:00 +00:00
|
|
|
Continue running until just after the selected stack frame returns (or
|
|
|
|
until there is some other reason to stop, such as a fatal signal or a
|
|
|
|
breakpoint). Print value returned by the selected stack frame (if any).
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
Contrast this with the @samp{return} command (@pxref{Returning}).
|
|
|
|
|
|
|
|
@item until
|
|
|
|
@kindex until
|
1989-09-30 00:00:00 +00:00
|
|
|
This command is used to avoid single stepping through a loop more than
|
|
|
|
once. It is like the @samp{next} command, except that when @samp{until}
|
|
|
|
encounters a jump, it automatically continues execution until the
|
|
|
|
program counter is greater than the address of the jump.
|
|
|
|
|
|
|
|
This means that when you reach the end of a loop after single stepping
|
|
|
|
though it, @samp{until} will cause the program to continue execution
|
|
|
|
until the loop is exited. In contrast, a @samp{next} command at the end
|
|
|
|
of a loop will simply step back to the beginning of the loop, which
|
|
|
|
would force you to step through the next iteration.
|
|
|
|
|
|
|
|
@samp{until} always stops the program if it attempts to exit the current
|
|
|
|
stack frame.
|
|
|
|
|
|
|
|
@samp{until} may produce somewhat counterintuitive results if the order
|
|
|
|
of the source lines does not match the actual order of execution. For
|
|
|
|
example, in a typical C @code{for}-loop, the third expression in the
|
|
|
|
@code{for}-statement (the loop-step expression) is executed after the
|
|
|
|
statements in the body of the loop, but is written before them.
|
|
|
|
Therefore, the @samp{until} command would appear to step back to the
|
|
|
|
beginning of the loop when it advances to this expression. However, it
|
|
|
|
has not really done so, not in terms of the actual machine code.
|
|
|
|
|
|
|
|
Note that @samp{until} with no argument works by means of single
|
|
|
|
instruction stepping, and hence is slower than @samp{until} with an
|
|
|
|
argument.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item until @var{location}
|
1989-09-30 00:00:00 +00:00
|
|
|
Continue running the program until either the specified location is
|
1990-12-19 13:30:35 +00:00
|
|
|
reached, or the current (innermost) stack frame returns. @var{location}
|
|
|
|
is any of the forms of argument acceptable to @samp{break} (@pxref{Set
|
|
|
|
Breaks}). This form of the command uses breakpoints, and hence is
|
|
|
|
quicker than @samp{until} without an argument.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item stepi
|
|
|
|
@itemx si
|
|
|
|
@kindex stepi
|
|
|
|
@kindex si
|
1989-09-30 00:00:00 +00:00
|
|
|
Execute one machine instruction, then stop and return to the debugger.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
It is often useful to do @samp{display/i $pc} when stepping by machine
|
|
|
|
instructions. This will cause the next instruction to be executed to
|
|
|
|
be displayed automatically at each stop. @xref{Auto Display}.
|
|
|
|
|
|
|
|
An argument is a repeat count, as in @samp{step}.
|
|
|
|
|
|
|
|
@item nexti
|
|
|
|
@itemx ni
|
|
|
|
@kindex nexti
|
|
|
|
@kindex ni
|
1989-09-30 00:00:00 +00:00
|
|
|
Execute one machine instruction, but if it is a subroutine call,
|
1989-01-31 17:56:40 +00:00
|
|
|
proceed until the subroutine returns.
|
|
|
|
|
|
|
|
An argument is a repeat count, as in @samp{next}.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
A typical technique for using stepping is to put a breakpoint
|
|
|
|
(@pxref{Breakpoints}) at the beginning of the function or the section of
|
|
|
|
the program in which a problem is believed to lie, and then step through
|
|
|
|
the suspect area, examining the variables that are interesting, until the
|
|
|
|
problem happens.
|
|
|
|
|
|
|
|
The @samp{cont} command can be used after stepping to resume execution
|
|
|
|
until the next breakpoint or signal.
|
|
|
|
|
|
|
|
@node Stack, Source, Stopping, Top
|
|
|
|
@chapter Examining the Stack
|
|
|
|
|
|
|
|
When your program has stopped, the first thing you need to know is where it
|
|
|
|
stopped and how it got there.
|
|
|
|
|
|
|
|
@cindex call stack
|
|
|
|
Each time your program performs a function call, the information about
|
|
|
|
where in the program the call was made from is saved in a block of data
|
|
|
|
called a @dfn{stack frame}. The frame also contains the arguments of the
|
|
|
|
call and the local variables of the function that was called. All the
|
|
|
|
stack frames are allocated in a region of memory called the @dfn{call
|
|
|
|
stack}.
|
|
|
|
|
|
|
|
When your program stops, the GDB commands for examining the stack allow you
|
|
|
|
to see all of this information.
|
|
|
|
|
|
|
|
One of the stack frames is @dfn{selected} by GDB and many GDB commands
|
|
|
|
refer implicitly to the selected frame. In particular, whenever you ask
|
|
|
|
GDB for the value of a variable in the program, the value is found in the
|
|
|
|
selected frame. There are special GDB commands to select whichever frame
|
|
|
|
you are interested in.
|
|
|
|
|
|
|
|
When the program stops, GDB automatically selects the currently executing
|
|
|
|
frame and describes it briefly as the @samp{frame} command does
|
|
|
|
(@pxref{Frame Info, Info}).
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Frames:: Explanation of stack frames and terminology.
|
|
|
|
* Backtrace:: Summarizing many frames at once.
|
|
|
|
* Selection:: How to select a stack frame.
|
|
|
|
* Info: Frame Info, Commands to print information on stack frames.
|
1990-12-17 18:23:17 +00:00
|
|
|
* Exception Handling: How GDB supports exception handling for C++.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Frames, Backtrace, Stack, Stack
|
|
|
|
@section Stack Frames
|
|
|
|
|
|
|
|
@cindex frame
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex stack frame
|
|
|
|
The call stack is divided up into contiguous pieces called @dfn{stack
|
|
|
|
frames}, or @dfn{frames} for short; each frame is the data associated
|
|
|
|
with 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 is executing.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@cindex initial frame
|
|
|
|
@cindex outermost frame
|
|
|
|
@cindex innermost frame
|
|
|
|
When your program is started, the stack has only one frame, that of the
|
|
|
|
function @code{main}. This is called the @dfn{initial} frame or the
|
|
|
|
@dfn{outermost} frame. Each time a function is called, a new frame is
|
|
|
|
made. Each time a function returns, the frame for that function invocation
|
|
|
|
is eliminated. If a function is recursive, there can be many frames for
|
|
|
|
the same function. The frame for the function in which execution is
|
|
|
|
actually occurring is called the @dfn{innermost} frame. This is the most
|
|
|
|
recently created of all the stack frames that still exist.
|
|
|
|
|
|
|
|
@cindex frame pointer
|
|
|
|
Inside your program, stack frames are identified by their addresses. A
|
|
|
|
stack frame consists of many bytes, each of which has its own address; each
|
|
|
|
kind of computer has a convention for choosing one of those bytes whose
|
|
|
|
address serves as the address of the frame. Usually this address is kept
|
|
|
|
in a register called the @dfn{frame pointer register} while execution is
|
|
|
|
going on in that frame.
|
|
|
|
|
|
|
|
@cindex frame number
|
|
|
|
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 upward.
|
|
|
|
These numbers do not really exist in your program; they are to give you a
|
|
|
|
way of talking about stack frames in GDB commands.
|
|
|
|
|
|
|
|
@cindex selected frame
|
|
|
|
Many GDB commands refer implicitly to one stack frame. GDB records a stack
|
|
|
|
frame that is called the @dfn{selected} stack frame; you can select any
|
|
|
|
frame using one set of GDB commands, and then other commands will operate
|
|
|
|
on that frame. When your program stops, GDB automatically selects the
|
|
|
|
innermost frame.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex frameless execution
|
|
|
|
Some functions can be compiled to run without a frame reserved for them
|
|
|
|
on the stack. This is occasionally done with heavily used library
|
|
|
|
functions to save the frame setup time. GDB has limited facilities for
|
|
|
|
dealing with these function invocations; if the innermost function
|
|
|
|
invocation has no stack frame, GDB will give it a virtual stack frame of
|
|
|
|
0 and correctly allow tracing of the function call chain. Results are
|
|
|
|
undefined if a function invocation besides the innermost one is
|
|
|
|
frameless.
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@node Backtrace, Selection, Frames, Stack
|
|
|
|
@section Backtraces
|
|
|
|
|
|
|
|
A backtrace is a summary of how the program got where it is. It shows one
|
|
|
|
line per frame, for many frames, starting with the currently executing
|
|
|
|
frame (frame zero), followed by its caller (frame one), and on up the
|
|
|
|
stack.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item backtrace
|
|
|
|
@itemx bt
|
1989-09-30 00:00:00 +00:00
|
|
|
@kindex backtrace
|
|
|
|
@kindex bt
|
1989-01-31 17:56:40 +00:00
|
|
|
Print a backtrace of the entire stack: one line per frame for all
|
|
|
|
frames in the stack.
|
|
|
|
|
|
|
|
You can stop the backtrace at any time by typing the system interrupt
|
|
|
|
character, normally @kbd{Control-C}.
|
|
|
|
|
|
|
|
@item backtrace @var{n}
|
|
|
|
@itemx bt @var{n}
|
1989-09-30 00:00:00 +00:00
|
|
|
Similar, but print only the innermost @var{n} frames.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item backtrace @var{-n}
|
|
|
|
@itemx bt @var{-n}
|
1989-09-30 00:00:00 +00:00
|
|
|
Similar, but print only the outermost @var{n} frames.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end table
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@kindex where
|
|
|
|
@kindex info stack
|
|
|
|
The names @samp{where} and @samp{info stack} are additional aliases
|
|
|
|
for @samp{backtrace}.
|
|
|
|
|
|
|
|
Every line in the backtrace shows the frame number, the function name
|
|
|
|
and the program counter value.
|
|
|
|
|
|
|
|
If the function is in a source file whose symbol table data has been
|
|
|
|
fully read, the backtrace shows the source file name and 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 line number.)
|
|
|
|
|
|
|
|
Here is an example of a backtrace. It was made with the command
|
|
|
|
@samp{bt 3}, so it shows the innermost three frames.
|
|
|
|
|
|
|
|
@example
|
1990-12-19 13:30:35 +00:00
|
|
|
#0 rtx_equal_p (x=(rtx) 0x8e58c, y=(rtx) 0x1086c4) \
|
|
|
|
(/gp/rms/cc/rtlanal.c line 337)
|
1989-09-30 00:00:00 +00:00
|
|
|
#1 0x246b0 in expand_call (...) (...)
|
|
|
|
#2 0x21cfc in expand_expr (...) (...)
|
|
|
|
(More stack frames follow...)
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
The functions @code{expand_call} and @code{expand_expr} are in a file
|
|
|
|
whose symbol details have not been fully read. Full detail is available
|
|
|
|
for the function @code{rtx_equal_p}, which is in the file
|
|
|
|
@file{rtlanal.c}. Its arguments, named @code{x} and @code{y}, are shown
|
|
|
|
with their typed values.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@node Selection, Frame Info, Backtrace, Stack
|
|
|
|
@section Selecting a Frame
|
|
|
|
|
|
|
|
Most commands for examining the stack and other data in the program 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 brief description
|
|
|
|
of the stack frame just selected.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item frame @var{n}
|
|
|
|
@kindex frame
|
|
|
|
Select frame number @var{n}. Recall that frame zero is the innermost
|
|
|
|
(currently executing) frame, frame one is the frame that called the
|
|
|
|
innermost one, and so on. The highest-numbered frame is @code{main}'s
|
|
|
|
frame.
|
|
|
|
|
|
|
|
@item frame @var{addr}
|
|
|
|
Select the frame at address @var{addr}. This is useful mainly if the
|
|
|
|
chaining of stack frames has been damaged by a bug, making it
|
|
|
|
impossible for GDB to assign numbers properly to all frames. In
|
|
|
|
addition, this can be useful when the program has multiple stacks and
|
|
|
|
switches between them.
|
|
|
|
|
|
|
|
@item up @var{n}
|
|
|
|
@kindex up
|
|
|
|
Select the frame @var{n} frames up from the frame previously selected.
|
|
|
|
For positive numbers @var{n}, this advances toward the outermost
|
|
|
|
frame, to higher frame numbers, to frames that have existed longer.
|
|
|
|
@var{n} defaults to one.
|
|
|
|
|
|
|
|
@item down @var{n}
|
|
|
|
@kindex down
|
|
|
|
Select the frame @var{n} frames down from the frame previously
|
|
|
|
selected. For positive numbers @var{n}, this advances toward the
|
|
|
|
innermost frame, to lower frame numbers, to frames that were created
|
|
|
|
more recently. @var{n} defaults to one.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
All of these commands end by printing some information on the frame that
|
|
|
|
has been selected: the frame number, the function name, the arguments, the
|
|
|
|
source file and line number of execution in that frame, and the text of
|
|
|
|
that source line. For example:
|
|
|
|
|
|
|
|
@example
|
|
|
|
#3 main (argc=3, argv=??, env=??) at main.c, line 67
|
|
|
|
67 read_input_file (argv[i]);
|
|
|
|
@end example
|
|
|
|
|
|
|
|
After such a printout, the @samp{list} command with no arguments will print
|
|
|
|
ten lines centered on the point of execution in the frame. @xref{List}.
|
|
|
|
|
1990-12-17 18:23:17 +00:00
|
|
|
@node Frame Info, Exception Handling, Selection, Stack
|
1989-01-31 17:56:40 +00:00
|
|
|
@section Information on a Frame
|
|
|
|
|
|
|
|
There are several other commands to print information about the selected
|
|
|
|
stack frame.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item frame
|
|
|
|
This command prints a brief description of the selected stack frame.
|
|
|
|
It can be abbreviated @samp{f}. With an argument, this command is
|
|
|
|
used to select a stack frame; with no argument, it does not change
|
|
|
|
which frame is selected, but still prints the same information.
|
|
|
|
|
|
|
|
@item info frame
|
|
|
|
@kindex info frame
|
|
|
|
This command prints a verbose description of the selected stack frame,
|
|
|
|
including the address of the frame, the addresses of the next frame in
|
|
|
|
(called by this frame) and the next frame out (caller of this frame),
|
|
|
|
the address of the frame's arguments, the program counter saved in it
|
|
|
|
(the address of execution in the caller frame), and which registers
|
|
|
|
were saved in the frame. The verbose description is useful when
|
|
|
|
something has gone wrong that has made the stack format fail to fit
|
|
|
|
the usual conventions.
|
|
|
|
|
|
|
|
@item info frame @var{addr}
|
|
|
|
Print a verbose description of the frame at address @var{addr},
|
|
|
|
without selecting that frame. The selected frame remains unchanged by
|
|
|
|
this command.
|
|
|
|
|
|
|
|
@item info args
|
|
|
|
@kindex info args
|
|
|
|
Print the arguments of the selected frame, each on a separate line.
|
|
|
|
|
|
|
|
@item info locals
|
|
|
|
@kindex info locals
|
|
|
|
Print the local variables of the selected frame, each on a separate
|
|
|
|
line. These are all variables declared static or automatic within all
|
|
|
|
program blocks that execution in this frame is currently inside of.
|
|
|
|
|
1990-12-17 18:23:17 +00:00
|
|
|
@item info catch
|
|
|
|
@kindex info catch
|
|
|
|
Print a list of all the exception handlers that are active in the
|
|
|
|
current stack frame given the current value of @code{pc}. To see
|
|
|
|
other exception handlers of higher frames, visit the higher frame
|
|
|
|
(using the @samp{up} command) and type @samp{info catch}.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Exception Handling,, Frame Info, Stack
|
|
|
|
|
|
|
|
Some languages, such as GNU C++, implement exception handling. GDB
|
|
|
|
can be used to examine what caused the program to raise an exception
|
|
|
|
and to list the exceptions the program is prepared to handle at a
|
|
|
|
given point in time.
|
|
|
|
|
|
|
|
@cindex raise exceptions
|
|
|
|
GNU C++ raises an exception by calling a library function named
|
|
|
|
@code{__raise_exception} which has the following ANSI C interface:
|
|
|
|
|
|
|
|
@example
|
|
|
|
/* ADDR is where the exception identifier is stored.
|
|
|
|
ID is the exception identifier. */
|
|
|
|
void __raise_exception (void **addr, void *id);
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
By setting a breakpoint on @code{__raise_exception}
|
|
|
|
(@xref{Breakpoints}), all exceptions that a program raises will be
|
|
|
|
first caught by the debugger before any stack unwinding has taken
|
|
|
|
place. If you set a breakpoint in an exception handler instead of at
|
|
|
|
the point of the raise, you will likely not easily have the
|
|
|
|
information needed to know from where the exception was raised.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
By using a conditional breakpoint (@xref{Conditions}), you can cause
|
1990-12-17 18:23:17 +00:00
|
|
|
the debugger to stop only when a specific exception is raised.
|
|
|
|
Multiple conditional breakpoints can be used to stop the program when
|
|
|
|
any of a number of exceptions are raised.
|
|
|
|
|
|
|
|
@cindex catch exceptions
|
|
|
|
To examine the exceptions that a piece of a program is prepared to
|
|
|
|
catch, the @samp{info catch} function is used. This function shows
|
|
|
|
all exception handlers that are active in the current frame (for the
|
|
|
|
current value of the program counter). By traversing frames (using
|
|
|
|
the @samp{up} and @samp{down} commands), other exception handlers can
|
|
|
|
be observed.
|
|
|
|
|
|
|
|
Breakpoints can be set at active exception handlers by using the
|
|
|
|
@samp{catch} command. The syntax is @samp{catch @var{exceptions}},
|
|
|
|
where @var{exceptions} is a list of names of exceptions to catch.
|
|
|
|
|
|
|
|
There are currently some limitations to exception handling in GDB.
|
|
|
|
These will be corrected in a future release.
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
@item If you call a function interactively it will normally return
|
|
|
|
control to the user when it has finished executing. If the call
|
|
|
|
raises an exception however, the call may bypass the mechanism that
|
|
|
|
returns control to the user and cause the program to simply continue
|
|
|
|
running until it hits a breakpoint, catches a signal that GDB is
|
|
|
|
listening for, or exits.
|
|
|
|
@item You cannot raise an exception interactively.
|
|
|
|
@item You cannot interactively install an exception handler.
|
|
|
|
@end itemize
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@node Source, Data, Stack, Top
|
|
|
|
@chapter Examining Source Files
|
|
|
|
|
|
|
|
GDB knows which source files your program was compiled from, and
|
|
|
|
can print parts of their text. When your program stops, GDB
|
|
|
|
spontaneously prints the line it stopped in. Likewise, when you
|
|
|
|
select a stack frame (@pxref{Selection}), GDB prints the line
|
|
|
|
which execution in that frame has stopped in. You can also
|
|
|
|
print parts of source files by explicit command.
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* List:: Using the @samp{list} command to print source files.
|
|
|
|
* Search:: Commands for searching source files.
|
|
|
|
* Source Path:: Specifying the directories to search for source files.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node List, Search, Source, Source
|
|
|
|
@section Printing Source Lines
|
|
|
|
|
|
|
|
@kindex list
|
|
|
|
To print lines from a source file, use the @samp{list} command
|
|
|
|
(abbreviated @samp{l}). There are several ways to specify what part
|
|
|
|
of the file you want to print.
|
|
|
|
|
|
|
|
Here are the forms of the @samp{list} command most commonly used:
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item list @var{linenum}
|
|
|
|
Print ten lines centered around line number @var{linenum} in the
|
|
|
|
current source file.
|
|
|
|
|
|
|
|
@item list @var{function}
|
|
|
|
Print ten lines centered around the beginning of function
|
|
|
|
@var{function}.
|
|
|
|
|
|
|
|
@item list
|
|
|
|
Print ten more lines. If the last lines printed were printed with a
|
|
|
|
@samp{list} command, this prints ten lines following the last lines
|
|
|
|
printed; however, if the last line printed was a solitary line printed
|
|
|
|
as part of displaying a stack frame (@pxref{Stack}), this prints ten
|
|
|
|
lines centered around that line.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@item list -
|
1989-01-31 17:56:40 +00:00
|
|
|
Print ten lines just before the lines last printed.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
Repeating a @samp{list} command with @key{RET} discards the argument,
|
|
|
|
so it is equivalent to typing just @samp{list}. This is more useful
|
|
|
|
than listing the same lines again. An exception is made for an
|
|
|
|
argument of @samp{-}; that argument is preserved in repetition so that
|
|
|
|
each repetition moves up in the file.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex linespec
|
1989-01-31 17:56:40 +00:00
|
|
|
In general, the @samp{list} command expects you to supply zero, one or two
|
|
|
|
@dfn{linespecs}. Linespecs specify source lines; there are several ways
|
|
|
|
of writing them but the effect is always to specify some source line.
|
|
|
|
Here is a complete description of the possible arguments for @samp{list}:
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item list @var{linespec}
|
|
|
|
Print ten lines centered around the line specified by @var{linespec}.
|
|
|
|
|
|
|
|
@item list @var{first},@var{last}
|
|
|
|
Print lines from @var{first} to @var{last}. Both arguments are
|
|
|
|
linespecs.
|
|
|
|
|
|
|
|
@item list ,@var{last}
|
|
|
|
Print ten lines ending with @var{last}.
|
|
|
|
|
|
|
|
@item list @var{first},
|
|
|
|
Print ten lines starting with @var{first}.
|
|
|
|
|
|
|
|
@item list +
|
|
|
|
Print ten lines just after the lines last printed.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@item list -
|
1989-01-31 17:56:40 +00:00
|
|
|
Print ten lines just before the lines last printed.
|
|
|
|
|
|
|
|
@item list
|
|
|
|
As described in the preceding table.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
Here are the ways of specifying a single source line---all the
|
|
|
|
kinds of linespec.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@table @code
|
1989-01-31 17:56:40 +00:00
|
|
|
@item @var{linenum}
|
|
|
|
Specifies line @var{linenum} of the current source file.
|
|
|
|
When a @samp{list} command has two linespecs, this refers to
|
|
|
|
the same source file as the first linespec.
|
|
|
|
|
|
|
|
@item +@var{offset}
|
|
|
|
Specifies the line @var{offset} lines after the last line printed.
|
|
|
|
When used as the second linespec in a @samp{list} command that has
|
|
|
|
two, this specifies the line @var{offset} lines down from the
|
|
|
|
first linespec.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@item -@var{offset}
|
1989-01-31 17:56:40 +00:00
|
|
|
Specifies the line @var{offset} lines before the last line printed.
|
|
|
|
|
|
|
|
@item @var{filename}:@var{linenum}
|
|
|
|
Specifies line @var{linenum} in the source file @var{filename}.
|
|
|
|
|
|
|
|
@item @var{function}
|
|
|
|
Specifies the line of the open-brace that begins the body of the
|
|
|
|
function @var{function}.
|
|
|
|
|
|
|
|
@item @var{filename}:@var{function}
|
|
|
|
Specifies the line of the open-brace that begins the body of the
|
|
|
|
function @var{function} in the file @var{filename}. The file name is
|
|
|
|
needed with a function name only for disambiguation of identically
|
|
|
|
named functions in different source files.
|
|
|
|
|
|
|
|
@item *@var{address}
|
|
|
|
Specifies the line containing the program address @var{address}.
|
|
|
|
@var{address} may be any expression.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
One other command is used to map source lines to program addresses.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item info line @var{linenum}
|
|
|
|
@kindex info line
|
|
|
|
Print the starting and ending addresses of the compiled code for
|
|
|
|
source line @var{linenum}.
|
|
|
|
|
|
|
|
@kindex $_
|
|
|
|
The default examine address for the @samp{x} command is changed to the
|
|
|
|
starting address of the line, so that @samp{x/i} is sufficient to
|
|
|
|
begin examining the machine code (@pxref{Memory}). Also, this address
|
1989-09-30 00:00:00 +00:00
|
|
|
is saved as the value of the convenience variable @code{$_}
|
1989-01-31 17:56:40 +00:00
|
|
|
(@pxref{Convenience Vars}).
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Search, Source Path, List, Source
|
|
|
|
@section Searching Source Files
|
|
|
|
@cindex searching
|
|
|
|
@kindex forward-search
|
|
|
|
@kindex reverse-search
|
|
|
|
|
|
|
|
There are two commands for searching through the current source file for a
|
|
|
|
regular expression.
|
|
|
|
|
|
|
|
The command @samp{forward-search @var{regexp}} checks each line, starting
|
|
|
|
with the one following the last line listed, for a match for @var{regexp}.
|
|
|
|
It lists the line that is found. You can abbreviate the command name
|
|
|
|
as @samp{fo}.
|
|
|
|
|
|
|
|
The command @samp{reverse-search @var{regexp}} checks each line, starting
|
|
|
|
with the one before the last line listed and going backward, for a match
|
|
|
|
for @var{regexp}. It lists the line that is found. You can abbreviate
|
|
|
|
this command with as little as @samp{rev}.
|
|
|
|
|
|
|
|
@node Source Path,, Search, Source
|
|
|
|
@section Specifying Source Directories
|
|
|
|
|
|
|
|
@cindex source path
|
|
|
|
@cindex directories for source files
|
1990-12-17 18:23:17 +00:00
|
|
|
Executable programs sometimes do not record the directories of the source
|
|
|
|
files from which they were compiled, just the names. Even when they do,
|
|
|
|
the directories could be moved between the compilation and your debugging
|
|
|
|
session. GDB remembers a list of directories to search for source files;
|
|
|
|
this is called the @dfn{source path}. Each time GDB wants a 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 name. @b{Note that
|
|
|
|
the executable search path is @i{not} used for this purpose. Neither is
|
|
|
|
the current working directory, unless it happens to be in the source
|
|
|
|
path.}
|
1990-12-13 17:32:56 +00:00
|
|
|
|
|
|
|
If it can't find a source file in the source path, and the object program
|
|
|
|
records what directory it was compiled in, GDB tries that directory too.
|
|
|
|
If the source path is empty, and there is no record of the compilation
|
|
|
|
directory, GDB will, as a last resort, look in the current directory.
|
|
|
|
|
|
|
|
Whenever you reset or rearrange the source path, GDB will clear out
|
|
|
|
any information it has cached about where source files are found, where
|
|
|
|
each line is in the file, etc.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@kindex directory
|
1990-12-13 17:32:56 +00:00
|
|
|
When you start GDB, its source path is empty.
|
|
|
|
To add other directories, use the @samp{directory} command.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@table @code
|
1989-09-30 00:00:00 +00:00
|
|
|
@item directory @var{dirnames...}
|
1990-12-13 17:32:56 +00:00
|
|
|
Add directory @var{dirname} to the front of the source path. Several
|
1989-09-30 00:00:00 +00:00
|
|
|
directory names may be given to this command, separated by whitespace or
|
1990-12-13 17:32:56 +00:00
|
|
|
@samp{:}. If a name is already in the source path, it is moved to the
|
|
|
|
front of the path, so it will be searched sooner.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item directory
|
1990-12-13 17:32:56 +00:00
|
|
|
Reset the source path to empty again. This requires confirmation.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item info directories
|
|
|
|
@kindex info directories
|
|
|
|
Print the source path: show which directories it contains.
|
|
|
|
@end table
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
Because the @samp{directory} command, when used with arguments, adds to
|
|
|
|
the front of the source path, it can affect files that GDB has already
|
|
|
|
found. If the source path contains directories that you do not want,
|
|
|
|
and these directories contain misleading files with names matching your
|
|
|
|
source files, the way to correct the situation is as follows:
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@enumerate
|
|
|
|
@item
|
1990-12-13 17:32:56 +00:00
|
|
|
Use @samp{directory} with no argument to reset the source path to empty.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item
|
|
|
|
Use @samp{directory} with suitable arguments to add any other
|
1990-12-13 17:32:56 +00:00
|
|
|
directories you want in the source path. You can add all the directories
|
|
|
|
in one command.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end enumerate
|
|
|
|
|
|
|
|
@node Data, Symbols, Source, Top
|
|
|
|
@chapter Examining Data
|
|
|
|
|
|
|
|
@cindex printing data
|
|
|
|
@cindex examining data
|
|
|
|
@kindex print
|
1989-09-30 00:00:00 +00:00
|
|
|
The usual way to examine data in your program is with the @samp{print}
|
1989-01-31 17:56:40 +00:00
|
|
|
command (abbreviated @samp{p}). It evaluates and prints the value of any
|
1990-12-19 13:30:35 +00:00
|
|
|
valid expression of the language the program is written in (for now, C
|
|
|
|
or C++).
|
1989-01-31 17:56:40 +00:00
|
|
|
You type
|
|
|
|
|
|
|
|
@example
|
|
|
|
print @var{exp}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
1990-12-19 13:30:35 +00:00
|
|
|
where @var{exp} is any valid expression (in the source language), and
|
|
|
|
the value of @var{exp} is printed in a format appropriate to its data
|
|
|
|
type.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
A more low-level way of examining data is with the @samp{x} command.
|
|
|
|
It examines data in memory at a specified address and prints it in a
|
|
|
|
specified format.
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Expressions:: Expressions that can be computed and printed.
|
|
|
|
* Variables:: Using your program's variables in expressions.
|
|
|
|
* Assignment:: Setting your program's variables.
|
|
|
|
* Arrays:: Examining part of memory as an array.
|
1989-09-30 00:00:00 +00:00
|
|
|
* Format Options:: Controlling how structures and arrays are printed.
|
|
|
|
* Output formats:: Specifying formats for printing values.
|
1989-01-31 17:56:40 +00:00
|
|
|
* Memory:: Examining memory explicitly.
|
|
|
|
* Auto Display:: Printing certain expressions whenever program stops.
|
|
|
|
* Value History:: Referring to values previously printed.
|
|
|
|
* Convenience Vars:: Giving names to values for future reference.
|
|
|
|
* Registers:: Referring to and storing in machine registers.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Expressions, Variables, Data, Data
|
|
|
|
@section Expressions
|
|
|
|
|
|
|
|
@cindex expressions
|
|
|
|
Many different GDB commands accept an expression and compute its value.
|
|
|
|
Any kind of constant, variable or operator defined by the programming
|
|
|
|
language you are using is legal in an expression in GDB. This includes
|
|
|
|
conditional expressions, function calls, casts and string constants.
|
|
|
|
It unfortunately does not include symbols defined by preprocessor
|
1989-09-30 00:00:00 +00:00
|
|
|
@code{#define} commands.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
Casts are supported in all languages, not just in C, because it is so
|
|
|
|
useful to cast a number into a pointer so as to examine a structure
|
|
|
|
at that address in memory.
|
|
|
|
|
|
|
|
GDB supports three kinds of operator in addition to those of programming
|
|
|
|
languages:
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item @@
|
|
|
|
@samp{@@} is a binary operator for treating parts of memory as arrays.
|
|
|
|
@xref{Arrays}, for more information.
|
|
|
|
|
|
|
|
@item ::
|
|
|
|
@samp{::} allows you to specify a variable in terms of the file or
|
|
|
|
function it is defined in. @xref{Variables}.
|
|
|
|
|
|
|
|
@item @{@var{type}@} @var{addr}
|
|
|
|
Refers to an object of type @var{type} stored at address @var{addr} in
|
|
|
|
memory. @var{addr} may be any expression whose value is an integer or
|
|
|
|
pointer (but parentheses are required around nonunary operators, just as in
|
|
|
|
a cast). This construct is allowed regardless of what kind of data is
|
|
|
|
officially supposed to reside at @var{addr}.@refill
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Variables, Arrays, Expressions, Data
|
|
|
|
@section Program Variables
|
|
|
|
|
|
|
|
The most common kind of expression to use is the name of a variable
|
|
|
|
in your program.
|
|
|
|
|
|
|
|
Variables in expressions are understood in the selected stack frame
|
|
|
|
(@pxref{Selection}); they must either be global (or static) or be visible
|
|
|
|
according to the scope rules of the programming language from the point of
|
|
|
|
execution in that frame. This means that in the function
|
|
|
|
|
|
|
|
@example
|
|
|
|
foo (a)
|
|
|
|
int a;
|
|
|
|
@{
|
|
|
|
bar (a);
|
|
|
|
@{
|
|
|
|
int b = test ();
|
|
|
|
bar (b);
|
|
|
|
@}
|
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
the variable @code{a} is usable whenever the program is executing
|
|
|
|
within the function @code{foo}, but the variable @code{b} is visible
|
|
|
|
only while the program is executing inside the block in which @code{b}
|
|
|
|
is declared.
|
|
|
|
|
|
|
|
As a special exception, you can refer to a variable or function whose
|
|
|
|
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 function with the same name (if they are in different source files).
|
|
|
|
In such a case, it is not defined which one you will get. If you wish,
|
|
|
|
you can specify any one of them using the colon-colon construct:
|
|
|
|
|
|
|
|
@example
|
|
|
|
@var{block}::@var{variable}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
Here @var{block} is the name of the source file whose variable you want.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Arrays, Format options, Variables, Data
|
1989-01-31 17:56:40 +00:00
|
|
|
@section Artificial Arrays
|
|
|
|
|
|
|
|
@cindex artificial array
|
|
|
|
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 determined size for which only a pointer exists in the
|
|
|
|
program.
|
|
|
|
|
|
|
|
This can be done by constructing an @dfn{artificial array} with the
|
|
|
|
binary operator @samp{@@}. The left operand of @samp{@@} should be
|
|
|
|
the first element of the desired array, as an individual object.
|
|
|
|
The right operand should be the length of 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 argument; the second element
|
|
|
|
comes from bytes of memory immediately following those that hold the
|
|
|
|
first element, and so on. Here is an example. If a program says
|
|
|
|
|
|
|
|
@example
|
|
|
|
int *array = (int *) malloc (len * sizeof (int));
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
you can print the contents of @code{array} with
|
|
|
|
|
|
|
|
@example
|
|
|
|
p *array@@len
|
|
|
|
@end example
|
|
|
|
|
|
|
|
The left operand of @samp{@@} must reside in memory. Array values made
|
|
|
|
with @samp{@@} in this way behave just like other arrays in terms of
|
|
|
|
subscripting, and are coerced to pointers when used in expressions.
|
|
|
|
(It would probably appear in an expression via the value history,
|
|
|
|
after you had printed it out.)
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Format options, Output formats, Arrays, Data
|
|
|
|
@section Format options
|
|
|
|
|
|
|
|
@cindex format options
|
|
|
|
GDB provides a few ways to control how arrays and structures are
|
|
|
|
printed.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item info format
|
|
|
|
@kindex info format
|
|
|
|
Display the current settings for the format options.
|
|
|
|
|
|
|
|
@item set array-max @var{number-of-elements}
|
|
|
|
@kindex set array-max
|
|
|
|
If GDB is printing a large array, it will stop printing after it has
|
|
|
|
printed the number of elements set by the @samp{set array-max} command.
|
|
|
|
This limit also applies to the display of strings.
|
|
|
|
|
1990-11-09 18:30:56 +00:00
|
|
|
@item set arrayprint
|
|
|
|
@itemx set arrayprint on
|
|
|
|
@kindex set arrayprint
|
|
|
|
GDB will pretty print arrays. This format is more convenient to read,
|
|
|
|
but uses more space. The default is off.
|
|
|
|
|
|
|
|
@item set arrayprint off.
|
|
|
|
Return to compressed format for arrays.
|
|
|
|
|
|
|
|
@item set vtblprint
|
|
|
|
@itemx set vtblprint on
|
1990-12-19 13:30:35 +00:00
|
|
|
@kindex set vtblprint
|
1990-11-09 18:30:56 +00:00
|
|
|
|
|
|
|
Pretty print C++ virtual function tables. The default is off.
|
|
|
|
|
|
|
|
@item set vtblprint off
|
|
|
|
Do not pretty print C++ virtual arrays.
|
|
|
|
|
|
|
|
@item set addressprint
|
|
|
|
@item set adressprint on
|
|
|
|
@kindex set addressprint
|
|
|
|
GDB will print memory addresses in stack traces and structure values.
|
|
|
|
The default is on.
|
|
|
|
|
|
|
|
@item set addressprint off
|
|
|
|
Do not print addresses.
|
|
|
|
|
|
|
|
GDB will pretty print C++ virtual function tables. The default is off.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@item set prettyprint on
|
|
|
|
@kindex set prettyprint
|
|
|
|
Cause GDB to print structures in an indented format with one member per
|
|
|
|
line, like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
$1 = @{
|
|
|
|
next = 0x0,
|
|
|
|
flags = @{
|
|
|
|
sweet = 1,
|
|
|
|
sour = 1
|
|
|
|
@},
|
|
|
|
meat = 0x54 "Pork"
|
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@item set prettyprint off
|
|
|
|
Cause GDB to print structures in a compact format, like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat = 0x54 "Pork"@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
This is the default format.
|
|
|
|
|
|
|
|
@item set unionprint on
|
|
|
|
@kindex set unionprint
|
|
|
|
Tell GDB to print unions which are contained in structures. This is the
|
|
|
|
default setting.
|
|
|
|
@item set unionprint off
|
|
|
|
Tell GDB not to print unions which are contained in structures.
|
|
|
|
|
|
|
|
For example, given the declarations
|
|
|
|
|
|
|
|
@example
|
|
|
|
typedef enum @{Tree, Bug@} Species;
|
|
|
|
typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
|
1990-12-19 13:30:35 +00:00
|
|
|
typedef enum @{Caterpillar, Cocoon, Butterfly@} Bug_forms;
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
struct thing @{
|
|
|
|
Species it;
|
|
|
|
union @{
|
|
|
|
Tree_forms tree;
|
|
|
|
Bug_forms bug;
|
|
|
|
@} form;
|
|
|
|
@};
|
|
|
|
|
|
|
|
struct thing foo = @{Tree, @{Acorn@}@};
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
with @samp{set unionprint on} in effect @samp{p foo} would print
|
|
|
|
|
|
|
|
@example
|
|
|
|
$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
and with @samp{set unionprint off} in effect it would print
|
|
|
|
|
|
|
|
@example
|
|
|
|
$1 = @{it = Tree, form = @{...@}@}
|
|
|
|
@end example
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Output formats, Memory, Format options, Data
|
|
|
|
@section Output formats
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@cindex formatted output
|
|
|
|
@cindex output formats
|
|
|
|
GDB normally prints all values according to their data types. Sometimes
|
|
|
|
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 in memory
|
|
|
|
at a certain address as a character string or an instruction. These things
|
|
|
|
can be done with @dfn{output formats}.
|
|
|
|
|
|
|
|
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
|
|
|
|
@samp{print} command with a slash and a format letter. The format
|
|
|
|
letters supported are:
|
|
|
|
|
|
|
|
@table @samp
|
|
|
|
@item x
|
|
|
|
Regard the bits of the value as an integer, and print the integer in
|
|
|
|
hexadecimal.
|
|
|
|
|
|
|
|
@item d
|
|
|
|
Print as integer in signed decimal.
|
|
|
|
|
|
|
|
@item u
|
|
|
|
Print as integer in unsigned decimal.
|
|
|
|
|
|
|
|
@item o
|
|
|
|
Print as integer in octal.
|
|
|
|
|
|
|
|
@item a
|
1990-12-19 13:30:35 +00:00
|
|
|
Print as an address, both absolute in hex and as an offset from the
|
|
|
|
nearest preceding symbol.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item c
|
|
|
|
Regard as an integer and print it as a character constant.
|
|
|
|
|
|
|
|
@item f
|
|
|
|
Regard the bits of the value as a floating point number and print
|
|
|
|
using typical floating point syntax.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
For example, to print the program counter in hex (@pxref{Registers}), type
|
|
|
|
|
|
|
|
@example
|
|
|
|
p/x $pc
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
Note that no space is required before the slash; this is because command
|
|
|
|
names in GDB cannot contain a slash.
|
|
|
|
|
|
|
|
To reprint the last value in the value history with a different format,
|
|
|
|
you can use the @samp{print} command with just a format and no
|
|
|
|
expression. For example, @samp{p/x} reprints the last value in hex.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Memory, Auto Display, Output formats, Data
|
1989-01-31 17:56:40 +00:00
|
|
|
@subsection Examining Memory
|
|
|
|
|
|
|
|
@cindex examining memory
|
|
|
|
@kindex x
|
1989-09-30 00:00:00 +00:00
|
|
|
The command @samp{x} (for `examine') can be used to examine memory
|
|
|
|
without reference to the program's data types. The format in which you
|
|
|
|
wish to examine memory is instead explicitly specified. The allowable
|
|
|
|
formats are a superset of the formats described in the previous section.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@samp{x} is followed by a slash and an output format specification,
|
|
|
|
followed by an expression for an address. The expression need not have
|
|
|
|
a pointer value (though it may); it is used as an integer, as the
|
1989-09-30 00:00:00 +00:00
|
|
|
address of a byte of memory. @xref{Expressions} for more information on
|
|
|
|
expressions. For example, @samp{x/4xw $sp} prints the four words of
|
|
|
|
memory above the stack pointer in hexadecimal.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
The output format in this case specifies both how big a unit of memory
|
|
|
|
to examine and how to print the contents of that unit. It is done
|
|
|
|
with one or two of the following letters:
|
|
|
|
|
|
|
|
These letters specify just the size of unit to examine:
|
|
|
|
|
|
|
|
@table @samp
|
|
|
|
@item b
|
|
|
|
Examine individual bytes.
|
|
|
|
|
|
|
|
@item h
|
|
|
|
Examine halfwords (two bytes each).
|
|
|
|
|
|
|
|
@item w
|
|
|
|
Examine words (four bytes each).
|
|
|
|
|
|
|
|
@cindex word
|
|
|
|
Many assemblers and cpu designers still use `word' for a 16-bit quantity,
|
|
|
|
as a holdover from specific predecessor machines of the 1970's that really
|
|
|
|
did use two-byte words. But more generally the term `word' has always
|
|
|
|
referred to the size of quantity that a machine normally operates on and
|
1989-09-30 00:00:00 +00:00
|
|
|
stores in its registers. This is 32 bits for all the machines that GDB
|
1989-01-31 17:56:40 +00:00
|
|
|
runs on.
|
|
|
|
|
|
|
|
@item g
|
|
|
|
Examine giant words (8 bytes).
|
|
|
|
@end table
|
|
|
|
|
|
|
|
These letters specify just the way to print the contents:
|
|
|
|
|
|
|
|
@table @samp
|
|
|
|
@item x
|
|
|
|
Print as integers in unsigned hexadecimal.
|
|
|
|
|
|
|
|
@item d
|
|
|
|
Print as integers in signed decimal.
|
|
|
|
|
|
|
|
@item u
|
|
|
|
Print as integers in unsigned decimal.
|
|
|
|
|
|
|
|
@item o
|
|
|
|
Print as integers in unsigned octal.
|
|
|
|
|
|
|
|
@item a
|
|
|
|
Print as an address, both absolute in hex and then relative
|
|
|
|
to a symbol defined as an address below it.
|
|
|
|
|
|
|
|
@item c
|
|
|
|
Print as character constants.
|
|
|
|
|
|
|
|
@item f
|
|
|
|
Print as floating point. This works only with sizes @samp{w} and
|
|
|
|
@samp{g}.
|
|
|
|
|
|
|
|
@item s
|
|
|
|
Print a null-terminated string of characters. The specified unit size
|
|
|
|
is ignored; instead, the unit is however many bytes it takes to reach
|
|
|
|
a null character (including the null character).
|
|
|
|
|
|
|
|
@item i
|
|
|
|
Print a machine instruction in assembler syntax (or nearly). The
|
|
|
|
specified unit size is ignored; the number of bytes in an instruction
|
|
|
|
varies depending on the type of machine, the opcode and the addressing
|
|
|
|
modes used.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
If either the manner of printing or the size of unit fails to be specified,
|
|
|
|
the default is to use the same one that was used last. If you don't want
|
|
|
|
to use any letters after the slash, you can omit the slash as well.
|
|
|
|
|
|
|
|
You can also omit the address to examine. Then the address used is
|
|
|
|
just after the last unit examined. This is why string and instruction
|
|
|
|
formats actually compute a unit-size based on the data: so that the
|
|
|
|
next string or instruction examined will start in the right place.
|
|
|
|
The @samp{print} command sometimes sets the default address for
|
|
|
|
the @samp{x} command; when the value printed resides in memory, the
|
|
|
|
default is set to examine the same location. @samp{info line} also
|
|
|
|
sets the default for @samp{x}, to the address of the start of the
|
|
|
|
machine code for the specified line and @samp{info breakpoints} sets
|
|
|
|
it to the address of the last breakpoint listed.
|
|
|
|
|
|
|
|
When you use @key{RET} to repeat an @samp{x} command, it does not repeat
|
|
|
|
exactly the same: the address specified previously (if any) is ignored, so
|
|
|
|
that the repeated command examines the successive locations in memory
|
|
|
|
rather than the same ones.
|
|
|
|
|
|
|
|
You can examine several consecutive units of memory with one command by
|
|
|
|
writing a repeat-count after the slash (before the format letters, if any).
|
|
|
|
The repeat count must be a decimal integer. It has the same effect as
|
|
|
|
repeating the @samp{x} command that many times except that the output may
|
1989-09-30 00:00:00 +00:00
|
|
|
be more compact with several units per line. For example,
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
x/10i $pc
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
1989-09-30 00:00:00 +00:00
|
|
|
prints ten instructions starting with the one to be executed next in the
|
1989-01-31 17:56:40 +00:00
|
|
|
selected frame. After doing this, you could print another ten following
|
|
|
|
instructions with
|
|
|
|
|
|
|
|
@example
|
|
|
|
x/10
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
in which the format and address are allowed to default.
|
|
|
|
|
|
|
|
@kindex $_
|
|
|
|
@kindex $__
|
|
|
|
The addresses and contents printed by the @samp{x} command are not put 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 subsequent
|
1989-09-30 00:00:00 +00:00
|
|
|
use in expressions as values of the convenience variables @code{$_} and
|
|
|
|
@code{$__}.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
After an @samp{x} command, the last address examined is available for use
|
1989-09-30 00:00:00 +00:00
|
|
|
in expressions in the convenience variable @code{$_}. The contents of that
|
|
|
|
address, as examined, are available in the convenience variable @code{$__}.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
If the @samp{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
|
|
|
|
address printed if several units were printed on the last line of output.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@kindex disassemble
|
|
|
|
The specialized command @samp{disassemble} is also provided to dump a
|
|
|
|
range of memory as machine instructions. The default memory range is
|
|
|
|
the function surrounding the program counter of the selected frame. A
|
|
|
|
single argument to this command is a program counter value; the function
|
1990-09-05 17:54:31 +00:00
|
|
|
surrounding this value will be dumped. Two arguments (separated by one
|
|
|
|
or more spaces) specify a range of addresss (first inclusive, second
|
|
|
|
exclusive) to be dumped.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@node Auto Display, Value History, Memory, Data
|
|
|
|
@section Automatic Display
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex automatic display
|
|
|
|
@cindex display of expressions
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
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 @dfn{automatic
|
|
|
|
display list} so that GDB will print its value each time the program stops.
|
|
|
|
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 automatic display looks like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
2: foo = 38
|
|
|
|
3: bar[5] = (struct hack *) 0x3804
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
showing item numbers, expressions and their current values.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
If the expression refers to local variables, then it does not make sense
|
|
|
|
outside the lexical context for which it was set up. Such an expression
|
1990-12-19 13:30:35 +00:00
|
|
|
is disabled when execution enters a context where one of its variables
|
|
|
|
is not defined. For example, if you give the command
|
|
|
|
@samp{display name} while inside a function with an argument
|
|
|
|
@code{name}, then this argument will be displayed while the program
|
|
|
|
continues to stop inside that function. When it stops elsewhere---where
|
|
|
|
there is no variable @samp{name}---display is disabled. The next time
|
|
|
|
your program stops where @samp{name} is meaningful, you can enable the
|
|
|
|
display expression once again.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@table @code
|
|
|
|
@item display @var{exp}
|
|
|
|
@kindex display
|
|
|
|
Add the expression @var{exp} to the list of expressions to display
|
|
|
|
each time the program stops. @xref{Expressions}.
|
|
|
|
|
|
|
|
@item display/@var{fmt} @var{exp}
|
|
|
|
For @var{fmt} specifying only a display format and not a size or
|
|
|
|
count, add the expression @var{exp} to the auto-display list but
|
|
|
|
arranges to display it each time in the specified format @var{fmt}.
|
|
|
|
|
|
|
|
@item display/@var{fmt} @var{addr}
|
|
|
|
For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
|
|
|
|
number of units, add the expression @var{addr} as a memory address to
|
|
|
|
be examined each time the program stops. Examining means in effect
|
|
|
|
doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}.
|
|
|
|
|
|
|
|
@item undisplay @var{dnums}@dots{}
|
1989-09-30 00:00:00 +00:00
|
|
|
@itemx delete display @var{dnums}@dots{}
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex delete display
|
1989-09-30 00:00:00 +00:00
|
|
|
@kindex undisplay
|
1989-01-31 17:56:40 +00:00
|
|
|
Remove item numbers @var{dnums} from the list of expressions to display.
|
|
|
|
|
|
|
|
@item disable display @var{dnums}@dots{}
|
|
|
|
@kindex disable display
|
1989-09-30 00:00:00 +00:00
|
|
|
Disable the display of item numbers @var{dnums}. A disabled display
|
|
|
|
item is not printed automatically, but is not forgotten. It may be
|
|
|
|
reenabled later.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item enable display @var{dnums}@dots{}
|
|
|
|
@kindex enable display
|
|
|
|
Enable display of item numbers @var{dnums}. It becomes effective once
|
|
|
|
again in auto display of its expression, until you specify otherwise.
|
|
|
|
|
|
|
|
@item display
|
|
|
|
Display the current values of the expressions on the list, just as is
|
|
|
|
done when the program stops.
|
|
|
|
|
|
|
|
@item info display
|
|
|
|
@kindex info display
|
1989-09-30 00:00:00 +00:00
|
|
|
Print the list of expressions previously set up to display
|
|
|
|
automatically, each one with its item number, but without showing the
|
|
|
|
values. This includes disabled expressions, which are marked as such.
|
|
|
|
It also includes expressions which would not be displayed right now
|
|
|
|
because they refer to automatic variables not currently available.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Value History, Convenience Vars, Auto Display, Data
|
|
|
|
@section Value History
|
|
|
|
|
|
|
|
@cindex value history
|
|
|
|
Every value printed by the @samp{print} command is saved for the entire
|
|
|
|
session in GDB's @dfn{value history} so that you can refer to it in
|
|
|
|
other expressions.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex @code{$}
|
|
|
|
@cindex @code{$$}
|
|
|
|
@cindex history number
|
1989-01-31 17:56:40 +00:00
|
|
|
The values printed are given @dfn{history numbers} for you to refer to them
|
|
|
|
by. These are successive integers starting with 1. @samp{print} shows you
|
1989-09-30 00:00:00 +00:00
|
|
|
the history number assigned to a value by printing @samp{$@var{num} = }
|
|
|
|
before the value; here @var{num} is the history number.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
To refer to any previous value, use @samp{$} followed by the value's
|
|
|
|
history number. The output printed by @samp{print} is designed to remind
|
1989-09-30 00:00:00 +00:00
|
|
|
you of this. Just @code{$} refers to the most recent value in the history,
|
|
|
|
and @code{$$} refers to the value before that.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
@example
|
|
|
|
p *$
|
|
|
|
@end example
|
|
|
|
|
|
|
|
If you have a chain of structures where the component @samp{next} points
|
1989-09-30 00:00:00 +00:00
|
|
|
to the next one, you can print the contents of the next one with this:
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
p *$.next
|
|
|
|
@end example
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@noindent
|
1989-01-31 17:56:40 +00:00
|
|
|
It might be useful to repeat this command many times by typing @key{RET}.
|
|
|
|
|
|
|
|
Note that the history records values, not expressions. If the value of
|
1989-09-30 00:00:00 +00:00
|
|
|
@code{x} is 4 and you type this command:
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
print x
|
|
|
|
set x=5
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
then the value recorded in the value history by the @samp{print} command
|
1989-09-30 00:00:00 +00:00
|
|
|
remains 4 even though the value of @code{x} has changed.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@table @code
|
1989-09-30 00:00:00 +00:00
|
|
|
@item info values
|
|
|
|
@kindex info values
|
1989-01-31 17:56:40 +00:00
|
|
|
Print the last ten values in the value history, with their item
|
|
|
|
numbers. This is like @samp{p $$9} repeated ten times, except that
|
1989-09-30 00:00:00 +00:00
|
|
|
@samp{info values} does not change the history.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@item info values @var{n}
|
1989-01-31 17:56:40 +00:00
|
|
|
Print ten history values centered on history item number @var{n}.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
@item info values +
|
|
|
|
Print ten history values just after the values last printed.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Convenience Vars, Registers, Value History, Data
|
|
|
|
@section Convenience Variables
|
|
|
|
|
|
|
|
@cindex convenience variables
|
|
|
|
GDB provides @dfn{convenience variables} that you can use within GDB to
|
|
|
|
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 convenience
|
|
|
|
variable has no effect on further execution of your program. That's why
|
|
|
|
you can use them freely.
|
|
|
|
|
|
|
|
Convenience variables have names starting with @samp{$}. Any name starting
|
|
|
|
with @samp{$} can be used for a convenience variable, unless it is one of
|
|
|
|
the predefined set of register names (@pxref{Registers}).
|
|
|
|
|
|
|
|
You can save a value in a convenience variable with an assignment
|
|
|
|
expression, just as you would set a variable in your program. Example:
|
|
|
|
|
|
|
|
@example
|
|
|
|
set $foo = *object_ptr
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
1989-09-30 00:00:00 +00:00
|
|
|
would save in @code{$foo} the value contained in the object pointed to by
|
1989-01-31 17:56:40 +00:00
|
|
|
@code{object_ptr}.
|
|
|
|
|
|
|
|
Using a convenience variable for the first time creates it; but its value
|
|
|
|
is @code{void} until you assign a new value. You can alter the value with
|
|
|
|
another assignment at any time.
|
|
|
|
|
|
|
|
Convenience variables have no fixed types. You can assign a convenience
|
|
|
|
variable any type of value, even if it already has a value of a different
|
|
|
|
type. The convenience variable as an expression has whatever type its
|
|
|
|
current value has.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item info convenience
|
|
|
|
@kindex info convenience
|
|
|
|
Print a list of convenience variables used so far, and their values.
|
|
|
|
Abbreviated @samp{i con}.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
One of the ways to use a convenience variable is as a counter to be
|
|
|
|
incremented or a pointer to be advanced. For example:
|
|
|
|
|
|
|
|
@example
|
|
|
|
set $i = 0
|
|
|
|
print bar[$i++]->contents
|
|
|
|
@i{@dots{}repeat that command by typing @key{RET}.}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Some convenience variables are created automatically by GDB and given
|
|
|
|
values likely to be useful.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@table @code
|
1989-01-31 17:56:40 +00:00
|
|
|
@item $_
|
1989-09-30 00:00:00 +00:00
|
|
|
The variable @code{$_} is automatically set by the @samp{x} command to
|
1989-01-31 17:56:40 +00:00
|
|
|
the last address examined (@pxref{Memory}). Other commands which
|
1989-09-30 00:00:00 +00:00
|
|
|
provide a default address for @samp{x} to examine also set @code{$_}
|
1989-01-31 17:56:40 +00:00
|
|
|
to that address; these commands include @samp{info line} and @samp{info
|
|
|
|
breakpoint}.
|
|
|
|
|
|
|
|
@item $__
|
1989-09-30 00:00:00 +00:00
|
|
|
The variable @code{$__} is automatically set by the @samp{x} command
|
1989-01-31 17:56:40 +00:00
|
|
|
to the value found in the last address examined.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Registers,, Convenience Vars, Data
|
|
|
|
@section Registers
|
|
|
|
|
|
|
|
@cindex registers
|
|
|
|
Machine register contents can be referred to in expressions as variables
|
|
|
|
with names starting with @samp{$}. The names of registers are different
|
|
|
|
for each machine; use @samp{info registers} to see the names used on your
|
1989-09-30 00:00:00 +00:00
|
|
|
machine. The names @code{$pc} and @code{$sp} are used on all machines for
|
|
|
|
the program counter register and the stack pointer. Often @code{$fp} is
|
|
|
|
used for a register that contains a pointer to the current stack frame,
|
|
|
|
and @code{$ps} is used for a register that contains the processor
|
|
|
|
status. These standard register names may be available on your machine
|
|
|
|
even though the @code{info registers} command displays them with a
|
|
|
|
different name. For example, on the SPARC, @code{info registers}
|
|
|
|
displays the processor status register as @code{$psr} but you can also
|
|
|
|
refer to it as @code{$ps}.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
GDB always considers the contents of an ordinary register as an integer
|
|
|
|
when the register is examined in this way. Some machines have special
|
|
|
|
registers which can hold nothing but floating point; these registers are
|
|
|
|
considered floating point. There is no way to refer to the contents of an
|
|
|
|
ordinary register as floating point value (although you can @emph{print}
|
|
|
|
it as a floating point value with @samp{print/f $@var{regname}}).
|
|
|
|
|
|
|
|
Some registers have distinct ``raw'' and ``virtual'' data formats. This
|
|
|
|
means that the data format in which the register contents are saved by the
|
|
|
|
operating system is not the same one that your program normally sees. For
|
|
|
|
example, the registers of the 68881 floating point coprocessor are always
|
1989-09-30 00:00:00 +00:00
|
|
|
saved in ``extended'' format, but all C programs expect to work with
|
1989-01-31 17:56:40 +00:00
|
|
|
``double'' format. In such cases, GDB normally works with the virtual
|
|
|
|
format only (the format that makes sense for your program), but the
|
|
|
|
@samp{info registers} command prints the data in both formats.
|
|
|
|
|
|
|
|
Register values are relative to the selected stack frame
|
|
|
|
(@pxref{Selection}). This means that you get the value that the register
|
|
|
|
would contain if all stack frames farther in were exited and their saved
|
|
|
|
registers restored. In order to see the real contents of all registers,
|
|
|
|
you must select the innermost frame (with @samp{frame 0}).
|
|
|
|
|
|
|
|
Some registers are never saved (typically those numbered zero or one)
|
|
|
|
because they are used for returning function values; for these registers,
|
|
|
|
relativization makes no difference.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item info registers
|
|
|
|
@kindex info registers
|
|
|
|
Print the names and relativized values of all registers.
|
|
|
|
|
|
|
|
@item info registers @var{regname}
|
|
|
|
Print the relativized value of register @var{regname}. @var{regname}
|
|
|
|
may be any register name valid on the machine you are using, with
|
|
|
|
or without the initial @samp{$}.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@subsection Examples
|
|
|
|
|
|
|
|
You could print the program counter in hex with
|
|
|
|
|
|
|
|
@example
|
|
|
|
p/x $pc
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
or print the instruction to be executed next with
|
|
|
|
|
|
|
|
@example
|
|
|
|
x/i $pc
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
or add four to the stack pointer with
|
|
|
|
|
|
|
|
@example
|
|
|
|
set $sp += 4
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
The last is a way of removing one word from the stack, on machines where
|
|
|
|
stacks grow downward in memory (most machines, nowadays). This assumes
|
1989-09-30 00:00:00 +00:00
|
|
|
that the innermost stack frame is selected. Setting @code{$sp} is
|
1989-01-31 17:56:40 +00:00
|
|
|
not allowed when other stack frames are selected.
|
|
|
|
|
|
|
|
@node Symbols, Altering, Data, Top
|
|
|
|
@chapter Examining the Symbol Table
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
The commands described in this section allow you to inquire about the
|
|
|
|
symbols (names of variables, functions and types) defined in your
|
|
|
|
program. This information is found by GDB in the symbol table loaded by
|
|
|
|
the @samp{symbol-file} command; it is inherent in the text of your
|
|
|
|
program and does not change as the program executes.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item info address @var{symbol}
|
|
|
|
@kindex info address
|
1989-09-30 00:00:00 +00:00
|
|
|
Describe where the data for @var{symbol} is stored. For a register
|
|
|
|
variable, this says which register it is kept in. For a non-register
|
|
|
|
local variable, this prints the stack-frame offset at which the variable
|
|
|
|
is always stored.
|
|
|
|
|
|
|
|
Note the contrast with @samp{print &@var{symbol}}, which does not work
|
|
|
|
at all for a register variables, and for a stack local variable prints
|
|
|
|
the exact address of the current instantiation of the variable.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1990-09-05 17:54:31 +00:00
|
|
|
@item whatis @var{exp}
|
|
|
|
@kindex whatis
|
|
|
|
Print the data type of expression @var{exp}. @var{exp} is not
|
|
|
|
actually evaluated, and any side-effecting operations (such as
|
|
|
|
assignments or function calls) inside it do not take place.
|
|
|
|
@xref{Expressions}.
|
|
|
|
|
|
|
|
@item whatis
|
|
|
|
Print the data type of @code{$}, the last value in the value history.
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@item ptype @var{typename}
|
|
|
|
@kindex ptype
|
|
|
|
Print a description of data type @var{typename}. @var{typename} may be
|
|
|
|
the name of a type, or for C code it may have the form
|
|
|
|
@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
|
|
|
|
@samp{enum @var{enum-tag}}.@refill
|
|
|
|
|
1990-09-05 17:54:31 +00:00
|
|
|
@item ptype @var{exp}
|
|
|
|
Print a description of the type of expression @var{exp}. This is like
|
|
|
|
@samp{whatis} except it prints a detailed description, instead of just
|
|
|
|
the name of the type. For example, if the type of a variable is
|
|
|
|
@samp{struct complex @{double real; double imag;@}}, @samp{whatis} will
|
|
|
|
print @samp{struct complex} and @samp{ptype} will print @samp{struct
|
|
|
|
complex @{double real; double imag;@}}
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@item info sources
|
|
|
|
@kindex info sources
|
|
|
|
Print the names of all source files in the program for which there
|
|
|
|
is debugging information.
|
|
|
|
|
|
|
|
@item info functions
|
|
|
|
@kindex info functions
|
|
|
|
Print the names and data types of all defined functions.
|
|
|
|
|
|
|
|
@item info functions @var{regexp}
|
|
|
|
Print the names and data types of all defined functions
|
|
|
|
whose names contain a match for regular expression @var{regexp}.
|
|
|
|
Thus, @samp{info fun step} finds all functions whose names
|
|
|
|
include @samp{step}; @samp{info fun ^step} finds those whose names
|
|
|
|
start with @samp{step}.
|
|
|
|
|
|
|
|
@item info variables
|
|
|
|
@kindex info variables
|
|
|
|
Print the names and data types of all variables that are declared
|
1989-09-30 00:00:00 +00:00
|
|
|
outside of functions (i.e., except for local variables).
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item info variables @var{regexp}
|
1989-09-30 00:00:00 +00:00
|
|
|
Print the names and data types of all variables (except for local
|
|
|
|
variables) whose names contain a match for regular expression
|
1989-01-31 17:56:40 +00:00
|
|
|
@var{regexp}.
|
|
|
|
|
|
|
|
|
1990-02-08 06:14:00 +00:00
|
|
|
@ignore
|
|
|
|
This was never implemented.
|
1989-01-31 17:56:40 +00:00
|
|
|
@item info methods
|
1989-09-30 00:00:00 +00:00
|
|
|
@itemx info methods @var{regexp}
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex info methods
|
|
|
|
The @samp{info-methods} command permits the user to examine all defined
|
1989-09-30 00:00:00 +00:00
|
|
|
methods within C++ program, or (with the @var{regexp} argument) a
|
|
|
|
specific set of methods found in the various C++ classes. Many
|
|
|
|
C++ classes provide a large number of methods. Thus, the output
|
|
|
|
from the @samp{ptype} command can be overwhelming and hard to use. The
|
|
|
|
@samp{info-methods} command filters the methods, printing only those
|
|
|
|
which match the regular-expression @var{regexp}.
|
1990-02-08 06:14:00 +00:00
|
|
|
@end ignore
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item printsyms @var{filename}
|
|
|
|
@kindex printsyms
|
|
|
|
Write a complete dump of the debugger's symbol data into the
|
|
|
|
file @var{filename}.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Altering, Sequences, Symbols, Top
|
|
|
|
@chapter Altering Execution
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
Once you think you have found an error in the program, you might want to
|
1989-09-30 00:00:00 +00:00
|
|
|
find out for certain whether correcting the apparent error would lead to
|
|
|
|
correct results in the rest of the run. You can find the answer by
|
|
|
|
experiment, using the GDB features for altering execution of the
|
|
|
|
program.
|
|
|
|
|
|
|
|
For example, you can store new values into variables or memory
|
|
|
|
locations, give the program a signal, restart it at a different address,
|
|
|
|
or even return prematurely from a function to its caller.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@menu
|
|
|
|
* Assignment:: Altering variable values or memory contents.
|
|
|
|
* Jumping:: Altering control flow.
|
|
|
|
* Signaling:: Making signals happen in the program.
|
|
|
|
* Returning:: Making a function return prematurely.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Assignment, Jumping, Altering, Altering
|
|
|
|
@section Assignment to Variables
|
|
|
|
|
|
|
|
@cindex assignment
|
|
|
|
@cindex setting variables
|
|
|
|
To alter the value of a variable, evaluate an assignment expression.
|
|
|
|
@xref{Expressions}. For example,
|
|
|
|
|
|
|
|
@example
|
|
|
|
print x=4
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
would store the value 4 into the variable @code{x}, and then print
|
|
|
|
the value of the assignment expression (which is 4).
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
All the assignment operators of C are supported, including the
|
|
|
|
incrementation operators @samp{++} and @samp{--}, and combining
|
|
|
|
assignments such as @samp{+=} and @samp{<<=}.
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@kindex set
|
|
|
|
@kindex set variable
|
|
|
|
If you are not interested in seeing the value of the assignment, use the
|
|
|
|
@samp{set} command instead of the @samp{print} command. @samp{set} is
|
|
|
|
really the same as @samp{print} except that the expression's value is not
|
|
|
|
printed and is not put in the value history (@pxref{Value History}). The
|
|
|
|
expression is evaluated only for side effects.
|
|
|
|
|
|
|
|
Note that if the beginning of the argument string of the @samp{set} command
|
|
|
|
appears identical to a @samp{set} subcommand, it may be necessary to use
|
|
|
|
the @samp{set variable} command. This command is identical to @samp{set}
|
|
|
|
except for its lack of subcommands.
|
|
|
|
|
|
|
|
GDB allows more implicit conversions in assignments than C does; you can
|
|
|
|
freely store an integer value into a pointer variable or vice versa, and
|
|
|
|
any structure can be converted to any other structure that is the same
|
|
|
|
length or shorter.
|
1990-12-19 13:30:35 +00:00
|
|
|
@comment FIXME: how do structs align/pad in these conversions?
|
|
|
|
@comment /pesch@cygnus.com 18dec1990
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
|
1989-01-31 17:56:40 +00:00
|
|
|
construct to generate a value of specified type at a specified address
|
1989-09-30 00:00:00 +00:00
|
|
|
(@pxref{Expressions}). For example, @code{@{int@}0x83040} would refer
|
|
|
|
to memory location 0x83040 as an integer (which implies a certain size
|
|
|
|
and representation in memory), and
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
set @{int@}0x83040 = 4
|
|
|
|
@end example
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
would store the value 4 into that memory location.
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@node Jumping, Signaling, Assignment, Altering
|
|
|
|
@section Continuing at a Different Address
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
Ordinarily, when you continue the program, you do so at the place where
|
|
|
|
it stopped, with the @samp{cont} command. You can instead continue at
|
|
|
|
an address of your own choosing, with the following commands:
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@table @code
|
|
|
|
@item jump @var{linenum}
|
|
|
|
@kindex jump
|
|
|
|
Resume execution at line number @var{linenum}. Execution may stop
|
|
|
|
immediately if there is a breakpoint there.
|
|
|
|
|
|
|
|
The @samp{jump} command does not change the current stack frame, or
|
|
|
|
the stack pointer, or the contents of any memory location or any
|
|
|
|
register other than the program counter. If line @var{linenum} is in
|
|
|
|
a different function from the one currently executing, the results may
|
1989-09-30 00:00:00 +00:00
|
|
|
be bizarre if the two functions expect different patterns of arguments or
|
1989-01-31 17:56:40 +00:00
|
|
|
of local variables. For this reason, the @samp{jump} command requests
|
|
|
|
confirmation if the specified line is not in the function currently
|
1989-09-30 00:00:00 +00:00
|
|
|
executing. However, even bizarre results are predictable based on
|
|
|
|
careful study of the machine-language code of the program.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item jump *@var{address}
|
|
|
|
Resume execution at the instruction at address @var{address}.
|
|
|
|
@end table
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
You can get much the same effect as the @code{jump} command by storing a
|
|
|
|
new value into the register @code{$pc}. The difference is that this
|
|
|
|
does not start the program running; it only changes the address where it
|
|
|
|
@emph{will} run when it is continued. For example,
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
set $pc = 0x485
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
1989-09-30 00:00:00 +00:00
|
|
|
causes the next @samp{cont} command or stepping command to execute at
|
|
|
|
address 0x485, rather than at the address where the program stopped.
|
|
|
|
@xref{Stepping}.
|
|
|
|
|
|
|
|
The most common occasion to use the @samp{jump} command is when you have
|
|
|
|
stepped across a function call with @code{next}, and found that the
|
|
|
|
return value is incorrect. If all the relevant data appeared correct
|
|
|
|
before the function call, the error is probably in the function that
|
|
|
|
just returned.
|
|
|
|
|
|
|
|
In general, your next step would now be to rerun the program and execute
|
|
|
|
up to this function call, and then step into it to see where it goes
|
|
|
|
astray. But this may be time consuming. If the function did not have
|
|
|
|
significant side effects, you could get the same information by resuming
|
|
|
|
execution just before the function call and stepping through it. To do this,
|
|
|
|
first put a breakpoint on that function; then, use the @samp{jump} command
|
|
|
|
to continue on the line with the function call.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@node Signaling, Returning, Jumping, Altering
|
|
|
|
@section Giving the Program a Signal
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item signal @var{signalnum}
|
|
|
|
@kindex signal
|
1989-09-30 00:00:00 +00:00
|
|
|
Resume execution where the program stopped, but give it immediately the
|
|
|
|
signal number @var{signalnum}.
|
|
|
|
|
|
|
|
Alternatively, if @var{signalnum} is zero, continue execution without
|
|
|
|
giving a signal. This is useful when the program stopped on account of
|
|
|
|
a signal and would ordinary see the signal when resumed with the
|
|
|
|
@samp{cont} command; @samp{signal 0} causes it to resume without a
|
|
|
|
signal.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Returning,, Signaling, Altering
|
|
|
|
@section Returning from a Function
|
|
|
|
|
|
|
|
@cindex returning from a function
|
|
|
|
@kindex return
|
1989-09-30 00:00:00 +00:00
|
|
|
You can cancel execution of a function call with the @samp{return}
|
|
|
|
command. This command has the effect of discarding the selected stack
|
|
|
|
frame (and all frames within it), so that control moves to the caller of
|
|
|
|
that function. You can think of this as making the discarded frame
|
|
|
|
return prematurely.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
First select the stack frame that you wish to return from
|
1989-09-30 00:00:00 +00:00
|
|
|
(@pxref{Selection}). Then type the @samp{return} command. If you wish
|
|
|
|
to specify the value to be returned, give that as an argument.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
This pops the selected stack frame (and any other frames inside of it),
|
|
|
|
leaving its caller as the innermost remaining frame. That frame becomes
|
|
|
|
selected. The specified value is stored in the registers used for
|
|
|
|
returning values of functions.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
The @samp{return} command does not resume execution; it leaves the
|
|
|
|
program stopped in the state that would exist if the function had just
|
|
|
|
returned. Contrast this with the @samp{finish} command
|
|
|
|
(@pxref{Stepping}), which resumes execution until the selected stack
|
|
|
|
frame returns @emph{naturally}.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Sequences, Options, Altering, Top
|
1989-01-31 17:56:40 +00:00
|
|
|
@chapter Canned Sequences of Commands
|
|
|
|
|
|
|
|
GDB provides two ways to store sequences of commands for execution as a
|
|
|
|
unit: user-defined commands and command files.
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Define:: User-defined commands.
|
|
|
|
* Command Files:: Command files.
|
|
|
|
* Output:: Controlled output commands useful in
|
|
|
|
user-defined commands and command files.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Define, Command Files, Sequences, Sequences
|
|
|
|
@section User-Defined Commands
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex user-defined command
|
1989-01-31 17:56:40 +00:00
|
|
|
A @dfn{user-defined command} is a sequence of GDB commands to which you
|
|
|
|
assign a new name as a command. This is done with the @samp{define}
|
|
|
|
command.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item define @var{commandname}
|
|
|
|
@kindex define
|
|
|
|
Define a command named @var{commandname}. If there is already a command
|
|
|
|
by that name, you are asked to confirm that you want to redefine it.
|
|
|
|
|
|
|
|
The definition of the command is made up of other GDB command lines,
|
|
|
|
which are given following the @samp{define} command. The end of these
|
|
|
|
commands is marked by a line containing @samp{end}.
|
|
|
|
|
|
|
|
@item document @var{commandname}
|
|
|
|
@kindex document
|
|
|
|
Give documentation to the user-defined command @var{commandname}. The
|
|
|
|
command @var{commandname} must already be defined. This command reads
|
|
|
|
lines of documentation just as @samp{define} reads the lines of the
|
1989-09-30 00:00:00 +00:00
|
|
|
command definition, ending with @samp{end}. After the @samp{document}
|
|
|
|
command is finished, @samp{help} on command @var{commandname} will print
|
|
|
|
the documentation you have specified.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
You may use the @samp{document} command again to change the
|
|
|
|
documentation of a command. Redefining the command with @samp{define}
|
|
|
|
does not change the documentation.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
User-defined commands do not take arguments. When they are executed, the
|
|
|
|
commands of the definition are not printed. An error in any command
|
|
|
|
stops execution of the user-defined command.
|
|
|
|
|
|
|
|
Commands that would ask for confirmation if used interactively proceed
|
|
|
|
without asking when used inside a user-defined command. Many GDB commands
|
|
|
|
that normally print messages to say what they are doing omit the messages
|
|
|
|
when used in user-defined command.
|
|
|
|
|
|
|
|
@node Command Files, Output, Define, Sequences
|
|
|
|
@section Command Files
|
|
|
|
|
|
|
|
@cindex command files
|
|
|
|
A command file for GDB is a file of lines that are GDB commands. Comments
|
|
|
|
(lines starting with @samp{#}) may also be included. An empty line in a
|
|
|
|
command file does nothing; it does not mean to repeat the last command, as
|
|
|
|
it would from the terminal.
|
|
|
|
|
|
|
|
@cindex init file
|
1989-09-30 00:00:00 +00:00
|
|
|
@cindex @file{.gdbinit}
|
1989-01-31 17:56:40 +00:00
|
|
|
When GDB starts, it automatically executes its @dfn{init files}, command
|
|
|
|
files named @file{.gdbinit}. GDB reads the init file (if any) in your home
|
|
|
|
directory and then the init file (if any) in the current working
|
|
|
|
directory. (The init files are not executed if the @samp{-nx} option
|
|
|
|
is given.) You can also request the execution of a command file with the
|
|
|
|
@samp{source} command:
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item source @var{filename}
|
|
|
|
@kindex source
|
|
|
|
Execute the command file @var{filename}.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
The lines in a command file are executed sequentially. They are not
|
|
|
|
printed as they are executed. An error in any command terminates execution
|
|
|
|
of the command file.
|
|
|
|
|
|
|
|
Commands that would ask for confirmation if used interactively proceed
|
|
|
|
without asking when used in a command file. Many GDB commands that
|
|
|
|
normally print messages to say what they are doing omit the messages
|
|
|
|
when used in a command file.
|
|
|
|
|
|
|
|
@node Output,, Command Files, Sequences
|
|
|
|
@section Commands for Controlled Output
|
|
|
|
|
|
|
|
During the execution of a command file or a user-defined command, the only
|
|
|
|
output that appears is what is explicitly printed by the commands of the
|
|
|
|
definition. This section describes three commands useful for generating
|
|
|
|
exactly the output you want.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item echo @var{text}
|
|
|
|
@kindex echo
|
1989-09-30 00:00:00 +00:00
|
|
|
@comment I don't consider backslash-space a standard C escape sequence
|
|
|
|
@comment because it's not in ANSI.
|
|
|
|
Print @var{text}. Nonprinting characters can be included in @var{text}
|
|
|
|
using C escape sequences, such as @samp{\n} to print a newline. @b{No
|
|
|
|
newline will be printed unless you specify one.} In addition to the
|
|
|
|
standard C escape sequences a backslash followed by a space stands for a
|
|
|
|
space. This is useful for outputting a string with spaces at the
|
1990-12-19 13:30:35 +00:00
|
|
|
beginning or the end, since leading and trailing spaces are otherwise
|
|
|
|
trimmed from all arguments. Thus, to print @samp{@ and foo =@ }, use the
|
|
|
|
command @samp{echo \@ and foo = \@ }.
|
|
|
|
@comment FIXME: verify hard copy actually issues enspaces for '@ '! Will this
|
|
|
|
@comment confuse texinfo?
|
1989-09-30 00:00:00 +00:00
|
|
|
|
|
|
|
A backslash at the end of @var{text} can be used, as in C, to continue
|
|
|
|
the command onto subsequent lines. For example,
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@example
|
|
|
|
echo This is some text\n\
|
|
|
|
which is continued\n\
|
|
|
|
onto several lines.\n
|
|
|
|
@end example
|
|
|
|
|
|
|
|
produces the same output as
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@example
|
1989-09-30 00:00:00 +00:00
|
|
|
echo This is some text\n
|
|
|
|
echo which is continued\n
|
|
|
|
echo onto several lines.\n
|
1989-01-31 17:56:40 +00:00
|
|
|
@end example
|
|
|
|
|
|
|
|
@item output @var{expression}
|
|
|
|
@kindex output
|
|
|
|
Print the value of @var{expression} and nothing but that value: no
|
|
|
|
newlines, no @samp{$@var{nn} = }. The value is not entered in the
|
1989-09-30 00:00:00 +00:00
|
|
|
value history either. @xref{Expressions} for more information on
|
|
|
|
expressions.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item output/@var{fmt} @var{expression}
|
|
|
|
Print the value of @var{expression} in format @var{fmt}.
|
1989-09-30 00:00:00 +00:00
|
|
|
@xref{Output formats}, for more information.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@item printf @var{string}, @var{expressions}@dots{}
|
|
|
|
@kindex printf
|
|
|
|
Print the values of the @var{expressions} under the control of
|
|
|
|
@var{string}. The @var{expressions} are separated by commas and may
|
|
|
|
be either numbers or pointers. Their values are printed as specified
|
|
|
|
by @var{string}, exactly as if the program were to execute
|
|
|
|
|
|
|
|
@example
|
|
|
|
printf (@var{string}, @var{expressions}@dots{});
|
|
|
|
@end example
|
|
|
|
|
|
|
|
For example, you can print two values in hex like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
|
|
|
|
@end example
|
|
|
|
|
|
|
|
The only backslash-escape sequences that you can use in the string are
|
|
|
|
the simple ones that consist of backslash followed by a letter.
|
|
|
|
@end table
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Options, Emacs, Sequences, Top
|
|
|
|
@chapter Options and Arguments for GDB
|
|
|
|
|
|
|
|
When you invoke GDB, you can specify arguments telling it what files to
|
|
|
|
operate on and what other things to do.
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Mode Options:: Options controlling modes of operation.
|
|
|
|
* File Options:: Options to specify files (executable, coredump, commands)
|
|
|
|
* Other Arguments:: Any other arguments without options
|
|
|
|
also specify files.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Mode Options, File Options, Options, Options
|
|
|
|
@section Mode Options
|
|
|
|
|
|
|
|
@table @samp
|
|
|
|
@item -nx
|
|
|
|
Do not execute commands from the init files @file{.gdbinit}.
|
|
|
|
Normally, the commands in these files are executed after all the
|
|
|
|
command options and arguments have been processed. @xref{Command
|
|
|
|
Files}.
|
|
|
|
|
|
|
|
@item -q
|
|
|
|
``Quiet''. Do not print the usual introductory messages.
|
|
|
|
|
|
|
|
@item -batch
|
|
|
|
Run in batch mode. Exit with code 0 after processing all the command
|
|
|
|
files specified with @samp{-x} (and @file{.gdbinit}, if not inhibited).
|
|
|
|
Exit with nonzero status if an error occurs in executing the GDB
|
|
|
|
commands in the command files.
|
|
|
|
|
|
|
|
@item -fullname
|
|
|
|
This option is used when Emacs runs GDB as a subprocess. It tells GDB
|
|
|
|
to output the full file name and line number in a standard,
|
|
|
|
recognizable fashion each time a stack frame is displayed (which
|
|
|
|
includes each time the program stops). This recognizable format looks
|
|
|
|
like two @samp{\032} characters, followed by the file name, line number
|
|
|
|
and character position separated by colons, and a newline. The
|
|
|
|
Emacs-to-GDB interface program uses the two @samp{\032} characters as
|
|
|
|
a signal to display the source code for the frame.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node File Options, Other Arguments, Mode Options, Options
|
|
|
|
@section File-specifying Options
|
|
|
|
|
|
|
|
All the options and command line arguments given are processed
|
|
|
|
in sequential order. The order makes a difference when the
|
|
|
|
@samp{-x} option is used.
|
|
|
|
|
|
|
|
@table @samp
|
|
|
|
@item -s @var{file}
|
|
|
|
Read symbol table from file @var{file}.
|
|
|
|
|
|
|
|
@item -e @var{file}
|
|
|
|
Use file @var{file} as the executable file to execute when
|
|
|
|
appropriate, and for examining pure data in conjunction with a core
|
|
|
|
dump.
|
|
|
|
|
|
|
|
@item -se @var{file}
|
|
|
|
Read symbol table from file @var{file} and use it as the executable
|
|
|
|
file.
|
|
|
|
|
|
|
|
@item -c @var{file}
|
|
|
|
Use file @var{file} as a core dump to examine.
|
|
|
|
|
|
|
|
@item -x @var{file}
|
|
|
|
Execute GDB commands from file @var{file}.
|
|
|
|
|
|
|
|
@item -d @var{directory}
|
|
|
|
Add @var{directory} to the path to search for source files.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Other Arguments,, File Options, Options
|
|
|
|
@section Other Arguments
|
|
|
|
|
|
|
|
If there are arguments to GDB that are not options or associated with
|
|
|
|
options, the first one specifies the symbol table and executable file name
|
|
|
|
(as if it were preceded by @samp{-se}) and the second one specifies a core
|
|
|
|
dump file name (as if it were preceded by @samp{-c}).
|
|
|
|
|
|
|
|
@node Emacs, Remote, Options, Top
|
1989-01-31 17:56:40 +00:00
|
|
|
@chapter Using GDB under GNU Emacs
|
|
|
|
|
1990-09-05 19:19:18 +00:00
|
|
|
@cindex emacs
|
1989-01-31 17:56:40 +00:00
|
|
|
A special interface allows you to use GNU Emacs to view (and
|
|
|
|
edit) the source files for the program you are debugging with
|
|
|
|
GDB.
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
|
|
|
|
executable file you want to debug as an argument. This command starts
|
|
|
|
GDB as a subprocess of Emacs, with input and output through a newly
|
|
|
|
created Emacs buffer.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
Using GDB under Emacs is just like using GDB normally except for two
|
|
|
|
things:
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
|
|
All ``terminal'' input and output goes through the Emacs buffer. This
|
|
|
|
applies both to GDB commands and their output, and to the input and
|
|
|
|
output done by the program you are debugging.
|
|
|
|
|
|
|
|
This is useful because it means that you can copy the text of previous
|
|
|
|
commands and input them again; you can even use parts of the output
|
|
|
|
in this way.
|
|
|
|
|
|
|
|
All the facilities of Emacs's Shell mode are available for this purpose.
|
|
|
|
|
|
|
|
@item
|
|
|
|
GDB displays source code through Emacs. Each time GDB displays a
|
|
|
|
stack frame, Emacs automatically finds the source file for that frame
|
|
|
|
and puts an arrow (@samp{=>}) at the left margin of the current line.
|
1990-12-19 13:30:35 +00:00
|
|
|
Emacs uses a separate buffer for source display, and splits the window
|
|
|
|
to show both your GDB session and the source.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
Explicit GDB @samp{list} or search commands still produce output as
|
|
|
|
usual, but you probably will have no reason to use them.
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
In the GDB I/O buffer, you can use these special Emacs commands:
|
|
|
|
|
|
|
|
@table @kbd
|
|
|
|
@item M-s
|
|
|
|
Execute to another source line, like the GDB @samp{step} command.
|
|
|
|
|
|
|
|
@item M-n
|
|
|
|
Execute to next source line in this function, skipping all function
|
|
|
|
calls, like the GDB @samp{next} command.
|
|
|
|
|
|
|
|
@item M-i
|
|
|
|
Execute one instruction, like the GDB @samp{stepi} command.
|
|
|
|
|
|
|
|
@item C-c C-f
|
|
|
|
Execute until exit from the selected stack frame, like the GDB
|
|
|
|
@samp{finish} command.
|
1989-09-30 00:00:00 +00:00
|
|
|
|
1990-02-08 06:14:00 +00:00
|
|
|
@item M-c
|
|
|
|
@comment C-c C-p in emacs 19
|
1989-09-30 00:00:00 +00:00
|
|
|
Continue execution of the program, like the GDB @samp{cont} command.
|
1990-02-08 06:14:00 +00:00
|
|
|
|
|
|
|
@item M-u
|
|
|
|
@comment C-c C-u in emacs 19
|
|
|
|
Go up the number of frames indicated by the numeric argument
|
|
|
|
(@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}),
|
|
|
|
like the GDB @samp{up} command.@refill
|
|
|
|
|
|
|
|
@item M-d
|
|
|
|
@comment C-c C-d in emacs 19
|
|
|
|
Go down the number of frames indicated by the numeric argument, like the
|
|
|
|
GDB @samp{down} command.
|
1989-01-31 17:56:40 +00:00
|
|
|
@end table
|
|
|
|
|
|
|
|
In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
|
|
|
|
tells GDB to set a breakpoint on the source line point is on.
|
|
|
|
|
|
|
|
The source files displayed in Emacs are in ordinary Emacs buffers
|
|
|
|
which are visiting the source files in the usual way. You can edit
|
|
|
|
the files with these buffers if you wish; but keep in mind that GDB
|
|
|
|
communicates with Emacs in terms of line numbers. If you add or
|
|
|
|
delete lines from the text, the line numbers that GDB knows will cease
|
|
|
|
to correspond properly to the code.
|
|
|
|
|
1990-11-09 18:30:56 +00:00
|
|
|
@kindex emacs epoch environment
|
|
|
|
@kindex epoch
|
|
|
|
@kindex inspect
|
|
|
|
|
|
|
|
Version 18 of Emacs has a built-in window system called the @samp{epoch}
|
|
|
|
environment. Users of this environment can use a new command,
|
|
|
|
@samp{inspect} which performs identically to @samp{print} except that
|
|
|
|
each value is printed in its own window.
|
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@node Remote, Commands, Emacs, Top
|
|
|
|
@chapter Remote Kernel Debugging
|
|
|
|
|
1989-11-05 21:02:37 +00:00
|
|
|
If you are trying to debug a program running on a machine that can't run
|
|
|
|
GDB in the usual way, it is often useful to use remote debugging. For
|
|
|
|
example, you might be debugging an operating system kernel, or debugging
|
|
|
|
a small system which does not have a general purpose operating system
|
|
|
|
powerful enough to run a full-featured debugger. Currently GDB supports
|
|
|
|
remote debugging over a serial connection.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
The program to be debugged on the remote machine needs to contain a
|
|
|
|
debugging device driver which talks to GDB over the serial line using the
|
|
|
|
protocol described below. The same version of GDB that is used ordinarily
|
1989-11-05 21:02:37 +00:00
|
|
|
can be used for this. Several sample remote debugging drivers are
|
|
|
|
distributed with GDB; see the @file{README} file in the GDB distribution for
|
|
|
|
more information.
|
1989-01-31 17:56:40 +00:00
|
|
|
|
|
|
|
@menu
|
|
|
|
* Remote Commands:: Commands used to start and finish remote debugging.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
For details of the communication protocol, see the comments in the GDB
|
|
|
|
source file @file{remote.c}.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@node Remote Commands, GDB Bugs, Remote, Remote
|
1989-01-31 17:56:40 +00:00
|
|
|
@section Commands for Remote Debugging
|
|
|
|
|
|
|
|
To start remote debugging, first run GDB and specify as an executable file
|
|
|
|
the program that is running in the remote machine. This tells GDB how
|
|
|
|
to find the program's symbols and the contents of its pure text. Then
|
|
|
|
establish communication using the @samp{attach} command with a device
|
|
|
|
name rather than a pid as an argument. For example:
|
|
|
|
|
|
|
|
@example
|
|
|
|
attach /dev/ttyd
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
if the serial line is connected to the device named @file{/dev/ttyd}. This
|
|
|
|
will stop the remote machine if it is not already stopped.
|
|
|
|
|
|
|
|
Now you can use all the usual commands to examine and change data and to
|
|
|
|
step and continue the remote program.
|
|
|
|
|
|
|
|
To resume the remote program and stop debugging it, use the @samp{detach}
|
|
|
|
command.
|
|
|
|
|
1990-12-19 13:30:35 +00:00
|
|
|
@node GDB Bugs, , Remote Commands, Top
|
|
|
|
@comment node-name, next, previous, up
|
|
|
|
@chapter Reporting Bugs in GDB
|
|
|
|
@cindex Bugs in GDB
|
|
|
|
@cindex Reporting Bugs in GDB
|
|
|
|
|
|
|
|
Your bug reports play an essential role in making GDB reliable.
|
|
|
|
|
|
|
|
Reporting a bug may help you by bringing a solution to your problem, or it
|
|
|
|
may not. But in any case the important function of a bug report is to help
|
|
|
|
the entire community by making the next version of GDB work better. Bug
|
|
|
|
reports are your contribution to the maintenance of GDB.
|
|
|
|
|
|
|
|
In order for a bug report to serve its purpose, you must include the
|
|
|
|
information that makes for fixing the bug.
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Criteria: Bug Criteria. Have you really found a bug?
|
|
|
|
* Reporting: Bug Reporting. How to report a bug effectively.
|
|
|
|
* Known: Trouble. Known problems.
|
|
|
|
* Help: Service. Where to ask for help.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Bug Criteria, Bug Reporting, Bugs, Bugs
|
|
|
|
@section Have You Found a Bug?
|
|
|
|
@cindex Bug Criteria
|
|
|
|
|
|
|
|
If you are not sure whether you have found a bug, here are some guidelines:
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
|
|
@cindex Fatal Signal
|
|
|
|
@cindex Core Dump
|
|
|
|
If the debugger gets a fatal signal, for any input whatever, that is a
|
|
|
|
GDB bug. Reliable debuggers never crash.
|
|
|
|
|
|
|
|
@item
|
|
|
|
@cindex error on Valid Input
|
|
|
|
If GDB produces an error message for valid input, that is a bug.
|
|
|
|
|
|
|
|
@item
|
|
|
|
@cindex Invalid Input
|
|
|
|
If GDB does not produce an error message for invalid input,
|
|
|
|
that is a bug. However, you should note that your idea of
|
|
|
|
``invalid input'' might be my idea of ``an extension'' or ``support
|
|
|
|
for traditional practice''.
|
|
|
|
|
|
|
|
@item
|
|
|
|
If you are an experienced user of debugging tools, your suggestions
|
|
|
|
for improvement of GDB are welcome in any case.
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
@node Bug Reporting,, Bug Criteria, Bugs
|
|
|
|
@section How to Report Bugs
|
|
|
|
@cindex Bug Reports
|
|
|
|
@cindex Compiler Bugs, Reporting
|
|
|
|
|
|
|
|
Send bug reports for GDB to one of these addresses:
|
|
|
|
|
|
|
|
@example
|
|
|
|
bug-gdb@@prep.ai.mit.edu
|
|
|
|
@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@strong{Do not send bug reports to @samp{info-gdb}, or to any
|
|
|
|
newsgroups.} Most users of GDB do not want to receive bug reports.
|
|
|
|
Those that do, have asked to be on @samp{bug-gcc}.
|
|
|
|
|
|
|
|
The mailing list @samp{bug-gcc} has a newsgroup which serves as a
|
|
|
|
repeater. The mailing list and the newsgroup carry exactly the same
|
|
|
|
messages. Often people think of posting bug reports to the newsgroup
|
|
|
|
instead of mailing them. This appears to work, but it has one problem
|
|
|
|
which can be crucial: a newsgroup posting does not contain a mail path
|
|
|
|
back to the sender. Thus, if I need to ask for more information, I
|
|
|
|
may be unable to reach you. For this reason, it is better to send bug
|
|
|
|
reports to the mailing list.
|
|
|
|
|
|
|
|
As a last resort, send bug reports on paper to:
|
|
|
|
|
|
|
|
@example
|
|
|
|
GNU Debugger Bugs
|
|
|
|
545 Tech Sq
|
|
|
|
Cambridge, MA 02139
|
|
|
|
@end example
|
|
|
|
|
|
|
|
The fundamental principle of reporting bugs usefully is this:
|
|
|
|
@strong{report all the facts}. If you are not sure whether to state a
|
|
|
|
fact or leave it out, state it!
|
|
|
|
|
|
|
|
Often people omit facts because they think they know what causes the
|
|
|
|
problem and they conclude that some details don't matter. Thus, you might
|
|
|
|
assume that the name of the variable you use in an example does not matter.
|
|
|
|
Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
|
|
|
|
stray memory reference which happens to fetch from the location where that
|
|
|
|
name is stored in memory; perhaps, if the name were different, the contents
|
|
|
|
of that location would fool the debugger into doing the right thing despite
|
|
|
|
the bug. Play it safe and give a specific, complete example. That is the
|
|
|
|
easiest thing for you to do, and the most helpful.
|
|
|
|
|
|
|
|
Keep in mind that the purpose of a bug report is to enable me to fix
|
|
|
|
the bug if it is not known. It isn't very important what happens if
|
|
|
|
the bug is already known. Therefore, always write your bug reports on
|
|
|
|
the assumption that the bug is not known.
|
|
|
|
|
|
|
|
Sometimes people give a few sketchy facts and ask, ``Does this ring a
|
|
|
|
bell?'' Those bug reports are useless, and I urge everyone to
|
|
|
|
@emph{refuse to respond to them} except to chide the sender to report
|
|
|
|
bugs properly.
|
|
|
|
|
|
|
|
To enable me to fix the bug, you should include all these things:
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
|
|
The version of GDB. GDB announces it on startup.
|
|
|
|
|
|
|
|
Without this, I won't know whether there is any point in looking for
|
|
|
|
the bug in the current version of GDB.
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
|
|
|
A complete input file, and all necessary source files, that will
|
|
|
|
reproduce the bug. Run your source files through the C
|
|
|
|
preprocessor by doing @samp{gcc -E @var{sourcefile} > @var{outfile}},
|
|
|
|
then include the contents of @var{outfile} in the bug report. (Any
|
|
|
|
@samp{-I}, @samp{-D} or @samp{-U} options that you used in actual
|
|
|
|
compilation should also be used when doing this.)
|
|
|
|
|
|
|
|
A single statement is not enough of an example. In order to compile
|
|
|
|
it, it must be embedded in a function definition; and the bug might
|
|
|
|
depend on the details of how this is done.
|
|
|
|
|
|
|
|
Without a real example I can compile, all I can do about your bug
|
|
|
|
report is wish you luck. It would be futile to try to guess how to
|
|
|
|
provoke the bug.
|
|
|
|
|
|
|
|
@item
|
|
|
|
The command arguments you gave GCC or G++ to compile that example and
|
|
|
|
observe the bug. For example, did you use @samp{-O}? To guarantee
|
|
|
|
you won't omit something important, list them all.
|
|
|
|
|
|
|
|
If I were to try to guess the arguments, I would probably guess wrong
|
|
|
|
and then I would not encounter the bug.
|
|
|
|
|
|
|
|
@item
|
|
|
|
The type of machine you are using, and the operating system name and
|
|
|
|
version number.
|
|
|
|
|
|
|
|
@item
|
|
|
|
A description of what behavior you observe that you believe is
|
|
|
|
incorrect. For example, ``It gets a fatal signal,'' or, ``There is an
|
|
|
|
incorrect assembler instruction in the output.''
|
|
|
|
|
|
|
|
Of course, if the bug is that GDB gets a fatal signal, then I
|
|
|
|
will certainly notice it. But if the bug is incorrect output, I might
|
|
|
|
not notice unless it is glaringly wrong.
|
|
|
|
|
|
|
|
Even if the problem you experience is a fatal signal, you should still
|
|
|
|
say so explicitly. Suppose something strange is going on, such as,
|
|
|
|
your copy of GDB is out of synch, or you have encountered a
|
|
|
|
bug in the C library on your system. (This has happened!) Your copy
|
|
|
|
might crash and mine would not. If you @i{told} me to expect a crash,
|
|
|
|
then when mine fails to crash, I would know that the bug was not
|
|
|
|
happening for me. If you had not told me to expect a crash, then I
|
|
|
|
would not be able to draw any conclusion from my observations.
|
|
|
|
|
|
|
|
@item
|
|
|
|
If you wish to suggest changes to the GDB source, send me context
|
|
|
|
diffs. If you even discuss something in the GDB source, refer to
|
|
|
|
it by context, not by line number.
|
|
|
|
|
|
|
|
The line numbers in my development sources don't match those in your
|
|
|
|
sources. Your line numbers would convey no useful information to me.
|
|
|
|
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
Here are some things that are not necessary:
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
|
|
A description of the envelope of the bug.
|
|
|
|
|
|
|
|
Often people who encounter a bug spend a lot of time investigating
|
|
|
|
which changes to the input file will make the bug go away and which
|
|
|
|
changes will not affect it.
|
|
|
|
|
|
|
|
This is often time consuming and not very useful, because the way I
|
|
|
|
will find the bug is by running a single example under the debugger
|
|
|
|
with breakpoints, not by pure deduction from a series of examples.
|
|
|
|
I recommend that you save your time for something else.
|
|
|
|
|
|
|
|
Of course, if you can find a simpler example to report @emph{instead}
|
|
|
|
of the original one, that is a convenience for me. Errors in the
|
|
|
|
output will be easier to spot, running under the debugger will take
|
|
|
|
less time, etc.
|
|
|
|
|
|
|
|
However, simplification is not vital; if you don't want to do this,
|
|
|
|
report the bug anyway and send me the entire test case you used.
|
|
|
|
|
|
|
|
@item
|
|
|
|
A patch for the bug.
|
|
|
|
|
|
|
|
A patch for the bug does help me if it is a good one. But don't omit
|
|
|
|
the necessary information, such as the test case, on the assumption that
|
|
|
|
a patch is all I need. I might see problems with your patch and decide
|
|
|
|
to fix the problem another way, or I might not understand it at all.
|
|
|
|
|
|
|
|
Sometimes with a program as complicated as GDB it is very hard to
|
|
|
|
construct an example that will make the program follow a certain path
|
|
|
|
through the code. If you don't send me the example, I won't be able
|
|
|
|
to construct one, so I won't be able to verify that the bug is fixed.
|
|
|
|
|
|
|
|
And if I can't understand what bug you are trying to fix, or why your
|
|
|
|
patch should be an improvement, I won't install it. A test case will
|
|
|
|
help me to understand.
|
|
|
|
|
|
|
|
@item
|
|
|
|
A guess about what the bug is or what it depends on.
|
|
|
|
|
|
|
|
Such guesses are usually wrong. Even I can't guess right about such
|
|
|
|
things without first using the debugger to find the facts.
|
|
|
|
@end itemize
|
|
|
|
|
1990-12-17 18:23:17 +00:00
|
|
|
@include readline/inc-readline.texinfo
|
|
|
|
@include readline/inc-history.texinfo
|
1989-09-30 00:00:00 +00:00
|
|
|
|
1989-01-31 17:56:40 +00:00
|
|
|
@node Commands, Concepts, Remote, Top
|
|
|
|
@unnumbered Command Index
|
|
|
|
|
|
|
|
@printindex ky
|
|
|
|
|
1989-09-30 00:00:00 +00:00
|
|
|
@node Concepts, , Commands, Top
|
1989-01-31 17:56:40 +00:00
|
|
|
@unnumbered Concept Index
|
|
|
|
|
|
|
|
@printindex cp
|
|
|
|
|
|
|
|
@contents
|
|
|
|
@bye
|