\input texinfo @c -*-texinfo-*-
-@c Copyright 1988-2000
+@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
@syncodeindex fn cp
@c !!set GDB manual's edition---not the same as GDB version!
-@set EDITION Eighth
+@set EDITION Ninth
@c !!set GDB manual's revision date
-@set DATE March 2000
+@set DATE December 2001
-@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.
+@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.
@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree.
of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
for @value{GDBN} Version @value{GDBVN}.
-Copyright (C) 1988-2000 Free Software Foundation, Inc.
+Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
+ 1999, 2000, 2001, 2002 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.
+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.
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-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.
+(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
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-2000 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
Published by the Free Software Foundation @*
59 Temple Place - Suite 330, @*
Boston, MA 02111-1307 USA @*
ISBN 1-882114-77-9 @*
-
-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.
+
+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
+@ifnottex
@node Top, Summary, (dir), (dir)
@top Debugging with @value{GDBN}
This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-2000 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
@menu
* Summary:: Summary of @value{GDBN}
* Stack:: Examining the stack
* Source:: Examining source files
* Data:: Examining data
+* Macros:: Preprocessor Macros
+* Tracepoints:: Debugging remote targets non-intrusively
+* Overlays:: Debugging programs that use overlays
* Languages:: Using @value{GDBN} with different languages
* 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.
* Command Line Editing:: Command Line Editing
* Using History Interactively:: Using History Interactively
* Installing GDB:: Installing GDB
+* Maintenance Commands:: Maintenance Commands
+* Remote Protocol:: GDB Remote Serial Protocol
+* Copying:: GNU General Public License says
+ how you can copy and share GDB
+* GNU Free Documentation License:: The license for this documentation
* Index:: Index
@end menu
-@end ifinfo
-
-@c the replication sucks, but this avoids a texinfo 3.12 lameness
-
-@ifhtml
-@node Top
-
-@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
-@value{GDBVN}.
-
-Copyright (C) 1988-2000 Free Software Foundation, Inc.
-
-@menu
-* Summary:: Summary of @value{GDBN}
-* Sample Session:: A sample @value{GDBN} session
-
-* 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
-
-* Languages:: Using @value{GDBN} with different languages
-
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Configurations:: Configuration-specific information
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
-* Annotations:: @value{GDBN}'s annotation interface.
-
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print @value{GDBN} documentation
-
-* Command Line Editing:: Command Line Editing
-* Using History Interactively:: Using History Interactively
-* Installing GDB:: Installing GDB
-* Index:: Index
-@end menu
-
-@end ifhtml
+@end ifnottex
-@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}
For more information, see @ref{Support,,Supported languages}.
For more information, see @ref{C,,C and C++}.
-@cindex Chill
+@c OBSOLETE @cindex Chill
@cindex Modula-2
-Support for Modula-2 and Chill is partial. For information on Modula-2,
-see @ref{Modula-2,,Modula-2}. For information on Chill, see @ref{Chill}.
+Support for Modula-2
+@c OBSOLETE and Chill
+is partial. For information on Modula-2, see @ref{Modula-2,,Modula-2}.
+@c OBSOLETE For information on Chill, see @ref{Chill}.
@cindex Pascal
Debugging Pascal programs which use sets, subranges, file variables, or
you have these freedoms and that you cannot take these freedoms away
from anyone else.
+@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}
So that they may not regard their many labors as thankless, we
particularly thank those who shepherded @value{GDBN} through major
releases:
-Andrew Cagney (release 5.0);
+Andrew Cagney (releases 5.3, 5.2, 5.1 and 5.0);
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
-@value{GDBN}, 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.
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
+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
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.
+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
Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
Zuhn have made contributions both large and small.
+Jim Blandy added support for preprocessor macros, while working for Red
+Hat.
@node Sample Session
@chapter A Sample @value{GDBN} Session
The most usual way to start @value{GDBN} is with one argument,
specifying an executable program:
-@example
+@smallexample
@value{GDBP} @var{program}
-@end example
+@end smallexample
@noindent
You can also start with both an executable program and a core file
specified:
-@example
+@smallexample
@value{GDBP} @var{program} @var{core}
-@end example
+@end smallexample
You can, instead, specify a process ID as a second argument, if you want
to debug a running process:
-@example
+@smallexample
@value{GDBP} @var{program} 1234
-@end example
+@end smallexample
@noindent
would attach @value{GDBN} to process @code{1234} (unless you also have a file
``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.
+@smallexample
+gdb --args gcc -O2 -c foo.c
+@end smallexample
+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{@value{GDBP}} without printing the front material, which describes
@value{GDBN}'s non-warranty, by specifying @code{-silent}:
@noindent
Type
-@example
+@smallexample
@value{GDBP} -help
-@end example
+@end smallexample
@noindent
to display all available options and briefly describe their use
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
@itemx -c @var{file}
@cindex @code{--core}
@cindex @code{-c}
-Use file @var{file} as a core dump to examine.
+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}
on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing
but build a @file{.syms} file for future use is:
-@example
+@smallexample
gdb -batch -nx -mapped -readnow programname
-@end example
+@end smallexample
@node Mode Options
@subsection Choosing modes
@itemx -n
@cindex @code{--nx}
@cindex @code{-n}
-Do not execute commands found in any initialization files (normally
-called @file{.gdbinit}, or @file{gdb.ini} on PCs). Normally,
+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}.
example to download and run a program on another computer; in order to
make this more useful, the message
-@example
+@smallexample
Program exited normally.
-@end example
+@end smallexample
@noindent
(which is ordinarily issued whenever a program running under
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.0, the target side of the asynchronous
+(@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
@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}
@c FIXME: kingdon thinks there is more to -tty. Investigate.
@c resolve the situation of these eventually
-@c @item -tui
-@c @cindex @code{--tui}
-@c Use a Terminal User Interface. For information, use your Web browser to
-@c read the file @file{TUI.html}, which is usually installed in the
-@c directory @code{/opt/langtools/wdb/doc} on HP-UX systems. Do not use
-@c this option if you run @value{GDBN} from Emacs (see @pxref{Emacs, ,Using
-@c @value{GDBN} under @sc{gnu} Emacs}).
+@item -tui
+@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}
@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. For example,
-@samp{--interpreter=mi} causes @value{GDBN} to use the @dfn{gdbmi
-interface} (@pxref{GDB/MI, , The @sc{gdb/mi} Interface}).
+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}
nothing. This is useful mainly in command files (@pxref{Command
Files,,Command files}).
+@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
@c complete accuracy in these examples; space introduced for clarity.
@c If texinfo enhancements make it unnecessary, it would be nice to
@c replace " @key" by "@key" in the following...
-@example
+@smallexample
(@value{GDBP}) info bre @key{TAB}
-@end example
+@end smallexample
@noindent
@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
the only @code{info} subcommand beginning with @samp{bre}:
-@example
+@smallexample
(@value{GDBP}) info breakpoints
-@end example
+@end smallexample
@noindent
You can either press @key{RET} at this point, to run the @code{info
function names in your program that begin with those characters, for
example:
-@example
+@smallexample
(@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_cleanup make_reference_type
make_command make_symbol_completion_list
(@value{GDBP}) b make_
-@end example
+@end smallexample
@noindent
After displaying the available possibilities, @value{GDBN} copies your
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:
-
-@example
+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:
+
+@smallexample
(@value{GDBP}) b 'bubble( @kbd{M-?}
bubble(double,double) bubble(int,int)
(@value{GDBP}) b 'bubble(
-@end example
+@end smallexample
In some cases, @value{GDBN} can tell that completing a name requires using
quotes. When this happens, @value{GDBN} inserts the quote for you (while
completing as much as it can) if you do not type the quote in the first
place:
-@example
+@smallexample
(@value{GDBP}) b bub @key{TAB}
@exdent @value{GDBN} alters your input line to the following, and rings a bell:
(@value{GDBP}) b 'bubble(
-@end example
+@end smallexample
@noindent
In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
completion on an overloaded symbol.
For more information about overloaded functions, see @ref{C plus plus
-expressions, ,C++ expressions}. You can use the command @code{set
+expressions, ,C@t{++} expressions}. You can use the command @code{set
overload-resolution off} to disable overload resolution;
-see @ref{Debugging C plus plus, ,@value{GDBN} features for C++}.
+see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}.
@node Help
apropos reload
@end smallexample
-@noindent results in:
+@noindent
+results in:
@smallexample
@c @group
To request debugging information, specify the @samp{-g} option when you run
the compiler.
+Most compilers do not include information about preprocessor macros in
+the debugging information if you specify the @option{-g} flag alone,
+because this information is rather large. Version 3.1 of @value{NGCC},
+the @sc{gnu} C compiler, provides macro information if you specify the
+options @option{-gdwarf-2} and @option{-g3}; the former option requests
+debugging information in the Dwarf 2 format, and the latter requests
+``extra information''. In the future, we hope to find more compact ways
+to represent macro information, so that it can be included with
+@option{-g} alone.
+
Many C compilers are unable to handle the @samp{-g} and @samp{-O}
options together. Using those compilers, you cannot generate optimized
executables containing debugging information.
@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.
+(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
For example, this command:
-@example
+@smallexample
set env USER = foo
-@end example
+@end smallexample
@noindent
tells the debugged program, when subsequently run, that its user is named
You can redirect your program's input and/or output using shell
redirection with the @code{run} command. For example,
-@example
+@smallexample
run > outfile
-@end example
+@end smallexample
@noindent
starts your program, diverting its output to the file @file{outfile}.
commands. It also resets the controlling terminal for the child
process, for future @code{run} commands. For example,
-@example
+@smallexample
tty /dev/ttyb
-@end example
+@end smallexample
@noindent
directs that processes started with subsequent @code{run} commands
whose form varies depending on the particular system. For example, on
LynxOS, you might see
-@example
+@smallexample
[New process 35 thread 27]
-@end example
+@end smallexample
@noindent
when @value{GDBN} notices a new thread. In contrast, on an SGI system,
@c FIXME!! (1) Does the [New...] message appear even for the very first
@c thread of a program, or does it only appear for the
-@c second---i.e., when it becomes obvious we have a multithread
+@c second---i.e.@: when it becomes obvious we have a multithread
@c program?
@c (2) *Is* there necessarily a first thread always? Or do some
@c multithread systems permit starting a program with multiple
whose form varies depending on the particular system. For example, on
HP-UX, you see
-@example
+@smallexample
[New thread 2 (system thread 26594)]
-@end example
+@end smallexample
@noindent
when @value{GDBN} notices a new thread.
@end table
@c end table here to get a little more width for example
-@example
+@smallexample
(@value{GDBP}) info threads
* 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
at quicksort.c:137
from /usr/lib/libc.2
1 system thread 27905 0x7b003498 in _brk () \@*
from /usr/lib/libc.2
-@end example
+@end smallexample
@table @code
@kindex thread @var{threadno}
@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
@item break @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}
@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++ programs, @code{rbreak} is useful for setting
+When debugging C@t{++} programs, @code{rbreak} is useful for setting
breakpoints on overloaded functions that are not members of any special
classes.
@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.
-
-@item shlib events
-Shared library events.
-
-@end table
-
-@end table
+@samp{maint info breakpoints} (@pxref{maint info breakpoints}).
@node Set Watchpoints
When you issue the @code{watch} command, @value{GDBN} reports
-@example
+@smallexample
Hardware watchpoint @var{num}: @var{expr}
-@end example
+@end smallexample
@noindent
if it was able to set a hardware watchpoint.
@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
+@smallexample
/* @var{addr} is where the exception identifier is stored.
@var{id} is the exception identifier. */
void __raise_exception (void **addr, void *id);
-@end example
+@end smallexample
@noindent
To make the debugger catch all exceptions before any stack
symbols not referenced in the context of the breakpoint, @value{GDBN}
prints an error message:
-@example
+@smallexample
No symbol "foo" in current context.
-@end example
+@end smallexample
@noindent
@value{GDBN} does
For example, here is how you could use breakpoint commands to print the
value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
-@example
+@smallexample
break foo if x>0
commands
silent
printf "x is %d\n",x
cont
end
-@end example
+@end smallexample
One application for breakpoint commands is to compensate for one bug so
you can test for another. Put a breakpoint just after the erroneous line
so that your program does not stop, and start with the @code{silent}
command so that no output is produced. Here is an example:
-@example
+@smallexample
break 403
commands
silent
set x = y + 4
cont
end
-@end example
+@end smallexample
@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
attempting to run or continue a program with a breakpoint causes
@value{GDBN} to print an error message:
-@example
+@smallexample
Cannot insert breakpoints.
The same program may be running in another process.
-@end example
+@end smallexample
When this happens, you have three ways to proceed:
(@code{frame}) command shows that execution is stopped at line
@code{206}; yet when we use @code{until}, we get to line @code{195}:
-@example
+@smallexample
(@value{GDBP}) f
#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
206 expand_input();
(@value{GDBP}) until
195 for ( ; argc > 0; NEXTARG) @{
-@end example
+@end smallexample
This happened because, for execution efficiency, the compiler had
generated code for the loop closure test at the end, rather than the
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.
@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
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
@cindex frameless execution
Some compilers provide a way to compile functions so that they operate
without stack frames. (For example, the @value{GCC} option
-@example
+@smallexample
@samp{-fomit-frame-pointer}
-@end example
+@end smallexample
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
* Convenience Vars:: Convenience variables
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
+* Vector Unit:: Vector Unit
+* Memory Region Attributes:: Memory region attributes
+* Dump/Restore Files:: Copy between memory and a file
@end menu
@node Expressions
@code{print} and many other @value{GDBN} commands accept an expression and
compute its value. Any kind of constant, variable or operator defined
by the programming language you are using is valid in an expression in
-@value{GDBN}. This includes conditional expressions, function calls, casts
-and string constants. It unfortunately does not include symbols defined
-by preprocessor @code{#define} commands.
+@value{GDBN}. This includes conditional expressions, function calls,
+casts, and string constants. It also includes preprocessor macros, if
+you compiled your program to include this information; see
+@ref{Compilation}.
@value{GDBN} supports array constants in expressions input by
the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
@noindent This means that in the function
-@example
+@smallexample
foo (a)
int a;
@{
bar (b);
@}
@}
-@end example
+@end smallexample
@noindent
you can examine and use the variable @code{a} whenever your program is
@c info cannot cope with a :: index entry, but why deprive hard copy readers?
@cindex @code{::}, context for variables/functions
@end iftex
-@example
+@smallexample
@var{file}::@var{variable}
@var{function}::@var{variable}
-@end example
+@end smallexample
@noindent
Here @var{file} or @var{function} is the name of the context for the
make sure @value{GDBN} parses the file name as a single word---for example,
to print a global value of @code{x} defined in @file{f2.c}:
-@example
+@smallexample
(@value{GDBP}) p 'f2.c'::x
-@end example
+@end smallexample
-@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
might not be able to display values for such local variables. If that
happens, @value{GDBN} will print a message like this:
-@example
+@smallexample
No symbol "foo" in current context.
-@end example
+@end smallexample
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++ compiler usually
+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
following those that hold the first element, and so on. Here is an
example. If a program says
-@example
+@smallexample
int *array = (int *) malloc (len * sizeof (int));
-@end example
+@end smallexample
@noindent
you can print the contents of @code{array} with
-@example
+@smallexample
p *array@@len
-@end example
+@end smallexample
The left operand of @samp{@@} must reside in memory. Array values made
with @samp{@@} in this way behave just like other arrays in terms of
Another way to create an artificial array is to use a cast.
This re-interprets a value as if it were an array.
The value need not be in memory:
-@example
+@smallexample
(@value{GDBP}) p/x (short[2])0x12345678
$1 = @{0x1234, 0x5678@}
-@end example
+@end smallexample
As a convenience, if you leave the array length out (as in
@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
-@example
+@smallexample
(@value{GDBP}) p/x (short[])0x12345678
$2 = @{0x1234, 0x5678@}
-@end example
+@end smallexample
Sometimes the artificial array mechanism is not quite enough; in
moderately complex data structures, the elements of interest may not
structures, and you are interested in the values of a field @code{fv}
in each structure. Here is an example of what you might type:
-@example
+@smallexample
set $i = 0
p dtab[$i++]->fv
@key{RET}
@key{RET}
@dots{}
-@end example
+@end smallexample
@node Output Formats
@section Output formats
@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:
-@example
+@smallexample
(@value{GDBP}) p/a 0x54320
$3 = 0x54320 <_initialize_vx+396>
-@end example
+@end smallexample
+
+@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.
For example, to print the program counter in hex (@pxref{Registers}), type
-@example
+@smallexample
p/x $pc
-@end example
+@end smallexample
@noindent
Note that no space is required before the slash; this is because command
to remove an expression from the list, you specify that number.
The automatic display looks like this:
-@example
+@smallexample
2: foo = 38
3: bar[5] = (struct hack *) 0x3804
-@end example
+@end smallexample
@noindent
This display shows item numbers, expressions and their current values. As with
For example, here @value{GDBN} shows that a variable @code{ptt} points
at another variable @code{t}, defined in @file{hi2.c}:
-@example
+@smallexample
(@value{GDBP}) set print symbol-filename on
(@value{GDBP}) p/a ptt
$4 = 0xe008 <t in hi2.c>
-@end example
+@end smallexample
@quotation
@emph{Warning:} For pointers that point to a local variable, @samp{p/a}
@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 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.
+Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
This is the default.
@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.
+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}).)
+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
For example, suppose you have just printed a pointer to a structure and
want to see the contents of the structure. It suffices to type
-@example
+@smallexample
p *$
-@end example
+@end smallexample
If you have a chain of structures where the component @code{next} points
to the next one, you can print the contents of the next one with this:
-@example
+@smallexample
p *$.next
-@end example
+@end smallexample
@noindent
You can print successive links in the chain by repeating this
Note that the history records values, not expressions. If the value of
@code{x} is 4 and you type these commands:
-@example
+@smallexample
print x
set x=5
-@end example
+@end smallexample
@noindent
then the value recorded in the value history by the @code{print} command
expression, just as you would set a variable in your program.
For example:
-@example
+@smallexample
set $foo = *object_ptr
-@end example
+@end smallexample
@noindent
would save in @code{$foo} the value contained in the object pointed to by
incremented or a pointer to be advanced. For example, to print
a field from successive elements of an array of structures:
-@example
+@smallexample
set $i = 0
print bar[$i++]->contents
-@end example
+@end smallexample
@noindent
Repeat that command by typing @key{RET}.
register that contains the processor status. For example,
you could print the program counter in hex with
-@example
+@smallexample
p/x $pc
-@end example
+@end smallexample
@noindent
or print the instruction to be executed next with
-@example
+@smallexample
x/i $pc
-@end example
+@end smallexample
@noindent
or add four to the stack pointer@footnote{This is a way of removing
regardless of machine architecture, use @code{return};
see @ref{Returning, ,Returning from a function}.} with
-@example
+@smallexample
set $sp += 4
-@end example
+@end smallexample
Whenever possible, these four standard register names are available on
your machine even though the machine has different canonical mnemonics,
the ARM and x86 machines.
@end table
-@node Languages
-@chapter Using @value{GDBN} with Different Languages
-@cindex languages
+@node Vector Unit
+@section Vector Unit
+@cindex vector unit
-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}.
+Depending on the configuration, @value{GDBN} may be able to give you
+more information about the status of the vector unit.
-@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}.
+@table @code
+@kindex info vector
+@item info vector
+Display information about the vector unit. The exact contents and
+layout vary depending on the hardware.
+@end table
-@menu
-* Setting:: Switching between source languages
-* Show:: Displaying the language
-* Checks:: Type and range checks
-* Support:: Supported languages
-@end menu
+@node Memory Region Attributes
+@section Memory region attributes
+@cindex memory region attributes
-@node Setting
-@section Switching between source languages
+@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.
-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.
+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.
-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}, but you can
-set the language associated with a filename extension. @xref{Show, ,
-Displaying the language}.
+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.
-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.
+@table @code
+@kindex mem
+@item mem @var{lower} @var{upper} @var{attributes}@dots{}
+Define memory region bounded by @var{lower} and @var{upper} with
+attributes @var{attributes}@dots{}. Note that @var{upper} == 0 is a
+special case: it is treated as the the target's maximum memory address.
+(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
-@menu
-* Filenames:: Filename extensions and languages.
-* Manually:: Setting the working language manually
-* Automatically:: Having @value{GDBN} infer the source language
-@end menu
+@kindex delete mem
+@item delete mem @var{nums}@dots{}
+Remove memory regions @var{nums}@dots{}.
-@node Filenames
-@subsection List of filename extensions and languages
+@kindex disable mem
+@item disable mem @var{nums}@dots{}
+Disable memory regions @var{nums}@dots{}.
+A disabled memory region is not forgotten.
+It may be enabled again later.
-If a source file name ends in one of the following extensions, then
-@value{GDBN} infers that its language is the one indicated.
+@kindex enable mem
+@item enable mem @var{nums}@dots{}
+Enable memory regions @var{nums}@dots{}.
-@table @file
+@kindex info mem
+@item info mem
+Print a table of all defined memory regions, with the following columns
+for each region.
-@item .c
-C source file
+@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}.
-@item .C
-@itemx .cc
-@itemx .cp
-@itemx .cpp
-@itemx .cxx
-@itemx .c++
-C++ source file
+@item Lo Address
+The address defining the inclusive lower bound of the memory region.
-@item .f
-@itemx .F
-Fortran source file
+@item Hi Address
+The address defining the exclusive upper bound of the memory region.
-@item .ch
-@itemx .c186
-@itemx .c286
-CHILL source file
+@item Attributes
+The list of attributes set for this memory region.
+@end table
+@end table
-@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.
+@subsection Attributes
+
+@subsubsection Memory Access Mode
+The access mode attributes set whether @value{GDBN} may make read or
+write accesses to a memory region.
+
+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.
+
+@table @code
+@item ro
+Memory is read only.
+@item wo
+Memory is write only.
+@item rw
+Memory is read/write. This is the default.
@end table
-In addition, you may set the language associated with a filename
-extension. @xref{Show, , Displaying the language}.
+@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.
-@node Manually
-@subsection Setting the working language
+@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
-If you allow @value{GDBN} to set the language automatically,
-expressions are interpreted the same way in your debugging session and
-your program.
+@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.
-@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}.
+@table @code
+@item cache
+Enable @value{GDBN} to cache target memory.
+@item nocache
+Disable @value{GDBN} from caching target memory. This is the default.
+@end table
-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:
+@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 Dump/Restore Files
+@section Copy between memory and a file
+@cindex dump/restore files
+@cindex append data to a file
+@cindex dump data to a file
+@cindex restore data from a file
+@kindex dump
+@kindex append
+@kindex restore
+
+The commands @code{dump}, @code{append}, and @code{restore} are used
+for copying data between target memory and a file. Data is written
+into a file using @code{dump} or @code{append}, and restored from a
+file into memory by using @code{restore}. Files may be binary, srec,
+intel hex, or tekhex (but only binary files can be appended).
+
+@table @code
+@kindex dump binary
+@kindex append binary
+@item dump binary memory @var{filename} @var{start_addr} @var{end_addr}
+Dump contents of memory from @var{start_addr} to @var{end_addr} into
+raw binary format file @var{filename}.
+
+@item append binary memory @var{filename} @var{start_addr} @var{end_addr}
+Append contents of memory from @var{start_addr} to @var{end_addr} to
+raw binary format file @var{filename}.
+
+@item dump binary value @var{filename} @var{expression}
+Dump value of @var{expression} into raw binary format file @var{filename}.
+
+@item append binary memory @var{filename} @var{expression}
+Append value of @var{expression} to raw binary format file @var{filename}.
+
+@kindex dump ihex
+@item dump ihex memory @var{filename} @var{start_addr} @var{end_addr}
+Dump contents of memory from @var{start_addr} to @var{end_addr} into
+intel hex format file @var{filename}.
+
+@item dump ihex value @var{filename} @var{expression}
+Dump value of @var{expression} into intel hex format file @var{filename}.
+
+@kindex dump srec
+@item dump srec memory @var{filename} @var{start_addr} @var{end_addr}
+Dump contents of memory from @var{start_addr} to @var{end_addr} into
+srec format file @var{filename}.
+
+@item dump srec value @var{filename} @var{expression}
+Dump value of @var{expression} into srec format file @var{filename}.
+
+@kindex dump tekhex
+@item dump tekhex memory @var{filename} @var{start_addr} @var{end_addr}
+Dump contents of memory from @var{start_addr} to @var{end_addr} into
+tekhex format file @var{filename}.
+
+@item dump tekhex value @var{filename} @var{expression}
+Dump value of @var{expression} into tekhex format file @var{filename}.
+
+@item restore @var{filename} [@var{binary}] @var{bias} @var{start} @var{end}
+Restore the contents of file @var{filename} into memory. The @code{restore}
+command can automatically recognize any known bfd file format, except for
+raw binary. To restore a raw binary file you must use the optional argument
+@var{binary} after the filename.
+
+If @var{bias} is non-zero, its value will be added to the addresses
+contained in the file. Binary files always start at address zero, so
+they will be restored at address @var{bias}. Other bfd files have
+a built-in location; they will be restored at offset @var{bias}
+from that location.
+
+If @var{start} and/or @var{end} are non-zero, then only data between
+file offset @var{start} and file offset @var{end} will be restored.
+These offsets are relative to the addresses in the file, before
+the @var{bias} argument is applied.
+
+@end table
+
+@node Macros
+@chapter C Preprocessor Macros
+
+Some languages, such as C and C++, provide a way to define and invoke
+``preprocessor macros'' which expand into strings of tokens.
+@value{GDBN} can evaluate expressions containing macro invocations, show
+the result of macro expansion, and show a macro's definition, including
+where it was defined.
+
+You may need to compile your program specially to provide @value{GDBN}
+with information about preprocessor macros. Most compilers do not
+include macros in their debugging information, even when you compile
+with the @option{-g} flag. @xref{Compilation}.
+
+A program may define a macro at one point, remove that definition later,
+and then provide a different definition after that. Thus, at different
+points in the program, a macro may have different definitions, or have
+no definition at all. If there is a current stack frame, @value{GDBN}
+uses the macros in scope at that frame's source code line. Otherwise,
+@value{GDBN} uses the macros in scope at the current listing location;
+see @ref{List}.
+
+At the moment, @value{GDBN} does not support the @code{##}
+token-splicing operator, the @code{#} stringification operator, or
+variable-arity macros.
+
+Whenever @value{GDBN} evaluates an expression, it always expands any
+macro invocations present in the expression. @value{GDBN} also provides
+the following commands for working with macros explicitly.
+
+@table @code
+
+@kindex macro expand
+@cindex macro expansion, showing the results of preprocessor
+@cindex preprocessor macro expansion, showing the results of
+@cindex expanding preprocessor macros
+@item macro expand @var{expression}
+@itemx macro exp @var{expression}
+Show the results of expanding all preprocessor macro invocations in
+@var{expression}. Since @value{GDBN} simply expands macros, but does
+not parse the result, @var{expression} need not be a valid expression;
+it can be any string of tokens.
+
+@kindex macro expand-once
+@item macro expand-once @var{expression}
+@itemx macro exp1 @var{expression}
+@i{(This command is not yet implemented.)} Show the results of
+expanding those preprocessor macro invocations that appear explicitly in
+@var{expression}. Macro invocations appearing in that expansion are
+left unchanged. This command allows you to see the effect of a
+particular macro more clearly, without being confused by further
+expansions. Since @value{GDBN} simply expands macros, but does not
+parse the result, @var{expression} need not be a valid expression; it
+can be any string of tokens.
+
+@kindex info macro
+@cindex macro definition, showing
+@cindex definition, showing a macro's
+@item info macro @var{macro}
+Show the definition of the macro named @var{macro}, and describe the
+source location where that definition was established.
+
+@kindex macro define
+@cindex user-defined macros
+@cindex defining macros interactively
+@cindex macros, user-defined
+@item macro define @var{macro} @var{replacement-list}
+@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list}
+@i{(This command is not yet implemented.)} Introduce a definition for a
+preprocessor macro named @var{macro}, invocations of which are replaced
+by the tokens given in @var{replacement-list}. The first form of this
+command defines an ``object-like'' macro, which takes no arguments; the
+second form defines a ``function-like'' macro, which takes the arguments
+given in @var{arglist}.
+
+A definition introduced by this command is in scope in every expression
+evaluated in @value{GDBN}, until it is removed with the @command{macro
+undef} command, described below. The definition overrides all
+definitions for @var{macro} present in the program being debugged, as
+well as any previous user-supplied definition.
+
+@kindex macro undef
+@item macro undef @var{macro}
+@i{(This command is not yet implemented.)} Remove any user-supplied
+definition for the macro named @var{macro}. This command only affects
+definitions provided with the @command{macro define} command, described
+above; it cannot remove definitions present in the program being
+debugged.
+
+@end table
+
+@cindex macros, example of debugging with
+Here is a transcript showing the above commands in action. First, we
+show our source files:
-@example
-print a = b + c
-@end example
+@smallexample
+$ cat sample.c
+#include <stdio.h>
+#include "sample.h"
-@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.
+#define M 42
+#define ADD(x) (M + x)
-@node Automatically
-@subsection Having @value{GDBN} infer the source language
+main ()
+@{
+#define N 28
+ printf ("Hello, world!\n");
+#undef N
+ printf ("We're so creative.\n");
+#define N 1729
+ printf ("Goodbye, world!\n");
+@}
+$ cat sample.h
+#define Q <
+$
+@end smallexample
-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.
+Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}.
+We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the
+compiler includes information about preprocessor macros in the debugging
+information.
-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
+$ gcc -gdwarf-2 -g3 sample.c -o sample
+$
+@end smallexample
-@node Show
-@section Displaying the language
+Now, we start @value{GDBN} on our sample program:
-The following commands help you find out which language is the
-working language, and also what language source files were written in.
+@smallexample
+$ gdb -nw sample
+GNU gdb 2002-05-06-cvs
+Copyright 2002 Free Software Foundation, Inc.
+GDB is free software, @dots{}
+(gdb)
+@end smallexample
-@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.
+We can expand macros and examine their definitions, even when the
+program is not running. @value{GDBN} uses the current listing position
+to decide which macro definitions are in scope:
-@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.
+@smallexample
+(gdb) list main
+3
+4 #define M 42
+5 #define ADD(x) (M + x)
+6
+7 main ()
+8 @{
+9 #define N 28
+10 printf ("Hello, world!\n");
+11 #undef N
+12 printf ("We're so creative.\n");
+(gdb) info macro ADD
+Defined at /home/jimb/gdb/macros/play/sample.c:5
+#define ADD(x) (M + x)
+(gdb) info macro Q
+Defined at /home/jimb/gdb/macros/play/sample.h:1
+ included at /home/jimb/gdb/macros/play/sample.c:2
+#define Q <
+(gdb) macro expand ADD(1)
+expands to: (42 + 1)
+(gdb) macro expand-once ADD(1)
+expands to: once (M + 1)
+(gdb)
+@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
+In the example above, note that @command{macro expand-once} expands only
+the macro invocation explicit in the original text --- the invocation of
+@code{ADD} --- but does not expand the invocation of the macro @code{M},
+which was introduced by @code{ADD}.
-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:
+Once the program is running, GDB uses the macro definitions in force at
+the source line of the current stack frame:
-@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}.
+@smallexample
+(gdb) break main
+Breakpoint 1 at 0x8048370: file sample.c, line 10.
+(gdb) run
+Starting program: /home/jimb/gdb/macros/play/sample
+
+Breakpoint 1, main () at sample.c:10
+10 printf ("Hello, world!\n");
+(gdb)
+@end smallexample
-@item info extensions
-List all the filename extensions and the associated languages.
-@end table
+At line 10, the definition of the macro @code{N} at line 9 is in force:
-@node Checks
-@section Type and range checking
+@smallexample
+(gdb) info macro N
+Defined at /home/jimb/gdb/macros/play/sample.c:9
+#define N 28
+(gdb) macro expand N Q M
+expands to: 28 < 42
+(gdb) print N Q M
+$1 = 1
+(gdb)
+@end smallexample
-@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
+As we step over directives that remove @code{N}'s definition, and then
+give it a new definition, @value{GDBN} finds the definition (or lack
+thereof) in force at each point:
-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.
+@smallexample
+(gdb) next
+Hello, world!
+12 printf ("We're so creative.\n");
+(gdb) info macro N
+The symbol `N' has no definition as a C/C++ preprocessor macro
+at /home/jimb/gdb/macros/play/sample.c:12
+(gdb) next
+We're so creative.
+14 printf ("Goodbye, world!\n");
+(gdb) info macro N
+Defined at /home/jimb/gdb/macros/play/sample.c:13
+#define N 1729
+(gdb) macro expand N Q M
+expands to: 1729 < 42
+(gdb) print N Q M
+$2 = 0
+(gdb)
+@end smallexample
-@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 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.
@menu
-* Type Checking:: An overview of type checking
-* Range Checking:: An overview of range checking
+* Set Tracepoints::
+* Analyze Collected Data::
+* Tracepoint Variables::
@end menu
-@cindex type checking
-@cindex checks, type
-@node Type Checking
-@subsection An overview of type checking
+@node Set Tracepoints
+@section Commands to Set Tracepoints
-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,
+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.
+
+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.
+
+This section describes commands to set tracepoints and associated
+conditions and actions.
+
+@menu
+* Create and Delete Tracepoints::
+* Enable and Disable Tracepoints::
+* Tracepoint Passcounts::
+* Tracepoint Actions::
+* Listing Tracepoints::
+* Starting and Stopping Trace Experiment::
+@end menu
+
+@node Create and Delete Tracepoints
+@subsection Create and Delete Tracepoints
+
+@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:
@smallexample
-1 + 2 @result{} 3
-@exdent but
-@error{} 1 + 2.3
+(@value{GDBP}) @b{trace foo.c:121} // a source file and line number
+
+(@value{GDBP}) @b{trace +2} // 2 lines forward
+
+(@value{GDBP}) @b{trace my_function} // first source line of function
+
+(@value{GDBP}) @b{trace *my_function} // EXACT start address of function
+
+(@value{GDBP}) @b{trace *0x2117c4} // an address
@end smallexample
-The second example fails because the @code{CARDINAL} 1 is not
-type-compatible with the @code{REAL} 2.3.
+@noindent
+You can abbreviate @code{trace} as @code{tr}.
-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.
+@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.
-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.
+@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.
-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.
+Examples:
-@value{GDBN} provides some additional commands for controlling the type checker:
+@smallexample
+(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints
+
+(@value{GDBP}) @b{delete trace} // remove all tracepoints
+@end smallexample
+
+@noindent
+You can abbreviate this command as @code{del tr}.
+@end table
+
+@node Enable and Disable Tracepoints
+@subsection Enable and Disable Tracepoints
-@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.
+@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.
-@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.
+@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
-@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.
+@node Tracepoint Passcounts
+@subsection Tracepoint Passcounts
-@item show type
-Show the current setting of the type checker, and whether or not @value{GDBN}
-is setting it automatically.
+@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
+(@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
-@cindex range checking
-@cindex checks, range
-@node Range Checking
-@subsection An overview of range checking
+@node Tracepoint Actions
+@subsection Tracepoint Action Lists
-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.
+@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}.
-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.
+@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}.
-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
+@smallexample
+(@value{GDBP}) @b{collect @var{data}} // collect some data
-@example
-@var{m} + 1 @result{} @var{s}
-@end example
+(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
-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{GDBP}) @b{end} // signals the end of actions.
+@end smallexample
-@value{GDBN} provides some additional commands for controlling the range checker:
+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.
-@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++, 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.
+@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
-@menu
-* C:: C and C++
-* Modula-2:: Modula-2
-* Chill:: Chill
-@end menu
+@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:
-@node C
-@subsection C and C++
+@table @code
+@item $regs
+collect all registers
-@cindex C and C++
-@cindex expressions in C or C++
+@item $args
+collect all function arguments
-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.
+@item $locals
+collect all local variables.
+@end table
-@cindex C@t{++}
-@cindex @code{g++}, @sc{gnu} C@t{++} compiler
-@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}).
+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.
-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.
+The command @code{info scope} (@pxref{Symbols, info scope}) is
+particularly useful for figuring out what data to collect.
-@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
+@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):
-@node C Operators
-@subsubsection C and C++ operators
+@smallexample
+> while-stepping 12
+ > collect $regs, myglobal
+ > end
+>
+@end smallexample
-@cindex C and C++ operators
+@noindent
+You may abbreviate @code{while-stepping} as @code{ws} or
+@code{stepping}.
+@end table
-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.
+@node Listing Tracepoints
+@subsection Listing Tracepoints
-For the purposes of C and C++, the following definitions hold:
+@table @code
+@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:
@itemize @bullet
-
@item
-@emph{Integral types} include @code{int} with any of its storage-class
-specifiers; @code{char}; @code{enum}; and, for C++, @code{bool}.
-
+its number
@item
-@emph{Floating-point types} include @code{float}, @code{double}, and
-@code{long double} (if supported by the target platform).
-
+whether it is enabled or disabled
@item
-@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
-
+its address
@item
-@emph{Scalar types} include all of the above.
-
+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
+@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
+
@noindent
-The following operators are supported. They are listed here
-in order of increasing precedence:
+This command can be abbreviated @code{info tp}.
+@end table
+
+@node Starting and Stopping Trace Experiment
+@subsection Starting and Stopping Trace Experiment
@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.
+@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.
-@item =
-Assignment. The value of an assignment expression is the value
-assigned. Defined on scalar types.
+@kindex tstop
+@cindex stop a running trace experiment
+@item tstop
+This command takes no arguments. It ends the trace experiment, and
+stops collecting data.
-@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{%}.
+@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.
-@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.
+@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
-@item ||
-Logical @sc{or}. Defined on integral types.
+Here is an example of the commands we described so far:
-@item &&
-Logical @sc{and}. Defined on integral types.
+@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
-@item |
-Bitwise @sc{or}. Defined on integral types.
-@item ^
-Bitwise exclusive-@sc{or}. Defined on integral types.
+@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.
-@item &
-Bitwise @sc{and}. Defined on integral types.
+@menu
+* 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
-@item ==@r{, }!=
-Equality and inequality. Defined on scalar types. The value of these
-expressions is 0 for false and non-zero for true.
+@node tfind
+@subsection @code{tfind @var{n}}
+
+@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.
+
+Here are the various forms of using the @code{tfind} command.
+
+@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).
+
+@item tfind none
+Stop debugging trace snapshots, resume @emph{live} debugging.
+
+@item tfind end
+Same as @samp{tfind none}.
+
+@item tfind
+No argument means find the next trace snapshot.
+
+@item tfind -
+Find the previous trace snapshot before the current one. This permits
+retracing earlier steps.
+
+@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.
+
+@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 tfind outside @var{addr1}, @var{addr2}
+Find the next snapshot whose PC is outside the given range of
+addresses.
+
+@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
+
+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 <@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.
+@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 <<@r{, }>>
-left shift, and right shift. Defined on integral types.
+Or, if we want to examine the variable @code{X} at each source line in
+the buffer:
-@item @@
-The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+@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 +@r{, }-
-Addition and subtraction. Defined on integral types, floating-point types and
-pointer types.
+@node tdump
+@subsection @code{tdump}
+@kindex tdump
+@cindex dump all data collected at tracepoint
+@cindex tracepoint data, display
-@item *@r{, }/@r{, }%
-Multiplication, division, and modulus. Multiplication and division are
-defined on integral and floating-point types. Modulus is defined on
-integral types.
+This command takes no arguments. It prints all the data collected at
+the current trace snapshot.
-@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.
+@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 *
-Pointer dereferencing. Defined on pointer types. Same precedence as
-@code{++}.
+(@value{GDBP})
+@end smallexample
-@item &
-Address operator. Defined on variables. Same precedence as @code{++}.
+@node save-tracepoints
+@subsection @code{save-tracepoints @var{filename}}
+@kindex save-tracepoints
+@cindex save tracepoints for future sessions
-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.
+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 -
-Negative. Defined on integral and floating-point types. Same
-precedence as @code{++}.
+@node Tracepoint Variables
+@section Convenience Variables for Tracepoints
+@cindex tracepoint variables
+@cindex convenience variables for tracepoints
-@item !
-Logical negation. Defined on integral types. Same precedence as
-@code{++}.
+@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.
-@item ~
-Bitwise complement operator. Defined on integral types. Same precedence as
-@code{++}.
+@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.
-@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.
+@vindex $trace_file
+@item (char []) $trace_file
+The source file for the current trace snapshot.
-@item .*@r{, }->*
-Dereferences of pointers to members.
+@vindex $trace_func
+@item (char []) $trace_func
+The name of the function containing @code{$tracepoint}.
+@end table
-@item []
-Array indexing. @code{@var{a}[@var{i}]} is defined as
-@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
+Note: @code{$trace_file} is not suitable for use in @code{printf},
+use @code{output} instead.
-@item ()
-Function parameter list. 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 ::
-C++ scope resolution operator. Defined on @code{struct}, @code{union},
-and @code{class} types.
+@smallexample
+(@value{GDBP}) @b{tfind start}
-@item ::
-Doubled colons also represent the @value{GDBN} scope operator
-(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
-above.
-@end table
+(@value{GDBP}) @b{while $trace_frame != -1}
+> output $trace_file
+> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
+> tfind
+> end
+@end smallexample
-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.
+@node Overlays
+@chapter Debugging Programs That Use Overlays
+@cindex overlays
+
+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.
@menu
-* C Constants::
+* 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 C Constants
-@subsubsection C and C++ constants
+@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.
+
+@c NB: In the below the mapped area's size is greater or equal to the
+@c size of all overlays. This is intentional to remind the developer
+@c that overlays don't necessarily need to be the same size.
-@cindex C and C++ constants
+@smallexample
+@group
+ Data Instruction Larger
+Address Space Address Space Address Space
++-----------+ +-----------+ +-----------+
+| | | | | |
++-----------+ +-----------+ +-----------+<-- overlay 1
+| program | | main | .----| overlay 1 | load address
+| variables | | program | | +-----------+
+| and heap | | | | | |
++-----------+ | | | +-----------+<-- overlay 2
+| | +-----------+ | | | load address
++-----------+ | | | .-| overlay 2 |
+ | | | | | |
+ mapped --->+-----------+ | | +-----------+
+ address | | | | | |
+ | overlay | <-' | | |
+ | area | <---' +-----------+<-- overlay 3
+ | | <---. | | load address
+ +-----------+ `--| overlay 3 |
+ | | | |
+ +-----------+ | |
+ +-----------+
+ | |
+ +-----------+
+
+ @anchor{A code overlay}A code overlay
+@end group
+@end smallexample
-@value{GDBN} allows you to express the constants of C and C++ in the
-following ways:
+The diagram (@pxref{A code overlay}) shows a system with separate data
+and instruction address spaces. To map an overlay, the program copies
+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. 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.
+
+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}.
+
+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:
@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.
+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.
@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.
+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.
@item
-Enumerated constants consist of enumerated identifiers, or their
-integral equivalents.
+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}.
@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.
+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.
+
+@end itemize
+
+The overlay system described above is rather simple, and could be
+improved in many ways:
+
+@itemize @bullet
@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.
+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
-Pointer constants are an integral value. You can also write pointers
-to constants using the C operator @samp{&}.
+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
-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.
+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.
+
@end itemize
-@menu
-* C plus plus expressions::
-* C Defaults::
-* C Checks::
-* Debugging C::
-@end menu
+@node Overlay Commands
+@section Overlay Commands
+
+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.
+
+@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:
+
+@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.
+
+@end table
+
+Normally, when @value{GDBN} prints a code address, it includes the name
+of the function the address falls in:
-@node C plus plus expressions
-@subsubsection C++ expressions
-
-@cindex expressions in C++
-@value{GDBN} expression handling can interpret most C++ expressions.
-
-@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
+@smallexample
+(gdb) print main
+$3 = @{int ()@} 0x11a0 <main>
+@end smallexample
+@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:
-@enumerate
+@smallexample
+(gdb) overlay list
+No sections are mapped.
+(gdb) print foo
+$5 = @{int (int)@} 0x100000 <*foo*>
+@end smallexample
+@noindent
+When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
+name normally:
-@cindex member functions
-@item
-Member function calls are allowed; you can use expressions like
+@smallexample
+(gdb) overlay list
+Section .ov.foo.text, loaded at 0x100000 - 0x100034,
+ mapped at 0x1016 - 0x104a
+(gdb) print foo
+$6 = @{int (int)@} 0x1016 <foo>
+@end smallexample
-@example
-count = aml->GetOriginal(x, y)
-@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:
-@vindex this@r{, inside C@t{++} member functions}
-@cindex namespace in C++
+@itemize @bullet
@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++.
-
-@cindex call overloaded functions
-@cindex overloaded functions, calling
-@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. @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.
+@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
+@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.
-The @value{GDBN} command-completion facility can simplify this;
-see @ref{Completion, ,Command completion}.
+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
+@smallexample
+struct
+@{
+ /* The overlay's mapped address. */
+ unsigned long vma;
-In addition, when used with HP's C++ 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.
+ /* The size of the overlay, in bytes. */
+ unsigned long size;
-@node C Defaults
-@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 smallexample
-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.
+@item @code{_novlys}:
+This variable must be a four-byte signed integer, holding the total
+number of elements in @code{_ovly_table}.
+
+@end table
+
+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.
+
+In addition, your overlay manager may define a function called
+@code{_ovly_debug_event}. If this function is defined, @value{GDBN}
+will silently set a breakpoint there. If the overlay manager then
+calls this function whenever it has changed the overlay table, this
+will enable @value{GDBN} to accurately keep track of which overlays
+are in program memory, and update any breakpoints that may be set
+in overlays. This will allow breakpoints to work even if the
+overlays are kept in ROM or other non-writable memory while they
+are not being executed.
+
+@node Overlay Sample Program
+@section Overlay Sample Program
+@cindex overlay example program
+
+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.
+
+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}:
-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.
+@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
+
+You can build the test program using the @code{d10v-elf} GCC
+cross-compiler like this:
-@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.
+@smallexample
+$ 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 smallexample
-@node C Checks
-@subsubsection C and C++ type and range checks
+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}.
-@cindex C and C++ checks
-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:
+@node Languages
+@chapter Using @value{GDBN} with Different Languages
+@cindex languages
-@itemize @bullet
-@item
-The two variables are structured and have the same structure, union, or
-enumerated tag.
+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}.
-@item
-The two variables have the same type name, or types that have been
-declared equivalent through @code{typedef}.
+@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}.
-@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
+@menu
+* Setting:: Switching between source languages
+* Show:: Displaying the language
+* Checks:: Type and range checks
+* Support:: Supported languages
+@end menu
-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 Setting
+@section Switching between source languages
-@node Debugging C
-@subsubsection @value{GDBN} and 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.
-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{@{...@}}.
+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}.
-The @code{@@} operator aids in the debugging of dynamic arrays, formed
-with pointers and a memory allocation function. @xref{Expressions,
-,Expressions}.
+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.
@menu
-* Debugging C plus plus::
+* Filenames:: Filename extensions and languages.
+* Manually:: Setting the working language manually
+* Automatically:: Having @value{GDBN} infer the source language
@end menu
-@node Debugging C plus plus
-@subsubsection @value{GDBN} features for C++
+@node Filenames
+@subsection List of filename extensions and languages
-@cindex commands for C++
+If a source file name ends in one of the following extensions, then
+@value{GDBN} infers that its language is the one indicated.
-Some @value{GDBN} commands are particularly useful with C++, and some are
-designed specifically for use with C++. Here is a summary:
+@table @file
-@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}.
+@item .c
+C source file
-@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}.
+@item .C
+@itemx .cc
+@itemx .cp
+@itemx .cpp
+@itemx .cxx
+@itemx .c++
+C@t{++} source file
-@cindex C++ exception handling
-@item catch throw
-@itemx catch catch
-Debug C++ exception handling using these commands. @xref{Set
-Catchpoints, , Setting catchpoints}.
+@item .f
+@itemx .F
+Fortran source file
-@cindex inheritance
-@item ptype @var{typename}
-Print inheritance relationships as well as other information for type
-@var{typename}.
-@xref{Symbols, ,Examining the Symbol Table}.
+@c OBSOLETE @item .ch
+@c OBSOLETE @itemx .c186
+@c OBSOLETE @itemx .c286
+@c OBSOLETE CHILL source file
-@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}.
+@item .mod
+Modula-2 source 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 .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
-@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++ compiler (@code{aCC}).)
+In addition, you may set the language associated with a filename
+extension. @xref{Show, , Displaying the language}.
-@kindex set overload-resolution
-@cindex overloaded functions, overload resolution
-@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 (see @ref{C plus plus expressions, ,C++
-expressions}, for details). If it cannot find a match, it emits a
-message.
+@node Manually
+@subsection Setting the working language
-@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.
+If you allow @value{GDBN} to set the language automatically,
+expressions are interpreted the same way in your debugging session and
+your program.
-@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.
-@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.
+@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}.
-@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
+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:
-@node M2 Operators
-@subsubsection Operators
-@cindex Modula-2 operators
+@smallexample
+print a = b + c
+@end smallexample
-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:
+@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.
-@itemize @bullet
+@node Automatically
+@subsection Having @value{GDBN} infer the source language
-@item
-@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
-their subranges.
+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.
-@item
-@emph{Character types} consist of @code{CHAR} and its subranges.
+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.
-@item
-@emph{Floating-point types} consist of @code{REAL}.
+@node Show
+@section Displaying the language
-@item
-@emph{Pointer types} consist of anything declared as @code{POINTER TO
-@var{type}}.
+The following commands help you find out which language is the
+working language, and also what language source files were written in.
-@item
-@emph{Scalar types} consist of all of the above.
+@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
-@emph{Set types} consist of @code{SET} and @code{BITSET} types.
+@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
-@emph{Boolean types} consist of @code{BOOLEAN}.
-@end itemize
+@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
-The following operators are supported, and appear in order of
-increasing precedence:
+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 ,
-Function argument or array index separator.
-
-@item :=
-Assignment. The value of @var{var} @code{:=} @var{value} is
-@var{value}.
+@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 <@r{, }>
-Less than, greater than on integral, floating-point, or enumerated
-types.
+@item info extensions
+List all the filename extensions and the associated languages.
+@end table
-@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{<}.
+@node Checks
+@section Type and range checking
-@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.
+@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
-@item IN
-Set membership. Defined on set types and the types of their members.
-Same precedence as @code{<}.
+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.
-@item OR
-Boolean disjunction. Defined on boolean types.
+@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.
-@item AND@r{, }&
-Boolean conjunction. Defined on boolean types.
+@menu
+* Type Checking:: An overview of type checking
+* Range Checking:: An overview of range checking
+@end menu
-@item @@
-The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+@cindex type checking
+@cindex checks, type
+@node Type Checking
+@subsection An overview of type checking
-@item +@r{, }-
-Addition and subtraction on integral and floating-point types, or union
-and difference on set types.
+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,
-@item *
-Multiplication on integral and floating-point types, or set intersection
-on set types.
+@smallexample
+1 + 2 @result{} 3
+@exdent but
+@error{} 1 + 2.3
+@end smallexample
-@item /
-Division on floating-point types, or symmetric set difference on set
-types. Same precedence as @code{*}.
+The second example fails because the @code{CARDINAL} 1 is not
+type-compatible with the @code{REAL} 2.3.
-@item DIV@r{, }MOD
-Integer division and remainder. Defined on integral types. Same
-precedence as @code{*}.
+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.
-@item -
-Negative. Defined on @code{INTEGER} and @code{REAL} data.
+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.
-@item ^
-Pointer dereferencing. Defined on pointer types.
+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.
-@item NOT
-Boolean negation. Defined on boolean types. Same precedence as
-@code{^}.
+@value{GDBN} provides some additional commands for controlling the type checker:
-@item .
-@code{RECORD} field selector. Defined on @code{RECORD} data. Same
-precedence as @code{^}.
+@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 []
-Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
+@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 ()
-Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
-as @code{^}.
+@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 ::@r{, }.
-@value{GDBN} and Modula-2 scope operators.
+@item show type
+Show the current setting of the type checker, and whether or not @value{GDBN}
+is setting it automatically.
@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
-
-@cindex Modula-2 built-ins
-@node Built-In Func/Proc
-@subsubsection Built-in functions and procedures
-
-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}).
+@cindex range checking
+@cindex checks, range
+@node Range Checking
+@subsection An overview of range checking
-@item n
-represents a variable or constant of integral or floating-point type.
+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 r
-represents a variable or constant of floating-point type.
+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.
-@item t
-represents a type.
+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
-@item v
-represents a variable.
+@smallexample
+@var{m} + 1 @result{} @var{s}
+@end smallexample
-@item x
-represents a variable or constant of one of many types. See the
-explanation of the function for details.
-@end table
+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.
-All Modula-2 built-in procedures also return a result, described below.
+@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 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 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 DEC(@var{v},@var{i})
-Decrements the value in the variable @var{v} by @var{i}. Returns the
-new value.
+@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 EXCL(@var{m},@var{s})
-Removes the element @var{m} from the set @var{s}. Returns the new
-set.
+@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 FLOAT(@var{i})
-Returns the floating point equivalent of the integer @var{i}.
+@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
-@item HIGH(@var{a})
-Returns the index of the last member of @var{a}.
+@node Support
+@section Supported languages
-@item INC(@var{v})
-Increments the value in the variable @var{v} by one. Returns the new value.
+@value{GDBN} supports C, C@t{++}, Fortran, Java,
+@c OBSOLETE 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.
-@item INC(@var{v},@var{i})
-Increments the value in the variable @var{v} by @var{i}. Returns the
-new value.
+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.
-@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.
+@menu
+* C:: C and C@t{++}
+* Modula-2:: Modula-2
+@c OBSOLETE * Chill:: Chill
+@end menu
-@item MAX(@var{t})
-Returns the maximum value of the type @var{t}.
+@node C
+@subsection C and C@t{++}
-@item MIN(@var{t})
-Returns the minimum value of the type @var{t}.
+@cindex C and C@t{++}
+@cindex expressions in C or C@t{++}
-@item ODD(@var{i})
-Returns boolean TRUE if @var{i} is an odd number.
+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.
-@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.
+@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}).
-@item SIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+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.
-@item TRUNC(@var{r})
-Returns the integral part of @var{r}.
+@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
-@item VAL(@var{t},@var{i})
-Returns the member of the type @var{t} whose ordinal value is @var{i}.
-@end table
+@node C Operators
+@subsubsection C and C@t{++} operators
-@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 C and C@t{++} operators
-@cindex Modula-2 constants
-@node M2 Constants
-@subsubsection Constants
+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.
-@value{GDBN} allows you to express the constants of Modula-2 in the following
-ways:
+For the purposes of C and C@t{++}, the following definitions hold:
@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++ constants}, for a brief explanation of escape
-sequences.
+@emph{Integral types} include @code{int} with any of its storage-class
+specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}.
@item
-Enumerated constants consist of an enumerated identifier.
+@emph{Floating-point types} include @code{float}, @code{double}, and
+@code{long double} (if supported by the target platform).
@item
-Boolean constants consist of the identifiers @code{TRUE} and
-@code{FALSE}.
+@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
@item
-Pointer constants consist of integral values only.
+@emph{Scalar types} include all of the above.
-@item
-Set constants are not yet supported.
@end itemize
-@node M2 Defaults
-@subsubsection Modula-2 defaults
-@cindex Modula-2 defaults
+@noindent
+The following operators are supported. They are listed here
+in order of increasing precedence:
-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 @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.
-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.
+@item =
+Assignment. The value of an assignment expression is the value
+assigned. Defined on scalar types.
-@node Deviations
-@subsubsection Deviations from standard Modula-2
-@cindex Modula-2, deviations from
+@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{%}.
-A few changes have been made to make Modula-2 programs easier to debug.
-This is done primarily via loosening its type strictness:
+@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.
-@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 ||
+Logical @sc{or}. Defined on integral types.
-@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 &&
+Logical @sc{and}. Defined on integral types.
-@item
-The assignment operator (@code{:=}) returns the value of its right-hand
-argument.
+@item |
+Bitwise @sc{or}. Defined on integral types.
-@item
-All built-in procedures both modify @emph{and} return their argument.
-@end itemize
+@item ^
+Bitwise exclusive-@sc{or}. Defined on integral types.
-@node M2 Checks
-@subsubsection Modula-2 type and range checks
-@cindex Modula-2 checks
+@item &
+Bitwise @sc{and}. Defined on integral types.
-@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
+@item ==@r{, }!=
+Equality and inequality. Defined on scalar types. The value of these
+expressions is 0 for false and non-zero for true.
-@value{GDBN} considers two Modula-2 variables type equivalent if:
+@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.
-@itemize @bullet
-@item
-They are of types that have been declared equivalent via a @code{TYPE
-@var{t1} = @var{t2}} statement
+@item <<@r{, }>>
+left shift, and right shift. Defined on integral types.
-@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
+@item @@
+The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
-As long as type checking is enabled, any attempt to combine variables
-whose types are not equivalent is an error.
+@item +@r{, }-
+Addition and subtraction. Defined on integral types, floating-point types and
+pointer types.
-Range checking is done on all mathematical operations, assignment, array
-index bounds, and all built-in functions and procedures.
+@item *@r{, }/@r{, }%
+Multiplication, division, and modulus. Multiplication and division are
+defined on integral and floating-point types. Modulus is defined on
+integral types.
-@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
+@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.
-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:
+@item *
+Pointer dereferencing. Defined on pointer types. Same precedence as
+@code{++}.
-@example
+@item &
+Address operator. Defined on variables. Same precedence as @code{++}.
-@var{module} . @var{id}
-@var{scope} :: @var{id}
-@end example
+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.
-@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.
+@item -
+Negative. Defined on integral and floating-point types. Same
+precedence as @code{++}.
-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}.
+@item !
+Logical negation. Defined on integral types. Same precedence as
+@code{++}.
-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}.
+@item ~
+Bitwise complement operator. Defined on integral types. Same precedence as
+@code{++}.
-@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++: @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.
+@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.
-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++. However, because an
-address can be specified by an integral constant, the construct
-@samp{@{@var{type}@}@var{adrexp}} is still useful.
+@item .*@r{, }->*
+Dereferences of pointers to members.
-@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.
+@item []
+Array indexing. @code{@var{a}[@var{i}]} is defined as
+@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
-@node Chill
-@subsection Chill
+@item ()
+Function parameter list. Same precedence as @code{->}.
-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.
+@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
-@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.
+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
-* 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::
+* C Constants::
@end menu
-@node How modes are displayed
-@subsubsection How modes are displayed
+@node C Constants
+@subsubsection C and C@t{++} constants
-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:
+@cindex C and C@t{++} constants
+
+@value{GDBN} allows you to express the constants of C and C@t{++} in the
+following ways:
-@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},
+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
-@emph{Character Mode} which is predefined by @code{CHAR},
+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
-@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.
+Enumerated constants consist of enumerated identifiers, or their
+integral equivalents.
+
@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
+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 @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
+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 @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.
+Pointer constants are an integral value. You can also write pointers
+to constants using the C operator @samp{&}.
+
@item
-@emph{Free Reference Mode} which is displayed by the keyword @code{PTR}.
+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
-@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.
+@menu
+* C plus plus expressions::
+* C Defaults::
+* C Checks::
-@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
+* Debugging C::
+@end menu
-@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.
+@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
-@emph{Buffer Mode} which is displayed by
+Member function calls are allowed; you can use expressions like
+
@smallexample
-@code{BUFFER (<buffer length>)<buffer element mode>}
+count = aml->GetOriginal(x, y)
@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}
+@vindex this@r{, inside C@t{++} member functions}
+@cindex namespace in C@t{++}
@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}.
+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{++}.
-@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
+@cindex call overloaded functions
+@cindex overloaded functions, calling
+@cindex type conversions in C@t{++}
@item
-@emph{Bit String Mode} which is displayed by
-@smallexample
-@code{BOOLS(<string
-length>)}
-@end smallexample
-@end itemize
+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.
-@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
+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{++}}.
-@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.
+You must specify @code{set overload-resolution off} in order to use an
+explicit function signature to call an overloaded function, as in
@smallexample
-(@value{GDBP}) ptype str
-type = STRUCT (
- as x,
- bs x,
- CASE bs OF
- (karli):
- cs a
- (ott):
- ds x
- ESAC
-)
+p 'foo(char,int)'('x', 13)
@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:
+The @value{GDBN} command-completion facility can simplify this;
+see @ref{Completion, ,Command completion}.
-@smallexample
-set result := EXPR
-@end smallexample
+@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.
-@noindent
-This does the same as the Chill action @code{RESULT EXPR} (which
-is not available in @value{GDBN}).
+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}.
-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{->}.
+@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
-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.
+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.
-@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
+@node C Defaults
+@subsubsection C and C@t{++} defaults
-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}.
+@cindex C and C@t{++} defaults
-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.
+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.
-@smallexample
-(@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX
-@end smallexample
+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.
-@node Values and their Operations
-@subsubsection Values and their Operations
+@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.
-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.
+@node C Checks
+@subsubsection C and C@t{++} type and range checks
-This section describes how values have to be specified and which
-operations are legal to be used with such values.
+@cindex C and C@t{++} checks
-@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.
+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:
-@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++ 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.
+The two variables are structured and have the same structure, union, or
+enumerated tag.
@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).
+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
-@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
+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
-@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:
+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.
-@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
+@node Debugging C
+@subsubsection @value{GDBN} and C
-@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.
+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{@{...@}}.
-@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.
+The @code{@@} operator aids in the debugging of dynamic arrays, formed
+with pointers and a memory allocation function. @xref{Expressions,
+,Expressions}.
-@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.
+@menu
+* Debugging C plus plus::
+@end menu
-@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.
+@node Debugging C plus plus
+@subsubsection @value{GDBN} features for C@t{++}
-@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.
+@cindex commands for C@t{++}
-@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.}.
+Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
+designed specifically for use with C@t{++}. Here is a summary:
-Values of duration mode locations are represented by @code{ULONG} literals.
+@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}.
-Values of time mode locations appear as
-@smallexample
-@code{TIME(<secs>:<nsecs>)}
-@end smallexample
+@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}.
-@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
+@cindex inheritance
+@item ptype @var{typename}
+Print inheritance relationships as well as other information for type
+@var{typename}.
+@xref{Symbols, ,Examining the Symbol Table}.
-@item Zero-adic Operator Value
-The zero-adic operator value is derived from the instance value for the
-current active process.
+@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 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}:
+@item set print object
+@itemx show print object
+Choose whether to print derived (actual) or declared types of objects.
+@xref{Print Settings, ,Print settings}.
-@table @code
-@item @code{OR, ORIF, XOR}
-@itemx @code{AND, ANDIF}
-@itemx @code{NOT}
-Logical operators defined over operands of boolean mode.
+@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}).)
-@item @code{=, /=}
-Equality and inequality operators defined over all modes.
+@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 @code{>, >=}
-@itemx @code{<, <=}
-Relational operators defined over predefined modes.
+@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 @code{+, -}
-@itemx @code{*, /, MOD, REM}
-Arithmetic operators defined over predefined modes.
+@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
-@item @code{-}
-Change sign operator.
+@node Modula-2
+@subsection Modula-2
-@item @code{//}
-String concatenation operator.
+@cindex Modula-2, @value{GDBN} support
-@item @code{()}
-String repetition operator.
+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.
-@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->}).
+@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
-@item @code{OR, XOR}
-@itemx @code{AND}
-@itemx @code{NOT}
-Powerset and bitstring operators.
+@node M2 Operators
+@subsubsection Operators
+@cindex Modula-2 operators
-@item @code{>, >=}
-@itemx @code{<, <=}
-Powerset inclusion 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:
-@item @code{IN}
-Membership operator.
-@end table
-@end table
+@itemize @bullet
-@node Chill type and range checks
-@subsubsection Chill type and range checks
+@item
+@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
+their subranges.
-@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.
+@item
+@emph{Character types} consist of @code{CHAR} and its subranges.
-Range checking is done on all mathematical operations, assignment, array
-index bounds and all built in procedures.
+@item
+@emph{Floating-point types} consist of @code{REAL}.
-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.
+@item
+@emph{Pointer types} consist of anything declared as @code{POINTER TO
+@var{type}}.
-All checks can be disabled by the @value{GDBN} command @code{set check
-off}.
+@item
+@emph{Scalar types} consist of all of the above.
-@ignore
-@c Deviations from the Chill Standard Z200/88
-see last paragraph ?
-@end ignore
+@item
+@emph{Set types} consist of @code{SET} and @code{BITSET} types.
-@node Chill defaults
-@subsubsection Chill defaults
+@item
+@emph{Boolean types} consist of @code{BOOLEAN}.
+@end itemize
-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.
+@noindent
+The following operators are supported, and appear in order of
+increasing precedence:
-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.
+@table @code
+@item ,
+Function argument or array index separator.
-@node Symbols
-@chapter Examining the Symbol Table
+@item :=
+Assignment. The value of @var{var} @code{:=} @var{value} is
+@var{value}.
-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}).
+@item <@r{, }>
+Less than, greater than on integral, floating-point, or enumerated
+types.
-@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
+@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{<}.
-@noindent
-looks up the value of @code{x} in the scope of the file @file{foo.c}.
+@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.
-@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 IN
+Set membership. Defined on set types and the types of their members.
+Same precedence as @code{<}.
-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 OR
+Boolean disjunction. Defined on boolean types.
-@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 AND@r{, }&
+Boolean conjunction. Defined on boolean types.
-@item whatis
-Print the data type of @code{$}, the last value in the value history.
+@item @@
+The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
-@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 +@r{, }-
+Addition and subtraction on integral and floating-point types, or union
+and difference on set types.
-@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.
+@item *
+Multiplication on integral and floating-point types, or set intersection
+on set types.
-For example, for this variable declaration:
+@item /
+Division on floating-point types, or symmetric set difference on set
+types. Same precedence as @code{*}.
-@example
-struct complex @{double real; double imag;@} v;
-@end example
+@item DIV@r{, }MOD
+Integer division and remainder. Defined on integral types. Same
+precedence as @code{*}.
-@noindent
-the two commands give this output:
+@item -
+Negative. Defined on @code{INTEGER} and @code{REAL} data.
-@example
-@group
-(@value{GDBP}) whatis v
-type = struct complex
-(@value{GDBP}) ptype v
-type = struct complex @{
- double real;
- double imag;
-@}
-@end group
-@end example
+@item ^
+Pointer dereferencing. Defined on pointer types.
-@noindent
-As with @code{whatis}, using @code{ptype} without an argument refers to
-the type of @code{$}, the last value in the value history.
+@item NOT
+Boolean negation. Defined on boolean types. Same precedence as
+@code{^}.
-@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}.
+@item .
+@code{RECORD} field selector. Defined on @code{RECORD} data. Same
+precedence as @code{^}.
-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.
+@item []
+Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
-@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.
+@item ()
+Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
+as @code{^}.
-@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.
+@item ::@r{, }.
+@value{GDBN} and Modula-2 scope operators.
+@end table
-@kindex info functions
-@item info functions
-Print the names and data types of all defined functions.
+@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
-@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 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).
+@node Built-In Func/Proc
+@subsubsection Built-in functions and procedures
+@cindex Modula-2 built-ins
-@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}.
+Modula-2 also makes available several built-in procedures and functions.
+In describing these, the following metavariables are used:
-@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}.
-@end ignore
+@table @var
-@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:
+@item a
+represents an @code{ARRAY} variable.
-@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 c
+represents a @code{CHAR} constant or variable.
-@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.
+@item i
+represents a variable or constant of integral type.
-@kindex show symbol-reloading
-@item show symbol-reloading
-Show the current @code{on} or @code{off} setting.
-@end table
+@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}).
-@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.
+@item n
+represents a variable or constant of integral or floating-point type.
-A change in the setting of this subcommand will not take effect until
-the next time symbols for a file are loaded.
+@item r
+represents a variable or constant of floating-point type.
-@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
+@item t
+represents a type.
-@kindex show opaque-type-resolution
-@item show opaque-type-resolution
-Show whether opaque types are resolved or not.
+@item v
+represents a variable.
-@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}).
+@item x
+represents a variable or constant of one of many types. See the
+explanation of the function for details.
@end table
-@node Altering
-@chapter Altering Execution
+All Modula-2 built-in procedures also return a result, described below.
-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.
+@table @code
+@item ABS(@var{n})
+Returns the absolute value of @var{n}.
-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.
+@item CAP(@var{c})
+If @var{c} is a lower case letter, it returns its upper case
+equivalent, otherwise it returns its argument.
-@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
+@item CHR(@var{i})
+Returns the character whose ordinal value is @var{i}.
-@node Assignment
-@section Assignment to variables
+@item DEC(@var{v})
+Decrements the value in the variable @var{v} by one. Returns the new value.
-@cindex assignment
-@cindex setting variables
-To alter the value of a variable, evaluate an assignment expression.
-@xref{Expressions, ,Expressions}. For example,
+@item DEC(@var{v},@var{i})
+Decrements the value in the variable @var{v} by @var{i}. Returns the
+new value.
-@example
-print x=4
-@end example
+@item EXCL(@var{m},@var{s})
+Removes the element @var{m} from the set @var{s}. Returns the new
+set.
-@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.
+@item FLOAT(@var{i})
+Returns the floating point equivalent of the integer @var{i}.
-@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.
+@item HIGH(@var{a})
+Returns the index of the last member of @var{a}.
-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}:
+@item INC(@var{v})
+Increments the value in the variable @var{v} by one. Returns the new value.
-@example
-(@value{GDBP}) whatis width
-type = double
-(@value{GDBP}) p width
-$4 = 13
-(@value{GDBP}) set width=47
-Invalid syntax in expression.
-@end example
+@item INC(@var{v},@var{i})
+Increments the value in the variable @var{v} by @var{i}. Returns the
+new value.
-@noindent
-The invalid expression, of course, is @samp{=47}. In
-order to actually set the program's variable @code{width}, use
+@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.
-@example
-(@value{GDBP}) set var width=47
-@end example
+@item MAX(@var{t})
+Returns the maximum value of the type @var{t}.
-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}:
+@item MIN(@var{t})
+Returns the minimum value of the type @var{t}.
-@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
+@item ODD(@var{i})
+Returns boolean TRUE if @var{i} is an odd number.
-@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
+@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.
-@example
-(@value{GDBP}) set var g=4
-@end example
+@item SIZE(@var{x})
+Returns the size of its argument. @var{x} can be a variable or a type.
-@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
+@item TRUNC(@var{r})
+Returns the integral part of @var{r}.
-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
+@item VAL(@var{t},@var{i})
+Returns the member of the type @var{t} whose ordinal value is @var{i}.
+@end table
-@example
-set @{int@}0x83040 = 4
-@end example
+@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
-@noindent
-stores the value 4 into that memory location.
+@cindex Modula-2 constants
+@node M2 Constants
+@subsubsection Constants
-@node Jumping
-@section Continuing at a different address
+@value{GDBN} allows you to express the constants of Modula-2 in the following
+ways:
-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:
+@itemize @bullet
-@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}.
+@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}.
-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
+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 jump *@var{address}
-Resume execution at the instruction at address @var{address}.
-@end table
+@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}.
-@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,
+@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.
-@example
-set $pc = 0x485
-@end example
+@item
+Enumerated constants consist of an enumerated identifier.
-@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}.
+@item
+Boolean constants consist of the identifiers @code{TRUE} and
+@code{FALSE}.
-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.
+@item
+Pointer constants consist of integral values only.
-@c @group
-@node Signaling
-@section Giving your program a signal
+@item
+Set constants are not yet supported.
+@end itemize
-@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.
+@node M2 Defaults
+@subsubsection Modula-2 defaults
+@cindex Modula-2 defaults
-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.
+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.
-@code{signal} does not repeat when you press @key{RET} a second time
-after executing the command.
-@end table
-@c @end group
+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.
-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 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:
-@node Returning
-@section Returning from a function
+@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.)
-@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
+@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.
-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}.
+@item
+The assignment operator (@code{:=}) returns the value of its right-hand
+argument.
-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.
+@item
+All built-in procedures both modify @emph{and} return their argument.
+@end itemize
-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 M2 Checks
+@subsubsection Modula-2 type and range checks
+@cindex Modula-2 checks
-@node Calling
-@section Calling program functions
+@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 calling functions
-@kindex call
-@table @code
-@item call @var{expr}
-Evaluate the expression @var{expr} without displaying @code{void}
-returned values.
-@end table
+@value{GDBN} considers two Modula-2 variables type equivalent if:
-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.
+@itemize @bullet
+@item
+They are of types that have been declared equivalent via a @code{TYPE
+@var{t1} = @var{t2}} statement
-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.
+@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 Patching
-@section Patching programs
+As long as type checking is enabled, any attempt to combine variables
+whose types are not equivalent is an error.
-@cindex patching binaries
-@cindex writing into executables
-@cindex writing into corefiles
+Range checking is done on all mathematical operations, assignment, array
+index bounds, and all built-in functions and procedures.
-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.
+@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
-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.
+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:
-@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.
+@smallexample
-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.
+@var{module} . @var{id}
+@var{scope} :: @var{id}
+@end smallexample
-@item show write
-@kindex show write
-Display whether executable files and core files are opened for writing
-as well as reading.
-@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.
-@node GDB Files
-@chapter @value{GDBN} Files
+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}.
-@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.
+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}.
-@menu
-* Files:: Commands to specify files
-* Symbol Errors:: Errors reading symbol files
-@end menu
+@node GDB/M2
+@subsubsection @value{GDBN} and Modula-2
-@node Files
-@section Commands to specify files
+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.
-@cindex symbol table
-@cindex core dump file
+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.
-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}}).
+@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.
-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.
+@c OBSOLETE @node Chill
+@c OBSOLETE @subsection Chill
+@c OBSOLETE
+@c OBSOLETE The extensions made to @value{GDBN} to support Chill only support output
+@c OBSOLETE from the @sc{gnu} Chill compiler. Other Chill compilers are not currently
+@c OBSOLETE supported, and attempting to debug executables produced by them is most
+@c OBSOLETE likely to give an error as @value{GDBN} reads in the executable's symbol
+@c OBSOLETE table.
+@c OBSOLETE
+@c OBSOLETE @c This used to say "... following Chill related topics ...", but since
+@c OBSOLETE @c menus are not shown in the printed manual, it would look awkward.
+@c OBSOLETE This section covers the Chill related topics and the features
+@c OBSOLETE of @value{GDBN} which support these topics.
+@c OBSOLETE
+@c OBSOLETE @menu
+@c OBSOLETE * How modes are displayed:: How modes are displayed
+@c OBSOLETE * Locations:: Locations and their accesses
+@c OBSOLETE * Values and their Operations:: Values and their Operations
+@c OBSOLETE * Chill type and range checks::
+@c OBSOLETE * Chill defaults::
+@c OBSOLETE @end menu
+@c OBSOLETE
+@c OBSOLETE @node How modes are displayed
+@c OBSOLETE @subsubsection How modes are displayed
+@c OBSOLETE
+@c OBSOLETE The Chill Datatype- (Mode) support of @value{GDBN} is directly related
+@c OBSOLETE with the functionality of the @sc{gnu} Chill compiler, and therefore deviates
+@c OBSOLETE slightly from the standard specification of the Chill language. The
+@c OBSOLETE provided modes are:
+@c OBSOLETE
+@c OBSOLETE @c FIXME: this @table's contents effectively disable @code by using @r
+@c OBSOLETE @c on every @item. So why does it need @code?
+@c OBSOLETE @table @code
+@c OBSOLETE @item @r{@emph{Discrete modes:}}
+@c OBSOLETE @itemize @bullet
+@c OBSOLETE @item
+@c OBSOLETE @emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT,
+@c OBSOLETE UINT, LONG, ULONG},
+@c OBSOLETE @item
+@c OBSOLETE @emph{Boolean Mode} which is predefined by @code{BOOL},
+@c OBSOLETE @item
+@c OBSOLETE @emph{Character Mode} which is predefined by @code{CHAR},
+@c OBSOLETE @item
+@c OBSOLETE @emph{Set Mode} which is displayed by the keyword @code{SET}.
+@c OBSOLETE @smallexample
+@c OBSOLETE (@value{GDBP}) ptype x
+@c OBSOLETE type = SET (karli = 10, susi = 20, fritzi = 100)
+@c OBSOLETE @end smallexample
+@c OBSOLETE If the type is an unnumbered set the set element values are omitted.
+@c OBSOLETE @item
+@c OBSOLETE @emph{Range Mode} which is displayed by
+@c OBSOLETE @smallexample
+@c OBSOLETE @code{type = <basemode>(<lower bound> : <upper bound>)}
+@c OBSOLETE @end smallexample
+@c OBSOLETE where @code{<lower bound>, <upper bound>} can be of any discrete literal
+@c OBSOLETE expression (e.g. set element names).
+@c OBSOLETE @end itemize
+@c OBSOLETE
+@c OBSOLETE @item @r{@emph{Powerset Mode:}}
+@c OBSOLETE A Powerset Mode is displayed by the keyword @code{POWERSET} followed by
+@c OBSOLETE the member mode of the powerset. The member mode can be any discrete mode.
+@c OBSOLETE @smallexample
+@c OBSOLETE (@value{GDBP}) ptype x
+@c OBSOLETE type = POWERSET SET (egon, hugo, otto)
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @item @r{@emph{Reference Modes:}}
+@c OBSOLETE @itemize @bullet
+@c OBSOLETE @item
+@c OBSOLETE @emph{Bound Reference Mode} which is displayed by the keyword @code{REF}
+@c OBSOLETE followed by the mode name to which the reference is bound.
+@c OBSOLETE @item
+@c OBSOLETE @emph{Free Reference Mode} which is displayed by the keyword @code{PTR}.
+@c OBSOLETE @end itemize
+@c OBSOLETE
+@c OBSOLETE @item @r{@emph{Procedure mode}}
+@c OBSOLETE The procedure mode is displayed by @code{type = PROC(<parameter list>)
+@c OBSOLETE <return mode> EXCEPTIONS (<exception list>)}. The @code{<parameter
+@c OBSOLETE list>} is a list of the parameter modes. @code{<return mode>} indicates
+@c OBSOLETE the mode of the result of the procedure if any. The exceptionlist lists
+@c OBSOLETE all possible exceptions which can be raised by the procedure.
+@c OBSOLETE
+@c OBSOLETE @ignore
+@c OBSOLETE @item @r{@emph{Instance mode}}
+@c OBSOLETE The instance mode is represented by a structure, which has a static
+@c OBSOLETE type, and is therefore not really of interest.
+@c OBSOLETE @end ignore
+@c OBSOLETE
+@c OBSOLETE @item @r{@emph{Synchronization Modes:}}
+@c OBSOLETE @itemize @bullet
+@c OBSOLETE @item
+@c OBSOLETE @emph{Event Mode} which is displayed by
+@c OBSOLETE @smallexample
+@c OBSOLETE @code{EVENT (<event length>)}
+@c OBSOLETE @end smallexample
+@c OBSOLETE where @code{(<event length>)} is optional.
+@c OBSOLETE @item
+@c OBSOLETE @emph{Buffer Mode} which is displayed by
+@c OBSOLETE @smallexample
+@c OBSOLETE @code{BUFFER (<buffer length>)<buffer element mode>}
+@c OBSOLETE @end smallexample
+@c OBSOLETE where @code{(<buffer length>)} is optional.
+@c OBSOLETE @end itemize
+@c OBSOLETE
+@c OBSOLETE @item @r{@emph{Timing Modes:}}
+@c OBSOLETE @itemize @bullet
+@c OBSOLETE @item
+@c OBSOLETE @emph{Duration Mode} which is predefined by @code{DURATION}
+@c OBSOLETE @item
+@c OBSOLETE @emph{Absolute Time Mode} which is predefined by @code{TIME}
+@c OBSOLETE @end itemize
+@c OBSOLETE
+@c OBSOLETE @item @r{@emph{Real Modes:}}
+@c OBSOLETE Real Modes are predefined with @code{REAL} and @code{LONG_REAL}.
+@c OBSOLETE
+@c OBSOLETE @item @r{@emph{String Modes:}}
+@c OBSOLETE @itemize @bullet
+@c OBSOLETE @item
+@c OBSOLETE @emph{Character String Mode} which is displayed by
+@c OBSOLETE @smallexample
+@c OBSOLETE @code{CHARS(<string length>)}
+@c OBSOLETE @end smallexample
+@c OBSOLETE followed by the keyword @code{VARYING} if the String Mode is a varying
+@c OBSOLETE mode
+@c OBSOLETE @item
+@c OBSOLETE @emph{Bit String Mode} which is displayed by
+@c OBSOLETE @smallexample
+@c OBSOLETE @code{BOOLS(<string
+@c OBSOLETE length>)}
+@c OBSOLETE @end smallexample
+@c OBSOLETE @end itemize
+@c OBSOLETE
+@c OBSOLETE @item @r{@emph{Array Mode:}}
+@c OBSOLETE The Array Mode is displayed by the keyword @code{ARRAY(<range>)}
+@c OBSOLETE followed by the element mode (which may in turn be an array mode).
+@c OBSOLETE @smallexample
+@c OBSOLETE (@value{GDBP}) ptype x
+@c OBSOLETE type = ARRAY (1:42)
+@c OBSOLETE ARRAY (1:20)
+@c OBSOLETE SET (karli = 10, susi = 20, fritzi = 100)
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @item @r{@emph{Structure Mode}}
+@c OBSOLETE The Structure mode is displayed by the keyword @code{STRUCT(<field
+@c OBSOLETE list>)}. The @code{<field list>} consists of names and modes of fields
+@c OBSOLETE of the structure. Variant structures have the keyword @code{CASE <field>
+@c OBSOLETE OF <variant fields> ESAC} in their field list. Since the current version
+@c OBSOLETE of the GNU Chill compiler doesn't implement tag processing (no runtime
+@c OBSOLETE checks of variant fields, and therefore no debugging info), the output
+@c OBSOLETE always displays all variant fields.
+@c OBSOLETE @smallexample
+@c OBSOLETE (@value{GDBP}) ptype str
+@c OBSOLETE type = STRUCT (
+@c OBSOLETE as x,
+@c OBSOLETE bs x,
+@c OBSOLETE CASE bs OF
+@c OBSOLETE (karli):
+@c OBSOLETE cs a
+@c OBSOLETE (ott):
+@c OBSOLETE ds x
+@c OBSOLETE ESAC
+@c OBSOLETE )
+@c OBSOLETE @end smallexample
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node Locations
+@c OBSOLETE @subsubsection Locations and their accesses
+@c OBSOLETE
+@c OBSOLETE A location in Chill is an object which can contain values.
+@c OBSOLETE
+@c OBSOLETE A value of a location is generally accessed by the (declared) name of
+@c OBSOLETE the location. The output conforms to the specification of values in
+@c OBSOLETE Chill programs. How values are specified
+@c OBSOLETE is the topic of the next section, @ref{Values and their Operations}.
+@c OBSOLETE
+@c OBSOLETE The pseudo-location @code{RESULT} (or @code{result}) can be used to
+@c OBSOLETE display or change the result of a currently-active procedure:
+@c OBSOLETE
+@c OBSOLETE @smallexample
+@c OBSOLETE set result := EXPR
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE This does the same as the Chill action @code{RESULT EXPR} (which
+@c OBSOLETE is not available in @value{GDBN}).
+@c OBSOLETE
+@c OBSOLETE Values of reference mode locations are printed by @code{PTR(<hex
+@c OBSOLETE value>)} in case of a free reference mode, and by @code{(REF <reference
+@c OBSOLETE mode>) (<hex-value>)} in case of a bound reference. @code{<hex value>}
+@c OBSOLETE represents the address where the reference points to. To access the
+@c OBSOLETE value of the location referenced by the pointer, use the dereference
+@c OBSOLETE operator @samp{->}.
+@c OBSOLETE
+@c OBSOLETE Values of procedure mode locations are displayed by
+@c OBSOLETE @smallexample
+@c OBSOLETE @code{@{ PROC
+@c OBSOLETE (<argument modes> ) <return mode> @} <address> <name of procedure
+@c OBSOLETE location>}
+@c OBSOLETE @end smallexample
+@c OBSOLETE @code{<argument modes>} is a list of modes according to the parameter
+@c OBSOLETE specification of the procedure and @code{<address>} shows the address of
+@c OBSOLETE the entry point.
+@c OBSOLETE
+@c OBSOLETE @ignore
+@c OBSOLETE Locations of instance modes are displayed just like a structure with two
+@c OBSOLETE fields specifying the @emph{process type} and the @emph{copy number} of
+@c OBSOLETE the investigated instance location@footnote{This comes from the current
+@c OBSOLETE implementation of instances. They are implemented as a structure (no
+@c OBSOLETE na). The output should be something like @code{[<name of the process>;
+@c OBSOLETE <instance number>]}.}. The field names are @code{__proc_type} and
+@c OBSOLETE @code{__proc_copy}.
+@c OBSOLETE
+@c OBSOLETE Locations of synchronization modes are displayed like a structure with
+@c OBSOLETE the field name @code{__event_data} in case of a event mode location, and
+@c OBSOLETE like a structure with the field @code{__buffer_data} in case of a buffer
+@c OBSOLETE mode location (refer to previous paragraph).
+@c OBSOLETE
+@c OBSOLETE Structure Mode locations are printed by @code{[.<field name>: <value>,
+@c OBSOLETE ...]}. The @code{<field name>} corresponds to the structure mode
+@c OBSOLETE definition and the layout of @code{<value>} varies depending of the mode
+@c OBSOLETE of the field. If the investigated structure mode location is of variant
+@c OBSOLETE structure mode, the variant parts of the structure are enclosed in curled
+@c OBSOLETE braces (@samp{@{@}}). Fields enclosed by @samp{@{,@}} are residing
+@c OBSOLETE on the same memory location and represent the current values of the
+@c OBSOLETE memory location in their specific modes. Since no tag processing is done
+@c OBSOLETE all variants are displayed. A variant field is printed by
+@c OBSOLETE @code{(<variant name>) = .<field name>: <value>}. (who implements the
+@c OBSOLETE stuff ???)
+@c OBSOLETE @smallexample
+@c OBSOLETE (@value{GDBP}) print str1 $4 = [.as: 0, .bs: karli, .<TAG>: { (karli) =
+@c OBSOLETE [.cs: []], (susi) = [.ds: susi]}]
+@c OBSOLETE @end smallexample
+@c OBSOLETE @end ignore
+@c OBSOLETE
+@c OBSOLETE Substructures of string mode-, array mode- or structure mode-values
+@c OBSOLETE (e.g. array slices, fields of structure locations) are accessed using
+@c OBSOLETE certain operations which are described in the next section, @ref{Values
+@c OBSOLETE and their Operations}.
+@c OBSOLETE
+@c OBSOLETE A location value may be interpreted as having a different mode using the
+@c OBSOLETE location conversion. This mode conversion is written as @code{<mode
+@c OBSOLETE name>(<location>)}. The user has to consider that the sizes of the modes
+@c OBSOLETE have to be equal otherwise an error occurs. Furthermore, no range
+@c OBSOLETE checking of the location against the destination mode is performed, and
+@c OBSOLETE therefore the result can be quite confusing.
+@c OBSOLETE
+@c OBSOLETE @smallexample
+@c OBSOLETE (@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @node Values and their Operations
+@c OBSOLETE @subsubsection Values and their Operations
+@c OBSOLETE
+@c OBSOLETE Values are used to alter locations, to investigate complex structures in
+@c OBSOLETE more detail or to filter relevant information out of a large amount of
+@c OBSOLETE data. There are several (mode dependent) operations defined which enable
+@c OBSOLETE such investigations. These operations are not only applicable to
+@c OBSOLETE constant values but also to locations, which can become quite useful
+@c OBSOLETE when debugging complex structures. During parsing the command line
+@c OBSOLETE (e.g. evaluating an expression) @value{GDBN} treats location names as
+@c OBSOLETE the values behind these locations.
+@c OBSOLETE
+@c OBSOLETE This section describes how values have to be specified and which
+@c OBSOLETE operations are legal to be used with such values.
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE @item Literal Values
+@c OBSOLETE Literal values are specified in the same manner as in @sc{gnu} Chill programs.
+@c OBSOLETE For detailed specification refer to the @sc{gnu} Chill implementation Manual
+@c OBSOLETE chapter 1.5.
+@c OBSOLETE @c FIXME: if the Chill Manual is a Texinfo documents, the above should
+@c OBSOLETE @c be converted to a @ref.
+@c OBSOLETE
+@c OBSOLETE @ignore
+@c OBSOLETE @itemize @bullet
+@c OBSOLETE @item
+@c OBSOLETE @emph{Integer Literals} are specified in the same manner as in Chill
+@c OBSOLETE programs (refer to the Chill Standard z200/88 chpt 5.2.4.2)
+@c OBSOLETE @item
+@c OBSOLETE @emph{Boolean Literals} are defined by @code{TRUE} and @code{FALSE}.
+@c OBSOLETE @item
+@c OBSOLETE @emph{Character Literals} are defined by @code{'<character>'}. (e.g.
+@c OBSOLETE @code{'M'})
+@c OBSOLETE @item
+@c OBSOLETE @emph{Set Literals} are defined by a name which was specified in a set
+@c OBSOLETE mode. The value delivered by a Set Literal is the set value. This is
+@c OBSOLETE comparable to an enumeration in C/C@t{++} language.
+@c OBSOLETE @item
+@c OBSOLETE @emph{Emptiness Literal} is predefined by @code{NULL}. The value of the
+@c OBSOLETE emptiness literal delivers either the empty reference value, the empty
+@c OBSOLETE procedure value or the empty instance value.
+@c OBSOLETE
+@c OBSOLETE @item
+@c OBSOLETE @emph{Character String Literals} are defined by a sequence of characters
+@c OBSOLETE enclosed in single- or double quotes. If a single- or double quote has
+@c OBSOLETE to be part of the string literal it has to be stuffed (specified twice).
+@c OBSOLETE @item
+@c OBSOLETE @emph{Bitstring Literals} are specified in the same manner as in Chill
+@c OBSOLETE programs (refer z200/88 chpt 5.2.4.8).
+@c OBSOLETE @item
+@c OBSOLETE @emph{Floating point literals} are specified in the same manner as in
+@c OBSOLETE (gnu-)Chill programs (refer @sc{gnu} Chill implementation Manual chapter 1.5).
+@c OBSOLETE @end itemize
+@c OBSOLETE @end ignore
+@c OBSOLETE
+@c OBSOLETE @item Tuple Values
+@c OBSOLETE A tuple is specified by @code{<mode name>[<tuple>]}, where @code{<mode
+@c OBSOLETE name>} can be omitted if the mode of the tuple is unambiguous. This
+@c OBSOLETE unambiguity is derived from the context of a evaluated expression.
+@c OBSOLETE @code{<tuple>} can be one of the following:
+@c OBSOLETE
+@c OBSOLETE @itemize @bullet
+@c OBSOLETE @item @emph{Powerset Tuple}
+@c OBSOLETE @item @emph{Array Tuple}
+@c OBSOLETE @item @emph{Structure Tuple}
+@c OBSOLETE Powerset tuples, array tuples and structure tuples are specified in the
+@c OBSOLETE same manner as in Chill programs refer to z200/88 chpt 5.2.5.
+@c OBSOLETE @end itemize
+@c OBSOLETE
+@c OBSOLETE @item String Element Value
+@c OBSOLETE A string element value is specified by
+@c OBSOLETE @smallexample
+@c OBSOLETE @code{<string value>(<index>)}
+@c OBSOLETE @end smallexample
+@c OBSOLETE where @code{<index>} is a integer expression. It delivers a character
+@c OBSOLETE value which is equivalent to the character indexed by @code{<index>} in
+@c OBSOLETE the string.
+@c OBSOLETE
+@c OBSOLETE @item String Slice Value
+@c OBSOLETE A string slice value is specified by @code{<string value>(<slice
+@c OBSOLETE spec>)}, where @code{<slice spec>} can be either a range of integer
+@c OBSOLETE expressions or specified by @code{<start expr> up <size>}.
+@c OBSOLETE @code{<size>} denotes the number of elements which the slice contains.
+@c OBSOLETE The delivered value is a string value, which is part of the specified
+@c OBSOLETE string.
+@c OBSOLETE
+@c OBSOLETE @item Array Element Values
+@c OBSOLETE An array element value is specified by @code{<array value>(<expr>)} and
+@c OBSOLETE delivers a array element value of the mode of the specified array.
+@c OBSOLETE
+@c OBSOLETE @item Array Slice Values
+@c OBSOLETE An array slice is specified by @code{<array value>(<slice spec>)}, where
+@c OBSOLETE @code{<slice spec>} can be either a range specified by expressions or by
+@c OBSOLETE @code{<start expr> up <size>}. @code{<size>} denotes the number of
+@c OBSOLETE arrayelements the slice contains. The delivered value is an array value
+@c OBSOLETE which is part of the specified array.
+@c OBSOLETE
+@c OBSOLETE @item Structure Field Values
+@c OBSOLETE A structure field value is derived by @code{<structure value>.<field
+@c OBSOLETE name>}, where @code{<field name>} indicates the name of a field specified
+@c OBSOLETE in the mode definition of the structure. The mode of the delivered value
+@c OBSOLETE corresponds to this mode definition in the structure definition.
+@c OBSOLETE
+@c OBSOLETE @item Procedure Call Value
+@c OBSOLETE The procedure call value is derived from the return value of the
+@c OBSOLETE procedure@footnote{If a procedure call is used for instance in an
+@c OBSOLETE expression, then this procedure is called with all its side
+@c OBSOLETE effects. This can lead to confusing results if used carelessly.}.
+@c OBSOLETE
+@c OBSOLETE Values of duration mode locations are represented by @code{ULONG} literals.
+@c OBSOLETE
+@c OBSOLETE Values of time mode locations appear as
+@c OBSOLETE @smallexample
+@c OBSOLETE @code{TIME(<secs>:<nsecs>)}
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE
+@c OBSOLETE @ignore
+@c OBSOLETE This is not implemented yet:
+@c OBSOLETE @item Built-in Value
+@c OBSOLETE @noindent
+@c OBSOLETE The following built in functions are provided:
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE @item @code{ADDR()}
+@c OBSOLETE @item @code{NUM()}
+@c OBSOLETE @item @code{PRED()}
+@c OBSOLETE @item @code{SUCC()}
+@c OBSOLETE @item @code{ABS()}
+@c OBSOLETE @item @code{CARD()}
+@c OBSOLETE @item @code{MAX()}
+@c OBSOLETE @item @code{MIN()}
+@c OBSOLETE @item @code{SIZE()}
+@c OBSOLETE @item @code{UPPER()}
+@c OBSOLETE @item @code{LOWER()}
+@c OBSOLETE @item @code{LENGTH()}
+@c OBSOLETE @item @code{SIN()}
+@c OBSOLETE @item @code{COS()}
+@c OBSOLETE @item @code{TAN()}
+@c OBSOLETE @item @code{ARCSIN()}
+@c OBSOLETE @item @code{ARCCOS()}
+@c OBSOLETE @item @code{ARCTAN()}
+@c OBSOLETE @item @code{EXP()}
+@c OBSOLETE @item @code{LN()}
+@c OBSOLETE @item @code{LOG()}
+@c OBSOLETE @item @code{SQRT()}
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE For a detailed description refer to the GNU Chill implementation manual
+@c OBSOLETE chapter 1.6.
+@c OBSOLETE @end ignore
+@c OBSOLETE
+@c OBSOLETE @item Zero-adic Operator Value
+@c OBSOLETE The zero-adic operator value is derived from the instance value for the
+@c OBSOLETE current active process.
+@c OBSOLETE
+@c OBSOLETE @item Expression Values
+@c OBSOLETE The value delivered by an expression is the result of the evaluation of
+@c OBSOLETE the specified expression. If there are error conditions (mode
+@c OBSOLETE incompatibility, etc.) the evaluation of expressions is aborted with a
+@c OBSOLETE corresponding error message. Expressions may be parenthesised which
+@c OBSOLETE causes the evaluation of this expression before any other expression
+@c OBSOLETE which uses the result of the parenthesised expression. The following
+@c OBSOLETE operators are supported by @value{GDBN}:
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE @item @code{OR, ORIF, XOR}
+@c OBSOLETE @itemx @code{AND, ANDIF}
+@c OBSOLETE @itemx @code{NOT}
+@c OBSOLETE Logical operators defined over operands of boolean mode.
+@c OBSOLETE
+@c OBSOLETE @item @code{=, /=}
+@c OBSOLETE Equality and inequality operators defined over all modes.
+@c OBSOLETE
+@c OBSOLETE @item @code{>, >=}
+@c OBSOLETE @itemx @code{<, <=}
+@c OBSOLETE Relational operators defined over predefined modes.
+@c OBSOLETE
+@c OBSOLETE @item @code{+, -}
+@c OBSOLETE @itemx @code{*, /, MOD, REM}
+@c OBSOLETE Arithmetic operators defined over predefined modes.
+@c OBSOLETE
+@c OBSOLETE @item @code{-}
+@c OBSOLETE Change sign operator.
+@c OBSOLETE
+@c OBSOLETE @item @code{//}
+@c OBSOLETE String concatenation operator.
+@c OBSOLETE
+@c OBSOLETE @item @code{()}
+@c OBSOLETE String repetition operator.
+@c OBSOLETE
+@c OBSOLETE @item @code{->}
+@c OBSOLETE Referenced location operator which can be used either to take the
+@c OBSOLETE address of a location (@code{->loc}), or to dereference a reference
+@c OBSOLETE location (@code{loc->}).
+@c OBSOLETE
+@c OBSOLETE @item @code{OR, XOR}
+@c OBSOLETE @itemx @code{AND}
+@c OBSOLETE @itemx @code{NOT}
+@c OBSOLETE Powerset and bitstring operators.
+@c OBSOLETE
+@c OBSOLETE @item @code{>, >=}
+@c OBSOLETE @itemx @code{<, <=}
+@c OBSOLETE Powerset inclusion operators.
+@c OBSOLETE
+@c OBSOLETE @item @code{IN}
+@c OBSOLETE Membership operator.
+@c OBSOLETE @end table
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node Chill type and range checks
+@c OBSOLETE @subsubsection Chill type and range checks
+@c OBSOLETE
+@c OBSOLETE @value{GDBN} considers two Chill variables mode equivalent if the sizes
+@c OBSOLETE of the two modes are equal. This rule applies recursively to more
+@c OBSOLETE complex datatypes which means that complex modes are treated
+@c OBSOLETE equivalent if all element modes (which also can be complex modes like
+@c OBSOLETE structures, arrays, etc.) have the same size.
+@c OBSOLETE
+@c OBSOLETE Range checking is done on all mathematical operations, assignment, array
+@c OBSOLETE index bounds and all built in procedures.
+@c OBSOLETE
+@c OBSOLETE Strong type checks are forced using the @value{GDBN} command @code{set
+@c OBSOLETE check strong}. This enforces strong type and range checks on all
+@c OBSOLETE operations where Chill constructs are used (expressions, built in
+@c OBSOLETE functions, etc.) in respect to the semantics as defined in the z.200
+@c OBSOLETE language specification.
+@c OBSOLETE
+@c OBSOLETE All checks can be disabled by the @value{GDBN} command @code{set check
+@c OBSOLETE off}.
+@c OBSOLETE
+@c OBSOLETE @ignore
+@c OBSOLETE @c Deviations from the Chill Standard Z200/88
+@c OBSOLETE see last paragraph ?
+@c OBSOLETE @end ignore
+@c OBSOLETE
+@c OBSOLETE @node Chill defaults
+@c OBSOLETE @subsubsection Chill defaults
+@c OBSOLETE
+@c OBSOLETE If type and range checking are set automatically by @value{GDBN}, they
+@c OBSOLETE both default to @code{on} whenever the working language changes to
+@c OBSOLETE Chill. This happens regardless of whether you or @value{GDBN}
+@c OBSOLETE selected the working language.
+@c OBSOLETE
+@c OBSOLETE If you allow @value{GDBN} to set the language automatically, then entering
+@c OBSOLETE code compiled from a file whose name ends with @file{.ch} sets the
+@c OBSOLETE working language to Chill. @xref{Automatically, ,Having @value{GDBN} set
+@c OBSOLETE the language automatically}, for further details.
-@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.
+@node Symbols
+@chapter Examining the Symbol Table
-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.
+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}).
-@item file
-@code{file} with no argument makes @value{GDBN} discard any information it
-has on both executable file and the symbol table.
+@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,
-@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.
+@smallexample
+p 'foo.c'::x
+@end smallexample
-@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.
+@noindent
+looks up the value of @code{x} in the scope of the file @file{foo.c}.
-@code{symbol-file} with no argument clears out @value{GDBN} information on your
-program's symbol table.
+@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.
-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}.
+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.
-@code{symbol-file} does not repeat if you press @key{RET} again after
-executing it once.
+@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:
-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.
+@smallexample
+(@value{GDBP}) info symbol 0x54320
+_initialize_vx + 396 in section .text
+@end smallexample
-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}.)
+@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.
-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 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}.
-@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.
+@item whatis
+Print the data type of @code{$}, the last value in the value history.
-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 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}}.
-You can use both options together, to make sure the auxiliary symbol
-file has all the symbol information for your program.
+@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.
-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.
+For example, for this variable declaration:
-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.
+@smallexample
+struct complex @{double real; double imag;@} v;
+@end smallexample
-@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.
+@noindent
+the two commands give this output:
-@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.
+@smallexample
+@group
+(@value{GDBP}) whatis v
+type = struct complex
+(@value{GDBP}) ptype v
+type = struct complex @{
+ double real;
+ double imag;
+@}
+@end group
+@end smallexample
-@code{core-file} with no argument specifies that no core file is
-to be used.
+@noindent
+As with @code{whatis}, using @code{ptype} without an argument refers to
+the type of @code{$}, the last value in the value history.
-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 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}.
-@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}
-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.
+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.
-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.
+@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:
-@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+@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
-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}.
+@noindent
+This command is especially useful for determining what data to collect
+during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
+collect}.
-@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 info source
+@item info source
+Show information about the current source file---that is, the source file for
+the function containing the current point of execution:
+@itemize @bullet
+@item
+the name of the source file, and the directory containing it,
+@item
+the directory it was compiled in,
+@item
+its length, in lines,
+@item
+which programming language it is written in,
+@item
+whether the executable includes debugging information for that file, and
+if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and
+@item
+whether the debugging information includes information about
+preprocessor macros.
+@end itemize
-@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 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.
-@end table
+@kindex info functions
+@item info functions
+Print the names and data types of all defined functions.
-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.
+@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.
-@cindex shared libraries
-@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
-libraries.
+@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).
-@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).
+@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}.
-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.
+@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
-@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
+@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 info sharedlibrary
-@kindex info share
-@item info share
-@itemx info sharedlibrary
-Print the names of the shared libraries which are currently loaded.
+@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 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
+@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,
+
+@smallexample
+print x=4
+@end smallexample
+
+@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}:
+
+@smallexample
+(@value{GDBP}) whatis width
+type = double
+(@value{GDBP}) p width
+$4 = 13
+(@value{GDBP}) set width=47
+Invalid syntax in expression.
+@end smallexample
+
+@noindent
+The invalid expression, of course, is @samp{=47}. In
+order to actually set the program's variable @code{width}, use
+
+@smallexample
+(@value{GDBP}) set var width=47
+@end smallexample
+
+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}:
+
+@smallexample
+@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 smallexample
+
+@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
+
+@smallexample
+(@value{GDBP}) set var g=4
+@end smallexample
+
+@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
+
+@smallexample
+set @{int@}0x83040 = 4
+@end smallexample
+
+@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,
+
+@smallexample
+set $pc = 0x485
+@end smallexample
+
+@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.
+
+@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
+@kindex set trust-readonly-sections
+@item set trust-readonly-sections on
+Tell @value{GDBN} that readonly sections in your object file
+really are read-only (i.e.@: that their contents will not change).
+In that case, @value{GDBN} can fetch values from these sections
+out of the object file, rather than from the target program.
+For some targets (notably embedded ones), this can be a significant
+enhancement to debugging performance.
+
+The default is off.
+
+@item set trust-readonly-sections off
+Tell @value{GDBN} not to trust readonly sections. This means that
+the contents of the section might change while the program is running,
+and must therefore be fetched from the target when needed.
+@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 HP-UX systems, @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.
+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
+
+Here are some common targets (available, or not, depending on the GDB
+configuration):
+
+@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 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.
+
+@kindex target sim
+@item target sim
+Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
+In general,
+@smallexample
+ target sim
+ load
+ run
+@end smallexample
+@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}.
+
+@end table
+
+Some configurations may include these targets as well:
+
+@table @code
+
+@kindex target nrom
+@item target nrom @var{dev}
+NetROM ROM emulator. This target only supports downloading.
+
+@end table
+
+Different targets are available on different configurations of @value{GDBN};
+your configuration may have more or fewer targets.
+
+Many remote targets require you to download the executable's code
+once you've successfully established a connection.
+
+@table @code
+
+@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.
+
+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{}}''
+
+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.
+
+@code{load} does not repeat if you press @key{RET} again after using it.
+@end table
+
+@node Byte Order
+@section Choosing target byte order
+
+@cindex choosing target byte order
+@cindex target byte order
+
+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.
+
+@table @code
+@kindex set endian big
+@item set endian big
+Instruct @value{GDBN} to assume the target is big-endian.
+
+@kindex set endian little
+@item set endian little
+Instruct @value{GDBN} to assume the target is little-endian.
+
+@kindex set endian auto
+@item set endian auto
+Instruct @value{GDBN} to use the byte order associated with the
+executable.
+
+@item show endian
+Display @value{GDBN}'s current idea of the target byte order.
+
+@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 Remote
+@section Remote debugging
+@cindex remote debugging
+
+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.
+
+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}.
+
+Other remote targets may be available in your
+configuration of @value{GDBN}; use @code{help target} to list them.
+
+@node KOD
+@section Kernel Object Display
+
+@cindex kernel object display
+@cindex kernel object
+@cindex KOD
+
+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.
+
+Use the @code{set os} command to set the operating system. This tells
+@value{GDBN} which kernel object display module to initialize:
+
+@smallexample
+(@value{GDBP}) set os cisco
+@end smallexample
+
+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:
+
+@smallexample
+(@value{GDBP}) info cisco
+List of Cisco Kernel Objects
+Object Description
+any Any and all objects
+@end smallexample
+
+Further subcommands can be used to query about particular objects known
+by the kernel.
+
+There is currently no way to determine whether a given operating system
+is supported other than to try it.
+
+
+@node Remote Debugging
+@chapter Debugging remote programs
+
+@menu
+* Server:: Using the gdbserver program
+* NetWare:: Using the gdbserve.nlm program
+* remote stub:: Implementing a remote stub
+@end menu
+
+@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.
+
+@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.
+
+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 usual
+syntax is:
+
+@smallexample
+target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
+@end smallexample
+
+@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}:
+
+@smallexample
+target> gdbserver /dev/com1 emacs foo.txt
+@end smallexample
+
+@code{gdbserver} waits passively for the host @value{GDBN} to communicate
+with it.
+
+To use a TCP connection instead of a serial line:
+
+@smallexample
+target> gdbserver host:2345 emacs foo.txt
+@end smallexample
+
+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.
+
+On some targets, @code{gdbserver} can also attach to running programs.
+This is accomplished via the @code{--attach} argument. The syntax is:
+
+@smallexample
+target> gdbserver @var{comm} --attach @var{pid}
+@end smallexample
+
+@var{pid} is the process ID of a currently running process. It isn't necessary
+to point @code{gdbserver} at a binary for the running process.
+
+@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:
+
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
+
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and
+
+@smallexample
+(@value{GDBP}) target remote the-target:2345
+@end smallexample
+
+@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
+
+@node NetWare
+@section Using the @code{gdbserve.nlm} program
+
+@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}.
+
+@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.
+
+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:
+
+@smallexample
+load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
+ [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
+@end smallexample
+
+@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}.
+
+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:
+
+@smallexample
+load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
+@end smallexample
+
+@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:
+
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
+
+@noindent
+communications with the server via serial line @file{/dev/ttyb}.
+@end table
+
+@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
+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
+A C subroutine library to support your program's
+subroutine calls, notably managing input and output.
+
+@item
+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
+
+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:
+
+@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
+
+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.
+
+@cindex remote serial stub list
+These working remote stubs are distributed with @value{GDBN}:
+
+@table @code
+
+@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.
+
+@end table
+
+The @file{README} file in the @value{GDBN} distribution may list other
+recently added stubs.
+
+@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 Stub Contents
+@subsection What the stub can do for you
+
+@cindex remote serial stub
+The debugging stub for your architecture supplies these three
+subroutines:
+
+@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.
+
+@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
+
+@node Bootstrapping
+@subsection What you must do for the stub
+
+@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.
+
+First of all you need to tell the stub how to communicate with the
+serial port.
+
+@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
+
+@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.
+
+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}).
+
+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
+You must also make sure this library routine is available:
+
+@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
+
+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 Debug Session
+@subsection Putting it all together
+
+@cindex remote serial debugging summary
+In summary, when your program is ready to debug, you must follow these
+steps.
+
+@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
+
+@item
+Insert these lines near the top of your program:
+
+@smallexample
+set_debug_traps();
+breakpoint();
+@end smallexample
+
+@item
+For the 680x0 stub only, you need to provide a variable called
+@code{exceptionHook}. Normally you just use:
+
+@smallexample
+void (*exceptionHook)() = 0;
+@end smallexample
+
+@noindent
+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.
+
+@item
+Compile and link together: your program, the @value{GDBN} debugging stub for
+your target architecture, and the supporting subroutines.
+
+@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.
+
+@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
+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.
+
+@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 or UDP 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}:
+
+@smallexample
+target remote /dev/ttyb
+@end smallexample
+
+@cindex TCP port, @code{target remote}
+To use a TCP connection, use an argument of the form
+@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}.
+For example, to connect to port 2828 on a
+terminal server named @code{manyfarms}:
+
+@smallexample
+target remote manyfarms:2828
+@end smallexample
+
+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:
-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.
+@smallexample
+target remote :1234
+@end smallexample
+@noindent
-To display or set the threshold, use the commands:
+Note that the colon is still required here.
-@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.
+@cindex UDP port, @code{target remote}
+To use a UDP connection, use an argument of the form
+@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828
+on a terminal server named @code{manyfarms}:
-@kindex show auto-solib-add
-@item show auto-solib-add
-Display the current autoloading size threshold, in megabytes.
-@end table
+@smallexample
+target remote udp:manyfarms:2828
+@end smallexample
-@node Symbol Errors
-@section Errors reading symbol files
+When using a UDP connection for remote debugging, you should keep in mind
+that the `U' stands for ``Unreliable''. UDP can silently drop packets on
+busy or unreliable networks, which will cause havoc with your debugging
+session.
-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}).
+@end enumerate
-The messages currently printed, and their meanings, include:
+Now you can use all the usual commands to examine and change data and to
+step and continue the remote program.
-@table @code
-@item inner block not inside outer block in @var{symbol}
+To resume the remote program and stop debugging it, use the @code{detach}
+command.
-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.
+@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:
-@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.
+@smallexample
+Interrupted while waiting for the program.
+Give up (and stop debugging it)? (y or n)
+@end smallexample
-@item block at @var{address} out of order
+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.
-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}.)
+@node Configurations
+@chapter Configuration-Specific Information
-@item bad block start address patched
+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.
-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.
+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.
-@value{GDBN} circumvents the problem by treating the symbol scope block as
-starting on the previous source line.
+@menu
+* Native::
+* Embedded OS::
+* Embedded Processors::
+* Architectures::
+@end menu
-@item bad string table offset in symbol @var{n}
+@node Native
+@section Native
-@cindex foo
-Symbol number @var{n} contains a pointer into the string table which is
-larger than the size of the string table.
+This section describes details specific to particular native
+configurations.
-@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.
+@menu
+* HP-UX:: HP-UX
+* SVR4 Process Information:: SVR4 process information
+* DJGPP Native:: Features specific to the DJGPP port
+* Cygwin Native:: Features specific to the Cygwin port
+@end menu
-@item unknown symbol type @code{0x@var{nn}}
+@node HP-UX
+@subsection HP-UX
-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.
+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.
-@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.
+@node SVR4 Process Information
+@subsection SVR4 process information
-@item stub type has NULL name
+@kindex /proc
+@cindex process image
-@value{GDBN} could not find the full definition for a struct or class.
+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 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
+@kindex info proc
+@item info proc
+Summarize available information about the process.
-@item info mismatch between compiler and debugger
+@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
+@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.
-@value{GDBN} could not parse a type specification output by the compiler.
+@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
-@node Targets
-@chapter Specifying a Debugging Target
+@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 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:
-@cindex debugging target
-@kindex target
+@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
-A @dfn{target} is the execution environment occupied by your program.
+@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
-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}).
+@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.
-@menu
-* Active Targets:: Active targets
-* Target Commands:: Commands for managing targets
-* Byte Order:: Choosing target byte order
-* Remote:: Remote debugging
-* KOD:: Kernel Object Display
+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:
+
+@smallexample
+@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
+
+@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.
+
+This command is supported only with some DPMI servers.
+@end table
+
+@node Cygwin Native
+@subsection Features for Debugging MS Windows PE executables
+@cindex MS Windows debugging
+@cindex native Cygwin debugging
+@cindex Cygwin-specific commands
+
+@value{GDBN} supports native debugging of MS Windows programs, and
+defines a few commands specific to the Cygwin port. This
+subsection describes those commands.
+
+@table @code
+@kindex info w32
+@item info w32
+This is a prefix of MS Windows specific commands which print
+information about the target system and important OS structures.
+
+@item info w32 selector
+This command displays information returned by
+the Win32 API @code{GetThreadSelectorEntry} function.
+It takes an optional argument that is evaluated to
+a long value to give the information about this given selector.
+Without argument, this command displays information
+about the the six segment registers.
+
+@kindex info dll
+@item info dll
+This is a Cygwin specific alias of info shared.
+
+@kindex dll-symbols
+@item dll-symbols
+This command loads symbols from a dll similarly to
+add-sym command but without the need to specify a base address.
+
+@kindex set new-console
+@item set new-console @var{mode}
+If @var{mode} is @code{on} the debuggee will
+be started in a new console on next start.
+If @var{mode} is @code{off}i, the debuggee will
+be started in the same console as the debugger.
+
+@kindex show new-console
+@item show new-console
+Displays whether a new console is used
+when the debuggee is started.
+
+@kindex set new-group
+@item set new-group @var{mode}
+This boolean value controls whether the debuggee should
+start a new group or stay in the same group as the debugger.
+This affects the way the Windows OS handles
+Ctrl-C.
+
+@kindex show new-group
+@item show new-group
+Displays current value of new-group boolean.
+
+@kindex set debugevents
+@item set debugevents
+This boolean value adds debug output concerning events seen by the debugger.
+
+@kindex set debugexec
+@item set debugexec
+This boolean value adds debug output concerning execute events
+seen by the debugger.
+
+@kindex set debugexceptions
+@item set debugexceptions
+This boolean value adds debug ouptut concerning exception events
+seen by the debugger.
+
+@kindex set debugmemory
+@item set debugmemory
+This boolean value adds debug ouptut concerning memory events
+seen by the debugger.
+
+@kindex set shell
+@item set shell
+This boolean values specifies whether the debuggee is called
+via a shell or directly (default value is on).
+
+@kindex show shell
+@item show shell
+Displays if the debuggee will be started with a shell.
+
+@end table
+
+@node Embedded OS
+@section Embedded Operating Systems
+
+This section describes configurations involving the debugging of
+embedded operating systems that are available for several different
+architectures.
+@menu
+* VxWorks:: Using @value{GDBN} with VxWorks
@end menu
-@node Active Targets
-@section Active targets
+@value{GDBN} includes the ability to debug programs running on
+various real-time operating systems.
-@cindex stacking targets
-@cindex active targets
-@cindex multiple targets
+@node VxWorks
+@subsection Using @value{GDBN} with VxWorks
-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.
+@cindex VxWorks
-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.)
+@table @code
-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.
+@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.
-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}).
+@end table
-@node Target Commands
-@section Commands for managing targets
+On VxWorks, @code{load} links @var{filename} dynamically on the
+current target system as well as adding its symbols in @value{GDBN}.
+
+@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.)
@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.
+@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
-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 following information on connecting to VxWorks was current when
+this manual was produced; newer releases of VxWorks may use revised
+procedures.
-The @code{target} command does not repeat if you press @key{RET} again
-after executing the command.
+@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}.
-@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}).
+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).
-@item help target @var{name}
-Describe a particular target, including any parameters necessary to
-select it.
+@value{GDBN} comes up showing the prompt:
-@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.
+@smallexample
+(vxgdb)
+@end smallexample
-@quotation
-@emph{Warning:} To specify a file format with @code{set gnutarget},
-you must know the actual BFD name.
-@end quotation
+@menu
+* VxWorks Connection:: Connecting to VxWorks
+* VxWorks Download:: VxWorks download
+* VxWorks Attach:: Running tasks
+@end menu
-@noindent
-@xref{Files, , Commands to specify files}.
+@node VxWorks Connection
+@subsubsection Connecting to VxWorks
-@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
+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:
-Here are some common targets (available, or not, depending on the GDB
-configuration):
+@smallexample
+(vxgdb) target vxworks tt
+@end smallexample
-@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}}.
+@need 750
+@value{GDBN} displays messages like these:
-@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}}.
+@smallexample
+Attaching remote machine across net...
+Connected to tt.
+@end smallexample
-@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.
+@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:
-@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}.
+@smallexample
+prog.o: No such file or directory.
+@end smallexample
-@end table
+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.
-Some configurations may include these targets as well:
+@node VxWorks Download
+@subsubsection VxWorks download
-@table @code
+@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:
-@kindex target nrom
-@item target nrom @var{dev}
-NetROM ROM emulator. This target only supports downloading.
+@smallexample
+-> cd "@var{vxpath}/vw/demo/rdb"
+@end smallexample
-@end table
+@noindent
+Then, in @value{GDBN}, type:
-Different targets are available on different configurations of @value{GDBN};
-your configuration may have more or fewer targets.
+@smallexample
+(vxgdb) cd @var{hostpath}/vw/demo/rdb
+(vxgdb) load prog.o
+@end smallexample
-Many remote targets require you to download the executable's code
-once you've successfully established a connection.
+@value{GDBN} displays a response similar to this:
-@table @code
+@smallexample
+Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
+@end smallexample
-@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.
+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.)
-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{}}''
+@node VxWorks Attach
+@subsubsection Running tasks
-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.
+@cindex running VxWorks tasks
+You can also attach to an existing task using the @code{attach} command as
+follows:
-@code{load} does not repeat if you press @key{RET} again after using it.
-@end table
+@smallexample
+(vxgdb) attach @var{task}
+@end smallexample
-@node Byte Order
-@section Choosing target byte order
+@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.
-@cindex choosing target byte order
-@cindex target byte order
+@node Embedded Processors
+@section Embedded Processors
-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.
+This section goes into details specific to particular embedded
+configurations.
-@table @code
-@kindex set endian big
-@item set endian big
-Instruct @value{GDBN} to assume the target is big-endian.
-@kindex set endian little
-@item set endian little
-Instruct @value{GDBN} to assume the target is little-endian.
+@menu
+* ARM:: ARM
+* H8/300:: Hitachi H8/300
+* H8/500:: Hitachi H8/500
+* i960:: Intel i960
+* M32R/D:: Mitsubishi M32R/D
+* M68K:: Motorola M68K
+@c OBSOLETE * 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 ARM
+@subsection ARM
-@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 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.
+
+@kindex target rdp
+@item target rdp @var{dev}
+ARM Demon monitor.
@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 H8/300
+@subsection Hitachi H8/300
-@node Remote
-@section Remote debugging
-@cindex remote debugging
+@table @code
-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.
+@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.
-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}.
+@kindex target e7000@r{, with H8/300}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi H8 and SH.
-Other remote targets may be available in your
-configuration of @value{GDBN}; use @code{help target} to list them.
+@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.
-@menu
-* Remote Serial:: @value{GDBN} remote serial protocol
-@end menu
+@end table
-@node Remote Serial
-@subsection The @value{GDBN} remote serial protocol
+@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).
-@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:
+@value{GDBN} needs to know these things to talk to your
+Hitachi SH, H8/300, or H8/500:
@enumerate
@item
-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.
+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.)
@item
-A C subroutine library to support your program's
-subroutine calls, notably managing input and output.
+what serial device connects your host to your Hitachi board (the first
+serial device available on your host is the default).
@item
-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.
+what speed to use over the serial device.
@end enumerate
-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:
-
-@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
-
-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.
+@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
-@cindex remote serial stub list
-These working remote stubs are distributed with @value{GDBN}:
+@node Hitachi Boards
+@subsubsection Connecting to Hitachi boards
-@table @code
+@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}.
-@item i386-stub.c
-@cindex @file{i386-stub.c}
-@cindex Intel
-@cindex i386
-For Intel 386 and compatible architectures.
+@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).
-@item m68k-stub.c
-@cindex @file{m68k-stub.c}
-@cindex Motorola 680x0
-@cindex m680x0
-For Motorola 680x0 architectures.
+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.
-@item sh-stub.c
-@cindex @file{sh-stub.c}
-@cindex Hitachi
-@cindex SH
-For Hitachi SH architectures.
+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.
-@item sparc-stub.c
-@cindex @file{sparc-stub.c}
-@cindex Sparc
-For @sc{sparc} architectures.
+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}.
-@item sparcl-stub.c
-@cindex @file{sparcl-stub.c}
-@cindex Fujitsu
-@cindex SparcLite
-For Fujitsu @sc{sparclite} architectures.
+@smallexample
+C:\H8300\TEST> asynctsr 2
+C:\H8300\TEST> mode com2:9600,n,8,1,p
-@end table
+Resident portion of MODE loaded
-The @file{README} file in the @value{GDBN} distribution may list other
-recently added stubs.
+COM2: 9600, n, 8, 1, p
-@menu
-* Stub Contents:: What the stub can do for you
-* Bootstrapping:: What you must do for the stub
-* Debug Session:: Putting it all together
-* Protocol:: Definition of the communication protocol
-* Server:: Using the `gdbserver' program
-* NetWare:: Using the `gdbserve.nlm' program
-@end menu
+@end smallexample
-@node Stub Contents
-@subsubsection What the stub can do for you
+@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
-@cindex remote serial stub
-The debugging stub for your architecture supplies these three
-subroutines:
+@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}.)
-@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.
+@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
-@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.
+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.
-@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.
+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!
-@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.
+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
-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
+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
-@node Bootstrapping
-@subsubsection What you must do for the stub
+In either case, @value{GDBN} sees the effect of a @sc{reset} on the
+development board as a ``normal exit'' of your program.
-@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.
+@node Hitachi ICE
+@subsubsection Using the E7000 in-circuit emulator
-First of all you need to tell the stub how to communicate with the
-serial port.
+@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:
@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 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 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.
+@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
-@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.
-
-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}).
+@node Hitachi Special
+@subsubsection Special @value{GDBN} commands for Hitachi micros
-Other routines you need to supply are:
+Some @value{GDBN} commands are available only for the H8/300:
@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.
+@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.
-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
-You must also make sure this library routine is available:
+@node H8/500
+@subsection H8/500
@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
-
-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 Debug Session
-@subsubsection Putting it all together
+@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}.
-@cindex remote serial debugging summary
-In summary, when your program is ready to debug, you must follow these
-steps.
+@end table
-@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 i960
+@subsection Intel i960
-@item
-Insert these lines near the top of your program:
+@table @code
-@example
-set_debug_traps();
-breakpoint();
-@end example
+@kindex target mon960
+@item target mon960 @var{dev}
+MON960 monitor for Intel i960.
-@item
-For the 680x0 stub only, you need to provide a variable called
-@code{exceptionHook}. Normally you just use:
+@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}.
-@example
-void (*exceptionHook)() = 0;
-@end example
+@end table
-@noindent
-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.
+@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:
+@itemize @bullet
@item
-Compile and link together: your program, the @value{GDBN} debugging stub for
-your target architecture, and the supporting subroutines.
+Through command line options specifying serial port, version of the
+Nindy protocol, and communications speed;
@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.
+By responding to a prompt on startup;
@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.
+By using the @code{target} command at any point during your @value{GDBN}
+session. @xref{Target Commands, ,Commands for managing targets}.
-@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.
+@end itemize
-@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}:
+@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}.
-@example
-target remote /dev/ttyb
-@end example
+@menu
+* Nindy Startup:: Startup with Nindy
+* Nindy Options:: Options for Nindy
+* Nindy Reset:: Nindy reset command
+@end menu
-@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}:
+@node Nindy Startup
+@subsubsection Startup with Nindy
-@example
-target remote manyfarms:2828
-@end example
-@end enumerate
+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:
-Now you can use all the usual commands to examine and change data and to
-step and continue the remote program.
+@smallexample
+Attach /dev/ttyNN -- specify NN, or "quit" to quit:
+@end smallexample
-To resume the remote program and stop debugging it, use the @code{detach}
-command.
+@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
+@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}).
-@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:
+@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.
-@example
-Interrupted while waiting for the program.
-Give up (and stop debugging it)? (y or n)
-@end example
+@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
-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.
+@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.
-@node Protocol
-@subsubsection Communication protocol
+@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
-@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.)
+The standard @samp{-b} option controls the line speed used on the serial
+port.
-However, 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}.
+@c @group
+@node Nindy Reset
+@subsubsection Nindy reset command
-In the examples below, @samp{<-} and @samp{->} are used to indicate
-transmitted and received data respectfully.
+@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
-@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}:
+@node M32R/D
+@subsection Mitsubishi M32R/D
-@example
-@code{$}@var{packet-data}@code{#}@var{checksum}
-@end example
-@noindent
+@table @code
-@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).
+@kindex target m32r
+@item target m32r @var{dev}
+Mitsubishi M32R/D ROM monitor.
-Implementors should note that prior to @value{GDBN} 5.0 the protocol
-specification also included an optional two-digit @var{sequence-id}:
+@end table
-@example
-@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
-@end example
+@node M68K
+@subsection M68k
-@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}.
+The Motorola m68k configuration includes ColdFire support, and
+target command for the following ROM monitors.
-@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):
+@table @code
-@example
-<- @code{$}@var{packet-data}@code{#}@var{checksum}
--> @code{+}
-@end example
-@noindent
+@kindex target abug
+@item target abug @var{dev}
+ABug ROM monitor for M68K.
-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).
+@kindex target cpu32bug
+@item target cpu32bug @var{dev}
+CPU32BUG monitor, running on a CPU32 (M68K) board.
-@var{packet-data} consists of a sequence of characters with the
-exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
-exceptions).
+@kindex target dbug
+@item target dbug @var{dev}
+dBUG ROM monitor for Motorola ColdFire.
-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.
+@kindex target est
+@item target est @var{dev}
+EST-300 ICE monitor, running on a CPU32 (M68K) board.
-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}).
+@kindex target rom68k
+@item target rom68k @var{dev}
+ROM 68K monitor, running on an M68K IDP board.
-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.
+@end table
-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.
+If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
+instead have only a single special target command:
-So:
-@example
-"@code{0* }"
-@end example
-@noindent
-means the same as "0000".
+@table @code
-The error response returned for some packets includes a two character
-error number. That number is not well defined.
+@kindex target es1800
+@item target es1800 @var{dev}
+ES-1800 emulator for M68K.
-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.
+@end table
-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.
+[context?]
-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 ops
-@tab @code{!}
-@tab
-Use the extended remote protocol. Sticky---only needs to be set once.
-The extended remote protocol supports the @samp{R} packet.
-@item
-@tab reply @samp{}
-@tab
-Stubs that support the extended remote protocol return @samp{} which,
-unfortunately, is identical to the response returned by stubs that do not
-support protocol extensions.
-
-@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.}
+@table @code
-@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
+@kindex target rombug
+@item target rombug @var{dev}
+ROMBUG ROM monitor for OS/9000.
-@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
+@end table
-@item toggle debug @strong{(deprecated)}
-@tab @code{d}
-@tab
-toggle debug flag.
+@c OBSOLETE @node M88K
+@c OBSOLETE @subsection M88K
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE
+@c OBSOLETE @kindex target bug
+@c OBSOLETE @item target bug @var{dev}
+@c OBSOLETE BUG monitor, running on a MVME187 (m88k) board.
+@c OBSOLETE
+@c OBSOLETE @end table
-@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.
+@node MIPS Embedded
+@subsection MIPS Embedded
-@item reserved
-@tab @code{e}
-@tab Reserved for future use
+@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}.
-@item reserved
-@tab @code{E}
-@tab Reserved for future use
+@need 1000
+Use these @value{GDBN} commands to specify the connection to your target board:
-@item reserved
-@tab @code{f}
-@tab Reserved for future use
+@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.
-@item reserved
-@tab @code{F}
-@tab Reserved for future use
+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 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.
+@smallexample
+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 smallexample
-@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 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}}.
-@item reserved
-@tab @code{h}
-@tab Reserved for future use
+@item target pmon @var{port}
+@kindex target pmon @var{port}
+PMON ROM monitor.
-@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
+@item target ddb @var{port}
+@kindex target ddb @var{port}
+NEC's DDB variant of PMON for Vr4300.
-@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 target lsi @var{port}
+@kindex target lsi @var{port}
+LSI variant of PMON.
-@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.
+@kindex target r3900
+@item target r3900 @var{dev}
+Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
-@item signal then cycle step @strong{(reserved)}
-@tab @code{I}
-@tab
-See @samp{i} and @samp{S} for likely syntax and semantics.
+@kindex target array
+@item target array @var{dev}
+Array Tech LSI33K RAID controller board.
-@item reserved
-@tab @code{j}
-@tab Reserved for future use
+@end table
-@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?)}.
+@noindent
+@value{GDBN} also supports these special commands for MIPS targets:
-@item reserved
-@tab @code{l}
-@tab Reserved for future use
+@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 reserved
-@tab @code{L}
-@tab Reserved for future use
+@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}.
-@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
+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.
-@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).
+As usual, you can inquire about the @code{mipsfpu} variable with
+@samp{show mipsfpu}.
-@item reserved
-@tab @code{n}
-@tab Reserved for future use
+@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 reserved
-@tab @code{N}
-@tab Reserved for future use
+@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}.)
-@item reserved
-@tab @code{o}
-@tab Reserved for future use
+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
-@item reserved
-@tab @code{O}
-@tab Reserved for future use
+@node PowerPC
+@subsection PowerPC
-@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.
+@table @code
-@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
+@kindex target dink32
+@item target dink32 @var{dev}
+DINK32 ROM monitor.
-@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}.
+@kindex target ppcbug
+@item target ppcbug @var{dev}
+@kindex target ppcbug1
+@item target ppcbug1 @var{dev}
+PPCBUG ROM monitor for PowerPC.
-@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.
+@kindex target sds
+@item target sds @var{dev}
+SDS monitor, running on a PowerPC board (such as Motorola's ADS).
-@item reset @strong{(deprecated)}
-@tab @code{r}
-@tab
-Reset the entire system.
+@end table
-@item remote restart
-@tab @code{R}@var{XX}
-@tab
-Restart the remote server. @var{XX} while needed has no clear
-definition. FIXME: @emph{An example interaction explaining how this
-packet is used in extended-remote mode is needed}.
+@node PA
+@subsection HP PA Embedded
-@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
+@table @code
-@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
+@kindex target op50n
+@item target op50n @var{dev}
+OP50N monitor, running on an OKI HPPA board.
-@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.
+@kindex target w89k
+@item target w89k @var{dev}
+W89K monitor, running on a Winbond HPPA board.
-@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
+@end table
-@item reserved
-@tab @code{u}
-@tab Reserved for future use
+@node SH
+@subsection Hitachi SH
-@item reserved
-@tab @code{U}
-@tab Reserved for future use
+@table @code
-@item reserved
-@tab @code{v}
-@tab Reserved for future use
+@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.
-@item reserved
-@tab @code{V}
-@tab Reserved for future use
+@kindex target e7000@r{, with Hitachi SH}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi SH.
-@item reserved
-@tab @code{w}
-@tab Reserved for future use
+@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.
-@item reserved
-@tab @code{W}
-@tab Reserved for future use
+@end table
-@item reserved
-@tab @code{x}
-@tab Reserved for future use
+@node Sparclet
+@subsection Tsqware Sparclet
-@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
+@cindex Sparclet
-@item reserved
-@tab @code{y}
-@tab Reserved for future use
+@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.
-@item reserved
-@tab @code{Y}
-@tab Reserved for future use
+@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
-@item remove break or watchpoint @strong{(draft)}
-@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
-@tab
-See @samp{Z}.
+@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:
-@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.
+@smallexample
+sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
+@end smallexample
-@item reserved
-@tab <other>
-@tab Reserved for future use
+You can use @code{objdump} to verify that the addresses are what you intended:
-@end multitable
+@smallexample
+sparclet-aout-objdump --headers --syms prog
+@end smallexample
-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.
+@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).
-@multitable @columnfractions .4 .6
+@value{GDBN} comes up showing the prompt:
-@item @code{S}@var{AA}
-@tab @var{AA} is the signal number
+@smallexample
+(gdbslet)
+@end smallexample
-@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.
+@menu
+* Sparclet File:: Setting the file to debug
+* Sparclet Connection:: Connecting to Sparclet
+* Sparclet Download:: Sparclet download
+* Sparclet Execution:: Running and debugging
+@end menu
-@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.
+@node Sparclet File
+@subsubsection Setting file to debug
-@item @code{X}@var{AA}
-@tab
-The process terminated with signal @var{AA}.
+The @value{GDBN} command @code{file} lets you choose with program to debug.
-@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.}
+@smallexample
+(gdbslet) file prog
+@end smallexample
-@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.
+@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:
-@end multitable
+@smallexample
+prog: No such file or directory.
+@end smallexample
-The following set and query packets have already been defined.
+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.
-@multitable @columnfractions .2 .2 .6
+@node Sparclet Connection
+@subsubsection Connecting to Sparclet
-@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.
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
+To connect to a target on serial port ``@code{ttya}'', type:
-@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'}).
+@smallexample
+(gdbslet) target sparclet /dev/ttya
+Remote target sparclet connected to /dev/ttya
+main () at ../prog.c:3
+@end smallexample
-@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.
+@need 750
+@value{GDBN} displays messages like these:
-@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()}.
+@smallexample
+Connected to ttya.
+@end smallexample
-@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.
+@node Sparclet Download
+@subsubsection Sparclet download
-@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}
+@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:
-@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()}.
+@smallexample
+(gdbslet) load prog 0x12010000
+Loading section .text, size 0xdb0 vma 0x12010000
+@end smallexample
-@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.
+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.
-@item
-@tab reply @samp{}
-@tab
-When @samp{q}@samp{Rcmd} is not recognized.
+@node Sparclet Execution
+@subsubsection Running and debugging
-@end multitable
+@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.
-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.
+@smallexample
+(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 smallexample
-@multitable @columnfractions .5 .5
+@node Sparclite
+@subsection Fujitsu Sparclite
-@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.
+@table @code
-@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}.
+@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
+remote protocol.
-@end multitable
+@end table
-Example sequence of a target being re-started. Notice how the restart
-does not get any direct output:
+@node ST2000
+@subsection Tandem ST2000
-@example
-<- @code{R00}
--> @code{+}
-@emph{target restarts}
-<- @code{?}
--> @code{+}
--> @code{T001:1234123412341234}
-<- @code{+}
-@end example
+@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
+STDBUG protocol.
-Example sequence of a target being stepped by a single instruction:
+To connect your ST2000 to the host system, see the manufacturer's
+manual. Once the ST2000 is physically attached, you can run:
-@example
-<- @code{G1445...}
--> @code{+}
-<- @code{s}
--> @code{+}
-@emph{time passes}
--> @code{T001:1234123412341234}
-<- @code{+}
-<- @code{g}
--> @code{+}
--> @code{1455...}
-<- @code{+}
-@end example
+@smallexample
+target st2000 @var{dev} @var{speed}
+@end smallexample
-@node Server
-@subsubsection Using the @code{gdbserver} program
+@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}}.
-@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.
+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.
-@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.
+@cindex ST2000 auxiliary commands
+These auxiliary @value{GDBN} commands are available to help you with the ST2000
+environment:
-@value{GDBN} and @code{gdbserver} communicate via either a serial line
-or a TCP connection, using the standard @value{GDBN} remote serial
-protocol.
+@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.
-@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 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
-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:
+@node Z8000
+@subsection Zilog Z8000
-@smallexample
-target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
-@end smallexample
+@cindex Z8000
+@cindex simulator, Z8000
+@cindex Zilog Z8000 simulator
-@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}:
+When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
+a Z8000 simulator.
-@smallexample
-target> gdbserver /dev/com1 emacs foo.txt
-@end smallexample
+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.
-@code{gdbserver} waits passively for the host @value{GDBN} to communicate
-with it.
+@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
-To use a TCP connection instead of a serial line:
+@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.
-@smallexample
-target> gdbserver host:2345 emacs foo.txt
-@end smallexample
+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:
-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.
+@table @code
-@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 cycles
+Counts clock-ticks in the simulator.
+
+@item insts
+Counts instructions run in the simulator.
+
+@item time
+Execution time in 60ths of a second.
-@smallexample
-(@value{GDBP}) target remote /dev/ttyb
-@end smallexample
+@end table
-@noindent
-communicates with the server via serial line @file{/dev/ttyb}, and
+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.
-@smallexample
-(@value{GDBP}) target remote the-target:2345
-@end smallexample
+@node Architectures
+@section Architectures
-@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
+This section describes characteristics of architectures that affect
+all uses of @value{GDBN} with the architecture, both native and cross.
-@node NetWare
-@subsubsection Using the @code{gdbserve.nlm} program
+@menu
+* A29K::
+* Alpha::
+* MIPS::
+@end menu
-@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}.
+@node A29K
+@subsection A29K
-@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
-using the standard @value{GDBN} remote serial protocol.
+@table @code
-@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.
+@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.
-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:
+@kindex show rstack_high_address
+@item show rstack_high_address
+Display the current limit of the register stack, on AMD 29000 family
+processors.
-@smallexample
-load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
- [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
-@end smallexample
+@end table
-@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}.
+@node Alpha
+@subsection Alpha
-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:
+See the following section.
-@smallexample
-load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
-@end smallexample
+@node MIPS
+@subsection MIPS
-@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:
+@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.
-@smallexample
-(@value{GDBP}) target remote /dev/ttyb
-@end smallexample
+@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:
-@noindent
-communications with the server via serial line @file{/dev/ttyb}.
+@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
-@node KOD
-@section Kernel Object Display
+@noindent
+These commands are available @emph{only} when @value{GDBN} is configured
+for debugging programs on Alpha or MIPS processors.
-@cindex kernel object display
-@cindex kernel object
-@cindex KOD
-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.
+@node Controlling GDB
+@chapter Controlling @value{GDBN}
-Use the @code{set os} command to set the operating system. This tells
-@value{GDBN} which kernel object display module to initialize:
+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.
-@example
-(@value{GDBP}) set os cisco
-@end example
+@menu
+* Prompt:: Prompt
+* Editing:: Command editing
+* History:: Command history
+* Screen Size:: Screen size
+* Numbers:: Numbers
+* Messages/Warnings:: Optional warnings and messages
+* Debugging Output:: Optional messages about internal happenings
+@end menu
-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:
+@node Prompt
+@section Prompt
-@example
-(@value{GDBP}) info cisco
-List of Cisco Kernel Objects
-Object Description
-any Any and all objects
-@end example
+@cindex prompt
-Further subcommands can be used to query about particular objects known
-by the kernel.
+@value{GDBN} indicates its readiness to read a command by printing a string
+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
+which one you are talking to.
-There is currently no way to determine whether a given operating system
-is supported other than to try it.
+@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.
+@table @code
+@kindex set prompt
+@item set prompt @var{newprompt}
+Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
-@node Configurations
-@chapter Configuration-Specific Information
+@kindex show prompt
+@item show prompt
+Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
+@end table
-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.
+@node Editing
+@section Command editing
+@cindex readline
+@cindex command line editing
-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.
+@value{GDBN} reads its input commands via the @dfn{readline} interface. This
+@sc{gnu} library provides consistent behavior for programs which provide a
+command line interface to the user. Advantages are @sc{gnu} Emacs-style
+or @dfn{vi}-style inline editing of commands, @code{csh}-like history
+substitution, and a storage and recall of command history across
+debugging sessions.
-@menu
-* Native::
-* Embedded OS::
-* Embedded Processors::
-* Architectures::
-@end menu
+You may control the behavior of command line editing in @value{GDBN} with the
+command @code{set}.
-@node Native
-@section Native
+@table @code
+@kindex set editing
+@cindex editing
+@item set editing
+@itemx set editing on
+Enable command line editing (enabled by default).
-This section describes details specific to particular native
-configurations.
+@item set editing off
+Disable command line editing.
-@menu
-* HP-UX:: HP-UX
-* SVR4 Process Information:: SVR4 process information
-@end menu
+@kindex show editing
+@item show editing
+Show whether command line editing is enabled.
+@end table
-@node HP-UX
-@subsection HP-UX
+@node History
+@section Command history
+
+@value{GDBN} can keep track of the commands you type during your
+debugging sessions, so that you can be certain of precisely what
+happened. Use these commands to manage the @value{GDBN} command
+history facility.
+
+@table @code
+@cindex history substitution
+@cindex history file
+@kindex set history filename
+@kindex GDBHISTFILE
+@item set history filename @var{fname}
+Set the name of the @value{GDBN} command history file to @var{fname}.
+This is the file where @value{GDBN} reads an initial command history
+list, and where it writes the command history from this session when it
+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} (@file{./_gdb_history} on MS-DOS) if this variable
+is not set.
-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.
+@cindex history save
+@kindex set history save
+@item set history save
+@itemx set history save on
+Record command history in a file, whose name may be specified with the
+@code{set history filename} command. By default, this option is disabled.
-@node SVR4 Process Information
-@subsection SVR4 process information
+@item set history save off
+Stop recording command history in a file.
-@kindex /proc
-@cindex process image
+@cindex history size
+@kindex set history size
+@item set history size @var{size}
+Set the number of commands which @value{GDBN} keeps in its history list.
+This defaults to the value of the environment variable
+@code{HISTSIZE}, or to 256 if this variable is not set.
+@end table
-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.
+@cindex history expansion
+History expansion assigns special meaning to the character @kbd{!}.
+@ifset have-readline-appendices
+@xref{Event Designators}.
+@end ifset
-@table @code
-@kindex info proc
-@item info proc
-Summarize available information about the process.
+Since @kbd{!} is also the logical not operator in C, history expansion
+is off by default. If you decide to enable history expansion with the
+@code{set history expansion on} command, you may sometimes need to
+follow @kbd{!} (when it is used as logical not, in an expression) with
+a space or a tab to prevent it from being expanded. The readline
+history facilities do not attempt substitution on the strings
+@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
-@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.
+The commands to control history expansion are:
-@kindex info proc times
-@item info proc times
-Starting time, user CPU time, and system CPU time for your program and
-its children.
+@table @code
+@kindex set history expansion
+@item set history expansion on
+@itemx set history expansion
+Enable history expansion. History expansion is off by default.
-@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.
+@item set history expansion off
+Disable history expansion.
-@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.
+The readline code comes with more complete documentation of
+editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs
+or @code{vi} may wish to read it.
+@ifset have-readline-appendices
+@xref{Command Line Editing}.
+@end ifset
-@item info proc all
-Show all the above information about the process.
+@c @group
+@kindex show history
+@item show history
+@itemx show history filename
+@itemx show history save
+@itemx show history size
+@itemx show history expansion
+These commands display the state of the @value{GDBN} history parameters.
+@code{show history} by itself displays all four states.
+@c @end group
@end table
-@node Embedded OS
-@section Embedded Operating Systems
+@table @code
+@kindex shows
+@item show commands
+Display the last ten commands in the command history.
-This section describes configurations involving the debugging of
-embedded operating systems that are available for several different
-architectures.
+@item show commands @var{n}
+Print ten commands centered on command number @var{n}.
-@menu
-* VxWorks:: Using @value{GDBN} with VxWorks
-@end menu
+@item show commands +
+Print ten commands just after the commands last printed.
+@end table
-@value{GDBN} includes the ability to debug programs running on
-various real-time operating systems.
+@node Screen Size
+@section Screen size
+@cindex size of screen
+@cindex pauses in output
-@node VxWorks
-@subsection Using @value{GDBN} with VxWorks
+Certain commands to @value{GDBN} may produce large amounts of
+information output to the screen. To help you read all of it,
+@value{GDBN} pauses and asks you for input at the end of each page of
+output. Type @key{RET} when you want to continue the output, or @kbd{q}
+to discard the remaining output. Also, the screen width setting
+determines when to wrap lines of output. Depending on what is being
+printed, @value{GDBN} tries to break the line at a readable place,
+rather than simply letting it overflow onto the following line.
-@cindex VxWorks
+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,
+you can override it with the @code{set height} and @code{set
+width} commands:
@table @code
+@kindex set height
+@kindex set width
+@kindex show width
+@kindex show height
+@item set height @var{lpp}
+@itemx show height
+@itemx set width @var{cpl}
+@itemx show width
+These @code{set} commands specify a screen height of @var{lpp} lines and
+a screen width of @var{cpl} characters. The associated @code{show}
+commands display the current settings.
-@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.
+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
-On VxWorks, @code{load} links @var{filename} dynamically on the
-current target system as well as adding its symbols in @value{GDBN}.
+@node Numbers
+@section Numbers
+@cindex number representation
+@cindex entering numbers
-@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.)
+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
-@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.
+@kindex set input-radix
+@item set input-radix @var{base}
+Set the default base for numeric input. Supported choices
+for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+specified either unambiguously or using the current default radix; for
+example, any of
+
+@smallexample
+set radix 012
+set radix 10.
+set radix 0xa
+@end smallexample
+
+@noindent
+sets the base to decimal. On the other hand, @samp{set radix 10}
+leaves the radix unchanged no matter what it was.
+
+@kindex set output-radix
+@item set output-radix @var{base}
+Set the default base for numeric display. Supported choices
+for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+specified either unambiguously or using the current default radix.
+
+@kindex show input-radix
+@item show input-radix
+Display the current default base for numeric input.
+
+@kindex show output-radix
+@item show output-radix
+Display the current default base for numeric display.
@end table
-The following information on connecting to VxWorks was current when
-this manual was produced; newer releases of VxWorks may use revised
-procedures.
+@node Messages/Warnings
+@section Optional warnings and messages
-@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}.
+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.
-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).
+Currently, the messages controlled by @code{set verbose} are those
+which announce that the symbol table for a source file is being read;
+see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
-@value{GDBN} comes up showing the prompt:
+@table @code
+@kindex set verbose
+@item set verbose on
+Enables @value{GDBN} output of certain informational messages.
-@example
-(vxgdb)
-@end example
+@item set verbose off
+Disables @value{GDBN} output of certain informational messages.
-@menu
-* VxWorks Connection:: Connecting to VxWorks
-* VxWorks Download:: VxWorks download
-* VxWorks Attach:: Running tasks
-@end menu
+@kindex show verbose
+@item show verbose
+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}).
+
+@table @code
-@node VxWorks Connection
-@subsubsection Connecting to VxWorks
+@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.
-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:
+@kindex show complaints
+@item show complaints
+Displays how many symbol complaints @value{GDBN} is permitted to produce.
-@example
-(vxgdb) target vxworks tt
-@end example
+@end table
-@need 750
-@value{GDBN} displays messages like these:
+By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
+lot of stupid questions to confirm certain commands. For example, if
+you try to run a program which is already running:
@smallexample
-Attaching remote machine across net...
-Connected to tt.
+(@value{GDBP}) run
+The program being debugged has been started already.
+Start it from the beginning? (y or n)
@end smallexample
-@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:
+If you are willing to unflinchingly face the consequences of your own
+commands, you can disable this ``feature'':
-@example
-prog.o: No such file or directory.
-@end example
+@table @code
-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.
+@kindex set confirm
+@cindex flinching
+@cindex confirmation
+@cindex stupid questions
+@item set confirm off
+Disables confirmation requests.
-@node VxWorks Download
-@subsubsection VxWorks download
+@item set confirm on
+Enables confirmation requests (the default).
-@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:
+@kindex show confirm
+@item show confirm
+Displays state of confirmation requests.
-@example
--> cd "@var{vxpath}/vw/demo/rdb"
-@end example
+@end table
-@noindent
-Then, in @value{GDBN}, type:
+@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
-@example
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
-(vxgdb) load prog.o
-@end example
+@node Sequences
+@chapter Canned Sequences of Commands
-@value{GDBN} displays a response similar to this:
+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.
+
+@menu
+* Define:: User-defined commands
+* Hooks:: User-defined command hooks
+* Command Files:: Command files
+* Output:: Commands for controlled output
+@end menu
+
+@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:
@smallexample
-Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
+define adder
+ print $arg0 + $arg1 + $arg2
@end smallexample
-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.)
+@noindent
+To execute the command use:
-@node VxWorks Attach
-@subsubsection Running tasks
+@smallexample
+adder 1 2 3
+@end smallexample
-@cindex running VxWorks tasks
-You can also attach to an existing task using the @code{attach} command as
-follows:
+@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.
-@example
-(vxgdb) attach @var{task}
-@end example
+@table @code
-@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.
+@kindex define
+@item define @var{commandname}
+Define a command named @var{commandname}. If there is already a command
+by that name, you are asked to confirm that you want to redefine it.
-@node Embedded Processors
-@section Embedded Processors
+The definition of the command is made up of other @value{GDBN} command lines,
+which are given following the @code{define} command. The end of these
+commands is marked by a line containing @code{end}.
-This section goes into details specific to particular embedded
-configurations.
+@kindex if
+@kindex else
+@item if
+Takes a single argument, which is an expression to evaluate.
+It is followed by a series of commands that are executed
+only if the expression is true (nonzero).
+There can then optionally be a line @code{else}, followed
+by a series of commands that are only executed if the expression
+was false. The end of the list is marked by a line containing @code{end}.
-@menu
-* A29K Embedded:: AMD A29K Embedded
-* 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
+@kindex while
+@item while
+The syntax is similar to @code{if}: the command takes a single argument,
+which is an expression to evaluate, and must be followed by the commands to
+execute, one per line, terminated by an @code{end}.
+The commands are executed repeatedly as long as the expression
+evaluates to true.
-@node A29K Embedded
-@subsection AMD A29K Embedded
+@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
+@var{commandname} displays the documentation you have written.
-@menu
-* A29K UDI::
-* A29K EB29K::
-* Comms (EB29K):: Communications setup
-* gdb-EB29K:: EB29K cross-debugging
-* Remote Log:: Remote log
-@end menu
+You may use the @code{document} command again to change the
+documentation of a command. Redefining the command with @code{define}
+does not change the documentation.
-@table @code
+@kindex help user-defined
+@item help user-defined
+List all user-defined commands, with the first line of the documentation
+(if any) for each.
-@kindex target adapt
-@item target adapt @var{dev}
-Adapt monitor for A29K.
+@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
+definitions for all user-defined commands.
-@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{A29K EB29K, ,EBMON protocol for AMD29K}.
+@kindex show max-user-call-depth
+@kindex set max-user-call-depth
+@item show max-user-call-depth
+@itemx set max-user-call-depth
+The value of @code{max-user-call-depth} controls how many recursion
+levels are allowed in user-defined commands before GDB suspects an
+infinite recursion and aborts the command.
@end table
-@node A29K UDI
-@subsubsection A29K UDI
+When user-defined commands are executed, the
+commands of the definition are not printed. An error in any command
+stops execution of the user-defined command.
-@cindex UDI
-@cindex AMD29K via UDI
+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
+messages when used in a user-defined command.
-@value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
-protocol for debugging the a29k processor family. To use this
-configuration with AMD targets running the MiniMON monitor, you need the
-program @code{MONTIP}, available from AMD at no charge. You can also
-use @value{GDBN} with the UDI-conformant a29k simulator program
-@code{ISSTIP}, also available from AMD.
+@node Hooks
+@section User-defined command hooks
+@cindex command hooks
+@cindex hooks, for commands
+@cindex hooks, pre-command
-@table @code
-@item target udi @var{keyword}
-@kindex udi
-Select the UDI interface to a remote a29k board or simulator, where
-@var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
-This file contains keyword entries which specify parameters used to
-connect to a29k targets. If the @file{udi_soc} file is not in your
-working directory, you must set the environment variable @samp{UDICONF}
-to its pathname.
-@end table
+@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.
-@node A29K EB29K
-@subsubsection EBMON protocol for AMD29K
+@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.
-@cindex EB29K board
-@cindex running 29K programs
+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.
-AMD distributes a 29K development board meant to fit in a PC, together
-with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
-term, this development system is called the ``EB29K''. To use
-@value{GDBN} from a Unix system to run programs on the EB29K board, you
-must first connect a serial cable between the PC (which hosts the EB29K
-board) and a serial port on the Unix system. In the following, we
-assume you've hooked the cable between the PC's @file{COM1} port and
-@file{/dev/ttya} on the Unix system.
+@c It would be nice if hookpost could be passed a parameter indicating
+@c if the command it hooks executed properly or not. FIXME!
-@node Comms (EB29K)
-@subsubsection Communications setup
+@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,
+displays are printed, or the stack frame is printed.
-The next step is to set up the PC's port, by doing something like this
-in DOS on the PC:
+For example, to ignore @code{SIGALRM} signals while
+single-stepping, but treat them normally during normal execution,
+you could define:
-@example
-C:\> MODE com1:9600,n,8,1,none
-@end example
+@smallexample
+define hook-stop
+handle SIGALRM nopass
+end
-@noindent
-This example---run on an MS DOS 4.0 system---sets the PC port to 9600
-bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
-you must match the communications parameters when establishing the Unix
-end of the connection as well.
-@c FIXME: Who knows what this "no retry action" crud from the DOS manual may
-@c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
-@c
-@c It's optional, but it's unwise to omit it: who knows what is the
-@c default value set when the DOS machines boots? "No retry" means that
-@c the DOS serial device driver won't retry the operation if it fails;
-@c I understand that this is needed because the GDB serial protocol
-@c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99
+define hook-run
+handle SIGALRM pass
+end
-To give control of the PC to the Unix side of the serial line, type
-the following at the DOS console:
+define hook-continue
+handle SIGLARM pass
+end
+@end smallexample
-@example
-C:\> CTTY com1
-@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:
-@noindent
-(Later, if you wish to return control to the DOS console, you can use
-the command @code{CTTY con}---but you must send it over the device that
-had control, in our example over the @file{COM1} serial line.)
+@smallexample
+define hook-echo
+echo <<<---
+end
-From the Unix host, use a communications program such as @code{tip} or
-@code{cu} to communicate with the PC; for example,
+define hookpost-echo
+echo --->>>\n
+end
-@example
-cu -s 9600 -l /dev/ttya
-@end example
+(@value{GDBP}) echo Hello World
+<<<---Hello World--->>>
+(@value{GDBP})
-@noindent
-The @code{cu} options shown specify, respectively, the linespeed and the
-serial port to use. If you use @code{tip} instead, your command line
-may look something like the following:
+@end smallexample
-@example
-tip -9600 /dev/ttya
-@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}.
+@c FIXME! So how does Joe User discover whether a command is an alias
+@c or not?
+If an error occurs during the execution of your hook, execution of
+@value{GDBN} commands stops and @value{GDBN} issues a prompt
+(before the command that you actually typed had a chance to run).
-@noindent
-Your system may require a different name where we show
-@file{/dev/ttya} as the argument to @code{tip}. The communications
-parameters, including which port to use, are associated with the
-@code{tip} argument in the ``remote'' descriptions file---normally the
-system table @file{/etc/remote}.
-@c FIXME: What if anything needs doing to match the "n,8,1,none" part of
-@c the DOS side's comms setup? cu can support -o (odd
-@c parity), -e (even parity)---apparently no settings for no parity or
-@c for character size. Taken from stty maybe...? John points out tip
-@c can set these as internal variables, eg ~s parity=none; man stty
-@c suggests that it *might* work to stty these options with stdin or
-@c stdout redirected... ---doc@cygnus.com, 25feb91
-@c
-@c There's nothing to be done for the "none" part of the DOS MODE
-@c command. The rest of the parameters should be matched by the
-@c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99
-
-@kindex EBMON
-Using the @code{tip} or @code{cu} connection, change the DOS working
-directory to the directory containing a copy of your 29K program, then
-start the PC program @code{EBMON} (an EB29K control program supplied
-with your board by AMD). You should see an initial display from
-@code{EBMON} similar to the one that follows, ending with the
-@code{EBMON} prompt @samp{#}---
-
-@example
-C:\> G:
-
-G:\> CD \usr\joe\work29k
-
-G:\USR\JOE\WORK29K> EBMON
-Am29000 PC Coprocessor Board Monitor, version 3.0-18
-Copyright 1990 Advanced Micro Devices, Inc.
-Written by Gibbons and Associates, Inc.
-
-Enter '?' or 'H' for help
-
-PC Coprocessor Type = EB29K
-I/O Base = 0x208
-Memory Base = 0xd0000
-
-Data Memory Size = 2048KB
-Available I-RAM Range = 0x8000 to 0x1fffff
-Available D-RAM Range = 0x80002000 to 0x801fffff
-
-PageSize = 0x400
-Register Stack Size = 0x800
-Memory Stack Size = 0x1800
-
-CPU PRL = 0x3
-Am29027 Available = No
-Byte Write Available = Yes
-
-# ~.
-@end example
-
-Then exit the @code{cu} or @code{tip} program (done in the example by
-typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
-running, ready for @value{GDBN} to take over.
-
-For this example, we've assumed what is probably the most convenient
-way to make sure the same 29K program is on both the PC and the Unix
-system: a PC/NFS connection that establishes ``drive @file{G:}'' on the
-PC as a file system on the Unix host. If you do not have PC/NFS or
-something similar connecting the two systems, you must arrange some
-other way---perhaps floppy-disk transfer---of getting the 29K program
-from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
-serial line.
-
-@node gdb-EB29K
-@subsubsection EB29K cross-debugging
-
-Finally, @code{cd} to the directory containing an image of your 29K
-program on the Unix system, and start @value{GDBN}---specifying as argument the
-name of your 29K program:
-
-@example
-cd /usr/joe/work29k
-@value{GDBP} myfoo
-@end example
-
-@need 500
-Now you can use the @code{target} command:
-
-@example
-target amd-eb /dev/ttya 9600 MYFOO
-@c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
-@c emphasize that this is the name as seen by DOS (since I think DOS is
-@c single-minded about case of letters). ---doc@cygnus.com, 25feb91
-@end example
+If you try to define a hook which does not match any known command, you
+get a warning from the @code{define} command.
-@noindent
-In this example, we've assumed your program is in a file called
-@file{myfoo}. Note that the filename given as the last argument to
-@code{target amd-eb} should be the name of the program as it appears to DOS.
-In our example this is simply @code{MYFOO}, but in general it can include
-a DOS path, and depending on your transfer mechanism may not resemble
-the name on the Unix side.
-
-At this point, you can set any breakpoints you wish; when you are ready
-to see your program run on the 29K board, use the @value{GDBN} command
-@code{run}.
-
-To stop debugging the remote program, use the @value{GDBN} @code{detach}
-command.
+@node Command Files
+@section Command files
-To return control of the PC to its console, use @code{tip} or @code{cu}
-once again, after your @value{GDBN} session has concluded, to attach to
-@code{EBMON}. You can then type the command @code{q} to shut down
-@code{EBMON}, returning control to the DOS command-line interpreter.
-Type @kbd{CTTY con} to return command input to the main DOS console,
-and type @kbd{~.} to leave @code{tip} or @code{cu}.
-
-@node Remote Log
-@subsubsection Remote log
-@cindex @file{eb.log}, a log file for EB29K
-@cindex log file for EB29K
-
-The @code{target amd-eb} command creates a file @file{eb.log} in the
-current working directory, to help debug problems with the connection.
-@file{eb.log} records all the output from @code{EBMON}, including echoes
-of the commands sent to it. Running @samp{tail -f} on this file in
-another window often helps to understand trouble with @code{EBMON}, or
-unexpected events on the PC side of the connection.
+@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
+the last command, as it would from the terminal.
-@node ARM
-@subsection ARM
+@cindex init file
+@cindex @file{.gdbinit}
+@cindex @file{gdb.ini}
+When you start @value{GDBN}, it automatically executes commands from its
+@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:
-@table @code
+@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.}.
-@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.
+@item
+Processes command line options and operands.
-@kindex target rdp
-@item target rdp @var{dev}
-ARM Demon monitor.
+@item
+Reads the init file (if any) in the current working directory.
-@end table
+@item
+Reads command files specified by the @samp{-x} option.
+@end enumerate
-@node H8/300
-@subsection Hitachi H8/300
+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}).
-@table @code
+@cindex init file name
+On some configurations of @value{GDBN}, the init file is known by a
+different name (these are typically environments where a specialized
+form of @value{GDBN} may need to coexist with other forms, hence a
+different name for the specialized version's init file). These are the
+environments with special init file names:
-@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.
+@cindex @file{.vxgdbinit}
+@itemize @bullet
+@item
+VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
-@kindex target e7000@r{, with H8/300}
-@item target e7000 @var{dev}
-E7000 emulator for Hitachi H8 and SH.
+@cindex @file{.os68gdbinit}
+@item
+OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
-@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.
+@cindex @file{.esgdbinit}
+@item
+ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
+@end itemize
-@end table
+You can also request the execution of a command file with the
+@code{source} command:
-@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).
+@table @code
+@kindex source
+@item source @var{filename}
+Execute the command file @var{filename}.
+@end table
-@value{GDBN} needs to know these things to talk to your
-Hitachi SH, H8/300, or H8/500:
+The lines in a command file are executed sequentially. They are not
+printed as they are executed. An error in any command terminates
+execution of the command file and control is returned to the console.
-@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.)
+Commands that would ask for confirmation if used interactively proceed
+without asking when used in a command file. Many @value{GDBN} commands that
+normally print messages to say what they are doing omit the messages
+when called from command files.
-@item
-what serial device connects your host to your Hitachi board (the first
-serial device available on your host is the default).
+@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.
-@item
-what speed to use over the serial device.
-@end enumerate
+@smallexample
+gdb < cmds > log 2>&1
+@end smallexample
-@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
+(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 Hitachi Boards
-@subsubsection Connecting to Hitachi boards
+@node Output
+@section Commands for controlled output
-@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}.
+During the execution of a command file or a user-defined command, normal
+@value{GDBN} output is suppressed; the only output that appears is what is
+explicitly printed by the commands in the definition. This section
+describes three commands useful for generating exactly the output you
+want.
-@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).
+@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{ }}.
-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.
+A backslash at the end of @var{text} can be used, as in C, to continue
+the command onto subsequent lines. For example,
-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.
+@smallexample
+echo This is some text\n\
+which is continued\n\
+onto several lines.\n
+@end smallexample
-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}.
+produces the same output as
-@example
-C:\H8300\TEST> asynctsr 2
-C:\H8300\TEST> mode com2:9600,n,8,1,p
+@smallexample
+echo This is some text\n
+echo which is continued\n
+echo onto several lines.\n
+@end smallexample
-Resident portion of MODE loaded
+@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.
-COM2: 9600, n, 8, 1, p
+@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.
-@end example
+@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.
-@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
+@smallexample
+printf (@var{string}, @var{expressions}@dots{});
+@end smallexample
-@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}.)
+For example, you can print two values in hex like this:
@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 *
+printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
@end smallexample
-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.
+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
-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!
+@node TUI
+@chapter @value{GDBN} Text User Interface
+@cindex TUI
+
+@menu
+* TUI Overview:: TUI overview
+* TUI Keys:: TUI key bindings
+* TUI Single Key Mode:: TUI single key mode
+* 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:
-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
+A curses (or TUI) mode in which it displays several text
+windows on the terminal.
@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.
+A standard mode which corresponds to the @value{GDBN} configured without
+the TUI.
@end itemize
-In either case, @value{GDBN} sees the effect of a @sc{reset} on the
-development board as a ``normal exit'' of your program.
+In the TUI mode, @value{GDBN} can display several text window
+on the terminal:
-@node Hitachi ICE
-@subsubsection Using the E7000 in-circuit emulator
+@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.
-@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:
+@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.
-@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 assembly
+The assembly window shows the disassembly output of the program.
-@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
+@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.
-@node Hitachi Special
-@subsubsection Special @value{GDBN} commands for Hitachi micros
+@end table
-Some @value{GDBN} commands are available only for the H8/300:
+The source and assembly windows show the current program position
+by highlighting the current line and marking them with the @samp{>} marker.
+Breakpoints are also indicated with two markers. A first one
+indicates the breakpoint type:
@table @code
+@item B
+Breakpoint which was hit at least once.
-@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.
-
-@end table
-
-@node H8/500
-@subsection H8/500
+@item b
+Breakpoint which was never hit.
-@table @code
+@item H
+Hardware breakpoint which was hit at least once.
-@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}.
+@item h
+Hardware breakpoint which was never hit.
@end table
-@node i960
-@subsection Intel i960
+The second marker indicates whether the breakpoint is enabled or not:
@table @code
+@item +
+Breakpoint is enabled.
-@kindex target mon960
-@item target mon960 @var{dev}
-MON960 monitor for Intel i960.
-
-@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}.
+@item -
+Breakpoint is disabled.
@end table
-@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:
+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
-Through command line options specifying serial port, version of the
-Nindy protocol, and communications speed;
+source
@item
-By responding to a prompt on startup;
+assembly
@item
-By using the @code{target} command at any point during your @value{GDBN}
-session. @xref{Target Commands, ,Commands for managing targets}.
+source and assembly
+
+@item
+source and registers
+
+@item
+assembly and registers
@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}.
+On top of the command window a status line gives various information
+concerning the current process begin debugged. The status line is
+updated when the information it shows changes. The following fields
+are displayed:
-@menu
-* Nindy Startup:: Startup with Nindy
-* Nindy Options:: Options for Nindy
-* Nindy Reset:: Nindy reset command
-@end menu
+@table @emph
+@item target
+Indicates the current gdb target
+(@pxref{Targets, ,Specifying a Debugging Target}).
-@node Nindy Startup
-@subsubsection Startup with Nindy
+@item process
+Gives information about the current process or thread number.
+When no process is being debugged, this field is set to @code{No process}.
-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:
+@item function
+Gives the current function name for the selected frame.
+The name is demangled if demangling is turned on (@pxref{Print Settings}).
+When there is no symbol corresponding to the current program counter
+the string @code{??} is displayed.
-@example
-Attach /dev/ttyNN -- specify NN, or "quit" to quit:
-@end example
+@item line
+Indicates the current line number for the selected frame.
+When the current line number is not known the string @code{??} is displayed.
-@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}).
+@item pc
+Indicates the current program counter address.
-@node Nindy Options
-@subsubsection Options for Nindy
+@end table
-These are the startup options for beginning your @value{GDBN} session with a
-Nindy-960 board attached:
+@node TUI Keys
+@section TUI Key Bindings
+@cindex TUI key bindings
-@table @code
-@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}).
+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 TUI also provides
+a @emph{SingleKey} keymap which binds several keys directly to
+@value{GDBN} commands. The following key bindings
+are installed for both TUI mode and the @value{GDBN} standard mode.
-@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.
+@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.
-@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
+@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.
-@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.
+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.
+
+@kindex C-x s
+@item C-x s
+Use the TUI @emph{SingleKey} keymap that binds single key to gdb commands
+(@pxref{TUI Single Key Mode}).
-@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
-The standard @samp{-b} option controls the line speed used on the serial
-port.
+The following key bindings are handled only by the TUI mode:
-@c @group
-@node Nindy Reset
-@subsubsection Nindy reset command
+@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.
-@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
+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}.
-@table @code
+@node TUI Single Key Mode
+@section TUI Single Key Mode
+@cindex TUI single key mode
-@kindex target m32r
-@item target m32r @var{dev}
-Mitsubishi M32R/D ROM monitor.
+The TUI provides a @emph{SingleKey} mode in which it installs a particular
+key binding in the readline keymaps to connect single keys to
+some gdb commands.
-@end table
+@table @kbd
+@kindex c @r{(SingleKey TUI key)}
+@item c
+continue
-@node M68K
-@subsection M68k
+@kindex d @r{(SingleKey TUI key)}
+@item d
+down
-The Motorola m68k configuration includes ColdFire support, and
-target command for the following ROM monitors.
+@kindex f @r{(SingleKey TUI key)}
+@item f
+finish
-@table @code
+@kindex n @r{(SingleKey TUI key)}
+@item n
+next
-@kindex target abug
-@item target abug @var{dev}
-ABug ROM monitor for M68K.
+@kindex q @r{(SingleKey TUI key)}
+@item q
+exit the @emph{SingleKey} mode.
-@kindex target cpu32bug
-@item target cpu32bug @var{dev}
-CPU32BUG monitor, running on a CPU32 (M68K) board.
+@kindex r @r{(SingleKey TUI key)}
+@item r
+run
-@kindex target dbug
-@item target dbug @var{dev}
-dBUG ROM monitor for Motorola ColdFire.
+@kindex s @r{(SingleKey TUI key)}
+@item s
+step
-@kindex target est
-@item target est @var{dev}
-EST-300 ICE monitor, running on a CPU32 (M68K) board.
+@kindex u @r{(SingleKey TUI key)}
+@item u
+up
-@kindex target rom68k
-@item target rom68k @var{dev}
-ROM 68K monitor, running on an M68K IDP board.
+@kindex v @r{(SingleKey TUI key)}
+@item v
+info locals
+
+@kindex w @r{(SingleKey TUI key)}
+@item w
+where
@end table
-If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
-instead have only a single special target command:
+Other keys temporarily switch to the @value{GDBN} command prompt.
+The key that was pressed is inserted in the editing buffer so that
+it is possible to type most @value{GDBN} commands without interaction
+with the TUI @emph{SingleKey} mode. Once the command is entered the TUI
+@emph{SingleKey} mode is restored. The only way to permanently leave
+this mode is by hitting @key{q} or @samp{@key{C-x} @key{s}}.
+
+
+@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 info win
+@kindex info win
+List and give the size of all displayed windows.
-@kindex target es1800
-@item target es1800 @var{dev}
-ES-1800 emulator for M68K.
+@item layout next
+@kindex layout next
+Display the next layout.
-@end table
+@item layout prev
+@kindex layout prev
+Display the previous layout.
-[context?]
+@item layout src
+@kindex layout src
+Display the source window only.
-@table @code
+@item layout asm
+@kindex layout asm
+Display the assembly window only.
-@kindex target rombug
-@item target rombug @var{dev}
-ROMBUG ROM monitor for OS/9000.
+@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 M88K
-@subsection M88K
+@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.
-@kindex target bug
-@item target bug @var{dev}
-BUG monitor, running on a MVME187 (m88k) board.
+@item ascii
+Use ascii characters + - and | to draw the border.
+
+@item acs
+Use the Alternate Character Set to draw the border. The border is
+drawn using character line graphics if the terminal supports them.
@end table
-@node MIPS Embedded
-@subsection MIPS Embedded
+@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}.
-@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}.
+@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.
-@need 1000
-Use these @value{GDBN} commands to specify the connection to your target board:
+@item standout
+Use standout mode.
-@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.
+@item reverse
+Use reverse video mode.
-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 half
+Use half bright mode.
-@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 half-standout
+Use half bright and standout mode.
-@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}}.
+@item bold
+Use extra bright or bold mode.
-@item target pmon @var{port}
-@kindex target pmon @var{port}
-PMON ROM monitor.
+@item bold-standout
+Use extra bright or bold and standout mode.
-@item target ddb @var{port}
-@kindex target ddb @var{port}
-NEC's DDB variant of PMON for Vr4300.
+@end table
-@item target lsi @var{port}
-@kindex target lsi @var{port}
-LSI variant of PMON.
+@end table
-@kindex target r3900
-@item target r3900 @var{dev}
-Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
+@node Emacs
+@chapter Using @value{GDBN} under @sc{gnu} Emacs
-@kindex target array
-@item target array @var{dev}
-Array Tech LSI33K RAID controller board.
+@cindex Emacs
+@cindex @sc{gnu} Emacs
+A special interface allows you to use @sc{gnu} Emacs to view (and
+edit) the source files for the program you are debugging with
+@value{GDBN}.
-@end table
+To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
+executable file you want to debug as an argument. This command starts
+@value{GDBN} as a subprocess of Emacs, with input and output through a newly
+created Emacs buffer.
+@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:
-@noindent
-@value{GDBN} also supports these special commands for MIPS targets:
+@itemize @bullet
+@item
+All ``terminal'' input and output goes through the Emacs buffer.
+@end itemize
-@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.
+This applies both to @value{GDBN} commands and their output, and to the input
+and output done by the program you are debugging.
-@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}.
+This is useful because it means that you can copy the text of previous
+commands and input them again; you can even use parts of the output
+in this way.
-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.
+All the facilities of Emacs' Shell mode are available for interacting
+with your program. In particular, you can send signals the usual
+way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
+stop.
-As usual, you can inquire about the @code{mipsfpu} variable with
-@samp{show mipsfpu}.
+@itemize @bullet
+@item
+@value{GDBN} displays source code through Emacs.
+@end itemize
-@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}.
+Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
+source file for that frame and puts an arrow (@samp{=>}) at the
+left margin of the current line. Emacs uses a separate buffer for
+source display, and splits the screen to show both your @value{GDBN} session
+and the source.
-@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}.)
+Explicit @value{GDBN} @code{list} or search commands still produce output as
+usual, but you probably have no reason to use them from Emacs.
-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
+@quotation
+@emph{Warning:} If the directory where your program resides is not your
+current directory, it can be easy to confuse Emacs about the location of
+the source files, in which case the auxiliary display buffer does not
+appear to show your source. @value{GDBN} can find programs by searching your
+environment's @code{PATH} variable, so the @value{GDBN} input and output
+session proceeds normally; but Emacs does not get enough information
+back from @value{GDBN} to locate the source files in this situation. To
+avoid this problem, either start @value{GDBN} mode from the directory where
+your program resides, or specify an absolute file name when prompted for the
+@kbd{M-x gdb} argument.
-@node PowerPC
-@subsection PowerPC
+A similar confusion can result if you use the @value{GDBN} @code{file} command to
+switch to debugging a program in some other location, from an existing
+@value{GDBN} buffer in Emacs.
+@end quotation
-@table @code
+By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
+you need to call @value{GDBN} by a different name (for example, if you keep
+several configurations around, with different names) you can set the
+Emacs variable @code{gdb-command-name}; for example,
-@kindex target dink32
-@item target dink32 @var{dev}
-DINK32 ROM monitor.
+@smallexample
+(setq gdb-command-name "mygdb")
+@end smallexample
-@kindex target ppcbug
-@item target ppcbug @var{dev}
-@kindex target ppcbug1
-@item target ppcbug1 @var{dev}
-PPCBUG ROM monitor for PowerPC.
+@noindent
+(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.
+
+In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
+addition to the standard Shell mode commands:
-@kindex target sds
-@item target sds @var{dev}
-SDS monitor, running on a PowerPC board (such as Motorola's ADS).
+@table @kbd
+@item C-h m
+Describe the features of Emacs' @value{GDBN} Mode.
-@end table
+@item M-s
+Execute to another source line, like the @value{GDBN} @code{step} command; also
+update the display window to show the current file and location.
-@node PA
-@subsection HP PA Embedded
+@item M-n
+Execute to next source line in this function, skipping all function
+calls, like the @value{GDBN} @code{next} command. Then update the display window
+to show the current file and location.
-@table @code
+@item M-i
+Execute one instruction, like the @value{GDBN} @code{stepi} command; update
+display window accordingly.
-@kindex target op50n
-@item target op50n @var{dev}
-OP50N monitor, running on an OKI HPPA board.
+@item M-x gdb-nexti
+Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
+display window accordingly.
-@kindex target w89k
-@item target w89k @var{dev}
-W89K monitor, running on a Winbond HPPA board.
+@item C-c C-f
+Execute until exit from the selected stack frame, like the @value{GDBN}
+@code{finish} command.
-@end table
+@item M-c
+Continue execution of your program, like the @value{GDBN} @code{continue}
+command.
-@node SH
-@subsection Hitachi SH
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
-@table @code
+@item M-u
+Go up the number of frames indicated by the numeric argument
+(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
+like the @value{GDBN} @code{up} command.
-@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.
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
-@kindex target e7000@r{, with Hitachi SH}
-@item target e7000 @var{dev}
-E7000 emulator for Hitachi SH.
+@item M-d
+Go down the number of frames indicated by the numeric argument, like the
+@value{GDBN} @code{down} command.
-@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.
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
-@end table
+@item C-x &
+Read the number where the cursor is positioned, and insert it at the end
+of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code
+around an address that was displayed earlier, type @kbd{disassemble};
+then move the cursor to the address display, and pick up the
+argument for @code{disassemble} by typing @kbd{C-x &}.
-@node Sparclet
-@subsection Tsqware Sparclet
+You can customize this further by defining elements of the list
+@code{gdb-print-command}; once it is defined, you can format or
+otherwise process numbers picked up by @kbd{C-x &} before they are
+inserted. A numeric argument to @kbd{C-x &} indicates that you
+wish special formatting, and also acts as an index to pick an element of the
+list. If the list element is a string, the number to be inserted is
+formatted using the Emacs function @code{format}; otherwise the number
+is passed as an argument to the corresponding list element.
+@end table
-@cindex Sparclet
+In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
+tells @value{GDBN} to set a breakpoint on the source line point is on.
-@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.
+If you accidentally delete the source-display buffer, an easy way to get
+it back is to type the command @code{f} in the @value{GDBN} buffer, to
+request a frame display; when you run under Emacs, this recreates
+the source buffer if necessary to show you the context of the current
+frame.
-@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
+The source files displayed in Emacs are in ordinary Emacs buffers
+which are visiting the source files in the usual way. You can edit
+the files with these buffers if you wish; but keep in mind that @value{GDBN}
+communicates with Emacs in terms of line numbers. If you add or
+delete lines from the text, the line numbers that @value{GDBN} knows cease
+to correspond properly with the code.
-@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:
+@c The following dropped because Epoch is nonstandard. Reactivate
+@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
+@ignore
+@kindex Emacs Epoch environment
+@kindex Epoch
+@kindex inspect
-@example
-sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
-@end example
+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
-You can use @code{objdump} to verify that the addresses are what you intended:
+@include annotate.texi
+@include gdbmi.texinfo
-@example
-sparclet-aout-objdump --headers --syms prog
-@end example
+@node GDB Bugs
+@chapter Reporting Bugs in @value{GDBN}
+@cindex bugs in @value{GDBN}
+@cindex reporting bugs in @value{GDBN}
-@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).
+Your bug reports play an essential role in making @value{GDBN} reliable.
-@value{GDBN} comes up showing the prompt:
+Reporting a bug may help you by bringing a solution to your problem, or it
+may not. But in any case the principal function of a bug report is to help
+the entire community by making the next version of @value{GDBN} work better. Bug
+reports are your contribution to the maintenance of @value{GDBN}.
-@example
-(gdbslet)
-@end example
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
@menu
-* Sparclet File:: Setting the file to debug
-* Sparclet Connection:: Connecting to Sparclet
-* Sparclet Download:: Sparclet download
-* Sparclet Execution:: Running and debugging
+* Bug Criteria:: Have you found a bug?
+* Bug Reporting:: How to report bugs
@end menu
-@node Sparclet File
-@subsubsection Setting file to debug
-
-The @value{GDBN} command @code{file} lets you choose with program to debug.
-
-@example
-(gdbslet) file prog
-@end example
+@node Bug Criteria
+@section Have you found a bug?
+@cindex bug criteria
-@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:
+If you are not sure whether you have found a bug, here are some guidelines:
-@example
-prog: No such file or directory.
-@end example
+@itemize @bullet
+@cindex fatal signal
+@cindex debugger crash
+@cindex crash of debugger
+@item
+If the debugger gets a fatal signal, for any input whatever, that is a
+@value{GDBN} bug. Reliable debuggers never crash.
-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.
+@cindex error on valid input
+@item
+If @value{GDBN} produces an error message for valid input, that is a
+bug. (Note that if you're cross debugging, the problem may also be
+somewhere in the connection to the target.)
-@node Sparclet Connection
-@subsubsection Connecting to Sparclet
+@cindex invalid input
+@item
+If @value{GDBN} does not produce an error message for invalid input,
+that is a bug. However, you should note that your idea of
+``invalid input'' might be our idea of ``an extension'' or ``support
+for traditional practice''.
-The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
-To connect to a target on serial port ``@code{ttya}'', type:
+@item
+If you are an experienced user of debugging tools, your suggestions
+for improvement of @value{GDBN} are welcome in any case.
+@end itemize
-@example
-(gdbslet) target sparclet /dev/ttya
-Remote target sparclet connected to /dev/ttya
-main () at ../prog.c:3
-@end example
+@node Bug Reporting
+@section How to report bugs
+@cindex bug reports
+@cindex @value{GDBN} bugs, reporting
-@need 750
-@value{GDBN} displays messages like these:
+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.
-@example
-Connected to ttya.
-@end example
+You can find contact information for many support companies and
+individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
+distribution.
+@c should add a web page ref...
-@node Sparclet Download
-@subsubsection Sparclet download
+In any event, we also recommend that you submit bug reports for
+@value{GDBN}. The prefered method is to submit them directly using
+@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web
+page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can
+be used.
-@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:
+@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
+not want to receive bug reports. Those that do have arranged to receive
+@samp{bug-gdb}.
-@example
-(gdbslet) load prog 0x12010000
-Loading section .text, size 0xdb0 vma 0x12010000
-@end example
+The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
+serves as a repeater. The mailing list and the newsgroup carry exactly
+the same messages. Often people think of posting bug reports to the
+newsgroup instead of mailing them. This appears to work, but it has one
+problem which can be crucial: a newsgroup posting often lacks a mail
+path back to the sender. Thus, if we need to ask for more information,
+we may be unable to reach you. For this reason, it is better to send
+bug reports to the mailing list.
-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.
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}. If you are not sure whether to state a
+fact or leave it out, state it!
-@node Sparclet Execution
-@subsubsection Running and debugging
+Often people omit facts because they think they know what causes the
+problem and assume that some details do not matter. Thus, you might
+assume that the name of the variable you use in an example does not matter.
+Well, probably it does not, but one cannot be sure. Perhaps the bug is a
+stray memory reference which happens to fetch from the location where that
+name is stored in memory; perhaps, if the name were different, the contents
+of that location would fool the debugger into doing the right thing despite
+the bug. Play it safe and give a specific, complete example. That is the
+easiest thing for you to do, and the most helpful.
-@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.
+Keep in mind that the purpose of a bug report is to enable us to fix the
+bug. It may be that the bug has been reported previously, but neither
+you nor we can know that unless your bug report is complete and
+self-contained.
-@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
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?'' Those bug reports are useless, and we urge everyone to
+@emph{refuse to respond to them} except to chide the sender to report
+bugs properly.
-@node Sparclite
-@subsection Fujitsu Sparclite
+To enable us to fix the bug, you should include all these things:
-@table @code
+@itemize @bullet
+@item
+The version of @value{GDBN}. @value{GDBN} announces it if you start
+with no arguments; you can also print it at any time using @code{show
+version}.
-@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
-remote protocol.
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of @value{GDBN}.
-@end table
+@item
+The type of machine you are using, and the operating system name and
+version number.
-@node ST2000
-@subsection Tandem ST2000
+@item
+What compiler (and its version) was used to compile @value{GDBN}---e.g.
+``@value{GCC}--2.8.1''.
-@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
-STDBUG protocol.
+@item
+What compiler (and its version) was used to compile the program you are
+debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
+C Compiler''. For GCC, you can say @code{gcc --version} to get this
+information; for other compilers, see the documentation for those
+compilers.
-To connect your ST2000 to the host system, see the manufacturer's
-manual. Once the ST2000 is physically attached, you can run:
+@item
+The command arguments you gave the compiler to compile your example and
+observe the bug. For example, did you use @samp{-O}? To guarantee
+you will not omit something important, list them all. A copy of the
+Makefile (or the output from make) is sufficient.
-@example
-target st2000 @var{dev} @var{speed}
-@end example
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
-@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}}.
+@item
+A complete input script, and all necessary source files, that will
+reproduce the bug.
-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.
+@item
+A description of what behavior you observe that you believe is
+incorrect. For example, ``It gets a fatal signal.''
-@cindex ST2000 auxiliary commands
-These auxiliary @value{GDBN} commands are available to help you with the ST2000
-environment:
+Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
+will certainly notice it. But if the bug is incorrect output, we might
+not notice unless it is glaringly wrong. You might as well not give us
+a chance to make a mistake.
-@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.
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly. Suppose something strange is going on, such as, your
+copy of @value{GDBN} is out of synch, or you have encountered a bug in
+the C library on your system. (This has happened!) Your copy might
+crash and ours would not. If you told us to expect a crash, then when
+ours fails to crash, we would know that the bug was not happening for
+us. If you had not told us to expect a crash, then we would not be able
+to draw any conclusion from our observations.
-@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
+@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
+it by context, not by line number.
-@node Z8000
-@subsection Zilog Z8000
+The line numbers in our development sources will not match those in your
+sources. Your line numbers would convey no useful information to us.
-@cindex Z8000
-@cindex simulator, Z8000
-@cindex Zilog Z8000 simulator
+@end itemize
-When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
-a Z8000 simulator.
+Here are some things that are not necessary:
-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.
+@itemize @bullet
+@item
+A description of the envelope of the bug.
-@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
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
-@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.
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
-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:
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us. Errors in the
+output will be easier to spot, running under the debugger will take
+less time, and so on.
-@table @code
+However, simplification is not vital; if you do not want to do this,
+report the bug anyway and send us the entire test case you used.
-@item cycles
-Counts clock-ticks in the simulator.
+@item
+A patch for the bug.
-@item insts
-Counts instructions run in the simulator.
+A patch for the bug does help us if it is a good one. But do not omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need. We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
-@item time
-Execution time in 60ths of a second.
+Sometimes with a program as complicated as @value{GDBN} it is very hard to
+construct an example that will make the program follow a certain path
+through the code. If you do not send us the example, we will not be able
+to construct one, so we will not be able to verify that the bug is fixed.
-@end table
+And if we cannot understand what bug you are trying to fix, or why your
+patch should be an improvement, we will not install it. A test case will
+help us to understand.
-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.
+@item
+A guess about what the bug is or what it depends on.
-@node Architectures
-@section Architectures
+Such guesses are usually wrong. Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
-This section describes characteristics of architectures that affect
-all uses of @value{GDBN} with the architecture, both native and cross.
+@c The readline documentation is distributed with the readline code
+@c and consists of the two following files:
+@c rluser.texinfo
+@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.texinfo
-@menu
-* A29K::
-* Alpha::
-* MIPS::
-@end menu
-@node A29K
-@subsection A29K
+@node Formatting Documentation
+@appendix Formatting Documentation
-@table @code
+@cindex @value{GDBN} reference card
+@cindex reference card
+The @value{GDBN} 4 release includes an already-formatted reference card, ready
+for printing with PostScript or Ghostscript, in the @file{gdb}
+subdirectory of the main source directory@footnote{In
+@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
+release.}. If you can use PostScript or Ghostscript with your printer,
+you can print the reference card immediately with @file{refcard.ps}.
-@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.
+The release also includes the source for the reference card. You
+can format it, using @TeX{}, by typing:
-@kindex show rstack_high_address
-@item show rstack_high_address
-Display the current limit of the register stack, on AMD 29000 family
-processors.
+@smallexample
+make refcard.dvi
+@end smallexample
-@end table
+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.
-@node Alpha
-@subsection Alpha
+@cindex documentation
-See the following section.
+All the documentation for @value{GDBN} comes as part of the machine-readable
+distribution. The documentation is written in Texinfo format, which is
+a documentation system that uses a single source file to produce both
+on-line information and a printed manual. You can use one of the Info
+formatting commands to create the on-line version of the documentation
+and @TeX{} (or @code{texi2roff}) to typeset the printed version.
-@node MIPS
-@subsection MIPS
+@value{GDBN} includes an already formatted copy of the on-line Info
+version of this manual in the @file{gdb} subdirectory. The main Info
+file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
+subordinate files matching @samp{gdb.info*} in the same directory. If
+necessary, you can print out these files, or read them with any editor;
+but they are easier to read using the @code{info} subsystem in @sc{gnu}
+Emacs or the standalone @code{info} program, available as part of the
+@sc{gnu} Texinfo distribution.
-@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.
+If you want to format these Info files yourself, you need one of the
+Info formatting programs, such as @code{texinfo-format-buffer} or
+@code{makeinfo}.
-@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:
+If you have @code{makeinfo} installed, and are in the top level
+@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
+version @value{GDBVN}), you can make the Info file by typing:
-@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.
+@smallexample
+cd gdb
+make gdb.info
+@end smallexample
-@item show heuristic-fence-post
-Display the current limit.
-@end table
+If you want to typeset and print copies of this manual, you need @TeX{},
+a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
+Texinfo definitions file.
-@noindent
-These commands are available @emph{only} when @value{GDBN} is configured
-for debugging programs on Alpha or MIPS processors.
+@TeX{} is a typesetting program; it does not print files directly, but
+produces output files called @sc{dvi} files. To print a typeset
+document, you need a program to print @sc{dvi} files. If your system
+has @TeX{} installed, chances are it has such a program. The precise
+command to use depends on your system; @kbd{lpr -d} is common; another
+(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
+require a file name without any extension or a @samp{.dvi} extension.
+@TeX{} also requires a macro definitions file called
+@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
+written in Texinfo format. On its own, @TeX{} cannot either read or
+typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
+and is located in the @file{gdb-@var{version-number}/texinfo}
+directory.
-@node Controlling GDB
-@chapter Controlling @value{GDBN}
+If you have @TeX{} and a @sc{dvi} printer program installed, you can
+typeset and print this manual. First switch to the the @file{gdb}
+subdirectory of the main source directory (for example, to
+@file{gdb-@value{GDBVN}/gdb}) and type:
-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.
+@smallexample
+make gdb.dvi
+@end smallexample
-@menu
-* Prompt:: Prompt
-* Editing:: Command editing
-* History:: Command history
-* Screen Size:: Screen size
-* Numbers:: Numbers
-* Messages/Warnings:: Optional warnings and messages
-* Debugging Output:: Optional messages about internal happenings
-@end menu
+Then give @file{gdb.dvi} to your @sc{dvi} printing program.
-@node Prompt
-@section Prompt
+@node Installing GDB
+@appendix Installing @value{GDBN}
+@cindex configuring @value{GDBN}
+@cindex installation
-@cindex prompt
+@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.
+@iftex
+@c irrelevant in info file; it's as current as the code it lives with.
+@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
+look at the @file{README} file in the sources; we may have improved the
+installation procedures since publishing this manual.}
+@end iftex
-@value{GDBN} indicates its readiness to read a command by printing a string
-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
-which one you are talking to.
+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}.
-@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.
+For example, the @value{GDBN} version @value{GDBVN} distribution is in the
+@file{gdb-@value{GDBVN}} directory. That directory contains:
@table @code
-@kindex set prompt
-@item set prompt @var{newprompt}
-Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
-
-@kindex show prompt
-@item show prompt
-Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
-@end table
+@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
+script for configuring @value{GDBN} and all its supporting libraries
-@node Editing
-@section Command editing
-@cindex readline
-@cindex command line editing
+@item gdb-@value{GDBVN}/gdb
+the source specific to @value{GDBN} itself
-@value{GDBN} reads its input commands via the @dfn{readline} interface. This
-@sc{gnu} library provides consistent behavior for programs which provide a
-command line interface to the user. Advantages are @sc{gnu} Emacs-style
-or @dfn{vi}-style inline editing of commands, @code{csh}-like history
-substitution, and a storage and recall of command history across
-debugging sessions.
+@item gdb-@value{GDBVN}/bfd
+source for the Binary File Descriptor library
-You may control the behavior of command line editing in @value{GDBN} with the
-command @code{set}.
+@item gdb-@value{GDBVN}/include
+@sc{gnu} include files
-@table @code
-@kindex set editing
-@cindex editing
-@item set editing
-@itemx set editing on
-Enable command line editing (enabled by default).
+@item gdb-@value{GDBVN}/libiberty
+source for the @samp{-liberty} free software library
-@item set editing off
-Disable command line editing.
+@item gdb-@value{GDBVN}/opcodes
+source for the library of opcode tables and disassemblers
-@kindex show editing
-@item show editing
-Show whether command line editing is enabled.
-@end table
+@item gdb-@value{GDBVN}/readline
+source for the @sc{gnu} command-line interface
-@node History
-@section Command history
+@item gdb-@value{GDBVN}/glob
+source for the @sc{gnu} filename pattern-matching subroutine
-@value{GDBN} can keep track of the commands you type during your
-debugging sessions, so that you can be certain of precisely what
-happened. Use these commands to manage the @value{GDBN} command
-history facility.
+@item gdb-@value{GDBVN}/mmalloc
+source for the @sc{gnu} memory-mapped malloc package
+@end table
-@table @code
-@cindex history substitution
-@cindex history file
-@kindex set history filename
-@kindex GDBHISTFILE
-@item set history filename @var{fname}
-Set the name of the @value{GDBN} command history file to @var{fname}.
-This is the file where @value{GDBN} reads an initial command history
-list, and where it writes the command history from this session when it
-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} (@file{./_gdb_history} on MS-DOS) if this variable
-is not set.
+The simplest way to configure and build @value{GDBN} is to run @code{configure}
+from the @file{gdb-@var{version-number}} source directory, which in
+this example is the @file{gdb-@value{GDBVN}} directory.
-@cindex history save
-@kindex set history save
-@item set history save
-@itemx set history save on
-Record command history in a file, whose name may be specified with the
-@code{set history filename} command. By default, this option is disabled.
+First switch to the @file{gdb-@var{version-number}} source directory
+if you are not already in it; then run @code{configure}. Pass the
+identifier for the platform on which @value{GDBN} will run as an
+argument.
-@item set history save off
-Stop recording command history in a file.
+For example:
-@cindex history size
-@kindex set history size
-@item set history size @var{size}
-Set the number of commands which @value{GDBN} keeps in its history list.
-This defaults to the value of the environment variable
-@code{HISTSIZE}, or to 256 if this variable is not set.
-@end table
+@smallexample
+cd gdb-@value{GDBVN}
+./configure @var{host}
+make
+@end smallexample
-@cindex history expansion
-History expansion assigns special meaning to the character @kbd{!}.
-@ifset have-readline-appendices
-@xref{Event Designators}.
-@end ifset
+@noindent
+where @var{host} is an identifier such as @samp{sun4} or
+@samp{decstation}, that identifies the platform where @value{GDBN} will run.
+(You can often leave off @var{host}; @code{configure} tries to guess the
+correct value by examining your system.)
-Since @kbd{!} is also the logical not operator in C, history expansion
-is off by default. If you decide to enable history expansion with the
-@code{set history expansion on} command, you may sometimes need to
-follow @kbd{!} (when it is used as logical not, in an expression) with
-a space or a tab to prevent it from being expanded. The readline
-history facilities do not attempt substitution on the strings
-@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
+Running @samp{configure @var{host}} and then running @code{make} builds the
+@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
+libraries, then @code{gdb} itself. The configured source files, and the
+binaries, are left in the corresponding source directories.
-The commands to control history expansion are:
+@need 750
+@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
+system does not recognize this automatically when you run a different
+shell, you may need to run @code{sh} on it explicitly:
-@table @code
-@kindex set history expansion
-@item set history expansion on
-@itemx set history expansion
-Enable history expansion. History expansion is off by default.
+@smallexample
+sh configure @var{host}
+@end smallexample
-@item set history expansion off
-Disable history expansion.
+If you run @code{configure} from a directory that contains source
+directories for multiple libraries or programs, such as the
+@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
+creates configuration files for every directory level underneath (unless
+you tell it not to, with the @samp{--norecursion} option).
-The readline code comes with more complete documentation of
-editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs
-or @code{vi} may wish to read it.
-@ifset have-readline-appendices
-@xref{Command Line Editing}.
-@end ifset
+You can run the @code{configure} script from any of the
+subordinate directories in the @value{GDBN} distribution if you only want to
+configure that subdirectory, but be sure to specify a path to it.
-@c @group
-@kindex show history
-@item show history
-@itemx show history filename
-@itemx show history save
-@itemx show history size
-@itemx show history expansion
-These commands display the state of the @value{GDBN} history parameters.
-@code{show history} by itself displays all four states.
-@c @end group
-@end table
+For example, with version @value{GDBVN}, type the following to configure only
+the @code{bfd} subdirectory:
-@table @code
-@kindex shows
-@item show commands
-Display the last ten commands in the command history.
+@smallexample
+@group
+cd gdb-@value{GDBVN}/bfd
+../configure @var{host}
+@end group
+@end smallexample
-@item show commands @var{n}
-Print ten commands centered on command number @var{n}.
+You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
+However, you should make sure that the shell on your path (named by
+the @samp{SHELL} environment variable) is publicly readable. Remember
+that @value{GDBN} uses the shell to start your program---some systems refuse to
+let @value{GDBN} debug child processes whose programs are not readable.
-@item show commands +
-Print ten commands just after the commands last printed.
-@end table
+@menu
+* Separate Objdir:: Compiling @value{GDBN} in another directory
+* Config Names:: Specifying names for hosts and targets
+* Configure Options:: Summary of options for configure
+@end menu
-@node Screen Size
-@section Screen size
-@cindex size of screen
-@cindex pauses in output
+@node Separate Objdir
+@section Compiling @value{GDBN} in another directory
-Certain commands to @value{GDBN} may produce large amounts of
-information output to the screen. To help you read all of it,
-@value{GDBN} pauses and asks you for input at the end of each page of
-output. Type @key{RET} when you want to continue the output, or @kbd{q}
-to discard the remaining output. Also, the screen width setting
-determines when to wrap lines of output. Depending on what is being
-printed, @value{GDBN} tries to break the line at a readable place,
-rather than simply letting it overflow onto the following line.
+If you want to run @value{GDBN} versions for several host or target machines,
+you need a different @code{gdb} compiled for each combination of
+host and target. @code{configure} is designed to make this easy by
+allowing you to generate each configuration in a separate subdirectory,
+rather than in the source directory. If your @code{make} program
+handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
+@code{make} in each of these directories builds the @code{gdb}
+program specified there.
-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,
-you can override it with the @code{set height} and @code{set
-width} commands:
+To build @code{gdb} in a separate directory, run @code{configure}
+with the @samp{--srcdir} option to specify where to find the source.
+(You also need to specify a path to find @code{configure}
+itself from your working directory. If the path to @code{configure}
+would be the same as the argument to @samp{--srcdir}, you can leave out
+the @samp{--srcdir} option; it is assumed.)
-@table @code
-@kindex set height
-@kindex set width
-@kindex show width
-@kindex show height
-@item set height @var{lpp}
-@itemx show height
-@itemx set width @var{cpl}
-@itemx show width
-These @code{set} commands specify a screen height of @var{lpp} lines and
-a screen width of @var{cpl} characters. The associated @code{show}
-commands display the current settings.
+For example, with version @value{GDBVN}, you can build @value{GDBN} in a
+separate directory for a Sun 4 like this:
-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.
+@smallexample
+@group
+cd gdb-@value{GDBVN}
+mkdir ../gdb-sun4
+cd ../gdb-sun4
+../gdb-@value{GDBVN}/configure sun4
+make
+@end group
+@end smallexample
-Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
-from wrapping its output.
-@end table
+When @code{configure} builds a configuration using a remote source
+directory, it creates a tree for the binaries with the same structure
+(and using the same names) as the tree under the source directory. In
+the example, you'd find the Sun 4 library @file{libiberty.a} in the
+directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
+@file{gdb-sun4/gdb}.
-@node Numbers
-@section Numbers
-@cindex number representation
-@cindex entering numbers
+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}).
+You specify a cross-debugging target by
+giving the @samp{--target=@var{target}} option to @code{configure}.
-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.
+When you run @code{make} to build a program or library, you must run
+it in a configured directory---whatever directory you were in when you
+called @code{configure} (or one of its subdirectories).
-@table @code
-@kindex set input-radix
-@item set input-radix @var{base}
-Set the default base for numeric input. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
-specified either unambiguously or using the current default radix; for
-example, any of
+The @code{Makefile} that @code{configure} generates in each source
+directory also runs recursively. If you type @code{make} in a source
+directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
+directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
+will build all the required libraries, and then build GDB.
-@smallexample
-set radix 012
-set radix 10.
-set radix 0xa
-@end smallexample
+When you have multiple hosts or targets configured in separate
+directories, you can run @code{make} on them in parallel (for example,
+if they are NFS-mounted on each of the hosts); they will not interfere
+with each other.
-@noindent
-sets the base to decimal. On the other hand, @samp{set radix 10}
-leaves the radix unchanged no matter what it was.
+@node Config Names
+@section Specifying names for hosts and targets
-@kindex set output-radix
-@item set output-radix @var{base}
-Set the default base for numeric display. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
-specified either unambiguously or using the current default radix.
+The specifications used for hosts and targets in the @code{configure}
+script are based on a three-part naming scheme, but some short predefined
+aliases are also supported. The full naming scheme encodes three pieces
+of information in the following pattern:
-@kindex show input-radix
-@item show input-radix
-Display the current default base for numeric input.
+@smallexample
+@var{architecture}-@var{vendor}-@var{os}
+@end smallexample
-@kindex show output-radix
-@item show output-radix
-Display the current default base for numeric display.
-@end table
+For example, you can use the alias @code{sun4} as a @var{host} argument,
+or as the value for @var{target} in a @code{--target=@var{target}}
+option. The equivalent full name is @samp{sparc-sun-sunos4}.
-@node Messages/Warnings
-@section Optional warnings and messages
+The @code{configure} script accompanying @value{GDBN} does not provide
+any query facility to list all supported host and target names or
+aliases. @code{configure} calls the Bourne shell script
+@code{config.sub} to map abbreviations to full names; you can read the
+script, if you wish, or you can use it to test your guesses on
+abbreviations---for example:
-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.
+@smallexample
+% sh config.sub i386-linux
+i386-pc-linux-gnu
+% sh config.sub alpha-linux
+alpha-unknown-linux-gnu
+% sh config.sub hp9k700
+hppa1.1-hp-hpux
+% sh config.sub sun4
+sparc-sun-sunos4.1.1
+% sh config.sub sun3
+m68k-sun-sunos4.1.1
+% sh config.sub i986v
+Invalid configuration `i986v': machine `i986v' not recognized
+@end smallexample
-Currently, the messages controlled by @code{set verbose} are those
-which announce that the symbol table for a source file is being read;
-see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
+@noindent
+@code{config.sub} is also distributed in the @value{GDBN} source
+directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
-@table @code
-@kindex set verbose
-@item set verbose on
-Enables @value{GDBN} output of certain informational messages.
+@node Configure Options
+@section @code{configure} options
-@item set verbose off
-Disables @value{GDBN} output of certain informational messages.
+Here is a summary of the @code{configure} options and arguments that
+are most often useful for building @value{GDBN}. @code{configure} also has
+several other options not listed here. @inforef{What Configure
+Does,,configure.info}, for a full explanation of @code{configure}.
-@kindex show verbose
-@item show verbose
-Displays whether @code{set verbose} is on or off.
-@end table
+@smallexample
+configure @r{[}--help@r{]}
+ @r{[}--prefix=@var{dir}@r{]}
+ @r{[}--exec-prefix=@var{dir}@r{]}
+ @r{[}--srcdir=@var{dirname}@r{]}
+ @r{[}--norecursion@r{]} @r{[}--rm@r{]}
+ @r{[}--target=@var{target}@r{]}
+ @var{host}
+@end smallexample
-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}).
+@noindent
+You may introduce options with a single @samp{-} rather than
+@samp{--} if you prefer; but you may abbreviate option names if you use
+@samp{--}.
@table @code
+@item --help
+Display a quick summary of how to invoke @code{configure}.
-@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.
+@item --prefix=@var{dir}
+Configure the source to install programs and files under directory
+@file{@var{dir}}.
-@kindex show complaints
-@item show complaints
-Displays how many symbol complaints @value{GDBN} is permitted to produce.
+@item --exec-prefix=@var{dir}
+Configure the source to install programs under directory
+@file{@var{dir}}.
-@end table
+@c avoid splitting the warning from the explanation:
+@need 2000
+@item --srcdir=@var{dirname}
+@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
+@code{make} that implements the @code{VPATH} feature.}@*
+Use this option to make configurations in directories separate from the
+@value{GDBN} source directories. Among other things, you can use this to
+build (or maintain) several configurations simultaneously, in separate
+directories. @code{configure} writes configuration specific files in
+the current directory, but arranges for them to use the source in the
+directory @var{dirname}. @code{configure} creates directories under
+the working directory in parallel to the source directories below
+@var{dirname}.
-By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
-lot of stupid questions to confirm certain commands. For example, if
-you try to run a program which is already running:
+@item --norecursion
+Configure only the directory level where @code{configure} is executed; do not
+propagate configuration to subdirectories.
-@example
-(@value{GDBP}) run
-The program being debugged has been started already.
-Start it from the beginning? (y or n)
-@end example
+@item --target=@var{target}
+Configure @value{GDBN} for cross-debugging programs running on the specified
+@var{target}. Without this option, @value{GDBN} is configured to debug
+programs that run on the same machine (@var{host}) as @value{GDBN} itself.
-If you are willing to unflinchingly face the consequences of your own
-commands, you can disable this ``feature'':
+There is no convenient way to generate a list of all available targets.
-@table @code
+@item @var{host} @dots{}
+Configure @value{GDBN} to run on the specified @var{host}.
-@kindex set confirm
-@cindex flinching
-@cindex confirmation
-@cindex stupid questions
-@item set confirm off
-Disables confirmation requests.
+There is no convenient way to generate a list of all available hosts.
+@end table
-@item set confirm on
-Enables confirmation requests (the default).
+There are many other options available as well, but they are generally
+needed for special purposes only.
-@kindex show confirm
-@item show confirm
-Displays state of confirmation requests.
+@node Maintenance Commands
+@appendix Maintenance Commands
+@cindex maintenance commands
+@cindex internal commands
-@end table
+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.
-@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++ 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++ 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
+@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:
-@node Sequences
-@chapter Canned Sequences of Commands
+@table @code
+@item breakpoint
+Normal, explicitly set breakpoint.
-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.
+@item watchpoint
+Normal, explicitly set watchpoint.
-@menu
-* Define:: User-defined commands
-* Hooks:: User-defined command hooks
-* Command Files:: Command files
-* Output:: Commands for controlled output
-@end menu
+@item longjmp
+Internal breakpoint, used to handle correctly stepping through
+@code{longjmp} calls.
-@node Define
-@section User-defined commands
+@item longjmp resume
+Internal breakpoint at the target of a @code{longjmp}.
-@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:
+@item until
+Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
-@smallexample
-define adder
- print $arg0 + $arg1 + $arg2
-@end smallexample
+@item finish
+Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
-@noindent
-To execute the command use:
+@item shlib events
+Shared library events.
-@smallexample
-adder 1 2 3
-@end smallexample
+@end table
-@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.
+@kindex maint internal-error
+@kindex maint internal-warning
+@item maint internal-error
+@itemx maint internal-warning
+Cause @value{GDBN} to call the internal function @code{internal_error}
+or @code{internal_warning} and hence behave as though an internal error
+or internal warning has been detected. In addition to reporting the
+internal problem, these functions give the user the opportunity to
+either quit @value{GDBN} or create a core file of the current
+@value{GDBN} session.
-@table @code
+@smallexample
+(gdb) @kbd{maint internal-error testing, 1, 2}
+@dots{}/maint.c:121: internal-error: testing, 1, 2
+A problem internal to GDB has been detected. Further
+debugging may prove unreliable.
+Quit this debugging session? (y or n) @kbd{n}
+Create a core file? (y or n) @kbd{n}
+(gdb)
+@end smallexample
-@kindex define
-@item define @var{commandname}
-Define a command named @var{commandname}. If there is already a command
-by that name, you are asked to confirm that you want to redefine it.
+Takes an optional parameter that is used as the text of the error or
+warning message.
-The definition of the command is made up of other @value{GDBN} command lines,
-which are given following the @code{define} command. The end of these
-commands is marked by a line containing @code{end}.
+@kindex maint print registers
+@kindex maint print raw-registers
+@kindex maint print cooked-registers
+@item maint print registers
+@itemx maint print raw-registers
+@itemx maint print cooked-registers
+Print @value{GDBN}'s internal register data structures.
-@kindex if
-@kindex else
-@item if
-Takes a single argument, which is an expression to evaluate.
-It is followed by a series of commands that are executed
-only if the expression is true (nonzero).
-There can then optionally be a line @code{else}, followed
-by a series of commands that are only executed if the expression
-was false. The end of the list is marked by a line containing @code{end}.
+The command @samp{maint print raw-registers} includes the contents of
+the raw register cache; and the command @samp{maint print
+cooked-registers} includes the (cooked) value of all registers.
+@xref{Registers,, Registers, gdbint, @value{GDBN} Internals}.
-@kindex while
-@item while
-The syntax is similar to @code{if}: the command takes a single argument,
-which is an expression to evaluate, and must be followed by the commands to
-execute, one per line, terminated by an @code{end}.
-The commands are executed repeatedly as long as the expression
-evaluates to true.
+Takes an optional file parameter.
-@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
-@var{commandname} displays the documentation you have written.
+@end table
-You may use the @code{document} command again to change the
-documentation of a command. Redefining the command with @code{define}
-does not change the documentation.
-@kindex help user-defined
-@item help user-defined
-List all user-defined commands, with the first line of the documentation
-(if any) for each.
+@node Remote Protocol
+@appendix @value{GDBN} Remote Serial Protocol
-@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
-definitions for all user-defined commands.
+@menu
+* Overview::
+* Packets::
+* Stop Reply Packets::
+* General Query Packets::
+* Register Packet Format::
+* Examples::
+@end menu
-@end table
+@node Overview
+@section Overview
-When user-defined commands are executed, the
-commands of the definition are not printed. An error in any command
-stops execution of the user-defined command.
+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}.
-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
-messages when used in a user-defined command.
+In the examples below, @samp{->} and @samp{<-} are used to indicate
+transmitted and received data respectfully.
-@node Hooks
-@section User-defined command hooks
-@cindex command hooks
-@cindex hooks, for commands
-@cindex hooks, pre-command
+@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}:
-@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.
+@smallexample
+@code{$}@var{packet-data}@code{#}@var{checksum}
+@end smallexample
+@noindent
-@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.
+@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).
-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.
+Implementors should note that prior to @value{GDBN} 5.0 the protocol
+specification also included an optional two-digit @var{sequence-id}:
-@c It would be nice if hookpost could be passed a parameter indicating
-@c if the command it hooks executed properly or not. FIXME!
+@smallexample
+@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
+@end smallexample
-@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,
-displays are printed, or the stack frame is printed.
+@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}.
-For example, to ignore @code{SIGALRM} signals while
-single-stepping, but treat them normally during normal execution,
-you could define:
+@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
-define hook-stop
-handle SIGALRM nopass
-end
+@smallexample
+-> @code{$}@var{packet-data}@code{#}@var{checksum}
+<- @code{+}
+@end smallexample
+@noindent
-define hook-run
-handle SIGALRM pass
-end
+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).
-define hook-continue
-handle SIGLARM pass
-end
-@end example
+@var{packet-data} consists of a sequence of characters with the
+exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
+exceptions).
-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:
+Fields within the packet should be separated using @samp{,} @samp{;} or
+@cindex remote protocol, field separator
+@samp{:}. Except where otherwise noted all numbers are represented in
+@sc{hex} with leading zeros suppressed.
-@example
-define hook-echo
-echo <<<---
-end
+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}).
-define hookpost-echo
-echo --->>>\n
-end
+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.
-(@value{GDBP}) echo Hello World
-<<<---Hello World--->>>
-(@value{GDBP})
+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.
-@end example
+So:
+@smallexample
+"@code{0* }"
+@end smallexample
+@noindent
+means the same as "0000".
-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}.
-@c FIXME! So how does Joe User discover whether a command is an alias
-@c or not?
-If an error occurs during the execution of your hook, execution of
-@value{GDBN} commands stops and @value{GDBN} issues a prompt
-(before the command that you actually typed had a chance to run).
+The error response returned for some packets includes a two character
+error number. That number is not well defined.
-If you try to define a hook which does not match any known command, you
-get a warning from the @code{define} command.
+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.
-@node Command Files
-@section Command files
+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.
-@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
-the last command, as it would from the terminal.
+@node Packets
+@section Packets
-@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 and
-@file{gdb.ini} on DOS/Windows. During startup, @value{GDBN} does the
-following:
+The following table provides a complete list of all currently defined
+@var{command}s and their corresponding response @var{data}.
-@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.}.
+@table @r
-@item
-Processes command line options and operands.
+@item @code{!} --- extended mode
+@cindex @code{!} packet
-@item
-Reads the init file (if any) in the current working directory.
+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
-Reads command files specified by the @samp{-x} option.
-@end enumerate
+Reply:
+@table @samp
+@item OK
+The remote target both supports and has enabled extended mode.
+@end table
-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}).
+@item @code{?} --- last signal
+@cindex @code{?} packet
-@cindex init file name
-On some configurations of @value{GDBN}, the init file is known by a
-different name (these are typically environments where a specialized
-form of @value{GDBN} may need to coexist with other forms, hence a
-different name for the specialized version's init file). These are the
-environments with special init file names:
+Indicate the reason the target halted. The reply is the same as for
+step and continue.
-@cindex @file{.vxgdbinit}
-@itemize @bullet
-@item
-VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
-@cindex @file{.os68gdbinit}
-@item
-OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
+@item @code{a} --- reserved
-@cindex @file{.esgdbinit}
-@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
-@end itemize
+Reserved for future use.
-You can also request the execution of a command file with the
-@code{source} command:
+@item @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,@dots{}} --- set program arguments @strong{(reserved)}
+@cindex @code{A} packet
-@table @code
-@kindex source
-@item source @var{filename}
-Execute the command file @var{filename}.
-@end table
+Initialized @samp{argv[]} array passed into program. @var{arglen}
+specifies the number of bytes in the hex encoded byte stream @var{arg}.
+See @code{gdbserver} for more details.
-The lines in a command file are executed sequentially. They are not
-printed as they are executed. An error in any command terminates execution
-of the command file.
+Reply:
+@table @samp
+@item OK
+@item E@var{NN}
+@end table
-Commands that would ask for confirmation if used interactively proceed
-without asking when used in a command file. Many @value{GDBN} commands that
-normally print messages to say what they are doing omit the messages
-when called from command files.
+@item @code{b}@var{baud} --- set baud @strong{(deprecated)}
+@cindex @code{b} packet
-@node Output
-@section Commands for controlled output
+Change the serial line speed to @var{baud}.
-During the execution of a command file or a user-defined command, normal
-@value{GDBN} output is suppressed; the only output that appears is what is
-explicitly printed by the commands in the definition. This section
-describes three commands useful for generating exactly the output you
-want.
+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.}
-@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{ }}.
+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.}
-A backslash at the end of @var{text} can be used, as in C, to continue
-the command onto subsequent lines. For example,
+@item @code{B}@var{addr},@var{mode} --- set breakpoint @strong{(deprecated)}
+@cindex @code{B} packet
-@example
-echo This is some text\n\
-which is continued\n\
-onto several lines.\n
-@end example
+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.}
-produces the same output as
+@item @code{c}@var{addr} --- continue
+@cindex @code{c} packet
-@example
-echo This is some text\n
-echo which is continued\n
-echo onto several lines.\n
-@end example
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+current address.
-@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.
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
-@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 @code{C}@var{sig}@code{;}@var{addr} --- continue with signal
+@cindex @code{C} packet
-@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.
+Continue with signal @var{sig} (hex signal number). If
+@code{;}@var{addr} is omitted, resume at same address.
-@example
-printf (@var{string}, @var{expressions}@dots{});
-@end example
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
-For example, you can print two values in hex like this:
+@item @code{d} --- toggle debug @strong{(deprecated)}
+@cindex @code{d} packet
-@smallexample
-printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
-@end smallexample
+Toggle debug flag.
-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.
+@item @code{D} --- detach
+@cindex @code{D} packet
+
+Detach @value{GDBN} from the remote system. Sent to the remote target
+before @value{GDBN} disconnects.
+
+Reply:
+@table @samp
+@item @emph{no response}
+@value{GDBN} does not check for any response after sending this packet.
@end table
-@node Emacs
-@chapter Using @value{GDBN} under @sc{gnu} Emacs
+@item @code{e} --- reserved
-@cindex Emacs
-@cindex @sc{gnu} Emacs
-A special interface allows you to use @sc{gnu} Emacs to view (and
-edit) the source files for the program you are debugging with
-@value{GDBN}.
+Reserved for future use.
-To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
-executable file you want to debug as an argument. This command starts
-@value{GDBN} as a subprocess of Emacs, with input and output through a newly
-created Emacs buffer.
-@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
+@item @code{E} --- reserved
-Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
-things:
+Reserved for future use.
-@itemize @bullet
-@item
-All ``terminal'' input and output goes through the Emacs buffer.
-@end itemize
+@item @code{f} --- reserved
-This applies both to @value{GDBN} commands and their output, and to the input
-and output done by the program you are debugging.
+Reserved for future use.
-This is useful because it means that you can copy the text of previous
-commands and input them again; you can even use parts of the output
-in this way.
+@item @code{F} --- reserved
-All the facilities of Emacs' Shell mode are available for interacting
-with your program. In particular, you can send signals the usual
-way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
-stop.
+Reserved for future use.
-@itemize @bullet
-@item
-@value{GDBN} displays source code through Emacs.
-@end itemize
+@item @code{g} --- read registers
+@anchor{read registers packet}
+@cindex @code{g} packet
-Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
-source file for that frame and puts an arrow (@samp{=>}) at the
-left margin of the current line. Emacs uses a separate buffer for
-source display, and splits the screen to show both your @value{GDBN} session
-and the source.
+Read general registers.
-Explicit @value{GDBN} @code{list} or search commands still produce output as
-usual, but you probably have no reason to use them from Emacs.
+Reply:
+@table @samp
+@item @var{XX@dots{}}
+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 E@var{NN}
+for an error.
+@end table
-@quotation
-@emph{Warning:} If the directory where your program resides is not your
-current directory, it can be easy to confuse Emacs about the location of
-the source files, in which case the auxiliary display buffer does not
-appear to show your source. @value{GDBN} can find programs by searching your
-environment's @code{PATH} variable, so the @value{GDBN} input and output
-session proceeds normally; but Emacs does not get enough information
-back from @value{GDBN} to locate the source files in this situation. To
-avoid this problem, either start @value{GDBN} mode from the directory where
-your program resides, or specify an absolute file name when prompted for the
-@kbd{M-x gdb} argument.
+@item @code{G}@var{XX@dots{}} --- write regs
+@cindex @code{G} packet
-A similar confusion can result if you use the @value{GDBN} @code{file} command to
-switch to debugging a program in some other location, from an existing
-@value{GDBN} buffer in Emacs.
-@end quotation
+@xref{read registers packet}, for a description of the @var{XX@dots{}}
+data.
-By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
-you need to call @value{GDBN} by a different name (for example, if you keep
-several configurations around, with different names) you can set the
-Emacs variable @code{gdb-command-name}; for example,
+Reply:
+@table @samp
+@item OK
+for success
+@item E@var{NN}
+for an error
+@end table
-@example
-(setq gdb-command-name "mygdb")
-@end example
+@item @code{h} --- reserved
-@noindent
-(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.
+Reserved for future use.
-In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
-addition to the standard Shell mode commands:
+@item @code{H}@var{c}@var{t@dots{}} --- set thread
+@cindex @code{H} packet
-@table @kbd
-@item C-h m
-Describe the features of Emacs' @value{GDBN} Mode.
+Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
+@samp{G}, et.al.). @var{c} depends on the operation to be performed: it
+should be @samp{c} for step and continue operations, @samp{g} for other
+operations. The thread designator @var{t@dots{}} may be -1, meaning all
+the threads, a thread number, or zero which means pick any thread.
-@item M-s
-Execute to another source line, like the @value{GDBN} @code{step} command; also
-update the display window to show the current file and location.
+Reply:
+@table @samp
+@item OK
+for success
+@item E@var{NN}
+for an error
+@end table
-@item M-n
-Execute to next source line in this function, skipping all function
-calls, like the @value{GDBN} @code{next} command. Then update the display window
-to show the current file and location.
+@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 M-i
-Execute one instruction, like the @value{GDBN} @code{stepi} command; update
-display window accordingly.
+@item @code{i}@var{addr}@code{,}@var{nnn} --- cycle step @strong{(draft)}
+@anchor{cycle step packet}
+@cindex @code{i} packet
-@item M-x gdb-nexti
-Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
-display window accordingly.
+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 C-c C-f
-Execute until exit from the selected stack frame, like the @value{GDBN}
-@code{finish} command.
+@item @code{I} --- signal then cycle step @strong{(reserved)}
+@cindex @code{I} packet
-@item M-c
-Continue execution of your program, like the @value{GDBN} @code{continue}
-command.
+@xref{step with signal packet}. @xref{cycle step packet}.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
+@item @code{j} --- reserved
-@item M-u
-Go up the number of frames indicated by the numeric argument
-(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
-like the @value{GDBN} @code{up} command.
+Reserved for future use.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
+@item @code{J} --- reserved
-@item M-d
-Go down the number of frames indicated by the numeric argument, like the
-@value{GDBN} @code{down} command.
+Reserved for future use.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
+@item @code{k} --- kill request
+@cindex @code{k} packet
-@item C-x &
-Read the number where the cursor is positioned, and insert it at the end
-of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code
-around an address that was displayed earlier, type @kbd{disassemble};
-then move the cursor to the address display, and pick up the
-argument for @code{disassemble} by typing @kbd{C-x &}.
+FIXME: @emph{There is no description of how to operate when a specific
+thread context has been selected (i.e.@: does 'k' kill only that
+thread?)}.
-You can customize this further by defining elements of the list
-@code{gdb-print-command}; once it is defined, you can format or
-otherwise process numbers picked up by @kbd{C-x &} before they are
-inserted. A numeric argument to @kbd{C-x &} indicates that you
-wish special formatting, and also acts as an index to pick an element of the
-list. If the list element is a string, the number to be inserted is
-formatted using the Emacs function @code{format}; otherwise the number
-is passed as an argument to the corresponding list element.
-@end table
+@item @code{K} --- reserved
-In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
-tells @value{GDBN} to set a breakpoint on the source line point is on.
+Reserved for future use.
-If you accidentally delete the source-display buffer, an easy way to get
-it back is to type the command @code{f} in the @value{GDBN} buffer, to
-request a frame display; when you run under Emacs, this recreates
-the source buffer if necessary to show you the context of the current
-frame.
+@item @code{l} --- reserved
-The source files displayed in Emacs are in ordinary Emacs buffers
-which are visiting the source files in the usual way. You can edit
-the files with these buffers if you wish; but keep in mind that @value{GDBN}
-communicates with Emacs in terms of line numbers. If you add or
-delete lines from the text, the line numbers that @value{GDBN} knows cease
-to correspond properly with the code.
+Reserved for future use.
-@c The following dropped because Epoch is nonstandard. Reactivate
-@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
-@ignore
-@kindex Emacs Epoch environment
-@kindex Epoch
-@kindex inspect
+@item @code{L} --- reserved
-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
+Reserved for future use.
-@include annotate.texi
-@include gdbmi.texinfo
+@item @code{m}@var{addr}@code{,}@var{length} --- read memory
+@cindex @code{m} packet
-@node GDB Bugs
-@chapter Reporting Bugs in @value{GDBN}
-@cindex bugs in @value{GDBN}
-@cindex reporting bugs in @value{GDBN}
+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.}
-Your bug reports play an essential role in making @value{GDBN} reliable.
+Reply:
+@table @samp
+@item @var{XX@dots{}}
+@var{XX@dots{}} 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 E@var{NN}
+@var{NN} is errno
+@end table
-Reporting a bug may help you by bringing a solution to your problem, or it
-may not. But in any case the principal function of a bug report is to help
-the entire community by making the next version of @value{GDBN} work better. Bug
-reports are your contribution to the maintenance of @value{GDBN}.
+@item @code{M}@var{addr},@var{length}@code{:}@var{XX@dots{}} --- write mem
+@cindex @code{M} packet
-In order for a bug report to serve its purpose, you must include the
-information that enables us to fix the bug.
+Write @var{length} bytes of memory starting at address @var{addr}.
+@var{XX@dots{}} is the data.
-@menu
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
-@end menu
+Reply:
+@table @samp
+@item OK
+for success
+@item E@var{NN}
+for an error (this includes the case where only part of the data was
+written).
+@end table
-@node Bug Criteria
-@section Have you found a bug?
-@cindex bug criteria
+@item @code{n} --- reserved
-If you are not sure whether you have found a bug, here are some guidelines:
+Reserved for future use.
-@itemize @bullet
-@cindex fatal signal
-@cindex debugger crash
-@cindex crash of debugger
-@item
-If the debugger gets a fatal signal, for any input whatever, that is a
-@value{GDBN} bug. Reliable debuggers never crash.
+@item @code{N} --- reserved
-@cindex error on valid input
-@item
-If @value{GDBN} produces an error message for valid input, that is a
-bug. (Note that if you're cross debugging, the problem may also be
-somewhere in the connection to the target.)
+Reserved for future use.
-@cindex invalid input
-@item
-If @value{GDBN} does not produce an error message for invalid input,
-that is a bug. However, you should note that your idea of
-``invalid input'' might be our idea of ``an extension'' or ``support
-for traditional practice''.
+@item @code{o} --- reserved
-@item
-If you are an experienced user of debugging tools, your suggestions
-for improvement of @value{GDBN} are welcome in any case.
-@end itemize
+Reserved for future use.
-@node Bug Reporting
-@section How to report bugs
-@cindex bug reports
-@cindex @value{GDBN} bugs, reporting
+@item @code{O} --- reserved
-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.
+Reserved for future use.
-You can find contact information for many support companies and
-individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
-distribution.
-@c should add a web page ref...
+@item @code{p}@var{n@dots{}} --- read reg @strong{(reserved)}
+@cindex @code{p} packet
-In any event, we also recommend that you send bug reports for
-@value{GDBN} to this addresses:
+@xref{write register packet}.
-@example
-bug-gdb@@gnu.org
-@end example
+Reply:
+@table @samp
+@item @var{r@dots{}.}
+The hex encoded value of the register in target byte order.
+@end table
-@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
-not want to receive bug reports. Those that do have arranged to receive
-@samp{bug-gdb}.
+@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register
+@anchor{write register packet}
+@cindex @code{P} packet
-The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
-serves as a repeater. The mailing list and the newsgroup carry exactly
-the same messages. Often people think of posting bug reports to the
-newsgroup instead of mailing them. This appears to work, but it has one
-problem which can be crucial: a newsgroup posting often lacks a mail
-path back to the sender. Thus, if we need to ask for more information,
-we may be unable to reach you. For this reason, it is better to send
-bug reports to the mailing list.
+Write register @var{n@dots{}} with value @var{r@dots{}}, which contains two hex
+digits for each byte in the register (target byte order).
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E@var{NN}
+for an error
+@end table
+
+@item @code{q}@var{query} --- general query
+@anchor{general query packet}
+@cindex @code{q} packet
+
+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.
+
+Reply:
+@table @samp
+@item @var{XX@dots{}}
+Hex encoded data from query. The reply can not be empty.
+@item E@var{NN}
+error reply
+@item
+Indicating an unrecognized @var{query}.
+@end table
+
+@item @code{Q}@var{var}@code{=}@var{val} --- general set
+@cindex @code{Q} packet
+
+Set value of @var{var} to @var{val}.
-As a last resort, send bug reports on paper to:
+@xref{general query packet}, for a discussion of naming conventions.
-@example
-@sc{gnu} Debugger Bugs
-Free Software Foundation Inc.
-59 Temple Place - Suite 330
-Boston, MA 02111-1307
-USA
-@end example
+@item @code{r} --- reset @strong{(deprecated)}
+@cindex @code{r} packet
-The fundamental principle of reporting bugs usefully is this:
-@strong{report all the facts}. If you are not sure whether to state a
-fact or leave it out, state it!
+Reset the entire system.
-Often people omit facts because they think they know what causes the
-problem and assume that some details do not matter. Thus, you might
-assume that the name of the variable you use in an example does not matter.
-Well, probably it does not, but one cannot be sure. Perhaps the bug is a
-stray memory reference which happens to fetch from the location where that
-name is stored in memory; perhaps, if the name were different, the contents
-of that location would fool the debugger into doing the right thing despite
-the bug. Play it safe and give a specific, complete example. That is the
-easiest thing for you to do, and the most helpful.
+@item @code{R}@var{XX} --- remote restart
+@cindex @code{R} packet
-Keep in mind that the purpose of a bug report is to enable us to fix the
-bug. It may be that the bug has been reported previously, but neither
-you nor we can know that unless your bug report is complete and
-self-contained.
+Restart the program being debugged. @var{XX}, while needed, is ignored.
+This packet is only available in extended mode.
-Sometimes people give a few sketchy facts and ask, ``Does this ring a
-bell?'' Those bug reports are useless, and we urge everyone to
-@emph{refuse to respond to them} except to chide the sender to report
-bugs properly.
+Reply:
+@table @samp
+@item @emph{no reply}
+The @samp{R} packet has no reply.
+@end table
-To enable us to fix the bug, you should include all these things:
+@item @code{s}@var{addr} --- step
+@cindex @code{s} packet
-@itemize @bullet
-@item
-The version of @value{GDBN}. @value{GDBN} announces it if you start
-with no arguments; you can also print it at any time using @code{show
-version}.
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+same address.
-Without this, we will not know whether there is any point in looking for
-the bug in the current version of @value{GDBN}.
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
-@item
-The type of machine you are using, and the operating system name and
-version number.
+@item @code{S}@var{sig}@code{;}@var{addr} --- step with signal
+@anchor{step with signal packet}
+@cindex @code{S} packet
-@item
-What compiler (and its version) was used to compile @value{GDBN}---e.g.
-``@value{GCC}--2.8.1''.
+Like @samp{C} but step not continue.
-@item
-What compiler (and its version) was used to compile the program you are
-debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
-C Compiler''. For GCC, you can say @code{gcc --version} to get this
-information; for other compilers, see the documentation for those
-compilers.
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
-@item
-The command arguments you gave the compiler to compile your example and
-observe the bug. For example, did you use @samp{-O}? To guarantee
-you will not omit something important, list them all. A copy of the
-Makefile (or the output from make) is sufficient.
+@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search
+@cindex @code{t} packet
-If we were to try to guess the arguments, we would probably guess wrong
-and then we might not encounter the bug.
+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
-A complete input script, and all necessary source files, that will
-reproduce the bug.
+@item @code{T}@var{XX} --- thread alive
+@cindex @code{T} packet
-@item
-A description of what behavior you observe that you believe is
-incorrect. For example, ``It gets a fatal signal.''
+Find out if the thread XX is alive.
-Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
-will certainly notice it. But if the bug is incorrect output, we might
-not notice unless it is glaringly wrong. You might as well not give us
-a chance to make a mistake.
+Reply:
+@table @samp
+@item OK
+thread is still alive
+@item E@var{NN}
+thread is dead
+@end table
-Even if the problem you experience is a fatal signal, you should still
-say so explicitly. Suppose something strange is going on, such as, your
-copy of @value{GDBN} is out of synch, or you have encountered a bug in
-the C library on your system. (This has happened!) Your copy might
-crash and ours would not. If you told us to expect a crash, then when
-ours fails to crash, we would know that the bug was not happening for
-us. If you had not told us to expect a crash, then we would not be able
-to draw any conclusion from our observations.
+@item @code{u} --- reserved
-@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
-it by context, not by line number.
+Reserved for future use.
-The line numbers in our development sources will not match those in your
-sources. Your line numbers would convey no useful information to us.
+@item @code{U} --- reserved
-@end itemize
+Reserved for future use.
-Here are some things that are not necessary:
+@item @code{v} --- reserved
-@itemize @bullet
-@item
-A description of the envelope of the bug.
+Reserved for future use.
-Often people who encounter a bug spend a lot of time investigating
-which changes to the input file will make the bug go away and which
-changes will not affect it.
+@item @code{V} --- reserved
-This is often time consuming and not very useful, because the way we
-will find the bug is by running a single example under the debugger
-with breakpoints, not by pure deduction from a series of examples.
-We recommend that you save your time for something else.
+Reserved for future use.
-Of course, if you can find a simpler example to report @emph{instead}
-of the original one, that is a convenience for us. Errors in the
-output will be easier to spot, running under the debugger will take
-less time, and so on.
+@item @code{w} --- reserved
-However, simplification is not vital; if you do not want to do this,
-report the bug anyway and send us the entire test case you used.
+Reserved for future use.
-@item
-A patch for the bug.
+@item @code{W} --- reserved
-A patch for the bug does help us if it is a good one. But do not omit
-the necessary information, such as the test case, on the assumption that
-a patch is all we need. We might see problems with your patch and decide
-to fix the problem another way, or we might not understand it at all.
+Reserved for future use.
-Sometimes with a program as complicated as @value{GDBN} it is very hard to
-construct an example that will make the program follow a certain path
-through the code. If you do not send us the example, we will not be able
-to construct one, so we will not be able to verify that the bug is fixed.
+@item @code{x} --- reserved
-And if we cannot understand what bug you are trying to fix, or why your
-patch should be an improvement, we will not install it. A test case will
-help us to understand.
+Reserved for future use.
-@item
-A guess about what the bug is or what it depends on.
+@item @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX@dots{}} --- write mem (binary)
+@cindex @code{X} packet
-Such guesses are usually wrong. Even we cannot guess right about such
-things without first using the debugger to find the facts.
-@end itemize
+@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}}
+is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
+escaped using @code{0x7d}.
-@c The readline documentation is distributed with the readline code
-@c and consists of the two following files:
-@c rluser.texinfo
-@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.texinfo
+Reply:
+@table @samp
+@item OK
+for success
+@item E@var{NN}
+for an error
+@end table
+@item @code{y} --- reserved
-@node Formatting Documentation
-@appendix Formatting Documentation
+Reserved for future use.
-@cindex @value{GDBN} reference card
-@cindex reference card
-The @value{GDBN} 4 release includes an already-formatted reference card, ready
-for printing with PostScript or Ghostscript, in the @file{gdb}
-subdirectory of the main source directory@footnote{In
-@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
-release.}. If you can use PostScript or Ghostscript with your printer,
-you can print the reference card immediately with @file{refcard.ps}.
+@item @code{Y} reserved
-The release also includes the source for the reference card. You
-can format it, using @TeX{}, by typing:
+Reserved for future use.
-@example
-make refcard.dvi
-@end example
+@item @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length} --- remove break or watchpoint @strong{(draft)}
+@cindex @code{z} packet
-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.
+@xref{insert breakpoint or watchpoint packet}.
-@cindex documentation
+@item @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length} --- insert break or watchpoint @strong{(draft)}
+@anchor{insert breakpoint or watchpoint packet}
+@cindex @code{Z} packet
-All the documentation for @value{GDBN} comes as part of the machine-readable
-distribution. The documentation is written in Texinfo format, which is
-a documentation system that uses a single source file to produce both
-on-line information and a printed manual. You can use one of the Info
-formatting commands to create the on-line version of the documentation
-and @TeX{} (or @code{texi2roff}) to typeset the printed version.
+@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.
-@value{GDBN} includes an already formatted copy of the on-line Info
-version of this manual in the @file{gdb} subdirectory. The main Info
-file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
-subordinate files matching @samp{gdb.info*} in the same directory. If
-necessary, you can print out these files, or read them with any editor;
-but they are easier to read using the @code{info} subsystem in @sc{gnu}
-Emacs or the standalone @code{info} program, available as part of the
-@sc{gnu} Texinfo distribution.
+Reply:
+@table @samp
+@item E@var{NN}
+for an error
+@item OK
+for success
+@item @samp{}
+If not supported.
+@end table
-If you want to format these Info files yourself, you need one of the
-Info formatting programs, such as @code{texinfo-format-buffer} or
-@code{makeinfo}.
+@end table
-If you have @code{makeinfo} installed, and are in the top level
-@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
-version @value{GDBVN}), you can make the Info file by typing:
+@node Stop Reply Packets
+@section Stop Reply Packets
+@cindex stop reply packets
-@example
-cd gdb
-make gdb.info
-@end example
+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.
-If you want to typeset and print copies of this manual, you need @TeX{},
-a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
-Texinfo definitions file.
+@table @samp
-@TeX{} is a typesetting program; it does not print files directly, but
-produces output files called @sc{dvi} files. To print a typeset
-document, you need a program to print @sc{dvi} files. If your system
-has @TeX{} installed, chances are it has such a program. The precise
-command to use depends on your system; @kbd{lpr -d} is common; another
-(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
-require a file name without any extension or a @samp{.dvi} extension.
+@item S@var{AA}
+@var{AA} is the signal number
-@TeX{} also requires a macro definitions file called
-@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
-written in Texinfo format. On its own, @TeX{} cannot either read or
-typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
-and is located in the @file{gdb-@var{version-number}/texinfo}
-directory.
+@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
+@cindex @code{T} packet reply
-If you have @TeX{} and a @sc{dvi} printer program installed, you can
-typeset and print this manual. First switch to the the @file{gdb}
-subdirectory of the main source directory (for example, to
-@file{gdb-@value{GDBVN}/gdb}) and type:
+@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...} = (@samp{watch} |
+@samp{rwatch} | @samp{awatch}, @var{r...} = data address, 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.
-@example
-make gdb.dvi
-@end example
+@item W@var{AA}
-Then give @file{gdb.dvi} to your @sc{dvi} printing program.
+The process exited, and @var{AA} is the exit status. This is only
+applicable to certain targets.
-@node Installing GDB
-@appendix Installing @value{GDBN}
-@cindex configuring @value{GDBN}
-@cindex installation
+@item X@var{AA}
-@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.
-@iftex
-@c irrelevant in info file; it's as current as the code it lives with.
-@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
-look at the @file{README} file in the sources; we may have improved the
-installation procedures since publishing this manual.}
-@end iftex
+The process terminated with signal @var{AA}.
-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}.
+@item N@var{AA};@var{t@dots{}};@var{d@dots{}};@var{b@dots{}} @strong{(obsolete)}
-For example, the @value{GDBN} version @value{GDBVN} distribution is in the
-@file{gdb-@value{GDBVN}} directory. That directory contains:
+@var{AA} = signal number; @var{t@dots{}} = address of symbol
+@code{_start}; @var{d@dots{}} = base of data section; @var{b@dots{}} =
+base of bss section. @emph{Note: only used by Cisco Systems targets.
+The difference between this reply and the @samp{qOffsets} query is that
+the @samp{N} packet may arrive spontaneously whereas the @samp{qOffsets}
+is a query initiated by the host debugger.}
-@table @code
-@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
-script for configuring @value{GDBN} and all its supporting libraries
+@item O@var{XX@dots{}}
-@item gdb-@value{GDBVN}/gdb
-the source specific to @value{GDBN} itself
+@var{XX@dots{}} 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 @samp{W}, @samp{T}, etc.
-@item gdb-@value{GDBVN}/bfd
-source for the Binary File Descriptor library
+@end table
-@item gdb-@value{GDBVN}/include
-@sc{gnu} include files
+@node General Query Packets
+@section General Query Packets
-@item gdb-@value{GDBVN}/libiberty
-source for the @samp{-liberty} free software library
+The following set and query packets have already been defined.
-@item gdb-@value{GDBVN}/opcodes
-source for the library of opcode tables and disassemblers
+@table @r
-@item gdb-@value{GDBVN}/readline
-source for the @sc{gnu} command-line interface
+@item @code{q}@code{C} --- current thread
-@item gdb-@value{GDBVN}/glob
-source for the @sc{gnu} filename pattern-matching subroutine
+Return the current thread id.
-@item gdb-@value{GDBVN}/mmalloc
-source for the @sc{gnu} memory-mapped malloc package
+Reply:
+@table @samp
+@item @code{QC}@var{pid}
+Where @var{pid} is a HEX encoded 16 bit process id.
+@item *
+Any other reply implies the old pid.
@end table
-The simplest way to configure and build @value{GDBN} is to run @code{configure}
-from the @file{gdb-@var{version-number}} source directory, which in
-this example is the @file{gdb-@value{GDBVN}} directory.
+@item @code{q}@code{fThreadInfo} -- all thread ids
+
+@code{q}@code{sThreadInfo}
+
+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.
-First switch to the @file{gdb-@var{version-number}} source directory
-if you are not already in it; then run @code{configure}. Pass the
-identifier for the platform on which @value{GDBN} will run as an
-argument.
+NOTE: replaces the @code{qL} query (see below).
-For example:
+Reply:
+@table @samp
+@item @code{m}@var{id}
+A single thread id
+@item @code{m}@var{id},@var{id}@dots{}
+a comma-separated list of thread ids
+@item @code{l}
+(lower case 'el') denotes end of list.
+@end table
-@example
-cd gdb-@value{GDBVN}
-./configure @var{host}
-make
-@end example
+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. @value{GDBN}
+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'}).
-@noindent
-where @var{host} is an identifier such as @samp{sun4} or
-@samp{decstation}, that identifies the platform where @value{GDBN} will run.
-(You can often leave off @var{host}; @code{configure} tries to guess the
-correct value by examining your system.)
+@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info
+
+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''.
+
+Reply:
+@table @samp
+@item @var{XX@dots{}}
+Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising
+the printable string containing the extra information about the thread's
+attributes.
+@end table
-Running @samp{configure @var{host}} and then running @code{make} builds the
-@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
-libraries, then @code{gdb} itself. The configured source files, and the
-binaries, are left in the corresponding source directories.
+@item @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} --- query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
-@need 750
-@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
-system does not recognize this automatically when you run a different
-shell, you may need to run @code{sh} on it explicitly:
+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}.
-@example
-sh configure @var{host}
-@end example
+NOTE: this query is replaced by the @code{q}@code{fThreadInfo} query
+(see above).
-If you run @code{configure} from a directory that contains source
-directories for multiple libraries or programs, such as the
-@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
-creates configuration files for every directory level underneath (unless
-you tell it not to, with the @samp{--norecursion} option).
+Reply:
+@table @samp
+@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}}
+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@dots{}}
+is a sequence of thread IDs from the target. @var{threadid} (eight hex
+digits). See @code{remote.c:parse_threadlist_response()}.
+@end table
-You can run the @code{configure} script from any of the
-subordinate directories in the @value{GDBN} distribution if you only want to
-configure that subdirectory, but be sure to specify a path to it.
+@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block
-For example, with version @value{GDBVN}, type the following to configure only
-the @code{bfd} subdirectory:
+Reply:
+@table @samp
+@item @code{E}@var{NN}
+An error (such as memory fault)
+@item @code{C}@var{CRC32}
+A 32 bit cyclic redundancy check of the specified memory region.
+@end table
-@example
-@group
-cd gdb-@value{GDBVN}/bfd
-../configure @var{host}
-@end group
-@end example
+@item @code{q}@code{Offsets} --- query sect offs
-You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
-However, you should make sure that the shell on your path (named by
-the @samp{SHELL} environment variable) is publicly readable. Remember
-that @value{GDBN} uses the shell to start your program---some systems refuse to
-let @value{GDBN} debug child processes whose programs are not readable.
+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.}
-@menu
-* Separate Objdir:: Compiling @value{GDBN} in another directory
-* Config Names:: Specifying names for hosts and targets
-* Configure Options:: Summary of options for configure
-@end menu
+Reply:
+@table @samp
+@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
+@end table
-@node Separate Objdir
-@section Compiling @value{GDBN} in another directory
+@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request
-If you want to run @value{GDBN} versions for several host or target machines,
-you need a different @code{gdb} compiled for each combination of
-host and target. @code{configure} is designed to make this easy by
-allowing you to generate each configuration in a separate subdirectory,
-rather than in the source directory. If your @code{make} program
-handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
-@code{make} in each of these directories builds the @code{gdb}
-program specified there.
+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.
-To build @code{gdb} in a separate directory, run @code{configure}
-with the @samp{--srcdir} option to specify where to find the source.
-(You also need to specify a path to find @code{configure}
-itself from your working directory. If the path to @code{configure}
-would be the same as the argument to @samp{--srcdir}, you can leave out
-the @samp{--srcdir} option; it is assumed.)
+Reply:
+@table @samp
+@item *
+@end table
-For example, with version @value{GDBVN}, you can build @value{GDBN} in a
-separate directory for a Sun 4 like this:
+See @code{remote.c:remote_unpack_thread_info_response()}.
-@example
-@group
-cd gdb-@value{GDBVN}
-mkdir ../gdb-sun4
-cd ../gdb-sun4
-../gdb-@value{GDBVN}/configure sun4
-make
-@end group
-@end example
+@item @code{q}@code{Rcmd,}@var{command} --- remote command
-When @code{configure} builds a configuration using a remote source
-directory, it creates a tree for the binaries with the same structure
-(and using the same names) as the tree under the source directory. In
-the example, you'd find the Sun 4 library @file{libiberty.a} in the
-directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
-@file{gdb-sun4/gdb}.
+@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}.
-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}).
-You specify a cross-debugging target by
-giving the @samp{--target=@var{target}} option to @code{configure}.
+Reply:
+@table @samp
+@item OK
+A command response with no output.
+@item @var{OUTPUT}
+A command response with the hex encoded output string @var{OUTPUT}.
+@item @code{E}@var{NN}
+Indicate a badly formed request.
+@item @samp{}
+When @samp{q}@samp{Rcmd} is not recognized.
+@end table
-When you run @code{make} to build a program or library, you must run
-it in a configured directory---whatever directory you were in when you
-called @code{configure} (or one of its subdirectories).
+@item @code{qSymbol::} --- symbol lookup
-The @code{Makefile} that @code{configure} generates in each source
-directory also runs recursively. If you type @code{make} in a source
-directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
-directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
-will build all the required libraries, and then build GDB.
+Notify the target that @value{GDBN} is prepared to serve symbol lookup
+requests. Accept requests from the target for the values of symbols.
-When you have multiple hosts or targets configured in separate
-directories, you can run @code{make} on them in parallel (for example,
-if they are NFS-mounted on each of the hosts); they will not interfere
-with each other.
+Reply:
+@table @samp
+@item @code{OK}
+The target does not need to look up any (more) symbols.
+@item @code{qSymbol:}@var{sym_name}
+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.
+@end table
-@node Config Names
-@section Specifying names for hosts and targets
+@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value
-The specifications used for hosts and targets in the @code{configure}
-script are based on a three-part naming scheme, but some short predefined
-aliases are also supported. The full naming scheme encodes three pieces
-of information in the following pattern:
+Set the value of @var{sym_name} to @var{sym_value}.
-@example
-@var{architecture}-@var{vendor}-@var{os}
-@end example
+@var{sym_name} (hex encoded) is the name of a symbol whose value the
+target has previously requested.
-For example, you can use the alias @code{sun4} as a @var{host} argument,
-or as the value for @var{target} in a @code{--target=@var{target}}
-option. The equivalent full name is @samp{sparc-sun-sunos4}.
+@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.
-The @code{configure} script accompanying @value{GDBN} does not provide
-any query facility to list all supported host and target names or
-aliases. @code{configure} calls the Bourne shell script
-@code{config.sub} to map abbreviations to full names; you can read the
-script, if you wish, or you can use it to test your guesses on
-abbreviations---for example:
+Reply:
+@table @samp
+@item @code{OK}
+The target does not need to look up any (more) symbols.
+@item @code{qSymbol:}@var{sym_name}
+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 table
-@smallexample
-% sh config.sub i386-linux
-i386-pc-linux-gnu
-% sh config.sub alpha-linux
-alpha-unknown-linux-gnu
-% sh config.sub hp9k700
-hppa1.1-hp-hpux
-% sh config.sub sun4
-sparc-sun-sunos4.1.1
-% sh config.sub sun3
-m68k-sun-sunos4.1.1
-% sh config.sub i986v
-Invalid configuration `i986v': machine `i986v' not recognized
-@end smallexample
+@end table
-@noindent
-@code{config.sub} is also distributed in the @value{GDBN} source
-directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
+@node Register Packet Format
+@section Register Packet Format
-@node Configure Options
-@section @code{configure} options
+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.
-Here is a summary of the @code{configure} options and arguments that
-are most often useful for building @value{GDBN}. @code{configure} also has
-several other options not listed here. @inforef{What Configure
-Does,,configure.info}, for a full explanation of @code{configure}.
+@table @r
-@example
-configure @r{[}--help@r{]}
- @r{[}--prefix=@var{dir}@r{]}
- @r{[}--exec-prefix=@var{dir}@r{]}
- @r{[}--srcdir=@var{dirname}@r{]}
- @r{[}--norecursion@r{]} @r{[}--rm@r{]}
- @r{[}--target=@var{target}@r{]}
- @var{host}
-@end example
+@item MIPS32
-@noindent
-You may introduce options with a single @samp{-} rather than
-@samp{--} if you prefer; but you may abbreviate option names if you use
-@samp{--}.
+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.
-@table @code
-@item --help
-Display a quick summary of how to invoke @code{configure}.
+@item MIPS64
-@item --prefix=@var{dir}
-Configure the source to install programs and files under directory
-@file{@var{dir}}.
+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}.
-@item --exec-prefix=@var{dir}
-Configure the source to install programs under directory
-@file{@var{dir}}.
+@end table
-@c avoid splitting the warning from the explanation:
-@need 2000
-@item --srcdir=@var{dirname}
-@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
-@code{make} that implements the @code{VPATH} feature.}@*
-Use this option to make configurations in directories separate from the
-@value{GDBN} source directories. Among other things, you can use this to
-build (or maintain) several configurations simultaneously, in separate
-directories. @code{configure} writes configuration specific files in
-the current directory, but arranges for them to use the source in the
-directory @var{dirname}. @code{configure} creates directories under
-the working directory in parallel to the source directories below
-@var{dirname}.
+@node Examples
+@section Examples
-@item --norecursion
-Configure only the directory level where @code{configure} is executed; do not
-propagate configuration to subdirectories.
+Example sequence of a target being re-started. Notice how the restart
+does not get any direct output:
-@item --target=@var{target}
-Configure @value{GDBN} for cross-debugging programs running on the specified
-@var{target}. Without this option, @value{GDBN} is configured to debug
-programs that run on the same machine (@var{host}) as @value{GDBN} itself.
+@smallexample
+-> @code{R00}
+<- @code{+}
+@emph{target restarts}
+-> @code{?}
+<- @code{+}
+<- @code{T001:1234123412341234}
+-> @code{+}
+@end smallexample
-There is no convenient way to generate a list of all available targets.
+Example sequence of a target being stepped by a single instruction:
-@item @var{host} @dots{}
-Configure @value{GDBN} to run on the specified @var{host}.
+@smallexample
+-> @code{G1445@dots{}}
+<- @code{+}
+-> @code{s}
+<- @code{+}
+@emph{time passes}
+<- @code{T001:1234123412341234}
+-> @code{+}
+-> @code{g}
+<- @code{+}
+<- @code{1455@dots{}}
+-> @code{+}
+@end smallexample
-There is no convenient way to generate a list of all available hosts.
-@end table
+@include gpl.texi
-There are many other options available as well, but they are generally
-needed for special purposes only.
+@include fdl.texi
@node Index
@unnumbered Index
% 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