\input texinfo @c -*-texinfo-*-
-@c Copyright 1988-1999
+@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
+@c 1999, 2000, 2001, 2002
@c Free Software Foundation, Inc.
@c
-@c %**start of header
+@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@c of @set vars. However, you can override filename with makeinfo -o.
@setfilename gdb.info
@finalout
@syncodeindex ky cp
-@c readline appendices use @vindex
+@c readline appendices use @vindex, @findex and @ftable,
+@c annotate.texi and gdbmi use @findex.
@syncodeindex vr cp
+@syncodeindex fn cp
@c !!set GDB manual's edition---not the same as GDB version!
-@set EDITION Seventh
+@set EDITION Ninth
@c !!set GDB manual's revision date
-@set DATE February 1999
+@set DATE December 2001
-@c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly.
+@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.
-@ifinfo
@c This is a dir.info fragment to support semi-automated addition of
-@c manuals to an info tree. zoo@cygnus.com is developing this facility.
-@format
-START-INFO-DIR-ENTRY
+@c manuals to an info tree.
+@dircategory Programming & development tools.
+@direntry
* Gdb: (gdb). The @sc{gnu} debugger.
-END-INFO-DIR-ENTRY
-@end format
-@end ifinfo
-@c
-@c
+@end direntry
+
@ifinfo
This file documents the @sc{gnu} debugger @value{GDBN}.
-This is the @value{EDITION} Edition, @value{DATE},
+This is the @value{EDITION} Edition, @value{DATE},
of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
for @value{GDBN} Version @value{GDBVN}.
-Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
-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).
+Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
+ 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``Free Software'' and ``Free Software Needs
+Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+(a) The Free Software Foundation's Back-Cover Text is: ``You have
+freedom to copy and modify this GNU Manual, like GNU software. Copies
+published by the Free Software Foundation raise funds for GNU
+development.''
@end ifinfo
@titlepage
@title Debugging with @value{GDBN}
@subtitle The @sc{gnu} Source-Level Debugger
@sp 1
-@ifclear HPPA
@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
@subtitle @value{DATE}
-@author Richard M. Stallman and Roland H. Pesch
-@end ifclear
-@ifset HPPA
-@subtitle Edition @value{EDITION}, for @value{HPVER} (based on @value{GDBN} @value{GDBVN})
-@subtitle @value{DATE}
-@author Richard M. Stallman and Roland H. Pesch (modified by HP)
-@end ifset
+@author Richard Stallman, Roland Pesch, Stan Shebs, et al.
@page
-@ifclear HPPA
-@tex
-{\parskip=0pt
-\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@prep.ai.mit.edu.)\par
-\hfill {\it Debugging with @value{GDBN}}\par
-\hfill \TeX{}info \texinfoversion\par
-}
-@end tex
-@end ifclear
-@ifset HPPA
@tex
{\parskip=0pt
+\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par
\hfill {\it Debugging with @value{GDBN}}\par
\hfill \TeX{}info \texinfoversion\par
}
@end tex
-@end ifset
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-1999 Free Software Foundation, Inc.
+Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
+1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
@sp 2
-@ifclear HPPA
Published by the Free Software Foundation @*
59 Temple Place - Suite 330, @*
Boston, MA 02111-1307 USA @*
-Printed copies are available for $20 each. @*
-ISBN 1-882114-11-6 @*
-@end ifclear
-
-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
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+ISBN 1-882114-77-9 @*
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``Free Software'' and ``Free Software Needs
+Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
+
+(a) The Free Software Foundation's Back-Cover Text is: ``You have
+freedom to copy and modify this GNU Manual, like GNU software. Copies
+published by the Free Software Foundation raise funds for GNU
+development.''
@end titlepage
@page
@ifinfo
@node Top, Summary, (dir), (dir)
+
@top Debugging with @value{GDBN}
This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
-This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
+This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-1999 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
+
@menu
* Summary:: Summary of @value{GDBN}
* Sample Session:: A sample @value{GDBN} session
* Stack:: Examining the stack
* Source:: Examining source files
* Data:: Examining data
+* Tracepoints:: Debugging remote targets non-intrusively
+* Overlays:: Debugging programs that use overlays
* Languages:: Using @value{GDBN} with different languages
-* C:: C language support
* Symbols:: Examining the symbol table
* Altering:: Altering execution
* GDB Files:: @value{GDBN} files
* Targets:: Specifying a debugging target
+* Remote Debugging:: Debugging remote programs
+* Configurations:: Configuration-specific information
* Controlling GDB:: Controlling @value{GDBN}
* Sequences:: Canned sequences of commands
+* TUI:: @value{GDBN} Text User Interface
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
+* Annotations:: @value{GDBN}'s annotation interface.
+* GDB/MI:: @value{GDBN}'s Machine Interface.
* GDB Bugs:: Reporting bugs in @value{GDBN}
-
-@ifclear PRECONFIGURED
-@ifclear HPPA
* Formatting Documentation:: How to format and print @value{GDBN} documentation
-@end ifclear
-
-@end ifclear
* Command Line Editing:: Command Line Editing
* Using History Interactively:: Using History Interactively
* Installing GDB:: Installing GDB
+* Maintenance Commands:: Maintenance Commands
+* Remove Protocol:: GDB Remote Serial Protocol
+* GNU Free Documentation License:: The license for this documentation
* Index:: Index
+@end menu
- --- The Detailed Node Listing ---
-
-Summary of @value{GDBN}
-
-* Free Software:: Freely redistributable software
-* Contributors:: Contributors to GDB
-
-Getting In and Out of @value{GDBN}
-
-* Invoking GDB:: How to start @value{GDBN}
-* Quitting GDB:: How to quit @value{GDBN}
-* Shell Commands:: How to use shell commands inside @value{GDBN}
-
-Invoking @value{GDBN}
-
-* File Options:: Choosing files
-* Mode Options:: Choosing modes
-
-@value{GDBN} Commands
-
-* Command Syntax:: How to give commands to @value{GDBN}
-* Completion:: Command completion
-* Help:: How to ask @value{GDBN} for help
-
-Running Programs Under @value{GDBN}
-
-* Compilation:: Compiling for debugging
-* Starting:: Starting your program
-* Arguments:: Your program's arguments
-* Environment:: Your program's environment
-* Working Directory:: Your program's working directory
-* Input/Output:: Your program's input and output
-* Attach:: Debugging an already-running process
-* Kill Process:: Killing the child process
-* Process Information:: Additional process information
-
-* Threads:: Debugging programs with multiple threads
-* Processes:: Debugging programs with multiple processes
-
-Stopping and Continuing
-
-* Breakpoints:: Breakpoints, watchpoints, and catchpoints
-* Continuing and Stepping:: Resuming execution
-* Signals:: Signals
-* Thread Stops:: Stopping and starting multi-thread programs
-
-Breakpoints and watchpoints
-
-* Set Breaks:: Setting breakpoints
-* Set Watchpoints:: Setting watchpoints
-* Set Catchpoints:: Setting catchpoints
-* Delete Breaks:: Deleting breakpoints
-* Disabling:: Disabling breakpoints
-* Conditions:: Break conditions
-* Break Commands:: Breakpoint command lists
-* Breakpoint Menus:: Breakpoint menus
-
-Examining the Stack
-
-* Frames:: Stack frames
-* Backtrace:: Backtraces
-* Selection:: Selecting a frame
-* Frame Info:: Information on a frame
-* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack
-
-Examining Source Files
-
-* List:: Printing source lines
-* Search:: Searching source files
-* Source Path:: Specifying source directories
-* Machine Code:: Source and machine code
-
-Examining Data
-
-* Expressions:: Expressions
-* Variables:: Program variables
-* Arrays:: Artificial arrays
-* Output Formats:: Output formats
-* Memory:: Examining memory
-* Auto Display:: Automatic display
-* Print Settings:: Print settings
-* Value History:: Value history
-* Convenience Vars:: Convenience variables
-* Registers:: Registers
-* Floating Point Hardware:: Floating point hardware
-
-Using @value{GDBN} with Different Languages
-
-* Setting:: Switching between source languages
-* Show:: Displaying the language
-* Checks:: Type and range checks
-* Support:: Supported languages
-
-Switching between source languages
-
-* Filenames:: Filename extensions and languages.
-* Manually:: Setting the working language manually
-* Automatically:: Having @value{GDBN} infer the source language
-
-Type and range checking
-
-* Type Checking:: An overview of type checking
-* Range Checking:: An overview of range checking
-
-Supported languages
-
-C Language Support
-
-* C:: C and C++
-* C Operators:: C and C++ operators
-* C Constants:: C and C++ constants
-* C plus plus expressions:: C++ expressions
-* C Defaults:: Default settings for C and C++
-* C Checks:: C and C++ type and range checks
-* Debugging C:: @value{GDBN} and C
-* Debugging C plus plus:: @value{GDBN} features for C++
-
-Modula-2
-
-* M2 Operators:: Built-in operators
-* Built-In Func/Proc:: Built-in functions and procedures
-* M2 Constants:: Modula-2 constants
-* M2 Defaults:: Default settings for Modula-2
-* Deviations:: Deviations from standard Modula-2
-* M2 Checks:: Modula-2 type and range checks
-* M2 Scope:: The scope operators @code{::} and @code{.}
-* GDB/M2:: @value{GDBN} and Modula-2
-
-Altering Execution
-
-* Assignment:: Assignment to variables
-* Jumping:: Continuing at a different address
-* Signaling:: Giving your program a signal
-* Returning:: Returning from a function
-* Calling:: Calling your program's functions
-* Patching:: Patching your program
-
-@value{GDBN} Files
-
-* Files:: Commands to specify files
-* Symbol Errors:: Errors reading symbol files
-
-Specifying a Debugging Target
-
-* Active Targets:: Active targets
-* Target Commands:: Commands for managing targets
-@ifclear HPPA
-* Byte Order:: Choosing target byte order
-* Remote:: Remote debugging
-
-Remote debugging
-@end ifclear
-
-* Remote Serial:: @value{GDBN} remote serial protocol
-
-* i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy)
-
-* UDI29K Remote:: The UDI protocol for AMD29K
-
-* EB29K Remote:: The EBMON protocol for AMD29K
-
-* VxWorks Remote:: @value{GDBN} and VxWorks
+@end ifinfo
-* ST2000 Remote:: @value{GDBN} with a Tandem ST2000
+@c the replication sucks, but this avoids a texinfo 3.12 lameness
-* Hitachi Remote:: @value{GDBN} and Hitachi Microprocessors
+@ifhtml
+@node Top
-* MIPS Remote:: @value{GDBN} and MIPS boards
+@top Debugging with @value{GDBN}
-* Simulator:: Simulated CPU target
+This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
-Controlling @value{GDBN}
+This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
+@value{GDBVN}.
-* Prompt:: Prompt
-* Editing:: Command editing
-* History:: Command history
-* Screen Size:: Screen size
-* Numbers:: Numbers
-* Messages/Warnings:: Optional warnings and messages
+Copyright (C) 1988-2000 Free Software Foundation, Inc.
-Canned Sequences of Commands
+@menu
+* Summary:: Summary of @value{GDBN}
+* Sample Session:: A sample @value{GDBN} session
-* Define:: User-defined commands
-* Hooks:: User-defined command hooks
-* Command Files:: Command files
-* Output:: Commands for controlled output
+* Invocation:: Getting in and out of @value{GDBN}
+* Commands:: @value{GDBN} commands
+* Running:: Running programs under @value{GDBN}
+* Stopping:: Stopping and continuing
+* Stack:: Examining the stack
+* Source:: Examining source files
+* Data:: Examining data
+* Tracepoints:: Debugging remote targets non-intrusively
+* Overlays:: Debugging programs that use overlays
-Reporting Bugs in @value{GDBN}
+* Languages:: Using @value{GDBN} with different languages
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
+* Symbols:: Examining the symbol table
+* Altering:: Altering execution
+* GDB Files:: @value{GDBN} files
+* Targets:: Specifying a debugging target
+* Remote Debugging:: Debugging remote programs
+* Configurations:: Configuration-specific information
+* Controlling GDB:: Controlling @value{GDBN}
+* Sequences:: Canned sequences of commands
+* TUI:: @value{GDBN} Text User Interface
+* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
+* Annotations:: @value{GDBN}'s annotation interface.
+* GDB/MI:: @value{GDBN}'s Machine Interface.
-Installing @value{GDBN}
+* GDB Bugs:: Reporting bugs in @value{GDBN}
+* Formatting Documentation:: How to format and print @value{GDBN} documentation
-* Separate Objdir:: Compiling @value{GDBN} in another directory
-* Config Names:: Specifying names for hosts and targets
-* Configure Options:: Summary of options for configure
+* Command Line Editing:: Command Line Editing
+* Using History Interactively:: Using History Interactively
+* Installing GDB:: Installing GDB
+* Maintenance Commands:: Maintenance Commands
+* Remove Protocol:: GDB Remote Serial Protocol
+* GNU Free Documentation License:: The license for this documentation
+* Index:: Index
@end menu
-@end ifinfo
+@end ifhtml
-@node Summary, Sample Session, Top, Top
+@c TeX can handle the contents at the start but makeinfo 3.12 can not
+@iftex
+@contents
+@end iftex
+
+@node Summary
@unnumbered Summary of @value{GDBN}
The purpose of a debugger such as @value{GDBN} is to allow you to see what is
effects of one bug and go on to learn about another.
@end itemize
-You can use @value{GDBN} to debug programs written in C or C++.
-@c "MOD2" used as a "miscellaneous languages" flag here.
-@c This is acceptable while there is no real doc for Chill and Pascal.
+You can use @value{GDBN} to debug programs written in C and C++.
For more information, see @ref{Support,,Supported languages}.
For more information, see @ref{C,,C and C++}.
+@cindex Chill
+@cindex Modula-2
Support for Modula-2 and Chill is partial. For information on Modula-2,
-see @ref{Modula-2,,Modula-2}. There is no further documentation on Chill yet.
+see @ref{Modula-2,,Modula-2}. For information on Chill, see @ref{Chill}.
-Debugging Pascal programs which use sets, subranges, file variables, or nested
-functions does not currently work. @value{GDBN} does not support
-entering expressions, printing values, or similar features using Pascal syntax.
+@cindex Pascal
+Debugging Pascal programs which use sets, subranges, file variables, or
+nested functions does not currently work. @value{GDBN} does not support
+entering expressions, printing values, or similar features using Pascal
+syntax.
@cindex Fortran
@value{GDBN} can be used to debug programs written in Fortran, although
-it does not yet support entering expressions, printing values, or
-similar features using Fortran syntax. It may be necessary to refer to
-some variables with a trailing underscore.
-
-@ifset HPPA
-This version of the manual documents HP Wildebeest (WDB) Version 0.75,
-implemented on HP 9000 systems running Release 10.20, 10.30, or 11.0 of
-the HP-UX operating system. HP WDB 0.75 can be used to debug code
-generated by the HP ANSI C and HP ANSI C++ compilers as well as the
-@sc{gnu} C and C++ compilers. It does not support the debugging of
-Fortran, Modula-2, or Chill programs.
-@end ifset
+it may be necessary to refer to some variables with a trailing
+underscore.
@menu
* Free Software:: Freely redistributable software
* Contributors:: Contributors to GDB
@end menu
-@node Free Software, Contributors, Summary, Summary
+@node Free Software
@unnumberedsec Free software
-@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
+@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
General Public License
(GPL). The GPL gives you the freedom to copy or adapt a licensed
program---but every person getting a copy also gets with it the
you have these freedoms and that you cannot take these freedoms away
from anyone else.
-@node Contributors, , Free Software, Summary
-@unnumberedsec Contributors to GDB
-
-Richard Stallman was the original author of GDB, and of many other
-@sc{gnu} programs. Many others have contributed to its development.
-This section attempts to credit major contributors. One of the virtues
-of free software is that everyone is free to contribute to it; with
-regret, we cannot actually acknowledge everyone here. The file
-@file{ChangeLog} in the @value{GDBN} distribution approximates a
+@unnumberedsec Free Software Needs Free Documentation
+
+The biggest deficiency in the free software community today is not in
+the software---it is the lack of good free documentation that we can
+include with the free software. Many of our most important
+programs do not come with free reference manuals and free introductory
+texts. Documentation is an essential part of any software package;
+when an important free software package does not come with a free
+manual and a free tutorial, that is a major gap. We have many such
+gaps today.
+
+Consider Perl, for instance. The tutorial manuals that people
+normally use are non-free. How did this come about? Because the
+authors of those manuals published them with restrictive terms---no
+copying, no modification, source files not available---which exclude
+them from the free software world.
+
+That wasn't the first time this sort of thing happened, and it was far
+from the last. Many times we have heard a GNU user eagerly describe a
+manual that he is writing, his intended contribution to the community,
+only to learn that he had ruined everything by signing a publication
+contract to make it non-free.
+
+Free documentation, like free software, is a matter of freedom, not
+price. The problem with the non-free manual is not that publishers
+charge a price for printed copies---that in itself is fine. (The Free
+Software Foundation sells printed copies of manuals, too.) The
+problem is the restrictions on the use of the manual. Free manuals
+are available in source code form, and give you permission to copy and
+modify. Non-free manuals do not allow this.
+
+The criteria of freedom for a free manual are roughly the same as for
+free software. Redistribution (including the normal kinds of
+commercial redistribution) must be permitted, so that the manual can
+accompany every copy of the program, both on-line and on paper.
+
+Permission for modification of the technical content is crucial too.
+When people modify the software, adding or changing features, if they
+are conscientious they will change the manual too---so they can
+provide accurate and clear documentation for the modified program. A
+manual that leaves you no choice but to write a new manual to document
+a changed version of the program is not really available to our
+community.
+
+Some kinds of limits on the way modification is handled are
+acceptable. For example, requirements to preserve the original
+author's copyright notice, the distribution terms, or the list of
+authors, are ok. It is also no problem to require modified versions
+to include notice that they were modified. Even entire sections that
+may not be deleted or changed are acceptable, as long as they deal
+with nontechnical topics (like this one). These kinds of restrictions
+are acceptable because they don't obstruct the community's normal use
+of the manual.
+
+However, it must be possible to modify all the @emph{technical}
+content of the manual, and then distribute the result in all the usual
+media, through all the usual channels. Otherwise, the restrictions
+obstruct the use of the manual, it is not free, and we need another
+manual to replace it.
+
+Please spread the word about this issue. Our community continues to
+lose manuals to proprietary publishing. If we spread the word that
+free software needs free reference manuals and free tutorials, perhaps
+the next person who wants to contribute by writing documentation will
+realize, before it is too late, that only free manuals contribute to
+the free software community.
+
+If you are writing documentation, please insist on publishing it under
+the GNU Free Documentation License or another free documentation
+license. Remember that this decision requires your approval---you
+don't have to let the publisher decide. Some commercial publishers
+will use a free license if you insist, but they will not propose the
+option; it is up to you to raise the issue and say firmly that this is
+what you want. If the publisher you are dealing with refuses, please
+try other publishers. If you're not sure whether a proposed license
+is free, write to @email{licensing@@gnu.org}.
+
+You can encourage commercial publishers to sell more free, copylefted
+manuals and tutorials by buying them, and particularly by buying
+copies from the publishers that paid for their writing or for major
+improvements. Meanwhile, try to avoid buying non-free documentation
+at all. Check the distribution terms of a manual before you buy it,
+and insist that whoever seeks your business must respect your freedom.
+Check the history of the book, and try to reward the publishers that
+have paid or pay the authors to work on it.
+
+The Free Software Foundation maintains a list of free documentation
+published by other publishers, at
+@url{http://www.fsf.org/doc/other-free-books.html}.
+
+@node Contributors
+@unnumberedsec Contributors to @value{GDBN}
+
+Richard Stallman was the original author of @value{GDBN}, and of many
+other @sc{gnu} programs. Many others have contributed to its
+development. This section attempts to credit major contributors. One
+of the virtues of free software is that everyone is free to contribute
+to it; with regret, we cannot actually acknowledge everyone here. The
+file @file{ChangeLog} in the @value{GDBN} distribution approximates a
blow-by-blow account.
Changes much prior to version 2.0 are lost in the mists of time.
So that they may not regard their many labors as thankless, we
particularly thank those who shepherded @value{GDBN} through major
releases:
+Andrew Cagney (releases 5.0 and 5.1);
Jim Blandy (release 4.18);
Jason Molenda (release 4.17);
Stan Shebs (release 4.14);
Richard Stallman, assisted at various times by Peter TerMaat, Chris
Hanson, and Richard Mlynarik, handled releases through 2.8.
-Michael Tiemann is the author of most of the @sc{gnu} C++ support in GDB,
-with significant additional contributions from Per Bothner. James
-Clark wrote the @sc{gnu} C++ demangler. Early work on C++ was by Peter
-TerMaat (who also did much general update work leading to release 3.0).
+Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support
+in @value{GDBN}, with significant additional contributions from Per
+Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++}
+demangler. Early work on C@t{++} was by Peter TerMaat (who also did
+much general update work leading to release 3.0).
-@value{GDBN} 4 uses the BFD subroutine library to examine multiple
+@value{GDBN} uses the BFD subroutine library to examine multiple
object-file formats; BFD was a joint project of David V.
Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
David Johnson wrote the original COFF support; Pace Willison did
the original support for encapsulated COFF.
-Brent Benson of Harris Computer Systems contributed DWARF 2 support.
+Brent Benson of Harris Computer Systems contributed DWARF2 support.
Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
Andrew Beers of SUNY Buffalo wrote the language-switching code, the
Modula-2 support, and contributed the Languages chapter of this manual.
-Fred Fish wrote most of the support for Unix System Vr4.
-He also enhanced the command-completion support to cover C++ overloaded
+Fred Fish wrote most of the support for Unix System Vr4.
+He also enhanced the command-completion support to cover C@t{++} overloaded
symbols.
Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and
Matsushita sponsored the support for the MN10200 and MN10300 processors.
-Fujitsu sponsored the support for SPARClite and FR30 processors
+Fujitsu sponsored the support for SPARClite and FR30 processors.
Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
watchpoints.
Stu Grossman wrote gdbserver.
Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
-nearly innumerable bug fixes and cleanups throughout GDB.
+nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
The following people at the Hewlett-Packard Company contributed
support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
-(narrow mode), HP's implementation of kernel threads, HP's aC++
+(narrow mode), HP's implementation of kernel threads, HP's aC@t{++}
compiler, and the terminal user interface: Ben Krepp, Richard Title,
John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve
Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific
information in this manual.
-Cygnus Solutions has sponsored GDB maintenance and much of its
-development since 1991. Cygnus engineers who have worked on GDB
-fulltime include Mark Alexander, Jim Blandy, Per Bothner, Edith Epstein,
-Chris Faylor, Fred Fish, Martin Hunt, Jim Ingham, John Gilmore, Stu
-Grossman, Kung Hsu, Jim Kingdon, John Metzler, Fernando Nasser, Geoffrey
-Noer, Dawn Perchik, Rich Pixley, Zdenek Radouch, Keith Seitz, Stan
-Shebs, David Taylor, and Elena Zannoni. In addition, Dave Brolley, Ian
-Carmichael, Steve Chamberlain, Nick Clifton, JT Conklin, Stan Cox, DJ
-Delorie, Ulrich Drepper, Frank Eigler, Doug Evans, Sean Fagan, David
-Henkel-Wallace, Richard Henderson, Jeff Holcomb, Jeff Law, Jim Lemke,
-Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, Catherine Moore,
-Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith,
-Mike Stump, Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron
-Unrau, Jim Wilson, and David Zuhn have made contributions both large
-and small.
-
-
-@node Sample Session, Invocation, Summary, Top
+DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
+Robert Hoehne made significant contributions to the DJGPP port.
+
+Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
+development since 1991. Cygnus engineers who have worked on @value{GDBN}
+fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
+Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
+Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
+Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
+Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
+addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
+JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
+Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
+Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
+Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
+Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
+Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
+Zuhn have made contributions both large and small.
+
+
+@node Sample Session
@chapter A Sample @value{GDBN} Session
You can use this manual at your leisure to read all about @value{GDBN}.
@noindent
Let us use @value{GDBN} to try to see what is going on.
-@ifclear HPPA
@smallexample
$ @b{@value{GDBP} m4}
@c FIXME: this falsifies the exact text played out, to permit smallbook
@c FIXME... format to come out better.
@value{GDBN} is free software and you are welcome to distribute copies
- of it under certain conditions; type "show copying" to see
+ of it under certain conditions; type "show copying" to see
the conditions.
-There is absolutely no warranty for @value{GDBN}; type "show warranty"
+There is absolutely no warranty for @value{GDBN}; type "show warranty"
for details.
@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
(@value{GDBP})
@end smallexample
-@end ifclear
-@ifset HPPA
-@smallexample
-$ @b{@value{GDBP} m4}
-Wildebeest is free software and you are welcome to distribute copies of
-it under certain conditions; type "show copying" to see the conditions.
-There is absolutely no warranty for Wildebeest; type "show warranty"
-for details.
-
-Hewlett-Packard Wildebeest 0.75 (based on GDB 4.16)
-(built for PA-RISC 1.1 or 2.0, HP-UX 10.20)
-Copyright 1996, 1997 Free Software Foundation, Inc.
-(@value{GDBP})
-@end smallexample
-@end ifset
@noindent
@value{GDBN} reads only enough symbol data to know where to find the
@smallexample
@b{changequote(<QUOTE>,<UNQUOTE>)}
-Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
+Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
at builtin.c:879
879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
@end smallexample
(@value{GDBP}) @b{bt}
#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
at input.c:530
-#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
+#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
at builtin.c:882
#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
(@value{GDBP}) @b{quit}
@end smallexample
-@node Invocation, Commands, Sample Session, Top
+@node Invocation
@chapter Getting In and Out of @value{GDBN}
This chapter discusses how to start @value{GDBN}, and how to get out of it.
-The essentials are:
+The essentials are:
@itemize @bullet
-@item
-type @samp{@value{GDBP}} to start GDB.
-@item
+@item
+type @samp{@value{GDBP}} to start @value{GDBN}.
+@item
type @kbd{quit} or @kbd{C-d} to exit.
@end itemize
* Shell Commands:: How to use shell commands inside @value{GDBN}
@end menu
-@node Invoking GDB, Quitting GDB, Invocation, Invocation
+@node Invoking GDB
@section Invoking @value{GDBN}
Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
The command-line options described here are designed
to cover a variety of situations; in some environments, some of these
-options may effectively be unavailable.
+options may effectively be unavailable.
The most usual way to start @value{GDBN} is with one argument,
specifying an executable program:
would attach @value{GDBN} to process @code{1234} (unless you also have a file
named @file{1234}; @value{GDBN} does check for a core file first).
-@ifclear HPPA
Taking advantage of the second command-line argument requires a fairly
-complete operating system; when you use @value{GDBN} as a remote debugger
-attached to a bare board, there may not be any notion of ``process'',
-and there is often no way to get a core dump.
-@end ifclear
+complete operating system; when you use @value{GDBN} as a remote
+debugger attached to a bare board, there may not be any notion of
+``process'', and there is often no way to get a core dump. @value{GDBN}
+will warn you if it is unable to attach or to read core dumps.
+
+You can optionally have @code{@value{GDBP}} pass any arguments after the
+executable file to the inferior using @code{--args}. This option stops
+option processing.
+@example
+gdb --args gcc -O2 -c foo.c
+@end example
+This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
+@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
-You can run @code{gdb} without printing the front material, which describes
+You can run @code{@value{GDBP}} without printing the front material, which describes
@value{GDBN}'s non-warranty, by specifying @code{-silent}:
@smallexample
When @value{GDBN} starts, it reads any arguments other than options as
specifying an executable file and core file (or process ID). This is
the same as if the arguments were specified by the @samp{-se} and
-@samp{-c} options respectively. (@value{GDBN} reads the first argument
-that does not have an associated option flag as equivalent to the
-@samp{-se} option followed by that argument; and the second argument
-that does not have an associated option flag, if any, as equivalent to
-the @samp{-c} option followed by that argument.)
+@samp{-c} (or @samp{-p} options respectively. (@value{GDBN} reads the
+first argument that does not have an associated option flag as
+equivalent to the @samp{-se} option followed by that argument; and the
+second argument that does not have an associated option flag, if any, as
+equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
+If the second argument begins with a decimal digit, @value{GDBN} will
+first attempt to attach to it as a process, and if that fails, attempt
+to open it as a corefile. If you have a corefile whose name begins with
+a digit, you can prevent @value{GDBN} from treating it as a pid by
+prefixing it with @file{./}, eg. @file{./12345}.
If @value{GDBN} has not been configured to included core file support,
such as for most embedded targets, then it will complain about a second
(If you prefer, you can flag option arguments with @samp{--} rather
than @samp{-}, though we illustrate the more usual convention.)
+@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
+@c way, both those who look for -foo and --foo in the index, will find
+@c it.
+
@table @code
@item -symbols @var{file}
@itemx -s @var{file}
+@cindex @code{--symbols}
+@cindex @code{-s}
Read symbol table from file @var{file}.
@item -exec @var{file}
@itemx -e @var{file}
+@cindex @code{--exec}
+@cindex @code{-e}
Use file @var{file} as the executable file to execute when appropriate,
and for examining pure data in conjunction with a core dump.
@item -se @var{file}
+@cindex @code{--se}
Read symbol table from file @var{file} and use it as the executable
file.
@item -core @var{file}
@itemx -c @var{file}
-Use file @var{file} as a core dump to examine.
+@cindex @code{--core}
+@cindex @code{-c}
+Use file @var{file} as a core dump to examine.
@item -c @var{number}
-Connect to process ID @var{number}, as with the @code{attach} command
-(unless there is a file in core-dump format named @var{number}, in which
-case @samp{-c} specifies that file as a core dump to read).
+@item -pid @var{number}
+@itemx -p @var{number}
+@cindex @code{--pid}
+@cindex @code{-p}
+Connect to process ID @var{number}, as with the @code{attach} command.
+If there is no such process, @value{GDBN} will attempt to open a core
+file named @var{number}.
@item -command @var{file}
@itemx -x @var{file}
+@cindex @code{--command}
+@cindex @code{-x}
Execute @value{GDBN} commands from file @var{file}. @xref{Command
Files,, Command files}.
@item -directory @var{directory}
@itemx -d @var{directory}
+@cindex @code{--directory}
+@cindex @code{-d}
Add @var{directory} to the path to search for source files.
-@ifclear HPPA
@item -m
@itemx -mapped
+@cindex @code{--mapped}
+@cindex @code{-m}
@emph{Warning: this option depends on operating system facilities that are not
supported on all systems.}@*
If memory-mapped files are available on your system through the @code{mmap}
-system call, you can use this option
+system call, you can use this option
to have @value{GDBN} write the symbols from your
program into a reusable file in the current directory. If the program you are debugging is
-called @file{/tmp/fred}, the mapped symbol file is @file{./fred.syms}.
+called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.
Future @value{GDBN} debugging sessions notice the presence of this file,
and can quickly map in symbol information from it, rather than reading
the symbol table from the executable program.
The @file{.syms} file is specific to the host machine where @value{GDBN}
is run. It holds an exact image of the internal @value{GDBN} symbol
table. It cannot be shared across multiple host platforms.
-@end ifclear
-@ifclear HPPA
@item -r
@itemx -readnow
+@cindex @code{--readnow}
+@cindex @code{-r}
Read each symbol file's entire symbol table immediately, rather than
the default, which is to read it incrementally as it is needed.
This makes startup slower, but makes future operations faster.
-@end ifclear
+
@end table
-@ifclear HPPA
-The @code{-mapped} and @code{-readnow} options are typically combined in
+You typically combine the @code{-mapped} and @code{-readnow} options in
order to build a @file{.syms} file that contains complete symbol
-information. (@xref{Files,,Commands to specify files}, for
-information on @file{.syms} files.) A simple GDB invocation to do
-nothing but build a @file{.syms} file for future use is:
+information. (@xref{Files,,Commands to specify files}, for information
+on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing
+but build a @file{.syms} file for future use is:
@example
- gdb -batch -nx -mapped -readnow programname
+gdb -batch -nx -mapped -readnow programname
@end example
-@end ifclear
-@node Mode Options, , File Options, Invoking GDB
+@node Mode Options
@subsection Choosing modes
You can run @value{GDBN} in various alternative modes---for example, in
@table @code
@item -nx
@itemx -n
-Do not execute commands from any initialization files (normally called
-@file{.gdbinit}, or @file{gdb.ini} on PCs). Normally, the commands in
-these files are executed after all the command options and arguments
-have been processed. @xref{Command Files,,Command files}.
+@cindex @code{--nx}
+@cindex @code{-n}
+Do not execute commands found in any initialization files. Normally,
+@value{GDBN} executes the commands in these files after all the command
+options and arguments have been processed. @xref{Command Files,,Command
+files}.
@item -quiet
+@itemx -silent
@itemx -q
+@cindex @code{--quiet}
+@cindex @code{--silent}
+@cindex @code{-q}
``Quiet''. Do not print the introductory and copyright messages. These
messages are also suppressed in batch mode.
@item -batch
+@cindex @code{--batch}
Run in batch mode. Exit with status @code{0} after processing all the
command files specified with @samp{-x} (and all commands from
initialization files, if not inhibited with @samp{-n}). Exit with
nonzero status if an error occurs in executing the @value{GDBN} commands
in the command files.
-Batch mode may be useful for running @value{GDBN} as a filter, for example to
-download and run a program on another computer; in order to make this
-more useful, the message
+Batch mode may be useful for running @value{GDBN} as a filter, for
+example to download and run a program on another computer; in order to
+make this more useful, the message
@example
Program exited normally.
@end example
@noindent
-(which is ordinarily issued whenever a program running under @value{GDBN} control
-terminates) is not issued when running in batch mode.
+(which is ordinarily issued whenever a program running under
+@value{GDBN} control terminates) is not issued when running in batch
+mode.
+
+@item -nowindows
+@itemx -nw
+@cindex @code{--nowindows}
+@cindex @code{-nw}
+``No windows''. If @value{GDBN} comes with a graphical user interface
+(GUI) built in, then this option tells @value{GDBN} to only use the command-line
+interface. If no GUI is available, this option has no effect.
+
+@item -windows
+@itemx -w
+@cindex @code{--windows}
+@cindex @code{-w}
+If @value{GDBN} includes a GUI, then this option requires it to be
+used if possible.
@item -cd @var{directory}
+@cindex @code{--cd}
Run @value{GDBN} using @var{directory} as its working directory,
instead of the current directory.
@item -fullname
@itemx -f
+@cindex @code{--fullname}
+@cindex @code{-f}
@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
subprocess. It tells @value{GDBN} to output the full file name and line
number in a standard, recognizable fashion each time a stack frame is
@samp{\032} characters as a signal to display the source code for the
frame.
-@ifclear HPPA
-@item -b @var{bps}
+@item -epoch
+@cindex @code{--epoch}
+The Epoch Emacs-@value{GDBN} interface sets this option when it runs
+@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print
+routines so as to allow Epoch to display values of expressions in a
+separate window.
+
+@item -annotate @var{level}
+@cindex @code{--annotate}
+This option sets the @dfn{annotation level} inside @value{GDBN}. Its
+effect is identical to using @samp{set annotate @var{level}}
+(@pxref{Annotations}).
+Annotation level controls how much information does @value{GDBN} print
+together with its prompt, values of expressions, source lines, and other
+types of output. Level 0 is the normal, level 1 is for use when
+@value{GDBN} is run as a subprocess of @sc{gnu} Emacs, level 2 is the
+maximum annotation suitable for programs that control @value{GDBN}.
+
+@item -async
+@cindex @code{--async}
+Use the asynchronous event loop for the command-line interface.
+@value{GDBN} processes all events, such as user keyboard input, via a
+special event loop. This allows @value{GDBN} to accept and process user
+commands in parallel with the debugged process being
+run@footnote{@value{GDBN} built with @sc{djgpp} tools for
+MS-DOS/MS-Windows supports this mode of operation, but the event loop is
+suspended when the debuggee runs.}, so you don't need to wait for
+control to return to @value{GDBN} before you type the next command.
+(@emph{Note:} as of version 5.1, the target side of the asynchronous
+operation is not yet in place, so @samp{-async} does not work fully
+yet.)
+@c FIXME: when the target side of the event loop is done, the above NOTE
+@c should be removed.
+
+When the standard input is connected to a terminal device, @value{GDBN}
+uses the asynchronous event loop by default, unless disabled by the
+@samp{-noasync} option.
+
+@item -noasync
+@cindex @code{--noasync}
+Disable the asynchronous event loop for the command-line interface.
+
+@item --args
+@cindex @code{--args}
+Change interpretation of command line so that arguments following the
+executable file are passed as command line arguments to the inferior.
+This option stops option processing.
+
+@item -baud @var{bps}
+@itemx -b @var{bps}
+@cindex @code{--baud}
+@cindex @code{-b}
Set the line speed (baud rate or bits per second) of any serial
interface used by @value{GDBN} for remote debugging.
-@end ifclear
@item -tty @var{device}
+@itemx -t @var{device}
+@cindex @code{--tty}
+@cindex @code{-t}
Run using @var{device} for your program's standard input and output.
@c FIXME: kingdon thinks there is more to -tty. Investigate.
-@ifset HPPA
+@c resolve the situation of these eventually
@item -tui
-Use a Terminal User Interface. For information, use your Web browser to
-read the file @file{TUI.html}, which is usually installed in the
-directory @code{/opt/langtools/wdb/doc} on HP-UX systems. Do not use
-this option if you run @value{GDBN} from Emacs (see @pxref{Emacs, ,Using
-@value{GDBN} under @sc{gnu} Emacs}).
-
-@item -xdb
-Run in XDB compatibility mode, allowing the use of certain XDB commands.
-For information, see the file @file{xdb_trans.html}, which is usually
-installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
-systems.
-@end ifset
+@cindex @code{--tui}
+Activate the Terminal User Interface when starting.
+The Terminal User Interface manages several text windows on the terminal,
+showing source, assembly, registers and @value{GDBN} command outputs
+(@pxref{TUI, ,@value{GDBN} Text User Interface}).
+Do not use this option if you run @value{GDBN} from Emacs
+(@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
+
+@c @item -xdb
+@c @cindex @code{--xdb}
+@c Run in XDB compatibility mode, allowing the use of certain XDB commands.
+@c For information, see the file @file{xdb_trans.html}, which is usually
+@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
+@c systems.
+
+@item -interpreter @var{interp}
+@cindex @code{--interpreter}
+Use the interpreter @var{interp} for interface with the controlling
+program or device. This option is meant to be set by programs which
+communicate with @value{GDBN} using it as a back end.
+
+@samp{--interpreter=mi} (or @samp{--interpreter=mi1}) causes
+@value{GDBN} to use the @dfn{gdb/mi interface} (@pxref{GDB/MI, , The
+@sc{gdb/mi} Interface}). The older @sc{gdb/mi} interface, included in
+@value{GDBN} version 5.0 can be selected with @samp{--interpreter=mi0}.
+
+@item -write
+@cindex @code{--write}
+Open the executable and core files for both reading and writing. This
+is equivalent to the @samp{set write on} command inside @value{GDBN}
+(@pxref{Patching}).
+
+@item -statistics
+@cindex @code{--statistics}
+This option causes @value{GDBN} to print statistics about time and
+memory usage after it completes each command and returns to the prompt.
+
+@item -version
+@cindex @code{--version}
+This option causes @value{GDBN} to print its version number and
+no-warranty blurb, and exit.
+
@end table
-@node Quitting GDB, Shell Commands, Invoking GDB, Invocation
+@node Quitting GDB
@section Quitting @value{GDBN}
@cindex exiting @value{GDBN}
@cindex leaving @value{GDBN}
@table @code
@kindex quit @r{[}@var{expression}@r{]}
-@kindex q
-@item quit
-To exit @value{GDBN}, use the @code{quit} command (abbreviated @code{q}), or
-type an end-of-file character (usually @kbd{C-d}). If you do not supply
-@var{expression}, @value{GDBN} will terminate normally; otherwise it will
-terminate using the result of @var{expression} as the error code.
+@kindex q @r{(@code{quit})}
+@item quit @r{[}@var{expression}@r{]}
+@itemx q
+To exit @value{GDBN}, use the @code{quit} command (abbreviated
+@code{q}), or type an end-of-file character (usually @kbd{C-d}). If you
+do not supply @var{expression}, @value{GDBN} will terminate normally;
+otherwise it will terminate using the result of @var{expression} as the
+error code.
@end table
@cindex interrupt
device, you can release it with the @code{detach} command
(@pxref{Attach, ,Debugging an already-running process}).
-@node Shell Commands, , Quitting GDB, Invocation
+@node Shell Commands
@section Shell commands
If you need to execute occasional shell commands during your
@item shell @var{command string}
Invoke a standard shell to execute @var{command string}.
If it exists, the environment variable @code{SHELL} determines which
-shell to run. Otherwise @value{GDBN} uses @code{/bin/sh}.
+shell to run. Otherwise @value{GDBN} uses the default shell
+(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
@end table
The utility @code{make} is often needed in development environments.
arguments. This is equivalent to @samp{shell make @var{make-args}}.
@end table
-@node Commands, Running, Invocation, Top
+@node Commands
@chapter @value{GDBN} Commands
You can abbreviate a @value{GDBN} command to the first few letters of the command
* Help:: How to ask @value{GDBN} for help
@end menu
-@node Command Syntax, Completion, Commands, Commands
+@node Command Syntax
@section Command syntax
A @value{GDBN} command is a single line of input. There is no limit on
arguments whose meaning depends on the command name. For example, the
command @code{step} accepts an argument which is the number of times to
step, as in @samp{step 5}. You can also use the @code{step} command
-with no arguments. Some command names do not allow any arguments.
+with no arguments. Some commands do not allow any arguments.
@cindex abbreviation
@value{GDBN} command names may always be truncated if that abbreviation is
arguments to the @code{help} command.
@cindex repeating commands
-@kindex RET
+@kindex RET @r{(repeat last command)}
A blank line as input to @value{GDBN} (typing just @key{RET}) means to
-repeat the previous command. Certain commands (for example, @code{run})
+repeat the previous command. Certain commands (for example, @code{run})
will not repeat this way; these are commands whose unintentional
repetition might cause trouble and which you are unlikely to want to
repeat.
@key{RET} too many in this situation, @value{GDBN} disables command
repetition after any command that generates this sort of display.
-@kindex #
+@kindex # @r{(a comment)}
@cindex comment
Any text from a @kbd{#} to the end of the line is a comment; it does
nothing. This is useful mainly in command files (@pxref{Command
Files,,Command files}).
-@node Completion, Help, Command Syntax, Commands
+@cindex repeating command sequences
+@kindex C-o @r{(operate-and-get-next)}
+The @kbd{C-o} binding is useful for repeating a complex sequence of
+commands. This command accepts the current line, like @kbd{RET}, and
+then fetches the next line relative to the current line from the history
+for editing.
+
+@node Completion
@section Command completion
@cindex completion
@example
(@value{GDBP}) b make_ @key{TAB}
@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
-make_a_section_from_file make_environ
-make_abs_section make_function_type
-make_blockvector make_pointer_type
-make_cleanup make_reference_type
+make_a_section_from_file make_environ
+make_abs_section make_function_type
+make_blockvector make_pointer_type
+make_cleanup make_reference_type
make_command make_symbol_completion_list
(@value{GDBP}) b make_
@end example
command.
If you just want to see the list of alternatives in the first place, you
-can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
+can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
means @kbd{@key{META} ?}. You can type this either by holding down a
key designated as the @key{META} shift on your keyboard (if there is
one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
@value{GDBN} commands.
The most likely situation where you might need this is in typing the
-name of a C++ function. This is because C++ allows function overloading
-(multiple definitions of the same function, distinguished by argument
-type). For example, when you want to set a breakpoint you may need to
-distinguish whether you mean the version of @code{name} that takes an
-@code{int} parameter, @code{name(int)}, or the version that takes a
-@code{float} parameter, @code{name(float)}. To use the word-completion
-facilities in this situation, type a single quote @code{'} at the
-beginning of the function name. This alerts @value{GDBN} that it may need to
-consider more information than usual when you press @key{TAB} or
-@kbd{M-?} to request word completion:
+name of a C@t{++} function. This is because C@t{++} allows function
+overloading (multiple definitions of the same function, distinguished
+by argument type). For example, when you want to set a breakpoint you
+may need to distinguish whether you mean the version of @code{name}
+that takes an @code{int} parameter, @code{name(int)}, or the version
+that takes a @code{float} parameter, @code{name(float)}. To use the
+word-completion facilities in this situation, type a single quote
+@code{'} at the beginning of the function name. This alerts
+@value{GDBN} that it may need to consider more information than usual
+when you press @key{TAB} or @kbd{M-?} to request word completion:
@example
-(@value{GDBP}) b 'bubble( @key{M-?}
+(@value{GDBP}) b 'bubble( @kbd{M-?}
bubble(double,double) bubble(int,int)
(@value{GDBP}) b 'bubble(
@end example
you have not yet started typing the argument list when you ask for
completion on an overloaded symbol.
-For more information about overloaded functions, @pxref{C plus plus
-expressions, ,C++ expressions}. You can use the command @code{set
+For more information about overloaded functions, see @ref{C plus plus
+expressions, ,C@t{++} expressions}. You can use the command @code{set
overload-resolution off} to disable overload resolution;
-@pxref{Debugging C plus plus, ,@value{GDBN} features for C++}.
+see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}.
-@node Help, , Completion, Commands
+@node Help
@section Getting help
@cindex online documentation
@kindex help
-You can always ask @value{GDBN} itself for information on its commands,
+You can always ask @value{GDBN} itself for information on its commands,
using the command @code{help}.
@table @code
-@kindex h
+@kindex h @r{(@code{help})}
@item help
@itemx h
You can use @code{help} (abbreviated @code{h}) with no arguments to
(@value{GDBP}) help
List of classes of commands:
-running -- Running the program
-stack -- Examining the stack
-data -- Examining data
+aliases -- Aliases of other commands
breakpoints -- Making program stop at certain points
+data -- Examining data
files -- Specifying and examining files
+internals -- Maintenance commands
+obscure -- Obscure features
+running -- Running the program
+stack -- Examining the stack
status -- Status inquiries
support -- Support facilities
+tracepoints -- Tracing of program execution without@*
+ stopping the program
user-defined -- User-defined commands
-aliases -- Aliases of other commands
-obscure -- Obscure features
-Type "help" followed by a class name for a list of
+Type "help" followed by a class name for a list of
commands in that class.
-Type "help" followed by command name for full
+Type "help" followed by command name for full
documentation.
Command name abbreviations are allowed if unambiguous.
(@value{GDBP})
@end smallexample
+@c the above line break eliminates huge line overfull...
@item help @var{class}
Using one of the general help classes as an argument, you can get a
@c Line break in "show" line falsifies real output, but needed
@c to fit in smallbook page size.
-show -- Generic command for showing things set
- with "set"
-info -- Generic command for printing status
+info -- Generic command for showing things
+ about the program being debugged
+show -- Generic command for showing things
+ about the debugger
-Type "help" followed by command name for full
+Type "help" followed by command name for full
documentation.
Command name abbreviations are allowed if unambiguous.
(@value{GDBP})
With a command name as @code{help} argument, @value{GDBN} displays a
short paragraph on how to use that command.
+@kindex apropos
+@item apropos @var{args}
+The @code{apropos @var{args}} command searches through all of the @value{GDBN}
+commands, and their documentation, for the regular expression specified in
+@var{args}. It prints out all matches found. For example:
+
+@smallexample
+apropos reload
+@end smallexample
+
+@noindent
+results in:
+
+@smallexample
+@c @group
+set symbol-reloading -- Set dynamic symbol table reloading
+ multiple times in one run
+show symbol-reloading -- Show dynamic symbol table reloading
+ multiple times in one run
+@c @end group
+@end smallexample
+
@kindex complete
@item complete @var{args}
The @code{complete @var{args}} command lists all the possible completions
@smallexample
@group
+if
+ignore
info
inspect
-ignore
@end group
@end smallexample
@c @group
@table @code
@kindex info
-@kindex i
+@kindex i @r{(@code{info})}
@item info
This command (abbreviated @code{i}) is for describing the state of your
program. For example, you can list the arguments given to your program
@kindex set
@item set
-You can assign the result of an expression to an environment variable with
+You can assign the result of an expression to an environment variable with
@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
@code{set prompt $}.
@kindex show
@item show
-In contrast to @code{info}, @code{show} is for describing the state of
+In contrast to @code{info}, @code{show} is for describing the state of
@value{GDBN} itself.
You can change most of the things you can @code{show}, by using the
related command @code{set}; for example, you can control what number
@cindex version number
@item show version
Show what version of @value{GDBN} is running. You should include this
-information in @value{GDBN} bug-reports. If multiple versions of @value{GDBN} are in
-use at your site, you may occasionally want to determine which version
-of @value{GDBN} you are running; as @value{GDBN} evolves, new commands are introduced,
-and old ones may wither away. The version number is also announced
-when you start @value{GDBN}.
+information in @value{GDBN} bug-reports. If multiple versions of
+@value{GDBN} are in use at your site, you may need to determine which
+version of @value{GDBN} you are running; as @value{GDBN} evolves, new
+commands are introduced, and old ones may wither away. Also, many
+system vendors ship variant versions of @value{GDBN}, and there are
+variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
+The version number is the same as the one announced when you start
+@value{GDBN}.
@kindex show copying
@item show copying
@kindex show warranty
@item show warranty
-Display the @sc{gnu} ``NO WARRANTY'' statement.
+Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
+if your version of @value{GDBN} comes with one.
+
@end table
-@node Running, Stopping, Commands, Top
+@node Running
@chapter Running Programs Under @value{GDBN}
When you run a program under @value{GDBN}, you must first generate
* Input/Output:: Your program's input and output
* Attach:: Debugging an already-running process
* Kill Process:: Killing the child process
-* Process Information:: Additional process information
* Threads:: Debugging programs with multiple threads
* Processes:: Debugging programs with multiple processes
@end menu
-@node Compilation, Starting, Running, Running
+@node Compilation
@section Compiling for debugging
In order to debug a program effectively, you need to generate
options together. Using those compilers, you cannot generate optimized
executables containing debugging information.
-@ifclear HPPA
-@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or without
-@end ifclear
-@ifset HPPA
-The HP ANSI C and C++ compilers, as well as @value{NGCC}, the @sc{gnu} C
-compiler, support @samp{-g} with or without
-@end ifset
-@samp{-O}, making it possible to debug optimized code. We recommend
-that you @emph{always} use @samp{-g} whenever you compile a program.
-You may think your program is correct, but there is no sense in pushing
-your luck.
+@value{NGCC}, the @sc{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 your program is correct, but there is no sense
+in pushing your luck.
@cindex optimized code, debugging
@cindex debugging optimized code
format; if your @sc{gnu} C compiler has this option, do not use it.
@need 2000
-@node Starting, Arguments, Compilation, Running
+@node Starting
@section Starting your program
@cindex starting
@cindex running
@table @code
@kindex run
+@kindex r @r{(@code{run})}
@item run
@itemx r
Use the @code{run} command to start your program under @value{GDBN}.
table, and reads it again. When it does this, @value{GDBN} tries to retain
your current breakpoints.
-@node Arguments, Environment, Starting, Running
+@node Arguments
@section Your program's arguments
@cindex arguments (to your program)
The arguments to your program can be specified by the arguments of the
-@code{run} command.
+@code{run} command.
They are passed to a shell, which expands wildcard characters and
performs redirection of I/O, and thence to your program. Your
@code{SHELL} environment variable (if it exists) specifies what shell
@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses
-@code{/bin/sh}.
+the default shell (@file{/bin/sh} on Unix).
+
+On non-Unix systems, the program is usually invoked directly by
+@value{GDBN}, which emulates I/O redirection via the appropriate system
+calls, and the wildcard characters are expanded by the startup code of
+the program, not by the shell.
@code{run} with no arguments uses the same arguments used by the previous
@code{run}, or those set by the @code{set args} command.
-@kindex set args
@table @code
+@kindex set args
@item set args
Specify the arguments to be used the next time your program is run. If
@code{set args} has no arguments, @code{run} executes your program
Show the arguments to give your program when it is started.
@end table
-@node Environment, Working Directory, Arguments, Running
+@node Environment
@section Your program's environment
@cindex environment (of your program)
@kindex path
@item path @var{directory}
Add @var{directory} to the front of the @code{PATH} environment variable
-(the search path for executables), for both @value{GDBN} and your program.
-You may specify several directory names, separated by @samp{:} or
-whitespace. If @var{directory} is already in the path, it is moved to
-the front, so it is searched sooner.
+(the search path for executables) that will be passed to your program.
+The value of @code{PATH} used by @value{GDBN} does not change.
+You may specify several directory names, separated by whitespace or by a
+system-dependent separator character (@samp{:} on Unix, @samp{;} on
+MS-DOS and MS-Windows). If @var{directory} is already in the path, it
+is moved to the front, so it is searched sooner.
You can use the string @samp{$cwd} to refer to whatever is the current
working directory at the time @value{GDBN} searches the path. If you
your program. You can abbreviate @code{environment} as @code{env}.
@kindex set environment
-@item set environment @var{varname} @r{[}=@r{]} @var{value}
+@item set environment @var{varname} @r{[}=@var{value}@r{]}
Set environment variable @var{varname} to @var{value}. The value
changes for your program only, not for @value{GDBN} itself. @var{value} may
be any string; the values of environment variables are just strings, and
@end example
@noindent
-tells a Unix program, when subsequently run, that its user is named
+tells the debugged program, when subsequently run, that its user is named
@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
are not actually required.)
rather than assigning it an empty value.
@end table
-@emph{Warning:} @value{GDBN} runs your program using the shell indicated
+@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
+the shell indicated
by your @code{SHELL} environment variable if it exists (or
@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
that runs an initialization file---such as @file{.cshrc} for C-shell, or
files that are only run when you sign on, such as @file{.login} or
@file{.profile}.
-@node Working Directory, Input/Output, Environment, Running
+@node Working Directory
@section Your program's working directory
@cindex working directory (of your program)
Print the @value{GDBN} working directory.
@end table
-@node Input/Output, Attach, Working Directory, Running
+@node Input/Output
@section Your program's input and output
@cindex redirection
@cindex i/o
@cindex terminal
By default, the program you run under @value{GDBN} does input and output to
-the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
+the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
to its own terminal modes to interact with you, but it records the terminal
modes your program was using and switches back to them when you continue
running your program.
command, only the input @emph{for your program} is affected. The input
for @value{GDBN} still comes from your terminal.
-@node Attach, Kill Process, Input/Output, Running
+@node Attach
@section Debugging an already-running process
@kindex attach
@cindex attach
The first thing @value{GDBN} does after arranging to debug the specified
process is to stop it. You can examine and modify an attached process
-with all the @value{GDBN} commands that are ordinarily available when you start
-@ifclear HPPA
-processes with @code{run}. You can insert breakpoints; you can step and
-@end ifclear
-@ifset HPPA
-processes with @code{run}. You can insert breakpoints (except in shared
-libraries); you can step and
-@end ifset
-continue; you can modify storage. If you would rather the process
-continue running, you may use the @code{continue} command after
+with all the @value{GDBN} commands that are ordinarily available when
+you start processes with @code{run}. You can insert breakpoints; you
+can step and continue; you can modify storage. If you would rather the
+process continue running, you may use the @code{continue} command after
attaching @value{GDBN} to the process.
@table @code
confirm} command (@pxref{Messages/Warnings, ,Optional warnings and
messages}).
-@node Kill Process, Process Information, Attach, Running
+@node Kill Process
@section Killing the child process
@table @code
reads the symbol table again (while trying to preserve your current
breakpoint settings).
-@node Process Information, Threads, Kill Process, Running
-@section Additional process information
-
-@kindex /proc
-@cindex process image
-
-Some operating systems provide a facility called @samp{/proc} that can
-be used to examine the image of a running process using file-system
-subroutines. If @value{GDBN} is configured for an operating system with this
-facility, the command @code{info proc} is available to report on several
-kinds of information about the process running your program.
-@code{info proc} works only on SVR4 systems that support @code{procfs}.
-This includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware,
-but not HP-UX or Linux, for example.
-
-@table @code
-@kindex info proc
-@item info proc
-Summarize available information about the process.
-
-@kindex info proc mappings
-@item info proc mappings
-Report on the address ranges accessible in the program, with information
-on whether your program may read, write, or execute each range.
-
-@kindex info proc times
-@item info proc times
-Starting time, user CPU time, and system CPU time for your program and
-its children.
-
-@kindex info proc id
-@item info proc id
-Report on the process IDs related to your program: its own process ID,
-the ID of its parent, the process group ID, and the session ID.
-
-@kindex info proc status
-@item info proc status
-General information on the state of the process. If the process is
-stopped, this report includes the reason for stopping, and any signal
-received.
-
-@item info proc all
-Show all the above information about the process.
-@end table
-
-@node Threads, Processes, Process Information, Running
-@section Debugging programs with multiple threads
+@node Threads
+@section Debugging programs with multiple threads
@cindex threads of execution
@cindex multiple threads
@item automatic notification of new threads
@item @samp{thread @var{threadno}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
+@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
@end itemize
-@ifclear HPPA
@quotation
@emph{Warning:} These facilities are not yet available on every
@value{GDBN} configuration where the operating system supports threads.
@c FIXME to implementors: how hard would it be to say "sorry, this GDB
@c doesn't support threads"?
@end quotation
-@end ifclear
@cindex focus of debugging
@cindex current thread
This thread is called the @dfn{current thread}. Debugging commands show
program information from the perspective of the current thread.
-@ifclear HPPA
-@kindex New @var{systag}
+@cindex @code{New} @var{systag} message
@cindex thread identifier (system)
@c FIXME-implementors!! It would be more helpful if the [New...] message
@c included GDB's numeric thread handle, so you could just go to that
@c program?
@c (2) *Is* there necessarily a first thread always? Or do some
@c multithread systems permit starting a program with multiple
-@c threads ab initio?
+@c threads ab initio?
@cindex thread number
@cindex thread identifier (GDB)
An asterisk @samp{*} to the left of the @value{GDBN} thread number
indicates the current thread.
-For example,
+For example,
@end table
@c end table here to get a little more width for example
* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
at threadtest.c:68
@end smallexample
-@end ifclear
-@ifset HPPA
+
+On HP-UX systems:
@cindex thread number
@cindex thread identifier (GDB)
number---a small integer assigned in thread-creation order---with each
thread in your program.
-@kindex New @var{systag}
-@cindex thread identifier (system)
+@cindex @code{New} @var{systag} message, on HP-UX
+@cindex thread identifier (system), on HP-UX
@c FIXME-implementors!! It would be more helpful if the [New...] message
@c included GDB's numeric thread handle, so you could just go to that
@c thread without first checking `info threads'.
@end example
@noindent
-when @value{GDBN} notices a new thread.
+when @value{GDBN} notices a new thread.
@table @code
@kindex info threads
An asterisk @samp{*} to the left of the @value{GDBN} thread number
indicates the current thread.
-For example,
+For example,
@end table
@c end table here to get a little more width for example
@example
(@value{GDBP}) info threads
- * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") at quicksort.c:137
- 2 system thread 26606 0x7b0030d8 in __ksleep () from /usr/lib/libc.2
- 1 system thread 27905 0x7b003498 in _brk () from /usr/lib/libc.2
+ * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
+ at quicksort.c:137
+ 2 system thread 26606 0x7b0030d8 in __ksleep () \@*
+ from /usr/lib/libc.2
+ 1 system thread 27905 0x7b003498 in _brk () \@*
+ from /usr/lib/libc.2
@end example
-@end ifset
@table @code
@kindex thread @var{threadno}
@smallexample
@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one
(@value{GDBP}) thread 2
-@ifclear HPPA
[Switching to process 35 thread 23]
-@end ifclear
-@ifset HPPA
-[Switching to thread 2 (system thread 26594)]
-@end ifset
0x34e5 in sigpause ()
@end smallexample
@noindent
As with the @samp{[New @dots{}]} message, the form of the text after
@samp{Switching to} depends on your system's conventions for identifying
-threads.
+threads.
@kindex thread apply
@item thread apply [@var{threadno}] [@var{all}] @var{args}
more threads. Specify the numbers of the threads that you want affected
with the command argument @var{threadno}. @var{threadno} is the internal
@value{GDBN} thread number, as shown in the first field of the @samp{info
-threads} display. To apply a command to all threads, use
-@code{thread apply all} @var{args}.
+threads} display. To apply a command to all threads, use
+@code{thread apply all} @var{args}.
@end table
@cindex automatic thread selection
@xref{Set Watchpoints,,Setting watchpoints}, for information about
watchpoints in programs with multiple threads.
-@ifclear HPPA
-@node Processes, , Threads, Running
+@node Processes
@section Debugging programs with multiple processes
@cindex fork, debugging programs which call
@cindex multiple processes
@cindex processes, multiple
-@value{GDBN} has no special support for debugging programs which create
-additional processes using the @code{fork} function. When a program
-forks, @value{GDBN} will continue to debug the parent process and the
-child process will run unimpeded. If you have set a breakpoint in any
-code which the child then executes, the child will get a @code{SIGTRAP}
-signal which (unless it catches the signal) will cause it to terminate.
+On most systems, @value{GDBN} has no special support for debugging
+programs which create additional processes using the @code{fork}
+function. When a program forks, @value{GDBN} will continue to debug the
+parent process and the child process will run unimpeded. If you have
+set a breakpoint in any code which the child then executes, the child
+will get a @code{SIGTRAP} signal which (unless it catches the signal)
+will cause it to terminate.
However, if you want to debug the child process there is a workaround
which isn't too painful. Put a call to @code{sleep} in the code which
on the child. While the child is sleeping, use the @code{ps} program to
get its process ID. Then tell @value{GDBN} (a new invocation of
@value{GDBN} if you are also debugging the parent process) to attach to
-the child process (see @ref{Attach}). From that point on you can debug
+the child process (@pxref{Attach}). From that point on you can debug
the child process just like any other process which you attached to.
-@end ifclear
-@ifset HPPA
-@node Processes, , Threads, Running
-@section Debugging programs with multiple processes
-
-@cindex fork, debugging programs which call
-@cindex multiple processes
-@cindex processes, multiple
-@value{GDBN} provides support for debugging programs that create
-additional processes using the @code{fork} or @code{vfork} function.
+On HP-UX (11.x and later only?), @value{GDBN} provides support for
+debugging programs that create additional processes using the
+@code{fork} or @code{vfork} function.
By default, when a program forks, @value{GDBN} will continue to debug
the parent process and the child process will run unimpeded.
@table @code
@item parent
The original process is debugged after a fork. The child process runs
-unimpeded.
+unimpeded. This is the default.
@item child
The new process is debugged after a fork. The parent process runs
@end table
@item show follow-fork-mode
-Display the current debugger response to a fork or vfork call.
+Display the current debugger response to a @code{fork} or @code{vfork} call.
@end table
If you ask to debug a child process and a @code{vfork} is followed by an
You can use the @code{catch} command to make @value{GDBN} stop whenever
a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
Catchpoints, ,Setting catchpoints}.
-@end ifset
-@node Stopping, Stack, Running, Top
+@node Stopping
@chapter Stopping and Continuing
The principal purposes of using a debugger are so that you can stop your
* Thread Stops:: Stopping and starting multi-thread programs
@end menu
-@node Breakpoints, Continuing and Stepping, Stopping, Stopping
+@node Breakpoints
@section Breakpoints, watchpoints, and catchpoints
@cindex breakpoints
@cindex catchpoints
@cindex breakpoint on events
A @dfn{catchpoint} is another special breakpoint that stops your program
-when a certain kind of event occurs, such as the throwing of a C++
+when a certain kind of event occurs, such as the throwing of a C@t{++}
exception or the loading of a library. As with watchpoints, you use a
different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
catchpoints}), but aside from that, you can manage a catchpoint like any
other breakpoint. (To stop when your program receives a signal, use the
-@code{handle} command; @pxref{Signals, ,Signals}.)
+@code{handle} command; see @ref{Signals, ,Signals}.)
@cindex breakpoint numbers
@cindex numbers for breakpoints
@dfn{disabled}; if disabled, it has no effect on your program until you
enable it again.
+@cindex breakpoint ranges
+@cindex ranges of breakpoints
+Some @value{GDBN} commands accept a range of breakpoints on which to
+operate. A breakpoint range is either a single breakpoint number, like
+@samp{5}, or two such numbers, in increasing order, separated by a
+hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
+all breakpoint in that range are operated on.
+
@menu
* Set Breaks:: Setting breakpoints
* Set Watchpoints:: Setting watchpoints
* Conditions:: Break conditions
* Break Commands:: Breakpoint command lists
* Breakpoint Menus:: Breakpoint menus
-
-@c * Error in Breakpoints:: ``Cannot insert breakpoints''
+* Error in Breakpoints:: ``Cannot insert breakpoints''
@end menu
-@node Set Breaks, Set Watchpoints, Breakpoints, Breakpoints
+@node Set Breaks
@subsection Setting breakpoints
-@c FIXME LMB what does GDB do if no code on line of breakpt?
+@c FIXME LMB what does GDB do if no code on line of breakpt?
@c consider in particular declaration with/without initialization.
@c
@c FIXME 2 is there stuff on this already? break at fun start, already init?
@kindex break
-@kindex b
-@kindex $bpnum
+@kindex b @r{(@code{break})}
+@vindex $bpnum@r{, convenience variable}
@cindex latest breakpoint
Breakpoints are set with the @code{break} command (abbreviated
-@code{b}). The debugger convenience variable @samp{$bpnum} records the
-number of the breakpoints you've set most recently; see @ref{Convenience
+@code{b}). The debugger convenience variable @samp{$bpnum} records the
+number of the breakpoint you've set most recently; see @ref{Convenience
Vars,, Convenience variables}, for a discussion of what you can do with
convenience variables.
@table @code
@item break @var{function}
-Set a breakpoint at entry to function @var{function}.
+Set a breakpoint at entry to function @var{function}.
When using source languages that permit overloading of symbols, such as
-C++, @var{function} may refer to more than one possible place to break.
+C@t{++}, @var{function} may refer to more than one possible place to break.
@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation.
@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.
+at which execution stopped in the currently selected @dfn{stack frame}.
+(@xref{Frames, ,Frames}, for a description of stack frames.)
@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 stops your program just before it executes any of the
+The current source file is the last file whose source text was printed.
+The breakpoint will stop your program just before it executes any of the
code on that line.
@item break @var{filename}:@var{linenum}
way, but the breakpoint is automatically deleted after the first time your
program stops there. @xref{Disabling, ,Disabling breakpoints}.
-@ifclear HPPA
@kindex hbreak
@item hbreak @var{args}
-Set a hardware-assisted breakpoint. @var{args} are the same as for the
-@code{break} command and the breakpoint is set in the same way, but the
+Set a hardware-assisted breakpoint. @var{args} are the same as for the
+@code{break} command and the breakpoint is set in the same way, but the
breakpoint requires hardware support and some target hardware may not
have this support. The main purpose of this is EPROM/ROM code
-debugging, so you can set a breakpoint at an instruction without
-changing the instruction. This can be used with the new trap-generation
-provided by SPARClite DSU. DSU will generate traps when a program accesses
-some data or instruction address that is assigned to the debug registers.
-However the hardware breakpoint registers can only take two data breakpoints,
-and @value{GDBN} will reject this command if more than two are used.
-Delete or disable unused hardware breakpoints before setting
-new ones. @xref{Conditions, ,Break conditions}.
+debugging, so you can set a breakpoint at an instruction without
+changing the instruction. This can be used with the new trap-generation
+provided by SPARClite DSU and some x86-based targets. These targets
+will generate traps when a program accesses some data or instruction
+address that is assigned to the debug registers. However the hardware
+breakpoint registers can take a limited number of breakpoints. For
+example, on the DSU, only two data breakpoints can be set at a time, and
+@value{GDBN} will reject this command if more than two are used. Delete
+or disable unused hardware breakpoints before setting new ones
+(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}.
@kindex thbreak
@item thbreak @var{args}
Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
are the same as for the @code{hbreak} command and the breakpoint is set in
-the same way. However, like the @code{tbreak} command,
+the same way. However, like the @code{tbreak} command,
the breakpoint is automatically deleted after the
first time your program stops there. Also, like the @code{hbreak}
-command, the breakpoint requires hardware support and some target hardware
-may not have this support. @xref{Disabling, ,Disabling breakpoints}.
-Also @xref{Conditions, ,Break conditions}.
-@end ifclear
+command, the breakpoint requires hardware support and some target hardware
+may not have this support. @xref{Disabling, ,Disabling breakpoints}.
+See also @ref{Conditions, ,Break conditions}.
@kindex rbreak
@cindex regular expression
@item rbreak @var{regex}
-@c FIXME what kind of regexp?
Set breakpoints on all functions matching the regular expression
-@var{regex}. This command
-sets an unconditional breakpoint on all matches, printing a list of all
-breakpoints it set. Once these breakpoints are set, they are treated
-just like the breakpoints set with the @code{break} command. You can
-delete them, disable them, or make them conditional the same way as any
-other breakpoint.
-
-When debugging C++ programs, @code{rbreak} is useful for setting
+@var{regex}. This command sets an unconditional breakpoint on all
+matches, printing a list of all breakpoints it set. Once these
+breakpoints are set, they are treated just like the breakpoints set with
+the @code{break} command. You can delete them, disable them, or make
+them conditional the same way as any other breakpoint.
+
+The syntax of the regular expression is the standard one used with tools
+like @file{grep}. Note that this is different from the syntax used by
+shells, so for instance @code{foo*} matches all functions that include
+an @code{fo} followed by zero or more @code{o}s. There is an implicit
+@code{.*} leading and trailing the regular expression you supply, so to
+match only functions that begin with @code{foo}, use @code{^foo}.
+
+When debugging C@t{++} programs, @code{rbreak} is useful for setting
breakpoints on overloaded functions that are not members of any special
classes.
Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
that are not enabled.
@item Address
-Where the breakpoint is in your program, as a memory address
+Where the breakpoint is in your program, as a memory address.
@item What
Where the breakpoint is in the source for your program, as a file and
line number.
number @var{n} as argument lists only that breakpoint. The
convenience variable @code{$_} and the default examining-address for
the @code{x} command are set to the address of the last breakpoint
-listed (@pxref{Memory, ,Examining memory}).
+listed (@pxref{Memory, ,Examining memory}).
@noindent
@code{info break} displays a count of the number of times the breakpoint
@cindex negative breakpoint numbers
@cindex internal @value{GDBN} breakpoints
-@value{GDBN} itself sometimes sets breakpoints in your program for special
-purposes, such as proper handling of @code{longjmp} (in C programs).
-These internal breakpoints are assigned negative numbers, starting with
-@code{-1}; @samp{info breakpoints} does not display them.
-
+@value{GDBN} itself sometimes sets breakpoints in your program for
+special purposes, such as proper handling of @code{longjmp} (in C
+programs). These internal breakpoints are assigned negative numbers,
+starting with @code{-1}; @samp{info breakpoints} does not display them.
You can see these breakpoints with the @value{GDBN} maintenance command
-@samp{maint info breakpoints}.
-
-@table @code
-@kindex maint info breakpoints
-@item maint info breakpoints
-Using the same format as @samp{info breakpoints}, display both the
-breakpoints you've set explicitly, and those @value{GDBN} is using for
-internal purposes. Internal breakpoints are shown with negative
-breakpoint numbers. The type column identifies what kind of breakpoint
-is shown:
-
-@table @code
-@item breakpoint
-Normal, explicitly set breakpoint.
-
-@item watchpoint
-Normal, explicitly set watchpoint.
-
-@item longjmp
-Internal breakpoint, used to handle correctly stepping through
-@code{longjmp} calls.
-
-@item longjmp resume
-Internal breakpoint at the target of a @code{longjmp}.
-
-@item until
-Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
-
-@item finish
-Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
-
-@ifset HPPA
-@item shlib events
-Shared library events.
-@end ifset
-@end table
-@end table
+@samp{maint info breakpoints} (@pxref{maint info breakpoints}).
-@node Set Watchpoints, Set Catchpoints, Set Breaks, Breakpoints
+@node Set Watchpoints
@subsection Setting watchpoints
@cindex setting watchpoints
this may happen.
Depending on your system, watchpoints may be implemented in software or
-hardware. GDB does software watchpointing by single-stepping your
+hardware. @value{GDBN} does software watchpointing by single-stepping your
program and testing the variable's value each time, which is hundreds of
times slower than normal execution. (But this may still be worth it, to
catch errors where you have no clue what part of your program is the
culprit.)
-On some systems, such as HP-UX and Linux, GDB includes support for
+On some systems, such as HP-UX, Linux and some other x86-based targets,
+@value{GDBN} includes support for
hardware watchpoints, which do not slow down the running of your
program.
@kindex rwatch
@item rwatch @var{expr}
Set a watchpoint that will break when watch @var{expr} is read by the program.
-If you use both watchpoints, both must be set with the @code{rwatch}
-command.
@kindex awatch
@item awatch @var{expr}
-Set a watchpoint that will break when @var{args} is read and written into
-by the program. If you use both watchpoints, both must be set with the
-@code{awatch} command.
+Set a watchpoint that will break when @var{expr} is either read or written into
+by the program.
@kindex info watchpoints
@item info watchpoints
@noindent
if it was able to set a hardware watchpoint.
-The SPARClite DSU will generate traps when a program accesses
-some data or instruction address that is assigned to the debug registers.
-For the data addresses, DSU facilitates the @code{watch} command.
-However the hardware breakpoint registers can only take two data watchpoints,
-and both watchpoints must be the same kind. For example, you can set two
-watchpoints with @code{watch} commands, two with @code{rwatch}
-commands, @strong{or} two with @code{awatch} commands, but you cannot set one
-watchpoint with one command and the other with a different command.
+Currently, the @code{awatch} and @code{rwatch} commands can only set
+hardware watchpoints, because accesses to data that don't change the
+value of the watched expression cannot be detected without examining
+every instruction as it is being executed, and @value{GDBN} does not do
+that currently. If @value{GDBN} finds that it is unable to set a
+hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
+will print a message like this:
+
+@smallexample
+Expression cannot be implemented with read/access watchpoint.
+@end smallexample
+
+Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
+data type of the watched expression is wider than what a hardware
+watchpoint on the target machine can handle. For example, some systems
+can only watch regions that are up to 4 bytes wide; on such systems you
+cannot set hardware watchpoints for an expression that yields a
+double-precision floating-point number (which is typically 8 bytes
+wide). As a work-around, it might be possible to break the large region
+into a series of smaller ones and watch them with separate watchpoints.
+
+If you set too many hardware watchpoints, @value{GDBN} might be unable
+to insert all of them when you resume the execution of your program.
+Since the precise number of active watchpoints is unknown until such
+time as the program is about to be resumed, @value{GDBN} might not be
+able to warn you about this when you set the watchpoints, and the
+warning will be printed only when the program is resumed:
+
+@smallexample
+Hardware watchpoint @var{num}: Could not insert watchpoint
+@end smallexample
+
+@noindent
+If this happens, delete or disable some of the watchpoints.
+
+The SPARClite DSU will generate traps when a program accesses some data
+or instruction address that is assigned to the debug registers. For the
+data addresses, DSU facilitates the @code{watch} command. However the
+hardware breakpoint registers can only take two data watchpoints, and
+both watchpoints must be the same kind. For example, you can set two
+watchpoints with @code{watch} commands, two with @code{rwatch} commands,
+@strong{or} two with @code{awatch} commands, but you cannot set one
+watchpoint with one command and the other with a different command.
@value{GDBN} will reject the command if you try to mix watchpoints.
Delete or disable unused watchpoint commands before setting new ones.
If you call a function interactively using @code{print} or @code{call},
-any watchpoints you have set will be inactive until GDB reaches another
+any watchpoints you have set will be inactive until @value{GDBN} reaches another
kind of breakpoint or the call completes.
+@value{GDBN} automatically deletes watchpoints that watch local
+(automatic) variables, or expressions that involve such variables, when
+they go out of scope, that is, when the execution leaves the block in
+which these variables were defined. In particular, when the program
+being debugged terminates, @emph{all} local variables go out of scope,
+and so only watchpoints that watch global variables remain set. If you
+rerun the program, you will need to set all such watchpoints again. One
+way of doing that would be to set a code breakpoint at the entry to the
+@code{main} function and when it breaks, set all the watchpoints.
+
@quotation
@cindex watchpoints and threads
@cindex threads and watchpoints
-@ifclear HPPA
@emph{Warning:} In multi-thread programs, watchpoints have only limited
usefulness. With the current watchpoint implementation, @value{GDBN}
can only watch the value of an expression @emph{in a single thread}. If
can become current), then you can use watchpoints as usual. However,
@value{GDBN} may not notice when a non-current thread's activity changes
the expression.
-@end ifclear
-@ifset HPPA
-@emph{Warning:} In multi-thread programs, software watchpoints have only
-limited usefulness. If @value{GDBN} creates a software watchpoint, it
-can only watch the value of an expression @emph{in a single thread}. If
-you are confident that the expression can only change due to the current
-thread's activity (and if you are also confident that no other thread
-can become current), then you can use software watchpoints as usual.
-However, @value{GDBN} may not notice when a non-current thread's
-activity changes the expression. (Hardware watchpoints, in contrast,
-watch an expression in all threads.)
-@end ifset
+
+@c FIXME: this is almost identical to the previous paragraph.
+@emph{HP-UX Warning:} In multi-thread programs, software watchpoints
+have only limited usefulness. If @value{GDBN} creates a software
+watchpoint, it can only watch the value of an expression @emph{in a
+single thread}. If you are confident that the expression can only
+change due to the current thread's activity (and if you are also
+confident that no other thread can become current), then you can use
+software watchpoints as usual. However, @value{GDBN} may not notice
+when a non-current thread's activity changes the expression. (Hardware
+watchpoints, in contrast, watch an expression in all threads.)
@end quotation
-@node Set Catchpoints, Delete Breaks, Set Watchpoints, Breakpoints
+@node Set Catchpoints
@subsection Setting catchpoints
-@cindex catchpoints
+@cindex catchpoints, setting
@cindex exception handlers
@cindex event handling
You can use @dfn{catchpoints} to cause the debugger to stop for certain
-kinds of program events, such as C++ exceptions or the loading of a
+kinds of program events, such as C@t{++} exceptions or the loading of a
shared library. Use the @code{catch} command to set a catchpoint.
@table @code
@table @code
@item throw
@kindex catch throw
-The throwing of a C++ exception.
+The throwing of a C@t{++} exception.
@item catch
@kindex catch catch
-The catching of a C++ exception.
+The catching of a C@t{++} exception.
@item exec
@kindex catch exec
Use the @code{info break} command to list the current catchpoints.
-There are currently some limitations to C++ exception handling
+There are currently some limitations to C@t{++} exception handling
(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
@itemize @bullet
out where the exception was raised.
To stop just before an exception handler is called, you need some
-knowledge of the implementation. In the case of @sc{gnu} C++, exceptions are
+knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are
raised by calling a library function named @code{__raise_exception}
which has the following ANSI C interface:
@example
/* @var{addr} is where the exception identifier is stored.
- ID is the exception identifier. */
- void __raise_exception (void **@var{addr}, void *@var{id});
+ @var{id} is the exception identifier. */
+ void __raise_exception (void **addr, void *id);
@end example
@noindent
raised.
-@node Delete Breaks, Disabling, Set Catchpoints, Breakpoints
+@node Delete Breaks
@subsection Deleting breakpoints
@cindex clearing breakpoints, watchpoints, catchpoints
@cindex delete breakpoints
@kindex delete
-@kindex d
-@item delete @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
-Delete the breakpoints, watchpoints, or catchpoints of the numbers
-specified as arguments. If no argument is specified, delete all
+@kindex d @r{(@code{delete})}
+@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
+ranges specified as arguments. If no argument is specified, delete all
breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
confirm off}). You can abbreviate this command as @code{d}.
@end table
-@node Disabling, Conditions, Delete Breaks, Breakpoints
+@node Disabling
@subsection Disabling breakpoints
@kindex disable breakpoints
Disabled. The breakpoint has no effect on your program.
@item
Enabled once. The breakpoint stops your program, but then becomes
-disabled. A breakpoint set with the @code{tbreak} command starts out in
-this state.
+disabled.
@item
Enabled for deletion. The breakpoint stops your program, but
-immediately after it does so it is deleted permanently.
+immediately after it does so it is deleted permanently. A breakpoint
+set with the @code{tbreak} command starts out in this state.
@end itemize
You can use the following commands to enable or disable breakpoints,
@table @code
@kindex disable breakpoints
@kindex disable
-@kindex dis
-@item disable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
+@kindex dis @r{(@code{disable})}
+@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
Disable the specified breakpoints---or all breakpoints, if none are
listed. A disabled breakpoint has no effect but is not forgotten. All
options such as ignore-counts, conditions and commands are remembered in
@kindex enable breakpoints
@kindex enable
-@item enable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
+@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
Enable the specified breakpoints (or all defined breakpoints). They
become effective once again in stopping your program.
-@item enable @r{[}breakpoints@r{]} once @var{bnums}@dots{}
+@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
Enable the specified breakpoints temporarily. @value{GDBN} disables any
of these breakpoints immediately after stopping your program.
-@item enable @r{[}breakpoints@r{]} delete @var{bnums}@dots{}
+@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
Enable the specified breakpoints to work once, then die. @value{GDBN}
deletes any of these breakpoints as soon as your program stops there.
@end table
+@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
+@c confusing: tbreak is also initially enabled.
Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
,Setting breakpoints}), breakpoints that you set are initially enabled;
subsequently, they become disabled or enabled only when you use one of
breakpoints; see @ref{Continuing and Stepping, ,Continuing and
stepping}.)
-@node Conditions, Break Commands, Disabling, Breakpoints
+@node Conditions
@subsection Break conditions
@cindex conditional breakpoints
@cindex breakpoint conditions
@c FIXME what is scope of break condition expr? Context where wanted?
-@c in particular for a watchpoint?
+@c in particular for a watchpoint?
The simplest sort of breakpoint breaks every time your program reaches a
specified place. You can also specify a @dfn{condition} for a
breakpoint. A condition is just a Boolean expression in your
unless there is another enabled breakpoint at the same address. (In
that case, @value{GDBN} might see the other breakpoint first and stop your
program without checking the condition of this one.) Note that
-breakpoint commands are usually more convenient and flexible for the
+breakpoint commands are usually more convenient and flexible than break
+conditions for the
purpose of performing side effects when a breakpoint is reached
(@pxref{Break Commands, ,Breakpoint command lists}).
@samp{if} in the arguments to the @code{break} command. @xref{Set
Breaks, ,Setting breakpoints}. They can also be changed at any time
with the @code{condition} command.
-@ifclear HPPA
-@c The watch command now seems to recognize the if keyword.
-@c catch doesn't, though.
-The @code{watch} command does not recognize the @code{if} keyword;
-@code{condition} is the only way to impose a further condition on a
-watchpoint.
-@end ifclear
-@ifset HPPA
+
You can also use the @code{if} keyword with the @code{watch} command.
The @code{catch} command does not recognize the @code{if} keyword;
@code{condition} is the only way to impose a further condition on a
catchpoint.
-@end ifset
@table @code
@kindex condition
@var{expression} is true (nonzero, in C). When you use
@code{condition}, @value{GDBN} checks @var{expression} immediately for
syntactic correctness, and to determine whether symbols in it have
-referents in the context of your breakpoint.
-@c FIXME so what does GDB do if there is no referent? Moreover, what
-@c about watchpoints?
+referents in the context of your breakpoint. If @var{expression} uses
+symbols not referenced in the context of the breakpoint, @value{GDBN}
+prints an error message:
+
+@example
+No symbol "foo" in current context.
+@end example
+
+@noindent
@value{GDBN} does
not actually evaluate @var{expression} at the time the @code{condition}
-command is given, however. @xref{Expressions, ,Expressions}.
+command (or a command that sets a breakpoint with a condition, like
+@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}.
@item condition @var{bnum}
Remove the condition from breakpoint number @var{bnum}. It becomes
Ignore counts apply to breakpoints, watchpoints, and catchpoints.
-@node Break Commands, Breakpoint Menus, Conditions, Breakpoints
+@node Break Commands
@subsection Breakpoint command lists
@cindex breakpoint commands
end
@end example
-@node Breakpoint Menus, , Break Commands, Breakpoints
+@node Breakpoint Menus
@subsection Breakpoint menus
@cindex overloading
@cindex symbol overloading
-Some programming languages (notably C++) permit a single function name
+Some programming languages (notably C@t{++}) permit a single function name
to be defined several times, for application in different contexts.
This is called @dfn{overloading}. When a function name is overloaded,
@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
@end smallexample
@c @ifclear BARETARGET
-@c @node Error in Breakpoints
-@c @subsection ``Cannot insert breakpoints''
+@node Error in Breakpoints
+@subsection ``Cannot insert breakpoints''
@c
@c FIXME!! 14/6/95 Is there a real example of this? Let's use it.
@c
-@c Under some operating systems, breakpoints cannot be used in a program if
-@c any other process is running that program. In this situation,
-@c attempting to run or continue a program with a breakpoint causes
-@c @value{GDBN} to stop the other process.
-@c
-@c When this happens, you have three ways to proceed:
-@c
-@c @enumerate
-@c @item
-@c Remove or disable the breakpoints, then continue.
-@c
-@c @item
-@c Suspend @value{GDBN}, and copy the file containing your program to a new
-@c name. Resume @value{GDBN} and use the @code{exec-file} command to specify
-@c that @value{GDBN} should run your program under that name.
-@c Then start your program again.
-@c
-@c @item
-@c Relink your program so that the text segment is nonsharable, using the
-@c linker option @samp{-N}. The operating system limitation may not apply
-@c to nonsharable executables.
-@c @end enumerate
+Under some operating systems, breakpoints cannot be used in a program if
+any other process is running that program. In this situation,
+attempting to run or continue a program with a breakpoint causes
+@value{GDBN} to print an error message:
+
+@example
+Cannot insert breakpoints.
+The same program may be running in another process.
+@end example
+
+When this happens, you have three ways to proceed:
+
+@enumerate
+@item
+Remove or disable the breakpoints, then continue.
+
+@item
+Suspend @value{GDBN}, and copy the file containing your program to a new
+name. Resume @value{GDBN} and use the @code{exec-file} command to specify
+that @value{GDBN} should run your program under that name.
+Then start your program again.
+
+@item
+Relink your program so that the text segment is nonsharable, using the
+linker option @samp{-N}. The operating system limitation may not apply
+to nonsharable executables.
+@end enumerate
@c @end ifclear
-@node Continuing and Stepping, Signals, Breakpoints, Stopping
+A similar message can be printed if you request too many active
+hardware-assisted breakpoints and watchpoints:
+
+@c FIXME: the precise wording of this message may change; the relevant
+@c source change is not committed yet (Sep 3, 1999).
+@smallexample
+Stopped; cannot insert breakpoints.
+You may have requested too many hardware breakpoints and watchpoints.
+@end smallexample
+
+@noindent
+This message is printed when you attempt to resume the program, since
+only then @value{GDBN} knows exactly how many hardware breakpoints and
+watchpoints it needs to insert.
+
+When this message is printed, you need to disable or remove some of the
+hardware-assisted breakpoints and watchpoints, and then continue.
+
+
+@node Continuing and Stepping
@section Continuing and stepping
@cindex stepping
line of source code, or one machine instruction (depending on what
particular command you use). Either when continuing or when stepping,
your program may stop even sooner, due to a breakpoint or a signal. (If
-due to a signal, you may want to use @code{handle}, or use @samp{signal
-0} to resume execution. @xref{Signals, ,Signals}.)
+it stops due to a signal, you may want to use @code{handle}, or use
+@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
@table @code
@kindex continue
-@kindex c
-@kindex fg
+@kindex c @r{(@code{continue})}
+@kindex fg @r{(resume foreground execution)}
@item continue @r{[}@var{ignore-count}@r{]}
@itemx c @r{[}@var{ignore-count}@r{]}
@itemx fg @r{[}@var{ignore-count}@r{]}
stopped due to a breakpoint. At other times, the argument to
@code{continue} is ignored.
-The synonyms @code{c} and @code{fg} are provided purely for convenience,
-and have exactly the same behavior as @code{continue}.
+The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the
+debugged program is deemed to be the foreground program) are provided
+purely for convenience, and have exactly the same behavior as
+@code{continue}.
@end table
To resume execution at a different place, you can use @code{return}
@table @code
@kindex step
-@kindex s
+@kindex s @r{(@code{step})}
@item step
Continue running your program until control reaches a different source
line, then stop it and return control to @value{GDBN}. This command is
below.
@end quotation
-The @code{step} command now only stops at the first instruction of a
-source line. This prevents the multiple stops that used to occur in
-switch statements, for loops, etc. @code{step} continues to stop if a
-function that has debugging information is called within the line.
+The @code{step} command only stops at the first instruction of a source
+line. This prevents the multiple stops that could otherwise occur in
+@code{switch} statements, @code{for} loops, etc. @code{step} continues
+to stop if a function that has debugging information is called within
+the line. In other words, @code{step} @emph{steps inside} any functions
+called within the line.
-Also, the @code{step} command now only enters a subroutine if there is line
-number information for the subroutine. Otherwise it acts like the
-@code{next} command. This avoids problems when using @code{cc -gl}
+Also, the @code{step} command only enters a function if there is line
+number information for the function. Otherwise it acts like the
+@code{next} command. This avoids problems when using @code{cc -gl}
on MIPS machines. Previously, @code{step} entered subroutines if there
-was any debugging information about the routine.
+was any debugging information about the routine.
@item step @var{count}
Continue running as in @code{step}, but do so @var{count} times. If a
@var{count} steps, stepping stops right away.
@kindex next
-@kindex n
+@kindex n @r{(@code{next})}
@item next @r{[}@var{count}@r{]}
Continue to the next source line in the current (innermost) stack frame.
This is similar to @code{step}, but function calls that appear within
@c @code{step}, but any function calls appearing within the code of the
@c function are executed without stopping.
-The @code{next} command now only stops at the first instruction of a
-source line. This prevents the multiple stops that used to occur in
-switch statements, for loops, etc.
+The @code{next} command only stops at the first instruction of a
+source line. This prevents multiple stops that could otherwise occur in
+@code{switch} statements, @code{for} loops, etc.
+
+@kindex set step-mode
+@item set step-mode
+@cindex functions without line info, and stepping
+@cindex stepping into functions with no line info
+@itemx set step-mode on
+The @code{set step-mode on} command causes the @code{step} command to
+stop at the first instruction of a function which contains no debug line
+information rather than stepping over it.
+
+This is useful in cases where you may be interested in inspecting the
+machine instructions of a function which has no symbolic info and do not
+want @value{GDBN} to automatically skip over this function.
+
+@item set step-mode off
+Causes the @code{step} command to step over any functions which contains no
+debug information. This is the default.
@kindex finish
@item finish
,Returning from a function}).
@kindex until
-@kindex u
+@kindex u @r{(@code{until})}
@item until
@itemx u
Continue running until a source line past the current line, in the
and hence is quicker than @code{until} without an argument.
@kindex stepi
-@kindex si
+@kindex si @r{(@code{stepi})}
@item stepi
+@itemx stepi @var{arg}
@itemx si
Execute one machine instruction, then stop and return to the debugger.
@need 750
@kindex nexti
-@kindex ni
+@kindex ni @r{(@code{nexti})}
@item nexti
+@itemx nexti @var{arg}
@itemx ni
Execute one machine instruction, but if it is a function call,
proceed until the function returns.
An argument is a repeat count, as in @code{next}.
@end table
-@node Signals, Thread Stops, Continuing and Stepping, Stopping
+@node Signals
@section Signals
@cindex signals
A signal is an asynchronous event that can happen in a program. The
operating system defines the possible kinds of signals, and gives each
kind a name and a number. For example, in Unix @code{SIGINT} is the
-signal a program gets when you type an interrupt (often @kbd{C-c});
+signal a program gets when you type an interrupt character (often @kbd{C-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 your program has
@cindex fatal signals
Some signals, including @code{SIGALRM}, are a normal part of the
functioning of your program. Others, such as @code{SIGSEGV}, indicate
-errors; these signals are @dfn{fatal} (kill your program immediately) if the
+errors; these signals are @dfn{fatal} (they kill your 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 your program, but it is normally
fatal so it can carry out the purpose of the interrupt: to kill the program.
signal.
@cindex handling signals
-Normally, @value{GDBN} is set up to ignore non-erroneous signals like @code{SIGALRM}
-(so as not to interfere with their role in the functioning of your program)
+Normally, @value{GDBN} is set up to let the non-erroneous signals like
+@code{SIGALRM} be silently passed to your program
+(so as not to interfere with their role in the program's functioning)
but to stop your program immediately whenever an error signal happens.
You can change these settings with the @code{handle} command.
@table @code
@kindex info signals
@item info signals
+@itemx info handle
Print a table of all the kinds of signals and how @value{GDBN} has been told to
handle each one. You can use this to see the signal numbers of all
the defined types of signals.
-@code{info handle} is the new alias for @code{info signals}.
+@code{info handle} is an alias for @code{info signals}.
@kindex handle
@item handle @var{signal} @var{keywords}@dots{}
-Change the way @value{GDBN} 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.
+Change the way @value{GDBN} 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); a list of signal numbers of the form
+@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
+known signals. The @var{keywords} say what change to make.
@end table
@c @group
implies the @code{nostop} keyword as well.
@item pass
+@itemx noignore
@value{GDBN} should allow your program to see this signal; your program
can handle the signal, or else it may terminate if the signal is fatal
-and not handled.
+and not handled. @code{pass} and @code{noignore} are synonyms.
@item nopass
+@itemx ignore
@value{GDBN} should not allow your program to see this signal.
+@code{nopass} and @code{ignore} are synonyms.
@end table
@c @end group
-When a signal stops your program, the signal is not visible until you
+When a signal stops your program, the signal is not visible to the
+program until you
continue. Your program sees the signal then, if @code{pass} is in
effect for the signal in question @emph{at that time}. In other words,
after @value{GDBN} reports a signal, you can use the @code{handle}
command with @code{pass} or @code{nopass} to control whether your
program sees that signal when you continue.
+The default is set to @code{nostop}, @code{noprint}, @code{pass} for
+non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and
+@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the
+erroneous signals.
+
You can also use the @code{signal} command to prevent your 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. For example, if your program stopped
execution; but your program would probably terminate immediately as
a result of the fatal signal once it saw the signal. To prevent this,
you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
-program a signal}.
+program a signal}.
-@node Thread Stops, , Signals, Stopping
+@node Thread Stops
@section Stopping and starting multi-thread programs
When your program has multiple threads (@pxref{Threads,, Debugging
breakpoint condition, like this:
@smallexample
-(gdb) break frik.c:13 thread 28 if bartab > lim
+(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim
@end smallexample
@end table
@cindex threads, continuing
Conversely, whenever you restart the program, @emph{all} threads start
executing. @emph{This is true even when single-stepping} with commands
-like @code{step} or @code{next}.
+like @code{step} or @code{next}.
In particular, @value{GDBN} cannot single-step all threads in lockstep.
Since thread scheduling is up to your debugging target's operating
mode optimizes for single-stepping. It stops other threads from
``seizing the prompt'' by preempting the current thread while you are
stepping. Other threads will only rarely (or never) get a chance to run
-when you step. They are more likely to run when you ``next'' over a
+when you step. They are more likely to run when you @samp{next} over a
function call, and they are completely free to run when you use commands
-like ``continue'', ``until'', or ``finish''. However, unless another
+like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
thread hits a breakpoint during its timeslice, they will never steal the
-GDB prompt away from the thread that you are debugging.
+@value{GDBN} prompt away from the thread that you are debugging.
@item show scheduler-locking
Display the current scheduler locking mode.
@end table
-@node Stack, Source, Stopping, Top
+@node Stack
@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, information about the call
-is generated.
-That information includes the location of the call in your program,
-the arguments of the call,
+Each time your program performs a function call, information about the call
+is generated.
+That information includes the location of the call in your program,
+the arguments of the call,
and the local variables of the function being called.
-The information is saved in a block of data called a @dfn{stack frame}.
+The information is saved in a block of data called a @dfn{stack frame}.
The stack frames are allocated in a region of memory called the @dfn{call
stack}.
interested in. @xref{Selection, ,Selecting a frame}.
When your program stops, @value{GDBN} automatically selects the
-currently executing frame and describes it briefly, similar to the
+currently executing frame and describes it briefly, similar to the
@code{frame} command (@pxref{Frame Info, ,Information about a frame}).
@menu
* Backtrace:: Backtraces
* Selection:: Selecting a frame
* Frame Info:: Information on a frame
-* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack
@end menu
-@node Frames, Backtrace, Stack, Stack
+@node Frames
@section Stack frames
-@cindex frame
+@cindex frame, definition
@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
they are assigned by @value{GDBN} to give you a way of designating stack
frames in @value{GDBN} commands.
-@c below produces an acceptable overful hbox. --mew 13aug1993
+@c The -fomit-frame-pointer below perennially causes hbox overflow
+@c underflow problems.
@cindex frameless execution
Some compilers provide a way to compile functions so that they operate
-without stack frames. (For example, the @code{@value{GCC}} option
-@samp{-fomit-frame-pointer} generates functions without a frame.)
+without stack frames. (For example, the @value{GCC} option
+@example
+@samp{-fomit-frame-pointer}
+@end example
+generates functions without a frame.)
This is occasionally done with heavily used library functions to save
the frame setup time. @value{GDBN} has limited facilities for dealing
with these function invocations. If the innermost function invocation
no provision for frameless functions elsewhere in the stack.
@table @code
-@kindex frame
+@kindex frame@r{, command}
+@cindex current stack frame
@item frame @var{args}
-The @code{frame} command allows you to move from one stack frame to another,
+The @code{frame} command allows you to move from one stack frame to another,
and to print the stack frame you select. @var{args} may be either the
-address of the frame or the stack frame number. Without an argument,
-@code{frame} prints the current stack frame.
+address of the frame or the stack frame number. Without an argument,
+@code{frame} prints the current stack frame.
@kindex select-frame
+@cindex selecting frame silently
@item select-frame
The @code{select-frame} command allows you to move from one stack frame
to another without printing the frame. This is the silent version of
@code{frame}.
@end table
-@node Backtrace, Selection, Frames, Stack
+@node Backtrace
@section Backtraces
@cindex backtraces
@table @code
@kindex backtrace
-@kindex bt
+@kindex bt @r{(@code{backtrace})}
@item backtrace
@itemx bt
Print a backtrace of the entire stack: one line per frame for all
@kindex where
@kindex info stack
-@kindex info s
+@kindex info s @r{(@code{info stack})}
The names @code{where} and @code{info stack} (abbreviated @code{info s})
are additional aliases for @code{backtrace}.
@smallexample
@group
-#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
+#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
value, indicating that your program has stopped at the beginning of the
code for line @code{993} of @code{builtin.c}.
-@node Selection, Frame Info, Backtrace, Stack
+@node Selection
@section Selecting a frame
Most commands for examining the stack and other data in your program work on
of the stack frame just selected.
@table @code
-@kindex frame
-@kindex f
+@kindex frame@r{, selecting}
+@kindex f @r{(@code{frame})}
@item frame @var{n}
@itemx f @var{n}
Select frame number @var{n}. Recall that frame zero is the innermost
addition, this can be useful when your program has multiple stacks and
switches between them.
-@ifclear HPPA
On the SPARC architecture, @code{frame} needs two addresses to
select an arbitrary frame: a frame pointer and a stack pointer.
@c note to future updaters: this is conditioned on a flag
@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date
@c as of 27 Jan 1994.
-@end ifclear
@kindex up
@item up @var{n}
that have existed longer. @var{n} defaults to one.
@kindex down
-@kindex do
+@kindex do @r{(@code{down})}
@item down @var{n}
Move @var{n} frames down the stack. For positive numbers @var{n}, this
advances toward the innermost frame, to lower frame numbers, to frames
All of these commands end by printing two lines of output describing the
frame. The first line shows the frame number, the function name, the
arguments, and the source file and line number of execution in that
-frame. The second line shows the text of that source line.
+frame. The second line shows the text of that source line.
@need 1000
For example:
distracting.
@end table
-@node Frame Info, Alpha/MIPS Stack, Selection, Stack
+@node Frame Info
@section Information about a frame
There are several other commands to print information about the selected
@xref{Selection, ,Selecting a frame}.
@kindex info frame
-@kindex info f
+@kindex info f @r{(@code{info frame})}
@item info frame
@itemx info f
This command prints a verbose description of the selected stack frame,
including:
@itemize @bullet
-@item
-the address of the frame
+@item
+the address of the frame
@item
the address of the next frame down (called by this frame)
@item
@item
the address of the frame's arguments
@item
+the address of the frame's local variables
+@item
the program counter saved in it (the address of execution in the caller frame)
@item
which registers were saved in the frame
line. These are all variables (declared either static or automatic)
accessible at the point of execution of the selected frame.
-@ifclear HPPA
@kindex info catch
-@cindex catch exceptions
-@cindex exception handlers
+@cindex catch exceptions, list active handlers
+@cindex exception handlers, how to list
@item info catch
Print a list of all the exception handlers that are active in the
current stack frame at the current point of execution. To see other
exception handlers, visit the associated frame (using the @code{up},
@code{down}, or @code{frame} commands); then type @code{info catch}.
@xref{Set Catchpoints, , Setting catchpoints}.
-@end ifclear
-@end table
-
-@node Alpha/MIPS Stack, , Frame Info, Stack
-@section MIPS/Alpha machines and the function stack
-
-@cindex stack on Alpha
-@cindex stack on MIPS
-@cindex Alpha stack
-@cindex MIPS stack
-Alpha- and MIPS-based computers use an unusual stack frame, which
-sometimes requires @value{GDBN} to search backward in the object code to
-find the beginning of a function.
-
-@cindex response time, MIPS debugging
-To improve response time (especially for embedded applications, where
-@value{GDBN} may be restricted to a slow serial line for this search)
-you may want to limit the size of this search, using one of these
-commands:
-@table @code
-@cindex @code{heuristic-fence-post} (Alpha,MIPS)
-@item set heuristic-fence-post @var{limit}
-Restrict @value{GDBN} to examining at most @var{limit} bytes in its search
-for the beginning of a function. A value of @var{0} (the default)
-means there is no limit. However, except for @var{0}, the larger the
-limit the more bytes @code{heuristic-fence-post} must search and
-therefore the longer it takes to run.
-
-@item show heuristic-fence-post
-Display the current limit.
@end table
-@noindent
-These commands are available @emph{only} when @value{GDBN} is configured
-for debugging programs on Alpha or MIPS processors.
-
-@node Source, Data, Stack, Top
+@node Source
@chapter Examining Source Files
@value{GDBN} can print parts of your program's source, since the debugging
source files by explicit command.
If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may
-prefer to use Emacs facilities to view source; @pxref{Emacs, ,Using
+prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
@value{GDBN} under @sc{gnu} Emacs}.
@menu
* Machine Code:: Source and machine code
@end menu
-@node List, Search, Source, Source
+@node List
@section Printing source lines
@kindex list
-@kindex l
+@kindex l @r{(@code{list})}
To print lines from a source file, use the @code{list} command
-(abbreviated @code{l}). By default, ten lines are printed.
+(abbreviated @code{l}). By default, ten lines are printed.
There are several ways to specify what part of the file you want to print.
Here are the forms of the @code{list} command most commonly used:
@cindex linespec
In general, the @code{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.
+of writing them, but the effect is always to specify some source line.
Here is a complete description of the possible arguments for @code{list}:
@table @code
@var{address} may be any expression.
@end table
-@node Search, Source Path, List, Source
+@node Search
@section Searching source files
@cindex searching
@kindex reverse-search
@itemx search @var{regexp}
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 use the
+@var{regexp}. It lists the line that is found. You can use the
synonym @samp{search @var{regexp}} or abbreviate the command name as
@code{fo}.
this command as @code{rev}.
@end table
-@node Source Path, Machine Code, Search, Source
+@node Source Path
@section Specifying source directories
@cindex source path
@kindex directory
@kindex dir
-When you start @value{GDBN}, its source path is empty.
+When you start @value{GDBN}, its source path includes only @samp{cdir}
+and @samp{cwd}, in that order.
To add other directories, use the @code{directory} command.
@table @code
@item directory @var{dirname} @dots{}
@item dir @var{dirname} @dots{}
Add directory @var{dirname} to the front of the source path. Several
-directory names may be given to this command, separated by @samp{:} or
+directory names may be given to this command, separated by @samp{:}
+(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as
+part of absolute file names) or
whitespace. You may specify a directory that is already in the source
path; this moves it forward, so @value{GDBN} searches it sooner.
@kindex cdir
@kindex cwd
-@kindex $cdir
-@kindex $cwd
+@vindex $cdir@r{, convenience variable}
+@vindex $cwdr@r{, convenience variable}
@cindex compilation directory
@cindex current directory
@cindex working directory
directories in one command.
@end enumerate
-@node Machine Code, , Source Path, Source
+@node Machine Code
@section Source and machine code
You can use the command @code{info line} to map source lines to program
addresses (and vice versa), and the command @code{disassemble} to display
a range of addresses as machine instructions. When run under @sc{gnu} Emacs
-mode, the @code{info line} command now causes the arrow to point to the
-line specified. Also, @code{info line} prints addresses in symbolic form as
+mode, the @code{info line} command causes the arrow to point to the
+line specified. Also, @code{info line} prints addresses in symbolic form as
well as hex.
@table @code
the object code for the first line of function
@code{m4_changequote}:
+@c FIXME: I think this example should also show the addresses in
+@c symbolic form, as they usually would be displayed.
@smallexample
-(@value{GDBP}) info line m4_changecom
+(@value{GDBP}) info line m4_changequote
Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
@end smallexample
@end smallexample
@cindex @code{$_} and @code{info line}
+@kindex x@r{(examine), and} info line
After @code{info line}, the default address for the @code{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,
mnemonics or other syntax.
@table @code
-@kindex set assembly-language
+@kindex set disassembly-flavor
@cindex assembly instructions
@cindex instructions, assembly
@cindex machine instructions
@cindex listing machine instructions
-@item set assembly-language @var{instruction-set}
+@cindex Intel disassembly flavor
+@cindex AT&T disassembly flavor
+@item set disassembly-flavor @var{instruction-set}
Select the instruction set to use when disassembling the
program via the @code{disassemble} or @code{x/i} commands.
Currently this command is only defined for the Intel x86 family. You
-can set @var{instruction-set} to either @code{i386} or @code{i8086}.
-The default is @code{i386}.
+can set @var{instruction-set} to either @code{intel} or @code{att}.
+The default is @code{att}, the AT&T flavor used by default by Unix
+assemblers for x86-based targets.
@end table
-@node Data, Languages, Source, Top
+@node Data
@chapter Examining Data
@cindex printing data
Different Languages}).
@table @code
-@item print @var{exp}
-@itemx print /@var{f} @var{exp}
-@var{exp} is an expression (in the source language). By default the
-value of @var{exp} is printed in a format appropriate to its data type;
+@item print @var{expr}
+@itemx print /@var{f} @var{expr}
+@var{expr} is an expression (in the source language). By default the
+value of @var{expr} is printed in a format appropriate to its data type;
you can choose a different format by specifying @samp{/@var{f}}, where
-@var{f} is a letter specifying the format; @pxref{Output Formats,,Output
+@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
formats}.
@item print
@itemx print /@var{f}
-If you omit @var{exp}, @value{GDBN} displays the last value again (from the
+If you omit @var{expr}, @value{GDBN} displays the last value again (from the
@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to
conveniently inspect the same value in an alternative format.
@end table
specified format. @xref{Memory, ,Examining memory}.
If you are interested in information about types, or about how the
-fields of a struct or class are declared, use the @code{ptype @var{exp}}
-command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
+fields of a struct or a class are declared, use the @code{ptype @var{exp}}
+command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
Table}.
@menu
* Convenience Vars:: Convenience variables
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
+* Memory Region Attributes:: Memory region attributes
@end menu
-@node Expressions, Variables, Data, Data
+@node Expressions
@section Expressions
@cindex expressions
and string constants. It unfortunately does not include symbols defined
by preprocessor @code{#define} commands.
-@value{GDBN} now supports array constants in expressions input by
-the user. The syntax is @var{@{element, element@dots{}@}}. For example,
-you can now use the command @code{print @{1, 2, 3@}} to build up an array in
-memory that is malloc'd in the target program.
+@value{GDBN} supports array constants in expressions input by
+the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
+you can use the command @code{print @{1, 2, 3@}} to build up an array in
+memory that is @code{malloc}ed in the target program.
Because C is so widespread, most of the expressions shown in examples in
this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
normally supposed to reside at @var{addr}.
@end table
-@node Variables, Arrays, Expressions, Data
+@node Variables
@section Program variables
The most common kind of expression to use is the name of a variable
global (or file-static)
@end itemize
-@noindent or
+@noindent or
@itemize @bullet
@item
visible according to the scope rules of the
programming language from the point of execution in that frame
-@end itemize
+@end itemize
@noindent This means that in the function
you can specify a static variable in a particular function or file,
using the colon-colon notation:
-@cindex colon-colon
+@cindex colon-colon, context for variables/functions
@iftex
@c info cannot cope with a :: index entry, but why deprive hard copy readers?
-@kindex ::
+@cindex @code{::}, context for variables/functions
@end iftex
@example
@var{file}::@var{variable}
(@value{GDBP}) p 'f2.c'::x
@end example
-@cindex C++ scope resolution
+@cindex C@t{++} scope resolution
This use of @samp{::} is very rarely in conflict with the very similar
-use of the same notation in C++. @value{GDBN} also supports use of the C++
+use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
scope resolution operator in @value{GDBN} expressions.
@c FIXME: Um, so what happens in one of those rare cases where it's in
@c conflict?? --mew
To be sure of always seeing accurate values, turn off all optimization
when compiling.
-@node Arrays, Output Formats, Variables, Data
+@cindex ``No symbol "foo" in current context''
+Another possible effect of compiler optimizations is to optimize
+unused variables out of existence, or assign variables to registers (as
+opposed to memory addresses). Depending on the support for such cases
+offered by the debug info format used by the compiler, @value{GDBN}
+might not be able to display values for such local variables. If that
+happens, @value{GDBN} will print a message like this:
+
+@example
+No symbol "foo" in current context.
+@end example
+
+To solve such problems, either recompile without optimizations, or use a
+different debug info format, if the compiler supports several such
+formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler usually
+supports the @samp{-gstabs} option. @samp{-gstabs} produces debug info
+in a format that is superior to formats such as COFF. You may be able
+to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for
+debug info. See @ref{Debugging Options,,Options for Debugging Your
+Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
+information.
+
+
+@node Arrays
@section Artificial arrays
@cindex artificial array
-@kindex @@
+@kindex @@@r{, referencing memory as an 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
@end example
As a convenience, if you leave the array length out (as in
-@samp{(@var{type})[])@var{value}}) gdb calculates the size to fill
+@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
@example
(@value{GDBP}) p/x (short[])0x12345678
@dots{}
@end example
-@node Output Formats, Memory, Arrays, Data
+@node Output Formats
@section Output formats
@cindex formatted output
Print as integer in binary. The letter @samp{t} stands for ``two''.
@footnote{@samp{b} cannot be used because these format letters are also
used with the @code{x} command, where @samp{b} stands for ``byte'';
-@pxref{Memory,,Examining memory}.}
+see @ref{Memory,,Examining memory}.}
@item a
@cindex unknown address, locating
+@cindex locate address
Print as an address, both absolute in hexadecimal and as an offset from
the nearest preceding symbol. You can use this format used to discover
where (in what function) an unknown address is located:
$3 = 0x54320 <_initialize_vx+396>
@end example
+@noindent
+The command @code{info symbol 0x54320} yields similar results.
+@xref{Symbols, info symbol}.
+
@item c
Regard as an integer and print it as a character constant.
you can use the @code{print} command with just a format and no
expression. For example, @samp{p/x} reprints the last value in hex.
-@node Memory, Auto Display, Output Formats, Data
+@node Memory
@section Examining memory
You can use the command @code{x} (for ``examine'') to examine memory in
@cindex examining memory
@table @code
-@kindex x
+@kindex x @r{(examine memory)}
@item x/@var{nfu} @var{addr}
@itemx x @var{addr}
@itemx x
(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
-@pxref{Registers}) in hexadecimal (@samp{x}).
+@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}).
Since the letters indicating unit sizes are all distinct from the
letters specifying output formats, you do not have to remember whether
and @samp{i}, you might still want to use a count @var{n}; for example,
@samp{3i} specifies that you want to see three machine instructions,
including any operands. The command @code{disassemble} gives an
-alternative way of inspecting machine instructions; @pxref{Machine
+alternative way of inspecting machine instructions; see @ref{Machine
Code,,Source and machine code}.
All the defaults for the arguments to @code{x} are designed to make it
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.
-@node Auto Display, Print Settings, Memory, Data
+@node Auto Display
@section Automatic display
@cindex automatic display
@cindex display of expressions
@table @code
@kindex display
-@item display @var{exp}
-Add the expression @var{exp} to the list of expressions to display
+@item display @var{expr}
+Add the expression @var{expr} to the list of expressions to display
each time your program stops. @xref{Expressions, ,Expressions}.
@code{display} does not repeat if you press @key{RET} again after using it.
-@item display/@var{fmt} @var{exp}
+@item display/@var{fmt} @var{expr}
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
+count, add the expression @var{expr} to the auto-display list but
arrange to display it each time in the specified format @var{fmt}.
@xref{Output Formats,,Output formats}.
For example, @samp{display/i $pc} can be helpful, to see the machine
instruction about to be executed each time execution stops (@samp{$pc}
-is a common name for the program counter; @pxref{Registers}).
+is a common name for the program counter; @pxref{Registers, ,Registers}).
@table @code
@kindex delete display
automatically. The next time your program stops where @code{last_char}
is meaningful, you can enable the display expression once again.
-@node Print Settings, Value History, Auto Display, Data
+@node Print Settings
@section Print settings
@cindex format options
@item set print max-symbolic-offset @var{max-offset}
Tell @value{GDBN} to only display the symbolic form of an address if the
offset between the closest earlier symbol and the address is less than
-@var{max-offset}. The default is 0, which tells @value{GDBN}
+@var{max-offset}. The default is 0, which tells @value{GDBN}
to always print the symbolic form of an address if any symbol precedes it.
@kindex show print max-symbolic-offset
If @value{GDBN} is printing a large array, it stops printing after it has
printed the number of elements set by the @code{set print elements} command.
This limit also applies to the display of strings.
+When @value{GDBN} starts, this limit is set to 200.
Setting @var{number-of-elements} to zero means that the printing is unlimited.
@kindex show print elements
@kindex set print null-stop
@item set print null-stop
Cause @value{GDBN} to stop printing the characters of an array when the first
-@sc{NULL} is encountered. This is useful when large arrays actually
+@sc{null} is encountered. This is useful when large arrays actually
contain only short strings.
+The default is off.
@kindex set print pretty
@item set print pretty on
-Cause @value{GDBN} to print structures in an indented format with one member
+Cause @value{GDBN} to print structures in an indented format with one member
per line, like this:
@smallexample
@kindex set print union
@item set print union on
-Tell @value{GDBN} to print unions which are contained in structures. This
+Tell @value{GDBN} to print unions which are contained in structures. This
is the default setting.
@item set print union off
@smallexample
typedef enum @{Tree, Bug@} Species;
typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
-typedef enum @{Caterpillar, Cocoon, Butterfly@}
+typedef enum @{Caterpillar, Cocoon, Butterfly@}
Bug_forms;
struct thing @{
@need 1000
@noindent
-These settings are of interest when debugging C++ programs:
+These settings are of interest when debugging C@t{++} programs:
@table @code
@cindex demangling
@kindex set print demangle
@item set print demangle
@itemx set print demangle on
-Print C++ names in their source form rather than in the encoded
+Print C@t{++} names in their source form rather than in the encoded
(``mangled'') form passed to the assembler and linker for type-safe
-linkage. The default is @samp{on}.
+linkage. The default is on.
@kindex show print demangle
@item show print demangle
-Show whether C++ names are printed in mangled or demangled form.
+Show whether C@t{++} names are printed in mangled or demangled form.
@kindex set print asm-demangle
@item set print asm-demangle
@itemx set print asm-demangle on
-Print C++ names in their source form rather than their mangled form, even
+Print C@t{++} names in their source form rather than their mangled form, even
in assembler code printouts such as instruction disassemblies.
The default is off.
@kindex show print asm-demangle
@item show print asm-demangle
-Show whether C++ names in assembly listings are printed in mangled
+Show whether C@t{++} names in assembly listings are printed in mangled
or demangled form.
@kindex set demangle-style
-@cindex C++ symbol decoding style
-@cindex symbol decoding style, C++
+@cindex C@t{++} symbol decoding style
+@cindex symbol decoding style, C@t{++}
@item set demangle-style @var{style}
Choose among several encoding schemes used by different compilers to
-represent C++ names. The choices for @var{style} are currently:
+represent C@t{++} names. The choices for @var{style} are currently:
@table @code
@item auto
Allow @value{GDBN} to choose a decoding style by inspecting your program.
@item gnu
-Decode based on the @sc{gnu} C++ compiler (@code{g++}) encoding algorithm.
-@ifclear HPPA
+Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
This is the default.
-@end ifclear
@item hp
-Decode based on the HP ANSI C++ (@code{aCC}) encoding algorithm.
+Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
@item lucid
-Decode based on the Lucid C++ compiler (@code{lcc}) encoding algorithm.
+Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm.
@item arm
-Decode using the algorithm in the @cite{C++ Annotated Reference Manual}.
+Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}.
@strong{Warning:} this setting alone is not sufficient to allow
debugging @code{cfront}-generated executables. @value{GDBN} would
require further enhancement to permit that.
@kindex show demangle-style
@item show demangle-style
-Display the encoding style currently in use for decoding C++ symbols.
+Display the encoding style currently in use for decoding C@t{++} symbols.
@kindex set print object
@item set print object
@kindex set print static-members
@item set print static-members
@itemx set print static-members on
-Print static members when displaying a C++ object. The default is on.
+Print static members when displaying a C@t{++} object. The default is on.
@item set print static-members off
-Do not print static members when displaying a C++ object.
+Do not print static members when displaying a C@t{++} object.
@kindex show print static-members
@item show print static-members
-Show whether C++ static members are printed, or not.
+Show whether C@t{++} static members are printed, or not.
@c These don't work with HP ANSI C++ yet.
@kindex set print vtbl
@item set print vtbl
@itemx set print vtbl on
-Pretty print C++ virtual function tables. The default is off.
-@ifset HPPA
+Pretty print C@t{++} virtual function tables. The default is off.
(The @code{vtbl} commands do not work on programs compiled with the HP
-ANSI C++ compiler (@code{aCC}).)
-@end ifset
+ANSI C@t{++} compiler (@code{aCC}).)
@item set print vtbl off
-Do not pretty print C++ virtual function tables.
+Do not pretty print C@t{++} virtual function tables.
@kindex show print vtbl
@item show print vtbl
-Show whether C++ virtual function tables are pretty printed, or not.
+Show whether C@t{++} virtual function tables are pretty printed, or not.
@end table
-@node Value History, Convenience Vars, Print Settings, Data
+@node Value History
@section Value history
@cindex value history
-Values printed by the @code{print} command are saved in the @value{GDBN}
-@dfn{value history}. This allows you to refer to them in other expressions.
-Values are kept until the symbol table is re-read or discarded
-(for example with the @code{file} or @code{symbol-file} commands).
-When the symbol table changes, the value history is discarded,
-since the values may contain pointers back to the types defined in the
+Values printed by the @code{print} command are saved in the @value{GDBN}
+@dfn{value history}. This allows you to refer to them in other expressions.
+Values are kept until the symbol table is re-read or discarded
+(for example with the @code{file} or @code{symbol-file} commands).
+When the symbol table changes, the value history is discarded,
+since the values may contain pointers back to the types defined in the
symbol table.
@cindex @code{$}
Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
same effect as @samp{show values +}.
-@node Convenience Vars, Registers, Value History, Data
+@node Convenience Vars
@section Convenience variables
@cindex convenience variables
Convenience variables are prefixed with @samp{$}. Any name preceded by
@samp{$} can be used for a convenience variable, unless it is one of
-the predefined machine-specific register names (@pxref{Registers}).
+the predefined machine-specific register names (@pxref{Registers, ,Registers}).
(Value history references, in contrast, are @emph{numbers} preceded
by @samp{$}. @xref{Value History, ,Value history}.)
@kindex show convenience
@item show convenience
Print a list of convenience variables used so far, and their values.
-Abbreviated @code{show con}.
+Abbreviated @code{show conv}.
@end table
One of the ways to use a convenience variable is as a counter to be
print bar[$i++]->contents
@end example
-@noindent Repeat that command by typing @key{RET}.
+@noindent
+Repeat that command by typing @key{RET}.
Some convenience variables are created automatically by @value{GDBN} and given
values likely to be useful.
@table @code
-@kindex $_
+@vindex $_@r{, convenience variable}
@item $_
The variable @code{$_} is automatically set by the @code{x} command to
the last address examined (@pxref{Memory, ,Examining memory}). Other
except when set by the @code{x} command, in which case it is a pointer
to the type of @code{$__}.
-@kindex $__
+@vindex $__@r{, convenience variable}
@item $__
The variable @code{$__} is automatically set by the @code{x} command
to the value found in the last address examined. Its type is chosen
to match the format in which the data was printed.
@item $_exitcode
-@kindex $_exitcode
+@vindex $_exitcode@r{, convenience variable}
The variable @code{$_exitcode} is automatically set to the exit code when
the program being debugged terminates.
@end table
-@ifset HPPA
-If you refer to a function or variable name that begins with a dollar
-sign, @value{GDBN} searches for a user or system name first, before it
-searches for a convenience variable.
-@end ifset
+On HP-UX systems, if you refer to a function or variable name that
+begins with a dollar sign, @value{GDBN} searches for a user or system
+name first, before it searches for a convenience variable.
-@node Registers, Floating Point Hardware, Convenience Vars, Data
+@node Registers
@section Registers
@cindex registers
@item info registers @var{regname} @dots{}
Print the @dfn{relativized} value of each specified register @var{regname}.
-As discussed in detail below, register values are normally relative to
-the selected stack frame. @var{regname} may be any register name valid on
+As discussed in detail below, register values are normally relative to
+the selected stack frame. @var{regname} may be any register name valid on
the machine you are using, with or without the initial @samp{$}.
@end table
stack frame is selected; setting @code{$sp} is not allowed when other
stack frames are selected. To pop entire frames off the stack,
regardless of machine architecture, use @code{return};
-@pxref{Returning, ,Returning from a function}.} with
+see @ref{Returning, ,Returning from a function}.} with
@example
set $sp += 4
so long as there is no conflict. The @code{info registers} command
shows the canonical names. 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}.
+can also refer to it as @code{$ps}; and on x86-based machines @code{$ps}
+is an alias for the @sc{eflags} register.
@value{GDBN} always considers the contents of an ordinary register as an
integer when the register is examined in this way. Some machines have
sees. For example, the registers of the 68881 floating point
coprocessor are always saved in ``extended'' (raw) format, but all C
programs expect to work with ``double'' (virtual) format. In such
-cases, @value{GDBN} normally works with the virtual format only (the format
+cases, @value{GDBN} normally works with the virtual format only (the format
that makes sense for your program), but the @code{info registers} command
prints the data in both formats.
@value{GDBN} is unable to locate the saved registers, the selected stack
frame makes no difference.
-@table @code
-@kindex set rstack_high_address
-@cindex AMD 29K register stack
-@cindex register stack, AMD29K
-@item set rstack_high_address @var{address}
-On AMD 29000 family processors, registers are saved in a separate
-``register stack''. There is no way for @value{GDBN} to determine the extent
-of this stack. Normally, @value{GDBN} just assumes that the stack is ``large
-enough''. This may result in @value{GDBN} referencing memory locations that
-do not exist. If necessary, you can get around this problem by
-specifying the ending address of the register stack with the @code{set
-rstack_high_address} command. The argument should be an address, which
-you probably want to precede with @samp{0x} to specify in
-hexadecimal.
-
-@kindex show rstack_high_address
-@item show rstack_high_address
-Display the current limit of the register stack, on AMD 29000 family
-processors.
-@end table
-
-@node Floating Point Hardware, , Registers, Data
+@node Floating Point Hardware
@section Floating point hardware
@cindex floating point
the ARM and x86 machines.
@end table
-@node Languages, Symbols, Data, Top
-@chapter Using @value{GDBN} with Different Languages
-@cindex languages
+@node Memory Region Attributes
+@section Memory Region Attributes
+@cindex memory region attributes
-Although programming languages generally have common aspects, they are
-rarely expressed in the same manner. For instance, in ANSI C,
-dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
-Modula-2, it is accomplished by @code{p^}. Values can also be
-represented (and displayed) differently. Hex numbers in C appear as
-@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
+@dfn{Memory region attributes} allow you to describe special handling
+required by regions of your target's memory. @value{GDBN} uses attributes
+to determine whether to allow certain types of memory accesses; whether to
+use specific width accesses; and whether to cache target memory.
-@cindex working language
-Language-specific information is built into @value{GDBN} for some languages,
-allowing you to express operations like the above in your program's
-native language, and allowing @value{GDBN} to output values in a manner
-consistent with the syntax of your program's native language. The
-language you use to build expressions is called the @dfn{working
-language}.
+Defined memory regions can be individually enabled and disabled. When a
+memory region is disabled, @value{GDBN} uses the default attributes when
+accessing memory in that region. Similarly, if no memory regions have
+been defined, @value{GDBN} uses the default attributes when accessing
+all memory.
-@menu
-* Setting:: Switching between source languages
-* Show:: Displaying the language
-* Checks:: Type and range checks
-* Support:: Supported languages
-@end menu
+When a memory region is defined, it is given a number to identify it;
+to enable, disable, or remove a memory region, you specify that number.
-@node Setting, Show, Languages, Languages
-@section Switching between source languages
+@table @code
+@kindex mem
+@item mem @var{address1} @var{address1} @var{attributes}@dots{}
+Define memory region bounded by @var{address1} and @var{address2}
+with attributes @var{attributes}@dots{}.
+
+@kindex delete mem
+@item delete mem @var{nums}@dots{}
+Remove memory region numbers @var{nums}.
+
+@kindex disable mem
+@item disable mem @var{nums}@dots{}
+Disable memory region numbers @var{nums}.
+A disabled memory region is not forgotten.
+It may be enabled again later.
+
+@kindex enable mem
+@item enable mem @var{nums}@dots{}
+Enable memory region numbers @var{nums}.
+
+@kindex info mem
+@item info mem
+Print a table of all defined memory regions, with the following columns
+for each region.
-There are two ways to control the working language---either have @value{GDBN}
-set it automatically, or select it manually yourself. You can use the
-@code{set language} command for either purpose. On startup, @value{GDBN}
-defaults to setting the language automatically. The working language is
-used to determine how expressions you type are interpreted, how values
-are printed, etc.
+@table @emph
+@item Memory Region Number
+@item Enabled or Disabled.
+Enabled memory regions are marked with @samp{y}.
+Disabled memory regions are marked with @samp{n}.
-In addition to the working language, every source file that
-@value{GDBN} knows about has its own working language. For some object
-file formats, the compiler might indicate which language a particular
-source file is in. However, most of the time @value{GDBN} infers the
-language from the name of the file. The language of a source file
-controls whether C++ names are demangled---this way @code{backtrace} can
-show each frame appropriately for its own language. There is no way to
-set the language of a source file from within @value{GDBN}.
+@item Lo Address
+The address defining the inclusive lower bound of the memory region.
-This is most commonly a problem when you use a program, such
-as @code{cfront} or @code{f2c}, that generates C but is written in
-another language. In that case, make the
-program use @code{#line} directives in its C output; that way
-@value{GDBN} will know the correct language of the source code of the original
-program, and will display that source code, not the generated C code.
+@item Hi Address
+The address defining the exclusive upper bound of the memory region.
-@menu
-* Filenames:: Filename extensions and languages.
-* Manually:: Setting the working language manually
-* Automatically:: Having @value{GDBN} infer the source language
-@end menu
+@item Attributes
+The list of attributes set for this memory region.
+@end table
+@end table
-@node Filenames, Manually, Setting, Setting
-@subsection List of filename extensions and languages
-If a source file name ends in one of the following extensions, then
-@value{GDBN} infers that its language is the one indicated.
+@subsection Attributes
-@table @file
+@subsubsection Memory Access Mode
+The access mode attributes set whether @value{GDBN} may make read or
+write accesses to a memory region.
-@item .c
-C source file
+While these attributes prevent @value{GDBN} from performing invalid
+memory accesses, they do nothing to prevent the target system, I/O DMA,
+etc. from accessing memory.
-@item .C
-@itemx .cc
-@itemx .cp
-@itemx .cpp
-@itemx .cxx
-@itemx .c++
-C++ source file
+@table @code
+@item ro
+Memory is read only.
+@item wo
+Memory is write only.
+@item rw
+Memory is read/write (default).
+@end table
-@item .f
-@itemx .F
-Fortran source file
+@subsubsection Memory Access Size
+The acccess size attributes tells @value{GDBN} to use specific sized
+accesses in the memory region. Often memory mapped device registers
+require specific sized accesses. If no access size attribute is
+specified, @value{GDBN} may use accesses of any size.
-@ifclear HPPA
-@item .ch
-@itemx .c186
-@itemx .c286
-CHILL source file.
-@end ifclear
+@table @code
+@item 8
+Use 8 bit memory accesses.
+@item 16
+Use 16 bit memory accesses.
+@item 32
+Use 32 bit memory accesses.
+@item 64
+Use 64 bit memory accesses.
+@end table
-@item .mod
-Modula-2 source file
+@c @subsubsection Hardware/Software Breakpoints
+@c The hardware/software breakpoint attributes set whether @value{GDBN}
+@c will use hardware or software breakpoints for the internal breakpoints
+@c used by the step, next, finish, until, etc. commands.
+@c
+@c @table @code
+@c @item hwbreak
+@c Always use hardware breakpoints
+@c @item swbreak (default)
+@c @end table
+
+@subsubsection Data Cache
+The data cache attributes set whether @value{GDBN} will cache target
+memory. While this generally improves performance by reducing debug
+protocol overhead, it can lead to incorrect results because @value{GDBN}
+does not know about volatile variables or memory mapped device
+registers.
-@item .s
-@itemx .S
-Assembler source file. This actually behaves almost like C, but
-@value{GDBN} does not skip over function prologues when stepping.
+@table @code
+@item cache
+Enable @value{GDBN} to cache target memory.
+@item nocache (default)
+Disable @value{GDBN} from caching target memory.
@end table
-In addition, you may set the language associated with a filename
-extension. @xref{Show, , Displaying the language}.
+@c @subsubsection Memory Write Verification
+@c The memory write verification attributes set whether @value{GDBN}
+@c will re-reads data after each write to verify the write was successful.
+@c
+@c @table @code
+@c @item verify
+@c @item noverify (default)
+@c @end table
+
+@node Tracepoints
+@chapter Tracepoints
+@c This chapter is based on the documentation written by Michael
+@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni.
+
+@cindex tracepoints
+In some applications, it is not feasible for the debugger to interrupt
+the program's execution long enough for the developer to learn
+anything helpful about its behavior. If the program's correctness
+depends on its real-time behavior, delays introduced by a debugger
+might cause the program to change its behavior drastically, or perhaps
+fail, even when the code itself is correct. It is useful to be able
+to observe the program's behavior without interrupting it.
+
+Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can
+specify locations in the program, called @dfn{tracepoints}, and
+arbitrary expressions to evaluate when those tracepoints are reached.
+Later, using the @code{tfind} command, you can examine the values
+those expressions had when the program hit the tracepoints. The
+expressions may also denote objects in memory---structures or arrays,
+for example---whose values @value{GDBN} should record; while visiting
+a particular tracepoint, you may inspect those objects as if they were
+in memory at that moment. However, because @value{GDBN} records these
+values without interacting with you, it can do so quickly and
+unobtrusively, hopefully not disturbing the program's behavior.
+
+The tracepoint facility is currently available only for remote
+targets. @xref{Targets}. In addition, your remote target must know how
+to collect trace data. This functionality is implemented in the remote
+stub; however, none of the stubs distributed with @value{GDBN} support
+tracepoints as of this writing.
+
+This chapter describes the tracepoint commands and features.
-@node Manually, Automatically, Filenames, Setting
-@subsection Setting the working language
+@menu
+* Set Tracepoints::
+* Analyze Collected Data::
+* Tracepoint Variables::
+@end menu
-If you allow @value{GDBN} to set the language automatically,
-expressions are interpreted the same way in your debugging session and
-your program.
+@node Set Tracepoints
+@section Commands to Set Tracepoints
-@kindex set language
-If you wish, you may set the language manually. To do this, issue the
-command @samp{set language @var{lang}}, where @var{lang} is the name of
-a language, such as
-@code{c} or @code{modula-2}.
-For a list of the supported languages, type @samp{set language}.
+Before running such a @dfn{trace experiment}, an arbitrary number of
+tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a
+tracepoint has a number assigned to it by @value{GDBN}. Like with
+breakpoints, tracepoint numbers are successive integers starting from
+one. Many of the commands associated with tracepoints take the
+tracepoint number as their argument, to identify which tracepoint to
+work on.
-Setting the language manually prevents @value{GDBN} from updating the working
-language automatically. This can lead to confusion if you try
-to debug a program when the working language is not the same as the
-source language, when an expression is acceptable to both
-languages---but means different things. For instance, if the current
-source file were written in C, and @value{GDBN} was parsing Modula-2, a
-command such as:
+For each tracepoint, you can specify, in advance, some arbitrary set
+of data that you want the target to collect in the trace buffer when
+it hits that tracepoint. The collected data can include registers,
+local variables, or global data. Later, you can use @value{GDBN}
+commands to examine the values these data had at the time the
+tracepoint was hit.
-@example
-print a = b + c
-@end example
+This section describes commands to set tracepoints and associated
+conditions and actions.
-@noindent
-might not have the effect you intended. In C, this means to add
-@code{b} and @code{c} and place the result in @code{a}. The result
-printed would be the value of @code{a}. In Modula-2, this means to compare
-@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
+@menu
+* Create and Delete Tracepoints::
+* Enable and Disable Tracepoints::
+* Tracepoint Passcounts::
+* Tracepoint Actions::
+* Listing Tracepoints::
+* Starting and Stopping Trace Experiment::
+@end menu
-@node Automatically, , Manually, Setting
-@subsection Having @value{GDBN} infer the source language
+@node Create and Delete Tracepoints
+@subsection Create and Delete Tracepoints
-To have @value{GDBN} set the working language automatically, use
-@samp{set language local} or @samp{set language auto}. @value{GDBN}
-then infers the working language. That is, when your program stops in a
-frame (usually by encountering a breakpoint), @value{GDBN} sets the
-working language to the language recorded for the function in that
-frame. If the language for a frame is unknown (that is, if the function
-or block corresponding to the frame was defined in a source file that
-does not have a recognized extension), the current working language is
-not changed, and @value{GDBN} issues a warning.
+@table @code
+@cindex set tracepoint
+@kindex trace
+@item trace
+The @code{trace} command is very similar to the @code{break} command.
+Its argument can be a source line, a function name, or an address in
+the target program. @xref{Set Breaks}. The @code{trace} command
+defines a tracepoint, which is a point in the target program where the
+debugger will briefly stop, collect some data, and then allow the
+program to continue. Setting a tracepoint or changing its commands
+doesn't take effect until the next @code{tstart} command; thus, you
+cannot change the tracepoint attributes once a trace experiment is
+running.
+
+Here are some examples of using the @code{trace} command:
-This may not seem necessary for most programs, which are written
-entirely in one source language. However, program modules and libraries
-written in one source language can be used by a main program written in
-a different source language. Using @samp{set language auto} in this
-case frees you from having to set the working language manually.
+@smallexample
+(@value{GDBP}) @b{trace foo.c:121} // a source file and line number
-@node Show, Checks, Setting, Languages
-@section Displaying the language
+(@value{GDBP}) @b{trace +2} // 2 lines forward
-The following commands help you find out which language is the
-working language, and also what language source files were written in.
+(@value{GDBP}) @b{trace my_function} // first source line of function
-@kindex show language
-@kindex info frame
-@kindex info source
-@table @code
-@item show language
-Display the current working language. This is the
-language you can use with commands such as @code{print} to
-build and compute expressions that may involve variables in your program.
+(@value{GDBP}) @b{trace *my_function} // EXACT start address of function
-@item info frame
-Display the source language for this frame. This language becomes the
-working language if you use an identifier from this frame.
-@xref{Frame Info, ,Information about a frame}, to identify the other
-information listed here.
+(@value{GDBP}) @b{trace *0x2117c4} // an address
+@end smallexample
-@item info source
-Display the source language of this source file.
-@xref{Symbols, ,Examining the Symbol Table}, to identify the other
-information listed here.
-@end table
+@noindent
+You can abbreviate @code{trace} as @code{tr}.
-In unusual circumstances, you may have source files with extensions
-not in the standard list. You can then set the extension associated
-with a language explicitly:
+@vindex $tpnum
+@cindex last tracepoint number
+@cindex recent tracepoint number
+@cindex tracepoint number
+The convenience variable @code{$tpnum} records the tracepoint number
+of the most recently set tracepoint.
-@kindex set extension-language
-@kindex info extensions
-@table @code
-@item set extension-language @var{.ext} @var{language}
-Set source files with extension @var{.ext} to be assumed to be in
-the source language @var{language}.
+@kindex delete tracepoint
+@cindex tracepoint deletion
+@item delete tracepoint @r{[}@var{num}@r{]}
+Permanently delete one or more tracepoints. With no argument, the
+default is to delete all tracepoints.
-@item info extensions
-List all the filename extensions and the associated languages.
-@end table
+Examples:
-@node Checks, Support, Show, Languages
-@section Type and range checking
+@smallexample
+(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints
-@quotation
-@emph{Warning:} In this release, the @value{GDBN} commands for type and range
-checking are included, but they do not yet have any effect. This
-section documents the intended facilities.
-@end quotation
-@c FIXME remove warning when type/range code added
+(@value{GDBP}) @b{delete trace} // remove all tracepoints
+@end smallexample
-Some languages are designed to guard you against making seemingly common
-errors through a series of compile- and run-time checks. These include
-checking the type of arguments to functions and operators, and making
-sure mathematical overflows are caught at run time. Checks such as
-these help to ensure a program's correctness once it has been compiled
-by eliminating type mismatches, and providing active checks for range
-errors when your program is running.
+@noindent
+You can abbreviate this command as @code{del tr}.
+@end table
-@value{GDBN} can check for conditions like the above if you wish.
-Although @value{GDBN} does not check the statements in your program, it
-can check expressions entered directly into @value{GDBN} for evaluation via
-the @code{print} command, for example. As with the working language,
-@value{GDBN} can also decide whether or not to check automatically based on
-your program's source language. @xref{Support, ,Supported languages},
-for the default settings of supported languages.
+@node Enable and Disable Tracepoints
+@subsection Enable and Disable Tracepoints
-@menu
-* Type Checking:: An overview of type checking
-* Range Checking:: An overview of range checking
-@end menu
+@table @code
+@kindex disable tracepoint
+@item disable tracepoint @r{[}@var{num}@r{]}
+Disable tracepoint @var{num}, or all tracepoints if no argument
+@var{num} is given. A disabled tracepoint will have no effect during
+the next trace experiment, but it is not forgotten. You can re-enable
+a disabled tracepoint using the @code{enable tracepoint} command.
+
+@kindex enable tracepoint
+@item enable tracepoint @r{[}@var{num}@r{]}
+Enable tracepoint @var{num}, or all tracepoints. The enabled
+tracepoints will become effective the next time a trace experiment is
+run.
+@end table
-@cindex type checking
-@cindex checks, type
-@node Type Checking, Range Checking, Checks, Checks
-@subsection An overview of type checking
+@node Tracepoint Passcounts
+@subsection Tracepoint Passcounts
-Some languages, such as Modula-2, are strongly typed, meaning that the
-arguments to operators and functions have to be of the correct type,
-otherwise an error occurs. These checks prevent type mismatch
-errors from ever causing any run-time problems. For example,
+@table @code
+@kindex passcount
+@cindex tracepoint pass count
+@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]}
+Set the @dfn{passcount} of a tracepoint. The passcount is a way to
+automatically stop a trace experiment. If a tracepoint's passcount is
+@var{n}, then the trace experiment will be automatically stopped on
+the @var{n}'th time that tracepoint is hit. If the tracepoint number
+@var{num} is not specified, the @code{passcount} command sets the
+passcount of the most recently defined tracepoint. If no passcount is
+given, the trace experiment will run until stopped explicitly by the
+user.
+
+Examples:
@smallexample
-1 + 2 @result{} 3
-@exdent but
-@error{} 1 + 2.3
+(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2}
+
+(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.}
+(@value{GDBP}) @b{trace foo}
+(@value{GDBP}) @b{pass 3}
+(@value{GDBP}) @b{trace bar}
+(@value{GDBP}) @b{pass 2}
+(@value{GDBP}) @b{trace baz}
+(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has}
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times}
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.}
@end smallexample
+@end table
-The second example fails because the @code{CARDINAL} 1 is not
-type-compatible with the @code{REAL} 2.3.
+@node Tracepoint Actions
+@subsection Tracepoint Action Lists
-For the expressions you use in @value{GDBN} commands, you can tell the
-@value{GDBN} type checker to skip checking;
-to treat any mismatches as errors and abandon the expression;
-or to only issue warnings when type mismatches occur,
-but evaluate the expression anyway. When you choose the last of
-these, @value{GDBN} evaluates expressions like the second example above, but
-also issues a warning.
+@table @code
+@kindex actions
+@cindex tracepoint actions
+@item actions @r{[}@var{num}@r{]}
+This command will prompt for a list of actions to be taken when the
+tracepoint is hit. If the tracepoint number @var{num} is not
+specified, this command sets the actions for the one that was most
+recently defined (so that you can define a tracepoint and then say
+@code{actions} without bothering about its number). You specify the
+actions themselves on the following lines, one action at a time, and
+terminate the actions list with a line containing just @code{end}. So
+far, the only defined actions are @code{collect} and
+@code{while-stepping}.
+
+@cindex remove actions from a tracepoint
+To remove all actions from a tracepoint, type @samp{actions @var{num}}
+and follow it immediately with @samp{end}.
-Even if you turn type checking off, there may be other reasons
-related to type that prevent @value{GDBN} from evaluating an expression.
-For instance, @value{GDBN} does not know how to add an @code{int} and
-a @code{struct foo}. These particular type errors have nothing to do
-with the language in use, and usually arise from expressions, such as
-the one described above, which make little sense to evaluate anyway.
+@smallexample
+(@value{GDBP}) @b{collect @var{data}} // collect some data
-Each language defines to what degree it is strict about type. For
-instance, both Modula-2 and C require the arguments to arithmetical
-operators to be numbers. In C, enumerated types and pointers can be
-represented as numbers, so that they are valid arguments to mathematical
-operators. @xref{Support, ,Supported languages}, for further
-details on specific languages.
+(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
-@value{GDBN} provides some additional commands for controlling the type checker:
+(@value{GDBP}) @b{end} // signals the end of actions.
+@end smallexample
-@kindex set check
-@kindex set check type
-@kindex show check type
-@table @code
-@item set check type auto
-Set type checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
-each language.
+In the following example, the action list begins with @code{collect}
+commands indicating the things to be collected when the tracepoint is
+hit. Then, in order to single-step and collect additional data
+following the tracepoint, a @code{while-stepping} command is used,
+followed by the list of things to be collected while stepping. The
+@code{while-stepping} command is terminated by its own separate
+@code{end} command. Lastly, the action list is terminated by an
+@code{end} command.
-@item set check type on
-@itemx set check type off
-Set type checking on or off, overriding the default setting for the
-current working language. Issue a warning if the setting does not
-match the language default. If any type mismatches occur in
-evaluating an expression while typechecking is on, @value{GDBN} prints a
-message and aborts evaluation of the expression.
+@smallexample
+(@value{GDBP}) @b{trace foo}
+(@value{GDBP}) @b{actions}
+Enter actions for tracepoint 1, one per line:
+> collect bar,baz
+> collect $regs
+> while-stepping 12
+ > collect $fp, $sp
+ > end
+end
+@end smallexample
-@item set check type warn
-Cause the type checker to issue warnings, but to always attempt to
-evaluate the expression. Evaluating the expression may still
-be impossible for other reasons. For example, @value{GDBN} cannot add
-numbers and structures.
+@kindex collect @r{(tracepoints)}
+@item collect @var{expr1}, @var{expr2}, @dots{}
+Collect values of the given expressions when the tracepoint is hit.
+This command accepts a comma-separated list of any valid expressions.
+In addition to global, static, or local variables, the following
+special arguments are supported:
-@item show type
-Show the current setting of the type checker, and whether or not @value{GDBN}
-is setting it automatically.
-@end table
+@table @code
+@item $regs
+collect all registers
-@cindex range checking
-@cindex checks, range
-@node Range Checking, , Type Checking, Checks
-@subsection An overview of range checking
+@item $args
+collect all function arguments
-In some languages (such as Modula-2), it is an error to exceed the
-bounds of a type; this is enforced with run-time checks. Such range
-checking is meant to ensure program correctness by making sure
-computations do not overflow, or indices on an array element access do
-not exceed the bounds of the array.
+@item $locals
+collect all local variables.
+@end table
-For expressions you use in @value{GDBN} commands, you can tell
-@value{GDBN} to treat range errors in one of three ways: ignore them,
-always treat them as errors and abandon the expression, or issue
-warnings but evaluate the expression anyway.
+You can give several consecutive @code{collect} commands, each one
+with a single argument, or one @code{collect} command with several
+arguments separated by commas: the effect is the same.
-A range error can result from numerical overflow, from exceeding an
-array index bound, or when you type a constant that is not a member
-of any type. Some languages, however, do not treat overflows as an
-error. In many implementations of C, mathematical overflow causes the
-result to ``wrap around'' to lower values---for example, if @var{m} is
-the largest integer value, and @var{s} is the smallest, then
+The command @code{info scope} (@pxref{Symbols, info scope}) is
+particularly useful for figuring out what data to collect.
-@example
-@var{m} + 1 @result{} @var{s}
-@end example
+@kindex while-stepping @r{(tracepoints)}
+@item while-stepping @var{n}
+Perform @var{n} single-step traces after the tracepoint, collecting
+new data at each step. The @code{while-stepping} command is
+followed by the list of what to collect while stepping (followed by
+its own @code{end} command):
-This, too, is specific to individual languages, and in some cases
-specific to individual compilers or machines. @xref{Support, ,
-Supported languages}, for further details on specific languages.
+@smallexample
+> while-stepping 12
+ > collect $regs, myglobal
+ > end
+>
+@end smallexample
-@value{GDBN} provides some additional commands for controlling the range checker:
+@noindent
+You may abbreviate @code{while-stepping} as @code{ws} or
+@code{stepping}.
+@end table
+
+@node Listing Tracepoints
+@subsection Listing Tracepoints
-@kindex set check
-@kindex set check range
-@kindex show check range
@table @code
-@item set check range auto
-Set range checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
-each language.
+@kindex info tracepoints
+@cindex information about tracepoints
+@item info tracepoints @r{[}@var{num}@r{]}
+Display information about the tracepoint @var{num}. If you don't specify
+a tracepoint number, displays information about all the tracepoints
+defined so far. For each tracepoint, the following information is
+shown:
-@item set check range on
-@itemx set check range off
-Set range checking on or off, overriding the default setting for the
-current working language. A warning is issued if the setting does not
-match the language default. If a range error occurs, then a message
-is printed and evaluation of the expression is aborted.
+@itemize @bullet
+@item
+its number
+@item
+whether it is enabled or disabled
+@item
+its address
+@item
+its passcount as given by the @code{passcount @var{n}} command
+@item
+its step count as given by the @code{while-stepping @var{n}} command
+@item
+where in the source files is the tracepoint set
+@item
+its action list as given by the @code{actions} command
+@end itemize
-@item set check range warn
-Output messages when the @value{GDBN} range checker detects a range error,
-but attempt to evaluate the expression anyway. Evaluating the
-expression may still be impossible for other reasons, such as accessing
-memory that the process does not own (a typical example from many Unix
-systems).
+@smallexample
+(@value{GDBP}) @b{info trace}
+Num Enb Address PassC StepC What
+1 y 0x002117c4 0 0 <gdb_asm>
+2 y 0x0020dc64 0 0 in g_test at g_test.c:1375
+3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41
+(@value{GDBP})
+@end smallexample
-@item show range
-Show the current setting of the range checker, and whether or not it is
-being set automatically by @value{GDBN}.
+@noindent
+This command can be abbreviated @code{info tp}.
@end table
-@node Support, , Checks, Languages
-@section Supported languages
+@node Starting and Stopping Trace Experiment
+@subsection Starting and Stopping Trace Experiment
-@value{GDBN} supports C, C++, Fortran, Chill, assembly, and Modula-2.
-Some @value{GDBN} features may be used in expressions regardless of the
-language you use: the @value{GDBN} @code{@@} and @code{::} operators,
-and the @samp{@{type@}addr} construct (@pxref{Expressions,
-,Expressions}) can be used with the constructs of any supported
-language.
+@table @code
+@kindex tstart
+@cindex start a new trace experiment
+@cindex collected data discarded
+@item tstart
+This command takes no arguments. It starts the trace experiment, and
+begins collecting data. This has the side effect of discarding all
+the data collected in the trace buffer during the previous trace
+experiment.
+
+@kindex tstop
+@cindex stop a running trace experiment
+@item tstop
+This command takes no arguments. It ends the trace experiment, and
+stops collecting data.
+
+@strong{Note:} a trace experiment and data collection may stop
+automatically if any tracepoint's passcount is reached
+(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
+
+@kindex tstatus
+@cindex status of trace data collection
+@cindex trace experiment, status of
+@item tstatus
+This command displays the status of the current trace data
+collection.
+@end table
+
+Here is an example of the commands we described so far:
+
+@smallexample
+(@value{GDBP}) @b{trace gdb_c_test}
+(@value{GDBP}) @b{actions}
+Enter actions for tracepoint #1, one per line.
+> collect $regs,$locals,$args
+> while-stepping 11
+ > collect $regs
+ > end
+> end
+(@value{GDBP}) @b{tstart}
+ [time passes @dots{}]
+(@value{GDBP}) @b{tstop}
+@end smallexample
-The following sections detail to what degree each source language is
-supported by @value{GDBN}. These sections are not meant to be language
-tutorials or references, but serve only as a reference guide to what the
-@value{GDBN} expression parser accepts, and what input and output
-formats should look like for different languages. There are many good
-books written on each of these languages; please look to these for a
-language reference or tutorial.
+
+@node Analyze Collected Data
+@section Using the collected data
+
+After the tracepoint experiment ends, you use @value{GDBN} commands
+for examining the trace data. The basic idea is that each tracepoint
+collects a trace @dfn{snapshot} every time it is hit and another
+snapshot every time it single-steps. All these snapshots are
+consecutively numbered from zero and go into a buffer, and you can
+examine them later. The way you examine them is to @dfn{focus} on a
+specific trace snapshot. When the remote stub is focused on a trace
+snapshot, it will respond to all @value{GDBN} requests for memory and
+registers by reading from the buffer which belongs to that snapshot,
+rather than from @emph{real} memory or registers of the program being
+debugged. This means that @strong{all} @value{GDBN} commands
+(@code{print}, @code{info registers}, @code{backtrace}, etc.) will
+behave as if we were currently debugging the program state as it was
+when the tracepoint occurred. Any requests for data that are not in
+the buffer will fail.
@menu
-* C:: C and C++
-* Modula-2:: Modula-2
+* tfind:: How to select a trace snapshot
+* tdump:: How to display all data for a snapshot
+* save-tracepoints:: How to save tracepoints for a future run
@end menu
-@node C, Modula-2, , Support
-@subsection C and C++
+@node tfind
+@subsection @code{tfind @var{n}}
-@cindex C and C++
-@cindex expressions in C or C++
+@kindex tfind
+@cindex select trace snapshot
+@cindex find trace snapshot
+The basic command for selecting a trace snapshot from the buffer is
+@code{tfind @var{n}}, which finds trace snapshot number @var{n},
+counting from zero. If no argument @var{n} is given, the next
+snapshot is selected.
-Since C and C++ are so closely related, many features of @value{GDBN} apply
-to both languages. Whenever this is the case, we discuss those languages
-together.
-
-@ifclear HPPA
-@cindex C++
-@kindex g++
-@cindex @sc{gnu} C++
-The C++ debugging facilities are jointly implemented by the C++
-compiler and @value{GDBN}. Therefore, to debug your C++ code
-effectively, you must compile your C++ programs with a supported
-C++ compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C++
-compiler (@code{aCC}).
-
-For best results when using @sc{gnu} C++, use the stabs debugging
-format. You can select that format explicitly with the @code{g++}
-command-line options @samp{-gstabs} or @samp{-gstabs+}. See
-@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
-CC, gcc.info, Using @sc{gnu} CC}, for more information.
-@end ifclear
-@ifset HPPA
-@cindex C++
-@kindex g++
-@cindex @sc{gnu} C++
-You can use @value{GDBN} to debug C programs compiled with either the HP
-C compiler (@code{cc}) or the GNU C compiler (@code{gcc}), and to debug
-programs compiled with either the HP ANSI C++ compiler (@code{aCC}) or
-the @sc{gnu} C++ compiler (@code{g++}).
-
-If you compile with the @sc{gnu} C++ compiler, use the stabs debugging
-format for best results when debugging. You can select that format
-explicitly with the @code{g++} command-line options @samp{-gstabs} or
-@samp{-gstabs+}. See @ref{Debugging Options,,Options for Debugging Your
-Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
-information.
-@end ifset
-
-@menu
-* C Operators:: C and C++ operators
-* C Constants:: C and C++ constants
-* C plus plus expressions:: C++ expressions
-* C Defaults:: Default settings for C and C++
-* C Checks:: C and C++ type and range checks
-* Debugging C:: @value{GDBN} and C
-* Debugging C plus plus:: @value{GDBN} features for C++
-@end menu
-
-@node C Operators, C Constants, , C
-@subsubsection C and C++ operators
+Here are the various forms of using the @code{tfind} command.
-@cindex C and C++ operators
-
-Operators must be defined on values of specific types. For instance,
-@code{+} is defined on numbers, but not on structures. Operators are
-often defined on groups of types.
-
-For the purposes of C and C++, the following definitions hold:
+@table @code
+@item tfind start
+Find the first snapshot in the buffer. This is a synonym for
+@code{tfind 0} (since 0 is the number of the first snapshot).
-@itemize @bullet
-@item
-@ifclear HPPA
-@emph{Integral types} include @code{int} with any of its storage-class
-specifiers; @code{char}; and @code{enum}.
-@end ifclear
-@ifset HPPA
-@emph{Integral types} include @code{int} with any of its storage-class
-specifiers; @code{char}; @code{enum}; and, for C++, @code{bool}.
-@end ifset
+@item tfind none
+Stop debugging trace snapshots, resume @emph{live} debugging.
-@item
-@emph{Floating-point types} include @code{float} and @code{double}.
+@item tfind end
+Same as @samp{tfind none}.
-@item
-@emph{Pointer types} include all types defined as @code{(@var{type}
-*)}.
+@item tfind
+No argument means find the next trace snapshot.
-@item
-@emph{Scalar types} include all of the above.
-@end itemize
+@item tfind -
+Find the previous trace snapshot before the current one. This permits
+retracing earlier steps.
-@noindent
-The following operators are supported. They are listed here
-in order of increasing precedence:
+@item tfind tracepoint @var{num}
+Find the next snapshot associated with tracepoint @var{num}. Search
+proceeds forward from the last examined trace snapshot. If no
+argument @var{num} is given, it means find the next snapshot collected
+for the same tracepoint as the current snapshot.
-@table @code
-@item ,
-The comma or sequencing operator. Expressions in a comma-separated list
-are evaluated from left to right, with the result of the entire
-expression being the last expression evaluated.
+@item tfind pc @var{addr}
+Find the next snapshot associated with the value @var{addr} of the
+program counter. Search proceeds forward from the last examined trace
+snapshot. If no argument @var{addr} is given, it means find the next
+snapshot with the same value of PC as the current snapshot.
-@item =
-Assignment. The value of an assignment expression is the value
-assigned. Defined on scalar types.
+@item tfind outside @var{addr1}, @var{addr2}
+Find the next snapshot whose PC is outside the given range of
+addresses.
-@item @var{op}=
-Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
-and translated to @w{@code{@var{a} = @var{a op b}}}.
-@w{@code{@var{op}=}} and @code{=} have the same precendence.
-@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
-@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
+@item tfind range @var{addr1}, @var{addr2}
+Find the next snapshot whose PC is between @var{addr1} and
+@var{addr2}. @c FIXME: Is the range inclusive or exclusive?
+
+@item tfind line @r{[}@var{file}:@r{]}@var{n}
+Find the next snapshot associated with the source line @var{n}. If
+the optional argument @var{file} is given, refer to line @var{n} in
+that source file. Search proceeds forward from the last examined
+trace snapshot. If no argument @var{n} is given, it means find the
+next line other than the one currently being examined; thus saying
+@code{tfind line} repeatedly can appear to have the same effect as
+stepping from line to line in a @emph{live} debugging session.
+@end table
-@item ?:
-The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
-of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
-integral type.
+The default arguments for the @code{tfind} commands are specifically
+designed to make it easy to scan through the trace buffer. For
+instance, @code{tfind} with no argument selects the next trace
+snapshot, and @code{tfind -} with no argument selects the previous
+trace snapshot. So, by giving one @code{tfind} command, and then
+simply hitting @key{RET} repeatedly you can examine all the trace
+snapshots in order. Or, by saying @code{tfind -} and then hitting
+@key{RET} repeatedly you can examine the snapshots in reverse order.
+The @code{tfind line} command with no argument selects the snapshot
+for the next source line executed. The @code{tfind pc} command with
+no argument selects the next snapshot with the same program counter
+(PC) as the current frame. The @code{tfind tracepoint} command with
+no argument selects the next trace snapshot collected by the same
+tracepoint as the current one.
+
+In addition to letting you scan through the trace buffer manually,
+these commands make it easy to construct @value{GDBN} scripts that
+scan through the trace buffer and print out whatever collected data
+you are interested in. Thus, if we want to examine the PC, FP, and SP
+registers from each trace frame in the buffer, we can say this:
-@item ||
-Logical @sc{or}. Defined on integral types.
+@smallexample
+(@value{GDBP}) @b{tfind start}
+(@value{GDBP}) @b{while ($trace_frame != -1)}
+> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
+ $trace_frame, $pc, $sp, $fp
+> tfind
+> end
+
+Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
+Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
+Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
+Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
+Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
+Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
+Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
+Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
+Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
+Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
+Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
+@end smallexample
-@item &&
-Logical @sc{and}. Defined on integral types.
+Or, if we want to examine the variable @code{X} at each source line in
+the buffer:
-@item |
-Bitwise @sc{or}. Defined on integral types.
+@smallexample
+(@value{GDBP}) @b{tfind start}
+(@value{GDBP}) @b{while ($trace_frame != -1)}
+> printf "Frame %d, X == %d\n", $trace_frame, X
+> tfind line
+> end
+
+Frame 0, X = 1
+Frame 7, X = 2
+Frame 13, X = 255
+@end smallexample
-@item ^
-Bitwise exclusive-@sc{or}. Defined on integral types.
+@node tdump
+@subsection @code{tdump}
+@kindex tdump
+@cindex dump all data collected at tracepoint
+@cindex tracepoint data, display
-@item &
-Bitwise @sc{and}. Defined on integral types.
+This command takes no arguments. It prints all the data collected at
+the current trace snapshot.
-@item ==@r{, }!=
-Equality and inequality. Defined on scalar types. The value of these
-expressions is 0 for false and non-zero for true.
+@smallexample
+(@value{GDBP}) @b{trace 444}
+(@value{GDBP}) @b{actions}
+Enter actions for tracepoint #2, one per line:
+> collect $regs, $locals, $args, gdb_long_test
+> end
+
+(@value{GDBP}) @b{tstart}
+
+(@value{GDBP}) @b{tfind line 444}
+#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
+at gdb_test.c:444
+444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
+
+(@value{GDBP}) @b{tdump}
+Data collected at tracepoint 2, trace frame 1:
+d0 0xc4aa0085 -995491707
+d1 0x18 24
+d2 0x80 128
+d3 0x33 51
+d4 0x71aea3d 119204413
+d5 0x22 34
+d6 0xe0 224
+d7 0x380035 3670069
+a0 0x19e24a 1696330
+a1 0x3000668 50333288
+a2 0x100 256
+a3 0x322000 3284992
+a4 0x3000698 50333336
+a5 0x1ad3cc 1758156
+fp 0x30bf3c 0x30bf3c
+sp 0x30bf34 0x30bf34
+ps 0x0 0
+pc 0x20b2c8 0x20b2c8
+fpcontrol 0x0 0
+fpstatus 0x0 0
+fpiaddr 0x0 0
+p = 0x20e5b4 "gdb-test"
+p1 = (void *) 0x11
+p2 = (void *) 0x22
+p3 = (void *) 0x33
+p4 = (void *) 0x44
+p5 = (void *) 0x55
+p6 = (void *) 0x66
+gdb_long_test = 17 '\021'
-@item <@r{, }>@r{, }<=@r{, }>=
-Less than, greater than, less than or equal, greater than or equal.
-Defined on scalar types. The value of these expressions is 0 for false
-and non-zero for true.
+(@value{GDBP})
+@end smallexample
-@item <<@r{, }>>
-left shift, and right shift. Defined on integral types.
+@node save-tracepoints
+@subsection @code{save-tracepoints @var{filename}}
+@kindex save-tracepoints
+@cindex save tracepoints for future sessions
-@item @@
-The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+This command saves all current tracepoint definitions together with
+their actions and passcounts, into a file @file{@var{filename}}
+suitable for use in a later debugging session. To read the saved
+tracepoint definitions, use the @code{source} command (@pxref{Command
+Files}).
-@item +@r{, }-
-Addition and subtraction. Defined on integral types, floating-point types and
-pointer types.
+@node Tracepoint Variables
+@section Convenience Variables for Tracepoints
+@cindex tracepoint variables
+@cindex convenience variables for tracepoints
-@item *@r{, }/@r{, }%
-Multiplication, division, and modulus. Multiplication and division are
-defined on integral and floating-point types. Modulus is defined on
-integral types.
+@table @code
+@vindex $trace_frame
+@item (int) $trace_frame
+The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no
+snapshot is selected.
+
+@vindex $tracepoint
+@item (int) $tracepoint
+The tracepoint for the current trace snapshot.
+
+@vindex $trace_line
+@item (int) $trace_line
+The line number for the current trace snapshot.
+
+@vindex $trace_file
+@item (char []) $trace_file
+The source file for the current trace snapshot.
+
+@vindex $trace_func
+@item (char []) $trace_func
+The name of the function containing @code{$tracepoint}.
+@end table
-@item ++@r{, }--
-Increment and decrement. When appearing before a variable, the
-operation is performed before the variable is used in an expression;
-when appearing after it, the variable's value is used before the
-operation takes place.
+Note: @code{$trace_file} is not suitable for use in @code{printf},
+use @code{output} instead.
-@item *
-Pointer dereferencing. Defined on pointer types. Same precedence as
-@code{++}.
+Here's a simple example of using these convenience variables for
+stepping through all the trace snapshots and printing some of their
+data.
-@item &
-Address operator. Defined on variables. Same precedence as @code{++}.
+@smallexample
+(@value{GDBP}) @b{tfind start}
-For debugging C++, @value{GDBN} implements a use of @samp{&} beyond what is
-allowed in the C++ language itself: you can use @samp{&(&@var{ref})}
-(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
-where a C++ reference variable (declared with @samp{&@var{ref}}) is
-stored.
+(@value{GDBP}) @b{while $trace_frame != -1}
+> output $trace_file
+> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
+> tfind
+> end
+@end smallexample
-@item -
-Negative. Defined on integral and floating-point types. Same
-precedence as @code{++}.
+@node Overlays
+@chapter Debugging Programs That Use Overlays
+@cindex overlays
-@item !
-Logical negation. Defined on integral types. Same precedence as
-@code{++}.
+If your program is too large to fit completely in your target system's
+memory, you can sometimes use @dfn{overlays} to work around this
+problem. @value{GDBN} provides some support for debugging programs that
+use overlays.
-@item ~
-Bitwise complement operator. Defined on integral types. Same precedence as
-@code{++}.
+@menu
+* How Overlays Work:: A general explanation of overlays.
+* Overlay Commands:: Managing overlays in @value{GDBN}.
+* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are
+ mapped by asking the inferior.
+* Overlay Sample Program:: A sample program using overlays.
+@end menu
+@node How Overlays Work
+@section How Overlays Work
+@cindex mapped overlays
+@cindex unmapped overlays
+@cindex load address, overlay's
+@cindex mapped address
+@cindex overlay area
+
+Suppose you have a computer whose instruction address space is only 64
+kilobytes long, but which has much more memory which can be accessed by
+other means: special instructions, segment registers, or memory
+management hardware, for example. Suppose further that you want to
+adapt a program which is larger than 64 kilobytes to run on this system.
+
+One solution is to identify modules of your program which are relatively
+independent, and need not call each other directly; call these modules
+@dfn{overlays}. Separate the overlays from the main program, and place
+their machine code in the larger memory. Place your main program in
+instruction memory, but leave at least enough space there to hold the
+largest overlay as well.
+
+Now, to call a function located in an overlay, you must first copy that
+overlay's machine code from the large memory into the space set aside
+for it in the instruction memory, and then jump to its entry point
+there.
-@item .@r{, }->
-Structure member, and pointer-to-structure member. For convenience,
-@value{GDBN} regards the two as equivalent, choosing whether to dereference a
-pointer based on the stored type information.
-Defined on @code{struct} and @code{union} data.
+@example
+@group
+ Data Instruction Larger
+Address Space Address Space Address Space
++-----------+ +-----------+ +-----------+
+| | | | | |
++-----------+ +-----------+ +-----------+<-- overlay 1
+| program | | main | | | load address
+| variables | | program | | overlay 1 |
+| and heap | | | ,---| |
++-----------+ | | | | |
+| | +-----------+ | +-----------+
++-----------+ | | | | |
+ mapped --->+-----------+ / +-----------+<-- overlay 2
+ address | overlay | <-' | overlay 2 | load address
+ | area | <-----| |
+ | | <---. +-----------+
+ | | | | |
+ +-----------+ | | |
+ | | | +-----------+<-- overlay 3
+ +-----------+ `--| | load address
+ | overlay 3 |
+ | |
+ +-----------+
+ | |
+ +-----------+
+
+ To map an overlay, copy its code from the larger address space
+ to the instruction address space. Since the overlays shown here
+ all use the same mapped address, only one may be mapped at a time.
+@end group
+@end example
-@ifset HPPA
-@item .*@r{, }->*
-Dereferences of pointers to members.
-@end ifset
+This diagram shows a system with separate data and instruction address
+spaces. For a system with a single address space for data and
+instructions, the diagram would be similar, except that the program
+variables and heap would share an address space with the main program
+and the overlay area.
-@item []
-Array indexing. @code{@var{a}[@var{i}]} is defined as
-@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
+An overlay loaded into instruction memory and ready for use is called a
+@dfn{mapped} overlay; its @dfn{mapped address} is its address in the
+instruction memory. An overlay not present (or only partially present)
+in instruction memory is called @dfn{unmapped}; its @dfn{load address}
+is its address in the larger memory. The mapped address is also called
+the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also
+called the @dfn{load memory address}, or @dfn{LMA}.
-@item ()
-Function parameter list. Same precedence as @code{->}.
+Unfortunately, overlays are not a completely transparent way to adapt a
+program to limited instruction memory. They introduce a new set of
+global constraints you must keep in mind as you design your program:
-@item ::
-C++ scope resolution operator. Defined on @code{struct}, @code{union},
-and @code{class} types.
+@itemize @bullet
-@item ::
-Doubled colons also represent the @value{GDBN} scope operator
-(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
-above.
-@end table
+@item
+Before calling or returning to a function in an overlay, your program
+must make sure that overlay is actually mapped. Otherwise, the call or
+return will transfer control to the right address, but in the wrong
+overlay, and your program will probably crash.
-@ifset HPPA
-If an operator is redefined in the user code, @value{GDBN} usually
-attempts to invoke the redefined version instead of using the operator's
-predefined meaning.
-@end ifset
+@item
+If the process of mapping an overlay is expensive on your system, you
+will need to choose your overlays carefully to minimize their effect on
+your program's performance.
-@menu
-* C Constants::
-@end menu
+@item
+The executable file you load onto your system must contain each
+overlay's instructions, appearing at the overlay's load address, not its
+mapped address. However, each overlay's instructions must be relocated
+and its symbols defined as if the overlay were at its mapped address.
+You can use GNU linker scripts to specify different load and relocation
+addresses for pieces of your program; see @ref{Overlay Description,,,
+ld.info, Using ld: the GNU linker}.
-@node C Constants, C plus plus expressions, C Operators, C
-@subsubsection C and C++ constants
+@item
+The procedure for loading executable files onto your system must be able
+to load their contents into the larger address space as well as the
+instruction and data spaces.
-@cindex C and C++ constants
+@end itemize
-@value{GDBN} allows you to express the constants of C and C++ in the
-following ways:
+The overlay system described above is rather simple, and could be
+improved in many ways:
@itemize @bullet
-@item
-Integer constants are a sequence of digits. Octal constants are
-specified by a leading @samp{0} (i.e. zero), and hexadecimal constants by
-a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
-@samp{l}, specifying that the constant should be treated as a
-@code{long} value.
@item
-Floating point constants are a sequence of digits, followed by a decimal
-point, followed by a sequence of digits, and optionally followed by an
-exponent. An exponent is of the form:
-@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
-sequence of digits. The @samp{+} is optional for positive exponents.
+If your system has suitable bank switch registers or memory management
+hardware, you could use those facilities to make an overlay's load area
+contents simply appear at their mapped address in instruction space.
+This would probably be faster than copying the overlay to its mapped
+area in the usual way.
@item
-Enumerated constants consist of enumerated identifiers, or their
-integral equivalents.
+If your overlays are small enough, you could set aside more than one
+overlay area, and have more than one overlay mapped at a time.
@item
-Character constants are a single character surrounded by single quotes
-(@code{'}), or a number---the ordinal value of the corresponding character
-(usually its @sc{ASCII} value). Within quotes, the single character may
-be represented by a letter or by @dfn{escape sequences}, which are of
-the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
-of the character's ordinal value; or of the form @samp{\@var{x}}, where
-@samp{@var{x}} is a predefined special character---for example,
-@samp{\n} for newline.
+You can use overlays to manage data, as well as instructions. In
+general, data overlays are even less transparent to your design than
+code overlays: whereas code overlays only require care when you call or
+return to functions, data overlays require care every time you access
+the data. Also, if you change the contents of a data overlay, you
+must copy its contents back out to its load address before you can copy a
+different data overlay into the same mapped area.
-@item
-String constants are a sequence of character constants surrounded
-by double quotes (@code{"}).
+@end itemize
-@item
-Pointer constants are an integral value. You can also write pointers
-to constants using the C operator @samp{&}.
-@item
-Array constants are comma-separated lists surrounded by braces @samp{@{}
-and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
-integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
-and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
-@end itemize
+@node Overlay Commands
+@section Overlay Commands
-@menu
-* C plus plus expressions::
-* C Defaults::
-* C Checks::
+To use @value{GDBN}'s overlay support, each overlay in your program must
+correspond to a separate section of the executable file. The section's
+virtual memory address and load memory address must be the overlay's
+mapped and load addresses. Identifying overlays with sections allows
+@value{GDBN} to determine the appropriate address of a function or
+variable, depending on whether the overlay is mapped or not.
-* Debugging C::
-@end menu
+@value{GDBN}'s overlay commands all start with the word @code{overlay};
+you can abbreviate this as @code{ov} or @code{ovly}. The commands are:
-@node C plus plus expressions, C Defaults, C Constants, C
-@subsubsection C++ expressions
-
-@cindex expressions in C++
-@value{GDBN} expression handling can interpret most C++ expressions.
-
-@ifclear HPPA
-@cindex C++ support, not in @sc{coff}
-@cindex @sc{coff} versus C++
-@cindex C++ and object formats
-@cindex object formats and C++
-@cindex a.out and C++
-@cindex @sc{ecoff} and C++
-@cindex @sc{xcoff} and C++
-@cindex @sc{elf}/stabs and C++
-@cindex @sc{elf}/@sc{dwarf} and C++
-@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
-@c periodically whether this has happened...
-@quotation
-@emph{Warning:} @value{GDBN} can only debug C++ code if you use the
-proper compiler. Typically, C++ debugging depends on the use of
-additional debugging information in the symbol table, and thus requires
-special support. In particular, if your compiler generates a.out, MIPS
-@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
-symbol table, these facilities are all available. (With @sc{gnu} CC,
-you can use the @samp{-gstabs} option to request stabs debugging
-extensions explicitly.) Where the object code format is standard
-@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C++
-support in @value{GDBN} does @emph{not} work.
-@end quotation
-@end ifclear
+@table @code
+@item overlay off
+@kindex overlay off
+Disable @value{GDBN}'s overlay support. When overlay support is
+disabled, @value{GDBN} assumes that all functions and variables are
+always present at their mapped addresses. By default, @value{GDBN}'s
+overlay support is disabled.
+
+@item overlay manual
+@kindex overlay manual
+@cindex manual overlay debugging
+Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN}
+relies on you to tell it which overlays are mapped, and which are not,
+using the @code{overlay map-overlay} and @code{overlay unmap-overlay}
+commands described below.
+
+@item overlay map-overlay @var{overlay}
+@itemx overlay map @var{overlay}
+@kindex overlay map-overlay
+@cindex map an overlay
+Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must
+be the name of the object file section containing the overlay. When an
+overlay is mapped, @value{GDBN} assumes it can find the overlay's
+functions and variables at their mapped addresses. @value{GDBN} assumes
+that any other overlays whose mapped ranges overlap that of
+@var{overlay} are now unmapped.
+
+@item overlay unmap-overlay @var{overlay}
+@itemx overlay unmap @var{overlay}
+@kindex overlay unmap-overlay
+@cindex unmap an overlay
+Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay}
+must be the name of the object file section containing the overlay.
+When an overlay is unmapped, @value{GDBN} assumes it can find the
+overlay's functions and variables at their load addresses.
+
+@item overlay auto
+@kindex overlay auto
+Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN}
+consults a data structure the overlay manager maintains in the inferior
+to see which overlays are mapped. For details, see @ref{Automatic
+Overlay Debugging}.
+
+@item overlay load-target
+@itemx overlay load
+@kindex overlay load-target
+@cindex reloading the overlay table
+Re-read the overlay table from the inferior. Normally, @value{GDBN}
+re-reads the table @value{GDBN} automatically each time the inferior
+stops, so this command should only be necessary if you have changed the
+overlay mapping yourself using @value{GDBN}. This command is only
+useful when using automatic overlay debugging.
+
+@item overlay list-overlays
+@itemx overlay list
+@cindex listing mapped overlays
+Display a list of the overlays currently mapped, along with their mapped
+addresses, load addresses, and sizes.
-@enumerate
+@end table
-@cindex member functions
-@item
-Member function calls are allowed; you can use expressions like
+Normally, when @value{GDBN} prints a code address, it includes the name
+of the function the address falls in:
@example
-count = aml->GetOriginal(x, y)
+(gdb) print main
+$3 = @{int ()@} 0x11a0 <main>
@end example
+@noindent
+When overlay debugging is enabled, @value{GDBN} recognizes code in
+unmapped overlays, and prints the names of unmapped functions with
+asterisks around them. For example, if @code{foo} is a function in an
+unmapped overlay, @value{GDBN} prints it this way:
-@kindex this
-@cindex namespace in C++
-@item
-While a member function is active (in the selected stack frame), your
-expressions have the same namespace available as the member function;
-that is, @value{GDBN} allows implicit references to the class instance
-pointer @code{this} following the same rules as C++.
+@example
+(gdb) overlay list
+No sections are mapped.
+(gdb) print foo
+$5 = @{int (int)@} 0x100000 <*foo*>
+@end example
+@noindent
+When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
+name normally:
-@ifclear HPPA
-@cindex call overloaded functions
-@cindex type conversions in C++
+@example
+(gdb) overlay list
+Section .ov.foo.text, loaded at 0x100000 - 0x100034,
+ mapped at 0x1016 - 0x104a
+(gdb) print foo
+$6 = @{int (int)@} 0x1016 <foo>
+@end example
+
+When overlay debugging is enabled, @value{GDBN} can find the correct
+address for functions and variables in an overlay, whether or not the
+overlay is mapped. This allows most @value{GDBN} commands, like
+@code{break} and @code{disassemble}, to work normally, even on unmapped
+code. However, @value{GDBN}'s breakpoint support has some limitations:
+
+@itemize @bullet
@item
-You can call overloaded functions; @value{GDBN} resolves the function
-call to the right definition, with one restriction---you must use
-arguments of the type required by the function that you want to call.
-@value{GDBN} does not perform conversions requiring constructors or
-user-defined type operators.
-@end ifclear
-@ifset HPPA
-@cindex call overloaded functions
-@cindex overloaded functions
-@cindex type conversions in C++
+@cindex breakpoints in overlays
+@cindex overlays, setting breakpoints in
+You can set breakpoints in functions in unmapped overlays, as long as
+@value{GDBN} can write to the overlay at its load address.
@item
-You can call overloaded functions; @value{GDBN} resolves the function
-call to the right definition, with some restrictions. GDB does not
-perform overload resolution involving user-defined type conversions,
-calls to constructors, or instantiations of templates that do not exist
-in the program. It also cannot handle ellipsis argument lists or
-default arguments.
+@value{GDBN} can not set hardware or simulator-based breakpoints in
+unmapped overlays. However, if you set a breakpoint at the end of your
+overlay manager (and tell @value{GDBN} which overlays are now mapped, if
+you are using manual overlay management), @value{GDBN} will re-set its
+breakpoints properly.
+@end itemize
-It does perform integral conversions and promotions, floating-point
-promotions, arithmetic conversions, pointer conversions, conversions of
-class objects to base classes, and standard conversions such as those of
-functions or arrays to pointers; it requires an exact match on the
-number of function arguments.
-Overload resolution is always performed, unless you have specified
-@code{set overload-resolution off}. @xref{Debugging C plus plus,
-,@value{GDBN} features for C++}.
+@node Automatic Overlay Debugging
+@section Automatic Overlay Debugging
+@cindex automatic overlay debugging
-You must specify@code{set overload-resolution off} in order to use an
-explicit function signature to call an overloaded function, as in
-@smallexample
-p 'foo(char,int)'('x', 13)
-@end smallexample
-The @value{GDBN} command-completion facility can simplify this;
-@pxref{Completion, ,Command completion}.
+@value{GDBN} can automatically track which overlays are mapped and which
+are not, given some simple co-operation from the overlay manager in the
+inferior. If you enable automatic overlay debugging with the
+@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN}
+looks in the inferior's memory for certain variables describing the
+current state of the overlays.
-@end ifset
+Here are the variables your overlay manager must define to support
+@value{GDBN}'s automatic overlay debugging:
-@cindex reference declarations
-@item
-@value{GDBN} understands variables declared as C++ references; you can use
-them in expressions just as you do in C++ source---they are automatically
-dereferenced.
+@table @asis
-In the parameter list shown when @value{GDBN} displays a frame, the values of
-reference variables are not displayed (unlike other variables); this
-avoids clutter, since references are often used for large structures.
-The @emph{address} of a reference variable is always shown, unless
-you have specified @samp{set print address off}.
+@item @code{_ovly_table}:
+This variable must be an array of the following structures:
-@item
-@value{GDBN} supports the C++ name resolution operator @code{::}---your
-expressions can use it just as expressions in your program do. Since
-one scope may be defined in another, you can use @code{::} repeatedly if
-necessary, for example in an expression like
-@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
-resolving name scope by reference to source files, in both C and C++
-debugging (@pxref{Variables, ,Program variables}).
-@end enumerate
+@example
+struct
+@{
+ /* The overlay's mapped address. */
+ unsigned long vma;
-@ifset HPPA
-In addition, @value{GDBN} supports calling virtual functions correctly,
-printing out virtual bases of objects, calling functions in a base
-subobject, casting objects, and invoking user-defined operators.
-@end ifset
+ /* The size of the overlay, in bytes. */
+ unsigned long size;
-@node C Defaults, C Checks, C plus plus expressions, C
-@subsubsection C and C++ defaults
+ /* The overlay's load address. */
+ unsigned long lma;
-@cindex C and C++ defaults
+ /* Non-zero if the overlay is currently mapped;
+ zero otherwise. */
+ unsigned long mapped;
+@}
+@end example
-@ifclear HPPA
-If you allow @value{GDBN} to set type and range checking automatically, they
-both default to @code{off} whenever the working language changes to
-C or C++. This happens regardless of whether you or @value{GDBN}
-selects the working language.
-@end ifclear
+@item @code{_novlys}:
+This variable must be a four-byte signed integer, holding the total
+number of elements in @code{_ovly_table}.
-If you allow @value{GDBN} to set the language automatically, it
-recognizes source files whose names end with @file{.c}, @file{.C}, or
-@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
-these files, it sets the working language to C or C++.
-@xref{Automatically, ,Having @value{GDBN} infer the source language},
-for further details.
+@end table
-@c Type checking is (a) primarily motivated by Modula-2, and (b)
-@c unimplemented. If (b) changes, it might make sense to let this node
-@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
+To decide whether a particular overlay is mapped or not, @value{GDBN}
+looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and
+@code{lma} members equal the VMA and LMA of the overlay's section in the
+executable file. When @value{GDBN} finds a matching entry, it consults
+the entry's @code{mapped} member to determine whether the overlay is
+currently mapped.
-@node C Checks, Debugging C, C Defaults, C Constants
-@subsubsection C and C++ type and range checks
-@cindex C and C++ checks
+@node Overlay Sample Program
+@section Overlay Sample Program
+@cindex overlay example program
-By default, when @value{GDBN} parses C or C++ expressions, type checking
-is not used. However, if you turn type checking on, @value{GDBN}
-considers two variables type equivalent if:
+When linking a program which uses overlays, you must place the overlays
+at their load addresses, while relocating them to run at their mapped
+addresses. To do this, you must write a linker script (@pxref{Overlay
+Description,,, ld.info, Using ld: the GNU linker}). Unfortunately,
+since linker scripts are specific to a particular host system, target
+architecture, and target memory layout, this manual cannot provide
+portable sample code demonstrating @value{GDBN}'s overlay support.
-@itemize @bullet
-@item
-The two variables are structured and have the same structure, union, or
-enumerated tag.
+However, the @value{GDBN} source distribution does contain an overlaid
+program, with linker scripts for a few systems, as part of its test
+suite. The program consists of the following files from
+@file{gdb/testsuite/gdb.base}:
-@item
-The two variables have the same type name, or types that have been
-declared equivalent through @code{typedef}.
+@table @file
+@item overlays.c
+The main program file.
+@item ovlymgr.c
+A simple overlay manager, used by @file{overlays.c}.
+@item foo.c
+@itemx bar.c
+@itemx baz.c
+@itemx grbx.c
+Overlay modules, loaded and used by @file{overlays.c}.
+@item d10v.ld
+@itemx m32r.ld
+Linker scripts for linking the test program on the @code{d10v-elf}
+and @code{m32r-elf} targets.
+@end table
-@ignore
-@c leaving this out because neither J Gilmore nor R Pesch understand it.
-@c FIXME--beers?
-@item
-The two @code{struct}, @code{union}, or @code{enum} variables are
-declared in the same declaration. (Note: this may not be true for all C
-compilers.)
-@end ignore
-@end itemize
+You can build the test program using the @code{d10v-elf} GCC
+cross-compiler like this:
-Range checking, if turned on, is done on mathematical operations. Array
-indices are not checked, since they are often used to index a pointer
-that is not itself an array.
+@example
+$ d10v-elf-gcc -g -c overlays.c
+$ d10v-elf-gcc -g -c ovlymgr.c
+$ d10v-elf-gcc -g -c foo.c
+$ d10v-elf-gcc -g -c bar.c
+$ d10v-elf-gcc -g -c baz.c
+$ d10v-elf-gcc -g -c grbx.c
+$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
+ baz.o grbx.o -Wl,-Td10v.ld -o overlays
+@end example
-@node Debugging C, Debugging C plus plus, C Checks, C
-@subsubsection @value{GDBN} and C
+The build process is identical for any other architecture, except that
+you must substitute the appropriate compiler and linker script for the
+target system for @code{d10v-elf-gcc} and @code{d10v.ld}.
-The @code{set print union} and @code{show print union} commands apply to
-the @code{union} type. When set to @samp{on}, any @code{union} that is
-inside a @code{struct} or @code{class} is also printed. Otherwise, it
-appears as @samp{@{...@}}.
-The @code{@@} operator aids in the debugging of dynamic arrays, formed
-with pointers and a memory allocation function. @xref{Expressions,
-,Expressions}.
+@node Languages
+@chapter Using @value{GDBN} with Different Languages
+@cindex languages
+
+Although programming languages generally have common aspects, they are
+rarely expressed in the same manner. For instance, in ANSI C,
+dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
+Modula-2, it is accomplished by @code{p^}. Values can also be
+represented (and displayed) differently. Hex numbers in C appear as
+@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
+
+@cindex working language
+Language-specific information is built into @value{GDBN} for some languages,
+allowing you to express operations like the above in your program's
+native language, and allowing @value{GDBN} to output values in a manner
+consistent with the syntax of your program's native language. The
+language you use to build expressions is called the @dfn{working
+language}.
@menu
-* Debugging C plus plus::
+* Setting:: Switching between source languages
+* Show:: Displaying the language
+* Checks:: Type and range checks
+* Support:: Supported languages
@end menu
-@node Debugging C plus plus, , Debugging C, C
-@subsubsection @value{GDBN} features for C++
+@node Setting
+@section Switching between source languages
-@cindex commands for C++
+There are two ways to control the working language---either have @value{GDBN}
+set it automatically, or select it manually yourself. You can use the
+@code{set language} command for either purpose. On startup, @value{GDBN}
+defaults to setting the language automatically. The working language is
+used to determine how expressions you type are interpreted, how values
+are printed, etc.
-Some @value{GDBN} commands are particularly useful with C++, and some are
-designed specifically for use with C++. Here is a summary:
+In addition to the working language, every source file that
+@value{GDBN} knows about has its own working language. For some object
+file formats, the compiler might indicate which language a particular
+source file is in. However, most of the time @value{GDBN} infers the
+language from the name of the file. The language of a source file
+controls whether C@t{++} names are demangled---this way @code{backtrace} can
+show each frame appropriately for its own language. There is no way to
+set the language of a source file from within @value{GDBN}, but you can
+set the language associated with a filename extension. @xref{Show, ,
+Displaying the language}.
-@table @code
-@cindex break in overloaded functions
-@item @r{breakpoint menus}
-When you want a breakpoint in a function whose name is overloaded,
-@value{GDBN} breakpoint menus help you specify which function definition
-you want. @xref{Breakpoint Menus,,Breakpoint menus}.
+This is most commonly a problem when you use a program, such
+as @code{cfront} or @code{f2c}, that generates C but is written in
+another language. In that case, make the
+program use @code{#line} directives in its C output; that way
+@value{GDBN} will know the correct language of the source code of the original
+program, and will display that source code, not the generated C code.
-@cindex overloading in C++
-@item rbreak @var{regex}
-Setting breakpoints using regular expressions is helpful for setting
-breakpoints on overloaded functions that are not members of any special
-classes.
-@xref{Set Breaks, ,Setting breakpoints}.
+@menu
+* Filenames:: Filename extensions and languages.
+* Manually:: Setting the working language manually
+* Automatically:: Having @value{GDBN} infer the source language
+@end menu
-@cindex C++ exception handling
-@item catch throw
-@itemx catch catch
-Debug C++ exception handling using these commands. @xref{Set
-Catchpoints, , Setting catchpoints}.
+@node Filenames
+@subsection List of filename extensions and languages
-@cindex inheritance
-@item ptype @var{typename}
-Print inheritance relationships as well as other information for type
-@var{typename}.
-@xref{Symbols, ,Examining the Symbol Table}.
+If a source file name ends in one of the following extensions, then
+@value{GDBN} infers that its language is the one indicated.
-@cindex C++ symbol display
-@item set print demangle
-@itemx show print demangle
-@itemx set print asm-demangle
-@itemx show print asm-demangle
-Control whether C++ symbols display in their source form, both when
-displaying code as C++ source and when displaying disassemblies.
-@xref{Print Settings, ,Print settings}.
+@table @file
-@item set print object
-@itemx show print object
-Choose whether to print derived (actual) or declared types of objects.
-@xref{Print Settings, ,Print settings}.
+@item .c
+C source file
-@item set print vtbl
-@itemx show print vtbl
-Control the format for printing virtual function tables.
-@xref{Print Settings, ,Print settings}.
-@ifset HPPA
-(The @code{vtbl} commands do not work on programs compiled with the HP
-ANSI C++ compiler (@code{aCC}).)
+@item .C
+@itemx .cc
+@itemx .cp
+@itemx .cpp
+@itemx .cxx
+@itemx .c++
+C@t{++} source file
-@kindex set overload-resolution
-@cindex overloaded functions
-@item set overload-resolution on
-Enable overload resolution for C++ expression evaluation. The default
-is on. For overloaded functions, @value{GDBN} evaluates the arguments
-and searches for a function whose signature matches the argument types,
-using the standard C++ conversion rules (@pxref{C plus plus expressions, ,C++
-expressions} for details). If it cannot find a match, it emits a
-message.
+@item .f
+@itemx .F
+Fortran source file
-@item set overload-resolution off
-Disable overload resolution for C++ expression evaluation. For
-overloaded functions that are not class member functions, @value{GDBN}
-chooses the first function of the specified name that it finds in the
-symbol table, whether or not its arguments are of the correct type. For
-overloaded functions that are class member functions, @value{GDBN}
-searches for a function whose signature @emph{exactly} matches the
-argument types.
-@end ifset
+@item .ch
+@itemx .c186
+@itemx .c286
+CHILL source file
-@item @r{Overloaded symbol names}
-You can specify a particular definition of an overloaded symbol, using
-the same notation that is used to declare such symbols in C++: type
-@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
-also use the @value{GDBN} command-line word completion facilities to list the
-available choices, or to finish the type list for you.
-@xref{Completion,, Command completion}, for details on how to do this.
+@item .mod
+Modula-2 source file
+
+@item .s
+@itemx .S
+Assembler source file. This actually behaves almost like C, but
+@value{GDBN} does not skip over function prologues when stepping.
@end table
-@node Modula-2, , C, Support
-@subsection Modula-2
+In addition, you may set the language associated with a filename
+extension. @xref{Show, , Displaying the language}.
-@cindex Modula-2
+@node Manually
+@subsection Setting the working language
-The extensions made to @value{GDBN} to support Modula-2 only support
-output from the @sc{gnu} Modula-2 compiler (which is currently being
-developed). Other Modula-2 compilers are not currently supported, and
-attempting to debug executables produced by them is most likely
-to give an error as @value{GDBN} reads in the executable's symbol
-table.
+If you allow @value{GDBN} to set the language automatically,
+expressions are interpreted the same way in your debugging session and
+your program.
-@cindex expressions in Modula-2
-@menu
-* M2 Operators:: Built-in operators
-* Built-In Func/Proc:: Built-in functions and procedures
-* M2 Constants:: Modula-2 constants
-* M2 Defaults:: Default settings for Modula-2
-* Deviations:: Deviations from standard Modula-2
-* M2 Checks:: Modula-2 type and range checks
-* M2 Scope:: The scope operators @code{::} and @code{.}
-* GDB/M2:: @value{GDBN} and Modula-2
-@end menu
+@kindex set language
+If you wish, you may set the language manually. To do this, issue the
+command @samp{set language @var{lang}}, where @var{lang} is the name of
+a language, such as
+@code{c} or @code{modula-2}.
+For a list of the supported languages, type @samp{set language}.
-@node M2 Operators, Built-In Func/Proc, Modula-2, Modula-2
-@subsubsection Operators
-@cindex Modula-2 operators
+Setting the language manually prevents @value{GDBN} from updating the working
+language automatically. This can lead to confusion if you try
+to debug a program when the working language is not the same as the
+source language, when an expression is acceptable to both
+languages---but means different things. For instance, if the current
+source file were written in C, and @value{GDBN} was parsing Modula-2, a
+command such as:
-Operators must be defined on values of specific types. For instance,
-@code{+} is defined on numbers, but not on structures. Operators are
-often defined on groups of types. For the purposes of Modula-2, the
-following definitions hold:
+@example
+print a = b + c
+@end example
-@itemize @bullet
+@noindent
+might not have the effect you intended. In C, this means to add
+@code{b} and @code{c} and place the result in @code{a}. The result
+printed would be the value of @code{a}. In Modula-2, this means to compare
+@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
-@item
-@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
-their subranges.
+@node Automatically
+@subsection Having @value{GDBN} infer the source language
+
+To have @value{GDBN} set the working language automatically, use
+@samp{set language local} or @samp{set language auto}. @value{GDBN}
+then infers the working language. That is, when your program stops in a
+frame (usually by encountering a breakpoint), @value{GDBN} sets the
+working language to the language recorded for the function in that
+frame. If the language for a frame is unknown (that is, if the function
+or block corresponding to the frame was defined in a source file that
+does not have a recognized extension), the current working language is
+not changed, and @value{GDBN} issues a warning.
+
+This may not seem necessary for most programs, which are written
+entirely in one source language. However, program modules and libraries
+written in one source language can be used by a main program written in
+a different source language. Using @samp{set language auto} in this
+case frees you from having to set the working language manually.
+
+@node Show
+@section Displaying the language
+
+The following commands help you find out which language is the
+working language, and also what language source files were written in.
+
+@kindex show language
+@kindex info frame@r{, show the source language}
+@kindex info source@r{, show the source language}
+@table @code
+@item show language
+Display the current working language. This is the
+language you can use with commands such as @code{print} to
+build and compute expressions that may involve variables in your program.
+
+@item info frame
+Display the source language for this frame. This language becomes the
+working language if you use an identifier from this frame.
+@xref{Frame Info, ,Information about a frame}, to identify the other
+information listed here.
+
+@item info source
+Display the source language of this source file.
+@xref{Symbols, ,Examining the Symbol Table}, to identify the other
+information listed here.
+@end table
+
+In unusual circumstances, you may have source files with extensions
+not in the standard list. You can then set the extension associated
+with a language explicitly:
+
+@kindex set extension-language
+@kindex info extensions
+@table @code
+@item set extension-language @var{.ext} @var{language}
+Set source files with extension @var{.ext} to be assumed to be in
+the source language @var{language}.
+
+@item info extensions
+List all the filename extensions and the associated languages.
+@end table
+
+@node Checks
+@section Type and range checking
+
+@quotation
+@emph{Warning:} In this release, the @value{GDBN} commands for type and range
+checking are included, but they do not yet have any effect. This
+section documents the intended facilities.
+@end quotation
+@c FIXME remove warning when type/range code added
+
+Some languages are designed to guard you against making seemingly common
+errors through a series of compile- and run-time checks. These include
+checking the type of arguments to functions and operators, and making
+sure mathematical overflows are caught at run time. Checks such as
+these help to ensure a program's correctness once it has been compiled
+by eliminating type mismatches, and providing active checks for range
+errors when your program is running.
+
+@value{GDBN} can check for conditions like the above if you wish.
+Although @value{GDBN} does not check the statements in your program, it
+can check expressions entered directly into @value{GDBN} for evaluation via
+the @code{print} command, for example. As with the working language,
+@value{GDBN} can also decide whether or not to check automatically based on
+your program's source language. @xref{Support, ,Supported languages},
+for the default settings of supported languages.
+
+@menu
+* Type Checking:: An overview of type checking
+* Range Checking:: An overview of range checking
+@end menu
+
+@cindex type checking
+@cindex checks, type
+@node Type Checking
+@subsection An overview of type checking
+
+Some languages, such as Modula-2, are strongly typed, meaning that the
+arguments to operators and functions have to be of the correct type,
+otherwise an error occurs. These checks prevent type mismatch
+errors from ever causing any run-time problems. For example,
+
+@smallexample
+1 + 2 @result{} 3
+@exdent but
+@error{} 1 + 2.3
+@end smallexample
+
+The second example fails because the @code{CARDINAL} 1 is not
+type-compatible with the @code{REAL} 2.3.
+
+For the expressions you use in @value{GDBN} commands, you can tell the
+@value{GDBN} type checker to skip checking;
+to treat any mismatches as errors and abandon the expression;
+or to only issue warnings when type mismatches occur,
+but evaluate the expression anyway. When you choose the last of
+these, @value{GDBN} evaluates expressions like the second example above, but
+also issues a warning.
+
+Even if you turn type checking off, there may be other reasons
+related to type that prevent @value{GDBN} from evaluating an expression.
+For instance, @value{GDBN} does not know how to add an @code{int} and
+a @code{struct foo}. These particular type errors have nothing to do
+with the language in use, and usually arise from expressions, such as
+the one described above, which make little sense to evaluate anyway.
+
+Each language defines to what degree it is strict about type. For
+instance, both Modula-2 and C require the arguments to arithmetical
+operators to be numbers. In C, enumerated types and pointers can be
+represented as numbers, so that they are valid arguments to mathematical
+operators. @xref{Support, ,Supported languages}, for further
+details on specific languages.
+
+@value{GDBN} provides some additional commands for controlling the type checker:
+
+@kindex set check@r{, type}
+@kindex set check type
+@kindex show check type
+@table @code
+@item set check type auto
+Set type checking on or off based on the current working language.
+@xref{Support, ,Supported languages}, for the default settings for
+each language.
+
+@item set check type on
+@itemx set check type off
+Set type checking on or off, overriding the default setting for the
+current working language. Issue a warning if the setting does not
+match the language default. If any type mismatches occur in
+evaluating an expression while type checking is on, @value{GDBN} prints a
+message and aborts evaluation of the expression.
+
+@item set check type warn
+Cause the type checker to issue warnings, but to always attempt to
+evaluate the expression. Evaluating the expression may still
+be impossible for other reasons. For example, @value{GDBN} cannot add
+numbers and structures.
+
+@item show type
+Show the current setting of the type checker, and whether or not @value{GDBN}
+is setting it automatically.
+@end table
+
+@cindex range checking
+@cindex checks, range
+@node Range Checking
+@subsection An overview of range checking
+
+In some languages (such as Modula-2), it is an error to exceed the
+bounds of a type; this is enforced with run-time checks. Such range
+checking is meant to ensure program correctness by making sure
+computations do not overflow, or indices on an array element access do
+not exceed the bounds of the array.
+
+For expressions you use in @value{GDBN} commands, you can tell
+@value{GDBN} to treat range errors in one of three ways: ignore them,
+always treat them as errors and abandon the expression, or issue
+warnings but evaluate the expression anyway.
+
+A range error can result from numerical overflow, from exceeding an
+array index bound, or when you type a constant that is not a member
+of any type. Some languages, however, do not treat overflows as an
+error. In many implementations of C, mathematical overflow causes the
+result to ``wrap around'' to lower values---for example, if @var{m} is
+the largest integer value, and @var{s} is the smallest, then
+
+@example
+@var{m} + 1 @result{} @var{s}
+@end example
+
+This, too, is specific to individual languages, and in some cases
+specific to individual compilers or machines. @xref{Support, ,
+Supported languages}, for further details on specific languages.
+
+@value{GDBN} provides some additional commands for controlling the range checker:
+
+@kindex set check@r{, range}
+@kindex set check range
+@kindex show check range
+@table @code
+@item set check range auto
+Set range checking on or off based on the current working language.
+@xref{Support, ,Supported languages}, for the default settings for
+each language.
+
+@item set check range on
+@itemx set check range off
+Set range checking on or off, overriding the default setting for the
+current working language. A warning is issued if the setting does not
+match the language default. If a range error occurs and range checking is on,
+then a message is printed and evaluation of the expression is aborted.
+
+@item set check range warn
+Output messages when the @value{GDBN} range checker detects a range error,
+but attempt to evaluate the expression anyway. Evaluating the
+expression may still be impossible for other reasons, such as accessing
+memory that the process does not own (a typical example from many Unix
+systems).
+
+@item show range
+Show the current setting of the range checker, and whether or not it is
+being set automatically by @value{GDBN}.
+@end table
+
+@node Support
+@section Supported languages
+
+@value{GDBN} supports C, C@t{++}, Fortran, Java, Chill, assembly, and Modula-2.
+@c This is false ...
+Some @value{GDBN} features may be used in expressions regardless of the
+language you use: the @value{GDBN} @code{@@} and @code{::} operators,
+and the @samp{@{type@}addr} construct (@pxref{Expressions,
+,Expressions}) can be used with the constructs of any supported
+language.
+
+The following sections detail to what degree each source language is
+supported by @value{GDBN}. These sections are not meant to be language
+tutorials or references, but serve only as a reference guide to what the
+@value{GDBN} expression parser accepts, and what input and output
+formats should look like for different languages. There are many good
+books written on each of these languages; please look to these for a
+language reference or tutorial.
+
+@menu
+* C:: C and C@t{++}
+* Modula-2:: Modula-2
+* Chill:: Chill
+@end menu
+
+@node C
+@subsection C and C@t{++}
+
+@cindex C and C@t{++}
+@cindex expressions in C or C@t{++}
+
+Since C and C@t{++} are so closely related, many features of @value{GDBN} apply
+to both languages. Whenever this is the case, we discuss those languages
+together.
+
+@cindex C@t{++}
+@cindex @code{g++}, @sc{gnu} C@t{++} compiler
+@cindex @sc{gnu} C@t{++}
+The C@t{++} debugging facilities are jointly implemented by the C@t{++}
+compiler and @value{GDBN}. Therefore, to debug your C@t{++} code
+effectively, you must compile your C@t{++} programs with a supported
+C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
+compiler (@code{aCC}).
+
+For best results when using @sc{gnu} C@t{++}, use the stabs debugging
+format. You can select that format explicitly with the @code{g++}
+command-line options @samp{-gstabs} or @samp{-gstabs+}. See
+@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
+CC, gcc.info, Using @sc{gnu} CC}, for more information.
+
+@menu
+* C Operators:: C and C@t{++} operators
+* C Constants:: C and C@t{++} constants
+* C plus plus expressions:: C@t{++} expressions
+* C Defaults:: Default settings for C and C@t{++}
+* C Checks:: C and C@t{++} type and range checks
+* Debugging C:: @value{GDBN} and C
+* Debugging C plus plus:: @value{GDBN} features for C@t{++}
+@end menu
+
+@node C Operators
+@subsubsection C and C@t{++} operators
+
+@cindex C and C@t{++} operators
+
+Operators must be defined on values of specific types. For instance,
+@code{+} is defined on numbers, but not on structures. Operators are
+often defined on groups of types.
+
+For the purposes of C and C@t{++}, the following definitions hold:
+
+@itemize @bullet
+
+@item
+@emph{Integral types} include @code{int} with any of its storage-class
+specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}.
+
+@item
+@emph{Floating-point types} include @code{float}, @code{double}, and
+@code{long double} (if supported by the target platform).
+
+@item
+@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
+
+@item
+@emph{Scalar types} include all of the above.
+
+@end itemize
+
+@noindent
+The following operators are supported. They are listed here
+in order of increasing precedence:
+
+@table @code
+@item ,
+The comma or sequencing operator. Expressions in a comma-separated list
+are evaluated from left to right, with the result of the entire
+expression being the last expression evaluated.
+
+@item =
+Assignment. The value of an assignment expression is the value
+assigned. Defined on scalar types.
+
+@item @var{op}=
+Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
+and translated to @w{@code{@var{a} = @var{a op b}}}.
+@w{@code{@var{op}=}} and @code{=} have the same precedence.
+@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
+@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
+
+@item ?:
+The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
+of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
+integral type.
+
+@item ||
+Logical @sc{or}. Defined on integral types.
+
+@item &&
+Logical @sc{and}. Defined on integral types.
+
+@item |
+Bitwise @sc{or}. Defined on integral types.
+
+@item ^
+Bitwise exclusive-@sc{or}. Defined on integral types.
+
+@item &
+Bitwise @sc{and}. Defined on integral types.
+
+@item ==@r{, }!=
+Equality and inequality. Defined on scalar types. The value of these
+expressions is 0 for false and non-zero for true.
+
+@item <@r{, }>@r{, }<=@r{, }>=
+Less than, greater than, less than or equal, greater than or equal.
+Defined on scalar types. The value of these expressions is 0 for false
+and non-zero for true.
+
+@item <<@r{, }>>
+left shift, and right shift. Defined on integral types.
+
+@item @@
+The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+
+@item +@r{, }-
+Addition and subtraction. Defined on integral types, floating-point types and
+pointer types.
+
+@item *@r{, }/@r{, }%
+Multiplication, division, and modulus. Multiplication and division are
+defined on integral and floating-point types. Modulus is defined on
+integral types.
+
+@item ++@r{, }--
+Increment and decrement. When appearing before a variable, the
+operation is performed before the variable is used in an expression;
+when appearing after it, the variable's value is used before the
+operation takes place.
+
+@item *
+Pointer dereferencing. Defined on pointer types. Same precedence as
+@code{++}.
+
+@item &
+Address operator. Defined on variables. Same precedence as @code{++}.
+
+For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
+allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
+(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
+where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
+stored.
+
+@item -
+Negative. Defined on integral and floating-point types. Same
+precedence as @code{++}.
+
+@item !
+Logical negation. Defined on integral types. Same precedence as
+@code{++}.
+
+@item ~
+Bitwise complement operator. Defined on integral types. Same precedence as
+@code{++}.
+
+
+@item .@r{, }->
+Structure member, and pointer-to-structure member. For convenience,
+@value{GDBN} regards the two as equivalent, choosing whether to dereference a
+pointer based on the stored type information.
+Defined on @code{struct} and @code{union} data.
+
+@item .*@r{, }->*
+Dereferences of pointers to members.
+
+@item []
+Array indexing. @code{@var{a}[@var{i}]} is defined as
+@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
+
+@item ()
+Function parameter list. Same precedence as @code{->}.
+
+@item ::
+C@t{++} scope resolution operator. Defined on @code{struct}, @code{union},
+and @code{class} types.
+
+@item ::
+Doubled colons also represent the @value{GDBN} scope operator
+(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
+above.
+@end table
+
+If an operator is redefined in the user code, @value{GDBN} usually
+attempts to invoke the redefined version instead of using the operator's
+predefined meaning.
+
+@menu
+* C Constants::
+@end menu
+
+@node C Constants
+@subsubsection C and C@t{++} constants
+
+@cindex C and C@t{++} constants
+
+@value{GDBN} allows you to express the constants of C and C@t{++} in the
+following ways:
+
+@itemize @bullet
+@item
+Integer constants are a sequence of digits. Octal constants are
+specified by a leading @samp{0} (i.e. zero), and hexadecimal constants by
+a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
+@samp{l}, specifying that the constant should be treated as a
+@code{long} value.
+
+@item
+Floating point constants are a sequence of digits, followed by a decimal
+point, followed by a sequence of digits, and optionally followed by an
+exponent. An exponent is of the form:
+@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
+sequence of digits. The @samp{+} is optional for positive exponents.
+A floating-point constant may also end with a letter @samp{f} or
+@samp{F}, specifying that the constant should be treated as being of
+the @code{float} (as opposed to the default @code{double}) type; or with
+a letter @samp{l} or @samp{L}, which specifies a @code{long double}
+constant.
+
+@item
+Enumerated constants consist of enumerated identifiers, or their
+integral equivalents.
+
+@item
+Character constants are a single character surrounded by single quotes
+(@code{'}), or a number---the ordinal value of the corresponding character
+(usually its @sc{ascii} value). Within quotes, the single character may
+be represented by a letter or by @dfn{escape sequences}, which are of
+the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
+of the character's ordinal value; or of the form @samp{\@var{x}}, where
+@samp{@var{x}} is a predefined special character---for example,
+@samp{\n} for newline.
+
+@item
+String constants are a sequence of character constants surrounded by
+double quotes (@code{"}). Any valid character constant (as described
+above) may appear. Double quotes within the string must be preceded by
+a backslash, so for instance @samp{"a\"b'c"} is a string of five
+characters.
+
+@item
+Pointer constants are an integral value. You can also write pointers
+to constants using the C operator @samp{&}.
+
+@item
+Array constants are comma-separated lists surrounded by braces @samp{@{}
+and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
+integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
+and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
+@end itemize
+
+@menu
+* C plus plus expressions::
+* C Defaults::
+* C Checks::
+
+* Debugging C::
+@end menu
+
+@node C plus plus expressions
+@subsubsection C@t{++} expressions
+
+@cindex expressions in C@t{++}
+@value{GDBN} expression handling can interpret most C@t{++} expressions.
+
+@cindex C@t{++} support, not in @sc{coff}
+@cindex @sc{coff} versus C@t{++}
+@cindex C@t{++} and object formats
+@cindex object formats and C@t{++}
+@cindex a.out and C@t{++}
+@cindex @sc{ecoff} and C@t{++}
+@cindex @sc{xcoff} and C@t{++}
+@cindex @sc{elf}/stabs and C@t{++}
+@cindex @sc{elf}/@sc{dwarf} and C@t{++}
+@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
+@c periodically whether this has happened...
+@quotation
+@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
+proper compiler. Typically, C@t{++} debugging depends on the use of
+additional debugging information in the symbol table, and thus requires
+special support. In particular, if your compiler generates a.out, MIPS
+@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
+symbol table, these facilities are all available. (With @sc{gnu} CC,
+you can use the @samp{-gstabs} option to request stabs debugging
+extensions explicitly.) Where the object code format is standard
+@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++}
+support in @value{GDBN} does @emph{not} work.
+@end quotation
+
+@enumerate
+
+@cindex member functions
+@item
+Member function calls are allowed; you can use expressions like
+
+@example
+count = aml->GetOriginal(x, y)
+@end example
+
+@vindex this@r{, inside C@t{++} member functions}
+@cindex namespace in C@t{++}
+@item
+While a member function is active (in the selected stack frame), your
+expressions have the same namespace available as the member function;
+that is, @value{GDBN} allows implicit references to the class instance
+pointer @code{this} following the same rules as C@t{++}.
+
+@cindex call overloaded functions
+@cindex overloaded functions, calling
+@cindex type conversions in C@t{++}
+@item
+You can call overloaded functions; @value{GDBN} resolves the function
+call to the right definition, with some restrictions. @value{GDBN} does not
+perform overload resolution involving user-defined type conversions,
+calls to constructors, or instantiations of templates that do not exist
+in the program. It also cannot handle ellipsis argument lists or
+default arguments.
+
+It does perform integral conversions and promotions, floating-point
+promotions, arithmetic conversions, pointer conversions, conversions of
+class objects to base classes, and standard conversions such as those of
+functions or arrays to pointers; it requires an exact match on the
+number of function arguments.
+
+Overload resolution is always performed, unless you have specified
+@code{set overload-resolution off}. @xref{Debugging C plus plus,
+,@value{GDBN} features for C@t{++}}.
+
+You must specify @code{set overload-resolution off} in order to use an
+explicit function signature to call an overloaded function, as in
+@smallexample
+p 'foo(char,int)'('x', 13)
+@end smallexample
+
+The @value{GDBN} command-completion facility can simplify this;
+see @ref{Completion, ,Command completion}.
+
+@cindex reference declarations
+@item
+@value{GDBN} understands variables declared as C@t{++} references; you can use
+them in expressions just as you do in C@t{++} source---they are automatically
+dereferenced.
+
+In the parameter list shown when @value{GDBN} displays a frame, the values of
+reference variables are not displayed (unlike other variables); this
+avoids clutter, since references are often used for large structures.
+The @emph{address} of a reference variable is always shown, unless
+you have specified @samp{set print address off}.
+
+@item
+@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your
+expressions can use it just as expressions in your program do. Since
+one scope may be defined in another, you can use @code{::} repeatedly if
+necessary, for example in an expression like
+@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
+resolving name scope by reference to source files, in both C and C@t{++}
+debugging (@pxref{Variables, ,Program variables}).
+@end enumerate
+
+In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports
+calling virtual functions correctly, printing out virtual bases of
+objects, calling functions in a base subobject, casting objects, and
+invoking user-defined operators.
+
+@node C Defaults
+@subsubsection C and C@t{++} defaults
+
+@cindex C and C@t{++} defaults
+
+If you allow @value{GDBN} to set type and range checking automatically, they
+both default to @code{off} whenever the working language changes to
+C or C@t{++}. This happens regardless of whether you or @value{GDBN}
+selects the working language.
+
+If you allow @value{GDBN} to set the language automatically, it
+recognizes source files whose names end with @file{.c}, @file{.C}, or
+@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
+these files, it sets the working language to C or C@t{++}.
+@xref{Automatically, ,Having @value{GDBN} infer the source language},
+for further details.
+
+@c Type checking is (a) primarily motivated by Modula-2, and (b)
+@c unimplemented. If (b) changes, it might make sense to let this node
+@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
+
+@node C Checks
+@subsubsection C and C@t{++} type and range checks
+
+@cindex C and C@t{++} checks
+
+By default, when @value{GDBN} parses C or C@t{++} expressions, type checking
+is not used. However, if you turn type checking on, @value{GDBN}
+considers two variables type equivalent if:
+
+@itemize @bullet
+@item
+The two variables are structured and have the same structure, union, or
+enumerated tag.
+
+@item
+The two variables have the same type name, or types that have been
+declared equivalent through @code{typedef}.
+
+@ignore
+@c leaving this out because neither J Gilmore nor R Pesch understand it.
+@c FIXME--beers?
+@item
+The two @code{struct}, @code{union}, or @code{enum} variables are
+declared in the same declaration. (Note: this may not be true for all C
+compilers.)
+@end ignore
+@end itemize
+
+Range checking, if turned on, is done on mathematical operations. Array
+indices are not checked, since they are often used to index a pointer
+that is not itself an array.
+
+@node Debugging C
+@subsubsection @value{GDBN} and C
+
+The @code{set print union} and @code{show print union} commands apply to
+the @code{union} type. When set to @samp{on}, any @code{union} that is
+inside a @code{struct} or @code{class} is also printed. Otherwise, it
+appears as @samp{@{...@}}.
+
+The @code{@@} operator aids in the debugging of dynamic arrays, formed
+with pointers and a memory allocation function. @xref{Expressions,
+,Expressions}.
+
+@menu
+* Debugging C plus plus::
+@end menu
+
+@node Debugging C plus plus
+@subsubsection @value{GDBN} features for C@t{++}
+
+@cindex commands for C@t{++}
+
+Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
+designed specifically for use with C@t{++}. Here is a summary:
+
+@table @code
+@cindex break in overloaded functions
+@item @r{breakpoint menus}
+When you want a breakpoint in a function whose name is overloaded,
+@value{GDBN} breakpoint menus help you specify which function definition
+you want. @xref{Breakpoint Menus,,Breakpoint menus}.
+
+@cindex overloading in C@t{++}
+@item rbreak @var{regex}
+Setting breakpoints using regular expressions is helpful for setting
+breakpoints on overloaded functions that are not members of any special
+classes.
+@xref{Set Breaks, ,Setting breakpoints}.
+
+@cindex C@t{++} exception handling
+@item catch throw
+@itemx catch catch
+Debug C@t{++} exception handling using these commands. @xref{Set
+Catchpoints, , Setting catchpoints}.
+
+@cindex inheritance
+@item ptype @var{typename}
+Print inheritance relationships as well as other information for type
+@var{typename}.
+@xref{Symbols, ,Examining the Symbol Table}.
+
+@cindex C@t{++} symbol display
+@item set print demangle
+@itemx show print demangle
+@itemx set print asm-demangle
+@itemx show print asm-demangle
+Control whether C@t{++} symbols display in their source form, both when
+displaying code as C@t{++} source and when displaying disassemblies.
+@xref{Print Settings, ,Print settings}.
+
+@item set print object
+@itemx show print object
+Choose whether to print derived (actual) or declared types of objects.
+@xref{Print Settings, ,Print settings}.
+
+@item set print vtbl
+@itemx show print vtbl
+Control the format for printing virtual function tables.
+@xref{Print Settings, ,Print settings}.
+(The @code{vtbl} commands do not work on programs compiled with the HP
+ANSI C@t{++} compiler (@code{aCC}).)
+
+@kindex set overload-resolution
+@cindex overloaded functions, overload resolution
+@item set overload-resolution on
+Enable overload resolution for C@t{++} expression evaluation. The default
+is on. For overloaded functions, @value{GDBN} evaluates the arguments
+and searches for a function whose signature matches the argument types,
+using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++}
+expressions}, for details). If it cannot find a match, it emits a
+message.
+
+@item set overload-resolution off
+Disable overload resolution for C@t{++} expression evaluation. For
+overloaded functions that are not class member functions, @value{GDBN}
+chooses the first function of the specified name that it finds in the
+symbol table, whether or not its arguments are of the correct type. For
+overloaded functions that are class member functions, @value{GDBN}
+searches for a function whose signature @emph{exactly} matches the
+argument types.
+
+@item @r{Overloaded symbol names}
+You can specify a particular definition of an overloaded symbol, using
+the same notation that is used to declare such symbols in C@t{++}: type
+@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
+also use the @value{GDBN} command-line word completion facilities to list the
+available choices, or to finish the type list for you.
+@xref{Completion,, Command completion}, for details on how to do this.
+@end table
+
+@node Modula-2
+@subsection Modula-2
+
+@cindex Modula-2, @value{GDBN} support
+
+The extensions made to @value{GDBN} to support Modula-2 only support
+output from the @sc{gnu} Modula-2 compiler (which is currently being
+developed). Other Modula-2 compilers are not currently supported, and
+attempting to debug executables produced by them is most likely
+to give an error as @value{GDBN} reads in the executable's symbol
+table.
+
+@cindex expressions in Modula-2
+@menu
+* M2 Operators:: Built-in operators
+* Built-In Func/Proc:: Built-in functions and procedures
+* M2 Constants:: Modula-2 constants
+* M2 Defaults:: Default settings for Modula-2
+* Deviations:: Deviations from standard Modula-2
+* M2 Checks:: Modula-2 type and range checks
+* M2 Scope:: The scope operators @code{::} and @code{.}
+* GDB/M2:: @value{GDBN} and Modula-2
+@end menu
+
+@node M2 Operators
+@subsubsection Operators
+@cindex Modula-2 operators
+
+Operators must be defined on values of specific types. For instance,
+@code{+} is defined on numbers, but not on structures. Operators are
+often defined on groups of types. For the purposes of Modula-2, the
+following definitions hold:
+
+@itemize @bullet
+
+@item
+@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
+their subranges.
+
+@item
+@emph{Character types} consist of @code{CHAR} and its subranges.
+
+@item
+@emph{Floating-point types} consist of @code{REAL}.
+
+@item
+@emph{Pointer types} consist of anything declared as @code{POINTER TO
+@var{type}}.
+
+@item
+@emph{Scalar types} consist of all of the above.
+
+@item
+@emph{Set types} consist of @code{SET} and @code{BITSET} types.
+
+@item
+@emph{Boolean types} consist of @code{BOOLEAN}.
+@end itemize
+
+@noindent
+The following operators are supported, and appear in order of
+increasing precedence:
+
+@table @code
+@item ,
+Function argument or array index separator.
+
+@item :=
+Assignment. The value of @var{var} @code{:=} @var{value} is
+@var{value}.
+
+@item <@r{, }>
+Less than, greater than on integral, floating-point, or enumerated
+types.
+
+@item <=@r{, }>=
+Less than or equal to, greater than or equal to
+on integral, floating-point and enumerated types, or set inclusion on
+set types. Same precedence as @code{<}.
+
+@item =@r{, }<>@r{, }#
+Equality and two ways of expressing inequality, valid on scalar types.
+Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
+available for inequality, since @code{#} conflicts with the script
+comment character.
+
+@item IN
+Set membership. Defined on set types and the types of their members.
+Same precedence as @code{<}.
+
+@item OR
+Boolean disjunction. Defined on boolean types.
+
+@item AND@r{, }&
+Boolean conjunction. Defined on boolean types.
+
+@item @@
+The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+
+@item +@r{, }-
+Addition and subtraction on integral and floating-point types, or union
+and difference on set types.
+
+@item *
+Multiplication on integral and floating-point types, or set intersection
+on set types.
+
+@item /
+Division on floating-point types, or symmetric set difference on set
+types. Same precedence as @code{*}.
+
+@item DIV@r{, }MOD
+Integer division and remainder. Defined on integral types. Same
+precedence as @code{*}.
+
+@item -
+Negative. Defined on @code{INTEGER} and @code{REAL} data.
+
+@item ^
+Pointer dereferencing. Defined on pointer types.
+
+@item NOT
+Boolean negation. Defined on boolean types. Same precedence as
+@code{^}.
+
+@item .
+@code{RECORD} field selector. Defined on @code{RECORD} data. Same
+precedence as @code{^}.
+
+@item []
+Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
+
+@item ()
+Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
+as @code{^}.
+
+@item ::@r{, }.
+@value{GDBN} and Modula-2 scope operators.
+@end table
+
+@quotation
+@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN}
+treats the use of the operator @code{IN}, or the use of operators
+@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
+@code{<=}, and @code{>=} on sets as an error.
+@end quotation
+
+
+@node Built-In Func/Proc
+@subsubsection Built-in functions and procedures
+@cindex Modula-2 built-ins
+
+Modula-2 also makes available several built-in procedures and functions.
+In describing these, the following metavariables are used:
+
+@table @var
+
+@item a
+represents an @code{ARRAY} variable.
+
+@item c
+represents a @code{CHAR} constant or variable.
+
+@item i
+represents a variable or constant of integral type.
+
+@item m
+represents an identifier that belongs to a set. Generally used in the
+same function with the metavariable @var{s}. The type of @var{s} should
+be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
+
+@item n
+represents a variable or constant of integral or floating-point type.
+
+@item r
+represents a variable or constant of floating-point type.
+
+@item t
+represents a type.
+
+@item v
+represents a variable.
+
+@item x
+represents a variable or constant of one of many types. See the
+explanation of the function for details.
+@end table
+
+All Modula-2 built-in procedures also return a result, described below.
+
+@table @code
+@item ABS(@var{n})
+Returns the absolute value of @var{n}.
+
+@item CAP(@var{c})
+If @var{c} is a lower case letter, it returns its upper case
+equivalent, otherwise it returns its argument.
+
+@item CHR(@var{i})
+Returns the character whose ordinal value is @var{i}.
+
+@item DEC(@var{v})
+Decrements the value in the variable @var{v} by one. Returns the new value.
+
+@item DEC(@var{v},@var{i})
+Decrements the value in the variable @var{v} by @var{i}. Returns the
+new value.
+
+@item EXCL(@var{m},@var{s})
+Removes the element @var{m} from the set @var{s}. Returns the new
+set.
+
+@item FLOAT(@var{i})
+Returns the floating point equivalent of the integer @var{i}.
+
+@item HIGH(@var{a})
+Returns the index of the last member of @var{a}.
+
+@item INC(@var{v})
+Increments the value in the variable @var{v} by one. Returns the new value.
+
+@item INC(@var{v},@var{i})
+Increments the value in the variable @var{v} by @var{i}. Returns the
+new value.
+
+@item INCL(@var{m},@var{s})
+Adds the element @var{m} to the set @var{s} if it is not already
+there. Returns the new set.
+
+@item MAX(@var{t})
+Returns the maximum value of the type @var{t}.
+
+@item MIN(@var{t})
+Returns the minimum value of the type @var{t}.
+
+@item ODD(@var{i})
+Returns boolean TRUE if @var{i} is an odd number.
+
+@item ORD(@var{x})
+Returns the ordinal value of its argument. For example, the ordinal
+value of a character is its @sc{ascii} value (on machines supporting the
+@sc{ascii} character set). @var{x} must be of an ordered type, which include
+integral, character and enumerated types.
+
+@item SIZE(@var{x})
+Returns the size of its argument. @var{x} can be a variable or a type.
+
+@item TRUNC(@var{r})
+Returns the integral part of @var{r}.
+
+@item VAL(@var{t},@var{i})
+Returns the member of the type @var{t} whose ordinal value is @var{i}.
+@end table
+
+@quotation
+@emph{Warning:} Sets and their operations are not yet supported, so
+@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
+an error.
+@end quotation
+
+@cindex Modula-2 constants
+@node M2 Constants
+@subsubsection Constants
+
+@value{GDBN} allows you to express the constants of Modula-2 in the following
+ways:
+
+@itemize @bullet
+
+@item
+Integer constants are simply a sequence of digits. When used in an
+expression, a constant is interpreted to be type-compatible with the
+rest of the expression. Hexadecimal integers are specified by a
+trailing @samp{H}, and octal integers by a trailing @samp{B}.
+
+@item
+Floating point constants appear as a sequence of digits, followed by a
+decimal point and another sequence of digits. An optional exponent can
+then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
+@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
+digits of the floating point constant must be valid decimal (base 10)
+digits.
+
+@item
+Character constants consist of a single character enclosed by a pair of
+like quotes, either single (@code{'}) or double (@code{"}). They may
+also be expressed by their ordinal value (their @sc{ascii} value, usually)
+followed by a @samp{C}.
+
+@item
+String constants consist of a sequence of characters enclosed by a
+pair of like quotes, either single (@code{'}) or double (@code{"}).
+Escape sequences in the style of C are also allowed. @xref{C
+Constants, ,C and C@t{++} constants}, for a brief explanation of escape
+sequences.
+
+@item
+Enumerated constants consist of an enumerated identifier.
+
+@item
+Boolean constants consist of the identifiers @code{TRUE} and
+@code{FALSE}.
+
+@item
+Pointer constants consist of integral values only.
+
+@item
+Set constants are not yet supported.
+@end itemize
+
+@node M2 Defaults
+@subsubsection Modula-2 defaults
+@cindex Modula-2 defaults
+
+If type and range checking are set automatically by @value{GDBN}, they
+both default to @code{on} whenever the working language changes to
+Modula-2. This happens regardless of whether you or @value{GDBN}
+selected the working language.
+
+If you allow @value{GDBN} to set the language automatically, then entering
+code compiled from a file whose name ends with @file{.mod} sets the
+working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
+the language automatically}, for further details.
+
+@node Deviations
+@subsubsection Deviations from standard Modula-2
+@cindex Modula-2, deviations from
+
+A few changes have been made to make Modula-2 programs easier to debug.
+This is done primarily via loosening its type strictness:
+
+@itemize @bullet
+@item
+Unlike in standard Modula-2, pointer constants can be formed by
+integers. This allows you to modify pointer variables during
+debugging. (In standard Modula-2, the actual address contained in a
+pointer variable is hidden from you; it can only be modified
+through direct assignment to another pointer variable or expression that
+returned a pointer.)
+
+@item
+C escape sequences can be used in strings and characters to represent
+non-printable characters. @value{GDBN} prints out strings with these
+escape sequences embedded. Single non-printable characters are
+printed using the @samp{CHR(@var{nnn})} format.
+
+@item
+The assignment operator (@code{:=}) returns the value of its right-hand
+argument.
+
+@item
+All built-in procedures both modify @emph{and} return their argument.
+@end itemize
+
+@node M2 Checks
+@subsubsection Modula-2 type and range checks
+@cindex Modula-2 checks
+
+@quotation
+@emph{Warning:} in this release, @value{GDBN} does not yet perform type or
+range checking.
+@end quotation
+@c FIXME remove warning when type/range checks added
+
+@value{GDBN} considers two Modula-2 variables type equivalent if:
+
+@itemize @bullet
+@item
+They are of types that have been declared equivalent via a @code{TYPE
+@var{t1} = @var{t2}} statement
+
+@item
+They have been declared on the same line. (Note: This is true of the
+@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
+@end itemize
+
+As long as type checking is enabled, any attempt to combine variables
+whose types are not equivalent is an error.
+
+Range checking is done on all mathematical operations, assignment, array
+index bounds, and all built-in functions and procedures.
+
+@node M2 Scope
+@subsubsection The scope operators @code{::} and @code{.}
+@cindex scope
+@cindex @code{.}, Modula-2 scope operator
+@cindex colon, doubled as scope operator
+@ifinfo
+@vindex colon-colon@r{, in Modula-2}
+@c Info cannot handle :: but TeX can.
+@end ifinfo
+@iftex
+@vindex ::@r{, in Modula-2}
+@end iftex
+
+There are a few subtle differences between the Modula-2 scope operator
+(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
+similar syntax:
+
+@example
+
+@var{module} . @var{id}
+@var{scope} :: @var{id}
+@end example
+
+@noindent
+where @var{scope} is the name of a module or a procedure,
+@var{module} the name of a module, and @var{id} is any declared
+identifier within your program, except another module.
+
+Using the @code{::} operator makes @value{GDBN} search the scope
+specified by @var{scope} for the identifier @var{id}. If it is not
+found in the specified scope, then @value{GDBN} searches all scopes
+enclosing the one specified by @var{scope}.
+
+Using the @code{.} operator makes @value{GDBN} search the current scope for
+the identifier specified by @var{id} that was imported from the
+definition module specified by @var{module}. With this operator, it is
+an error if the identifier @var{id} was not imported from definition
+module @var{module}, or if @var{id} is not an identifier in
+@var{module}.
+
+@node GDB/M2
+@subsubsection @value{GDBN} and Modula-2
+
+Some @value{GDBN} commands have little use when debugging Modula-2 programs.
+Five subcommands of @code{set print} and @code{show print} apply
+specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle},
+@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
+apply to C@t{++}, and the last to the C @code{union} type, which has no direct
+analogue in Modula-2.
+
+The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
+with any language, is not useful with Modula-2. Its
+intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
+created in Modula-2 as they can in C or C@t{++}. However, because an
+address can be specified by an integral constant, the construct
+@samp{@{@var{type}@}@var{adrexp}} is still useful.
+
+@cindex @code{#} in Modula-2
+In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
+interpreted as the beginning of a comment. Use @code{<>} instead.
+
+@node Chill
+@subsection Chill
+
+The extensions made to @value{GDBN} to support Chill only support output
+from the @sc{gnu} Chill compiler. Other Chill compilers are not currently
+supported, and attempting to debug executables produced by them is most
+likely to give an error as @value{GDBN} reads in the executable's symbol
+table.
+
+@c This used to say "... following Chill related topics ...", but since
+@c menus are not shown in the printed manual, it would look awkward.
+This section covers the Chill related topics and the features
+of @value{GDBN} which support these topics.
+
+@menu
+* How modes are displayed:: How modes are displayed
+* Locations:: Locations and their accesses
+* Values and their Operations:: Values and their Operations
+* Chill type and range checks::
+* Chill defaults::
+@end menu
+
+@node How modes are displayed
+@subsubsection How modes are displayed
+
+The Chill Datatype- (Mode) support of @value{GDBN} is directly related
+with the functionality of the @sc{gnu} Chill compiler, and therefore deviates
+slightly from the standard specification of the Chill language. The
+provided modes are:
+
+@c FIXME: this @table's contents effectively disable @code by using @r
+@c on every @item. So why does it need @code?
+@table @code
+@item @r{@emph{Discrete modes:}}
+@itemize @bullet
+@item
+@emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT,
+UINT, LONG, ULONG},
+@item
+@emph{Boolean Mode} which is predefined by @code{BOOL},
+@item
+@emph{Character Mode} which is predefined by @code{CHAR},
+@item
+@emph{Set Mode} which is displayed by the keyword @code{SET}.
+@smallexample
+(@value{GDBP}) ptype x
+type = SET (karli = 10, susi = 20, fritzi = 100)
+@end smallexample
+If the type is an unnumbered set the set element values are omitted.
+@item
+@emph{Range Mode} which is displayed by
+@smallexample
+@code{type = <basemode>(<lower bound> : <upper bound>)}
+@end smallexample
+where @code{<lower bound>, <upper bound>} can be of any discrete literal
+expression (e.g. set element names).
+@end itemize
+
+@item @r{@emph{Powerset Mode:}}
+A Powerset Mode is displayed by the keyword @code{POWERSET} followed by
+the member mode of the powerset. The member mode can be any discrete mode.
+@smallexample
+(@value{GDBP}) ptype x
+type = POWERSET SET (egon, hugo, otto)
+@end smallexample
+
+@item @r{@emph{Reference Modes:}}
+@itemize @bullet
+@item
+@emph{Bound Reference Mode} which is displayed by the keyword @code{REF}
+followed by the mode name to which the reference is bound.
+@item
+@emph{Free Reference Mode} which is displayed by the keyword @code{PTR}.
+@end itemize
+
+@item @r{@emph{Procedure mode}}
+The procedure mode is displayed by @code{type = PROC(<parameter list>)
+<return mode> EXCEPTIONS (<exception list>)}. The @code{<parameter
+list>} is a list of the parameter modes. @code{<return mode>} indicates
+the mode of the result of the procedure if any. The exceptionlist lists
+all possible exceptions which can be raised by the procedure.
+
+@ignore
+@item @r{@emph{Instance mode}}
+The instance mode is represented by a structure, which has a static
+type, and is therefore not really of interest.
+@end ignore
+
+@item @r{@emph{Synchronization Modes:}}
+@itemize @bullet
+@item
+@emph{Event Mode} which is displayed by
+@smallexample
+@code{EVENT (<event length>)}
+@end smallexample
+where @code{(<event length>)} is optional.
+@item
+@emph{Buffer Mode} which is displayed by
+@smallexample
+@code{BUFFER (<buffer length>)<buffer element mode>}
+@end smallexample
+where @code{(<buffer length>)} is optional.
+@end itemize
+
+@item @r{@emph{Timing Modes:}}
+@itemize @bullet
+@item
+@emph{Duration Mode} which is predefined by @code{DURATION}
+@item
+@emph{Absolute Time Mode} which is predefined by @code{TIME}
+@end itemize
+
+@item @r{@emph{Real Modes:}}
+Real Modes are predefined with @code{REAL} and @code{LONG_REAL}.
+
+@item @r{@emph{String Modes:}}
+@itemize @bullet
+@item
+@emph{Character String Mode} which is displayed by
+@smallexample
+@code{CHARS(<string length>)}
+@end smallexample
+followed by the keyword @code{VARYING} if the String Mode is a varying
+mode
+@item
+@emph{Bit String Mode} which is displayed by
+@smallexample
+@code{BOOLS(<string
+length>)}
+@end smallexample
+@end itemize
+
+@item @r{@emph{Array Mode:}}
+The Array Mode is displayed by the keyword @code{ARRAY(<range>)}
+followed by the element mode (which may in turn be an array mode).
+@smallexample
+(@value{GDBP}) ptype x
+type = ARRAY (1:42)
+ ARRAY (1:20)
+ SET (karli = 10, susi = 20, fritzi = 100)
+@end smallexample
+
+@item @r{@emph{Structure Mode}}
+The Structure mode is displayed by the keyword @code{STRUCT(<field
+list>)}. The @code{<field list>} consists of names and modes of fields
+of the structure. Variant structures have the keyword @code{CASE <field>
+OF <variant fields> ESAC} in their field list. Since the current version
+of the GNU Chill compiler doesn't implement tag processing (no runtime
+checks of variant fields, and therefore no debugging info), the output
+always displays all variant fields.
+@smallexample
+(@value{GDBP}) ptype str
+type = STRUCT (
+ as x,
+ bs x,
+ CASE bs OF
+ (karli):
+ cs a
+ (ott):
+ ds x
+ ESAC
+)
+@end smallexample
+@end table
+
+@node Locations
+@subsubsection Locations and their accesses
+
+A location in Chill is an object which can contain values.
+
+A value of a location is generally accessed by the (declared) name of
+the location. The output conforms to the specification of values in
+Chill programs. How values are specified
+is the topic of the next section, @ref{Values and their Operations}.
+
+The pseudo-location @code{RESULT} (or @code{result}) can be used to
+display or change the result of a currently-active procedure:
+
+@smallexample
+set result := EXPR
+@end smallexample
+
+@noindent
+This does the same as the Chill action @code{RESULT EXPR} (which
+is not available in @value{GDBN}).
+
+Values of reference mode locations are printed by @code{PTR(<hex
+value>)} in case of a free reference mode, and by @code{(REF <reference
+mode>) (<hex-value>)} in case of a bound reference. @code{<hex value>}
+represents the address where the reference points to. To access the
+value of the location referenced by the pointer, use the dereference
+operator @samp{->}.
+
+Values of procedure mode locations are displayed by
+@smallexample
+@code{@{ PROC
+(<argument modes> ) <return mode> @} <address> <name of procedure
+location>}
+@end smallexample
+@code{<argument modes>} is a list of modes according to the parameter
+specification of the procedure and @code{<address>} shows the address of
+the entry point.
+
+@ignore
+Locations of instance modes are displayed just like a structure with two
+fields specifying the @emph{process type} and the @emph{copy number} of
+the investigated instance location@footnote{This comes from the current
+implementation of instances. They are implemented as a structure (no
+na). The output should be something like @code{[<name of the process>;
+<instance number>]}.}. The field names are @code{__proc_type} and
+@code{__proc_copy}.
+
+Locations of synchronization modes are displayed like a structure with
+the field name @code{__event_data} in case of a event mode location, and
+like a structure with the field @code{__buffer_data} in case of a buffer
+mode location (refer to previous paragraph).
+
+Structure Mode locations are printed by @code{[.<field name>: <value>,
+...]}. The @code{<field name>} corresponds to the structure mode
+definition and the layout of @code{<value>} varies depending of the mode
+of the field. If the investigated structure mode location is of variant
+structure mode, the variant parts of the structure are enclosed in curled
+braces (@samp{@{@}}). Fields enclosed by @samp{@{,@}} are residing
+on the same memory location and represent the current values of the
+memory location in their specific modes. Since no tag processing is done
+all variants are displayed. A variant field is printed by
+@code{(<variant name>) = .<field name>: <value>}. (who implements the
+stuff ???)
+@smallexample
+(@value{GDBP}) print str1 $4 = [.as: 0, .bs: karli, .<TAG>: { (karli) =
+[.cs: []], (susi) = [.ds: susi]}]
+@end smallexample
+@end ignore
+
+Substructures of string mode-, array mode- or structure mode-values
+(e.g. array slices, fields of structure locations) are accessed using
+certain operations which are described in the next section, @ref{Values
+and their Operations}.
+
+A location value may be interpreted as having a different mode using the
+location conversion. This mode conversion is written as @code{<mode
+name>(<location>)}. The user has to consider that the sizes of the modes
+have to be equal otherwise an error occurs. Furthermore, no range
+checking of the location against the destination mode is performed, and
+therefore the result can be quite confusing.
+
+@smallexample
+(@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX
+@end smallexample
+
+@node Values and their Operations
+@subsubsection Values and their Operations
+
+Values are used to alter locations, to investigate complex structures in
+more detail or to filter relevant information out of a large amount of
+data. There are several (mode dependent) operations defined which enable
+such investigations. These operations are not only applicable to
+constant values but also to locations, which can become quite useful
+when debugging complex structures. During parsing the command line
+(e.g. evaluating an expression) @value{GDBN} treats location names as
+the values behind these locations.
+
+This section describes how values have to be specified and which
+operations are legal to be used with such values.
+
+@table @code
+@item Literal Values
+Literal values are specified in the same manner as in @sc{gnu} Chill programs.
+For detailed specification refer to the @sc{gnu} Chill implementation Manual
+chapter 1.5.
+@c FIXME: if the Chill Manual is a Texinfo documents, the above should
+@c be converted to a @ref.
+
+@ignore
+@itemize @bullet
+@item
+@emph{Integer Literals} are specified in the same manner as in Chill
+programs (refer to the Chill Standard z200/88 chpt 5.2.4.2)
+@item
+@emph{Boolean Literals} are defined by @code{TRUE} and @code{FALSE}.
+@item
+@emph{Character Literals} are defined by @code{'<character>'}. (e.g.
+@code{'M'})
+@item
+@emph{Set Literals} are defined by a name which was specified in a set
+mode. The value delivered by a Set Literal is the set value. This is
+comparable to an enumeration in C/C@t{++} language.
+@item
+@emph{Emptiness Literal} is predefined by @code{NULL}. The value of the
+emptiness literal delivers either the empty reference value, the empty
+procedure value or the empty instance value.
+
+@item
+@emph{Character String Literals} are defined by a sequence of characters
+enclosed in single- or double quotes. If a single- or double quote has
+to be part of the string literal it has to be stuffed (specified twice).
+@item
+@emph{Bitstring Literals} are specified in the same manner as in Chill
+programs (refer z200/88 chpt 5.2.4.8).
+@item
+@emph{Floating point literals} are specified in the same manner as in
+(gnu-)Chill programs (refer @sc{gnu} Chill implementation Manual chapter 1.5).
+@end itemize
+@end ignore
+
+@item Tuple Values
+A tuple is specified by @code{<mode name>[<tuple>]}, where @code{<mode
+name>} can be omitted if the mode of the tuple is unambiguous. This
+unambiguity is derived from the context of a evaluated expression.
+@code{<tuple>} can be one of the following:
+
+@itemize @bullet
+@item @emph{Powerset Tuple}
+@item @emph{Array Tuple}
+@item @emph{Structure Tuple}
+Powerset tuples, array tuples and structure tuples are specified in the
+same manner as in Chill programs refer to z200/88 chpt 5.2.5.
+@end itemize
+
+@item String Element Value
+A string element value is specified by
+@smallexample
+@code{<string value>(<index>)}
+@end smallexample
+where @code{<index>} is a integer expression. It delivers a character
+value which is equivalent to the character indexed by @code{<index>} in
+the string.
+
+@item String Slice Value
+A string slice value is specified by @code{<string value>(<slice
+spec>)}, where @code{<slice spec>} can be either a range of integer
+expressions or specified by @code{<start expr> up <size>}.
+@code{<size>} denotes the number of elements which the slice contains.
+The delivered value is a string value, which is part of the specified
+string.
+
+@item Array Element Values
+An array element value is specified by @code{<array value>(<expr>)} and
+delivers a array element value of the mode of the specified array.
+
+@item Array Slice Values
+An array slice is specified by @code{<array value>(<slice spec>)}, where
+@code{<slice spec>} can be either a range specified by expressions or by
+@code{<start expr> up <size>}. @code{<size>} denotes the number of
+arrayelements the slice contains. The delivered value is an array value
+which is part of the specified array.
+
+@item Structure Field Values
+A structure field value is derived by @code{<structure value>.<field
+name>}, where @code{<field name>} indicates the name of a field specified
+in the mode definition of the structure. The mode of the delivered value
+corresponds to this mode definition in the structure definition.
+
+@item Procedure Call Value
+The procedure call value is derived from the return value of the
+procedure@footnote{If a procedure call is used for instance in an
+expression, then this procedure is called with all its side
+effects. This can lead to confusing results if used carelessly.}.
+
+Values of duration mode locations are represented by @code{ULONG} literals.
+
+Values of time mode locations appear as
+@smallexample
+@code{TIME(<secs>:<nsecs>)}
+@end smallexample
+
+
+@ignore
+This is not implemented yet:
+@item Built-in Value
+@noindent
+The following built in functions are provided:
+
+@table @code
+@item @code{ADDR()}
+@item @code{NUM()}
+@item @code{PRED()}
+@item @code{SUCC()}
+@item @code{ABS()}
+@item @code{CARD()}
+@item @code{MAX()}
+@item @code{MIN()}
+@item @code{SIZE()}
+@item @code{UPPER()}
+@item @code{LOWER()}
+@item @code{LENGTH()}
+@item @code{SIN()}
+@item @code{COS()}
+@item @code{TAN()}
+@item @code{ARCSIN()}
+@item @code{ARCCOS()}
+@item @code{ARCTAN()}
+@item @code{EXP()}
+@item @code{LN()}
+@item @code{LOG()}
+@item @code{SQRT()}
+@end table
+
+For a detailed description refer to the GNU Chill implementation manual
+chapter 1.6.
+@end ignore
+
+@item Zero-adic Operator Value
+The zero-adic operator value is derived from the instance value for the
+current active process.
+
+@item Expression Values
+The value delivered by an expression is the result of the evaluation of
+the specified expression. If there are error conditions (mode
+incompatibility, etc.) the evaluation of expressions is aborted with a
+corresponding error message. Expressions may be parenthesised which
+causes the evaluation of this expression before any other expression
+which uses the result of the parenthesised expression. The following
+operators are supported by @value{GDBN}:
+
+@table @code
+@item @code{OR, ORIF, XOR}
+@itemx @code{AND, ANDIF}
+@itemx @code{NOT}
+Logical operators defined over operands of boolean mode.
+
+@item @code{=, /=}
+Equality and inequality operators defined over all modes.
+
+@item @code{>, >=}
+@itemx @code{<, <=}
+Relational operators defined over predefined modes.
+
+@item @code{+, -}
+@itemx @code{*, /, MOD, REM}
+Arithmetic operators defined over predefined modes.
+
+@item @code{-}
+Change sign operator.
+
+@item @code{//}
+String concatenation operator.
+
+@item @code{()}
+String repetition operator.
+
+@item @code{->}
+Referenced location operator which can be used either to take the
+address of a location (@code{->loc}), or to dereference a reference
+location (@code{loc->}).
+
+@item @code{OR, XOR}
+@itemx @code{AND}
+@itemx @code{NOT}
+Powerset and bitstring operators.
+
+@item @code{>, >=}
+@itemx @code{<, <=}
+Powerset inclusion operators.
+
+@item @code{IN}
+Membership operator.
+@end table
+@end table
+
+@node Chill type and range checks
+@subsubsection Chill type and range checks
+
+@value{GDBN} considers two Chill variables mode equivalent if the sizes
+of the two modes are equal. This rule applies recursively to more
+complex datatypes which means that complex modes are treated
+equivalent if all element modes (which also can be complex modes like
+structures, arrays, etc.) have the same size.
+
+Range checking is done on all mathematical operations, assignment, array
+index bounds and all built in procedures.
+
+Strong type checks are forced using the @value{GDBN} command @code{set
+check strong}. This enforces strong type and range checks on all
+operations where Chill constructs are used (expressions, built in
+functions, etc.) in respect to the semantics as defined in the z.200
+language specification.
+
+All checks can be disabled by the @value{GDBN} command @code{set check
+off}.
+
+@ignore
+@c Deviations from the Chill Standard Z200/88
+see last paragraph ?
+@end ignore
+
+@node Chill defaults
+@subsubsection Chill defaults
+
+If type and range checking are set automatically by @value{GDBN}, they
+both default to @code{on} whenever the working language changes to
+Chill. This happens regardless of whether you or @value{GDBN}
+selected the working language.
+
+If you allow @value{GDBN} to set the language automatically, then entering
+code compiled from a file whose name ends with @file{.ch} sets the
+working language to Chill. @xref{Automatically, ,Having @value{GDBN} set
+the language automatically}, for further details.
+
+@node Symbols
+@chapter Examining the Symbol Table
+
+The commands described in this chapter allow you to inquire about the
+symbols (names of variables, functions and types) defined in your
+program. This information is inherent in the text of your program and
+does not change as your program executes. @value{GDBN} finds it in your
+program's symbol table, in the file indicated when you started @value{GDBN}
+(@pxref{File Options, ,Choosing files}), or by one of the
+file-management commands (@pxref{Files, ,Commands to specify files}).
+
+@cindex symbol names
+@cindex names of symbols
+@cindex quoting names
+Occasionally, you may need to refer to symbols that contain unusual
+characters, which @value{GDBN} ordinarily treats as word delimiters. The
+most frequent case is in referring to static variables in other
+source files (@pxref{Variables,,Program variables}). File names
+are recorded in object files as debugging symbols, but @value{GDBN} would
+ordinarily parse a typical file name, like @file{foo.c}, as the three words
+@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
+@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
+
+@example
+p 'foo.c'::x
+@end example
+
+@noindent
+looks up the value of @code{x} in the scope of the file @file{foo.c}.
+
+@table @code
+@kindex info address
+@cindex address of a symbol
+@item info address @var{symbol}
+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 variable, and for a stack local variable prints
+the exact address of the current instantiation of the variable.
+
+@kindex info symbol
+@cindex symbol from address
+@item info symbol @var{addr}
+Print the name of a symbol which is stored at the address @var{addr}.
+If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
+nearest symbol and an offset from it:
+
+@example
+(@value{GDBP}) info symbol 0x54320
+_initialize_vx + 396 in section .text
+@end example
+
+@noindent
+This is the opposite of the @code{info address} command. You can use
+it to find out the name of a variable or a function given its address.
+
+@kindex whatis
+@item whatis @var{expr}
+Print the data type of expression @var{expr}. @var{expr} is not
+actually evaluated, and any side-effecting operations (such as
+assignments or function calls) inside it do not take place.
+@xref{Expressions, ,Expressions}.
+
+@item whatis
+Print the data type of @code{$}, the last value in the value history.
+
+@kindex ptype
+@item ptype @var{typename}
+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{class
+@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
+@var{union-tag}} or @samp{enum @var{enum-tag}}.
+
+@item ptype @var{expr}
+@itemx ptype
+Print a description of the type of expression @var{expr}. @code{ptype}
+differs from @code{whatis} by printing a detailed description, instead
+of just the name of the type.
+
+For example, for this variable declaration:
+
+@example
+struct complex @{double real; double imag;@} v;
+@end example
+
+@noindent
+the two commands give this output:
+
+@example
+@group
+(@value{GDBP}) whatis v
+type = struct complex
+(@value{GDBP}) ptype v
+type = struct complex @{
+ double real;
+ double imag;
+@}
+@end group
+@end example
+
+@noindent
+As with @code{whatis}, using @code{ptype} without an argument refers to
+the type of @code{$}, the last value in the value history.
+
+@kindex info types
+@item info types @var{regexp}
+@itemx info types
+Print a brief description of all types whose names match @var{regexp}
+(or all types in your program, if you supply no argument). Each
+complete typename is matched as though it were a complete line; thus,
+@samp{i type value} gives information on all types in your program whose
+names include the string @code{value}, but @samp{i type ^value$} gives
+information only on types whose complete name is @code{value}.
+
+This command differs from @code{ptype} in two ways: first, like
+@code{whatis}, it does not print a detailed description; second, it
+lists all source files where a type is defined.
+
+@kindex info scope
+@cindex local variables
+@item info scope @var{addr}
+List all the variables local to a particular scope. This command
+accepts a location---a function name, a source line, or an address
+preceded by a @samp{*}, and prints all the variables local to the
+scope defined by that location. For example:
+
+@smallexample
+(@value{GDBP}) @b{info scope command_line_handler}
+Scope for command_line_handler:
+Symbol rl is an argument at stack/frame offset 8, length 4.
+Symbol linebuffer is in static storage at address 0x150a18, length 4.
+Symbol linelength is in static storage at address 0x150a1c, length 4.
+Symbol p is a local variable in register $esi, length 4.
+Symbol p1 is a local variable in register $ebx, length 4.
+Symbol nline is a local variable in register $edx, length 4.
+Symbol repeat is a local variable at frame offset -8, length 4.
+@end smallexample
+
+@noindent
+This command is especially useful for determining what data to collect
+during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
+collect}.
+
+@kindex info source
+@item info source
+Show the name of the current source file---that is, the source file for
+the function containing the current point of execution---and the language
+it was written in.
+
+@kindex info sources
+@item info sources
+Print the names of all source files in your program for which there is
+debugging information, organized into two lists: files whose symbols
+have already been read, and files whose symbols will be read when needed.
+
+@kindex info functions
+@item 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 @code{step}; @samp{info fun ^step} finds those whose names
+start with @code{step}. If a function name contains characters
+that conflict with the regular expression language (eg.
+@samp{operator*()}), they may be quoted with a backslash.
+
+@kindex info variables
+@item info variables
+Print the names and data types of all variables that are declared
+outside of functions (i.e., excluding local variables).
+
+@item info variables @var{regexp}
+Print the names and data types of all variables (except for local
+variables) whose names contain a match for regular expression
+@var{regexp}.
+
+@ignore
+This was never implemented.
+@kindex info methods
+@item info methods
+@itemx info methods @var{regexp}
+The @code{info methods} command permits the user to examine all defined
+methods within C@t{++} program, or (with the @var{regexp} argument) a
+specific set of methods found in the various C@t{++} classes. Many
+C@t{++} classes provide a large number of methods. Thus, the output
+from the @code{ptype} command can be overwhelming and hard to use. The
+@code{info-methods} command filters the methods, printing only those
+which match the regular-expression @var{regexp}.
+@end ignore
+
+@cindex reloading symbols
+Some systems allow individual object files that make up your program to
+be replaced without stopping and restarting your program. For example,
+in VxWorks you can simply recompile a defective object file and keep on
+running. If you are running on one of these systems, you can allow
+@value{GDBN} to reload the symbols for automatically relinked modules:
+
+@table @code
+@kindex set symbol-reloading
+@item set symbol-reloading on
+Replace symbol definitions for the corresponding source file when an
+object file with a particular name is seen again.
+
+@item set symbol-reloading off
+Do not replace symbol definitions when encountering object files of the
+same name more than once. This is the default state; if you are not
+running on a system that permits automatic relinking of modules, you
+should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
+may discard symbols when linking large programs, that may contain
+several modules (from different directories or libraries) with the same
+name.
+
+@kindex show symbol-reloading
+@item show symbol-reloading
+Show the current @code{on} or @code{off} setting.
+@end table
+
+@kindex set opaque-type-resolution
+@item set opaque-type-resolution on
+Tell @value{GDBN} to resolve opaque types. An opaque type is a type
+declared as a pointer to a @code{struct}, @code{class}, or
+@code{union}---for example, @code{struct MyType *}---that is used in one
+source file although the full declaration of @code{struct MyType} is in
+another source file. The default is on.
+
+A change in the setting of this subcommand will not take effect until
+the next time symbols for a file are loaded.
+
+@item set opaque-type-resolution off
+Tell @value{GDBN} not to resolve opaque types. In this case, the type
+is printed as follows:
+@smallexample
+@{<no data fields>@}
+@end smallexample
+
+@kindex show opaque-type-resolution
+@item show opaque-type-resolution
+Show whether opaque types are resolved or not.
+
+@kindex maint print symbols
+@cindex symbol dump
+@kindex maint print psymbols
+@cindex partial symbol dump
+@item maint print symbols @var{filename}
+@itemx maint print psymbols @var{filename}
+@itemx maint print msymbols @var{filename}
+Write a dump of debugging symbol data into the file @var{filename}.
+These commands are used to debug the @value{GDBN} symbol-reading code. Only
+symbols with debugging data are included. If you use @samp{maint print
+symbols}, @value{GDBN} includes all the symbols for which it has already
+collected full details: that is, @var{filename} reflects symbols for
+only those files whose symbols @value{GDBN} has read. You can use the
+command @code{info sources} to find out which files these are. If you
+use @samp{maint print psymbols} instead, the dump shows information about
+symbols that @value{GDBN} only knows partially---that is, symbols defined in
+files that @value{GDBN} has skimmed, but not yet read completely. Finally,
+@samp{maint print msymbols} dumps just the minimal symbol information
+required for each object file from which @value{GDBN} has read some symbols.
+@xref{Files, ,Commands to specify files}, for a discussion of how
+@value{GDBN} reads symbols (in the description of @code{symbol-file}).
+@end table
+
+@node Altering
+@chapter Altering Execution
+
+Once you think you have found an error in your program, you might want to
+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 @value{GDBN} features for altering execution of the
+program.
+
+For example, you can store new values into variables or memory
+locations, give your program a signal, restart it at a different
+address, or even return prematurely from a function.
+
+@menu
+* Assignment:: Assignment to variables
+* Jumping:: Continuing at a different address
+* Signaling:: Giving your program a signal
+* Returning:: Returning from a function
+* Calling:: Calling your program's functions
+* Patching:: Patching your program
+@end menu
+
+@node Assignment
+@section Assignment to variables
+
+@cindex assignment
+@cindex setting variables
+To alter the value of a variable, evaluate an assignment expression.
+@xref{Expressions, ,Expressions}. For example,
+
+@example
+print x=4
+@end example
+
+@noindent
+stores the value 4 into the variable @code{x}, and then prints the
+value of the assignment expression (which is 4).
+@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
+information on operators in supported languages.
+
+@kindex set variable
+@cindex variables, setting
+If you are not interested in seeing the value of the assignment, use the
+@code{set} command instead of the @code{print} command. @code{set} is
+really the same as @code{print} except that the expression's value is
+not printed and is not put in the value history (@pxref{Value History,
+,Value history}). The expression is evaluated only for its effects.
+
+If the beginning of the argument string of the @code{set} command
+appears identical to a @code{set} subcommand, use the @code{set
+variable} command instead of just @code{set}. This command is identical
+to @code{set} except for its lack of subcommands. For example, if your
+program has a variable @code{width}, you get an error if you try to set
+a new value with just @samp{set width=13}, because @value{GDBN} has the
+command @code{set width}:
+
+@example
+(@value{GDBP}) whatis width
+type = double
+(@value{GDBP}) p width
+$4 = 13
+(@value{GDBP}) set width=47
+Invalid syntax in expression.
+@end example
+
+@noindent
+The invalid expression, of course, is @samp{=47}. In
+order to actually set the program's variable @code{width}, use
+
+@example
+(@value{GDBP}) set var width=47
+@end example
+
+Because the @code{set} command has many subcommands that can conflict
+with the names of program variables, it is a good idea to use the
+@code{set variable} command instead of just @code{set}. For example, if
+your program has a variable @code{g}, you run into problems if you try
+to set a new value with just @samp{set g=4}, because @value{GDBN} has
+the command @code{set gnutarget}, abbreviated @code{set g}:
+
+@example
+@group
+(@value{GDBP}) whatis g
+type = double
+(@value{GDBP}) p g
+$1 = 1
+(@value{GDBP}) set g=4
+(@value{GDBP}) p g
+$2 = 1
+(@value{GDBP}) r
+The program being debugged has been started already.
+Start it from the beginning? (y or n) y
+Starting program: /home/smith/cc_progs/a.out
+"/home/smith/cc_progs/a.out": can't open to read symbols:
+ Invalid bfd target.
+(@value{GDBP}) show g
+The current BFD target is "=4".
+@end group
+@end example
+
+@noindent
+The program variable @code{g} did not change, and you silently set the
+@code{gnutarget} to an invalid value. In order to set the variable
+@code{g}, use
+
+@example
+(@value{GDBP}) set var g=4
+@end example
+
+@value{GDBN} allows more implicit conversions in assignments than C; you can
+freely store an integer value into a pointer variable or vice versa,
+and you can convert any structure to any other structure that is the
+same length or shorter.
+@comment FIXME: how do structs align/pad in these conversions?
+@comment /doc@cygnus.com 18dec1990
+
+To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
+construct to generate a value of specified type at a specified address
+(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
+to memory location @code{0x83040} as an integer (which implies a certain size
+and representation in memory), and
+
+@example
+set @{int@}0x83040 = 4
+@end example
+
+@noindent
+stores the value 4 into that memory location.
+
+@node Jumping
+@section Continuing at a different address
+
+Ordinarily, when you continue your program, you do so at the place where
+it stopped, with the @code{continue} command. You can instead continue at
+an address of your own choosing, with the following commands:
+
+@table @code
+@kindex jump
+@item jump @var{linespec}
+Resume execution at line @var{linespec}. Execution stops again
+immediately if there is a breakpoint there. @xref{List, ,Printing
+source lines}, for a description of the different forms of
+@var{linespec}. It is common practice to use the @code{tbreak} command
+in conjunction with @code{jump}. @xref{Set Breaks, ,Setting
+breakpoints}.
+
+The @code{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{linespec} is in
+a different function from the one currently executing, the results may
+be bizarre if the two functions expect different patterns of arguments or
+of local variables. For this reason, the @code{jump} command requests
+confirmation if the specified line is not in the function currently
+executing. However, even bizarre results are predictable if you are
+well acquainted with the machine-language code of your program.
+
+@item jump *@var{address}
+Resume execution at the instruction at address @var{address}.
+@end table
+
+@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
+On many systems, 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 your program running; it only
+changes the address of where it @emph{will} run when you continue. For
+example,
+
+@example
+set $pc = 0x485
+@end example
+
+@noindent
+makes the next @code{continue} command or stepping command execute at
+address @code{0x485}, rather than at the address where your program stopped.
+@xref{Continuing and Stepping, ,Continuing and stepping}.
+
+The most common occasion to use the @code{jump} command is to back
+up---perhaps with more breakpoints set---over a portion of a program
+that has already executed, in order to examine its execution in more
+detail.
+
+@c @group
+@node Signaling
+@section Giving your program a signal
+
+@table @code
+@kindex signal
+@item signal @var{signal}
+Resume execution where your program stopped, but immediately give it the
+signal @var{signal}. @var{signal} can be the name or the number of a
+signal. For example, on many systems @code{signal 2} and @code{signal
+SIGINT} are both ways of sending an interrupt signal.
+
+Alternatively, if @var{signal} is zero, continue execution without
+giving a signal. This is useful when your program stopped on account of
+a signal and would ordinary see the signal when resumed with the
+@code{continue} command; @samp{signal 0} causes it to resume without a
+signal.
+
+@code{signal} does not repeat when you press @key{RET} a second time
+after executing the command.
+@end table
+@c @end group
+
+Invoking the @code{signal} command is not the same as invoking the
+@code{kill} utility from the shell. Sending a signal with @code{kill}
+causes @value{GDBN} to decide what to do with the signal depending on
+the signal handling tables (@pxref{Signals}). The @code{signal} command
+passes the signal directly to your program.
+
+
+@node Returning
+@section Returning from a function
+
+@table @code
+@cindex returning from a function
+@kindex return
+@item return
+@itemx return @var{expression}
+You can cancel execution of a function call with the @code{return}
+command. If you give an
+@var{expression} argument, its value is used as the function's return
+value.
+@end table
+
+When you use @code{return}, @value{GDBN} discards the selected stack frame
+(and all frames within it). You can think of this as making the
+discarded frame return prematurely. If you wish to specify a value to
+be returned, give that value as the argument to @code{return}.
+
+This pops the selected stack frame (@pxref{Selection, ,Selecting a
+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.
+
+The @code{return} command does not resume execution; it leaves the
+program stopped in the state that would exist if the function had just
+returned. In contrast, the @code{finish} command (@pxref{Continuing
+and Stepping, ,Continuing and stepping}) resumes execution until the
+selected stack frame returns naturally.
+
+@node Calling
+@section Calling program functions
+
+@cindex calling functions
+@kindex call
+@table @code
+@item call @var{expr}
+Evaluate the expression @var{expr} without displaying @code{void}
+returned values.
+@end table
+
+You can use this variant of the @code{print} command if you want to
+execute a function from your program, but without cluttering the output
+with @code{void} returned values. If the result is not void, it
+is printed and saved in the value history.
+
+@c OBSOLETE For the A29K, a user-controlled variable @code{call_scratch_address},
+@c OBSOLETE specifies the location of a scratch area to be used when @value{GDBN}
+@c OBSOLETE calls a function in the target. This is necessary because the usual
+@c OBSOLETE method of putting the scratch area on the stack does not work in systems
+@c OBSOLETE that have separate instruction and data spaces.
+
+@node Patching
+@section Patching programs
+
+@cindex patching binaries
+@cindex writing into executables
+@cindex writing into corefiles
+
+By default, @value{GDBN} opens the file containing your program's
+executable code (or the corefile) read-only. This prevents accidental
+alterations to machine code; but it also prevents you from intentionally
+patching your program's binary.
+
+If you'd like to be able to patch the binary, you can specify that
+explicitly with the @code{set write} command. For example, you might
+want to turn on internal debugging flags, or even to make emergency
+repairs.
+
+@table @code
+@kindex set write
+@item set write on
+@itemx set write off
+If you specify @samp{set write on}, @value{GDBN} opens executable and
+core files for both reading and writing; if you specify @samp{set write
+off} (the default), @value{GDBN} opens them read-only.
+
+If you have already loaded a file, you must load it again (using the
+@code{exec-file} or @code{core-file} command) after changing @code{set
+write}, for your new setting to take effect.
+
+@item show write
+@kindex show write
+Display whether executable files and core files are opened for writing
+as well as reading.
+@end table
+
+@node GDB Files
+@chapter @value{GDBN} Files
+
+@value{GDBN} 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 your
+program. To debug a core dump of a previous run, you must also tell
+@value{GDBN} the name of the core dump file.
+
+@menu
+* Files:: Commands to specify files
+* Symbol Errors:: Errors reading symbol files
+@end menu
+
+@node Files
+@section Commands to specify files
+
+@cindex symbol table
+@cindex core dump file
+
+You may want to specify executable and core dump file names. The usual
+way to do this is at start-up time, using the arguments to
+@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and
+Out of @value{GDBN}}).
+
+Occasionally it is necessary to change to a different file during a
+@value{GDBN} session. Or you may run @value{GDBN} and forget to specify
+a file you want to use. In these situations the @value{GDBN} commands
+to specify new files are useful.
+
+@table @code
+@cindex executable file
+@kindex file
+@item file @var{filename}
+Use @var{filename} as the program to be debugged. It is read for its
+symbols and for the contents of pure memory. It is also the program
+executed when you use the @code{run} command. If you do not specify a
+directory and the file is not found in the @value{GDBN} working directory,
+@value{GDBN} uses the environment variable @code{PATH} as a list of
+directories to search, just as the shell does when looking for a program
+to run. You can change the value of this variable, for both @value{GDBN}
+and your program, using the @code{path} command.
+
+On systems with memory-mapped files, an auxiliary file named
+@file{@var{filename}.syms} may hold symbol table information for
+@var{filename}. If so, @value{GDBN} maps in the symbol table from
+@file{@var{filename}.syms}, starting up more quickly. See the
+descriptions of the file options @samp{-mapped} and @samp{-readnow}
+(available on the command line, and with the commands @code{file},
+@code{symbol-file}, or @code{add-symbol-file}, described below),
+for more information.
+
+@item file
+@code{file} with no argument makes @value{GDBN} discard any information it
+has on both executable file and the symbol table.
+
+@kindex exec-file
+@item exec-file @r{[} @var{filename} @r{]}
+Specify that the program to be run (but not the symbol table) is found
+in @var{filename}. @value{GDBN} searches the environment variable @code{PATH}
+if necessary to locate your program. Omitting @var{filename} means to
+discard information on the executable file.
+
+@kindex symbol-file
+@item symbol-file @r{[} @var{filename} @r{]}
+Read symbol table information from file @var{filename}. @code{PATH} is
+searched when necessary. Use the @code{file} command to get both symbol
+table and program to run from the same file.
+
+@code{symbol-file} with no argument clears out @value{GDBN} information on your
+program's symbol table.
+
+The @code{symbol-file} command causes @value{GDBN} 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 @value{GDBN}.
+
+@code{symbol-file} does not repeat if you press @key{RET} again after
+executing it once.
+
+When @value{GDBN} is configured for a particular environment, it
+understands debugging information in whatever format is the standard
+generated for that environment; you may use either a @sc{gnu} compiler, or
+other compilers that adhere to the local conventions.
+Best results are usually obtained from @sc{gnu} compilers; for example,
+using @code{@value{GCC}} you can generate debugging information for
+optimized code.
+
+For most kinds of object files, with the exception of old SVR3 systems
+using COFF, the @code{symbol-file} command does not normally 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, as they are needed.
+
+The purpose of this two-stage reading strategy is to make @value{GDBN}
+start up 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 @code{set verbose} command can turn these
+pauses into messages if desired. @xref{Messages/Warnings, ,Optional
+warnings and messages}.)
+
+We have not implemented the two-stage strategy for COFF yet. When the
+symbol table is stored in COFF format, @code{symbol-file} reads the
+symbol table data in full right away. Note that ``stabs-in-COFF''
+still does the two-stage strategy, since the debug info is actually
+in stabs format.
+
+@kindex readnow
+@cindex reading symbols immediately
+@cindex symbols, reading immediately
+@kindex mapped
+@cindex memory-mapped symbol file
+@cindex saving symbol table
+@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+You can override the @value{GDBN} two-stage strategy for reading symbol
+tables by using the @samp{-readnow} option with any of the commands that
+load symbol table information, if you want to be sure @value{GDBN} has the
+entire symbol table available.
+
+If memory-mapped files are available on your system through the
+@code{mmap} system call, you can use another option, @samp{-mapped}, to
+cause @value{GDBN} to write the symbols for your program into a reusable
+file. Future @value{GDBN} debugging sessions map in symbol information
+from this auxiliary symbol file (if the program has not changed), rather
+than spending time reading the symbol table from the executable
+program. Using the @samp{-mapped} option has the same effect as
+starting @value{GDBN} with the @samp{-mapped} command-line option.
+
+You can use both options together, to make sure the auxiliary symbol
+file has all the symbol information for your program.
+
+The auxiliary symbol file for a program called @var{myprog} is called
+@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
+than the corresponding executable), @value{GDBN} always attempts to use
+it when you debug @var{myprog}; no special options or commands are
+needed.
+
+The @file{.syms} file is specific to the host machine where you run
+@value{GDBN}. It holds an exact image of the internal @value{GDBN}
+symbol table. It cannot be shared across multiple host platforms.
+
+@c FIXME: for now no mention of directories, since this seems to be in
+@c flux. 13mar1992 status is that in theory GDB would look either in
+@c current dir or in same dir as myprog; but issues like competing
+@c GDB's, or clutter in system dirs, mean that in practice right now
+@c only current dir is used. FFish says maybe a special GDB hierarchy
+@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
+@c files.
+
+@kindex core
+@kindex core-file
+@item core-file @r{[} @var{filename} @r{]}
+Specify the whereabouts of a core dump file to be used as the ``contents
+of memory''. Traditionally, core files contain only some parts of the
+address space of the process that generated them; @value{GDBN} can access the
+executable file itself for other parts.
+
+@code{core-file} with no argument specifies that no core file is
+to be used.
+
+Note that the core file is ignored when your program is actually running
+under @value{GDBN}. So, if you have been running your 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 @code{kill} command
+(@pxref{Kill Process, ,Killing the child process}).
+
+@kindex add-symbol-file
+@cindex dynamic linking
+@item add-symbol-file @var{filename} @var{address}
+@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
+The @code{add-symbol-file} command reads additional symbol table
+information from the file @var{filename}. You would use this command
+when @var{filename} has been dynamically loaded (by some other means)
+into the program that is running. @var{address} should be the memory
+address at which the file has been loaded; @value{GDBN} cannot figure
+this out for itself. You can additionally specify an arbitrary number
+of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit
+section name and base address for that section. You can specify any
+@var{address} as an expression.
+
+The symbol table of the file @var{filename} is added to the symbol table
+originally read with the @code{symbol-file} command. You can use the
+@code{add-symbol-file} command any number of times; the new symbol data
+thus read keeps adding to the old. To discard all old symbol data
+instead, use the @code{symbol-file} command without any arguments.
+
+@cindex relocatable object files, reading symbols from
+@cindex object files, relocatable, reading symbols from
+@cindex reading symbols from relocatable object files
+@cindex symbols, reading from relocatable object files
+@cindex @file{.o} files, reading symbols from
+Although @var{filename} is typically a shared library file, an
+executable file, or some other object file which has been fully
+relocated for loading into a process, you can also load symbolic
+information from relocatable @file{.o} files, as long as:
+
+@itemize @bullet
+@item
+the file's symbolic information refers only to linker symbols defined in
+that file, not to symbols defined by other object files,
+@item
+every section the file's symbolic information refers to has actually
+been loaded into the inferior, as it appears in the file, and
+@item
+you can determine the address at which every section was loaded, and
+provide these to the @code{add-symbol-file} command.
+@end itemize
+
+@noindent
+Some embedded operating systems, like Sun Chorus and VxWorks, can load
+relocatable files into an already running program; such systems
+typically make the requirements above easy to meet. However, it's
+important to recognize that many native systems use complex link
+procedures (@code{.linkonce} section factoring and C++ constructor table
+assembly, for example) that make the requirements difficult to meet. In
+general, one cannot assume that using @code{add-symbol-file} to read a
+relocatable object file's symbolic information will have the same effect
+as linking the relocatable object file into the program in the normal
+way.
+
+@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+
+You can use the @samp{-mapped} and @samp{-readnow} options just as with
+the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
+table information for @var{filename}.
+
+@kindex add-shared-symbol-file
+@item add-shared-symbol-file
+The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
+operating system for the Motorola 88k. @value{GDBN} automatically looks for
+shared libraries, however if @value{GDBN} does not find yours, you can run
+@code{add-shared-symbol-file}. It takes no arguments.
+
+@kindex section
+@item section
+The @code{section} command changes the base address of section SECTION of
+the exec file to ADDR. This can be used if the exec file does not contain
+section addresses, (such as in the a.out format), or when the addresses
+specified in the file itself are wrong. Each section must be changed
+separately. The @code{info files} command, described below, lists all
+the sections and their addresses.
+
+@kindex info files
+@kindex info target
+@item info files
+@itemx info target
+@code{info files} and @code{info target} are synonymous; both print the
+current target (@pxref{Targets, ,Specifying a Debugging Target}),
+including the names of the executable and core dump files currently in
+use by @value{GDBN}, and the files from which symbols were loaded. The
+command @code{help target} lists all possible targets rather than
+current ones.
+
+@kindex maint info sections
+@item maint info sections
+Another command that can give you extra information about program sections
+is @code{maint info sections}. In addition to the section information
+displayed by @code{info files}, this command displays the flags and file
+offset of each section in the executable and core dump files. In addition,
+@code{maint info sections} provides the following command options (which
+may be arbitrarily combined):
+
+@table @code
+@item ALLOBJ
+Display sections for all loaded object files, including shared libraries.
+@item @var{sections}
+Display info only for named @var{sections}.
+@item @var{section-flags}
+Display info only for sections for which @var{section-flags} are true.
+The section flags that @value{GDBN} currently knows about are:
+@table @code
+@item ALLOC
+Section will have space allocated in the process when loaded.
+Set for all sections except those containing debug information.
+@item LOAD
+Section will be loaded from the file into the child process memory.
+Set for pre-initialized code and data, clear for @code{.bss} sections.
+@item RELOC
+Section needs to be relocated before loading.
+@item READONLY
+Section cannot be modified by the child process.
+@item CODE
+Section contains executable code only.
+@item DATA
+Section contains data only (no executable code).
+@item ROM
+Section will reside in ROM.
+@item CONSTRUCTOR
+Section contains data for constructor/destructor lists.
+@item HAS_CONTENTS
+Section is not empty.
+@item NEVER_LOAD
+An instruction to the linker to not output the section.
+@item COFF_SHARED_LIBRARY
+A notification to the linker that the section contains
+COFF shared library information.
+@item IS_COMMON
+Section contains common symbols.
+@end table
+@end table
+@end table
+
+All file-specifying commands allow both absolute and relative file names
+as arguments. @value{GDBN} always converts the file name to an absolute file
+name and remembers it that way.
+
+@cindex shared libraries
+@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
+libraries.
+
+@value{GDBN} automatically loads symbol definitions from shared libraries
+when you use the @code{run} command, or when you examine a core file.
+(Before you issue the @code{run} command, @value{GDBN} does not understand
+references to a function in a shared library, however---unless you are
+debugging a core file).
+
+On HP-UX, if the program loads a library explicitly, @value{GDBN}
+automatically loads the symbols at the time of the @code{shl_load} call.
+
+@c FIXME: some @value{GDBN} release may permit some refs to undef
+@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
+@c FIXME...lib; check this from time to time when updating manual
+
+There are times, however, when you may wish to not automatically load
+symbol definitions from shared libraries, such as when they are
+particularly large or there are many of them.
+
+To control the automatic loading of shared library symbols, use the
+commands:
+
+@table @code
+@kindex set auto-solib-add
+@item set auto-solib-add @var{mode}
+If @var{mode} is @code{on}, symbols from all shared object libraries
+will be loaded automatically when the inferior begins execution, you
+attach to an independently started inferior, or when the dynamic linker
+informs @value{GDBN} that a new library has been loaded. If @var{mode}
+is @code{off}, symbols must be loaded manually, using the
+@code{sharedlibrary} command. The default value is @code{on}.
+
+@kindex show auto-solib-add
+@item show auto-solib-add
+Display the current autoloading mode.
+@end table
+
+To explicitly load shared library symbols, use the @code{sharedlibrary}
+command:
+
+@table @code
+@kindex info sharedlibrary
+@kindex info share
+@item info share
+@itemx info sharedlibrary
+Print the names of the shared libraries which are currently loaded.
+
+@kindex sharedlibrary
+@kindex share
+@item sharedlibrary @var{regex}
+@itemx share @var{regex}
+Load shared object library symbols for files matching a
+Unix regular expression.
+As with files loaded automatically, it only loads shared libraries
+required by your program for a core file or after typing @code{run}. If
+@var{regex} is omitted all shared libraries required by your program are
+loaded.
+@end table
+
+On some systems, such as HP-UX systems, @value{GDBN} supports
+autoloading shared library symbols until a limiting threshold size is
+reached. This provides the benefit of allowing autoloading to remain on
+by default, but avoids autoloading excessively large shared libraries,
+up to a threshold that is initially set, but which you can modify if you
+wish.
+
+Beyond that threshold, symbols from shared libraries must be explicitly
+loaded. To load these symbols, use the command @code{sharedlibrary
+@var{filename}}. The base address of the shared library is determined
+automatically by @value{GDBN} and need not be specified.
+
+To display or set the threshold, use the commands:
+
+@table @code
+@kindex set auto-solib-limit
+@item set auto-solib-limit @var{threshold}
+Set the autoloading size threshold, in an integral number of megabytes.
+If @var{threshold} is nonzero and shared library autoloading is enabled,
+symbols from all shared object libraries will be loaded until the total
+size of the loaded shared library symbols exceeds this threshold.
+Otherwise, symbols must be loaded manually, using the
+@code{sharedlibrary} command. The default threshold is 100 (i.e. 100
+Mb).
+
+@kindex show auto-solib-limit
+@item show auto-solib-limit
+Display the current autoloading size threshold, in megabytes.
+@end table
+
+@node Symbol Errors
+@section Errors reading symbol files
+
+While reading a symbol file, @value{GDBN} occasionally encounters problems,
+such as symbol types it does not recognize, or known bugs in compiler
+output. By default, @value{GDBN} does not notify you of such problems, since
+they are relatively common and primarily of interest to people
+debugging compilers. If you are interested in seeing information
+about ill-constructed symbol tables, you can either ask @value{GDBN} to print
+only one message about each such type of problem, no matter how many
+times the problem occurs; or you can ask @value{GDBN} to print more messages,
+to see how many times the problems occur, with the @code{set
+complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
+messages}).
+
+The messages currently printed, and their meanings, include:
+
+@table @code
+@item inner block not inside outer block in @var{symbol}
+
+The symbol information shows where symbol scopes begin and end
+(such as at the start of a function or a block of statements). This
+error indicates that an inner scope block is not fully contained
+in its outer scope blocks.
+
+@value{GDBN} circumvents the problem by treating the inner block as if it had
+the same scope as the outer block. In the error message, @var{symbol}
+may be shown as ``@code{(don't know)}'' if the outer block is not a
+function.
+
+@item block at @var{address} out of order
+
+The symbol information for symbol scope blocks should occur in
+order of increasing addresses. This error indicates that it does not
+do so.
+
+@value{GDBN} does not circumvent this problem, and has trouble
+locating symbols in the source file whose symbols it is reading. (You
+can often determine what source file is affected by specifying
+@code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and
+messages}.)
+
+@item bad block start address patched
+
+The symbol information for a symbol scope block has a start address
+smaller than the address of the preceding source line. This is known
+to occur in the SunOS 4.1.1 (and earlier) C compiler.
+
+@value{GDBN} circumvents the problem by treating the symbol scope block as
+starting on the previous source line.
+
+@item bad string table offset in symbol @var{n}
+
+@cindex foo
+Symbol number @var{n} contains a pointer into the string table which is
+larger than the size of the string table.
+
+@value{GDBN} circumvents the problem by considering the symbol to have the
+name @code{foo}, which may cause other problems if many symbols end up
+with this name.
+
+@item unknown symbol type @code{0x@var{nn}}
+
+The symbol information contains new data types that @value{GDBN} does
+not yet know how to read. @code{0x@var{nn}} is the symbol type of the
+uncomprehended information, in hexadecimal.
+
+@value{GDBN} circumvents the error by ignoring this symbol information.
+This usually allows you to debug your program, though certain symbols
+are not accessible. If you encounter such a problem and feel like
+debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
+on @code{complain}, then go up to the function @code{read_dbx_symtab}
+and examine @code{*bufp} to see the symbol.
+
+@item stub type has NULL name
+
+@value{GDBN} could not find the full definition for a struct or class.
+
+@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
+The symbol information for a C@t{++} member function is missing some
+information that recent versions of the compiler should have output for
+it.
+
+@item info mismatch between compiler and debugger
+
+@value{GDBN} could not parse a type specification output by the compiler.
+
+@end table
+
+@node Targets
+@chapter Specifying a Debugging Target
+
+@cindex debugging target
+@kindex target
+
+A @dfn{target} is the execution environment occupied by your program.
+
+Often, @value{GDBN} runs in the same host environment as your program;
+in that case, the debugging target is specified as a side effect when
+you use the @code{file} or @code{core} commands. When you need more
+flexibility---for example, running @value{GDBN} on a physically separate
+host, or controlling a standalone system over a serial port or a
+realtime system over a TCP/IP connection---you can use the @code{target}
+command to specify one of the target types configured for @value{GDBN}
+(@pxref{Target Commands, ,Commands for managing targets}).
+
+@menu
+* Active Targets:: Active targets
+* Target Commands:: Commands for managing targets
+* Byte Order:: Choosing target byte order
+* Remote:: Remote debugging
+* KOD:: Kernel Object Display
+
+@end menu
+
+@node Active Targets
+@section Active targets
+
+@cindex stacking targets
+@cindex active targets
+@cindex multiple targets
+
+There are three classes of targets: processes, core files, and
+executable files. @value{GDBN} can work concurrently on up to three
+active targets, one in each class. This allows you to (for example)
+start a process and inspect its activity without abandoning your work on
+a core file.
+
+For example, if you execute @samp{gdb a.out}, then the executable file
+@code{a.out} is the only active target. If you designate a core file as
+well---presumably from a prior run that crashed and coredumped---then
+@value{GDBN} has two active targets and uses them in tandem, looking
+first in the corefile target, then in the executable file, to satisfy
+requests for memory addresses. (Typically, these two classes of target
+are complementary, since core files contain only a program's
+read-write memory---variables and so on---plus machine status, while
+executable files contain only the program text and initialized data.)
+
+When you type @code{run}, your executable file becomes an active process
+target as well. When a process target is active, all @value{GDBN}
+commands requesting memory addresses refer to that target; addresses in
+an active core file or executable file target are obscured while the
+process target is active.
+
+Use the @code{core-file} and @code{exec-file} commands to select a new
+core file or executable target (@pxref{Files, ,Commands to specify
+files}). To specify as a target a process that is already running, use
+the @code{attach} command (@pxref{Attach, ,Debugging an already-running
+process}).
+
+@node Target Commands
+@section Commands for managing targets
+
+@table @code
+@item target @var{type} @var{parameters}
+Connects the @value{GDBN} 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.
+
+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.
+
+The @code{target} command does not repeat if you press @key{RET} again
+after executing the command.
+
+@kindex help target
+@item help target
+Displays the names of all targets available. To display targets
+currently selected, use either @code{info target} or @code{info files}
+(@pxref{Files, ,Commands to specify files}).
+
+@item help target @var{name}
+Describe a particular target, including any parameters necessary to
+select it.
+
+@kindex set gnutarget
+@item set gnutarget @var{args}
+@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
+knows whether it is reading an @dfn{executable},
+a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
+with the @code{set gnutarget} command. Unlike most @code{target} commands,
+with @code{gnutarget} the @code{target} refers to a program, not a machine.
+
+@quotation
+@emph{Warning:} To specify a file format with @code{set gnutarget},
+you must know the actual BFD name.
+@end quotation
+
+@noindent
+@xref{Files, , Commands to specify files}.
+
+@kindex show gnutarget
+@item show gnutarget
+Use the @code{show gnutarget} command to display what file format
+@code{gnutarget} is set to read. If you have not set @code{gnutarget},
+@value{GDBN} will determine the file format for each file automatically,
+and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
+@end table
-@item
-@emph{Character types} consist of @code{CHAR} and its subranges.
+Here are some common targets (available, or not, depending on the GDB
+configuration):
-@item
-@emph{Floating-point types} consist of @code{REAL}.
+@table @code
+@kindex target exec
+@item target exec @var{program}
+An executable file. @samp{target exec @var{program}} is the same as
+@samp{exec-file @var{program}}.
-@item
-@emph{Pointer types} consist of anything declared as @code{POINTER TO
-@var{type}}.
+@kindex target core
+@item target core @var{filename}
+A core dump file. @samp{target core @var{filename}} is the same as
+@samp{core-file @var{filename}}.
-@item
-@emph{Scalar types} consist of all of the above.
+@kindex target remote
+@item target remote @var{dev}
+Remote serial target in GDB-specific protocol. The argument @var{dev}
+specifies what serial device to use for the connection (e.g.
+@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote}
+supports the @code{load} command. This is only useful if you have
+some other way of getting the stub to the target system, and you can put
+it somewhere in memory where it won't get clobbered by the download.
-@item
-@emph{Set types} consist of @code{SET} and @code{BITSET} types.
+@kindex target sim
+@item target sim
+Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
+In general,
+@example
+ target sim
+ load
+ run
+@end example
+@noindent
+works; however, you cannot assume that a specific memory map, device
+drivers, or even basic I/O is available, although some simulators do
+provide these. For info about any processor-specific simulator details,
+see the appropriate section in @ref{Embedded Processors, ,Embedded
+Processors}.
-@item
-@emph{Boolean types} consist of @code{BOOLEAN}.
-@end itemize
+@end table
-@noindent
-The following operators are supported, and appear in order of
-increasing precedence:
+Some configurations may include these targets as well:
@table @code
-@item ,
-Function argument or array index separator.
-@item :=
-Assignment. The value of @var{var} @code{:=} @var{value} is
-@var{value}.
+@kindex target nrom
+@item target nrom @var{dev}
+NetROM ROM emulator. This target only supports downloading.
-@item <@r{, }>
-Less than, greater than on integral, floating-point, or enumerated
-types.
+@end table
-@item <=@r{, }>=
-Less than, greater than, less than or equal to, greater than or equal to
-on integral, floating-point and enumerated types, or set inclusion on
-set types. Same precedence as @code{<}.
+Different targets are available on different configurations of @value{GDBN};
+your configuration may have more or fewer targets.
-@item =@r{, }<>@r{, }#
-Equality and two ways of expressing inequality, valid on scalar types.
-Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
-available for inequality, since @code{#} conflicts with the script
-comment character.
+Many remote targets require you to download the executable's code
+once you've successfully established a connection.
-@item IN
-Set membership. Defined on set types and the types of their members.
-Same precedence as @code{<}.
+@table @code
-@item OR
-Boolean disjunction. Defined on boolean types.
+@kindex load @var{filename}
+@item load @var{filename}
+Depending on what remote debugging facilities are configured into
+@value{GDBN}, the @code{load} command may be available. Where it exists, it
+is meant to make @var{filename} (an executable) available for debugging
+on the remote system---by downloading, or dynamic linking, for example.
+@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
+the @code{add-symbol-file} command.
-@item AND@r{, }&
-Boolean conjuction. Defined on boolean types.
+If your @value{GDBN} does not have a @code{load} command, attempting to
+execute it gets the error message ``@code{You can't do that when your
+target is @dots{}}''
-@item @@
-The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+The file is loaded at whatever address is specified in the executable.
+For some object file formats, you can specify the load address when you
+link the program; for other formats, like a.out, the object file format
+specifies a fixed address.
+@c FIXME! This would be a good place for an xref to the GNU linker doc.
-@item +@r{, }-
-Addition and subtraction on integral and floating-point types, or union
-and difference on set types.
+@code{load} does not repeat if you press @key{RET} again after using it.
+@end table
-@item *
-Multiplication on integral and floating-point types, or set intersection
-on set types.
+@node Byte Order
+@section Choosing target byte order
-@item /
-Division on floating-point types, or symmetric set difference on set
-types. Same precedence as @code{*}.
+@cindex choosing target byte order
+@cindex target byte order
-@item DIV@r{, }MOD
-Integer division and remainder. Defined on integral types. Same
-precedence as @code{*}.
+Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
+offer the ability to run either big-endian or little-endian byte
+orders. Usually the executable or symbol will include a bit to
+designate the endian-ness, and you will not need to worry about
+which to use. However, you may still find it useful to adjust
+@value{GDBN}'s idea of processor endian-ness manually.
-@item -
-Negative. Defined on @code{INTEGER} and @code{REAL} data.
+@table @code
+@kindex set endian big
+@item set endian big
+Instruct @value{GDBN} to assume the target is big-endian.
-@item ^
-Pointer dereferencing. Defined on pointer types.
+@kindex set endian little
+@item set endian little
+Instruct @value{GDBN} to assume the target is little-endian.
-@item NOT
-Boolean negation. Defined on boolean types. Same precedence as
-@code{^}.
+@kindex set endian auto
+@item set endian auto
+Instruct @value{GDBN} to use the byte order associated with the
+executable.
-@item .
-@code{RECORD} field selector. Defined on @code{RECORD} data. Same
-precedence as @code{^}.
+@item show endian
+Display @value{GDBN}'s current idea of the target byte order.
-@item []
-Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
+@end table
-@item ()
-Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
-as @code{^}.
+Note that these commands merely adjust interpretation of symbolic
+data on the host, and that they have absolutely no effect on the
+target system.
-@item ::@r{, }.
-@value{GDBN} and Modula-2 scope operators.
-@end table
+@node Remote
+@section Remote debugging
+@cindex remote debugging
-@quotation
-@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN}
-treats the use of the operator @code{IN}, or the use of operators
-@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
-@code{<=}, and @code{>=} on sets as an error.
-@end quotation
+If you are trying to debug a program running on a machine that cannot run
+@value{GDBN} in the usual way, it is often useful to use remote debugging.
+For example, you might use remote debugging on an operating system kernel,
+or on a small system which does not have a general purpose operating system
+powerful enough to run a full-featured debugger.
-@cindex Modula-2 built-ins
-@node Built-In Func/Proc, M2 Constants, M2 Operators, Modula-2
-@subsubsection Built-in functions and procedures
+Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
+to make this work with particular debugging targets. In addition,
+@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
+but not specific to any particular target system) which you can use if you
+write the remote stubs---the code that runs on the remote system to
+communicate with @value{GDBN}.
-Modula-2 also makes available several built-in procedures and functions.
-In describing these, the following metavariables are used:
+Other remote targets may be available in your
+configuration of @value{GDBN}; use @code{help target} to list them.
-@table @var
+@node KOD
+@section Kernel Object Display
-@item a
-represents an @code{ARRAY} variable.
+@cindex kernel object display
+@cindex kernel object
+@cindex KOD
-@item c
-represents a @code{CHAR} constant or variable.
+Some targets support kernel object display. Using this facility,
+@value{GDBN} communicates specially with the underlying operating system
+and can display information about operating system-level objects such as
+mutexes and other synchronization objects. Exactly which objects can be
+displayed is determined on a per-OS basis.
-@item i
-represents a variable or constant of integral type.
+Use the @code{set os} command to set the operating system. This tells
+@value{GDBN} which kernel object display module to initialize:
-@item m
-represents an identifier that belongs to a set. Generally used in the
-same function with the metavariable @var{s}. The type of @var{s} should
-be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
+@example
+(@value{GDBP}) set os cisco
+@end example
-@item n
-represents a variable or constant of integral or floating-point type.
+If @code{set os} succeeds, @value{GDBN} will display some information
+about the operating system, and will create a new @code{info} command
+which can be used to query the target. The @code{info} command is named
+after the operating system:
-@item r
-represents a variable or constant of floating-point type.
+@example
+(@value{GDBP}) info cisco
+List of Cisco Kernel Objects
+Object Description
+any Any and all objects
+@end example
-@item t
-represents a type.
+Further subcommands can be used to query about particular objects known
+by the kernel.
-@item v
-represents a variable.
+There is currently no way to determine whether a given operating system
+is supported other than to try it.
-@item x
-represents a variable or constant of one of many types. See the
-explanation of the function for details.
-@end table
-All Modula-2 built-in procedures also return a result, described below.
+@node Remote Debugging
+@chapter Debugging remote programs
-@table @code
-@item ABS(@var{n})
-Returns the absolute value of @var{n}.
+@menu
+* Server:: Using the gdbserver program
+* NetWare:: Using the gdbserve.nlm program
+* remote stub:: Implementing a remote stub
+@end menu
-@item CAP(@var{c})
-If @var{c} is a lower case letter, it returns its upper case
-equivalent, otherwise it returns its argument
+@node Server
+@section Using the @code{gdbserver} program
+
+@kindex gdbserver
+@cindex remote connection without stubs
+@code{gdbserver} is a control program for Unix-like systems, which
+allows you to connect your program with a remote @value{GDBN} via
+@code{target remote}---but without linking in the usual debugging stub.
+
+@code{gdbserver} is not a complete replacement for the debugging stubs,
+because it requires essentially the same operating-system facilities
+that @value{GDBN} itself does. In fact, a system that can run
+@code{gdbserver} to connect to a remote @value{GDBN} could also run
+@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
+because it is a much smaller program than @value{GDBN} itself. It is
+also easier to port than all of @value{GDBN}, so you may be able to get
+started more quickly on a new system by using @code{gdbserver}.
+Finally, if you develop code for real-time systems, you may find that
+the tradeoffs involved in real-time operation make it more convenient to
+do as much development work as possible on another system, for example
+by cross-compiling. You can use @code{gdbserver} to make a similar
+choice for debugging.
+
+@value{GDBN} and @code{gdbserver} communicate via either a serial line
+or a TCP connection, using the standard @value{GDBN} remote serial
+protocol.
-@item CHR(@var{i})
-Returns the character whose ordinal value is @var{i}.
+@table @emph
+@item On the target machine,
+you need to have a copy of the program you want to debug.
+@code{gdbserver} does not need your program's symbol table, so you can
+strip the program if necessary to save space. @value{GDBN} on the host
+system does all the symbol handling.
-@item DEC(@var{v})
-Decrements the value in the variable @var{v}. Returns the new value.
+To use the server, you must tell it how to communicate with @value{GDBN};
+the name of your program; and the arguments for your program. The
+syntax is:
-@item DEC(@var{v},@var{i})
-Decrements the value in the variable @var{v} by @var{i}. Returns the
-new value.
+@smallexample
+target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
+@end smallexample
-@item EXCL(@var{m},@var{s})
-Removes the element @var{m} from the set @var{s}. Returns the new
-set.
+@var{comm} is either a device name (to use a serial line) or a TCP
+hostname and portnumber. For example, to debug Emacs with the argument
+@samp{foo.txt} and communicate with @value{GDBN} over the serial port
+@file{/dev/com1}:
-@item FLOAT(@var{i})
-Returns the floating point equivalent of the integer @var{i}.
+@smallexample
+target> gdbserver /dev/com1 emacs foo.txt
+@end smallexample
-@item HIGH(@var{a})
-Returns the index of the last member of @var{a}.
+@code{gdbserver} waits passively for the host @value{GDBN} to communicate
+with it.
-@item INC(@var{v})
-Increments the value in the variable @var{v}. Returns the new value.
+To use a TCP connection instead of a serial line:
-@item INC(@var{v},@var{i})
-Increments the value in the variable @var{v} by @var{i}. Returns the
-new value.
+@smallexample
+target> gdbserver host:2345 emacs foo.txt
+@end smallexample
-@item INCL(@var{m},@var{s})
-Adds the element @var{m} to the set @var{s} if it is not already
-there. Returns the new set.
+The only difference from the previous example is the first argument,
+specifying that you are communicating with the host @value{GDBN} via
+TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
+expect a TCP connection from machine @samp{host} to local TCP port 2345.
+(Currently, the @samp{host} part is ignored.) You can choose any number
+you want for the port number as long as it does not conflict with any
+TCP ports already in use on the target system (for example, @code{23} is
+reserved for @code{telnet}).@footnote{If you choose a port number that
+conflicts with another service, @code{gdbserver} prints an error message
+and exits.} You must use the same port number with the host @value{GDBN}
+@code{target remote} command.
+
+@item On the @value{GDBN} host machine,
+you need an unstripped copy of your program, since @value{GDBN} needs
+symbols and debugging information. Start up @value{GDBN} as usual,
+using the name of the local copy of your program as the first argument.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600@dmn{bps}.) After that, use @code{target
+remote} to establish communications with @code{gdbserver}. Its argument
+is either a device name (usually a serial device, like
+@file{/dev/ttyb}), or a TCP port descriptor in the form
+@code{@var{host}:@var{PORT}}. For example:
-@item MAX(@var{t})
-Returns the maximum value of the type @var{t}.
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
-@item MIN(@var{t})
-Returns the minimum value of the type @var{t}.
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and
-@item ODD(@var{i})
-Returns boolean TRUE if @var{i} is an odd number.
+@smallexample
+(@value{GDBP}) target remote the-target:2345
+@end smallexample
-@item ORD(@var{x})
-Returns the ordinal value of its argument. For example, the ordinal
-value of a character is its ASCII value (on machines supporting the
-ASCII character set). @var{x} must be of an ordered type, which include
-integral, character and enumerated types.
+@noindent
+communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
+For TCP connections, you must start up @code{gdbserver} prior to using
+the @code{target remote} command. Otherwise you may get an error whose
+text depends on the host system, but which usually looks something like
+@samp{Connection refused}.
+@end table
-@item SIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+@node NetWare
+@section Using the @code{gdbserve.nlm} program
-@item TRUNC(@var{r})
-Returns the integral part of @var{r}.
+@kindex gdbserve.nlm
+@code{gdbserve.nlm} is a control program for NetWare systems, which
+allows you to connect your program with a remote @value{GDBN} via
+@code{target remote}.
-@item VAL(@var{t},@var{i})
-Returns the member of the type @var{t} whose ordinal value is @var{i}.
-@end table
+@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
+using the standard @value{GDBN} remote serial protocol.
+
+@table @emph
+@item On the target machine,
+you need to have a copy of the program you want to debug.
+@code{gdbserve.nlm} does not need your program's symbol table, so you
+can strip the program if necessary to save space. @value{GDBN} on the
+host system does all the symbol handling.
-@quotation
-@emph{Warning:} Sets and their operations are not yet supported, so
-@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
-an error.
-@end quotation
+To use the server, you must tell it how to communicate with
+@value{GDBN}; the name of your program; and the arguments for your
+program. The syntax is:
-@cindex Modula-2 constants
-@node M2 Constants, M2 Defaults, Built-In Func/Proc, Modula-2
-@subsubsection Constants
+@smallexample
+load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
+ [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
+@end smallexample
-@value{GDBN} allows you to express the constants of Modula-2 in the following
-ways:
+@var{board} and @var{port} specify the serial line; @var{baud} specifies
+the baud rate used by the connection. @var{port} and @var{node} default
+to 0, @var{baud} defaults to 9600@dmn{bps}.
-@itemize @bullet
+For example, to debug Emacs with the argument @samp{foo.txt}and
+communicate with @value{GDBN} over serial port number 2 or board 1
+using a 19200@dmn{bps} connection:
-@item
-Integer constants are simply a sequence of digits. When used in an
-expression, a constant is interpreted to be type-compatible with the
-rest of the expression. Hexadecimal integers are specified by a
-trailing @samp{H}, and octal integers by a trailing @samp{B}.
+@smallexample
+load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
+@end smallexample
-@item
-Floating point constants appear as a sequence of digits, followed by a
-decimal point and another sequence of digits. An optional exponent can
-then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
-@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
-digits of the floating point constant must be valid decimal (base 10)
-digits.
+@item On the @value{GDBN} host machine,
+you need an unstripped copy of your program, since @value{GDBN} needs
+symbols and debugging information. Start up @value{GDBN} as usual,
+using the name of the local copy of your program as the first argument.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600@dmn{bps}. After that, use @code{target
+remote} to establish communications with @code{gdbserve.nlm}. Its
+argument is a device name (usually a serial device, like
+@file{/dev/ttyb}). For example:
-@item
-Character constants consist of a single character enclosed by a pair of
-like quotes, either single (@code{'}) or double (@code{"}). They may
-also be expressed by their ordinal value (their ASCII value, usually)
-followed by a @samp{C}.
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
-@item
-String constants consist of a sequence of characters enclosed by a
-pair of like quotes, either single (@code{'}) or double (@code{"}).
-Escape sequences in the style of C are also allowed. @xref{C
-Constants, ,C and C++ constants}, for a brief explanation of escape
-sequences.
+@noindent
+communications with the server via serial line @file{/dev/ttyb}.
+@end table
-@item
-Enumerated constants consist of an enumerated identifier.
+@node remote stub
+@section Implementing a remote stub
+
+@cindex debugging stub, example
+@cindex remote stub, example
+@cindex stub example, remote debugging
+The stub files provided with @value{GDBN} implement the target side of the
+communication protocol, and the @value{GDBN} side is implemented in the
+@value{GDBN} source file @file{remote.c}. Normally, you can simply allow
+these subroutines to communicate, and ignore the details. (If you're
+implementing your own stub file, you can still ignore the details: start
+with one of the existing stub files. @file{sparc-stub.c} is the best
+organized, and therefore the easiest to read.)
+
+@cindex remote serial debugging, overview
+To debug a program running on another machine (the debugging
+@dfn{target} machine), you must first arrange for all the usual
+prerequisites for the program to run by itself. For example, for a C
+program, you need:
+@enumerate
@item
-Boolean constants consist of the identifiers @code{TRUE} and
-@code{FALSE}.
+A startup routine to set up the C runtime environment; these usually
+have a name like @file{crt0}. The startup routine may be supplied by
+your hardware supplier, or you may have to write your own.
@item
-Pointer constants consist of integral values only.
+A C subroutine library to support your program's
+subroutine calls, notably managing input and output.
@item
-Set constants are not yet supported.
-@end itemize
+A way of getting your program to the other machine---for example, a
+download program. These are often supplied by the hardware
+manufacturer, but you may have to write your own from hardware
+documentation.
+@end enumerate
-@node M2 Defaults, Deviations, M2 Constants, Modula-2
-@subsubsection Modula-2 defaults
-@cindex Modula-2 defaults
+The next step is to arrange for your program to use a serial port to
+communicate with the machine where @value{GDBN} is running (the @dfn{host}
+machine). In general terms, the scheme looks like this:
-If type and range checking are set automatically by @value{GDBN}, they
-both default to @code{on} whenever the working language changes to
-Modula-2. This happens regardless of whether you, or @value{GDBN},
-selected the working language.
+@table @emph
+@item On the host,
+@value{GDBN} already understands how to use this protocol; when everything
+else is set up, you can simply use the @samp{target remote} command
+(@pxref{Targets,,Specifying a Debugging Target}).
+
+@item On the target,
+you must link with your program a few special-purpose subroutines that
+implement the @value{GDBN} remote serial protocol. The file containing these
+subroutines is called a @dfn{debugging stub}.
+
+On certain remote targets, you can use an auxiliary program
+@code{gdbserver} instead of linking a stub into your program.
+@xref{Server,,Using the @code{gdbserver} program}, for details.
+@end table
-If you allow @value{GDBN} to set the language automatically, then entering
-code compiled from a file whose name ends with @file{.mod} sets the
-working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
-the language automatically}, for further details.
+The debugging stub is specific to the architecture of the remote
+machine; for example, use @file{sparc-stub.c} to debug programs on
+@sc{sparc} boards.
-@node Deviations, M2 Checks, M2 Defaults, Modula-2
-@subsubsection Deviations from standard Modula-2
-@cindex Modula-2, deviations from
+@cindex remote serial stub list
+These working remote stubs are distributed with @value{GDBN}:
-A few changes have been made to make Modula-2 programs easier to debug.
-This is done primarily via loosening its type strictness:
+@table @code
-@itemize @bullet
-@item
-Unlike in standard Modula-2, pointer constants can be formed by
-integers. This allows you to modify pointer variables during
-debugging. (In standard Modula-2, the actual address contained in a
-pointer variable is hidden from you; it can only be modified
-through direct assignment to another pointer variable or expression that
-returned a pointer.)
+@item i386-stub.c
+@cindex @file{i386-stub.c}
+@cindex Intel
+@cindex i386
+For Intel 386 and compatible architectures.
+
+@item m68k-stub.c
+@cindex @file{m68k-stub.c}
+@cindex Motorola 680x0
+@cindex m680x0
+For Motorola 680x0 architectures.
+
+@item sh-stub.c
+@cindex @file{sh-stub.c}
+@cindex Hitachi
+@cindex SH
+For Hitachi SH architectures.
+
+@item sparc-stub.c
+@cindex @file{sparc-stub.c}
+@cindex Sparc
+For @sc{sparc} architectures.
+
+@item sparcl-stub.c
+@cindex @file{sparcl-stub.c}
+@cindex Fujitsu
+@cindex SparcLite
+For Fujitsu @sc{sparclite} architectures.
-@item
-C escape sequences can be used in strings and characters to represent
-non-printable characters. @value{GDBN} prints out strings with these
-escape sequences embedded. Single non-printable characters are
-printed using the @samp{CHR(@var{nnn})} format.
+@end table
-@item
-The assignment operator (@code{:=}) returns the value of its right-hand
-argument.
+The @file{README} file in the @value{GDBN} distribution may list other
+recently added stubs.
-@item
-All built-in procedures both modify @emph{and} return their argument.
-@end itemize
+@menu
+* Stub Contents:: What the stub can do for you
+* Bootstrapping:: What you must do for the stub
+* Debug Session:: Putting it all together
+@end menu
-@node M2 Checks, M2 Scope, Deviations, Modula-2
-@subsubsection Modula-2 type and range checks
-@cindex Modula-2 checks
+@node Stub Contents
+@subsection What the stub can do for you
-@quotation
-@emph{Warning:} in this release, @value{GDBN} does not yet perform type or
-range checking.
-@end quotation
-@c FIXME remove warning when type/range checks added
+@cindex remote serial stub
+The debugging stub for your architecture supplies these three
+subroutines:
-@value{GDBN} considers two Modula-2 variables type equivalent if:
+@table @code
+@item set_debug_traps
+@kindex set_debug_traps
+@cindex remote serial stub, initialization
+This routine arranges for @code{handle_exception} to run when your
+program stops. You must call this subroutine explicitly near the
+beginning of your program.
+
+@item handle_exception
+@kindex handle_exception
+@cindex remote serial stub, main routine
+This is the central workhorse, but your program never calls it
+explicitly---the setup code arranges for @code{handle_exception} to
+run when a trap is triggered.
+
+@code{handle_exception} takes control when your program stops during
+execution (for example, on a breakpoint), and mediates communications
+with @value{GDBN} on the host machine. This is where the communications
+protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
+representative on the target machine. It begins by sending summary
+information on the state of your program, then continues to execute,
+retrieving and transmitting any information @value{GDBN} needs, until you
+execute a @value{GDBN} command that makes your program resume; at that point,
+@code{handle_exception} returns control to your own code on the target
+machine.
-@itemize @bullet
-@item
-They are of types that have been declared equivalent via a @code{TYPE
-@var{t1} = @var{t2}} statement
+@item breakpoint
+@cindex @code{breakpoint} subroutine, remote
+Use this auxiliary subroutine to make your program contain a
+breakpoint. Depending on the particular situation, this may be the only
+way for @value{GDBN} to get control. For instance, if your target
+machine has some sort of interrupt button, you won't need to call this;
+pressing the interrupt button transfers control to
+@code{handle_exception}---in effect, to @value{GDBN}. On some machines,
+simply receiving characters on the serial port may also trigger a trap;
+again, in that situation, you don't need to call @code{breakpoint} from
+your own program---simply running @samp{target remote} from the host
+@value{GDBN} session gets control.
+
+Call @code{breakpoint} if none of these is true, or if you simply want
+to make certain your program stops at a predetermined point for the
+start of your debugging session.
+@end table
-@item
-They have been declared on the same line. (Note: This is true of the
-@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
-@end itemize
+@node Bootstrapping
+@subsection What you must do for the stub
-As long as type checking is enabled, any attempt to combine variables
-whose types are not equivalent is an error.
+@cindex remote stub, support routines
+The debugging stubs that come with @value{GDBN} are set up for a particular
+chip architecture, but they have no information about the rest of your
+debugging target machine.
-Range checking is done on all mathematical operations, assignment, array
-index bounds, and all built-in functions and procedures.
+First of all you need to tell the stub how to communicate with the
+serial port.
-@node M2 Scope, GDB/M2, M2 Checks, Modula-2
-@subsubsection The scope operators @code{::} and @code{.}
-@cindex scope
-@kindex .
-@cindex colon, doubled as scope operator
-@ifinfo
-@kindex colon-colon
-@c Info cannot handle :: but TeX can.
-@end ifinfo
-@iftex
-@kindex ::
-@end iftex
+@table @code
+@item int getDebugChar()
+@kindex getDebugChar
+Write this subroutine to read a single character from the serial port.
+It may be identical to @code{getchar} for your target system; a
+different name is used to allow you to distinguish the two if you wish.
+
+@item void putDebugChar(int)
+@kindex putDebugChar
+Write this subroutine to write a single character to the serial port.
+It may be identical to @code{putchar} for your target system; a
+different name is used to allow you to distinguish the two if you wish.
+@end table
-There are a few subtle differences between the Modula-2 scope operator
-(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
-similar syntax:
+@cindex control C, and remote debugging
+@cindex interrupting remote targets
+If you want @value{GDBN} to be able to stop your program while it is
+running, you need to use an interrupt-driven serial driver, and arrange
+for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
+character). That is the character which @value{GDBN} uses to tell the
+remote system to stop.
-@example
+Getting the debugging target to return the proper status to @value{GDBN}
+probably requires changes to the standard stub; one quick and dirty way
+is to just execute a breakpoint instruction (the ``dirty'' part is that
+@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
-@var{module} . @var{id}
-@var{scope} :: @var{id}
-@end example
+Other routines you need to supply are:
+
+@table @code
+@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
+@kindex exceptionHandler
+Write this function to install @var{exception_address} in the exception
+handling tables. You need to do this because the stub does not have any
+way of knowing what the exception handling tables on your target system
+are like (for example, the processor's table might be in @sc{rom},
+containing entries which point to a table in @sc{ram}).
+@var{exception_number} is the exception number which should be changed;
+its meaning is architecture-dependent (for example, different numbers
+might represent divide by zero, misaligned access, etc). When this
+exception occurs, control should be transferred directly to
+@var{exception_address}, and the processor state (stack, registers,
+and so on) should be just as it is when a processor exception occurs. So if
+you want to use a jump instruction to reach @var{exception_address}, it
+should be a simple jump, not a jump to subroutine.
+
+For the 386, @var{exception_address} should be installed as an interrupt
+gate so that interrupts are masked while the handler runs. The gate
+should be at privilege level 0 (the most privileged level). The
+@sc{sparc} and 68k stubs are able to mask interrupts themselves without
+help from @code{exceptionHandler}.
+
+@item void flush_i_cache()
+@kindex flush_i_cache
+On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
+instruction cache, if any, on your target machine. If there is no
+instruction cache, this subroutine may be a no-op.
+
+On target machines that have instruction caches, @value{GDBN} requires this
+function to make certain that the state of your program is stable.
+@end table
@noindent
-where @var{scope} is the name of a module or a procedure,
-@var{module} the name of a module, and @var{id} is any declared
-identifier within your program, except another module.
+You must also make sure this library routine is available:
-Using the @code{::} operator makes @value{GDBN} search the scope
-specified by @var{scope} for the identifier @var{id}. If it is not
-found in the specified scope, then @value{GDBN} searches all scopes
-enclosing the one specified by @var{scope}.
+@table @code
+@item void *memset(void *, int, int)
+@kindex memset
+This is the standard library function @code{memset} that sets an area of
+memory to a known value. If you have one of the free versions of
+@code{libc.a}, @code{memset} can be found there; otherwise, you must
+either obtain it from your hardware manufacturer, or write your own.
+@end table
-Using the @code{.} operator makes @value{GDBN} search the current scope for
-the identifier specified by @var{id} that was imported from the
-definition module specified by @var{module}. With this operator, it is
-an error if the identifier @var{id} was not imported from definition
-module @var{module}, or if @var{id} is not an identifier in
-@var{module}.
+If you do not use the GNU C compiler, you may need other standard
+library subroutines as well; this varies from one stub to another,
+but in general the stubs are likely to use any of the common library
+subroutines which @code{@value{GCC}} generates as inline code.
-@node GDB/M2, , M2 Scope, Modula-2
-@subsubsection @value{GDBN} and Modula-2
-Some @value{GDBN} commands have little use when debugging Modula-2 programs.
-Five subcommands of @code{set print} and @code{show print} apply
-specifically to C and C++: @samp{vtbl}, @samp{demangle},
-@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
-apply to C++, and the last to the C @code{union} type, which has no direct
-analogue in Modula-2.
+@node Debug Session
+@subsection Putting it all together
-The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
-while using any language, is not useful with Modula-2. Its
-intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
-created in Modula-2 as they can in C or C++. However, because an
-address can be specified by an integral constant, the construct
-@samp{@{@var{type}@}@var{adrexp}} is still useful. (@pxref{Expressions, ,Expressions})
+@cindex remote serial debugging summary
+In summary, when your program is ready to debug, you must follow these
+steps.
-@cindex @code{#} in Modula-2
-In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
-interpreted as the beginning of a comment. Use @code{<>} instead.
+@enumerate
+@item
+Make sure you have defined the supporting low-level routines
+(@pxref{Bootstrapping,,What you must do for the stub}):
+@display
+@code{getDebugChar}, @code{putDebugChar},
+@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
+@end display
-@node Symbols, Altering, Languages, Top
-@chapter Examining the Symbol Table
+@item
+Insert these lines near the top of your program:
-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 inherent in the text of your program and
-does not change as your program executes. @value{GDBN} finds it in your
-program's symbol table, in the file indicated when you started @value{GDBN}
-(@pxref{File Options, ,Choosing files}), or by one of the
-file-management commands (@pxref{Files, ,Commands to specify files}).
+@example
+set_debug_traps();
+breakpoint();
+@end example
-@cindex symbol names
-@cindex names of symbols
-@cindex quoting names
-Occasionally, you may need to refer to symbols that contain unusual
-characters, which @value{GDBN} ordinarily treats as word delimiters. The
-most frequent case is in referring to static variables in other
-source files (@pxref{Variables,,Program variables}). File names
-are recorded in object files as debugging symbols, but @value{GDBN} would
-ordinarily parse a typical file name, like @file{foo.c}, as the three words
-@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
-@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
+@item
+For the 680x0 stub only, you need to provide a variable called
+@code{exceptionHook}. Normally you just use:
@example
-p 'foo.c'::x
+void (*exceptionHook)() = 0;
@end example
@noindent
-looks up the value of @code{x} in the scope of the file @file{foo.c}.
+but if before calling @code{set_debug_traps}, you set it to point to a
+function in your program, that function is called when
+@code{@value{GDBN}} continues after stopping on a trap (for example, bus
+error). The function indicated by @code{exceptionHook} is called with
+one parameter: an @code{int} which is the exception number.
-@table @code
-@kindex info address
-@item info address @var{symbol}
-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.
+@item
+Compile and link together: your program, the @value{GDBN} debugging stub for
+your target architecture, and the supporting subroutines.
-Note the contrast with @samp{print &@var{symbol}}, which does not work
-at all for a register variable, and for a stack local variable prints
-the exact address of the current instantiation of the variable.
+@item
+Make sure you have a serial connection between your target machine and
+the @value{GDBN} host, and identify the serial port on the host.
-@kindex whatis
-@item whatis @var{exp}
-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, ,Expressions}.
+@item
+@c The "remote" target now provides a `load' command, so we should
+@c document that. FIXME.
+Download your program to your target machine (or get it there by
+whatever means the manufacturer provides), and start it.
-@item whatis
-Print the data type of @code{$}, the last value in the value history.
+@item
+To start remote debugging, run @value{GDBN} on the host machine, and specify
+as an executable file the program that is running in the remote machine.
+This tells @value{GDBN} how to find your program's symbols and the contents
+of its pure text.
-@kindex ptype
-@item ptype @var{typename}
-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{class
-@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
-@var{union-tag}} or @samp{enum @var{enum-tag}}.
+@item
+@cindex serial line, @code{target remote}
+Establish communication using the @code{target remote} command.
+Its argument specifies how to communicate with the target
+machine---either via a devicename attached to a direct serial line, or a
+TCP port (usually to a terminal server which in turn has a serial line
+to the target). For example, to use a serial line connected to the
+device named @file{/dev/ttyb}:
-@item ptype @var{exp}
-@itemx ptype
-Print a description of the type of expression @var{exp}. @code{ptype}
-differs from @code{whatis} by printing a detailed description, instead
-of just the name of the type.
+@example
+target remote /dev/ttyb
+@end example
-For example, for this variable declaration:
+@cindex TCP port, @code{target remote}
+To use a TCP connection, use an argument of the form
+@code{@var{host}:port}. For example, to connect to port 2828 on a
+terminal server named @code{manyfarms}:
@example
-struct complex @{double real; double imag;@} v;
+target remote manyfarms:2828
@end example
+If your remote target is actually running on the same machine as
+your debugger session (e.g.@: a simulator of your target running on
+the same host), you can omit the hostname. For example, to connect
+to port 1234 on your local machine:
+
+@example
+target remote :1234
+@end example
@noindent
-the two commands give this output:
+
+Note that the colon is still required here.
+@end enumerate
+
+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 @code{detach}
+command.
+
+@cindex interrupting remote programs
+@cindex remote programs, interrupting
+Whenever @value{GDBN} is waiting for the remote program, if you type the
+interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
+program. This may or may not succeed, depending in part on the hardware
+and the serial drivers the remote system uses. If you type the
+interrupt character once again, @value{GDBN} displays this prompt:
@example
-@group
-(@value{GDBP}) whatis v
-type = struct complex
-(@value{GDBP}) ptype v
-type = struct complex @{
- double real;
- double imag;
-@}
-@end group
+Interrupted while waiting for the program.
+Give up (and stop debugging it)? (y or n)
@end example
-@noindent
-As with @code{whatis}, using @code{ptype} without an argument refers to
-the type of @code{$}, the last value in the value history.
+If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
+(If you decide you want to try again later, you can use @samp{target
+remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
+goes back to waiting.
-@kindex info types
-@item info types @var{regexp}
-@itemx info types
-Print a brief description of all types whose name matches @var{regexp}
-(or all types in your program, if you supply no argument). Each
-complete typename is matched as though it were a complete line; thus,
-@samp{i type value} gives information on all types in your program whose
-name includes the string @code{value}, but @samp{i type ^value$} gives
-information only on types whose complete name is @code{value}.
-This command differs from @code{ptype} in two ways: first, like
-@code{whatis}, it does not print a detailed description; second, it
-lists all source files where a type is defined.
+@node Configurations
+@chapter Configuration-Specific Information
+
+While nearly all @value{GDBN} commands are available for all native and
+cross versions of the debugger, there are some exceptions. This chapter
+describes things that are only available in certain configurations.
+
+There are three major categories of configurations: native
+configurations, where the host and target are the same, embedded
+operating system configurations, which are usually the same for several
+different processor architectures, and bare embedded processors, which
+are quite different from each other.
+
+@menu
+* Native::
+* Embedded OS::
+* Embedded Processors::
+* Architectures::
+@end menu
+
+@node Native
+@section Native
+
+This section describes details specific to particular native
+configurations.
+
+@menu
+* HP-UX:: HP-UX
+* SVR4 Process Information:: SVR4 process information
+* DJGPP Native:: Features specific to the DJGPP port
+@end menu
-@kindex info source
-@item info source
-Show the name of the current source file---that is, the source file for
-the function containing the current point of execution---and the language
-it was written in.
+@node HP-UX
+@subsection HP-UX
-@kindex info sources
-@item info sources
-Print the names of all source files in your program for which there is
-debugging information, organized into two lists: files whose symbols
-have already been read, and files whose symbols will be read when needed.
+On HP-UX systems, if you refer to a function or variable name that
+begins with a dollar sign, @value{GDBN} searches for a user or system
+name first, before it searches for a convenience variable.
-@kindex info functions
-@item info functions
-Print the names and data types of all defined functions.
+@node SVR4 Process Information
+@subsection SVR4 process information
-@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 @code{step}; @samp{info fun ^step} finds those whose names
-start with @code{step}.
+@kindex /proc
+@cindex process image
-@kindex info variables
-@item info variables
-Print the names and data types of all variables that are declared
-outside of functions (i.e., excluding local variables).
+Many versions of SVR4 provide a facility called @samp{/proc} that can be
+used to examine the image of a running process using file-system
+subroutines. If @value{GDBN} is configured for an operating system with
+this facility, the command @code{info proc} is available to report on
+several kinds of information about the process running your program.
+@code{info proc} works only on SVR4 systems that include the
+@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix,
+and Unixware, but not HP-UX or Linux, for example.
-@item info variables @var{regexp}
-Print the names and data types of all variables (except for local
-variables) whose names contain a match for regular expression
-@var{regexp}.
+@table @code
+@kindex info proc
+@item info proc
+Summarize available information about the process.
+@kindex info proc mappings
+@item info proc mappings
+Report on the address ranges accessible in the program, with information
+on whether your program may read, write, or execute each range.
@ignore
-This was never implemented.
-@kindex info methods
-@item info methods
-@itemx info methods @var{regexp}
-The @code{info methods} command permits the user to examine all defined
-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 @code{ptype} command can be overwhelming and hard to use. The
-@code{info-methods} command filters the methods, printing only those
-which match the regular-expression @var{regexp}.
+@comment These sub-options of 'info proc' were not included when
+@comment procfs.c was re-written. Keep their descriptions around
+@comment against the day when someone finds the time to put them back in.
+@kindex info proc times
+@item info proc times
+Starting time, user CPU time, and system CPU time for your program and
+its children.
+
+@kindex info proc id
+@item info proc id
+Report on the process IDs related to your program: its own process ID,
+the ID of its parent, the process group ID, and the session ID.
+
+@kindex info proc status
+@item info proc status
+General information on the state of the process. If the process is
+stopped, this report includes the reason for stopping, and any signal
+received.
+
+@item info proc all
+Show all the above information about the process.
@end ignore
+@end table
-@ifclear HPPA
-@cindex reloading symbols
-Some systems allow individual object files that make up your program to
-be replaced without stopping and restarting your program. For example,
-in VxWorks you can simply recompile a defective object file and keep on
-running. If you are running on one of these systems, you can allow
-@value{GDBN} to reload the symbols for automatically relinked modules:
+@node DJGPP Native
+@subsection Features for Debugging @sc{djgpp} Programs
+@cindex @sc{djgpp} debugging
+@cindex native @sc{djgpp} debugging
+@cindex MS-DOS-specific commands
+
+@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and
+MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
+that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
+top of real-mode DOS systems and their emulations.
+
+@value{GDBN} supports native debugging of @sc{djgpp} programs, and
+defines a few commands specific to the @sc{djgpp} port. This
+subsection describes those commands.
@table @code
-@kindex set symbol-reloading
-@item set symbol-reloading on
-Replace symbol definitions for the corresponding source file when an
-object file with a particular name is seen again.
+@kindex info dos
+@item info dos
+This is a prefix of @sc{djgpp}-specific commands which print
+information about the target system and important OS structures.
+
+@kindex sysinfo
+@cindex MS-DOS system info
+@cindex free memory information (MS-DOS)
+@item info dos sysinfo
+This command displays assorted information about the underlying
+platform: the CPU type and features, the OS version and flavor, the
+DPMI version, and the available conventional and DPMI memory.
+
+@cindex GDT
+@cindex LDT
+@cindex IDT
+@cindex segment descriptor tables
+@cindex descriptor tables display
+@item info dos gdt
+@itemx info dos ldt
+@itemx info dos idt
+These 3 commands display entries from, respectively, Global, Local,
+and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor
+tables are data structures which store a descriptor for each segment
+that is currently in use. The segment's selector is an index into a
+descriptor table; the table entry for that index holds the
+descriptor's base address and limit, and its attributes and access
+rights.
+
+A typical @sc{djgpp} program uses 3 segments: a code segment, a data
+segment (used for both data and the stack), and a DOS segment (which
+allows access to DOS/BIOS data structures and absolute addresses in
+conventional memory). However, the DPMI host will usually define
+additional segments in order to support the DPMI environment.
+
+@cindex garbled pointers
+These commands allow to display entries from the descriptor tables.
+Without an argument, all entries from the specified table are
+displayed. An argument, which should be an integer expression, means
+display a single entry whose index is given by the argument. For
+example, here's a convenient way to display information about the
+debugged program's data segment:
-@item set symbol-reloading off
-Do not replace symbol definitions when re-encountering object files of
-the same name. This is the default state; if you are not running on a
-system that permits automatically relinking modules, you should leave
-@code{symbol-reloading} off, since otherwise @value{GDBN} may discard symbols
-when linking large programs, that may contain several modules (from
-different directories or libraries) with the same name.
+@smallexample
+@exdent @code{(@value{GDBP}) info dos ldt $ds}
+@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)}
+@end smallexample
-@kindex show symbol-reloading
-@item show symbol-reloading
-Show the current @code{on} or @code{off} setting.
-@end table
-@end ifclear
+@noindent
+This comes in handy when you want to see whether a pointer is outside
+the data segment's limit (i.e.@: @dfn{garbled}).
+
+@cindex page tables display (MS-DOS)
+@item info dos pde
+@itemx info dos pte
+These two commands display entries from, respectively, the Page
+Directory and the Page Tables. Page Directories and Page Tables are
+data structures which control how virtual memory addresses are mapped
+into physical addresses. A Page Table includes an entry for every
+page of memory that is mapped into the program's address space; there
+may be several Page Tables, each one holding up to 4096 entries. A
+Page Directory has up to 4096 entries, one each for every Page Table
+that is currently in use.
+
+Without an argument, @kbd{info dos pde} displays the entire Page
+Directory, and @kbd{info dos pte} displays all the entries in all of
+the Page Tables. An argument, an integer expression, given to the
+@kbd{info dos pde} command means display only that entry from the Page
+Directory table. An argument given to the @kbd{info dos pte} command
+means display entries from a single Page Table, the one pointed to by
+the specified entry in the Page Directory.
+
+@cindex direct memory access (DMA) on MS-DOS
+These commands are useful when your program uses @dfn{DMA} (Direct
+Memory Access), which needs physical addresses to program the DMA
+controller.
+
+These commands are supported only with some DPMI servers.
+
+@cindex physical address from linear address
+@item info dos address-pte @var{addr}
+This command displays the Page Table entry for a specified linear
+address. The argument linear address @var{addr} should already have the
+appropriate segment's base address added to it, because this command
+accepts addresses which may belong to @emph{any} segment. For
+example, here's how to display the Page Table entry for the page where
+the variable @code{i} is stored:
+
+@smallexample
+@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
+@exdent @code{Page Table entry for address 0x11a00d30:}
+@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
+@end smallexample
-@ifset HPPA
-@kindex set opaque-type-resolution
-@item set opaque-type-resolution on
-Tell @value{GDBN} to resolve opaque types. An opaque type is a type
-declared as a pointer to a @code{struct}, @code{class}, or
-@code{union}---for example, @code{struct MyType *}---that is used in one
-source file although the full declaration of @code{struct MyType} is in
-another source file. The default is on.
+@noindent
+This says that @code{i} is stored at offset @code{0xd30} from the page
+whose physical base address is @code{0x02698000}, and prints all the
+attributes of that page.
-A change in the setting of this subcommand will not take effect until
-the next time symbols for a file are loaded.
+Note that you must cast the addresses of variables to a @code{char *},
+since otherwise the value of @code{__djgpp_base_address}, the base
+address of all variables and functions in a @sc{djgpp} program, will
+be added using the rules of C pointer arithmetics: if @code{i} is
+declared an @code{int}, @value{GDBN} will add 4 times the value of
+@code{__djgpp_base_address} to the address of @code{i}.
+
+Here's another example, it displays the Page Table entry for the
+transfer buffer:
-@item set opaque-type-resolution off
-Tell @value{GDBN} not to resolve opaque types. In this case, the type
-is printed as follows:
@smallexample
-@{<no data fields>@}
+@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)}
+@exdent @code{Page Table entry for address 0x29110:}
+@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110}
@end smallexample
-@kindex show opaque-type-resolution
-@item show opaque-type-resolution
-Show whether opaque types are resolved or not.
-@end ifset
+@noindent
+(The @code{+ 3} offset is because the transfer buffer's address is the
+3rd member of the @code{_go32_info_block} structure.) The output of
+this command clearly shows that addresses in conventional memory are
+mapped 1:1, i.e.@: the physical and linear addresses are identical.
-@kindex maint print symbols
-@cindex symbol dump
-@kindex maint print psymbols
-@cindex partial symbol dump
-@item maint print symbols @var{filename}
-@itemx maint print psymbols @var{filename}
-@itemx maint print msymbols @var{filename}
-Write a dump of debugging symbol data into the file @var{filename}.
-These commands are used to debug the @value{GDBN} symbol-reading code. Only
-symbols with debugging data are included. If you use @samp{maint print
-symbols}, @value{GDBN} includes all the symbols for which it has already
-collected full details: that is, @var{filename} reflects symbols for
-only those files whose symbols @value{GDBN} has read. You can use the
-command @code{info sources} to find out which files these are. If you
-use @samp{maint print psymbols} instead, the dump shows information about
-symbols that @value{GDBN} only knows partially---that is, symbols defined in
-files that @value{GDBN} has skimmed, but not yet read completely. Finally,
-@samp{maint print msymbols} dumps just the minimal symbol information
-required for each object file from which @value{GDBN} has read some symbols.
-@xref{Files, ,Commands to specify files}, for a discussion of how
-@value{GDBN} reads symbols (in the description of @code{symbol-file}).
+This command is supported only with some DPMI servers.
@end table
-@node Altering, GDB Files, Symbols, Top
-@chapter Altering Execution
-
-Once you think you have found an error in your program, you might want to
-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 @value{GDBN} features for altering execution of the
-program.
+@node Embedded OS
+@section Embedded Operating Systems
-For example, you can store new values into variables or memory
-locations, give your program a signal, restart it at a different
-address, or even return prematurely from a function.
+This section describes configurations involving the debugging of
+embedded operating systems that are available for several different
+architectures.
@menu
-* Assignment:: Assignment to variables
-* Jumping:: Continuing at a different address
-* Signaling:: Giving your program a signal
-* Returning:: Returning from a function
-* Calling:: Calling your program's functions
-* Patching:: Patching your program
+* VxWorks:: Using @value{GDBN} with VxWorks
@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, ,Expressions}. For example,
+@value{GDBN} includes the ability to debug programs running on
+various real-time operating systems.
-@example
-print x=4
-@end example
+@node VxWorks
+@subsection Using @value{GDBN} with VxWorks
-@noindent
-stores the value 4 into the variable @code{x}, and then prints the
-value of the assignment expression (which is 4).
-@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
-information on operators in supported languages.
+@cindex VxWorks
-@kindex set variable
-@cindex variables, setting
-If you are not interested in seeing the value of the assignment, use the
-@code{set} command instead of the @code{print} command. @code{set} is
-really the same as @code{print} except that the expression's value is
-not printed and is not put in the value history (@pxref{Value History,
-,Value history}). The expression is evaluated only for its effects.
+@table @code
-@ifclear HPPA
-If the beginning of the argument string of the @code{set} command
-appears identical to a @code{set} subcommand, use the @code{set
-variable} command instead of just @code{set}. This command is identical
-to @code{set} except for its lack of subcommands. For example, if your
-program has a variable @code{width}, you get an error if you try to set
-a new value with just @samp{set width=13}, because @value{GDBN} has the
-command @code{set width}:
+@kindex target vxworks
+@item target vxworks @var{machinename}
+A VxWorks system, attached via TCP/IP. The argument @var{machinename}
+is the target system's machine name or IP address.
-@example
-(@value{GDBP}) whatis width
-type = double
-(@value{GDBP}) p width
-$4 = 13
-(@value{GDBP}) set width=47
-Invalid syntax in expression.
-@end example
+@end table
-@noindent
-The invalid expression, of course, is @samp{=47}. In
-order to actually set the program's variable @code{width}, use
+On VxWorks, @code{load} links @var{filename} dynamically on the
+current target system as well as adding its symbols in @value{GDBN}.
-@example
-(@value{GDBP}) set var width=47
-@end example
-@end ifclear
-@ifset HPPA
-Because the @code{set} command has many subcommands that can conflict
-with the names of program variables, it is a good idea to use the
-@code{set variable} command instead of just @code{set}. For example, if
-your program has a variable @code{g}, you run into problems if you try
-to set a new value with just @samp{set g=4}, because @value{GDBN} has
-the command @code{set gnutarget}, abbreviated @code{set g}:
+@value{GDBN} enables developers to spawn and debug tasks running on networked
+VxWorks targets from a Unix host. Already-running tasks spawned from
+the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
+both the Unix host and on the VxWorks target. The program
+@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
+installed with the name @code{vxgdb}, to distinguish it from a
+@value{GDBN} for debugging programs on the host itself.)
-@example
-@group
-(@value{GDBP}) whatis g
-type = double
-(@value{GDBP}) p g
-$1 = 1
-(@value{GDBP}) set g=4
-(gdb) p g
-$2 = 1
-(@value{GDBP}) r
-The program being debugged has been started already.
-Start it from the beginning? (y or n) y
-Starting program: /home/smith/cc_progs/a.out
-"/home/smith/cc_progs/a.out": can't open to read symbols: Invalid bfd target.
-(@value{GDBP}) show g
-The current BFD target is "=4".
-@end group
-@end example
+@table @code
+@item VxWorks-timeout @var{args}
+@kindex vxworks-timeout
+All VxWorks-based targets now support the option @code{vxworks-timeout}.
+This option is set by the user, and @var{args} represents the number of
+seconds @value{GDBN} waits for responses to rpc's. You might use this if
+your VxWorks target is a slow software simulator or is on the far side
+of a thin network line.
+@end table
-@noindent
-The program variable @code{g} did not change, and you silently set the
-@code{gnutarget} to an invalid value. In order to set the variable
-@code{g}, use
+The following information on connecting to VxWorks was current when
+this manual was produced; newer releases of VxWorks may use revised
+procedures.
-@example
-(@value{GDBP}) set var g=4
-@end example
-@end ifset
+@kindex INCLUDE_RDB
+To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
+to include the remote debugging interface routines in the VxWorks
+library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
+VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
+kernel. The resulting kernel contains @file{rdb.a}, and spawns the
+source debugging task @code{tRdbTask} when VxWorks is booted. For more
+information on configuring and remaking VxWorks, see the manufacturer's
+manual.
+@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
-@value{GDBN} allows more implicit conversions in assignments than C; you can
-freely store an integer value into a pointer variable or vice versa,
-and you can convert any structure to any other structure that is the
-same length or shorter.
-@comment FIXME: how do structs align/pad in these conversions?
-@comment /doc@cygnus.com 18dec1990
+Once you have included @file{rdb.a} in your VxWorks system image and set
+your Unix execution search path to find @value{GDBN}, you are ready to
+run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
+@code{vxgdb}, depending on your installation).
-To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
-construct to generate a value of specified type at a specified address
-(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
-to memory location @code{0x83040} as an integer (which implies a certain size
-and representation in memory), and
+@value{GDBN} comes up showing the prompt:
@example
-set @{int@}0x83040 = 4
+(vxgdb)
@end example
-@noindent
-stores the value 4 into that memory location.
+@menu
+* VxWorks Connection:: Connecting to VxWorks
+* VxWorks Download:: VxWorks download
+* VxWorks Attach:: Running tasks
+@end menu
-@node Jumping, Signaling, Assignment, Altering
-@section Continuing at a different address
+@node VxWorks Connection
+@subsubsection Connecting to VxWorks
-Ordinarily, when you continue your program, you do so at the place where
-it stopped, with the @code{continue} command. You can instead continue at
-an address of your own choosing, with the following commands:
+The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
+network. To connect to a target whose host name is ``@code{tt}'', type:
-@table @code
-@kindex jump
-@item jump @var{linespec}
-Resume execution at line @var{linespec}. Execution stops again
-immediately if there is a breakpoint there. @xref{List, ,Printing
-source lines}, for a description of the different forms of
-@var{linespec}. It is common practice to use the @code{tbreak} command
-in conjunction with @code{jump}. @xref{Set Breaks, ,Setting
-breakpoints}.
+@example
+(vxgdb) target vxworks tt
+@end example
+
+@need 750
+@value{GDBN} displays messages like these:
-The @code{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{linespec} is in
-a different function from the one currently executing, the results may
-be bizarre if the two functions expect different patterns of arguments or
-of local variables. For this reason, the @code{jump} command requests
-confirmation if the specified line is not in the function currently
-executing. However, even bizarre results are predictable if you are
-well acquainted with the machine-language code of your program.
+@smallexample
+Attaching remote machine across net...
+Connected to tt.
+@end smallexample
-@item jump *@var{address}
-Resume execution at the instruction at address @var{address}.
-@end table
+@need 1000
+@value{GDBN} then attempts to read the symbol tables of any object modules
+loaded into the VxWorks target since it was last booted. @value{GDBN} locates
+these files by searching the directories listed in the command search
+path (@pxref{Environment, ,Your program's environment}); if it fails
+to find an object file, it displays a message such as:
-@ifclear HPPA
-@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
-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 your program running; it only changes the address of where it
-@emph{will} run when you continue. For example,
+@example
+prog.o: No such file or directory.
+@end example
+
+When this happens, add the appropriate directory to the search path with
+the @value{GDBN} command @code{path}, and execute the @code{target}
+command again.
+
+@node VxWorks Download
+@subsubsection VxWorks download
+
+@cindex download to VxWorks
+If you have connected to the VxWorks target and you want to debug an
+object that has not yet been loaded, you can use the @value{GDBN}
+@code{load} command to download a file from Unix to VxWorks
+incrementally. The object file given as an argument to the @code{load}
+command is actually opened twice: first by the VxWorks target in order
+to download the code, then by @value{GDBN} in order to read the symbol
+table. This can lead to problems if the current working directories on
+the two systems differ. If both systems have NFS mounted the same
+filesystems, you can avoid these problems by using absolute paths.
+Otherwise, it is simplest to set the working directory on both systems
+to the directory in which the object file resides, and then to reference
+the file by its name, without any path. For instance, a program
+@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
+and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
+program, type this on VxWorks:
@example
-set $pc = 0x485
+-> cd "@var{vxpath}/vw/demo/rdb"
@end example
@noindent
-makes the next @code{continue} command or stepping command execute at
-address @code{0x485}, rather than at the address where your program stopped.
-@xref{Continuing and Stepping, ,Continuing and stepping}.
-@end ifclear
+Then, in @value{GDBN}, type:
-The most common occasion to use the @code{jump} command is to back
-up---perhaps with more breakpoints set---over a portion of a program
-that has already executed, in order to examine its execution in more
-detail.
+@example
+(vxgdb) cd @var{hostpath}/vw/demo/rdb
+(vxgdb) load prog.o
+@end example
-@c @group
-@node Signaling, Returning, Jumping, Altering
-@section Giving your program a signal
+@value{GDBN} displays a response similar to this:
-@table @code
-@kindex signal
-@item signal @var{signal}
-Resume execution where your program stopped, but immediately give it the
-signal @var{signal}. @var{signal} can be the name or the number of a
-signal. For example, on many systems @code{signal 2} and @code{signal
-SIGINT} are both ways of sending an interrupt signal.
+@smallexample
+Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
+@end smallexample
-Alternatively, if @var{signal} is zero, continue execution without
-giving a signal. This is useful when your program stopped on account of
-a signal and would ordinary see the signal when resumed with the
-@code{continue} command; @samp{signal 0} causes it to resume without a
-signal.
+You can also use the @code{load} command to reload an object module
+after editing and recompiling the corresponding source file. Note that
+this makes @value{GDBN} delete all currently-defined breakpoints,
+auto-displays, and convenience variables, and to clear the value
+history. (This is necessary in order to preserve the integrity of
+debugger's data structures that reference the target system's symbol
+table.)
-@code{signal} does not repeat when you press @key{RET} a second time
-after executing the command.
-@end table
-@c @end group
+@node VxWorks Attach
+@subsubsection Running tasks
-Invoking the @code{signal} command is not the same as invoking the
-@code{kill} utility from the shell. Sending a signal with @code{kill}
-causes @value{GDBN} to decide what to do with the signal depending on
-the signal handling tables (@pxref{Signals}). The @code{signal} command
-passes the signal directly to your program.
+@cindex running VxWorks tasks
+You can also attach to an existing task using the @code{attach} command as
+follows:
+@example
+(vxgdb) attach @var{task}
+@end example
-@node Returning, Calling, Signaling, Altering
-@section Returning from a function
+@noindent
+where @var{task} is the VxWorks hexadecimal task ID. The task can be running
+or suspended when you attach to it. Running tasks are suspended at
+the time of attachment.
-@table @code
-@cindex returning from a function
-@kindex return
-@item return
-@itemx return @var{expression}
-You can cancel execution of a function call with the @code{return}
-command. If you give an
-@var{expression} argument, its value is used as the function's return
-value.
-@end table
+@node Embedded Processors
+@section Embedded Processors
-When you use @code{return}, @value{GDBN} discards the selected stack frame
-(and all frames within it). You can think of this as making the
-discarded frame return prematurely. If you wish to specify a value to
-be returned, give that value as the argument to @code{return}.
+This section goes into details specific to particular embedded
+configurations.
-This pops the selected stack frame (@pxref{Selection, ,Selecting a
-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.
-The @code{return} command does not resume execution; it leaves the
-program stopped in the state that would exist if the function had just
-returned. In contrast, the @code{finish} command (@pxref{Continuing
-and Stepping, ,Continuing and stepping}) resumes execution until the
-selected stack frame returns naturally.
+@c OBSOLETE * A29K Embedded:: AMD A29K Embedded
+@menu
+* ARM:: ARM
+* H8/300:: Hitachi H8/300
+* H8/500:: Hitachi H8/500
+* i960:: Intel i960
+* M32R/D:: Mitsubishi M32R/D
+* M68K:: Motorola M68K
+* M88K:: Motorola M88K
+* MIPS Embedded:: MIPS Embedded
+* PA:: HP PA Embedded
+* PowerPC: PowerPC
+* SH:: Hitachi SH
+* Sparclet:: Tsqware Sparclet
+* Sparclite:: Fujitsu Sparclite
+* ST2000:: Tandem ST2000
+* Z8000:: Zilog Z8000
+@end menu
-@node Calling, Patching, Returning, Altering
-@section Calling program functions
+@c OBSOLETE @node A29K Embedded
+@c OBSOLETE @subsection AMD A29K Embedded
+@c OBSOLETE
+@c OBSOLETE @menu
+@c OBSOLETE * A29K UDI::
+@c OBSOLETE * A29K EB29K::
+@c OBSOLETE * Comms (EB29K):: Communications setup
+@c OBSOLETE * gdb-EB29K:: EB29K cross-debugging
+@c OBSOLETE * Remote Log:: Remote log
+@c OBSOLETE @end menu
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE
+@c OBSOLETE @kindex target adapt
+@c OBSOLETE @item target adapt @var{dev}
+@c OBSOLETE Adapt monitor for A29K.
+@c OBSOLETE
+@c OBSOLETE @kindex target amd-eb
+@c OBSOLETE @item target amd-eb @var{dev} @var{speed} @var{PROG}
+@c OBSOLETE @cindex AMD EB29K
+@c OBSOLETE Remote PC-resident AMD EB29K board, attached over serial lines.
+@c OBSOLETE @var{dev} is the serial device, as for @code{target remote};
+@c OBSOLETE @var{speed} allows you to specify the linespeed; and @var{PROG} is the
+@c OBSOLETE name of the program to be debugged, as it appears to DOS on the PC.
+@c OBSOLETE @xref{A29K EB29K, ,EBMON protocol for AMD29K}.
+@c OBSOLETE
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node A29K UDI
+@c OBSOLETE @subsubsection A29K UDI
+@c OBSOLETE
+@c OBSOLETE @cindex UDI
+@c OBSOLETE @cindex AMD29K via UDI
+@c OBSOLETE
+@c OBSOLETE @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
+@c OBSOLETE protocol for debugging the a29k processor family. To use this
+@c OBSOLETE configuration with AMD targets running the MiniMON monitor, you need the
+@c OBSOLETE program @code{MONTIP}, available from AMD at no charge. You can also
+@c OBSOLETE use @value{GDBN} with the UDI-conformant a29k simulator program
+@c OBSOLETE @code{ISSTIP}, also available from AMD.
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE @item target udi @var{keyword}
+@c OBSOLETE @kindex udi
+@c OBSOLETE Select the UDI interface to a remote a29k board or simulator, where
+@c OBSOLETE @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
+@c OBSOLETE This file contains keyword entries which specify parameters used to
+@c OBSOLETE connect to a29k targets. If the @file{udi_soc} file is not in your
+@c OBSOLETE working directory, you must set the environment variable @samp{UDICONF}
+@c OBSOLETE to its pathname.
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node A29K EB29K
+@c OBSOLETE @subsubsection EBMON protocol for AMD29K
+@c OBSOLETE
+@c OBSOLETE @cindex EB29K board
+@c OBSOLETE @cindex running 29K programs
+@c OBSOLETE
+@c OBSOLETE AMD distributes a 29K development board meant to fit in a PC, together
+@c OBSOLETE with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
+@c OBSOLETE term, this development system is called the ``EB29K''. To use
+@c OBSOLETE @value{GDBN} from a Unix system to run programs on the EB29K board, you
+@c OBSOLETE must first connect a serial cable between the PC (which hosts the EB29K
+@c OBSOLETE board) and a serial port on the Unix system. In the following, we
+@c OBSOLETE assume you've hooked the cable between the PC's @file{COM1} port and
+@c OBSOLETE @file{/dev/ttya} on the Unix system.
+@c OBSOLETE
+@c OBSOLETE @node Comms (EB29K)
+@c OBSOLETE @subsubsection Communications setup
+@c OBSOLETE
+@c OBSOLETE The next step is to set up the PC's port, by doing something like this
+@c OBSOLETE in DOS on the PC:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE C:\> MODE com1:9600,n,8,1,none
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE This example---run on an MS DOS 4.0 system---sets the PC port to 9600
+@c OBSOLETE bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
+@c OBSOLETE you must match the communications parameters when establishing the Unix
+@c OBSOLETE end of the connection as well.
+@c OBSOLETE @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
+@c OBSOLETE @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
+@c OBSOLETE @c
+@c OBSOLETE @c It's optional, but it's unwise to omit it: who knows what is the
+@c OBSOLETE @c default value set when the DOS machines boots? "No retry" means that
+@c OBSOLETE @c the DOS serial device driver won't retry the operation if it fails;
+@c OBSOLETE @c I understand that this is needed because the GDB serial protocol
+@c OBSOLETE @c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99
+@c OBSOLETE
+@c OBSOLETE To give control of the PC to the Unix side of the serial line, type
+@c OBSOLETE the following at the DOS console:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE C:\> CTTY com1
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE (Later, if you wish to return control to the DOS console, you can use
+@c OBSOLETE the command @code{CTTY con}---but you must send it over the device that
+@c OBSOLETE had control, in our example over the @file{COM1} serial line.)
+@c OBSOLETE
+@c OBSOLETE From the Unix host, use a communications program such as @code{tip} or
+@c OBSOLETE @code{cu} to communicate with the PC; for example,
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE cu -s 9600 -l /dev/ttya
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE The @code{cu} options shown specify, respectively, the linespeed and the
+@c OBSOLETE serial port to use. If you use @code{tip} instead, your command line
+@c OBSOLETE may look something like the following:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE tip -9600 /dev/ttya
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE Your system may require a different name where we show
+@c OBSOLETE @file{/dev/ttya} as the argument to @code{tip}. The communications
+@c OBSOLETE parameters, including which port to use, are associated with the
+@c OBSOLETE @code{tip} argument in the ``remote'' descriptions file---normally the
+@c OBSOLETE system table @file{/etc/remote}.
+@c OBSOLETE @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
+@c OBSOLETE @c the DOS side's comms setup? cu can support -o (odd
+@c OBSOLETE @c parity), -e (even parity)---apparently no settings for no parity or
+@c OBSOLETE @c for character size. Taken from stty maybe...? John points out tip
+@c OBSOLETE @c can set these as internal variables, eg ~s parity=none; man stty
+@c OBSOLETE @c suggests that it *might* work to stty these options with stdin or
+@c OBSOLETE @c stdout redirected... ---doc@cygnus.com, 25feb91
+@c OBSOLETE @c
+@c OBSOLETE @c There's nothing to be done for the "none" part of the DOS MODE
+@c OBSOLETE @c command. The rest of the parameters should be matched by the
+@c OBSOLETE @c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99
+@c OBSOLETE
+@c OBSOLETE @kindex EBMON
+@c OBSOLETE Using the @code{tip} or @code{cu} connection, change the DOS working
+@c OBSOLETE directory to the directory containing a copy of your 29K program, then
+@c OBSOLETE start the PC program @code{EBMON} (an EB29K control program supplied
+@c OBSOLETE with your board by AMD). You should see an initial display from
+@c OBSOLETE @code{EBMON} similar to the one that follows, ending with the
+@c OBSOLETE @code{EBMON} prompt @samp{#}---
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE C:\> G:
+@c OBSOLETE
+@c OBSOLETE G:\> CD \usr\joe\work29k
+@c OBSOLETE
+@c OBSOLETE G:\USR\JOE\WORK29K> EBMON
+@c OBSOLETE Am29000 PC Coprocessor Board Monitor, version 3.0-18
+@c OBSOLETE Copyright 1990 Advanced Micro Devices, Inc.
+@c OBSOLETE Written by Gibbons and Associates, Inc.
+@c OBSOLETE
+@c OBSOLETE Enter '?' or 'H' for help
+@c OBSOLETE
+@c OBSOLETE PC Coprocessor Type = EB29K
+@c OBSOLETE I/O Base = 0x208
+@c OBSOLETE Memory Base = 0xd0000
+@c OBSOLETE
+@c OBSOLETE Data Memory Size = 2048KB
+@c OBSOLETE Available I-RAM Range = 0x8000 to 0x1fffff
+@c OBSOLETE Available D-RAM Range = 0x80002000 to 0x801fffff
+@c OBSOLETE
+@c OBSOLETE PageSize = 0x400
+@c OBSOLETE Register Stack Size = 0x800
+@c OBSOLETE Memory Stack Size = 0x1800
+@c OBSOLETE
+@c OBSOLETE CPU PRL = 0x3
+@c OBSOLETE Am29027 Available = No
+@c OBSOLETE Byte Write Available = Yes
+@c OBSOLETE
+@c OBSOLETE # ~.
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE Then exit the @code{cu} or @code{tip} program (done in the example by
+@c OBSOLETE typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
+@c OBSOLETE running, ready for @value{GDBN} to take over.
+@c OBSOLETE
+@c OBSOLETE For this example, we've assumed what is probably the most convenient
+@c OBSOLETE way to make sure the same 29K program is on both the PC and the Unix
+@c OBSOLETE system: a PC/NFS connection that establishes ``drive @file{G:}'' on the
+@c OBSOLETE PC as a file system on the Unix host. If you do not have PC/NFS or
+@c OBSOLETE something similar connecting the two systems, you must arrange some
+@c OBSOLETE other way---perhaps floppy-disk transfer---of getting the 29K program
+@c OBSOLETE from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
+@c OBSOLETE serial line.
+@c OBSOLETE
+@c OBSOLETE @node gdb-EB29K
+@c OBSOLETE @subsubsection EB29K cross-debugging
+@c OBSOLETE
+@c OBSOLETE Finally, @code{cd} to the directory containing an image of your 29K
+@c OBSOLETE program on the Unix system, and start @value{GDBN}---specifying as argument the
+@c OBSOLETE name of your 29K program:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE cd /usr/joe/work29k
+@c OBSOLETE @value{GDBP} myfoo
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @need 500
+@c OBSOLETE Now you can use the @code{target} command:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE target amd-eb /dev/ttya 9600 MYFOO
+@c OBSOLETE @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
+@c OBSOLETE @c emphasize that this is the name as seen by DOS (since I think DOS is
+@c OBSOLETE @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE In this example, we've assumed your program is in a file called
+@c OBSOLETE @file{myfoo}. Note that the filename given as the last argument to
+@c OBSOLETE @code{target amd-eb} should be the name of the program as it appears to DOS.
+@c OBSOLETE In our example this is simply @code{MYFOO}, but in general it can include
+@c OBSOLETE a DOS path, and depending on your transfer mechanism may not resemble
+@c OBSOLETE the name on the Unix side.
+@c OBSOLETE
+@c OBSOLETE At this point, you can set any breakpoints you wish; when you are ready
+@c OBSOLETE to see your program run on the 29K board, use the @value{GDBN} command
+@c OBSOLETE @code{run}.
+@c OBSOLETE
+@c OBSOLETE To stop debugging the remote program, use the @value{GDBN} @code{detach}
+@c OBSOLETE command.
+@c OBSOLETE
+@c OBSOLETE To return control of the PC to its console, use @code{tip} or @code{cu}
+@c OBSOLETE once again, after your @value{GDBN} session has concluded, to attach to
+@c OBSOLETE @code{EBMON}. You can then type the command @code{q} to shut down
+@c OBSOLETE @code{EBMON}, returning control to the DOS command-line interpreter.
+@c OBSOLETE Type @kbd{CTTY con} to return command input to the main DOS console,
+@c OBSOLETE and type @kbd{~.} to leave @code{tip} or @code{cu}.
+@c OBSOLETE
+@c OBSOLETE @node Remote Log
+@c OBSOLETE @subsubsection Remote log
+@c OBSOLETE @cindex @file{eb.log}, a log file for EB29K
+@c OBSOLETE @cindex log file for EB29K
+@c OBSOLETE
+@c OBSOLETE The @code{target amd-eb} command creates a file @file{eb.log} in the
+@c OBSOLETE current working directory, to help debug problems with the connection.
+@c OBSOLETE @file{eb.log} records all the output from @code{EBMON}, including echoes
+@c OBSOLETE of the commands sent to it. Running @samp{tail -f} on this file in
+@c OBSOLETE another window often helps to understand trouble with @code{EBMON}, or
+@c OBSOLETE unexpected events on the PC side of the connection.
+
+@node ARM
+@subsection ARM
-@cindex calling functions
-@kindex call
@table @code
-@item call @var{expr}
-Evaluate the expression @var{expr} without displaying @code{void}
-returned values.
-@end table
-You can use this variant of the @code{print} command if you want to
-execute a function from your program, but without cluttering the output
-with @code{void} returned values. If the result is not void, it
-is printed and saved in the value history.
-
-@ifclear HPPA
-For the A29K, a user-controlled variable @code{call_scratch_address},
-specifies the location of a scratch area to be used when @value{GDBN}
-calls a function in the target. This is necessary because the usual
-method of putting the scratch area on the stack does not work in systems
-that have separate instruction and data spaces.
-@end ifclear
-
-@node Patching, , Calling, Altering
-@section Patching programs
+@kindex target rdi
+@item target rdi @var{dev}
+ARM Angel monitor, via RDI library interface to ADP protocol. You may
+use this target to communicate with both boards running the Angel
+monitor, or with the EmbeddedICE JTAG debug device.
-@cindex patching binaries
-@cindex writing into executables
-@cindex writing into corefiles
+@kindex target rdp
+@item target rdp @var{dev}
+ARM Demon monitor.
-By default, @value{GDBN} opens the file containing your program's
-executable code (or the corefile) read-only. This prevents accidental
-alterations to machine code; but it also prevents you from intentionally
-patching your program's binary.
+@end table
-If you'd like to be able to patch the binary, you can specify that
-explicitly with the @code{set write} command. For example, you might
-want to turn on internal debugging flags, or even to make emergency
-repairs.
+@node H8/300
+@subsection Hitachi H8/300
@table @code
-@kindex set write
-@item set write on
-@itemx set write off
-If you specify @samp{set write on}, @value{GDBN} opens executable and
-core files for both reading and writing; if you specify @samp{set write
-off} (the default), @value{GDBN} opens them read-only.
-If you have already loaded a file, you must load it again (using the
-@code{exec-file} or @code{core-file} command) after changing @code{set
-write}, for your new setting to take effect.
+@kindex target hms@r{, with H8/300}
+@item target hms @var{dev}
+A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host.
+Use special commands @code{device} and @code{speed} to control the serial
+line and the communications speed used.
+
+@kindex target e7000@r{, with H8/300}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi H8 and SH.
+
+@kindex target sh3@r{, with H8/300}
+@kindex target sh3e@r{, with H8/300}
+@item target sh3 @var{dev}
+@itemx target sh3e @var{dev}
+Hitachi SH-3 and SH-3E target systems.
-@item show write
-@kindex show write
-Display whether executable files and core files are opened for writing
-as well as reading.
@end table
-@node GDB Files, Targets, Altering, Top
-@chapter @value{GDBN} Files
+@cindex download to H8/300 or H8/500
+@cindex H8/300 or H8/500 download
+@cindex download to Hitachi SH
+@cindex Hitachi SH download
+When you select remote debugging to a Hitachi SH, H8/300, or H8/500
+board, the @code{load} command downloads your program to the Hitachi
+board and also opens it as the current executable target for
+@value{GDBN} on your host (like the @code{file} command).
-@value{GDBN} 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 your
-program. To debug a core dump of a previous run, you must also tell
-@value{GDBN} the name of the core dump file.
+@value{GDBN} needs to know these things to talk to your
+Hitachi SH, H8/300, or H8/500:
-@menu
-* Files:: Commands to specify files
-* Symbol Errors:: Errors reading symbol files
-@end menu
+@enumerate
+@item
+that you want to use @samp{target hms}, the remote debugging interface
+for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
+emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
+the default when @value{GDBN} is configured specifically for the Hitachi SH,
+H8/300, or H8/500.)
-@node Files, Symbol Errors, GDB Files, GDB Files
-@section Commands to specify files
+@item
+what serial device connects your host to your Hitachi board (the first
+serial device available on your host is the default).
-@cindex symbol table
-@cindex core dump file
+@item
+what speed to use over the serial device.
+@end enumerate
-You may want to specify executable and core dump file names. The usual
-way to do this is at start-up time, using the arguments to
-@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and
-Out of @value{GDBN}}).
+@menu
+* Hitachi Boards:: Connecting to Hitachi boards.
+* Hitachi ICE:: Using the E7000 In-Circuit Emulator.
+* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
+@end menu
-Occasionally it is necessary to change to a different file during a
-@value{GDBN} session. Or you may run @value{GDBN} and forget to specify
-a file you want to use. In these situations the @value{GDBN} commands
-to specify new files are useful.
+@node Hitachi Boards
+@subsubsection Connecting to Hitachi boards
+
+@c only for Unix hosts
+@kindex device
+@cindex serial device, Hitachi micros
+Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
+need to explicitly set the serial device. The default @var{port} is the
+first available port on your host. This is only necessary on Unix
+hosts, where it is typically something like @file{/dev/ttya}.
+
+@kindex speed
+@cindex serial line speed, Hitachi micros
+@code{@value{GDBN}} has another special command to set the communications
+speed: @samp{speed @var{bps}}. This command also is only used from Unix
+hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
+the DOS @code{mode} command (for instance,
+@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection).
+
+The @samp{device} and @samp{speed} commands are available only when you
+use a Unix host to debug your Hitachi microprocessor programs. If you
+use a DOS host,
+@value{GDBN} depends on an auxiliary terminate-and-stay-resident program
+called @code{asynctsr} to communicate with the development board
+through a PC serial port. You must also use the DOS @code{mode} command
+to set up the serial port on the DOS side.
+
+The following sample session illustrates the steps needed to start a
+program under @value{GDBN} control on an H8/300. The example uses a
+sample H8/300 program called @file{t.x}. The procedure is the same for
+the Hitachi SH and the H8/500.
+
+First hook up your development board. In this example, we use a
+board attached to serial port @code{COM2}; if you use a different serial
+port, substitute its name in the argument of the @code{mode} command.
+When you call @code{asynctsr}, the auxiliary comms program used by the
+debugger, you give it just the numeric part of the serial port's name;
+for example, @samp{asyncstr 2} below runs @code{asyncstr} on
+@code{COM2}.
-@table @code
-@cindex executable file
-@kindex file
-@item file @var{filename}
-Use @var{filename} as the program to be debugged. It is read for its
-symbols and for the contents of pure memory. It is also the program
-executed when you use the @code{run} command. If you do not specify a
-directory and the file is not found in the @value{GDBN} working directory,
-@value{GDBN} uses the environment variable @code{PATH} as a list of
-directories to search, just as the shell does when looking for a program
-to run. You can change the value of this variable, for both @value{GDBN}
-and your program, using the @code{path} command.
+@example
+C:\H8300\TEST> asynctsr 2
+C:\H8300\TEST> mode com2:9600,n,8,1,p
-@ifclear HPPA
-On systems with memory-mapped files, an auxiliary file
-@file{@var{filename}.syms} may hold symbol table information for
-@var{filename}. If so, @value{GDBN} maps in the symbol table from
-@file{@var{filename}.syms}, starting up more quickly. See the
-descriptions of the file options @samp{-mapped} and @samp{-readnow}
-(available on the command line, and with the commands @code{file},
-@code{symbol-file}, or @code{add-symbol-file}, described below),
-for more information.
-@end ifclear
+Resident portion of MODE loaded
-@item file
-@code{file} with no argument makes @value{GDBN} discard any information it
-has on both executable file and the symbol table.
+COM2: 9600, n, 8, 1, p
-@kindex exec-file
-@item exec-file @r{[} @var{filename} @r{]}
-Specify that the program to be run (but not the symbol table) is found
-in @var{filename}. @value{GDBN} searches the environment variable @code{PATH}
-if necessary to locate your program. Omitting @var{filename} means to
-discard information on the executable file.
+@end example
-@kindex symbol-file
-@item symbol-file @r{[} @var{filename} @r{]}
-Read symbol table information from file @var{filename}. @code{PATH} is
-searched when necessary. Use the @code{file} command to get both symbol
-table and program to run from the same file.
+@quotation
+@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
+@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
+disable it, or even boot without it, to use @code{asynctsr} to control
+your development board.
+@end quotation
-@code{symbol-file} with no argument clears out @value{GDBN} information on your
-program's symbol table.
+@kindex target hms@r{, and serial protocol}
+Now that serial communications are set up, and the development board is
+connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
+the name of your program as the argument. @code{@value{GDBN}} prompts
+you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
+commands to begin your debugging session: @samp{target hms} to specify
+cross-debugging to the Hitachi board, and the @code{load} command to
+download your program to the board. @code{load} displays the names of
+the program's sections, and a @samp{*} for each 2K of data downloaded.
+(If you want to refresh @value{GDBN} data on symbols or on the
+executable file without downloading, use the @value{GDBN} commands
+@code{file} or @code{symbol-file}. These commands, and @code{load}
+itself, are described in @ref{Files,,Commands to specify files}.)
-The @code{symbol-file} command causes @value{GDBN} 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 @value{GDBN}.
+@smallexample
+(eg-C:\H8300\TEST) @value{GDBP} t.x
+@value{GDBN} is free software and you are welcome to distribute copies
+ of it under certain conditions; type "show copying" to see
+ the conditions.
+There is absolutely no warranty for @value{GDBN}; type "show warranty"
+for details.
+@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
+(@value{GDBP}) target hms
+Connected to remote H8/300 HMS system.
+(@value{GDBP}) load t.x
+.text : 0x8000 .. 0xabde ***********
+.data : 0xabde .. 0xad30 *
+.stack : 0xf000 .. 0xf014 *
+@end smallexample
-@code{symbol-file} does not repeat if you press @key{RET} again after
-executing it once.
+At this point, you're ready to run or debug your program. From here on,
+you can use all the usual @value{GDBN} commands. The @code{break} command
+sets breakpoints; the @code{run} command starts your program;
+@code{print} or @code{x} display data; the @code{continue} command
+resumes execution after stopping at a breakpoint. You can use the
+@code{help} command at any time to find out more about @value{GDBN} commands.
-When @value{GDBN} is configured for a particular environment, it
-understands debugging information in whatever format is the standard
-generated for that environment; you may use either a @sc{gnu} compiler, or
-other compilers that adhere to the local conventions.
-@ifclear HPPA
-Best results are usually obtained from @sc{gnu} compilers; for example,
-using @code{@value{GCC}} you can generate debugging information for
-optimized code.
-@end ifclear
+Remember, however, that @emph{operating system} facilities aren't
+available on your development board; for example, if your program hangs,
+you can't send an interrupt---but you can press the @sc{reset} switch!
-For most kinds of object files, with the exception of old SVR3 systems
-using COFF, the @code{symbol-file} command does not normally 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, as they are needed.
+Use the @sc{reset} button on the development board
+@itemize @bullet
+@item
+to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
+no way to pass an interrupt signal to the development board); and
-The purpose of this two-stage reading strategy is to make @value{GDBN}
-start up 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 @code{set verbose} command can turn these
-pauses into messages if desired. @xref{Messages/Warnings, ,Optional
-warnings and messages}.)
+@item
+to return to the @value{GDBN} command prompt after your program finishes
+normally. The communications protocol provides no other way for @value{GDBN}
+to detect program completion.
+@end itemize
-@ifclear HPPA
-We have not implemented the two-stage strategy for COFF yet. When the
-symbol table is stored in COFF format, @code{symbol-file} reads the
-symbol table data in full right away. Note that ``stabs-in-COFF''
-still does the two-stage strategy, since the debug info is actually
-in stabs format.
+In either case, @value{GDBN} sees the effect of a @sc{reset} on the
+development board as a ``normal exit'' of your program.
-@kindex readnow
-@cindex reading symbols immediately
-@cindex symbols, reading immediately
-@kindex mapped
-@cindex memory-mapped symbol file
-@cindex saving symbol table
-@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
-@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
-You can override the @value{GDBN} two-stage strategy for reading symbol
-tables by using the @samp{-readnow} option with any of the commands that
-load symbol table information, if you want to be sure @value{GDBN} has the
-entire symbol table available.
-@end ifclear
+@node Hitachi ICE
+@subsubsection Using the E7000 in-circuit emulator
-@ifclear HPPA
-If memory-mapped files are available on your system through the
-@code{mmap} system call, you can use another option, @samp{-mapped}, to
-cause @value{GDBN} to write the symbols for your program into a reusable
-file. Future @value{GDBN} debugging sessions map in symbol information
-from this auxiliary symbol file (if the program has not changed), rather
-than spending time reading the symbol table from the executable
-program. Using the @samp{-mapped} option has the same effect as
-starting @value{GDBN} with the @samp{-mapped} command-line option.
+@kindex target e7000@r{, with Hitachi ICE}
+You can use the E7000 in-circuit emulator to develop code for either the
+Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
+e7000} command to connect @value{GDBN} to your E7000:
-You can use both options together, to make sure the auxiliary symbol
-file has all the symbol information for your program.
+@table @code
+@item target e7000 @var{port} @var{speed}
+Use this form if your E7000 is connected to a serial port. The
+@var{port} argument identifies what serial port to use (for example,
+@samp{com2}). The third argument is the line speed in bits per second
+(for example, @samp{9600}).
+
+@item target e7000 @var{hostname}
+If your E7000 is installed as a host on a TCP/IP network, you can just
+specify its hostname; @value{GDBN} uses @code{telnet} to connect.
+@end table
-The auxiliary symbol file for a program called @var{myprog} is called
-@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
-than the corresponding executable), @value{GDBN} always attempts to use
-it when you debug @var{myprog}; no special options or commands are
-needed.
+@node Hitachi Special
+@subsubsection Special @value{GDBN} commands for Hitachi micros
-The @file{.syms} file is specific to the host machine where you run
-@value{GDBN}. It holds an exact image of the internal @value{GDBN}
-symbol table. It cannot be shared across multiple host platforms.
+Some @value{GDBN} commands are available only for the H8/300:
-@c FIXME: for now no mention of directories, since this seems to be in
-@c flux. 13mar1992 status is that in theory GDB would look either in
-@c current dir or in same dir as myprog; but issues like competing
-@c GDB's, or clutter in system dirs, mean that in practice right now
-@c only current dir is used. FFish says maybe a special GDB hierarchy
-@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
-@c files.
+@table @code
-@kindex core
-@kindex core-file
-@item core-file @r{[} @var{filename} @r{]}
-Specify the whereabouts of a core dump file to be used as the ``contents
-of memory''. Traditionally, core files contain only some parts of the
-address space of the process that generated them; @value{GDBN} can access the
-executable file itself for other parts.
+@kindex set machine
+@kindex show machine
+@item set machine h8300
+@itemx set machine h8300h
+Condition @value{GDBN} for one of the two variants of the H8/300
+architecture with @samp{set machine}. You can use @samp{show machine}
+to check which variant is currently in effect.
-@code{core-file} with no argument specifies that no core file is
-to be used.
+@end table
-Note that the core file is ignored when your program is actually running
-under @value{GDBN}. So, if you have been running your 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 @code{kill} command
-(@pxref{Kill Process, ,Killing the child process}).
-@end ifclear
+@node H8/500
+@subsection H8/500
-@ifclear HPPA
-@kindex add-symbol-file
-@cindex dynamic linking
-@item add-symbol-file @var{filename} @var{address}
-@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
-The @code{add-symbol-file} command reads additional symbol table information
-from the file @var{filename}. You would use this command when @var{filename}
-has been dynamically loaded (by some other means) into the program that
-is running. @var{address} should be the memory address at which the
-file has been loaded; @value{GDBN} cannot figure this out for itself.
-You can specify @var{address} as an expression.
+@table @code
-The symbol table of the file @var{filename} is added to the symbol table
-originally read with the @code{symbol-file} command. You can use the
-@code{add-symbol-file} command any number of times; the new symbol data thus
-read keeps adding to the old. To discard all old symbol data instead,
-use the @code{symbol-file} command.
+@kindex set memory @var{mod}
+@cindex memory models, H8/500
+@item set memory @var{mod}
+@itemx show memory
+Specify which H8/500 memory model (@var{mod}) you are using with
+@samp{set memory}; check which memory model is in effect with @samp{show
+memory}. The accepted values for @var{mod} are @code{small},
+@code{big}, @code{medium}, and @code{compact}.
-@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+@end table
-You can use the @samp{-mapped} and @samp{-readnow} options just as with
-the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
-table information for @var{filename}.
+@node i960
+@subsection Intel i960
-@kindex add-shared-symbol-file
-@item add-shared-symbol-file
-The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
-operating system for the Motorola 88k. @value{GDBN} automatically looks for
-shared libraries, however if @value{GDBN} does not find yours, you can run
-@code{add-shared-symbol-file}. It takes no arguments.
-@end ifclear
+@table @code
-@ifclear HPPA
-@kindex section
-@item section
-The @code{section} command changes the base address of section SECTION of
-the exec file to ADDR. This can be used if the exec file does not contain
-section addresses, (such as in the a.out format), or when the addresses
-specified in the file itself are wrong. Each section must be changed
-separately. The ``info files'' command lists all the sections and their
-addresses.
-@end ifclear
+@kindex target mon960
+@item target mon960 @var{dev}
+MON960 monitor for Intel i960.
-@kindex info files
-@kindex info target
-@item info files
-@itemx info target
-@code{info files} and @code{info target} are synonymous; both print the
-current target (@pxref{Targets, ,Specifying a Debugging Target}),
-including the names of the executable and core dump files currently in
-use by @value{GDBN}, and the files from which symbols were loaded. The
-command @code{help target} lists all possible targets rather than
-current ones.
+@kindex target nindy
+@item target nindy @var{devicename}
+An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
+the name of the serial device to use for the connection, e.g.
+@file{/dev/ttya}.
@end table
-All file-specifying commands allow both absolute and relative file names
-as arguments. @value{GDBN} always converts the file name to an absolute file
-name and remembers it that way.
+@cindex Nindy
+@cindex i960
+@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
+@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
+tell @value{GDBN} how to connect to the 960 in several ways:
-@cindex shared libraries
-@ifclear HPPA
-@c added HP-UX -- Kim (HP writer)
-@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
-libraries.
-@end ifclear
-@ifset HPPA
-@value{GDBN} supports HP-UX shared libraries.
-@end ifset
-@value{GDBN} automatically loads symbol definitions from shared libraries
-when you use the @code{run} command, or when you examine a core file.
-(Before you issue the @code{run} command, @value{GDBN} does not understand
-references to a function in a shared library, however---unless you are
-debugging a core file).
-@ifset HPPA
-If the program loads a library explicitly, @value{GDBN} automatically
-loads the symbols at the time of the @code{shl_load} call.
-@end ifset
-@c FIXME: some @value{GDBN} release may permit some refs to undef
-@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
-@c FIXME...lib; check this from time to time when updating manual
+@itemize @bullet
+@item
+Through command line options specifying serial port, version of the
+Nindy protocol, and communications speed;
-@table @code
-@kindex info sharedlibrary
-@kindex info share
-@item info share
-@itemx info sharedlibrary
-Print the names of the shared libraries which are currently loaded.
+@item
+By responding to a prompt on startup;
-@kindex sharedlibrary
-@kindex share
-@item sharedlibrary @var{regex}
-@itemx share @var{regex}
+@item
+By using the @code{target} command at any point during your @value{GDBN}
+session. @xref{Target Commands, ,Commands for managing targets}.
-Load shared object library symbols for files matching a
-Unix regular expression.
-As with files loaded automatically, it only loads shared libraries
-required by your program for a core file or after typing @code{run}. If
-@var{regex} is omitted all shared libraries required by your program are
-loaded.
-@end table
+@end itemize
+
+@cindex download to Nindy-960
+With the Nindy interface to an Intel 960 board, @code{load}
+downloads @var{filename} to the 960 as well as adding its symbols in
+@value{GDBN}.
-@ifset HPPA
-@value{GDBN} detects the loading of a shared library and automatically
-reads in symbols from the newly loaded library, up to a threshold that
-is initially set but that you can modify if you wish.
+@menu
+* Nindy Startup:: Startup with Nindy
+* Nindy Options:: Options for Nindy
+* Nindy Reset:: Nindy reset command
+@end menu
-Beyond that threshold, symbols from shared libraries must be explicitly
-loaded. To load these symbols, use the command @code{sharedlibrary}
-@var{filename}. The base address of the shared library is determined
-automatically by @value{GDBN} and need not be specified.
+@node Nindy Startup
+@subsubsection Startup with Nindy
-To display or set the threshold, use the commands:
+If you simply start @code{@value{GDBP}} without using any command-line
+options, you are prompted for what serial port to use, @emph{before} you
+reach the ordinary @value{GDBN} prompt:
+
+@example
+Attach /dev/ttyNN -- specify NN, or "quit" to quit:
+@end example
+
+@noindent
+Respond to the prompt with whatever suffix (after @samp{/dev/tty})
+identifies the serial port you want to use. You can, if you choose,
+simply start up with no Nindy connection by responding to the prompt
+with an empty line. If you do this and later wish to attach to Nindy,
+use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
+
+@node Nindy Options
+@subsubsection Options for Nindy
+
+These are the startup options for beginning your @value{GDBN} session with a
+Nindy-960 board attached:
@table @code
-@kindex set auto-solib-add
-@item set auto-solib-add @var{threshold}
-Set the autoloading size threshold, in megabytes. If @var{threshold} is
-nonzero, symbols from all shared object libraries will be loaded
-automatically when the inferior begins execution or when the dynamic
-linker informs @value{GDBN} that a new library has been loaded, until
-the symbol table of the program and libraries exceeds this threshold.
-Otherwise, symbols must be loaded manually, using the
-@code{sharedlibrary} command. The default threshold is 100 megabytes.
+@item -r @var{port}
+Specify the serial port name of a serial interface to be used to connect
+to the target system. This option is only available when @value{GDBN} is
+configured for the Intel 960 target architecture. You may specify
+@var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
+device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
+suffix for a specific @code{tty} (e.g. @samp{-r a}).
+
+@item -O
+(An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
+the ``old'' Nindy monitor protocol to connect to the target system.
+This option is only available when @value{GDBN} is configured for the Intel 960
+target architecture.
-@kindex show auto-solib-add
-@item show auto-solib-add
-Display the current autoloading size threshold, in megabytes.
+@quotation
+@emph{Warning:} if you specify @samp{-O}, but are actually trying to
+connect to a target system that expects the newer protocol, the connection
+fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
+attempts to reconnect at several different line speeds. You can abort
+this process with an interrupt.
+@end quotation
+
+@item -brk
+Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
+system, in an attempt to reset it, before connecting to a Nindy target.
+
+@quotation
+@emph{Warning:} Many target systems do not have the hardware that this
+requires; it only works with a few boards.
+@end quotation
@end table
-@end ifset
-@node Symbol Errors, , Files, GDB Files
-@section Errors reading symbol files
+The standard @samp{-b} option controls the line speed used on the serial
+port.
-While reading a symbol file, @value{GDBN} occasionally encounters problems,
-such as symbol types it does not recognize, or known bugs in compiler
-output. By default, @value{GDBN} does not notify you of such problems, since
-they are relatively common and primarily of interest to people
-debugging compilers. If you are interested in seeing information
-about ill-constructed symbol tables, you can either ask @value{GDBN} to print
-only one message about each such type of problem, no matter how many
-times the problem occurs; or you can ask @value{GDBN} to print more messages,
-to see how many times the problems occur, with the @code{set
-complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
-messages}).
+@c @group
+@node Nindy Reset
+@subsubsection Nindy reset command
-The messages currently printed, and their meanings, include:
+@table @code
+@item reset
+@kindex reset
+For a Nindy target, this command sends a ``break'' to the remote target
+system; this is only useful if the target has been equipped with a
+circuit to perform a hard reset (or some other interesting action) when
+a break is detected.
+@end table
+@c @end group
+
+@node M32R/D
+@subsection Mitsubishi M32R/D
@table @code
-@item inner block not inside outer block in @var{symbol}
-The symbol information shows where symbol scopes begin and end
-(such as at the start of a function or a block of statements). This
-error indicates that an inner scope block is not fully contained
-in its outer scope blocks.
+@kindex target m32r
+@item target m32r @var{dev}
+Mitsubishi M32R/D ROM monitor.
-@value{GDBN} circumvents the problem by treating the inner block as if it had
-the same scope as the outer block. In the error message, @var{symbol}
-may be shown as ``@code{(don't know)}'' if the outer block is not a
-function.
+@end table
-@item block at @var{address} out of order
+@node M68K
+@subsection M68k
-The symbol information for symbol scope blocks should occur in
-order of increasing addresses. This error indicates that it does not
-do so.
+The Motorola m68k configuration includes ColdFire support, and
+target command for the following ROM monitors.
-@value{GDBN} does not circumvent this problem, and has trouble
-locating symbols in the source file whose symbols it is reading. (You
-can often determine what source file is affected by specifying
-@code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and
-messages}.)
+@table @code
-@item bad block start address patched
+@kindex target abug
+@item target abug @var{dev}
+ABug ROM monitor for M68K.
-The symbol information for a symbol scope block has a start address
-smaller than the address of the preceding source line. This is known
-to occur in the SunOS 4.1.1 (and earlier) C compiler.
+@kindex target cpu32bug
+@item target cpu32bug @var{dev}
+CPU32BUG monitor, running on a CPU32 (M68K) board.
-@value{GDBN} circumvents the problem by treating the symbol scope block as
-starting on the previous source line.
+@kindex target dbug
+@item target dbug @var{dev}
+dBUG ROM monitor for Motorola ColdFire.
-@item bad string table offset in symbol @var{n}
+@kindex target est
+@item target est @var{dev}
+EST-300 ICE monitor, running on a CPU32 (M68K) board.
-@cindex foo
-Symbol number @var{n} contains a pointer into the string table which is
-larger than the size of the string table.
+@kindex target rom68k
+@item target rom68k @var{dev}
+ROM 68K monitor, running on an M68K IDP board.
-@value{GDBN} circumvents the problem by considering the symbol to have the
-name @code{foo}, which may cause other problems if many symbols end up
-with this name.
+@end table
-@item unknown symbol type @code{0x@var{nn}}
+If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
+instead have only a single special target command:
-The symbol information contains new data types that @value{GDBN} does
-not yet know how to read. @code{0x@var{nn}} is the symbol type of the
-misunderstood information, in hexadecimal.
+@table @code
-@value{GDBN} circumvents the error by ignoring this symbol information.
-This usually allows you to debug your program, though certain symbols
-are not accessible. If you encounter such a problem and feel like
-debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
-on @code{complain}, then go up to the function @code{read_dbx_symtab}
-and examine @code{*bufp} to see the symbol.
+@kindex target es1800
+@item target es1800 @var{dev}
+ES-1800 emulator for M68K.
-@item stub type has NULL name
+@end table
-@value{GDBN} could not find the full definition for a struct or class.
+[context?]
-@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
-The symbol information for a C++ member function is missing some
-information that recent versions of the compiler should have output for
-it.
+@table @code
-@item info mismatch between compiler and debugger
+@kindex target rombug
+@item target rombug @var{dev}
+ROMBUG ROM monitor for OS/9000.
-@value{GDBN} could not parse a type specification output by the compiler.
+@end table
+
+@node M88K
+@subsection M88K
+
+@table @code
+
+@kindex target bug
+@item target bug @var{dev}
+BUG monitor, running on a MVME187 (m88k) board.
@end table
-@node Targets, Controlling GDB, GDB Files, Top
-@chapter Specifying a Debugging Target
+@node MIPS Embedded
+@subsection MIPS Embedded
-@cindex debugging target
-@kindex target
+@cindex MIPS boards
+@value{GDBN} can use the MIPS remote debugging protocol to talk to a
+MIPS board attached to a serial line. This is available when
+you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
-A @dfn{target} is the execution environment occupied by your program.
-@ifclear HPPA
-Often, @value{GDBN} runs in the same host environment as your program; in
-that case, the debugging target is specified as a side effect when you
-use the @code{file} or @code{core} commands. When you need more
-flexibility---for example, running @value{GDBN} on a physically separate
-host, or controlling a standalone system over a serial port or a
-realtime system over a TCP/IP connection---you
-@end ifclear
-@ifset HPPA
-On HP-UX systems, @value{GDBN} has been configured to support debugging
-of processes running on the PA-RISC architecture. This means that the
-only possible targets are:
+@need 1000
+Use these @value{GDBN} commands to specify the connection to your target board:
-@itemize @bullet
-@item
-An executable that has been compiled and linked to run on HP-UX
+@table @code
+@item target mips @var{port}
+@kindex target mips @var{port}
+To run a program on the board, start up @code{@value{GDBP}} with the
+name of your program as the argument. To connect to the board, use the
+command @samp{target mips @var{port}}, where @var{port} is the name of
+the serial port connected to the board. If the program has not already
+been downloaded to the board, you may use the @code{load} command to
+download it. You can then use all the usual @value{GDBN} commands.
+
+For example, this sequence connects to the target board through a serial
+port, and loads and runs a program called @var{prog} through the
+debugger:
-@item
-A live HP-UX process, either started by @value{GDBN} (with the
-@code{run} command) or started outside of @value{GDBN} and attached to
-(with the @code{attach} command)
+@example
+host$ @value{GDBP} @var{prog}
+@value{GDBN} is free software and @dots{}
+(@value{GDBP}) target mips /dev/ttyb
+(@value{GDBP}) load @var{prog}
+(@value{GDBP}) run
+@end example
-@item
-A core file generated by an HP-UX process that previously aborted
-execution
-@end itemize
+@item target mips @var{hostname}:@var{portnumber}
+On some @value{GDBN} host configurations, you can specify a TCP
+connection (for instance, to a serial line managed by a terminal
+concentrator) instead of a serial port, using the syntax
+@samp{@var{hostname}:@var{portnumber}}.
-@value{GDBN} on HP-UX has not been configured to support remote
-debugging, or to support programs running on other platforms. You
-can use the @code{target} command to specify one of the target types
-configured for @value{GDBN} (@pxref{Target Commands, ,Commands for managing
-targets}).
-@end ifset
+@item target pmon @var{port}
+@kindex target pmon @var{port}
+PMON ROM monitor.
-@menu
-* Active Targets:: Active targets
-* Target Commands:: Commands for managing targets
-* Byte Order:: Choosing target byte order
-* Remote:: Remote debugging
+@item target ddb @var{port}
+@kindex target ddb @var{port}
+NEC's DDB variant of PMON for Vr4300.
-@end menu
+@item target lsi @var{port}
+@kindex target lsi @var{port}
+LSI variant of PMON.
-@node Active Targets, Target Commands, Targets, Targets
-@section Active targets
+@kindex target r3900
+@item target r3900 @var{dev}
+Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
-@cindex stacking targets
-@cindex active targets
-@cindex multiple targets
+@kindex target array
+@item target array @var{dev}
+Array Tech LSI33K RAID controller board.
-There are three classes of targets: processes, core files, and
-executable files. @value{GDBN} can work concurrently on up to three
-active targets, one in each class. This allows you to (for example)
-start a process and inspect its activity without abandoning your work on
-a core file.
+@end table
-For example, if you execute @samp{gdb a.out}, then the executable file
-@code{a.out} is the only active target. If you designate a core file as
-well---presumably from a prior run that crashed and coredumped---then
-@value{GDBN} has two active targets and uses them in tandem, looking
-first in the corefile target, then in the executable file, to satisfy
-requests for memory addresses. (Typically, these two classes of target
-are complementary, since core files contain only a program's
-read-write memory---variables and so on---plus machine status, while
-executable files contain only the program text and initialized data.)
-When you type @code{run}, your executable file becomes an active process
-target as well. When a process target is active, all @value{GDBN}
-commands requesting memory addresses refer to that target; addresses in
-an active core file or executable file target are obscured while the
-process target is active.
+@noindent
+@value{GDBN} also supports these special commands for MIPS targets:
-Use the @code{core-file} and @code{exec-file} commands to select a new
-core file or executable target (@pxref{Files, ,Commands to specify
-files}). To specify as a target a process that is already running, use
-the @code{attach} command (@pxref{Attach, ,Debugging an already-running
-process}).
+@table @code
+@item set processor @var{args}
+@itemx show processor
+@kindex set processor @var{args}
+@kindex show processor
+Use the @code{set processor} command to set the type of MIPS
+processor when you want to access processor-type-specific registers.
+For example, @code{set processor @var{r3041}} tells @value{GDBN}
+to use the CPU registers appropriate for the 3041 chip.
+Use the @code{show processor} command to see what MIPS processor @value{GDBN}
+is using. Use the @code{info reg} command to see what registers
+@value{GDBN} is using.
+
+@item set mipsfpu double
+@itemx set mipsfpu single
+@itemx set mipsfpu none
+@itemx show mipsfpu
+@kindex set mipsfpu
+@kindex show mipsfpu
+@cindex MIPS remote floating point
+@cindex floating point, MIPS remote
+If your target board does not support the MIPS floating point
+coprocessor, you should use the command @samp{set mipsfpu none} (if you
+need this, you may wish to put the command in your @value{GDBN} init
+file). This tells @value{GDBN} how to find the return value of
+functions which return floating point values. It also allows
+@value{GDBN} to avoid saving the floating point registers when calling
+functions on the board. If you are using a floating point coprocessor
+with only single precision floating point support, as on the @sc{r4650}
+processor, use the command @samp{set mipsfpu single}. The default
+double precision floating point coprocessor may be selected using
+@samp{set mipsfpu double}.
+
+In previous versions the only choices were double precision or no
+floating point, so @samp{set mipsfpu on} will select double precision
+and @samp{set mipsfpu off} will select no floating point.
+
+As usual, you can inquire about the @code{mipsfpu} variable with
+@samp{show mipsfpu}.
+
+@item set remotedebug @var{n}
+@itemx show remotedebug
+@kindex set remotedebug@r{, MIPS protocol}
+@kindex show remotedebug@r{, MIPS protocol}
+@cindex @code{remotedebug}, MIPS protocol
+@cindex MIPS @code{remotedebug} protocol
+@c FIXME! For this to be useful, you must know something about the MIPS
+@c FIXME...protocol. Where is it described?
+You can see some debugging information about communications with the board
+by setting the @code{remotedebug} variable. If you set it to @code{1} using
+@samp{set remotedebug 1}, every packet is displayed. If you set it
+to @code{2}, every character is displayed. You can check the current value
+at any time with the command @samp{show remotedebug}.
+
+@item set timeout @var{seconds}
+@itemx set retransmit-timeout @var{seconds}
+@itemx show timeout
+@itemx show retransmit-timeout
+@cindex @code{timeout}, MIPS protocol
+@cindex @code{retransmit-timeout}, MIPS protocol
+@kindex set timeout
+@kindex show timeout
+@kindex set retransmit-timeout
+@kindex show retransmit-timeout
+You can control the timeout used while waiting for a packet, in the MIPS
+remote protocol, with the @code{set timeout @var{seconds}} command. The
+default is 5 seconds. Similarly, you can control the timeout used while
+waiting for an acknowledgement of a packet with the @code{set
+retransmit-timeout @var{seconds}} command. The default is 3 seconds.
+You can inspect both values with @code{show timeout} and @code{show
+retransmit-timeout}. (These commands are @emph{only} available when
+@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
+
+The timeout set by @code{set timeout} does not apply when @value{GDBN}
+is waiting for your program to stop. In that case, @value{GDBN} waits
+forever because it has no way of knowing how long the program is going
+to run before stopping.
+@end table
-@node Target Commands, Byte Order, Active Targets, Targets
-@section Commands for managing targets
+@node PowerPC
+@subsection PowerPC
@table @code
-@item target @var{type} @var{parameters}
-Connects the @value{GDBN} 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.
-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.
+@kindex target dink32
+@item target dink32 @var{dev}
+DINK32 ROM monitor.
-The @code{target} command does not repeat if you press @key{RET} again
-after executing the command.
+@kindex target ppcbug
+@item target ppcbug @var{dev}
+@kindex target ppcbug1
+@item target ppcbug1 @var{dev}
+PPCBUG ROM monitor for PowerPC.
-@kindex help target
-@item help target
-Displays the names of all targets available. To display targets
-currently selected, use either @code{info target} or @code{info files}
-(@pxref{Files, ,Commands to specify files}).
+@kindex target sds
+@item target sds @var{dev}
+SDS monitor, running on a PowerPC board (such as Motorola's ADS).
-@item help target @var{name}
-Describe a particular target, including any parameters necessary to
-select it.
+@end table
-@kindex set gnutarget
-@item set gnutarget @var{args}
-@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
-knows whether it is reading an @dfn{executable},
-a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
-with the @code{set gnutarget} command. Unlike most @code{target} commands,
-with @code{gnutarget} the @code{target} refers to a program, not a machine.
+@node PA
+@subsection HP PA Embedded
-@emph{Warning:} To specify a file format with @code{set gnutarget},
-you must know the actual BFD name.
+@table @code
-@noindent @xref{Files, , Commands to specify files}.
+@kindex target op50n
+@item target op50n @var{dev}
+OP50N monitor, running on an OKI HPPA board.
+
+@kindex target w89k
+@item target w89k @var{dev}
+W89K monitor, running on a Winbond HPPA board.
-@kindex show gnutarget
-@item show gnutarget
-Use the @code{show gnutarget} command to display what file format
-@code{gnutarget} is set to read. If you have not set @code{gnutarget},
-@value{GDBN} will determine the file format for each file automatically,
-and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
@end table
-@ifclear HPPA
-Here are some common targets (available, or not, depending on the GDB
-configuration):
-@end ifclear
-@ifset HPPA
-These are the valid targets on HP-UX systems:
-@end ifset
+@node SH
+@subsection Hitachi SH
@table @code
-@kindex target exec
-@item target exec @var{program}
-An executable file. @samp{target exec @var{program}} is the same as
-@samp{exec-file @var{program}}.
-@kindex target core
-@item target core @var{filename}
-A core dump file. @samp{target core @var{filename}} is the same as
-@samp{core-file @var{filename}}.
+@kindex target hms@r{, with Hitachi SH}
+@item target hms @var{dev}
+A Hitachi SH board attached via serial line to your host. Use special
+commands @code{device} and @code{speed} to control the serial line and
+the communications speed used.
-@kindex target remote
-@item target remote @var{dev}
-Remote serial target in GDB-specific protocol. The argument @var{dev}
-specifies what serial device to use for the connection (e.g.
-@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote}
-now supports the @code{load} command. This is only useful if you have
-some other way of getting the stub to the target system, and you can put
-it somewhere in memory where it won't get clobbered by the download.
+@kindex target e7000@r{, with Hitachi SH}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi SH.
+
+@kindex target sh3@r{, with SH}
+@kindex target sh3e@r{, with SH}
+@item target sh3 @var{dev}
+@item target sh3e @var{dev}
+Hitachi SH-3 and SH-3E target systems.
-@ifclear HPPA
-@kindex target sim
-@item target sim
-CPU simulator. @xref{Simulator,,Simulated CPU Target}.
-@end ifclear
@end table
-The following targets are all CPU-specific, and only available for
-specific configurations.
-@c should organize by CPU
+@node Sparclet
+@subsection Tsqware Sparclet
+
+@cindex Sparclet
+
+@value{GDBN} enables developers to debug tasks running on
+Sparclet targets from a Unix host.
+@value{GDBN} uses code that runs on
+both the Unix host and on the Sparclet target. The program
+@code{@value{GDBP}} is installed and executed on the Unix host.
@table @code
+@item remotetimeout @var{args}
+@kindex remotetimeout
+@value{GDBN} supports the option @code{remotetimeout}.
+This option is set by the user, and @var{args} represents the number of
+seconds @value{GDBN} waits for responses.
+@end table
-@kindex target abug
-@item target abug @var{dev}
-ABug ROM monitor for M68K.
+@cindex compiling, on Sparclet
+When compiling for debugging, include the options @samp{-g} to get debug
+information and @samp{-Ttext} to relocate the program to where you wish to
+load it on the target. You may also want to add the options @samp{-n} or
+@samp{-N} in order to reduce the size of the sections. Example:
-@kindex target adapt
-@item target adapt @var{dev}
-Adapt monitor for A29K.
+@example
+sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
+@end example
-@kindex target amd-eb
-@item target amd-eb @var{dev} @var{speed} @var{PROG}
-@cindex AMD EB29K
-Remote PC-resident AMD EB29K board, attached over serial lines.
-@var{dev} is the serial device, as for @code{target remote};
-@var{speed} allows you to specify the linespeed; and @var{PROG} is the
-name of the program to be debugged, as it appears to DOS on the PC.
-@xref{EB29K Remote, ,The EBMON protocol for AMD29K}.
+You can use @code{objdump} to verify that the addresses are what you intended:
-@kindex target array
-@item target array @var{dev}
-Array Tech LSI33K RAID controller board.
+@example
+sparclet-aout-objdump --headers --syms prog
+@end example
-@kindex target bug
-@item target bug @var{dev}
-BUG monitor, running on a MVME187 (m88k) board.
+@cindex running, on Sparclet
+Once you have set
+your Unix execution search path to find @value{GDBN}, you are ready to
+run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
+(or @code{sparclet-aout-gdb}, depending on your installation).
-@kindex target cpu32bug
-@item target cpu32bug @var{dev}
-CPU32BUG monitor, running on a CPU32 (M68K) board.
+@value{GDBN} comes up showing the prompt:
-@kindex target dbug
-@item target dbug @var{dev}
-dBUG ROM monitor for Motorola ColdFire.
+@example
+(gdbslet)
+@end example
-@kindex target ddb
-@item target ddb @var{dev}
-NEC's DDB monitor for Mips Vr4300.
+@menu
+* Sparclet File:: Setting the file to debug
+* Sparclet Connection:: Connecting to Sparclet
+* Sparclet Download:: Sparclet download
+* Sparclet Execution:: Running and debugging
+@end menu
-@kindex target dink32
-@item target dink32 @var{dev}
-DINK32 ROM monitor for PowerPC.
+@node Sparclet File
+@subsubsection Setting file to debug
-@kindex target e7000
-@item target e7000 @var{dev}
-E7000 emulator for Hitachi H8 and SH.
+The @value{GDBN} command @code{file} lets you choose with program to debug.
-@kindex target es1800
-@item target es1800 @var{dev}
-ES-1800 emulator for M68K.
+@example
+(gdbslet) file prog
+@end example
-@kindex target est
-@item target est @var{dev}
-EST-300 ICE monitor, running on a CPU32 (M68K) board.
+@need 1000
+@value{GDBN} then attempts to read the symbol table of @file{prog}.
+@value{GDBN} locates
+the file by searching the directories listed in the command search
+path.
+If the file was compiled with debug information (option "-g"), source
+files will be searched as well.
+@value{GDBN} locates
+the source files by searching the directories listed in the directory search
+path (@pxref{Environment, ,Your program's environment}).
+If it fails
+to find a file, it displays a message such as:
-@kindex target hms
-@item target hms @var{dev}
-A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host.
-Use special commands @code{device} and @code{speed} to control the serial
-line and the communications speed used.
-@xref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}.
+@example
+prog: No such file or directory.
+@end example
-@kindex target lsi
-@item target lsi @var{dev}
-LSI ROM monitor for Mips.
+When this happens, add the appropriate directories to the search paths with
+the @value{GDBN} commands @code{path} and @code{dir}, and execute the
+@code{target} command again.
-@kindex target m32r
-@item target m32r @var{dev}
-Mitsubishi M32R/D ROM monitor.
+@node Sparclet Connection
+@subsubsection Connecting to Sparclet
-@kindex target mips
-@item target mips @var{dev}
-IDT/SIM ROM monitor for Mips.
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
+To connect to a target on serial port ``@code{ttya}'', type:
-@kindex target mon960
-@item target mon960 @var{dev}
-MON960 monitor for Intel i960.
+@example
+(gdbslet) target sparclet /dev/ttya
+Remote target sparclet connected to /dev/ttya
+main () at ../prog.c:3
+@end example
-@kindex target nindy
-@item target nindy @var{devicename}
-An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
-the name of the serial device to use for the connection, e.g.
-@file{/dev/ttya}. @xref{i960-Nindy Remote, ,@value{GDBN} with a remote i960 (Nindy)}.
+@need 750
+@value{GDBN} displays messages like these:
-@kindex target nrom
-@item target nrom @var{dev}
-NetROM ROM emulator. This target only supports downloading.
+@example
+Connected to ttya.
+@end example
-@kindex target op50n
-@item target op50n @var{dev}
-OP50N monitor, running on an OKI HPPA board.
+@node Sparclet Download
+@subsubsection Sparclet download
-@kindex target pmon
-@item target pmon @var{dev}
-PMON ROM monitor for Mips.
+@cindex download to Sparclet
+Once connected to the Sparclet target,
+you can use the @value{GDBN}
+@code{load} command to download the file from the host to the target.
+The file name and load offset should be given as arguments to the @code{load}
+command.
+Since the file format is aout, the program must be loaded to the starting
+address. You can use @code{objdump} to find out what this value is. The load
+offset is an offset which is added to the VMA (virtual memory address)
+of each of the file's sections.
+For instance, if the program
+@file{prog} was linked to text address 0x1201000, with data at 0x12010160
+and bss at 0x12010170, in @value{GDBN}, type:
-@kindex target ppcbug
-@item target ppcbug @var{dev}
-@kindex target ppcbug1
-@item target ppcbug1 @var{dev}
-PPCBUG ROM monitor for PowerPC.
+@example
+(gdbslet) load prog 0x12010000
+Loading section .text, size 0xdb0 vma 0x12010000
+@end example
-@kindex target r3900
-@item target r3900 @var{dev}
-Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
+If the code is loaded at a different address then what the program was linked
+to, you may need to use the @code{section} and @code{add-symbol-file} commands
+to tell @value{GDBN} where to map the symbol table.
-@kindex target rdi
-@item target rdi @var{dev}
-ARM Angel monitor, via RDI library interface.
-
-@kindex target rdp
-@item target rdp @var{dev}
-ARM Demon monitor.
+@node Sparclet Execution
+@subsubsection Running and debugging
-@kindex target rom68k
-@item target rom68k @var{dev}
-ROM 68K monitor, running on an M68K IDP board.
+@cindex running and debugging Sparclet programs
+You can now begin debugging the task using @value{GDBN}'s execution control
+commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
+manual for the list of commands.
-@kindex target rombug
-@item target rombug @var{dev}
-ROMBUG ROM monitor for OS/9000.
+@example
+(gdbslet) b main
+Breakpoint 1 at 0x12010000: file prog.c, line 3.
+(gdbslet) run
+Starting program: prog
+Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
+3 char *symarg = 0;
+(gdbslet) step
+4 char *execarg = "hello!";
+(gdbslet)
+@end example
-@kindex target sds
-@item target sds @var{dev}
-SDS monitor, running on a PowerPC board (such as Motorola's ADS).
+@node Sparclite
+@subsection Fujitsu Sparclite
+
+@table @code
@kindex target sparclite
@item target sparclite @var{dev}
-Fujitsu sparclite boards, used only for the purpose of loading.
-You must use an additional command to debug the program.
-For example: target remote @var{dev} using @value{GDBN} standard
+Fujitsu sparclite boards, used only for the purpose of loading.
+You must use an additional command to debug the program.
+For example: target remote @var{dev} using @value{GDBN} standard
remote protocol.
-@kindex target sh3
-@kindex target sh3e
-@item target sh3 @var{dev}
-@item target sh3e @var{dev}
-Hitachi SH-3 and SH-3E target systems.
+@end table
-@kindex target st2000
-@item target st2000 @var{dev} @var{speed}
-A Tandem ST2000 phone switch, running Tandem's STDBUG protocol. @var{dev}
-is the name of the device attached to the ST2000 serial line;
-@var{speed} is the communication line speed. The arguments are not used
-if @value{GDBN} is configured to connect to the ST2000 using TCP or Telnet.
-@xref{ST2000 Remote,,@value{GDBN} with a Tandem ST2000}.
+@node ST2000
+@subsection Tandem ST2000
-@kindex target udi
-@item target udi @var{keyword}
-Remote AMD29K target, using the AMD UDI protocol. The @var{keyword}
-argument specifies which 29K board or simulator to use. @xref{UDI29K
-Remote,,The UDI protocol for AMD29K}.
+@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
+STDBUG protocol.
-@kindex target vxworks
-@item target vxworks @var{machinename}
-A VxWorks system, attached via TCP/IP. The argument @var{machinename}
-is the target system's machine name or IP address.
-@xref{VxWorks Remote, ,@value{GDBN} and VxWorks}.
+To connect your ST2000 to the host system, see the manufacturer's
+manual. Once the ST2000 is physically attached, you can run:
-@kindex target w89k
-@item target w89k @var{dev}
-W89K monitor, running on a Winbond HPPA board.
+@example
+target st2000 @var{dev} @var{speed}
+@end example
+
+@noindent
+to establish it as your debugging environment. @var{dev} is normally
+the name of a serial device, such as @file{/dev/ttya}, connected to the
+ST2000 via a serial line. You can instead specify @var{dev} as a TCP
+connection (for example, to a serial line attached via a terminal
+concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
+
+The @code{load} and @code{attach} commands are @emph{not} defined for
+this target; you must load your program into the ST2000 as you normally
+would for standalone operation. @value{GDBN} reads debugging information
+(such as symbols) from a separate, debugging version of the program
+available on your host computer.
+@c FIXME!! This is terribly vague; what little content is here is
+@c basically hearsay.
+
+@cindex ST2000 auxiliary commands
+These auxiliary @value{GDBN} commands are available to help you with the ST2000
+environment:
+@table @code
+@item st2000 @var{command}
+@kindex st2000 @var{cmd}
+@cindex STDBUG commands (ST2000)
+@cindex commands to STDBUG (ST2000)
+Send a @var{command} to the STDBUG monitor. See the manufacturer's
+manual for available commands.
+
+@item connect
+@cindex connect (to STDBUG)
+Connect the controlling terminal to the STDBUG command monitor. When
+you are done interacting with STDBUG, typing either of two character
+sequences gets you back to the @value{GDBN} command prompt:
+@kbd{@key{RET}~.} (Return, followed by tilde and period) or
+@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
@end table
-Different targets are available on different configurations of @value{GDBN};
-your configuration may have more or fewer targets.
+@node Z8000
+@subsection Zilog Z8000
-Many remote targets require you to download the executable's code
-once you've successfully established a connection.
+@cindex Z8000
+@cindex simulator, Z8000
+@cindex Zilog Z8000 simulator
-@table @code
+When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
+a Z8000 simulator.
-@kindex load @var{filename}
-@item load @var{filename}
-Depending on what remote debugging facilities are configured into
-@value{GDBN}, the @code{load} command may be available. Where it exists, it
-is meant to make @var{filename} (an executable) available for debugging
-on the remote system---by downloading, or dynamic linking, for example.
-@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
-the @code{add-symbol-file} command.
+For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
+unsegmented variant of the Z8000 architecture) or the Z8001 (the
+segmented variant). The simulator recognizes which architecture is
+appropriate by inspecting the object code.
-If your @value{GDBN} does not have a @code{load} command, attempting to
-execute it gets the error message ``@code{You can't do that when your
-target is @dots{}}''
+@table @code
+@item target sim @var{args}
+@kindex sim
+@kindex target sim@r{, with Z8000}
+Debug programs on a simulated CPU. If the simulator supports setup
+options, specify them via @var{args}.
+@end table
-The file is loaded at whatever address is specified in the executable.
-For some object file formats, you can specify the load address when you
-link the program; for other formats, like a.out, the object file format
-specifies a fixed address.
-@c FIXME! This would be a good place for an xref to the GNU linker doc.
+@noindent
+After specifying this target, you can debug programs for the simulated
+CPU in the same style as programs for your host computer; use the
+@code{file} command to load a new program image, the @code{run} command
+to run your program, and so on.
-On VxWorks, @code{load} links @var{filename} dynamically on the
-current target system as well as adding its symbols in @value{GDBN}.
+As well as making available all the usual machine registers
+(@pxref{Registers, ,Registers}), the Z8000 simulator provides three
+additional items of information as specially named registers:
-@cindex download to Nindy-960
-With the Nindy interface to an Intel 960 board, @code{load}
-downloads @var{filename} to the 960 as well as adding its symbols in
-@value{GDBN}.
+@table @code
-@cindex download to H8/300 or H8/500
-@cindex H8/300 or H8/500 download
-@cindex download to Hitachi SH
-@cindex Hitachi SH download
-When you select remote debugging to a Hitachi SH, H8/300, or H8/500 board
-(@pxref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}),
-the @code{load} command downloads your program to the Hitachi board and also
-opens it as the current executable target for @value{GDBN} on your host
-(like the @code{file} command).
+@item cycles
+Counts clock-ticks in the simulator.
+
+@item insts
+Counts instructions run in the simulator.
+
+@item time
+Execution time in 60ths of a second.
-@code{load} does not repeat if you press @key{RET} again after using it.
@end table
-@node Byte Order, Remote, Target Commands, Targets
-@section Choosing target byte order
+You can refer to these values in @value{GDBN} expressions with the usual
+conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
+conditional breakpoint that suspends only after at least 5000
+simulated clock ticks.
-@cindex choosing target byte order
-@cindex target byte order
-@kindex set endian big
-@kindex set endian little
-@kindex set endian auto
-@kindex show endian
+@node Architectures
+@section Architectures
-Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
-offer the ability to run either big-endian or little-endian byte
-orders. Usually the executable or symbol will include a bit to
-designate the endian-ness, and you will not need to worry about
-which to use. However, you may still find it useful to adjust
-GDB's idea of processor endian-ness manually.
+This section describes characteristics of architectures that affect
+all uses of @value{GDBN} with the architecture, both native and cross.
-@table @code
-@kindex set endian big
-@item set endian big
-Instruct @value{GDBN} to assume the target is big-endian.
+@menu
+* A29K::
+* Alpha::
+* MIPS::
+@end menu
-@kindex set endian little
-@item set endian little
-Instruct @value{GDBN} to assume the target is little-endian.
+@node A29K
+@subsection A29K
-@kindex set endian auto
-@item set endian auto
-Instruct @value{GDBN} to use the byte order associated with the
-executable.
+@table @code
-@item show endian
-Display @value{GDBN}'s current idea of the target byte order.
+@kindex set rstack_high_address
+@cindex AMD 29K register stack
+@cindex register stack, AMD29K
+@item set rstack_high_address @var{address}
+On AMD 29000 family processors, registers are saved in a separate
+@dfn{register stack}. There is no way for @value{GDBN} to determine the
+extent of this stack. Normally, @value{GDBN} just assumes that the
+stack is ``large enough''. This may result in @value{GDBN} referencing
+memory locations that do not exist. If necessary, you can get around
+this problem by specifying the ending address of the register stack with
+the @code{set rstack_high_address} command. The argument should be an
+address, which you probably want to precede with @samp{0x} to specify in
+hexadecimal.
+
+@kindex show rstack_high_address
+@item show rstack_high_address
+Display the current limit of the register stack, on AMD 29000 family
+processors.
@end table
-Note that these commands merely adjust interpretation of symbolic
-data on the host, and that they have absolutely no effect on the
-target system.
+@node Alpha
+@subsection Alpha
-@node Remote, , Byte Order, Targets
-@section Remote debugging
-@cindex remote debugging
+See the following section.
-If you are trying to debug a program running on a machine that cannot run
-@value{GDBN} in the usual way, it is often useful to use remote debugging.
-For example, you might use remote debugging on an operating system kernel,
-or on a small system which does not have a general purpose operating system
-powerful enough to run a full-featured debugger.
+@node MIPS
+@subsection MIPS
-Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
-to make this work with particular debugging targets. In addition,
-@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
-but not specific to any particular target system) which you can use if you
-write the remote stubs---the code that runs on the remote system to
-communicate with @value{GDBN}.
+@cindex stack on Alpha
+@cindex stack on MIPS
+@cindex Alpha stack
+@cindex MIPS stack
+Alpha- and MIPS-based computers use an unusual stack frame, which
+sometimes requires @value{GDBN} to search backward in the object code to
+find the beginning of a function.
-Other remote targets may be available in your
-configuration of @value{GDBN}; use @code{help target} to list them.
+@cindex response time, MIPS debugging
+To improve response time (especially for embedded applications, where
+@value{GDBN} may be restricted to a slow serial line for this search)
+you may want to limit the size of this search, using one of these
+commands:
-@c Text on starting up GDB in various specific cases; it goes up front
-@c in manuals configured for any of those particular situations, here
-@c otherwise.
-@menu
-* Remote Serial:: @value{GDBN} remote serial protocol
-* i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy)
-* UDI29K Remote:: The UDI protocol for AMD29K
-* EB29K Remote:: The EBMON protocol for AMD29K
-* VxWorks Remote:: @value{GDBN} and VxWorks
-* ST2000 Remote:: @value{GDBN} with a Tandem ST2000
-* Hitachi Remote:: @value{GDBN} and Hitachi Microprocessors
-* MIPS Remote:: @value{GDBN} and MIPS boards
-* Sparclet Remote:: @value{GDBN} and Sparclet boards
-* Simulator:: Simulated CPU target
-@end menu
+@table @code
+@cindex @code{heuristic-fence-post} (Alpha, MIPS)
+@item set heuristic-fence-post @var{limit}
+Restrict @value{GDBN} to examining at most @var{limit} bytes in its
+search for the beginning of a function. A value of @var{0} (the
+default) means there is no limit. However, except for @var{0}, the
+larger the limit the more bytes @code{heuristic-fence-post} must search
+and therefore the longer it takes to run.
+
+@item show heuristic-fence-post
+Display the current limit.
+@end table
-@include remote.texi
+@noindent
+These commands are available @emph{only} when @value{GDBN} is configured
+for debugging programs on Alpha or MIPS processors.
@node Controlling GDB
@chapter Controlling @value{GDBN}
-You can alter the way @value{GDBN} interacts with you by using
-the @code{set} command. For commands controlling how @value{GDBN} displays
-data, @pxref{Print Settings, ,Print settings}; other settings are described
-here.
+You can alter the way @value{GDBN} interacts with you by using the
+@code{set} command. For commands controlling how @value{GDBN} displays
+data, see @ref{Print Settings, ,Print settings}. Other settings are
+described here.
@menu
* Prompt:: Prompt
* Screen Size:: Screen size
* Numbers:: Numbers
* Messages/Warnings:: Optional warnings and messages
+* Debugging Output:: Optional messages about internal happenings
@end menu
-@node Prompt, Editing, Controlling GDB, Controlling GDB
+@node Prompt
@section Prompt
@cindex prompt
called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
can change the prompt string with the @code{set prompt} command. For
instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
-the prompt in one of the @value{GDBN} sessions so that you can always tell
+the prompt in one of the @value{GDBN} sessions so that you can always tell
which one you are talking to.
-@emph{Note:} @code{set prompt} no longer adds a space for you after the
+@emph{Note:} @code{set prompt} does not add a space for you after the
prompt you set. This allows you to set a prompt which ends in a space
or a prompt that does not.
Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
@end table
-@node Editing, History, Prompt, Controlling GDB
+@node Editing
@section Command editing
@cindex readline
@cindex command line editing
Show whether command line editing is enabled.
@end table
-@node History, Screen Size, Editing, Controlling GDB
+@node History
@section Command history
@value{GDBN} can keep track of the commands you type during your
exits. You can access this list through history expansion or through
the history command editing characters listed below. This file defaults
to the value of the environment variable @code{GDBHISTFILE}, or to
-@file{./.gdb_history} if this variable is not set.
+@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
+is not set.
@cindex history save
@kindex set history save
@end table
@table @code
-@kindex show commands
+@kindex shows
@item show commands
Display the last ten commands in the command history.
Print ten commands just after the commands last printed.
@end table
-@node Screen Size, Numbers, History, Controlling GDB
+@node Screen Size
@section Screen size
@cindex size of screen
@cindex pauses in output
printed, @value{GDBN} tries to break the line at a readable place,
rather than simply letting it overflow onto the following line.
-Normally @value{GDBN} knows the size of the screen from the termcap data base
+Normally @value{GDBN} knows the size of the screen from the terminal
+driver software. For example, on Unix @value{GDBN} uses 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,
+@code{stty rows} and @code{stty cols} settings. If this is not correct,
you can override it with the @code{set height} and @code{set
width} commands:
a screen width of @var{cpl} characters. The associated @code{show}
commands display the current settings.
-If you specify a height of zero lines, @value{GDBN} does not pause during
-output no matter how long the output is. This is useful if output is to a
+If you specify a height of zero lines, @value{GDBN} does 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.
Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
from wrapping its output.
@end table
-@node Numbers, Messages/Warnings, Screen Size, Controlling GDB
+@node Numbers
@section Numbers
@cindex number representation
@cindex entering numbers
-You can always enter numbers in octal, decimal, or hexadecimal in @value{GDBN} by
-the usual conventions: octal numbers begin with @samp{0}, decimal
-numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}.
-Numbers that begin with none of these are, by default, entered in base
-10; likewise, the default display for numbers---when no particular
-format is specified---is base 10. You can change the default base for
-both input and output with the @code{set radix} command.
+You can always enter numbers in octal, decimal, or hexadecimal in
+@value{GDBN} by the usual conventions: octal numbers begin with
+@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
+begin with @samp{0x}. Numbers that begin with none of these are, by
+default, entered in base 10; likewise, the default display for
+numbers---when no particular format is specified---is base 10. You can
+change the default base for both input and output with the @code{set
+radix} command.
@table @code
@kindex set input-radix
Display the current default base for numeric display.
@end table
-@node Messages/Warnings, , Numbers, Controlling GDB
+@node Messages/Warnings
@section Optional warnings and messages
-By default, @value{GDBN} is silent about its inner workings. If you are running
-on a slow machine, you may want to use the @code{set verbose} command.
-This makes @value{GDBN} tell you when it does a lengthy internal operation, so
-you will not think it has crashed.
+By default, @value{GDBN} is silent about its inner workings. If you are
+running on a slow machine, you may want to use the @code{set verbose}
+command. This makes @value{GDBN} tell you when it does a lengthy
+internal operation, so you will not think it has crashed.
Currently, the messages controlled by @code{set verbose} are those
which announce that the symbol table for a source file is being read;
Displays whether @code{set verbose} is on or off.
@end table
-By default, if @value{GDBN} encounters bugs in the symbol table of an object
-file, it is silent; but if you are debugging a compiler, you may find
-this information useful (@pxref{Symbol Errors, ,Errors reading symbol files}).
+By default, if @value{GDBN} encounters bugs in the symbol table of an
+object file, it is silent; but if you are debugging a compiler, you may
+find this information useful (@pxref{Symbol Errors, ,Errors reading
+symbol files}).
@table @code
+
@kindex set complaints
@item set complaints @var{limit}
-Permits @value{GDBN} to output @var{limit} complaints about each type of unusual
-symbols before becoming silent about the problem. Set @var{limit} to
-zero to suppress all complaints; set it to a large number to prevent
-complaints from being suppressed.
+Permits @value{GDBN} to output @var{limit} complaints about each type of
+unusual symbols before becoming silent about the problem. Set
+@var{limit} to zero to suppress all complaints; set it to a large number
+to prevent complaints from being suppressed.
@kindex show complaints
@item show complaints
Displays how many symbol complaints @value{GDBN} is permitted to produce.
+
@end table
By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
commands, you can disable this ``feature'':
@table @code
+
@kindex set confirm
@cindex flinching
@cindex confirmation
@kindex show confirm
@item show confirm
Displays state of confirmation requests.
+
+@end table
+
+@node Debugging Output
+@section Optional messages about internal happenings
+@table @code
+@kindex set debug arch
+@item set debug arch
+Turns on or off display of gdbarch debugging info. The default is off
+@kindex show debug arch
+@item show debug arch
+Displays the current state of displaying gdbarch debugging info.
+@kindex set debug event
+@item set debug event
+Turns on or off display of @value{GDBN} event debugging info. The
+default is off.
+@kindex show debug event
+@item show debug event
+Displays the current state of displaying @value{GDBN} event debugging
+info.
+@kindex set debug expression
+@item set debug expression
+Turns on or off display of @value{GDBN} expression debugging info. The
+default is off.
+@kindex show debug expression
+@item show debug expression
+Displays the current state of displaying @value{GDBN} expression
+debugging info.
+@kindex set debug overload
+@item set debug overload
+Turns on or off display of @value{GDBN} C@t{++} overload debugging
+info. This includes info such as ranking of functions, etc. The default
+is off.
+@kindex show debug overload
+@item show debug overload
+Displays the current state of displaying @value{GDBN} C@t{++} overload
+debugging info.
+@kindex set debug remote
+@cindex packets, reporting on stdout
+@cindex serial connections, debugging
+@item set debug remote
+Turns on or off display of reports on all packets sent back and forth across
+the serial line to the remote machine. The info is printed on the
+@value{GDBN} standard output stream. The default is off.
+@kindex show debug remote
+@item show debug remote
+Displays the state of display of remote packets.
+@kindex set debug serial
+@item set debug serial
+Turns on or off display of @value{GDBN} serial debugging info. The
+default is off.
+@kindex show debug serial
+@item show debug serial
+Displays the current state of displaying @value{GDBN} serial debugging
+info.
+@kindex set debug target
+@item set debug target
+Turns on or off display of @value{GDBN} target debugging info. This info
+includes what is going on at the target level of GDB, as it happens. The
+default is off.
+@kindex show debug target
+@item show debug target
+Displays the current state of displaying @value{GDBN} target debugging
+info.
+@kindex set debug varobj
+@item set debug varobj
+Turns on or off display of @value{GDBN} variable object debugging
+info. The default is off.
+@kindex show debug varobj
+@item show debug varobj
+Displays the current state of displaying @value{GDBN} variable object
+debugging info.
@end table
-@node Sequences, Emacs, Controlling GDB, Top
+@node Sequences
@chapter Canned Sequences of Commands
Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
-command lists}), @value{GDBN} provides two ways to store sequences of commands
-for execution as a unit: user-defined commands and command files.
+command lists}), @value{GDBN} provides two ways to store sequences of
+commands for execution as a unit: user-defined commands and command
+files.
@menu
* Define:: User-defined commands
* Output:: Commands for controlled output
@end menu
-@node Define, Hooks, Sequences, Sequences
+@node Define
@section User-defined commands
@cindex user-defined command
-A @dfn{user-defined command} is a sequence of @value{GDBN} commands to which
-you assign a new name as a command. This is done with the @code{define}
-command. User commands may accept up to 10 arguments separated by whitespace.
-Arguments are accessed within the user command via @var{$arg0@dots{}$arg9}.
-A trivial example:
+A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
+which you assign a new name as a command. This is done with the
+@code{define} command. User commands may accept up to 10 arguments
+separated by whitespace. Arguments are accessed within the user command
+via @var{$arg0@dots{}$arg9}. A trivial example:
@smallexample
define adder
print $arg0 + $arg1 + $arg2
@end smallexample
-@noindent To execute the command use:
+@noindent
+To execute the command use:
@smallexample
adder 1 2 3
@end smallexample
-@noindent This defines the command @code{adder}, which prints the sum of
-its three arguments. Note the arguments are text substitutions, so they may
+@noindent
+This defines the command @code{adder}, which prints the sum of
+its three arguments. Note the arguments are text substitutions, so they may
reference variables, use complex expressions, or even perform inferior
functions calls.
@table @code
+
@kindex define
@item define @var{commandname}
Define a command named @var{commandname}. If there is already a command
@kindex document
@item document @var{commandname}
Document the user-defined command @var{commandname}, so that it can be
-accessed by @code{help}. The command @var{commandname} must already be
-defined. This command reads lines of documentation just as @code{define}
-reads the lines of the command definition, ending with @code{end}.
-After the @code{document} command is finished, @code{help} on command
+accessed by @code{help}. The command @var{commandname} must already be
+defined. This command reads lines of documentation just as @code{define}
+reads the lines of the command definition, ending with @code{end}.
+After the @code{document} command is finished, @code{help} on command
@var{commandname} displays the documentation you have written.
You may use the @code{document} command again to change the
@kindex show user
@item show user
@itemx show user @var{commandname}
-Display the @value{GDBN} commands used to define @var{commandname} (but not its
-documentation). If no @var{commandname} is given, display the
+Display the @value{GDBN} commands used to define @var{commandname} (but
+not its documentation). If no @var{commandname} is given, display the
definitions for all user-defined commands.
+
@end table
When user-defined commands are executed, the
stops execution of the user-defined command.
If used interactively, commands that would ask for confirmation proceed
-without asking when used inside a user-defined command. Many @value{GDBN}
-commands that normally print messages to say what they are doing omit the
+without asking when used inside a user-defined command. Many @value{GDBN}
+commands that normally print messages to say what they are doing omit the
messages when used in a user-defined command.
-@node Hooks, Command Files, Define, Sequences
+@node Hooks
@section User-defined command hooks
-@cindex command files
+@cindex command hooks
+@cindex hooks, for commands
+@cindex hooks, pre-command
-You may define @emph{hooks}, which are a special kind of user-defined
+@kindex hook
+@kindex hook-
+You may define @dfn{hooks}, which are a special kind of user-defined
command. Whenever you run the command @samp{foo}, if the user-defined
command @samp{hook-foo} exists, it is executed (with no arguments)
before that command.
+@cindex hooks, post-command
+@kindex hookpost
+@kindex hookpost-
+A hook may also be defined which is run after the command you executed.
+Whenever you run the command @samp{foo}, if the user-defined command
+@samp{hookpost-foo} exists, it is executed (with no arguments) after
+that command. Post-execution hooks may exist simultaneously with
+pre-execution hooks, for the same command.
+
+It is valid for a hook to call the command which it hooks. If this
+occurs, the hook is not re-executed, thereby avoiding infinte recursion.
+
+@c It would be nice if hookpost could be passed a parameter indicating
+@c if the command it hooks executed properly or not. FIXME!
+
+@kindex stop@r{, a pseudo-command}
In addition, a pseudo-command, @samp{stop} exists. Defining
(@samp{hook-stop}) makes the associated commands execute every time
execution stops in your program: before breakpoint commands are run,
end
@end example
+As a further example, to hook at the begining and end of the @code{echo}
+command, and to add extra text to the beginning and end of the message,
+you could define:
+
+@example
+define hook-echo
+echo <<<---
+end
+
+define hookpost-echo
+echo --->>>\n
+end
+
+(@value{GDBP}) echo Hello World
+<<<---Hello World--->>>
+(@value{GDBP})
+
+@end example
+
You can define a hook for any single-word command in @value{GDBN}, but
not for command aliases; you should define a hook for the basic command
name, e.g. @code{backtrace} rather than @code{bt}.
If you try to define a hook which does not match any known command, you
get a warning from the @code{define} command.
-@node Command Files, Output, Hooks, Sequences
+@node Command Files
@section Command files
@cindex command files
-A command file for @value{GDBN} is a file of lines that are @value{GDBN}
-commands. Comments (lines starting with @kbd{#}) may also be included.
-An empty line in a command file does nothing; it does not mean to repeat
+A command file for @value{GDBN} is a file of lines that are @value{GDBN}
+commands. Comments (lines starting with @kbd{#}) 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
@cindex @file{.gdbinit}
+@cindex @file{gdb.ini}
When you start @value{GDBN}, it automatically executes commands from its
-@dfn{init files}. These are files named @file{.gdbinit} on Unix, or
-@file{gdb.ini} on DOS/Windows. @value{GDBN} reads the init file (if
-any) in your home directory, then processes command line options and
-operands, and then reads the init file (if any) in the current working
-directory. This is so the init file in your home directory can set
-options (such as @code{set complaints}) which affect the processing of
-the command line options and operands. The init files are not executed
-if you use the @samp{-nx} option; @pxref{Mode Options, ,Choosing modes}.
+@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP
+port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the
+limitations of file names imposed by DOS filesystems.}.
+During startup, @value{GDBN} does the following:
+
+@enumerate
+@item
+Reads the init file (if any) in your home directory@footnote{On
+DOS/Windows systems, the home directory is the one pointed to by the
+@code{HOME} environment variable.}.
+
+@item
+Processes command line options and operands.
+
+@item
+Reads the init file (if any) in the current working directory.
+
+@item
+Reads command files specified by the @samp{-x} option.
+@end enumerate
+
+The init file in your home directory can set options (such as @samp{set
+complaints}) that affect subsequent processing of command line options
+and operands. Init files are not executed if you use the @samp{-nx}
+option (@pxref{Mode Options, ,Choosing modes}).
@cindex init file name
On some configurations of @value{GDBN}, the init file is known by a
different name for the specialized version's init file). These are the
environments with special init file names:
-@kindex .vxgdbinit
+@cindex @file{.vxgdbinit}
@itemize @bullet
@item
-VxWorks (Wind River Systems real-time OS): @samp{.vxgdbinit}
+VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
-@kindex .os68gdbinit
+@cindex @file{.os68gdbinit}
@item
-OS68K (Enea Data Systems real-time OS): @samp{.os68gdbinit}
+OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
-@kindex .esgdbinit
+@cindex @file{.esgdbinit}
@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @samp{.esgdbinit}
+ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
@end itemize
You can also request the execution of a command file with the
normally print messages to say what they are doing omit the messages
when called from command files.
-@node Output, , Command Files, Sequences
+@value{GDBN} also accepts command input from standard input. In this
+mode, normal output goes to standard output and error output goes to
+standard error. Errors in a command file supplied on standard input do
+not terminate execution of the command file --- execution continues with
+the next command.
+
+@example
+gdb < cmds > log 2>&1
+@end example
+
+(The syntax above will vary depending on the shell used.) This example
+will execute commands from the file @file{cmds}. All output and errors
+would be directed to @file{log}.
+
+@node Output
@section Commands for controlled output
During the execution of a command file or a user-defined command, normal
want.
@table @code
-@kindex echo
-@item echo @var{text}
-@c I do not consider backslash-space a standard C escape sequence
-@c because it is 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. @strong{No newline is 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 displaying a
-string with spaces at the beginning or the end, since leading and
-trailing spaces are otherwise trimmed from all arguments.
-To print @samp{@w{ }and foo =@w{ }}, use the command
-@samp{echo \@w{ }and foo = \@w{ }}.
+@kindex echo
+@item echo @var{text}
+@c I do not consider backslash-space a standard C escape sequence
+@c because it is 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. @strong{No newline is 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 displaying a
+string with spaces at the beginning or the end, since leading and
+trailing spaces are otherwise trimmed from all arguments.
+To print @samp{@w{ }and foo =@w{ }}, use the command
+@samp{echo \@w{ }and foo = \@w{ }}.
+
+A backslash at the end of @var{text} can be used, as in C, to continue
+the command onto subsequent lines. For example,
+
+@example
+echo This is some text\n\
+which is continued\n\
+onto several lines.\n
+@end example
+
+produces the same output as
+
+@example
+echo This is some text\n
+echo which is continued\n
+echo onto several lines.\n
+@end example
+
+@kindex output
+@item output @var{expression}
+Print the value of @var{expression} and nothing but that value: no
+newlines, no @samp{$@var{nn} = }. The value is not entered in the
+value history either. @xref{Expressions, ,Expressions}, for more information
+on expressions.
+
+@item output/@var{fmt} @var{expression}
+Print the value of @var{expression} in format @var{fmt}. You can use
+the same formats as for @code{print}. @xref{Output Formats,,Output
+formats}, for more information.
+
+@kindex printf
+@item printf @var{string}, @var{expressions}@dots{}
+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 your program were to execute the C
+subroutine
+@c FIXME: the above implies that at least all ANSI C formats are
+@c supported, but it isn't true: %E and %G don't work (or so it seems).
+@c Either this is a bug, or the manual should document what formats are
+@c supported.
+
+@example
+printf (@var{string}, @var{expressions}@dots{});
+@end example
+
+For example, you can print two values in hex like this:
+
+@smallexample
+printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
+@end smallexample
+
+The only backslash-escape sequences that you can use in the format
+string are the simple ones that consist of backslash followed by a
+letter.
+@end table
+
+@node TUI
+@chapter @value{GDBN} Text User Interface
+@cindex TUI
+
+@menu
+* TUI Overview:: TUI overview
+* TUI Keys:: TUI key bindings
+* TUI Commands:: TUI specific commands
+* TUI Configuration:: TUI configuration variables
+@end menu
+
+The @value{GDBN} Text User Interface, TUI in short,
+is a terminal interface which uses the @code{curses} library
+to show the source file, the assembly output, the program registers
+and @value{GDBN} commands in separate text windows.
+The TUI is available only when @value{GDBN} is configured
+with the @code{--enable-tui} configure option (@pxref{Configure Options}).
+
+@node TUI Overview
+@section TUI overview
+
+The TUI has two display modes that can be switched while
+@value{GDBN} runs:
+
+@itemize @bullet
+@item
+A curses (or TUI) mode in which it displays several text
+windows on the terminal.
+
+@item
+A standard mode which corresponds to the @value{GDBN} configured without
+the TUI.
+@end itemize
+
+In the TUI mode, @value{GDBN} can display several text window
+on the terminal:
+
+@table @emph
+@item command
+This window is the @value{GDBN} command window with the @value{GDBN}
+prompt and the @value{GDBN} outputs. The @value{GDBN} input is still
+managed using readline but through the TUI. The @emph{command}
+window is always visible.
+
+@item source
+The source window shows the source file of the program. The current
+line as well as active breakpoints are displayed in this window.
+The current program position is shown with the @samp{>} marker and
+active breakpoints are shown with @samp{*} markers.
+
+@item assembly
+The assembly window shows the disassembly output of the program.
+
+@item register
+This window shows the processor registers. It detects when
+a register is changed and when this is the case, registers that have
+changed are highlighted.
+
+@end table
+
+The source, assembly and register windows are attached to the thread
+and the frame position. They are updated when the current thread
+changes, when the frame changes or when the program counter changes.
+These three windows are arranged by the TUI according to several
+layouts. The layout defines which of these three windows are visible.
+The following layouts are available:
+
+@itemize @bullet
+@item
+source
+
+@item
+assembly
+
+@item
+source and assembly
+
+@item
+source and registers
+
+@item
+assembly and registers
+
+@end itemize
+
+@node TUI Keys
+@section TUI Key Bindings
+@cindex TUI key bindings
+
+The TUI installs several key bindings in the readline keymaps
+(@pxref{Command Line Editing}).
+They allow to leave or enter in the TUI mode or they operate
+directly on the TUI layout and windows. The following key bindings
+are installed for both TUI mode and the @value{GDBN} standard mode.
+
+@table @kbd
+@kindex C-x C-a
+@item C-x C-a
+@kindex C-x a
+@itemx C-x a
+@kindex C-x A
+@itemx C-x A
+Enter or leave the TUI mode. When the TUI mode is left,
+the curses window management is left and @value{GDBN} operates using
+its standard mode writing on the terminal directly. When the TUI
+mode is entered, the control is given back to the curses windows.
+The screen is then refreshed.
+
+@kindex C-x 1
+@item C-x 1
+Use a TUI layout with only one window. The layout will
+either be @samp{source} or @samp{assembly}. When the TUI mode
+is not active, it will switch to the TUI mode.
+
+Think of this key binding as the Emacs @kbd{C-x 1} binding.
+
+@kindex C-x 2
+@item C-x 2
+Use a TUI layout with at least two windows. When the current
+layout shows already two windows, a next layout with two windows is used.
+When a new layout is chosen, one window will always be common to the
+previous layout and the new one.
+
+Think of it as the Emacs @kbd{C-x 2} binding.
+
+@end table
+
+The following key bindings are handled only by the TUI mode:
+
+@table @key
+@kindex PgUp
+@item PgUp
+Scroll the active window one page up.
+
+@kindex PgDn
+@item PgDn
+Scroll the active window one page down.
+
+@kindex Up
+@item Up
+Scroll the active window one line up.
+
+@kindex Down
+@item Down
+Scroll the active window one line down.
+
+@kindex Left
+@item Left
+Scroll the active window one column left.
+
+@kindex Right
+@item Right
+Scroll the active window one column right.
+
+@kindex C-L
+@item C-L
+Refresh the screen.
+
+@end table
+
+In the TUI mode, the arrow keys are used by the active window
+for scrolling. This means they are not available for readline. It is
+necessary to use other readline key bindings such as @key{C-p}, @key{C-n},
+@key{C-b} and @key{C-f}.
+
+@node TUI Commands
+@section TUI specific commands
+@cindex TUI commands
+
+The TUI has specific commands to control the text windows.
+These commands are always available, that is they do not depend on
+the current terminal mode in which @value{GDBN} runs. When @value{GDBN}
+is in the standard mode, using these commands will automatically switch
+in the TUI mode.
+
+@table @code
+@item layout next
+@kindex layout next
+Display the next layout.
+
+@item layout prev
+@kindex layout prev
+Display the previous layout.
+
+@item layout src
+@kindex layout src
+Display the source window only.
+
+@item layout asm
+@kindex layout asm
+Display the assembly window only.
+
+@item layout split
+@kindex layout split
+Display the source and assembly window.
+
+@item layout regs
+@kindex layout regs
+Display the register window together with the source or assembly window.
+
+@item focus next | prev | src | asm | regs | split
+@kindex focus
+Set the focus to the named window.
+This command allows to change the active window so that scrolling keys
+can be affected to another window.
+
+@item refresh
+@kindex refresh
+Refresh the screen. This is similar to using @key{C-L} key.
+
+@item update
+@kindex update
+Update the source window and the current execution point.
+
+@item winheight @var{name} +@var{count}
+@itemx winheight @var{name} -@var{count}
+@kindex winheight
+Change the height of the window @var{name} by @var{count}
+lines. Positive counts increase the height, while negative counts
+decrease it.
+
+@end table
+
+@node TUI Configuration
+@section TUI configuration variables
+@cindex TUI configuration variables
+
+The TUI has several configuration variables that control the
+appearance of windows on the terminal.
+
+@table @code
+@item set tui border-kind @var{kind}
+@kindex set tui border-kind
+Select the border appearance for the source, assembly and register windows.
+The possible values are the following:
+@table @code
+@item space
+Use a space character to draw the border.
-A backslash at the end of @var{text} can be used, as in C, to continue
-the command onto subsequent lines. For example,
+@item ascii
+Use ascii characters + - and | to draw the border.
-@example
-echo This is some text\n\
-which is continued\n\
-onto several lines.\n
-@end example
+@item acs
+Use the Alternate Character Set to draw the border. The border is
+drawn using character line graphics if the terminal supports them.
-produces the same output as
+@end table
-@example
-echo This is some text\n
-echo which is continued\n
-echo onto several lines.\n
-@end example
+@item set tui active-border-mode @var{mode}
+@kindex set tui active-border-mode
+Select the attributes to display the border of the active window.
+The possible values are @code{normal}, @code{standout}, @code{reverse},
+@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}.
-@kindex output
-@item output @var{expression}
-Print the value of @var{expression} and nothing but that value: no
-newlines, no @samp{$@var{nn} = }. The value is not entered in the
-value history either. @xref{Expressions, ,Expressions}, for more information
-on expressions.
+@item set tui border-mode @var{mode}
+@kindex set tui border-mode
+Select the attributes to display the border of other windows.
+The @var{mode} can be one of the following:
+@table @code
+@item normal
+Use normal attributes to display the border.
-@item output/@var{fmt} @var{expression}
-Print the value of @var{expression} in format @var{fmt}. You can use
-the same formats as for @code{print}. @xref{Output Formats,,Output
-formats}, for more information.
+@item standout
+Use standout mode.
-@kindex printf
-@item printf @var{string}, @var{expressions}@dots{}
-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 your program were to execute the C
-subroutine
+@item reverse
+Use reverse video mode.
-@example
-printf (@var{string}, @var{expressions}@dots{});
-@end example
+@item half
+Use half bright mode.
-For example, you can print two values in hex like this:
+@item half-standout
+Use half bright and standout mode.
-@smallexample
-printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
-@end smallexample
+@item bold
+Use extra bright or bold mode.
+
+@item bold-standout
+Use extra bright or bold and standout mode.
+
+@end table
-The only backslash-escape sequences that you can use in the format
-string are the simple ones that consist of backslash followed by a
-letter.
@end table
-@node Emacs, GDB Bugs, Sequences, Top
+@node Emacs
@chapter Using @value{GDBN} under @sc{gnu} Emacs
@cindex Emacs
executable file you want to debug as an argument. This command starts
@value{GDBN} as a subprocess of Emacs, with input and output through a newly
created Emacs buffer.
-@ifset HPPA
-(Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
-@end ifset
+@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
things:
@end example
@noindent
-(preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or
+(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or
in your @file{.emacs} file) makes Emacs call the program named
``@code{mygdb}'' instead.
@kindex Epoch
@kindex inspect
-Version 18 of @sc{gnu} Emacs has a built-in window system
+Version 18 of @sc{gnu} Emacs has a built-in window system
called the @code{epoch}
environment. Users of this environment can use a new command,
@code{inspect} which performs identically to @code{print} except that
each value is printed in its own window.
@end ignore
+@include annotate.texi
+@include gdbmi.texinfo
+
@node GDB Bugs
-@c links whacked to pacify makeinfo
-@c , Command Line Editing, Emacs, Top
@chapter Reporting Bugs in @value{GDBN}
@cindex bugs in @value{GDBN}
@cindex reporting bugs in @value{GDBN}
* Bug Reporting:: How to report bugs
@end menu
-@node Bug Criteria, Bug Reporting, GDB Bugs, GDB Bugs
+@node Bug Criteria
@section Have you found a bug?
@cindex bug criteria
for improvement of @value{GDBN} are welcome in any case.
@end itemize
-@node Bug Reporting, , Bug Criteria, GDB Bugs
+@node Bug Reporting
@section How to report bugs
@cindex bug reports
@cindex @value{GDBN} bugs, reporting
-@ifclear HPPA
A number of companies and individuals offer support for @sc{gnu} products.
If you obtained @value{GDBN} from a support organization, we recommend you
contact that organization first.
@value{GDBN} to this addresses:
@example
-bug-gdb@@prep.ai.mit.edu
+bug-gdb@@gnu.org
@end example
@strong{Do not send bug reports to @samp{info-gdb}, or to
-@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
+@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
not want to receive bug reports. Those that do have arranged to receive
@samp{bug-gdb}.
Boston, MA 02111-1307
USA
@end example
-@end ifclear
-
-@ifset HPPA
-If you obtained HP GDB as part of your HP ANSI C or HP ANSI C++ compiler
-kit, report problems to your HP Support Representative.
-
-If you obtained HP GDB from the Hewlett-Packard Web site, report
-problems by electronic mail to @code{wdb-www@@ch.hp.com}.
-@end ifset
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}. If you are not sure whether to state a
The type of machine you are using, and the operating system name and
version number.
-@ifclear HPPA
@item
What compiler (and its version) was used to compile @value{GDBN}---e.g.
``@value{GCC}--2.8.1''.
-@end ifclear
@item
What compiler (and its version) was used to compile the program you are
us. If you had not told us to expect a crash, then we would not be able
to draw any conclusion from our observations.
-@ifclear HPPA
@item
If you wish to suggest changes to the @value{GDBN} source, send us context
diffs. If you even discuss something in the @value{GDBN} source, refer to
The line numbers in our development sources will not match those in your
sources. Your line numbers would convey no useful information to us.
-@end ifclear
+
@end itemize
Here are some things that are not necessary:
things without first using the debugger to find the facts.
@end itemize
-@c The readline documentation is distributed with the readline code
+@c The readline documentation is distributed with the readline code
@c and consists of the two following files:
@c rluser.texinfo
-@c inc-hist.texi
+@c inc-hist.texinfo
@c Use -I with makeinfo to point to the appropriate directory,
@c environment var TEXINPUTS with TeX.
@include rluser.texinfo
-@include inc-hist.texi
+@include inc-hist.texinfo
-@ifclear PRECONFIGURED
-@ifclear HPPA
@node Formatting Documentation
-@c links whacked to pacify makeinfo
-@c , Installing GDB, Renamed Commands, Top
@appendix Formatting Documentation
@cindex @value{GDBN} reference card
make refcard.dvi
@end example
-The @value{GDBN} reference card is designed to print in @dfn{landscape}
-mode on US ``letter'' size paper;
+The @value{GDBN} reference card is designed to print in @dfn{landscape}
+mode on US ``letter'' size paper;
that is, on a sheet 11 inches wide by 8.5 inches
high. You will need to specify this form of printing as an option to
your @sc{dvi} output program.
@end example
Then give @file{gdb.dvi} to your @sc{dvi} printing program.
-@end ifclear
-@node Installing GDB, Index, Using History Interactively, Top
+@node Installing GDB
@appendix Installing @value{GDBN}
@cindex configuring @value{GDBN}
@cindex installation
-@ifset HPPA
-If you obtain @value{GDBN} (HP WDB 0.75) as part of your HP ANSI C or
-HP ANSI C++ Developer's Kit at HP-UX Release 11.0, you do not have to
-take any special action to build or install @value{GDBN}.
-
-If you obtain @value{GDBN} (HP WDB 0.75) from an HP web site, you may
-download either a @code{swinstall}-able package or a source tree, or
-both.
-
-Most customers will want to install the @value{GDBN} binary that is part
-of the @code{swinstall}-able package. To do so, use a command of the
-form
-
-@smallexample
-/usr/sbin/swinstall -s @var{package-name} WDB
-@end smallexample
-
-Alternatively, it is possible to build @value{GDBN} from the source
-distribution. Sophisticated customers who want to modify the debugger
-sources to tailor @value{GDBN} to their their needs may wish to do this.
-The source distribution consists of a @code{tar}'ed source tree rooted
-at @file{gdb-4.16/...}. The instructions that follow describe how to
-build a @file{gdb} executable from this source tree. HP believes that
-these instructions apply to the WDB source tree that it distributes.
-However, HP does not explicitly support building a @file{gdb} for any
-non-HP platform from the WDB source tree. It may work, but HP has not
-tested it for any platforms other than those described in the WDB 0.75
-Release Notes.
-@end ifset
-
@value{GDBN} comes with a @code{configure} script that automates the process
of preparing @value{GDBN} for installation; you can then use @code{make} to
build the @code{gdb} program.
installation procedures since publishing this manual.}
@end iftex
-The @value{GDBN} distribution includes all the source code you need for
-@value{GDBN} in a single directory, whose name is usually composed by
+The @value{GDBN} distribution includes all the source code you need for
+@value{GDBN} in a single directory, whose name is usually composed by
appending the version number to @samp{gdb}.
For example, the @value{GDBN} version @value{GDBVN} distribution is in the
* Configure Options:: Summary of options for configure
@end menu
-@node Separate Objdir, Config Names, Installing GDB, Installing GDB
+@node Separate Objdir
@section Compiling @value{GDBN} in another directory
If you want to run @value{GDBN} versions for several host or target machines,
would be the same as the argument to @samp{--srcdir}, you can leave out
the @samp{--srcdir} option; it is assumed.)
-For example, with version @value{GDBVN}, you can build @value{GDBN} in a
+For example, with version @value{GDBVN}, you can build @value{GDBN} in a
separate directory for a Sun 4 like this:
@example
@file{gdb-sun4/gdb}.
One popular reason to build several @value{GDBN} configurations in separate
-directories is to configure @value{GDBN} for cross-compiling (where
-@value{GDBN} runs on one machine---the @dfn{host}---while debugging
-programs that run on another machine---the @dfn{target}).
+directories is to configure @value{GDBN} for cross-compiling (where
+@value{GDBN} runs on one machine---the @dfn{host}---while debugging
+programs that run on another machine---the @dfn{target}).
You specify a cross-debugging target by
giving the @samp{--target=@var{target}} option to @code{configure}.
if they are NFS-mounted on each of the hosts); they will not interfere
with each other.
-@node Config Names, Configure Options, Separate Objdir, Installing GDB
+@node Config Names
@section Specifying names for hosts and targets
The specifications used for hosts and targets in the @code{configure}
@code{config.sub} is also distributed in the @value{GDBN} source
directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
-@node Configure Options, , Config Names, Installing GDB
+@node Configure Options
@section @code{configure} options
Here is a summary of the @code{configure} options and arguments that
There are many other options available as well, but they are generally
needed for special purposes only.
-@end ifclear
-
-@node Index, , Installing GDB, Top
+@node Maintenance Commands
+@appendix Maintenance Commands
+@cindex maintenance commands
+@cindex internal commands
+
+In addition to commands intended for @value{GDBN} users, @value{GDBN}
+includes a number of commands intended for @value{GDBN} developers.
+These commands are provided here for reference.
+
+@table @code
+@kindex maint info breakpoints
+@item @anchor{maint info breakpoints}maint info breakpoints
+Using the same format as @samp{info breakpoints}, display both the
+breakpoints you've set explicitly, and those @value{GDBN} is using for
+internal purposes. Internal breakpoints are shown with negative
+breakpoint numbers. The type column identifies what kind of breakpoint
+is shown:
+
+@table @code
+@item breakpoint
+Normal, explicitly set breakpoint.
+
+@item watchpoint
+Normal, explicitly set watchpoint.
+
+@item longjmp
+Internal breakpoint, used to handle correctly stepping through
+@code{longjmp} calls.
+
+@item longjmp resume
+Internal breakpoint at the target of a @code{longjmp}.
+
+@item until
+Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
+
+@item finish
+Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
+
+@item shlib events
+Shared library events.
+
+@end table
+
+@end table
+
+
+@node Remove Protocol
+@appendix @value{GDBN} Remote Serial Protocol
+
+There may be occasions when you need to know something about the
+protocol---for example, if there is only one serial port to your target
+machine, you might want your program to do something special if it
+recognizes a packet meant for @value{GDBN}.
+
+In the examples below, @samp{<-} and @samp{->} are used to indicate
+transmitted and received data respectfully.
+
+@cindex protocol, @value{GDBN} remote serial
+@cindex serial protocol, @value{GDBN} remote
+@cindex remote serial protocol
+All @value{GDBN} commands and responses (other than acknowledgments) are
+sent as a @var{packet}. A @var{packet} is introduced with the character
+@samp{$}, the actual @var{packet-data}, and the terminating character
+@samp{#} followed by a two-digit @var{checksum}:
+
+@example
+@code{$}@var{packet-data}@code{#}@var{checksum}
+@end example
+@noindent
+
+@cindex checksum, for @value{GDBN} remote
+@noindent
+The two-digit @var{checksum} is computed as the modulo 256 sum of all
+characters between the leading @samp{$} and the trailing @samp{#} (an
+eight bit unsigned checksum).
+
+Implementors should note that prior to @value{GDBN} 5.0 the protocol
+specification also included an optional two-digit @var{sequence-id}:
+
+@example
+@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
+@end example
+
+@cindex sequence-id, for @value{GDBN} remote
+@noindent
+That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
+has never output @var{sequence-id}s. Stubs that handle packets added
+since @value{GDBN} 5.0 must not accept @var{sequence-id}.
+
+@cindex acknowledgment, for @value{GDBN} remote
+When either the host or the target machine receives a packet, the first
+response expected is an acknowledgment: either @samp{+} (to indicate
+the package was received correctly) or @samp{-} (to request
+retransmission):
+
+@example
+<- @code{$}@var{packet-data}@code{#}@var{checksum}
+-> @code{+}
+@end example
+@noindent
+
+The host (@value{GDBN}) sends @var{command}s, and the target (the
+debugging stub incorporated in your program) sends a @var{response}. In
+the case of step and continue @var{command}s, the response is only sent
+when the operation has completed (the target has again stopped).
+
+@var{packet-data} consists of a sequence of characters with the
+exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
+exceptions).
+
+Fields within the packet should be separated using @samp{,} @samp{;} or
+@samp{:}. Except where otherwise noted all numbers are represented in
+HEX with leading zeros suppressed.
+
+Implementors should note that prior to @value{GDBN} 5.0, the character
+@samp{:} could not appear as the third character in a packet (as it
+would potentially conflict with the @var{sequence-id}).
+
+Response @var{data} can be run-length encoded to save space. A @samp{*}
+means that the next character is an @sc{ascii} encoding giving a repeat count
+which stands for that many repetitions of the character preceding the
+@samp{*}. The encoding is @code{n+29}, yielding a printable character
+where @code{n >=3} (which is where rle starts to win). The printable
+characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
+value greater than 126 should not be used.
+
+Some remote systems have used a different run-length encoding mechanism
+loosely refered to as the cisco encoding. Following the @samp{*}
+character are two hex digits that indicate the size of the packet.
+
+So:
+@example
+"@code{0* }"
+@end example
+@noindent
+means the same as "0000".
+
+The error response returned for some packets includes a two character
+error number. That number is not well defined.
+
+For any @var{command} not supported by the stub, an empty response
+(@samp{$#00}) should be returned. That way it is possible to extend the
+protocol. A newer @value{GDBN} can tell if a packet is supported based
+on that response.
+
+A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
+@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
+optional.
+
+Below is a complete list of all currently defined @var{command}s and
+their corresponding response @var{data}:
+@page
+@multitable @columnfractions .30 .30 .40
+@item Packet
+@tab Request
+@tab Description
+
+@item extended mode
+@tab @code{!}
+@tab
+Enable extended mode. In extended mode, the remote server is made
+persistent. The @samp{R} packet is used to restart the program being
+debugged.
+@item
+@tab reply @samp{OK}
+@tab
+The remote target both supports and has enabled extended mode.
+
+@item last signal
+@tab @code{?}
+@tab
+Indicate the reason the target halted. The reply is the same as for step
+and continue.
+@item
+@tab reply
+@tab see below
+
+
+@item reserved
+@tab @code{a}
+@tab Reserved for future use
+
+@item set program arguments @strong{(reserved)}
+@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
+@tab
+@item
+@tab
+@tab
+Initialized @samp{argv[]} array passed into program. @var{arglen}
+specifies the number of bytes in the hex encoded byte stream @var{arg}.
+See @file{gdbserver} for more details.
+@item
+@tab reply @code{OK}
+@item
+@tab reply @code{E}@var{NN}
+
+@item set baud @strong{(deprecated)}
+@tab @code{b}@var{baud}
+@tab
+Change the serial line speed to @var{baud}. JTC: @emph{When does the
+transport layer state change? When it's received, or after the ACK is
+transmitted. In either case, there are problems if the command or the
+acknowledgment packet is dropped.} Stan: @emph{If people really wanted
+to add something like this, and get it working for the first time, they
+ought to modify ser-unix.c to send some kind of out-of-band message to a
+specially-setup stub and have the switch happen "in between" packets, so
+that from remote protocol's point of view, nothing actually
+happened.}
+
+@item set breakpoint @strong{(deprecated)}
+@tab @code{B}@var{addr},@var{mode}
+@tab
+Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
+breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and
+@samp{z} packets.}
+
+@item continue
+@tab @code{c}@var{addr}
+@tab
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+current address.
+@item
+@tab reply
+@tab see below
+
+@item continue with signal
+@tab @code{C}@var{sig}@code{;}@var{addr}
+@tab
+Continue with signal @var{sig} (hex signal number). If
+@code{;}@var{addr} is omitted, resume at same address.
+@item
+@tab reply
+@tab see below
+
+@item toggle debug @strong{(deprecated)}
+@tab @code{d}
+@tab
+toggle debug flag.
+
+@item detach
+@tab @code{D}
+@tab
+Detach @value{GDBN} from the remote system. Sent to the remote target before
+@value{GDBN} disconnects.
+@item
+@tab reply @emph{no response}
+@tab
+@value{GDBN} does not check for any response after sending this packet.
+
+@item reserved
+@tab @code{e}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{E}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{f}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{F}
+@tab Reserved for future use
+
+@item read registers
+@tab @code{g}
+@tab Read general registers.
+@item
+@tab reply @var{XX...}
+@tab
+Each byte of register data is described by two hex digits. The bytes
+with the register are transmitted in target byte order. The size of
+each register and their position within the @samp{g} @var{packet} are
+determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} and
+@var{REGISTER_NAME} macros. The specification of several standard
+@code{g} packets is specified below.
+@item
+@tab @code{E}@var{NN}
+@tab for an error.
+
+@item write regs
+@tab @code{G}@var{XX...}
+@tab
+See @samp{g} for a description of the @var{XX...} data.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+
+@item reserved
+@tab @code{h}
+@tab Reserved for future use
+
+@item set thread
+@tab @code{H}@var{c}@var{t...}
+@tab
+Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
+@samp{G}, et.al.). @var{c} = @samp{c} for thread used in step and
+continue; @var{t...} can be -1 for all threads. @var{c} = @samp{g} for
+thread used in other operations. If zero, pick a thread, any thread.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+
+@c FIXME: JTC:
+@c 'H': How restrictive (or permissive) is the thread model. If a
+@c thread is selected and stopped, are other threads allowed
+@c to continue to execute? As I mentioned above, I think the
+@c semantics of each command when a thread is selected must be
+@c described. For example:
+@c
+@c 'g': If the stub supports threads and a specific thread is
+@c selected, returns the register block from that thread;
+@c otherwise returns current registers.
+@c
+@c 'G' If the stub supports threads and a specific thread is
+@c selected, sets the registers of the register block of
+@c that thread; otherwise sets current registers.
+
+@item cycle step @strong{(draft)}
+@tab @code{i}@var{addr}@code{,}@var{nnn}
+@tab
+Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
+present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
+step starting at that address.
+
+@item signal then cycle step @strong{(reserved)}
+@tab @code{I}
+@tab
+See @samp{i} and @samp{S} for likely syntax and semantics.
+
+@item reserved
+@tab @code{j}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{J}
+@tab Reserved for future use
+
+@item kill request
+@tab @code{k}
+@tab
+FIXME: @emph{There is no description of how operate when a specific
+thread context has been selected (ie. does 'k' kill only that thread?)}.
+
+@item reserved
+@tab @code{l}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{L}
+@tab Reserved for future use
+
+@item read memory
+@tab @code{m}@var{addr}@code{,}@var{length}
+@tab
+Read @var{length} bytes of memory starting at address @var{addr}.
+Neither @value{GDBN} nor the stub assume that sized memory transfers are assumed
+using word alligned accesses. FIXME: @emph{A word aligned memory
+transfer mechanism is needed.}
+@item
+@tab reply @var{XX...}
+@tab
+@var{XX...} is mem contents. Can be fewer bytes than requested if able
+to read only part of the data. Neither @value{GDBN} nor the stub assume that
+sized memory transfers are assumed using word alligned accesses. FIXME:
+@emph{A word aligned memory transfer mechanism is needed.}
+@item
+@tab reply @code{E}@var{NN}
+@tab @var{NN} is errno
+
+@item write mem
+@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...}
+@tab
+Write @var{length} bytes of memory starting at address @var{addr}.
+@var{XX...} is the data.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab
+for an error (this includes the case where only part of the data was
+written).
+
+@item reserved
+@tab @code{n}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{N}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{o}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{O}
+@tab Reserved for future use
+
+@item read reg @strong{(reserved)}
+@tab @code{p}@var{n...}
+@tab
+See write register.
+@item
+@tab return @var{r....}
+@tab The hex encoded value of the register in target byte order.
+
+@item write reg
+@tab @code{P}@var{n...}@code{=}@var{r...}
+@tab
+Write register @var{n...} with value @var{r...}, which contains two hex
+digits for each byte in the register (target byte order).
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+
+@item general query
+@tab @code{q}@var{query}
+@tab
+Request info about @var{query}. In general @value{GDBN} queries
+have a leading upper case letter. Custom vendor queries should use a
+company prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may
+optionally be followed by a @samp{,} or @samp{;} separated list. Stubs
+must ensure that they match the full @var{query} name.
+@item
+@tab reply @code{XX...}
+@tab Hex encoded data from query. The reply can not be empty.
+@item
+@tab reply @code{E}@var{NN}
+@tab error reply
+@item
+@tab reply @samp{}
+@tab Indicating an unrecognized @var{query}.
+
+@item general set
+@tab @code{Q}@var{var}@code{=}@var{val}
+@tab
+Set value of @var{var} to @var{val}. See @samp{q} for a discussing of
+naming conventions.
+
+@item reset @strong{(deprecated)}
+@tab @code{r}
+@tab
+Reset the entire system.
+
+@item remote restart
+@tab @code{R}@var{XX}
+@tab
+Restart the program being debugged. @var{XX}, while needed, is ignored.
+This packet is only available in extended mode.
+@item
+@tab
+no reply
+@tab
+The @samp{R} packet has no reply.
+
+@item step
+@tab @code{s}@var{addr}
+@tab
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+same address.
+@item
+@tab reply
+@tab see below
+
+@item step with signal
+@tab @code{S}@var{sig}@code{;}@var{addr}
+@tab
+Like @samp{C} but step not continue.
+@item
+@tab reply
+@tab see below
+
+@item search
+@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
+@tab
+Search backwards starting at address @var{addr} for a match with pattern
+@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
+bytes. @var{addr} must be at least 3 digits.
+
+@item thread alive
+@tab @code{T}@var{XX}
+@tab Find out if the thread XX is alive.
+@item
+@tab reply @code{OK}
+@tab thread is still alive
+@item
+@tab reply @code{E}@var{NN}
+@tab thread is dead
+
+@item reserved
+@tab @code{u}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{U}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{v}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{V}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{w}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{W}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{x}
+@tab Reserved for future use
+
+@item write mem (binary)
+@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
+@tab
+@var{addr} is address, @var{length} is number of bytes, @var{XX...} is
+binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
+escaped using @code{0x7d}.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+
+@item reserved
+@tab @code{y}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{Y}
+@tab Reserved for future use
+
+@item remove break or watchpoint @strong{(draft)}
+@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
+@tab
+See @samp{Z}.
+
+@item insert break or watchpoint @strong{(draft)}
+@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
+@tab
+@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
+breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
+@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
+bytes. For a software breakpoint, @var{length} specifies the size of
+the instruction to be patched. For hardware breakpoints and watchpoints
+@var{length} specifies the memory region to be monitored. To avoid
+potential problems with duplicate packets, the operations should be
+implemented in an idempotent way.
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab @samp{}
+@tab If not supported.
+
+@item reserved
+@tab <other>
+@tab Reserved for future use
+
+@end multitable
+
+The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
+receive any of the below as a reply. In the case of the @samp{C},
+@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
+when the target halts. In the below the exact meaning of @samp{signal
+number} is poorly defined. In general one of the UNIX signal numbering
+conventions is used.
+
+@multitable @columnfractions .4 .6
+
+@item @code{S}@var{AA}
+@tab @var{AA} is the signal number
+
+@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
+@tab
+@var{AA} = two hex digit signal number; @var{n...} = register number
+(hex), @var{r...} = target byte ordered register contents, size defined
+by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} =
+thread process ID, this is a hex integer; @var{n...} = other string not
+starting with valid hex digit. @value{GDBN} should ignore this
+@var{n...}, @var{r...} pair and go on to the next. This way we can
+extend the protocol.
+
+@item @code{W}@var{AA}
+@tab
+The process exited, and @var{AA} is the exit status. This is only
+applicable for certains sorts of targets.
+
+@item @code{X}@var{AA}
+@tab
+The process terminated with signal @var{AA}.
+
+@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)}
+@tab
+@var{AA} = signal number; @var{t...} = address of symbol "_start";
+@var{d...} = base of data section; @var{b...} = base of bss section.
+@emph{Note: only used by Cisco Systems targets. The difference between
+this reply and the "qOffsets" query is that the 'N' packet may arrive
+spontaneously whereas the 'qOffsets' is a query initiated by the host
+debugger.}
+
+@item @code{O}@var{XX...}
+@tab
+@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time
+while the program is running and the debugger should continue to wait
+for 'W', 'T', etc.
+
+@end multitable
+
+The following set and query packets have already been defined.
+
+@multitable @columnfractions .2 .2 .6
+
+@item current thread
+@tab @code{q}@code{C}
+@tab Return the current thread id.
+@item
+@tab reply @code{QC}@var{pid}
+@tab
+Where @var{pid} is a HEX encoded 16 bit process id.
+@item
+@tab reply *
+@tab Any other reply implies the old pid.
+
+@item all thread ids
+@tab @code{q}@code{fThreadInfo}
+@item
+@tab @code{q}@code{sThreadInfo}
+@tab
+Obtain a list of active thread ids from the target (OS). Since there
+may be too many active threads to fit into one reply packet, this query
+works iteratively: it may require more than one query/reply sequence to
+obtain the entire list of threads. The first query of the sequence will
+be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
+sequence will be the @code{qs}@code{ThreadInfo} query.
+@item
+@tab
+@tab NOTE: replaces the @code{qL} query (see below).
+@item
+@tab reply @code{m}@var{<id>}
+@tab A single thread id
+@item
+@tab reply @code{m}@var{<id>},@var{<id>...}
+@tab a comma-separated list of thread ids
+@item
+@tab reply @code{l}
+@tab (lower case 'el') denotes end of list.
+@item
+@tab
+@tab
+In response to each query, the target will reply with a list of one
+or more thread ids, in big-endian hex, separated by commas. GDB will
+respond to each reply with a request for more thread ids (using the
+@code{qs} form of the query), until the target responds with @code{l}
+(lower-case el, for @code{'last'}).
+
+@item extra thread info
+@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id}
+@tab
+@item
+@tab
+@tab
+Where @var{<id>} is a thread-id in big-endian hex.
+Obtain a printable string description of a thread's attributes from
+the target OS. This string may contain anything that the target OS
+thinks is interesting for @value{GDBN} to tell the user about the thread.
+The string is displayed in @value{GDBN}'s @samp{info threads} display.
+Some examples of possible thread extra info strings are "Runnable", or
+"Blocked on Mutex".
+@item
+@tab reply @var{XX...}
+@tab
+Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the
+printable string containing the extra information about the thread's
+attributes.
+
+@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
+@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
+@tab
+@item
+@tab
+@tab
+Obtain thread information from RTOS. Where: @var{startflag} (one hex
+digit) is one to indicate the first query and zero to indicate a
+subsequent query; @var{threadcount} (two hex digits) is the maximum
+number of threads the response packet can contain; and @var{nextthread}
+(eight hex digits), for subsequent queries (@var{startflag} is zero), is
+returned in the response as @var{argthread}.
+@item
+@tab
+@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo}
+query (see above).
+@item
+@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...}
+@tab
+@item
+@tab
+@tab
+Where: @var{count} (two hex digits) is the number of threads being
+returned; @var{done} (one hex digit) is zero to indicate more threads
+and one indicates no further threads; @var{argthreadid} (eight hex
+digits) is @var{nextthread} from the request packet; @var{thread...} is
+a sequence of thread IDs from the target. @var{threadid} (eight hex
+digits). See @code{remote.c:parse_threadlist_response()}.
+
+@item compute CRC of memory block
+@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
+@tab
+@item
+@tab reply @code{E}@var{NN}
+@tab An error (such as memory fault)
+@item
+@tab reply @code{C}@var{CRC32}
+@tab A 32 bit cyclic redundancy check of the specified memory region.
+
+@item query sect offs
+@tab @code{q}@code{Offsets}
+@tab
+Get section offsets that the target used when re-locating the downloaded
+image. @emph{Note: while a @code{Bss} offset is included in the
+response, @value{GDBN} ignores this and instead applies the @code{Data}
+offset to the @code{Bss} section.}
+@item
+@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
+
+@item thread info request
+@tab @code{q}@code{P}@var{mode}@var{threadid}
+@tab
+@item
+@tab
+@tab
+Returns information on @var{threadid}. Where: @var{mode} is a hex
+encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
+@item
+@tab reply *
+@tab
+See @code{remote.c:remote_unpack_thread_info_response()}.
+
+@item remote command
+@tab @code{q}@code{Rcmd,}@var{COMMAND}
+@tab
+@item
+@tab
+@tab
+@var{COMMAND} (hex encoded) is passed to the local interpreter for
+execution. Invalid commands should be reported using the output string.
+Before the final result packet, the target may also respond with a
+number of intermediate @code{O}@var{OUTPUT} console output
+packets. @emph{Implementors should note that providing access to a
+stubs's interpreter may have security implications}.
+@item
+@tab reply @code{OK}
+@tab
+A command response with no output.
+@item
+@tab reply @var{OUTPUT}
+@tab
+A command response with the hex encoded output string @var{OUTPUT}.
+@item
+@tab reply @code{E}@var{NN}
+@tab
+Indicate a badly formed request.
+
+@item
+@tab reply @samp{}
+@tab
+When @samp{q}@samp{Rcmd} is not recognized.
+
+@item symbol lookup
+@tab @code{qSymbol::}
+@tab
+Notify the target that @value{GDBN} is prepared to serve symbol lookup
+requests. Accept requests from the target for the values of symbols.
+@item
+@tab
+@tab
+@item
+@tab reply @code{OK}
+@tab
+The target does not need to look up any (more) symbols.
+@item
+@tab reply @code{qSymbol:}@var{sym_name}
+@tab
+@sp 2
+@noindent
+The target requests the value of symbol @var{sym_name} (hex encoded).
+@value{GDBN} may provide the value by using the
+@code{qSymbol:}@var{sym_value}:@var{sym_name}
+message, described below.
+
+@item symbol value
+@tab @code{qSymbol:}@var{sym_value}:@var{sym_name}
+@tab
+@sp 1
+@noindent
+Set the value of SYM_NAME to SYM_VALUE.
+@item
+@tab
+@tab
+@var{sym_name} (hex encoded) is the name of a symbol whose value
+the target has previously requested.
+@item
+@tab
+@tab
+@var{sym_value} (hex) is the value for symbol @var{sym_name}.
+If @value{GDBN} cannot supply a value for @var{sym_name}, then this
+field will be empty.
+@item
+@tab reply @code{OK}
+@tab
+The target does not need to look up any (more) symbols.
+@item
+@tab reply @code{qSymbol:}@var{sym_name}
+@tab
+@sp 2
+@noindent
+The target requests the value of a new symbol @var{sym_name} (hex encoded).
+@value{GDBN} will continue to supply the values of symbols (if available),
+until the target ceases to request them.
+
+@end multitable
+
+The following @samp{g}/@samp{G} packets have previously been defined.
+In the below, some thirty-two bit registers are transferred as sixty-four
+bits. Those registers should be zero/sign extended (which?) to fill the
+space allocated. Register bytes are transfered in target byte order.
+The two nibbles within a register byte are transfered most-significant -
+least-significant.
+
+@multitable @columnfractions .5 .5
+
+@item MIPS32
+@tab
+All registers are transfered as thirty-two bit quantities in the order:
+32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
+registers; fsr; fir; fp.
+
+@item MIPS64
+@tab
+All registers are transfered as sixty-four bit quantities (including
+thirty-two bit registers such as @code{sr}). The ordering is the same
+as @code{MIPS32}.
+
+@end multitable
+
+Example sequence of a target being re-started. Notice how the restart
+does not get any direct output:
+
+@example
+<- @code{R00}
+-> @code{+}
+@emph{target restarts}
+<- @code{?}
+-> @code{+}
+-> @code{T001:1234123412341234}
+<- @code{+}
+@end example
+
+Example sequence of a target being stepped by a single instruction:
+
+@example
+<- @code{G1445...}
+-> @code{+}
+<- @code{s}
+-> @code{+}
+@emph{time passes}
+-> @code{T001:1234123412341234}
+<- @code{+}
+<- @code{g}
+-> @code{+}
+-> @code{1455...}
+<- @code{+}
+@end example
+
+
+@include fdl.texi
+
+@node Index
@unnumbered Index
@printindex cp
% Blame: doc@cygnus.com, 1991.
@end tex
+@c TeX can handle the contents at the start but makeinfo 3.12 can not
+@ifinfo
+@contents
+@end ifinfo
+@ifhtml
@contents
+@end ifhtml
+
@bye
projects / deliverable / binutils-gdb.git / blobdiff