\input texinfo @c -*-texinfo-*-
@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001
+@c 1999, 2000, 2001, 2002
@c Free Software Foundation, Inc.
@c
@c %**start of header
@set EDITION Ninth
@c !!set GDB manual's revision date
-@set DATE April 2001
+@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,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
- 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 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 ``A Sample GDB Session'' and ``Free
-Software'', with the Front-Cover texts being ``A GNU Manual,'' and
-with the Back-Cover Texts as in (a) below.
-
-(a) The FSF'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.''
+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 ifinfo
@titlepage
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
- 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, @*
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 ``A Sample GDB Session'' and ``Free
-Software'', with the Front-Cover texts being ``A GNU Manual,'' and
-with the Back-Cover Texts as in (a) below.
-
-(a) The FSF'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.''
+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-2001 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
+* 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}
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.0 and 5.1);
Jim Blandy (release 4.18);
Jason Molenda (release 4.17);
Stan Shebs (release 4.14);
Richard Stallman, assisted at various times by Peter TerMaat, Chris
Hanson, and Richard Mlynarik, handled releases through 2.8.
-Michael Tiemann is the author of most of the @sc{gnu} C++ support in
-@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
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
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.
@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); a list of signal numberss of the form
+@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
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
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
* Memory Region Attributes:: Memory region attributes
+* Dump/Restore Files:: Copy between memory and a file
@end menu
@node Expressions
@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
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.
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,
@end table
@node Memory Region Attributes
-@section Memory Region Attributes
+@section Memory region attributes
@cindex memory region attributes
@dfn{Memory region attributes} allow you to describe special handling
@table @code
@kindex mem
-@item mem @var{address1} @var{address1} @var{attributes}@dots{}
+@item mem @var{address1} @var{address2} @var{attributes}@dots{}
Define memory region bounded by @var{address1} and @var{address2}
with attributes @var{attributes}@dots{}.
@kindex delete mem
@item delete mem @var{nums}@dots{}
-Remove memory region numbers @var{nums}.
+Remove memory regions @var{nums}@dots{}.
@kindex disable mem
@item disable mem @var{nums}@dots{}
-Disable memory region numbers @var{nums}.
+Disable memory regions @var{nums}@dots{}.
A disabled memory region is not forgotten.
It may be enabled again later.
@kindex enable mem
@item enable mem @var{nums}@dots{}
-Enable memory region numbers @var{nums}.
+Enable memory regions @var{nums}@dots{}.
@kindex info mem
@item info mem
@item wo
Memory is write only.
@item rw
-Memory is read/write (default).
+Memory is read/write. This is the default.
@end table
@subsubsection Memory Access Size
@table @code
@item cache
Enable @value{GDBN} to cache target memory.
-@item nocache (default)
-Disable @value{GDBN} from caching target memory.
+@item nocache
+Disable @value{GDBN} from caching target memory. This is the default.
@end table
@c @subsubsection Memory Write Verification
@c @item noverify (default)
@c @end table
-@node Languages
-@chapter Using @value{GDBN} with Different Languages
-@cindex languages
-
-Although programming languages generally have common aspects, they are
-rarely expressed in the same manner. For instance, in ANSI C,
-dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
-Modula-2, it is accomplished by @code{p^}. Values can also be
-represented (and displayed) differently. Hex numbers in C appear as
-@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
-
-@cindex working language
-Language-specific information is built into @value{GDBN} for some languages,
-allowing you to express operations like the above in your program's
-native language, and allowing @value{GDBN} to output values in a manner
-consistent with the syntax of your program's native language. The
-language you use to build expressions is called the @dfn{working
-language}.
+@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 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
-* Setting:: Switching between source languages
-* Show:: Displaying the language
-* Checks:: Type and range checks
-* Support:: Supported languages
+* Set Tracepoints::
+* Analyze Collected Data::
+* Tracepoint Variables::
@end menu
-@node Setting
-@section Switching between source languages
+@node Set Tracepoints
+@section Commands to Set Tracepoints
-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.
+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.
-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}.
+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 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.
+This section describes commands to set tracepoints and associated
+conditions and actions.
@menu
-* Filenames:: Filename extensions and languages.
-* Manually:: Setting the working language manually
-* Automatically:: Having @value{GDBN} infer the source language
+* Create and Delete Tracepoints::
+* Enable and Disable Tracepoints::
+* Tracepoint Passcounts::
+* Tracepoint Actions::
+* Listing Tracepoints::
+* Starting and Stopping Trace Experiment::
@end menu
-@node Filenames
-@subsection List of filename extensions and languages
+@node Create and Delete Tracepoints
+@subsection Create and Delete Tracepoints
-If a source file name ends in one of the following extensions, then
-@value{GDBN} infers that its language is the one indicated.
+@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.
-@table @file
+Here are some examples of using the @code{trace} command:
-@item .c
-C source file
+@smallexample
+(@value{GDBP}) @b{trace foo.c:121} // a source file and line number
-@item .C
-@itemx .cc
-@itemx .cp
-@itemx .cpp
-@itemx .cxx
-@itemx .c++
-C++ source file
+(@value{GDBP}) @b{trace +2} // 2 lines forward
-@item .f
-@itemx .F
-Fortran source file
+(@value{GDBP}) @b{trace my_function} // first source line of function
-@item .ch
-@itemx .c186
-@itemx .c286
-CHILL source file
+(@value{GDBP}) @b{trace *my_function} // EXACT start address of function
-@item .mod
-Modula-2 source file
+(@value{GDBP}) @b{trace *0x2117c4} // an address
+@end smallexample
-@item .s
-@itemx .S
-Assembler source file. This actually behaves almost like C, but
-@value{GDBN} does not skip over function prologues when stepping.
+@noindent
+You can abbreviate @code{trace} as @code{tr}.
+
+@vindex $tpnum
+@cindex last tracepoint number
+@cindex recent tracepoint number
+@cindex tracepoint number
+The convenience variable @code{$tpnum} records the tracepoint number
+of the most recently set tracepoint.
+
+@kindex 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.
+
+Examples:
+
+@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
-In addition, you may set the language associated with a filename
-extension. @xref{Show, , Displaying the language}.
+@node Enable and Disable Tracepoints
+@subsection Enable and Disable Tracepoints
-@node Manually
-@subsection Setting the working language
+@table @code
+@kindex disable tracepoint
+@item disable tracepoint @r{[}@var{num}@r{]}
+Disable tracepoint @var{num}, or all tracepoints if no argument
+@var{num} is given. A disabled tracepoint will have no effect during
+the next trace experiment, but it is not forgotten. You can re-enable
+a disabled tracepoint using the @code{enable tracepoint} command.
-If you allow @value{GDBN} to set the language automatically,
-expressions are interpreted the same way in your debugging session and
-your program.
+@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
-@kindex set language
-If you wish, you may set the language manually. To do this, issue the
-command @samp{set language @var{lang}}, where @var{lang} is the name of
-a language, such as
-@code{c} or @code{modula-2}.
-For a list of the supported languages, type @samp{set language}.
+@node Tracepoint Passcounts
+@subsection Tracepoint Passcounts
-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:
+@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.
-@example
-print a = b + c
-@end example
+Examples:
-@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.
+@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
-@node Automatically
-@subsection Having @value{GDBN} infer the source language
+@node Tracepoint Actions
+@subsection Tracepoint Action Lists
-To have @value{GDBN} set the working language automatically, use
-@samp{set language local} or @samp{set language auto}. @value{GDBN}
-then infers the working language. That is, when your program stops in a
-frame (usually by encountering a breakpoint), @value{GDBN} sets the
-working language to the language recorded for the function in that
-frame. If the language for a frame is unknown (that is, if the function
-or block corresponding to the frame was defined in a source file that
-does not have a recognized extension), the current working language is
-not changed, and @value{GDBN} issues a warning.
+@table @code
+@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}.
-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.
+@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}.
-@node Show
-@section Displaying the language
+@smallexample
+(@value{GDBP}) @b{collect @var{data}} // collect some data
-The following commands help you find out which language is the
-working language, and also what language source files were written in.
+(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
+
+(@value{GDBP}) @b{end} // signals the end of actions.
+@end smallexample
+
+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.
+
+@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
+
+@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:
-@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 $regs
+collect all registers
-@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 $args
+collect all function arguments
-@item info source
-Display the source language of this source file.
-@xref{Symbols, ,Examining the Symbol Table}, to identify the other
-information listed here.
+@item $locals
+collect all local variables.
@end table
-In unusual circumstances, you may have source files with extensions
-not in the standard list. You can then set the extension associated
-with a language explicitly:
+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.
+
+The command @code{info scope} (@pxref{Symbols, info scope}) is
+particularly useful for figuring out what data to collect.
+
+@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):
+
+@smallexample
+> while-stepping 12
+ > collect $regs, myglobal
+ > end
+>
+@end smallexample
+
+@noindent
+You may abbreviate @code{while-stepping} as @code{ws} or
+@code{stepping}.
+@end table
+
+@node Listing Tracepoints
+@subsection Listing Tracepoints
-@kindex set extension-language
-@kindex info extensions
@table @code
-@item set extension-language @var{.ext} @var{language}
-Set source files with extension @var{.ext} to be assumed to be in
-the source language @var{language}.
+@kindex info tracepoints
+@cindex information about tracepoints
+@item info tracepoints @r{[}@var{num}@r{]}
+Display information about the tracepoint @var{num}. If you don't specify
+a tracepoint number, displays information about all the tracepoints
+defined so far. For each tracepoint, the following information is
+shown:
-@item info extensions
-List all the filename extensions and the associated languages.
+@itemize @bullet
+@item
+its number
+@item
+whether it is enabled or disabled
+@item
+its address
+@item
+its passcount as given by the @code{passcount @var{n}} command
+@item
+its step count as given by the @code{while-stepping @var{n}} command
+@item
+where in the source files is the tracepoint set
+@item
+its action list as given by the @code{actions} command
+@end itemize
+
+@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
+This command can be abbreviated @code{info tp}.
@end table
-@node Checks
-@section Type and range checking
+@node Starting and Stopping Trace Experiment
+@subsection Starting and Stopping Trace Experiment
-@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
+@table @code
+@kindex tstart
+@cindex start a new trace experiment
+@cindex collected data discarded
+@item tstart
+This command takes no arguments. It starts the trace experiment, and
+begins collecting data. This has the side effect of discarding all
+the data collected in the trace buffer during the previous trace
+experiment.
-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.
+@kindex tstop
+@cindex stop a running trace experiment
+@item tstop
+This command takes no arguments. It ends the trace experiment, and
+stops collecting data.
+
+@strong{Note:} a trace experiment and data collection may stop
+automatically if any tracepoint's passcount is reached
+(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
+
+@kindex tstatus
+@cindex status of trace data collection
+@cindex trace experiment, status of
+@item tstatus
+This command displays the status of the current trace data
+collection.
+@end table
+
+Here is an example of the commands we described so far:
+
+@smallexample
+(@value{GDBP}) @b{trace gdb_c_test}
+(@value{GDBP}) @b{actions}
+Enter actions for tracepoint #1, one per line.
+> collect $regs,$locals,$args
+> while-stepping 11
+ > collect $regs
+ > end
+> end
+(@value{GDBP}) @b{tstart}
+ [time passes @dots{}]
+(@value{GDBP}) @b{tstop}
+@end smallexample
-@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 Analyze Collected Data
+@section Using the collected data
+
+After the tracepoint experiment ends, you use @value{GDBN} commands
+for examining the trace data. The basic idea is that each tracepoint
+collects a trace @dfn{snapshot} every time it is hit and another
+snapshot every time it single-steps. All these snapshots are
+consecutively numbered from zero and go into a buffer, and you can
+examine them later. The way you examine them is to @dfn{focus} on a
+specific trace snapshot. When the remote stub is focused on a trace
+snapshot, it will respond to all @value{GDBN} requests for memory and
+registers by reading from the buffer which belongs to that snapshot,
+rather than from @emph{real} memory or registers of the program being
+debugged. This means that @strong{all} @value{GDBN} commands
+(@code{print}, @code{info registers}, @code{backtrace}, etc.) will
+behave as if we were currently debugging the program state as it was
+when the tracepoint occurred. Any requests for data that are not in
+the buffer will fail.
@menu
-* Type Checking:: An overview of type checking
-* Range Checking:: An overview of range checking
+* 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
-@cindex type checking
-@cindex checks, type
-@node Type Checking
-@subsection An overview of type checking
+@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:
-Some languages, such as Modula-2, are strongly typed, meaning that the
-arguments to operators and functions have to be of the correct type,
-otherwise an error occurs. These checks prevent type mismatch
-errors from ever causing any run-time problems. For example,
+@smallexample
+(@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
+
+Or, if we want to examine the variable @code{X} at each source line in
+the buffer:
@smallexample
-1 + 2 @result{} 3
-@exdent but
-@error{} 1 + 2.3
+(@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
-The second example fails because the @code{CARDINAL} 1 is not
-type-compatible with the @code{REAL} 2.3.
+@node tdump
+@subsection @code{tdump}
+@kindex tdump
+@cindex dump all data collected at tracepoint
+@cindex tracepoint data, display
-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.
+This command takes no arguments. It prints all the data collected at
+the current trace snapshot.
-Even if you turn type checking off, there may be other reasons
-related to type that prevent @value{GDBN} from evaluating an expression.
-For instance, @value{GDBN} does not know how to add an @code{int} and
-a @code{struct foo}. These particular type errors have nothing to do
-with the language in use, and usually arise from expressions, such as
-the one described above, which make little sense to evaluate anyway.
+@smallexample
+(@value{GDBP}) @b{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'
-Each language defines to what degree it is strict about type. For
-instance, both Modula-2 and C require the arguments to arithmetical
-operators to be numbers. In C, enumerated types and pointers can be
-represented as numbers, so that they are valid arguments to mathematical
-operators. @xref{Support, ,Supported languages}, for further
-details on specific languages.
+(@value{GDBP})
+@end smallexample
-@value{GDBN} provides some additional commands for controlling the type checker:
+@node save-tracepoints
+@subsection @code{save-tracepoints @var{filename}}
+@kindex save-tracepoints
+@cindex save tracepoints for future sessions
+
+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}).
+
+@node Tracepoint Variables
+@section Convenience Variables for Tracepoints
+@cindex tracepoint variables
+@cindex convenience variables for 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.
+@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 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.
+@vindex $tracepoint
+@item (int) $tracepoint
+The tracepoint for the current trace snapshot.
-@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.
+@vindex $trace_line
+@item (int) $trace_line
+The line number for the current trace snapshot.
-@item show type
-Show the current setting of the type checker, and whether or not @value{GDBN}
-is setting it automatically.
-@end table
+@vindex $trace_file
+@item (char []) $trace_file
+The source file for the current trace snapshot.
-@cindex range checking
-@cindex checks, range
-@node Range Checking
-@subsection An overview of range checking
+@vindex $trace_func
+@item (char []) $trace_func
+The name of the function containing @code{$tracepoint}.
+@end table
-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.
+Note: @code{$trace_file} is not suitable for use in @code{printf},
+use @code{output} instead.
-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.
+Here's a simple example of using these convenience variables for
+stepping through all the trace snapshots and printing some of their
+data.
-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{tfind start}
-@example
-@var{m} + 1 @result{} @var{s}
-@end example
+(@value{GDBP}) @b{while $trace_frame != -1}
+> output $trace_file
+> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
+> tfind
+> end
+@end smallexample
-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.
+@node Overlays
+@chapter Debugging Programs That Use Overlays
+@cindex overlays
-@value{GDBN} provides some additional commands for controlling the range checker:
-
-@kindex set check@r{, range}
-@kindex set check range
-@kindex show check range
-@table @code
-@item set check range auto
-Set range checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
-each language.
-
-@item set check range on
-@itemx set check range off
-Set range checking on or off, overriding the default setting for the
-current working language. A warning is issued if the setting does not
-match the language default. If a range error occurs and range checking is on,
-then a message is printed and evaluation of the expression is aborted.
-
-@item set check range warn
-Output messages when the @value{GDBN} range checker detects a range error,
-but attempt to evaluate the expression anyway. Evaluating the
-expression may still be impossible for other reasons, such as accessing
-memory that the process does not own (a typical example from many Unix
-systems).
-
-@item show range
-Show the current setting of the range checker, and whether or not it is
-being set automatically by @value{GDBN}.
-@end table
-
-@node Support
-@section Supported languages
-
-@value{GDBN} supports C, C++, 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.
+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:: C and C++
-* Modula-2:: Modula-2
-* Chill:: Chill
+* 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
-@subsection C and C++
+@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++
-@cindex expressions in C or C++
+@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
-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.
+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:
-@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}).
+@itemize @bullet
-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.
+@item
+Before calling or returning to a function in an overlay, your program
+must make sure that overlay is actually mapped. Otherwise, the call or
+return will transfer control to the right address, but in the wrong
+overlay, and your program will probably crash.
-@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
+@item
+If the process of mapping an overlay is expensive on your system, you
+will need to choose your overlays carefully to minimize their effect on
+your program's performance.
-@node C Operators
-@subsubsection C and C++ operators
+@item
+The executable file you load onto your system must contain each
+overlay's instructions, appearing at the overlay's load address, not its
+mapped address. However, each overlay's instructions must be relocated
+and its symbols defined as if the overlay were at its mapped address.
+You can use GNU linker scripts to specify different load and relocation
+addresses for pieces of your program; see @ref{Overlay Description,,,
+ld.info, Using ld: the GNU linker}.
-@cindex C and C++ operators
+@item
+The procedure for loading executable files onto your system must be able
+to load their contents into the larger address space as well as the
+instruction and data spaces.
-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.
+@end itemize
-For the purposes of C and C++, the following definitions hold:
+The overlay system described above is rather simple, and could be
+improved in many ways:
@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}.
-
-@item
-@emph{Floating-point types} include @code{float}, @code{double}, and
-@code{long double} (if supported by the target platform).
+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
-@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
+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
-@emph{Scalar types} include all of the above.
+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
-@noindent
-The following operators are supported. They are listed here
-in order of increasing precedence:
-
-@table @code
-@item ,
-The comma or sequencing operator. Expressions in a comma-separated list
-are evaluated from left to right, with the result of the entire
-expression being the last expression evaluated.
-@item =
-Assignment. The value of an assignment expression is the value
-assigned. Defined on scalar types.
+@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:
-@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{%}.
+@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:
-@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.
+@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:
-@item ||
-Logical @sc{or}. Defined on integral types.
+@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
-@item &&
-Logical @sc{and}. Defined on integral types.
+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:
-@item |
-Bitwise @sc{or}. Defined on integral types.
+@itemize @bullet
+@item
+@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
+@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
-@item ^
-Bitwise exclusive-@sc{or}. Defined on integral types.
-@item &
-Bitwise @sc{and}. Defined on integral types.
+@node Automatic Overlay Debugging
+@section Automatic Overlay Debugging
+@cindex automatic overlay debugging
-@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} 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.
-@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.
+Here are the variables your overlay manager must define to support
+@value{GDBN}'s automatic overlay debugging:
-@item <<@r{, }>>
-left shift, and right shift. Defined on integral types.
+@table @asis
-@item @@
-The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+@item @code{_ovly_table}:
+This variable must be an array of the following structures:
-@item +@r{, }-
-Addition and subtraction. Defined on integral types, floating-point types and
-pointer types.
+@smallexample
+struct
+@{
+ /* The overlay's mapped address. */
+ unsigned long vma;
-@item *@r{, }/@r{, }%
-Multiplication, division, and modulus. Multiplication and division are
-defined on integral and floating-point types. Modulus is defined on
-integral types.
+ /* The size of the overlay, in bytes. */
+ unsigned long size;
-@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.
+ /* The overlay's load address. */
+ unsigned long lma;
-@item *
-Pointer dereferencing. Defined on pointer types. Same precedence as
-@code{++}.
+ /* Non-zero if the overlay is currently mapped;
+ zero otherwise. */
+ unsigned long mapped;
+@}
+@end smallexample
-@item &
-Address operator. Defined on variables. Same precedence as @code{++}.
+@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}:
-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.
+@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:
-@item -
-Negative. Defined on integral and floating-point types. Same
-precedence as @code{++}.
+@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
-@item !
-Logical negation. Defined on integral types. Same precedence as
-@code{++}.
+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}.
-@item ~
-Bitwise complement operator. Defined on integral types. Same precedence as
-@code{++}.
+@node Languages
+@chapter Using @value{GDBN} with Different Languages
+@cindex languages
-@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.
+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 .*@r{, }->*
-Dereferences of pointers to members.
+@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}.
-@item []
-Array indexing. @code{@var{a}[@var{i}]} is defined as
-@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
+@menu
+* Setting:: Switching between source languages
+* Show:: Displaying the language
+* Checks:: Type and range checks
+* Support:: Supported languages
+@end menu
-@item ()
-Function parameter list. Same precedence as @code{->}.
+@node Setting
+@section Switching between source languages
-@item ::
-C++ scope resolution operator. Defined on @code{struct}, @code{union},
-and @code{class} types.
+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.
-@item ::
-Doubled colons also represent the @value{GDBN} scope operator
-(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
-above.
-@end table
+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}.
-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.
+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
-* C Constants::
+* Filenames:: Filename extensions and languages.
+* Manually:: Setting the working language manually
+* Automatically:: Having @value{GDBN} infer the source language
@end menu
-@node C Constants
-@subsubsection C and C++ constants
+@node Filenames
+@subsection List of filename extensions and languages
-@cindex C and C++ constants
+If a source file name ends in one of the following extensions, then
+@value{GDBN} infers that its language is the one indicated.
-@value{GDBN} allows you to express the constants of C and C++ in the
-following ways:
+@table @file
-@itemize @bullet
-@item
-Integer constants are a sequence of digits. Octal constants are
-specified by a leading @samp{0} (i.e. zero), and hexadecimal constants by
-a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
-@samp{l}, specifying that the constant should be treated as a
-@code{long} value.
+@item .c
+C source file
-@item
-Floating point constants are a sequence of digits, followed by a decimal
-point, followed by a sequence of digits, and optionally followed by an
-exponent. An exponent is of the form:
-@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
-sequence of digits. The @samp{+} is optional for positive exponents.
-A floating-point constant may also end with a letter @samp{f} or
-@samp{F}, specifying that the constant should be treated as being of
-the @code{float} (as opposed to the default @code{double}) type; or with
-a letter @samp{l} or @samp{L}, which specifies a @code{long double}
-constant.
+@item .C
+@itemx .cc
+@itemx .cp
+@itemx .cpp
+@itemx .cxx
+@itemx .c++
+C@t{++} source file
-@item
-Enumerated constants consist of enumerated identifiers, or their
-integral equivalents.
+@item .f
+@itemx .F
+Fortran source file
-@item
-Character constants are a single character surrounded by single quotes
-(@code{'}), or a number---the ordinal value of the corresponding character
-(usually its @sc{ascii} value). Within quotes, the single character may
-be represented by a letter or by @dfn{escape sequences}, which are of
-the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
-of the character's ordinal value; or of the form @samp{\@var{x}}, where
-@samp{@var{x}} is a predefined special character---for example,
-@samp{\n} for newline.
+@item .ch
+@itemx .c186
+@itemx .c286
+CHILL source file
-@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 .mod
+Modula-2 source file
-@item
-Pointer constants are an integral value. You can also write pointers
-to constants using the C operator @samp{&}.
+@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
-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
+In addition, you may set the language associated with a filename
+extension. @xref{Show, , Displaying the language}.
-@menu
-* C plus plus expressions::
-* C Defaults::
-* C Checks::
+@node Manually
+@subsection Setting the working language
-* Debugging C::
-@end menu
+If you allow @value{GDBN} to set the language automatically,
+expressions are interpreted the same way in your debugging session and
+your program.
-@node 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
+@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}.
-@enumerate
+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:
-@cindex member functions
-@item
-Member function calls are allowed; you can use expressions like
+@smallexample
+print a = b + c
+@end smallexample
-@example
-count = aml->GetOriginal(x, y)
-@end example
+@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.
-@vindex this@r{, inside C@t{++} member functions}
-@cindex namespace in C++
-@item
-While a member function is active (in the selected stack frame), your
-expressions have the same namespace available as the member function;
-that is, @value{GDBN} allows implicit references to the class instance
-pointer @code{this} following the same rules as C++.
+@node Automatically
+@subsection Having @value{GDBN} infer the source language
-@cindex call overloaded functions
-@cindex overloaded functions, calling
-@cindex type conversions in C++
-@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.
+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.
-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.
+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.
-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 Show
+@section Displaying the language
-You must specify @code{set overload-resolution off} in order to use an
-explicit function signature to call an overloaded function, as in
-@smallexample
-p 'foo(char,int)'('x', 13)
-@end smallexample
+The following commands help you find out which language is the
+working language, and also what language source files were written in.
-The @value{GDBN} command-completion facility can simplify this;
-see @ref{Completion, ,Command completion}.
+@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.
-@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.
+@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.
-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 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
-@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
+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:
-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.
+@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}.
-@node C Defaults
-@subsubsection C and C++ defaults
+@item info extensions
+List all the filename extensions and the associated languages.
+@end table
-@cindex C and C++ defaults
+@node Checks
+@section Type and range checking
-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.
+@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
-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.
+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.
-@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.
+@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 C Checks
-@subsubsection C and C++ type and range checks
+@menu
+* Type Checking:: An overview of type checking
+* Range Checking:: An overview of range checking
+@end menu
-@cindex C and C++ checks
+@cindex type checking
+@cindex checks, type
+@node Type Checking
+@subsection An overview of type checking
-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:
+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,
-@itemize @bullet
-@item
-The two variables are structured and have the same structure, union, or
-enumerated tag.
+@smallexample
+1 + 2 @result{} 3
+@exdent but
+@error{} 1 + 2.3
+@end smallexample
-@item
-The two variables have the same type name, or types that have been
-declared equivalent through @code{typedef}.
+The second example fails because the @code{CARDINAL} 1 is not
+type-compatible with the @code{REAL} 2.3.
-@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
+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.
-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.
+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.
-@node Debugging C
-@subsubsection @value{GDBN} and C
+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.
-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{@{...@}}.
+@value{GDBN} provides some additional commands for controlling the type checker:
-The @code{@@} operator aids in the debugging of dynamic arrays, formed
-with pointers and a memory allocation function. @xref{Expressions,
-,Expressions}.
+@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.
-@menu
-* Debugging C plus plus::
-@end menu
+@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.
-@node Debugging C plus plus
-@subsubsection @value{GDBN} features for C++
+@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.
-@cindex commands for C++
+@item show type
+Show the current setting of the type checker, and whether or not @value{GDBN}
+is setting it automatically.
+@end table
-Some @value{GDBN} commands are particularly useful with C++, and some are
-designed specifically for use with C++. Here is a summary:
+@cindex range checking
+@cindex checks, range
+@node Range Checking
+@subsection An overview of range checking
-@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}.
+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.
-@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}.
+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 C++ exception handling
-@item catch throw
-@itemx catch catch
-Debug C++ exception handling using these commands. @xref{Set
-Catchpoints, , Setting catchpoints}.
+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
-@cindex inheritance
-@item ptype @var{typename}
-Print inheritance relationships as well as other information for type
-@var{typename}.
-@xref{Symbols, ,Examining the Symbol Table}.
+@smallexample
+@var{m} + 1 @result{} @var{s}
+@end smallexample
-@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}.
+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.
-@item set print object
-@itemx show print object
-Choose whether to print derived (actual) or declared types of objects.
-@xref{Print Settings, ,Print settings}.
+@value{GDBN} provides some additional commands for controlling the range checker:
-@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}).)
+@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.
-@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.
+@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 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.
+@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 @r{Overloaded symbol names}
-You can specify a particular definition of an overloaded symbol, using
-the same notation that is used to declare such symbols in C++: type
-@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
-also use the @value{GDBN} command-line word completion facilities to list the
-available choices, or to finish the type list for you.
-@xref{Completion,, Command completion}, for details on how to do this.
+@item 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 Modula-2
-@subsection Modula-2
+@node Support
+@section Supported languages
-@cindex Modula-2, @value{GDBN} support
+@value{GDBN} supports C, C@t{++}, Fortran, Java, Chill, assembly, and Modula-2.
+@c This is false ...
+Some @value{GDBN} features may be used in expressions regardless of the
+language you use: the @value{GDBN} @code{@@} and @code{::} operators,
+and the @samp{@{type@}addr} construct (@pxref{Expressions,
+,Expressions}) can be used with the constructs of any supported
+language.
-The 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.
+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.
-@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
+* C:: C and C@t{++}
+* Modula-2:: Modula-2
+* Chill:: Chill
@end menu
-@node M2 Operators
-@subsubsection Operators
-@cindex Modula-2 operators
+@node C
+@subsection C and C@t{++}
+
+@cindex C and C@t{++}
+@cindex expressions in C or C@t{++}
+
+Since C and C@t{++} are so closely related, many features of @value{GDBN} apply
+to both languages. Whenever this is the case, we discuss those languages
+together.
+
+@cindex C@t{++}
+@cindex @code{g++}, @sc{gnu} C@t{++} compiler
+@cindex @sc{gnu} C@t{++}
+The C@t{++} debugging facilities are jointly implemented by the C@t{++}
+compiler and @value{GDBN}. Therefore, to debug your C@t{++} code
+effectively, you must compile your C@t{++} programs with a supported
+C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
+compiler (@code{aCC}).
+
+For best results when using @sc{gnu} C@t{++}, use the stabs debugging
+format. You can select that format explicitly with the @code{g++}
+command-line options @samp{-gstabs} or @samp{-gstabs+}. See
+@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
+CC, gcc.info, Using @sc{gnu} CC}, for more information.
+
+@menu
+* C Operators:: C and C@t{++} operators
+* C Constants:: C and C@t{++} constants
+* C plus plus expressions:: C@t{++} expressions
+* C Defaults:: Default settings for C and C@t{++}
+* C Checks:: C and C@t{++} type and range checks
+* Debugging C:: @value{GDBN} and C
+* Debugging C plus plus:: @value{GDBN} features for C@t{++}
+@end menu
+
+@node C Operators
+@subsubsection C and C@t{++} operators
+
+@cindex C and C@t{++} operators
Operators must be defined on values of specific types. For instance,
@code{+} is defined on numbers, but not on structures. Operators are
-often defined on groups of types. For the purposes of Modula-2, the
-following definitions hold:
+often defined on groups of types.
+
+For the purposes of C and C@t{++}, the following definitions hold:
@itemize @bullet
@item
-@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
-their subranges.
+@emph{Integral types} include @code{int} with any of its storage-class
+specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}.
@item
-@emph{Character types} consist of @code{CHAR} and its subranges.
+@emph{Floating-point types} include @code{float}, @code{double}, and
+@code{long double} (if supported by the target platform).
@item
-@emph{Floating-point types} consist of @code{REAL}.
+@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
@item
-@emph{Pointer types} consist of anything declared as @code{POINTER TO
-@var{type}}.
-
-@item
-@emph{Scalar types} consist of all of the above.
-
-@item
-@emph{Set types} consist of @code{SET} and @code{BITSET} types.
+@emph{Scalar types} include all of the above.
-@item
-@emph{Boolean types} consist of @code{BOOLEAN}.
@end itemize
@noindent
-The following operators are supported, and appear in order of
-increasing precedence:
+The following operators are supported. They are listed here
+in order of increasing precedence:
@table @code
@item ,
-Function argument or array index separator.
+The comma or sequencing operator. Expressions in a comma-separated list
+are evaluated from left to right, with the result of the entire
+expression being the last expression evaluated.
-@item :=
-Assignment. The value of @var{var} @code{:=} @var{value} is
-@var{value}.
+@item =
+Assignment. The value of an assignment expression is the value
+assigned. Defined on scalar types.
-@item <@r{, }>
-Less than, greater than on integral, floating-point, or enumerated
-types.
+@item @var{op}=
+Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
+and translated to @w{@code{@var{a} = @var{a op b}}}.
+@w{@code{@var{op}=}} and @code{=} have the same precedence.
+@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
+@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
-@item <=@r{, }>=
-Less than or equal to, greater than or equal to
-on integral, floating-point and enumerated types, or set inclusion on
-set types. Same precedence as @code{<}.
+@item ?:
+The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
+of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
+integral type.
-@item =@r{, }<>@r{, }#
-Equality and two ways of expressing inequality, valid on scalar types.
-Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
-available for inequality, since @code{#} conflicts with the script
-comment character.
+@item ||
+Logical @sc{or}. Defined on integral types.
-@item IN
-Set membership. Defined on set types and the types of their members.
-Same precedence as @code{<}.
+@item &&
+Logical @sc{and}. Defined on integral types.
-@item OR
-Boolean disjunction. Defined on boolean types.
+@item |
+Bitwise @sc{or}. Defined on integral types.
-@item AND@r{, }&
-Boolean conjunction. Defined on boolean types.
+@item ^
+Bitwise exclusive-@sc{or}. Defined on integral types.
+
+@item &
+Bitwise @sc{and}. Defined on integral types.
+
+@item ==@r{, }!=
+Equality and inequality. Defined on scalar types. The value of these
+expressions is 0 for false and non-zero for true.
+
+@item <@r{, }>@r{, }<=@r{, }>=
+Less than, greater than, less than or equal, greater than or equal.
+Defined on scalar types. The value of these expressions is 0 for false
+and non-zero for true.
+
+@item <<@r{, }>>
+left shift, and right shift. Defined on integral types.
@item @@
The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
@item +@r{, }-
-Addition and subtraction on integral and floating-point types, or union
-and difference on set types.
+Addition and subtraction. Defined on integral types, floating-point types and
+pointer types.
+
+@item *@r{, }/@r{, }%
+Multiplication, division, and modulus. Multiplication and division are
+defined on integral and floating-point types. Modulus is defined on
+integral types.
+
+@item ++@r{, }--
+Increment and decrement. When appearing before a variable, the
+operation is performed before the variable is used in an expression;
+when appearing after it, the variable's value is used before the
+operation takes place.
@item *
-Multiplication on integral and floating-point types, or set intersection
-on set types.
+Pointer dereferencing. Defined on pointer types. Same precedence as
+@code{++}.
-@item /
-Division on floating-point types, or symmetric set difference on set
-types. Same precedence as @code{*}.
+@item &
+Address operator. Defined on variables. Same precedence as @code{++}.
-@item DIV@r{, }MOD
-Integer division and remainder. Defined on integral types. Same
-precedence as @code{*}.
+For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
+allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
+(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
+where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
+stored.
@item -
-Negative. Defined on @code{INTEGER} and @code{REAL} data.
+Negative. Defined on integral and floating-point types. Same
+precedence as @code{++}.
-@item ^
-Pointer dereferencing. Defined on pointer types.
+@item !
+Logical negation. Defined on integral types. Same precedence as
+@code{++}.
-@item NOT
-Boolean negation. Defined on boolean types. Same precedence as
-@code{^}.
+@item ~
+Bitwise complement operator. Defined on integral types. Same precedence as
+@code{++}.
-@item .
-@code{RECORD} field selector. Defined on @code{RECORD} data. Same
-precedence as @code{^}.
+
+@item .@r{, }->
+Structure member, and pointer-to-structure member. For convenience,
+@value{GDBN} regards the two as equivalent, choosing whether to dereference a
+pointer based on the stored type information.
+Defined on @code{struct} and @code{union} data.
+
+@item .*@r{, }->*
+Dereferences of pointers to members.
@item []
-Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
+Array indexing. @code{@var{a}[@var{i}]} is defined as
+@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
@item ()
-Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
-as @code{^}.
+Function parameter list. Same precedence as @code{->}.
-@item ::@r{, }.
-@value{GDBN} and Modula-2 scope operators.
+@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
-@quotation
-@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN}
-treats the use of the operator @code{IN}, or the use of operators
-@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
-@code{<=}, and @code{>=} on sets as an error.
-@end quotation
+If 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.
-@cindex Modula-2 built-ins
-@node Built-In Func/Proc
-@subsubsection Built-in functions and procedures
+@menu
+* C Constants::
+@end menu
-Modula-2 also makes available several built-in procedures and functions.
-In describing these, the following metavariables are used:
+@node C Constants
+@subsubsection C and C@t{++} constants
-@table @var
+@cindex C and C@t{++} constants
-@item a
-represents an @code{ARRAY} variable.
+@value{GDBN} allows you to express the constants of C and C@t{++} in the
+following ways:
-@item c
-represents a @code{CHAR} constant or variable.
+@itemize @bullet
+@item
+Integer constants are a sequence of digits. Octal constants are
+specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants
+by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
+@samp{l}, specifying that the constant should be treated as a
+@code{long} value.
-@item i
-represents a variable or constant of integral type.
+@item
+Floating point constants are a sequence of digits, followed by a decimal
+point, followed by a sequence of digits, and optionally followed by an
+exponent. An exponent is of the form:
+@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
+sequence of digits. The @samp{+} is optional for positive exponents.
+A floating-point constant may also end with a letter @samp{f} or
+@samp{F}, specifying that the constant should be treated as being of
+the @code{float} (as opposed to the default @code{double}) type; or with
+a letter @samp{l} or @samp{L}, which specifies a @code{long double}
+constant.
-@item m
-represents an identifier that belongs to a set. Generally used in the
-same function with the metavariable @var{s}. The type of @var{s} should
-be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
+@item
+Enumerated constants consist of enumerated identifiers, or their
+integral equivalents.
-@item n
-represents a variable or constant of integral or floating-point type.
+@item
+Character constants are a single character surrounded by single quotes
+(@code{'}), or a number---the ordinal value of the corresponding character
+(usually its @sc{ascii} value). Within quotes, the single character may
+be represented by a letter or by @dfn{escape sequences}, which are of
+the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
+of the character's ordinal value; or of the form @samp{\@var{x}}, where
+@samp{@var{x}} is a predefined special character---for example,
+@samp{\n} for newline.
-@item r
-represents a variable or constant of floating-point type.
+@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 t
-represents a type.
+@item
+Pointer constants are an integral value. You can also write pointers
+to constants using the C operator @samp{&}.
-@item v
-represents a variable.
+@item
+Array constants are comma-separated lists surrounded by braces @samp{@{}
+and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
+integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
+and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
+@end itemize
-@item x
-represents a variable or constant of one of many types. See the
-explanation of the function for details.
-@end table
+@menu
+* C plus plus expressions::
+* C Defaults::
+* C Checks::
-All Modula-2 built-in procedures also return a result, described below.
+* Debugging C::
+@end menu
-@table @code
-@item ABS(@var{n})
-Returns the absolute value of @var{n}.
+@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
-@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}.
+@enumerate
-@item DEC(@var{v})
-Decrements the value in the variable @var{v} by one. Returns the new value.
+@cindex member functions
+@item
+Member function calls are allowed; you can use expressions like
-@item DEC(@var{v},@var{i})
-Decrements the value in the variable @var{v} by @var{i}. Returns the
-new value.
+@smallexample
+count = aml->GetOriginal(x, y)
+@end smallexample
-@item EXCL(@var{m},@var{s})
-Removes the element @var{m} from the set @var{s}. Returns the new
-set.
+@vindex this@r{, inside C@t{++} member functions}
+@cindex namespace in C@t{++}
+@item
+While a member function is active (in the selected stack frame), your
+expressions have the same namespace available as the member function;
+that is, @value{GDBN} allows implicit references to the class instance
+pointer @code{this} following the same rules as C@t{++}.
-@item FLOAT(@var{i})
-Returns the floating point equivalent of the integer @var{i}.
+@cindex call overloaded functions
+@cindex overloaded functions, calling
+@cindex type conversions in C@t{++}
+@item
+You can call overloaded functions; @value{GDBN} resolves the function
+call to the right definition, with some restrictions. @value{GDBN} does not
+perform overload resolution involving user-defined type conversions,
+calls to constructors, or instantiations of templates that do not exist
+in the program. It also cannot handle ellipsis argument lists or
+default arguments.
-@item HIGH(@var{a})
-Returns the index of the last member of @var{a}.
+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.
-@item INC(@var{v})
-Increments the value in the variable @var{v} by one. Returns the new value.
+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 INC(@var{v},@var{i})
-Increments the value in the variable @var{v} by @var{i}. Returns the
-new value.
+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
-@item INCL(@var{m},@var{s})
-Adds the element @var{m} to the set @var{s} if it is not already
-there. Returns the new set.
+The @value{GDBN} command-completion facility can simplify this;
+see @ref{Completion, ,Command completion}.
-@item MAX(@var{t})
-Returns the maximum value of the type @var{t}.
+@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.
-@item MIN(@var{t})
-Returns the minimum value of the type @var{t}.
+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 ODD(@var{i})
-Returns boolean TRUE if @var{i} is an odd number.
+@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
-@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.
+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.
-@item SIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+@node C Defaults
+@subsubsection C and C@t{++} defaults
-@item TRUNC(@var{r})
-Returns the integral part of @var{r}.
+@cindex C and C@t{++} defaults
-@item VAL(@var{t},@var{i})
-Returns the member of the type @var{t} whose ordinal value is @var{i}.
-@end table
+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.
-@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
+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.
-@cindex Modula-2 constants
-@node M2 Constants
-@subsubsection Constants
+@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.
-@value{GDBN} allows you to express the constants of Modula-2 in the following
-ways:
+@node C Checks
+@subsubsection C and C@t{++} type and range checks
-@itemize @bullet
+@cindex C and C@t{++} checks
-@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}.
+By default, when @value{GDBN} parses C or C@t{++} expressions, type checking
+is not used. However, if you turn type checking on, @value{GDBN}
+considers two variables type equivalent if:
+@itemize @bullet
@item
-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.
+The two variables are structured and have the same structure, union, or
+enumerated tag.
@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}.
+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
-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.
+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
-Enumerated constants consist of an enumerated identifier.
+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.
-@item
-Boolean constants consist of the identifiers @code{TRUE} and
-@code{FALSE}.
+@node Debugging C
+@subsubsection @value{GDBN} and C
-@item
-Pointer constants consist of integral values only.
+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
-Set constants are not yet supported.
-@end itemize
+The @code{@@} operator aids in the debugging of dynamic arrays, formed
+with pointers and a memory allocation function. @xref{Expressions,
+,Expressions}.
-@node M2 Defaults
-@subsubsection Modula-2 defaults
-@cindex Modula-2 defaults
+@menu
+* Debugging C plus plus::
+@end menu
-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.
+@node Debugging C plus plus
+@subsubsection @value{GDBN} features for C@t{++}
-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.
+@cindex commands for C@t{++}
-@node Deviations
-@subsubsection Deviations from standard Modula-2
-@cindex Modula-2, deviations from
+Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
+designed specifically for use with C@t{++}. Here is a summary:
-A few changes have been made to make Modula-2 programs easier to debug.
-This is done primarily via loosening its type strictness:
+@table @code
+@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}.
-@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.)
+@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}.
-@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.
+@cindex C@t{++} exception handling
+@item catch throw
+@itemx catch catch
+Debug C@t{++} exception handling using these commands. @xref{Set
+Catchpoints, , Setting catchpoints}.
-@item
-The assignment operator (@code{:=}) returns the value of its right-hand
-argument.
+@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
-All built-in procedures both modify @emph{and} return their argument.
-@end itemize
+@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}.
-@node M2 Checks
-@subsubsection Modula-2 type and range checks
-@cindex Modula-2 checks
+@item set print object
+@itemx show print object
+Choose whether to print derived (actual) or declared types of objects.
+@xref{Print Settings, ,Print settings}.
-@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 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}).)
-@value{GDBN} considers two Modula-2 variables type equivalent if:
+@kindex set overload-resolution
+@cindex overloaded functions, overload resolution
+@item set overload-resolution on
+Enable overload resolution for C@t{++} expression evaluation. The default
+is on. For overloaded functions, @value{GDBN} evaluates the arguments
+and searches for a function whose signature matches the argument types,
+using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++}
+expressions}, for details). If it cannot find a match, it emits a
+message.
+
+@item set overload-resolution off
+Disable overload resolution for C@t{++} expression evaluation. For
+overloaded functions that are not class member functions, @value{GDBN}
+chooses the first function of the specified name that it finds in the
+symbol table, whether or not its arguments are of the correct type. For
+overloaded functions that are class member functions, @value{GDBN}
+searches for a function whose signature @emph{exactly} matches the
+argument types.
+
+@item @r{Overloaded symbol names}
+You can specify a particular definition of an overloaded symbol, using
+the same notation that is used to declare such symbols in C@t{++}: type
+@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
+also use the @value{GDBN} command-line word completion facilities to list the
+available choices, or to finish the type list for you.
+@xref{Completion,, Command completion}, for details on how to do this.
+@end table
+
+@node Modula-2
+@subsection Modula-2
+
+@cindex Modula-2, @value{GDBN} support
+
+The extensions made to @value{GDBN} to support Modula-2 only support
+output from the @sc{gnu} Modula-2 compiler (which is currently being
+developed). Other Modula-2 compilers are not currently supported, and
+attempting to debug executables produced by them is most likely
+to give an error as @value{GDBN} reads in the executable's symbol
+table.
+
+@cindex expressions in Modula-2
+@menu
+* M2 Operators:: Built-in operators
+* Built-In Func/Proc:: Built-in functions and procedures
+* M2 Constants:: Modula-2 constants
+* M2 Defaults:: Default settings for Modula-2
+* Deviations:: Deviations from standard Modula-2
+* M2 Checks:: Modula-2 type and range checks
+* M2 Scope:: The scope operators @code{::} and @code{.}
+* GDB/M2:: @value{GDBN} and Modula-2
+@end menu
+
+@node M2 Operators
+@subsubsection Operators
+@cindex Modula-2 operators
+
+Operators must be defined on values of specific types. For instance,
+@code{+} is defined on numbers, but not on structures. Operators are
+often defined on groups of types. For the purposes of Modula-2, the
+following definitions hold:
@itemize @bullet
-@item
-They are of types that have been declared equivalent via a @code{TYPE
-@var{t1} = @var{t2}} statement
@item
-They have been declared on the same line. (Note: This is true of the
-@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
-@end itemize
+@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
+their subranges.
-As long as type checking is enabled, any attempt to combine variables
-whose types are not equivalent is an error.
+@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 functions and procedures.
+@item
+@emph{Floating-point types} consist of @code{REAL}.
-@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
+@emph{Pointer types} consist of anything declared as @code{POINTER TO
+@var{type}}.
-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
+@emph{Scalar types} consist of all of the above.
-@example
+@item
+@emph{Set types} consist of @code{SET} and @code{BITSET} types.
-@var{module} . @var{id}
-@var{scope} :: @var{id}
-@end example
+@item
+@emph{Boolean types} consist of @code{BOOLEAN}.
+@end itemize
@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.
+The following operators are supported, and appear in order of
+increasing precedence:
-Using the @code{::} operator makes @value{GDBN} search the scope
-specified by @var{scope} for the identifier @var{id}. If it is not
-found in the specified scope, then @value{GDBN} searches all scopes
-enclosing the one specified by @var{scope}.
+@table @code
+@item ,
+Function argument or array index separator.
-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 :=
+Assignment. The value of @var{var} @code{:=} @var{value} is
+@var{value}.
-@node GDB/M2
-@subsubsection @value{GDBN} and Modula-2
+@item <@r{, }>
+Less than, greater than on integral, floating-point, or enumerated
+types.
-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{, }>=
+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{<}.
-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{, }<>@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.
-@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 IN
+Set membership. Defined on set types and the types of their members.
+Same precedence as @code{<}.
-@node Chill
-@subsection Chill
+@item OR
+Boolean disjunction. Defined on boolean types.
-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 AND@r{, }&
+Boolean conjunction. Defined on boolean types.
-@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.
+@item @@
+The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
-@menu
-* How modes are displayed:: How modes are displayed
-* Locations:: Locations and their accesses
-* Values and their Operations:: Values and their Operations
-* Chill type and range checks::
-* Chill defaults::
-@end menu
+@item +@r{, }-
+Addition and subtraction on integral and floating-point types, or union
+and difference on set types.
-@node How modes are displayed
-@subsubsection How modes are displayed
+@item *
+Multiplication on integral and floating-point types, or set intersection
+on set types.
-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:
+@item /
+Division on floating-point types, or symmetric set difference on set
+types. Same precedence as @code{*}.
-@c FIXME: this @table's contents effectively disable @code by using @r
-@c on every @item. So why does it need @code?
-@table @code
-@item @r{@emph{Discrete modes:}}
-@itemize @bullet
-@item
-@emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT,
-UINT, LONG, ULONG},
-@item
-@emph{Boolean Mode} which is predefined by @code{BOOL},
-@item
-@emph{Character Mode} which is predefined by @code{CHAR},
-@item
-@emph{Set Mode} which is displayed by the keyword @code{SET}.
-@smallexample
-(@value{GDBP}) ptype x
-type = SET (karli = 10, susi = 20, fritzi = 100)
-@end smallexample
-If the type is an unnumbered set the set element values are omitted.
-@item
-@emph{Range Mode} which is displayed by
-@smallexample
-@code{type = <basemode>(<lower bound> : <upper bound>)}
-@end smallexample
-where @code{<lower bound>, <upper bound>} can be of any discrete literal
-expression (e.g. set element names).
-@end itemize
+@item DIV@r{, }MOD
+Integer division and remainder. Defined on integral types. Same
+precedence as @code{*}.
-@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 -
+Negative. Defined on @code{INTEGER} and @code{REAL} data.
-@item @r{@emph{Reference Modes:}}
-@itemize @bullet
-@item
-@emph{Bound Reference Mode} which is displayed by the keyword @code{REF}
-followed by the mode name to which the reference is bound.
-@item
-@emph{Free Reference Mode} which is displayed by the keyword @code{PTR}.
-@end itemize
+@item ^
+Pointer dereferencing. Defined on pointer types.
-@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.
+@item NOT
+Boolean negation. Defined on boolean types. Same precedence as
+@code{^}.
-@ignore
-@item @r{@emph{Instance mode}}
-The instance mode is represented by a structure, which has a static
-type, and is therefore not really of interest.
-@end ignore
+@item .
+@code{RECORD} field selector. Defined on @code{RECORD} data. Same
+precedence as @code{^}.
-@item @r{@emph{Synchronization Modes:}}
-@itemize @bullet
-@item
-@emph{Event Mode} which is displayed by
-@smallexample
-@code{EVENT (<event length>)}
-@end smallexample
-where @code{(<event length>)} is optional.
-@item
-@emph{Buffer Mode} which is displayed by
-@smallexample
-@code{BUFFER (<buffer length>)<buffer element mode>}
-@end smallexample
-where @code{(<buffer length>)} is optional.
-@end itemize
+@item []
+Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
-@item @r{@emph{Timing Modes:}}
-@itemize @bullet
-@item
-@emph{Duration Mode} which is predefined by @code{DURATION}
-@item
-@emph{Absolute Time Mode} which is predefined by @code{TIME}
-@end itemize
+@item ()
+Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
+as @code{^}.
-@item @r{@emph{Real Modes:}}
-Real Modes are predefined with @code{REAL} and @code{LONG_REAL}.
+@item ::@r{, }.
+@value{GDBN} and Modula-2 scope operators.
+@end table
-@item @r{@emph{String Modes:}}
-@itemize @bullet
-@item
-@emph{Character String Mode} which is displayed by
-@smallexample
-@code{CHARS(<string length>)}
-@end smallexample
-followed by the keyword @code{VARYING} if the String Mode is a varying
-mode
-@item
-@emph{Bit String Mode} which is displayed by
-@smallexample
-@code{BOOLS(<string
-length>)}
-@end smallexample
-@end itemize
+@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 @r{@emph{Array Mode:}}
-The Array Mode is displayed by the keyword @code{ARRAY(<range>)}
-followed by the element mode (which may in turn be an array mode).
-@smallexample
-(@value{GDBP}) ptype x
-type = ARRAY (1:42)
- ARRAY (1:20)
- SET (karli = 10, susi = 20, fritzi = 100)
-@end smallexample
-@item @r{@emph{Structure Mode}}
-The Structure mode is displayed by the keyword @code{STRUCT(<field
-list>)}. The @code{<field list>} consists of names and modes of fields
-of the structure. Variant structures have the keyword @code{CASE <field>
-OF <variant fields> ESAC} in their field list. Since the current version
-of the GNU Chill compiler doesn't implement tag processing (no runtime
-checks of variant fields, and therefore no debugging info), the output
-always displays all variant fields.
-@smallexample
-(@value{GDBP}) ptype str
-type = STRUCT (
- as x,
- bs x,
- CASE bs OF
- (karli):
- cs a
- (ott):
- ds x
- ESAC
-)
-@end smallexample
-@end table
+@node Built-In Func/Proc
+@subsubsection Built-in functions and procedures
+@cindex Modula-2 built-ins
-@node Locations
-@subsubsection Locations and their accesses
+Modula-2 also makes available several built-in procedures and functions.
+In describing these, the following metavariables are used:
-A location in Chill is an object which can contain values.
+@table @var
-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}.
+@item a
+represents an @code{ARRAY} variable.
-The pseudo-location @code{RESULT} (or @code{result}) can be used to
-display or change the result of a currently-active procedure:
+@item c
+represents a @code{CHAR} constant or variable.
-@smallexample
-set result := EXPR
-@end smallexample
+@item i
+represents a variable or constant of integral type.
-@noindent
-This does the same as the Chill action @code{RESULT EXPR} (which
-is not available in @value{GDBN}).
+@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}).
-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 n
+represents a variable or constant of integral or floating-point type.
-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.
+@item r
+represents a variable or constant of floating-point type.
-@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}.
+@item t
+represents a type.
-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).
+@item v
+represents a variable.
-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
+@item x
+represents a variable or constant of one of many types. See the
+explanation of the function for details.
+@end table
-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}.
+All Modula-2 built-in procedures also return a result, described below.
-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.
+@table @code
+@item ABS(@var{n})
+Returns the absolute value of @var{n}.
-@smallexample
-(@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX
-@end smallexample
+@item CAP(@var{c})
+If @var{c} is a lower case letter, it returns its upper case
+equivalent, otherwise it returns its argument.
-@node Values and their Operations
-@subsubsection Values and their Operations
+@item CHR(@var{i})
+Returns the character whose ordinal value is @var{i}.
-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.
+@item DEC(@var{v})
+Decrements the value in the variable @var{v} by one. Returns the new value.
-This section describes how values have to be specified and which
-operations are legal to be used with such values.
+@item DEC(@var{v},@var{i})
+Decrements the value in the variable @var{v} by @var{i}. Returns the
+new value.
-@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.
+@item EXCL(@var{m},@var{s})
+Removes the element @var{m} from the set @var{s}. Returns the new
+set.
-@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.
+@item FLOAT(@var{i})
+Returns the floating point equivalent of the integer @var{i}.
-@item
-@emph{Character String Literals} are defined by a sequence of characters
-enclosed in single- or double quotes. If a single- or double quote has
-to be part of the string literal it has to be stuffed (specified twice).
-@item
-@emph{Bitstring Literals} are specified in the same manner as in Chill
-programs (refer z200/88 chpt 5.2.4.8).
-@item
-@emph{Floating point literals} are specified in the same manner as in
-(gnu-)Chill programs (refer @sc{gnu} Chill implementation Manual chapter 1.5).
-@end itemize
-@end ignore
+@item HIGH(@var{a})
+Returns the index of the last member of @var{a}.
-@item Tuple Values
-A tuple is specified by @code{<mode name>[<tuple>]}, where @code{<mode
-name>} can be omitted if the mode of the tuple is unambiguous. This
-unambiguity is derived from the context of a evaluated expression.
-@code{<tuple>} can be one of the following:
-
-@itemize @bullet
-@item @emph{Powerset Tuple}
-@item @emph{Array Tuple}
-@item @emph{Structure Tuple}
-Powerset tuples, array tuples and structure tuples are specified in the
-same manner as in Chill programs refer to z200/88 chpt 5.2.5.
-@end itemize
-
-@item String Element Value
-A string element value is specified by
-@smallexample
-@code{<string value>(<index>)}
-@end smallexample
-where @code{<index>} is a integer expression. It delivers a character
-value which is equivalent to the character indexed by @code{<index>} in
-the string.
-
-@item String Slice Value
-A string slice value is specified by @code{<string value>(<slice
-spec>)}, where @code{<slice spec>} can be either a range of integer
-expressions or specified by @code{<start expr> up <size>}.
-@code{<size>} denotes the number of elements which the slice contains.
-The delivered value is a string value, which is part of the specified
-string.
+@item INC(@var{v})
+Increments the value in the variable @var{v} by one. Returns the new value.
-@item Array Element Values
-An array element value is specified by @code{<array value>(<expr>)} and
-delivers a array element value of the mode of the specified array.
+@item INC(@var{v},@var{i})
+Increments the value in the variable @var{v} by @var{i}. Returns the
+new value.
-@item Array Slice Values
-An array slice is specified by @code{<array value>(<slice spec>)}, where
-@code{<slice spec>} can be either a range specified by expressions or by
-@code{<start expr> up <size>}. @code{<size>} denotes the number of
-arrayelements the slice contains. The delivered value is an array value
-which is part of the specified array.
+@item INCL(@var{m},@var{s})
+Adds the element @var{m} to the set @var{s} if it is not already
+there. Returns the new set.
-@item Structure Field Values
-A structure field value is derived by @code{<structure value>.<field
-name>}, where @code{<field name>} indicates the name of a field specified
-in the mode definition of the structure. The mode of the delivered value
-corresponds to this mode definition in the structure definition.
+@item MAX(@var{t})
+Returns the maximum value of the type @var{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.}.
+@item MIN(@var{t})
+Returns the minimum value of the type @var{t}.
-Values of duration mode locations are represented by @code{ULONG} literals.
+@item ODD(@var{i})
+Returns boolean TRUE if @var{i} is an odd number.
-Values of time mode locations appear as
-@smallexample
-@code{TIME(<secs>:<nsecs>)}
-@end smallexample
+@item ORD(@var{x})
+Returns the ordinal value of its argument. For example, the ordinal
+value of a character is its @sc{ascii} value (on machines supporting the
+@sc{ascii} character set). @var{x} must be of an ordered type, which include
+integral, character and enumerated types.
+@item SIZE(@var{x})
+Returns the size of its argument. @var{x} can be a variable or a type.
-@ignore
-This is not implemented yet:
-@item Built-in Value
-@noindent
-The following built in functions are provided:
+@item TRUNC(@var{r})
+Returns the integral part of @var{r}.
-@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()}
+@item VAL(@var{t},@var{i})
+Returns the member of the type @var{t} whose ordinal value is @var{i}.
@end table
-For a detailed description refer to the GNU Chill implementation manual
-chapter 1.6.
-@end ignore
-
-@item Zero-adic Operator Value
-The zero-adic operator value is derived from the instance value for the
-current active process.
-
-@item Expression Values
-The value delivered by an expression is the result of the evaluation of
-the specified expression. If there are error conditions (mode
-incompatibility, etc.) the evaluation of expressions is aborted with a
-corresponding error message. Expressions may be parenthesised which
-causes the evaluation of this expression before any other expression
-which uses the result of the parenthesised expression. The following
-operators are supported by @value{GDBN}:
-
-@table @code
-@item @code{OR, ORIF, XOR}
-@itemx @code{AND, ANDIF}
-@itemx @code{NOT}
-Logical operators defined over operands of boolean mode.
-
-@item @code{=, /=}
-Equality and inequality operators defined over all modes.
-
-@item @code{>, >=}
-@itemx @code{<, <=}
-Relational operators defined over predefined modes.
-
-@item @code{+, -}
-@itemx @code{*, /, MOD, REM}
-Arithmetic operators defined over predefined modes.
-
-@item @code{-}
-Change sign operator.
-
-@item @code{//}
-String concatenation operator.
+@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
-@item @code{()}
-String repetition operator.
+@cindex Modula-2 constants
+@node M2 Constants
+@subsubsection Constants
-@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->}).
+@value{GDBN} allows you to express the constants of Modula-2 in the following
+ways:
-@item @code{OR, XOR}
-@itemx @code{AND}
-@itemx @code{NOT}
-Powerset and bitstring operators.
+@itemize @bullet
-@item @code{>, >=}
-@itemx @code{<, <=}
-Powerset inclusion operators.
+@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 @code{IN}
-Membership operator.
-@end table
-@end table
+@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.
-@node Chill type and range checks
-@subsubsection Chill type and range checks
+@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}.
-@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
+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.
-Range checking is done on all mathematical operations, assignment, array
-index bounds and all built in procedures.
+@item
+Enumerated constants consist of an enumerated identifier.
-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
+Boolean constants consist of the identifiers @code{TRUE} and
+@code{FALSE}.
-All checks can be disabled by the @value{GDBN} command @code{set check
-off}.
+@item
+Pointer constants consist of integral values only.
-@ignore
-@c Deviations from the Chill Standard Z200/88
-see last paragraph ?
-@end ignore
+@item
+Set constants are not yet supported.
+@end itemize
-@node Chill defaults
-@subsubsection Chill defaults
+@node M2 Defaults
+@subsubsection Modula-2 defaults
+@cindex Modula-2 defaults
If type and range checking are set automatically by @value{GDBN}, they
both default to @code{on} whenever the working language changes to
-Chill. This happens regardless of whether you or @value{GDBN}
+Modula-2. This happens regardless of whether you or @value{GDBN}
selected the working language.
If you allow @value{GDBN} to set the language automatically, then entering
-code compiled from a file whose name ends with @file{.ch} sets the
-working language to Chill. @xref{Automatically, ,Having @value{GDBN} set
+code compiled from a file whose name ends with @file{.mod} sets the
+working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
the language automatically}, for further details.
-@node Symbols
-@chapter Examining the Symbol Table
+@node Deviations
+@subsubsection Deviations from standard Modula-2
+@cindex Modula-2, deviations from
-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}).
+A few changes have been made to make Modula-2 programs easier to debug.
+This is done primarily via loosening its type strictness:
-@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,
+@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.)
-@example
-p 'foo.c'::x
-@end example
+@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.
-@noindent
-looks up the value of @code{x} in the scope of the file @file{foo.c}.
+@item
+The assignment operator (@code{:=}) returns the value of its right-hand
+argument.
-@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
+All built-in procedures both modify @emph{and} return their argument.
+@end itemize
-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.
+@node M2 Checks
+@subsubsection Modula-2 type and range checks
+@cindex Modula-2 checks
-@kindex info symbol
-@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:
+@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
-@example
-(@value{GDBP}) info symbol 0x54320
-_initialize_vx + 396 in section .text
-@end example
+@value{GDBN} considers two Modula-2 variables type equivalent if:
-@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.
+@itemize @bullet
+@item
+They are of types that have been declared equivalent via a @code{TYPE
+@var{t1} = @var{t2}} statement
-@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
+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 whatis
-Print the data type of @code{$}, the last value in the value history.
+As long as type checking is enabled, any attempt to combine variables
+whose types are not equivalent is an error.
-@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}}.
+Range checking is done on all mathematical operations, assignment, array
+index bounds, and all built-in functions and procedures.
-@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.
+@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
-For example, for this variable declaration:
+There are a few subtle differences between the Modula-2 scope operator
+(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
+similar syntax:
-@example
-struct complex @{double real; double imag;@} v;
-@end example
+@smallexample
+
+@var{module} . @var{id}
+@var{scope} :: @var{id}
+@end smallexample
@noindent
-the two commands give this output:
+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.
-@example
-@group
-(@value{GDBP}) whatis v
-type = struct complex
-(@value{GDBP}) ptype v
-type = struct complex @{
- double real;
- double imag;
-@}
-@end group
-@end example
+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}.
-@noindent
-As with @code{whatis}, using @code{ptype} without an argument refers to
-the type of @code{$}, the last value in the value history.
+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}.
-@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}.
+@node GDB/M2
+@subsubsection @value{GDBN} and Modula-2
-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.
+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.
-@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.
+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.
-@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.
+@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.
-@kindex info functions
-@item info functions
-Print the names and data types of all defined functions.
+@node Chill
+@subsection Chill
-@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}.
+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.
-@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).
+@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.
-@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}.
+@menu
+* How modes are displayed:: How modes are displayed
+* Locations:: Locations and their accesses
+* Values and their Operations:: Values and their Operations
+* Chill type and range checks::
+* Chill defaults::
+@end menu
-@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
+@node How modes are displayed
+@subsubsection How modes are displayed
-@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:
+The Chill Datatype- (Mode) support of @value{GDBN} is directly related
+with the functionality of the @sc{gnu} Chill compiler, and therefore deviates
+slightly from the standard specification of the Chill language. The
+provided modes are:
+@c FIXME: this @table's contents effectively disable @code by using @r
+@c on every @item. So why does it need @code?
@table @code
-@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 @r{@emph{Discrete modes:}}
+@itemize @bullet
+@item
+@emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT,
+UINT, LONG, ULONG},
+@item
+@emph{Boolean Mode} which is predefined by @code{BOOL},
+@item
+@emph{Character Mode} which is predefined by @code{CHAR},
+@item
+@emph{Set Mode} which is displayed by the keyword @code{SET}.
+@smallexample
+(@value{GDBP}) ptype x
+type = SET (karli = 10, susi = 20, fritzi = 100)
+@end smallexample
+If the type is an unnumbered set the set element values are omitted.
+@item
+@emph{Range Mode} which is displayed by
+@smallexample
+@code{type = <basemode>(<lower bound> : <upper bound>)}
+@end smallexample
+where @code{<lower bound>, <upper bound>} can be of any discrete literal
+expression (e.g. set element names).
+@end itemize
-@item 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 @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
-@kindex show symbol-reloading
-@item show symbol-reloading
-Show the current @code{on} or @code{off} setting.
-@end table
+@item @r{@emph{Reference Modes:}}
+@itemize @bullet
+@item
+@emph{Bound Reference Mode} which is displayed by the keyword @code{REF}
+followed by the mode name to which the reference is bound.
+@item
+@emph{Free Reference Mode} which is displayed by the keyword @code{PTR}.
+@end itemize
-@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 @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.
-A change in the setting of this subcommand will not take effect until
-the next time symbols for a file are loaded.
+@ignore
+@item @r{@emph{Instance mode}}
+The instance mode is represented by a structure, which has a static
+type, and is therefore not really of interest.
+@end ignore
-@item set opaque-type-resolution off
-Tell @value{GDBN} not to resolve opaque types. In this case, the type
-is printed as follows:
+@item @r{@emph{Synchronization Modes:}}
+@itemize @bullet
+@item
+@emph{Event Mode} which is displayed by
@smallexample
-@{<no data fields>@}
+@code{EVENT (<event length>)}
+@end smallexample
+where @code{(<event length>)} is optional.
+@item
+@emph{Buffer Mode} which is displayed by
+@smallexample
+@code{BUFFER (<buffer length>)<buffer element mode>}
@end smallexample
+where @code{(<buffer length>)} is optional.
+@end itemize
-@kindex show opaque-type-resolution
-@item show opaque-type-resolution
-Show whether opaque types are resolved or not.
+@item @r{@emph{Timing Modes:}}
+@itemize @bullet
+@item
+@emph{Duration Mode} which is predefined by @code{DURATION}
+@item
+@emph{Absolute Time Mode} which is predefined by @code{TIME}
+@end itemize
-@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
+@item @r{@emph{Real Modes:}}
+Real Modes are predefined with @code{REAL} and @code{LONG_REAL}.
-@node Altering
-@chapter Altering Execution
+@item @r{@emph{String Modes:}}
+@itemize @bullet
+@item
+@emph{Character String Mode} which is displayed by
+@smallexample
+@code{CHARS(<string length>)}
+@end smallexample
+followed by the keyword @code{VARYING} if the String Mode is a varying
+mode
+@item
+@emph{Bit String Mode} which is displayed by
+@smallexample
+@code{BOOLS(<string
+length>)}
+@end smallexample
+@end itemize
-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.
+@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
-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 @r{@emph{Structure Mode}}
+The Structure mode is displayed by the keyword @code{STRUCT(<field
+list>)}. The @code{<field list>} consists of names and modes of fields
+of the structure. Variant structures have the keyword @code{CASE <field>
+OF <variant fields> ESAC} in their field list. Since the current version
+of the GNU Chill compiler doesn't implement tag processing (no runtime
+checks of variant fields, and therefore no debugging info), the output
+always displays all variant fields.
+@smallexample
+(@value{GDBP}) ptype str
+type = STRUCT (
+ as x,
+ bs x,
+ CASE bs OF
+ (karli):
+ cs a
+ (ott):
+ ds x
+ ESAC
+)
+@end smallexample
+@end table
-@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 Locations
+@subsubsection Locations and their accesses
-@node Assignment
-@section Assignment to variables
+A location in Chill is an object which can contain values.
-@cindex assignment
-@cindex setting variables
-To alter the value of a variable, evaluate an assignment expression.
-@xref{Expressions, ,Expressions}. For example,
+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}.
-@example
-print x=4
-@end example
+The pseudo-location @code{RESULT} (or @code{result}) can be used to
+display or change the result of a currently-active procedure:
+
+@smallexample
+set result := EXPR
+@end smallexample
@noindent
-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.
+This does the same as the Chill action @code{RESULT EXPR} (which
+is not available in @value{GDBN}).
-@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.
+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{->}.
-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}:
+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.
-@example
-(@value{GDBP}) whatis width
-type = double
-(@value{GDBP}) p width
-$4 = 13
-(@value{GDBP}) set width=47
-Invalid syntax in expression.
-@end example
+@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}.
-@noindent
-The invalid expression, of course, is @samp{=47}. In
-order to actually set the program's variable @code{width}, use
+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).
-@example
-(@value{GDBP}) set var width=47
-@end example
+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
-Because the @code{set} command has many subcommands that can conflict
-with the names of program variables, it is a good idea to use the
-@code{set variable} command instead of just @code{set}. For example, if
-your program has a variable @code{g}, you run into problems if you try
-to set a new value with just @samp{set g=4}, because @value{GDBN} has
-the command @code{set gnutarget}, abbreviated @code{set g}:
-
-@example
-@group
-(@value{GDBP}) whatis g
-type = double
-(@value{GDBP}) p g
-$1 = 1
-(@value{GDBP}) set g=4
-(@value{GDBP}) p g
-$2 = 1
-(@value{GDBP}) r
-The program being debugged has been started already.
-Start it from the beginning? (y or n) y
-Starting program: /home/smith/cc_progs/a.out
-"/home/smith/cc_progs/a.out": can't open to read symbols:
- Invalid bfd target.
-(@value{GDBP}) show g
-The current BFD target is "=4".
-@end group
-@end example
-
-@noindent
-The program variable @code{g} did not change, and you silently set the
-@code{gnutarget} to an invalid value. In order to set the variable
-@code{g}, use
-
-@example
-(@value{GDBP}) set var g=4
-@end example
-
-@value{GDBN} allows more implicit conversions in assignments than C; you can
-freely store an integer value into a pointer variable or vice versa,
-and you can convert any structure to any other structure that is the
-same length or shorter.
-@comment FIXME: how do structs align/pad in these conversions?
-@comment /doc@cygnus.com 18dec1990
+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}.
-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
+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.
-@example
-set @{int@}0x83040 = 4
-@end example
+@smallexample
+(@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX
+@end smallexample
-@noindent
-stores the value 4 into that memory location.
+@node Values and their Operations
+@subsubsection Values and their Operations
-@node Jumping
-@section Continuing at a different address
+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.
-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:
+This section describes how values have to be specified and which
+operations are legal to be used with such values.
@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 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.
-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.
+@ignore
+@itemize @bullet
+@item
+@emph{Integer Literals} are specified in the same manner as in Chill
+programs (refer to the Chill Standard z200/88 chpt 5.2.4.2)
+@item
+@emph{Boolean Literals} are defined by @code{TRUE} and @code{FALSE}.
+@item
+@emph{Character Literals} are defined by @code{'<character>'}. (e.g.
+@code{'M'})
+@item
+@emph{Set Literals} are defined by a name which was specified in a set
+mode. The value delivered by a Set Literal is the set value. This is
+comparable to an enumeration in C/C@t{++} language.
+@item
+@emph{Emptiness Literal} is predefined by @code{NULL}. The value of the
+emptiness literal delivers either the empty reference value, the empty
+procedure value or the empty instance value.
-@item jump *@var{address}
-Resume execution at the instruction at address @var{address}.
-@end table
+@item
+@emph{Character String Literals} are defined by a sequence of characters
+enclosed in single- or double quotes. If a single- or double quote has
+to be part of the string literal it has to be stuffed (specified twice).
+@item
+@emph{Bitstring Literals} are specified in the same manner as in Chill
+programs (refer z200/88 chpt 5.2.4.8).
+@item
+@emph{Floating point literals} are specified in the same manner as in
+(gnu-)Chill programs (refer @sc{gnu} Chill implementation Manual chapter 1.5).
+@end itemize
+@end ignore
-@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 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:
-@example
-set $pc = 0x485
-@end example
+@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
-@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 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 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 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.
-@c @group
-@node Signaling
-@section Giving your program a signal
+@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.
-@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.
+@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.
-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.
+@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.
-@code{signal} does not repeat when you press @key{RET} a second time
-after executing the command.
-@end table
-@c @end group
+@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.}.
-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.
+Values of duration mode locations are represented by @code{ULONG} literals.
+
+Values of time mode locations appear as
+@smallexample
+@code{TIME(<secs>:<nsecs>)}
+@end smallexample
-@node Returning
-@section Returning from a function
+@ignore
+This is not implemented yet:
+@item Built-in Value
+@noindent
+The following built in functions are provided:
@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.
+@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
-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.
+For a detailed description refer to the GNU Chill implementation manual
+chapter 1.6.
+@end ignore
-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.
+@item Zero-adic Operator Value
+The zero-adic operator value is derived from the instance value for the
+current active process.
-@node Calling
-@section Calling program functions
+@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}:
-@cindex calling functions
-@kindex call
@table @code
-@item call @var{expr}
-Evaluate the expression @var{expr} without displaying @code{void}
-returned values.
-@end table
+@item @code{OR, ORIF, XOR}
+@itemx @code{AND, ANDIF}
+@itemx @code{NOT}
+Logical operators defined over operands of boolean mode.
-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.
+@item @code{=, /=}
+Equality and inequality operators defined over all modes.
-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 @code{>, >=}
+@itemx @code{<, <=}
+Relational operators defined over predefined modes.
-@node Patching
-@section Patching programs
+@item @code{+, -}
+@itemx @code{*, /, MOD, REM}
+Arithmetic operators defined over predefined modes.
-@cindex patching binaries
-@cindex writing into executables
-@cindex writing into corefiles
+@item @code{-}
+Change sign operator.
-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.
+@item @code{//}
+String concatenation operator.
-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.
+@item @code{()}
+String repetition operator.
-@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.
+@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->}).
-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 @code{OR, XOR}
+@itemx @code{AND}
+@itemx @code{NOT}
+Powerset and bitstring operators.
-@item show write
-@kindex show write
-Display whether executable files and core files are opened for writing
-as well as reading.
-@end table
+@item @code{>, >=}
+@itemx @code{<, <=}
+Powerset inclusion operators.
-@node GDB Files
-@chapter @value{GDBN} Files
+@item @code{IN}
+Membership operator.
+@end table
+@end table
-@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.
+@node Chill type and range checks
+@subsubsection Chill type and range checks
-@menu
-* Files:: Commands to specify files
-* Symbol Errors:: Errors reading symbol files
-@end menu
+@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.
-@node Files
-@section Commands to specify files
+Range checking is done on all mathematical operations, assignment, array
+index bounds and all built in procedures.
-@cindex symbol table
-@cindex core dump file
+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.
-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}}).
+All checks can be disabled by the @value{GDBN} command @code{set check
+off}.
-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.
+@ignore
+@c Deviations from the Chill Standard Z200/88
+see last paragraph ?
+@end ignore
-@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 Chill defaults
+@subsubsection Chill defaults
-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.
+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.
-@item file
-@code{file} with no argument makes @value{GDBN} discard any information it
-has on both executable file and the symbol table.
+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.
-@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.
+@node Symbols
+@chapter Examining the Symbol Table
-@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.
+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}).
-@code{symbol-file} with no argument clears out @value{GDBN} information on your
-program's 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,
-The @code{symbol-file} command causes @value{GDBN} to forget the contents
-of its convenience variables, the value history, and all breakpoints and
-auto-display expressions. This is because they may contain pointers to
-the internal data recording symbols and data types, which are part of
-the old symbol table data being discarded inside @value{GDBN}.
+@smallexample
+p 'foo.c'::x
+@end smallexample
-@code{symbol-file} does not repeat if you press @key{RET} again after
-executing it once.
+@noindent
+looks up the value of @code{x} in the scope of the file @file{foo.c}.
-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.
+@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.
-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.
+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.
-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}.)
+@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:
-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.
+@smallexample
+(@value{GDBP}) info symbol 0x54320
+_initialize_vx + 396 in section .text
+@end smallexample
-@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.
+@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.
-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 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}.
-You can use both options together, to make sure the auxiliary symbol
-file has all the symbol information for your program.
+@item whatis
+Print the data type of @code{$}, the last value in the value history.
-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.
+@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}}.
-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.
+@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.
-@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.
+For example, for this variable declaration:
-@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
+struct complex @{double real; double imag;@} v;
+@end smallexample
-@code{core-file} with no argument specifies that no core file is
-to be used.
+@noindent
+the two commands give this output:
-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}).
+@smallexample
+@group
+(@value{GDBP}) whatis v
+type = struct complex
+(@value{GDBP}) ptype v
+type = struct complex @{
+ double real;
+ double imag;
+@}
+@end group
+@end smallexample
-@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.
+@noindent
+As with @code{whatis}, using @code{ptype} without an argument refers to
+the type of @code{$}, the last value in the value history.
-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 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}.
-@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+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.
-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 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:
-@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.
+@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
-@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.
+@noindent
+This command is especially useful for determining what data to collect
+during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
+collect}.
-@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 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.
-@end table
+@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.
-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.
+@kindex info functions
+@item info functions
+Print the names and data types of all defined functions.
-@cindex shared libraries
-@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
-libraries.
+@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.
-@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).
+@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).
-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.
+@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}.
-@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
+@ignore
+This was never implemented.
+@kindex info methods
+@item info methods
+@itemx info methods @var{regexp}
+The @code{info methods} command permits the user to examine all defined
+methods within C@t{++} program, or (with the @var{regexp} argument) a
+specific set of methods found in the various C@t{++} classes. Many
+C@t{++} classes provide a large number of methods. Thus, the output
+from the @code{ptype} command can be overwhelming and hard to use. The
+@code{info-methods} command filters the methods, printing only those
+which match the regular-expression @var{regexp}.
+@end ignore
+
+@cindex reloading symbols
+Some systems allow individual object files that make up your program to
+be replaced without stopping and restarting your program. For example,
+in VxWorks you can simply recompile a defective object file and keep on
+running. If you are running on one of these systems, you can allow
+@value{GDBN} to reload the symbols for automatically relinked modules:
@table @code
-@kindex 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
-loaded.
-@end table
+@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.
-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.
+@kindex show symbol-reloading
+@item show symbol-reloading
+Show the current @code{on} or @code{off} setting.
+@end table
-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.
+@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.
-To display or set the threshold, use the commands:
+A change in the setting of this subcommand will not take effect until
+the next time symbols for a file are loaded.
-@table @code
-@kindex set auto-solib-add
-@item set auto-solib-add @var{threshold}
-Set the autoloading size threshold, in megabytes. If @var{threshold} is
-nonzero, symbols from all shared object libraries will be loaded
-automatically when the inferior begins execution or when the dynamic
-linker informs @value{GDBN} that a new library has been loaded, until
-the symbol table of the program and libraries exceeds this threshold.
-Otherwise, symbols must be loaded manually, using the
-@code{sharedlibrary} command. The default threshold is 100 megabytes.
+@item 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 auto-solib-add
-@item show auto-solib-add
-Display the current autoloading size threshold, in megabytes.
+@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 Symbol Errors
-@section Errors reading symbol files
+@node Altering
+@chapter Altering Execution
-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}).
+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.
-The messages currently printed, and their meanings, include:
+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.
-@table @code
-@item inner block not inside outer block in @var{symbol}
+@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
-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.
+@node Assignment
+@section Assignment to variables
-@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.
+@cindex assignment
+@cindex setting variables
+To alter the value of a variable, evaluate an assignment expression.
+@xref{Expressions, ,Expressions}. For example,
-@item block at @var{address} out of order
+@smallexample
+print x=4
+@end smallexample
-The symbol information for symbol scope blocks should occur in
-order of increasing addresses. This error indicates that it does not
-do so.
+@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.
-@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}.)
+@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 bad block start address patched
+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}:
-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.
+@smallexample
+(@value{GDBP}) whatis width
+type = double
+(@value{GDBP}) p width
+$4 = 13
+(@value{GDBP}) set width=47
+Invalid syntax in expression.
+@end smallexample
-@value{GDBN} circumvents the problem by treating the symbol scope block as
-starting on the previous source line.
+@noindent
+The invalid expression, of course, is @samp{=47}. In
+order to actually set the program's variable @code{width}, use
-@item bad string table offset in symbol @var{n}
+@smallexample
+(@value{GDBP}) set var width=47
+@end smallexample
-@cindex foo
-Symbol number @var{n} contains a pointer into the string table which is
-larger than the size of the string table.
+Because the @code{set} command has many subcommands that can conflict
+with the names of program variables, it is a good idea to use the
+@code{set variable} command instead of just @code{set}. For example, if
+your program has a variable @code{g}, you run into problems if you try
+to set a new value with just @samp{set g=4}, because @value{GDBN} has
+the command @code{set gnutarget}, abbreviated @code{set g}:
-@value{GDBN} 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.
+@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
-@item unknown symbol type @code{0x@var{nn}}
+@noindent
+The program variable @code{g} did not change, and you silently set the
+@code{gnutarget} to an invalid value. In order to set the variable
+@code{g}, use
-The 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.
+@smallexample
+(@value{GDBP}) set var g=4
+@end smallexample
-@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.
+@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 stub type has NULL name
+To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
+construct to generate a value of specified type at a specified address
+(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
+to memory location @code{0x83040} as an integer (which implies a certain size
+and representation in memory), and
-@value{GDBN} could not find the full definition for a struct or class.
+@smallexample
+set @{int@}0x83040 = 4
+@end smallexample
-@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.
+@noindent
+stores the value 4 into that memory location.
-@item info mismatch between compiler and debugger
+@node Jumping
+@section Continuing at a different address
-@value{GDBN} could not parse a type specification output by the compiler.
+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:
-@end table
+@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}.
-@node Targets
-@chapter Specifying a Debugging Target
+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.
-@cindex debugging target
-@kindex target
+@item jump *@var{address}
+Resume execution at the instruction at address @var{address}.
+@end table
-A @dfn{target} is the execution environment occupied by your program.
+@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,
-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}).
+@smallexample
+set $pc = 0x485
+@end smallexample
-@menu
-* Active Targets:: Active targets
-* Target Commands:: Commands for managing targets
-* Byte Order:: Choosing target byte order
-* Remote:: Remote debugging
-* KOD:: Kernel Object Display
+@noindent
+makes the next @code{continue} command or stepping command execute at
+address @code{0x485}, rather than at the address where your program stopped.
+@xref{Continuing and Stepping, ,Continuing and stepping}.
-@end menu
+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.
-@node Active Targets
-@section Active targets
+@c @group
+@node Signaling
+@section Giving your program a signal
-@cindex stacking targets
-@cindex active targets
-@cindex multiple targets
+@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.
-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.
+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.
-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.)
+@code{signal} does not repeat when you press @key{RET} a second time
+after executing the command.
+@end table
+@c @end group
-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.
+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.
-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
+@node Returning
+@section Returning from a function
@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}).
+@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 help target @var{name}
-Describe a particular target, including any parameters necessary to
-select it.
+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}.
-@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.
+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.
-@quotation
-@emph{Warning:} To specify a file format with @code{set gnutarget},
-you must know the actual BFD name.
-@end quotation
+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.
-@noindent
-@xref{Files, , Commands to specify files}.
+@node Calling
+@section Calling program functions
-@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"}.
+@cindex calling functions
+@kindex call
+@table @code
+@item call @var{expr}
+Evaluate the expression @var{expr} without displaying @code{void}
+returned values.
@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}}.
+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.
-@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}}.
+@c OBSOLETE For the A29K, a user-controlled variable @code{call_scratch_address},
+@c OBSOLETE specifies the location of a scratch area to be used when @value{GDBN}
+@c OBSOLETE calls a function in the target. This is necessary because the usual
+@c OBSOLETE method of putting the scratch area on the stack does not work in systems
+@c OBSOLETE that have separate instruction and data spaces.
-@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.
+@node Patching
+@section Patching programs
-@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}.
+@cindex patching binaries
+@cindex writing into executables
+@cindex writing into corefiles
-@end table
+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.
-Some configurations may include these targets as well:
+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.
-@kindex target nrom
-@item target nrom @var{dev}
-NetROM ROM emulator. This target only supports downloading.
+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
-Different targets are available on different configurations of @value{GDBN};
-your configuration may have more or fewer targets.
+@node GDB Files
+@chapter @value{GDBN} Files
-Many remote targets require you to download the executable's code
-once you've successfully established a connection.
+@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.
-@table @code
+@menu
+* Files:: Commands to specify files
+* Symbol Errors:: Errors reading symbol files
+@end menu
-@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.
+@node Files
+@section Commands to specify files
-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{}}''
+@cindex symbol table
+@cindex core dump file
-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.
+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}}).
-@code{load} does not repeat if you press @key{RET} again after using it.
-@end table
+Occasionally it is necessary to change to a different file during a
+@value{GDBN} session. Or you may run @value{GDBN} and forget to specify
+a file you want to use. In these situations the @value{GDBN} commands
+to specify new files are useful.
-@node Byte Order
-@section Choosing target byte order
+@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.
-@cindex choosing target byte order
-@cindex target byte order
+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.
-Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
-offer the ability to run either big-endian or little-endian byte
-orders. Usually the executable or symbol will include a bit to
-designate the endian-ness, and you will not need to worry about
-which to use. However, you may still find it useful to adjust
-@value{GDBN}'s idea of processor endian-ness manually.
+@item file
+@code{file} with no argument makes @value{GDBN} discard any information it
+has on both executable file and the symbol table.
-@table @code
-@kindex set endian big
-@item set endian big
-Instruct @value{GDBN} to assume the target is big-endian.
+@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 set endian little
-@item set endian little
-Instruct @value{GDBN} to assume the target is little-endian.
+@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.
-@kindex set endian auto
-@item set endian auto
-Instruct @value{GDBN} to use the byte order associated with the
-executable.
+@code{symbol-file} with no argument clears out @value{GDBN} information on your
+program's symbol table.
-@item show endian
-Display @value{GDBN}'s current idea of the target byte order.
+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}.
-@end table
+@code{symbol-file} does not repeat if you press @key{RET} again after
+executing it once.
-Note that these commands merely adjust interpretation of symbolic
-data on the host, and that they have absolutely no effect on the
-target system.
+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.
-@node Remote
-@section Remote debugging
-@cindex remote debugging
+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.
-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.
+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}.)
-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}.
+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.
-Other remote targets may be available in your
-configuration of @value{GDBN}; use @code{help target} to list them.
+@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.
-@menu
-* Remote Serial:: @value{GDBN} remote serial protocol
-@end menu
+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.
-@node Remote Serial
-@subsection The @value{GDBN} remote serial protocol
+You can use both options together, to make sure the auxiliary symbol
+file has all the symbol information for your program.
-@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:
+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.
-@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.
+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.
-@item
-A C subroutine library to support your program's
-subroutine calls, notably managing input and output.
+@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.
-@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
+@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.
-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:
+@code{core-file} with no argument specifies that no core file is
+to be used.
-@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}).
+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}).
-@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}.
+@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.
-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 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.
-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 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:
-@cindex remote serial stub list
-These working remote stubs are distributed with @value{GDBN}:
+@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
-@table @code
+@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.
-@item i386-stub.c
-@cindex @file{i386-stub.c}
-@cindex Intel
-@cindex i386
-For Intel 386 and compatible architectures.
+@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
-@item m68k-stub.c
-@cindex @file{m68k-stub.c}
-@cindex Motorola 680x0
-@cindex m680x0
-For Motorola 680x0 architectures.
+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}.
-@item sh-stub.c
-@cindex @file{sh-stub.c}
-@cindex Hitachi
-@cindex SH
-For Hitachi SH architectures.
+@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.
-@item sparc-stub.c
-@cindex @file{sparc-stub.c}
-@cindex Sparc
-For @sc{sparc} architectures.
+@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.
-@item sparcl-stub.c
-@cindex @file{sparcl-stub.c}
-@cindex Fujitsu
-@cindex SparcLite
-For Fujitsu @sc{sparclite} architectures.
+@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.
-@end table
+@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 @file{README} file in the @value{GDBN} distribution may list other
-recently added stubs.
+The default is off.
-@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
+@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
-@node Stub Contents
-@subsubsection What the stub can do for you
+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 remote serial stub
-The debugging stub for your architecture supplies these three
-subroutines:
+@cindex shared libraries
+@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
+libraries.
-@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.
+@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 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.
+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.
-@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.
+@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
-@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.
+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.
-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
+To control the automatic loading of shared library symbols, use the
+commands:
-@node Bootstrapping
-@subsubsection What you must do for the stub
+@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}.
-@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.
+@kindex show auto-solib-add
+@item show auto-solib-add
+Display the current autoloading mode.
+@end table
-First of all you need to tell the stub how to communicate with the
-serial port.
+To explicitly load shared library symbols, use the @code{sharedlibrary}
+command:
@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.
+@kindex info sharedlibrary
+@kindex info share
+@item info share
+@itemx info sharedlibrary
+Print the names of the shared libraries which are currently loaded.
-@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.
+@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
-@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.
+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.
-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}).
+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.
-Other routines you need to supply are:
+To display or set the threshold, use the commands:
@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.
+@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).
-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}.
+@kindex show auto-solib-limit
+@item show auto-solib-limit
+Display the current autoloading size threshold, in megabytes.
+@end table
-@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.
+@node Symbol Errors
+@section Errors reading symbol files
-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
+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}).
-@noindent
-You must also make sure this library routine is available:
+The messages currently printed, and their meanings, include:
@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
+@item inner block not inside outer block in @var{symbol}
-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.
+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.
-@node Debug Session
-@subsubsection Putting it all together
+@item block at @var{address} out of order
-@cindex remote serial debugging summary
-In summary, when your program is ready to debug, you must follow these
-steps.
+The symbol information for symbol scope blocks should occur in
+order of increasing addresses. This error indicates that it does not
+do so.
-@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
+@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
-Insert these lines near the top of your program:
+@item bad block start address patched
-@example
-set_debug_traps();
-breakpoint();
-@end example
+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.
-@item
-For the 680x0 stub only, you need to provide a variable called
-@code{exceptionHook}. Normally you just use:
-
-@example
-void (*exceptionHook)() = 0;
-@end example
+@value{GDBN} circumvents the problem by treating the symbol scope block as
+starting on the previous source line.
-@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 bad string table offset in symbol @var{n}
-@item
-Compile and link together: your program, the @value{GDBN} debugging stub for
-your target architecture, and the supporting subroutines.
+@cindex foo
+Symbol number @var{n} contains a pointer into the string table which is
+larger than the size of the string table.
-@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.
+@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
-@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 unknown symbol type @code{0x@var{nn}}
-@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.
+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.
-@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}:
+@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.
-@example
-target remote /dev/ttyb
-@end example
+@item stub type has NULL name
-@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}:
+@value{GDBN} could not find the full definition for a struct or class.
-@example
-target remote manyfarms:2828
-@end example
-@end enumerate
+@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.
-Now you can use all the usual commands to examine and change data and to
-step and continue the remote program.
+@item info mismatch between compiler and debugger
-To resume the remote program and stop debugging it, use the @code{detach}
-command.
+@value{GDBN} could not parse a type specification output by the compiler.
-@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:
+@end table
-@example
-Interrupted while waiting for the program.
-Give up (and stop debugging it)? (y or n)
-@end example
+@node Targets
+@chapter Specifying a Debugging Target
-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.
+@cindex debugging target
+@kindex target
-@node Protocol
-@subsubsection Communication protocol
+A @dfn{target} is the execution environment occupied by your program.
-@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.)
+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}).
-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}.
+@menu
+* Active Targets:: Active targets
+* Target Commands:: Commands for managing targets
+* Byte Order:: Choosing target byte order
+* Remote:: Remote debugging
+* KOD:: Kernel Object Display
-In the examples below, @samp{<-} and @samp{->} are used to indicate
-transmitted and received data respectfully.
+@end menu
-@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 Active Targets
+@section Active targets
-@example
-@code{$}@var{packet-data}@code{#}@var{checksum}
-@end example
-@noindent
+@cindex stacking targets
+@cindex active targets
+@cindex multiple targets
-@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).
+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.
-Implementors should note that prior to @value{GDBN} 5.0 the protocol
-specification also included an optional two-digit @var{sequence-id}:
+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.)
-@example
-@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
-@end example
+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.
-@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}.
+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}).
-@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):
+@node Target Commands
+@section Commands for managing targets
-@example
-<- @code{$}@var{packet-data}@code{#}@var{checksum}
--> @code{+}
-@end example
-@noindent
+@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.
-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).
+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.
-@var{packet-data} consists of a sequence of characters with the
-exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
-exceptions).
+The @code{target} command does not repeat if you press @key{RET} again
+after executing the command.
-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 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}).
-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}).
+@item help target @var{name}
+Describe a particular target, including any parameters necessary to
+select it.
-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.
+@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.
-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.
+@quotation
+@emph{Warning:} To specify a file format with @code{set gnutarget},
+you must know the actual BFD name.
+@end quotation
-So:
-@example
-"@code{0* }"
-@end example
@noindent
-means the same as "0000".
-
-The error response returned for some packets includes a two character
-error number. That number is not well defined.
+@xref{Files, , Commands to specify files}.
-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.
+@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
-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.
+Here are some common targets (available, or not, depending on the GDB
+configuration):
-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.
+@table @code
+@kindex target exec
+@item target exec @var{program}
+An executable file. @samp{target exec @var{program}} is the same as
+@samp{exec-file @var{program}}.
-@item 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
+@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.
-@item reserved
-@tab @code{a}
-@tab Reserved for future use
+@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}.
-@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}
+@end table
-@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.}
+Some configurations may include these targets as well:
-@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 nrom
+@item target nrom @var{dev}
+NetROM ROM emulator. This target only supports downloading.
-@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.
+Different targets are available on different configurations of @value{GDBN};
+your configuration may have more or fewer targets.
-@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.
+Many remote targets require you to download the executable's code
+once you've successfully established a connection.
-@item reserved
-@tab @code{e}
-@tab Reserved for future use
+@table @code
-@item reserved
-@tab @code{E}
-@tab Reserved for future use
+@kindex load @var{filename}
+@item load @var{filename}
+Depending on what remote debugging facilities are configured into
+@value{GDBN}, the @code{load} command may be available. Where it exists, it
+is meant to make @var{filename} (an executable) available for debugging
+on the remote system---by downloading, or dynamic linking, for example.
+@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
+the @code{add-symbol-file} command.
-@item reserved
-@tab @code{f}
-@tab Reserved for future use
+If your @value{GDBN} does not have a @code{load} command, attempting to
+execute it gets the error message ``@code{You can't do that when your
+target is @dots{}}''
-@item reserved
-@tab @code{F}
-@tab Reserved for future use
+The file is loaded at whatever address is specified in the executable.
+For some object file formats, you can specify the load address when you
+link the program; for other formats, like a.out, the object file format
+specifies a fixed address.
+@c FIXME! This would be a good place for an xref to the GNU linker doc.
-@item 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.
+@code{load} does not repeat if you press @key{RET} again after using it.
+@end table
-@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
+@node Byte Order
+@section Choosing target byte order
-@item reserved
-@tab @code{h}
-@tab Reserved for future use
+@cindex choosing target byte order
+@cindex target byte order
-@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
+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.
-@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.
+@table @code
+@kindex set endian big
+@item set endian big
+Instruct @value{GDBN} to assume the target is big-endian.
-@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 set endian little
+@item set endian little
+Instruct @value{GDBN} to assume the target is little-endian.
-@item signal then cycle step @strong{(reserved)}
-@tab @code{I}
-@tab
-See @samp{i} and @samp{S} for likely syntax and semantics.
+@kindex set endian auto
+@item set endian auto
+Instruct @value{GDBN} to use the byte order associated with the
+executable.
-@item reserved
-@tab @code{j}
-@tab Reserved for future use
+@item show endian
+Display @value{GDBN}'s current idea of the target byte order.
-@item reserved
-@tab @code{J}
-@tab Reserved for future use
+@end table
-@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?)}.
+Note that these commands merely adjust interpretation of symbolic
+data on the host, and that they have absolutely no effect on the
+target system.
-@item reserved
-@tab @code{l}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{L}
-@tab Reserved for future use
+@node Remote
+@section Remote debugging
+@cindex remote debugging
-@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
+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.
-@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).
+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}.
-@item reserved
-@tab @code{n}
-@tab Reserved for future use
+Other remote targets may be available in your
+configuration of @value{GDBN}; use @code{help target} to list them.
-@item reserved
-@tab @code{N}
-@tab Reserved for future use
+@node KOD
+@section Kernel Object Display
-@item reserved
-@tab @code{o}
-@tab Reserved for future use
+@cindex kernel object display
+@cindex kernel object
+@cindex KOD
-@item reserved
-@tab @code{O}
-@tab Reserved for future use
+Some targets support kernel object display. Using this facility,
+@value{GDBN} communicates specially with the underlying operating system
+and can display information about operating system-level objects such as
+mutexes and other synchronization objects. Exactly which objects can be
+displayed is determined on a per-OS basis.
-@item 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.
+Use the @code{set os} command to set the operating system. This tells
+@value{GDBN} which kernel object display module to initialize:
-@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
+@smallexample
+(@value{GDBP}) set os cisco
+@end smallexample
-@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}.
+If @code{set os} succeeds, @value{GDBN} will display some information
+about the operating system, and will create a new @code{info} command
+which can be used to query the target. The @code{info} command is named
+after the operating system:
-@item 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.
+@smallexample
+(@value{GDBP}) info cisco
+List of Cisco Kernel Objects
+Object Description
+any Any and all objects
+@end smallexample
-@item reset @strong{(deprecated)}
-@tab @code{r}
-@tab
-Reset the entire system.
+Further subcommands can be used to query about particular objects known
+by the kernel.
-@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}.
+There is currently no way to determine whether a given operating system
+is supported other than to try it.
-@item step
-@tab @code{s}@var{addr}
-@tab
-@var{addr} is address to resume. If @var{addr} is omitted, resume at
-same address.
-@item
-@tab reply
-@tab see below
-@item step with signal
-@tab @code{S}@var{sig}@code{;}@var{addr}
-@tab
-Like @samp{C} but step not continue.
-@item
-@tab reply
-@tab see below
+@node Remote Debugging
+@chapter Debugging remote programs
-@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.
+@menu
+* Server:: Using the gdbserver program
+* NetWare:: Using the gdbserve.nlm program
+* remote stub:: Implementing a remote stub
+@end menu
-@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
+@node Server
+@section Using the @code{gdbserver} program
-@item reserved
-@tab @code{u}
-@tab Reserved for future use
+@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.
-@item reserved
-@tab @code{U}
-@tab Reserved for future use
+@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.
-@item reserved
-@tab @code{v}
-@tab Reserved for future use
+@value{GDBN} and @code{gdbserver} communicate via either a serial line
+or a TCP connection, using the standard @value{GDBN} remote serial
+protocol.
-@item reserved
-@tab @code{V}
-@tab Reserved for future use
+@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 reserved
-@tab @code{w}
-@tab Reserved for future use
+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:
-@item reserved
-@tab @code{W}
-@tab Reserved for future use
+@smallexample
+target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
+@end smallexample
-@item reserved
-@tab @code{x}
-@tab Reserved for future use
+@var{comm} is either a device name (to use a serial line) or a TCP
+hostname and portnumber. For example, to debug Emacs with the argument
+@samp{foo.txt} and communicate with @value{GDBN} over the serial port
+@file{/dev/com1}:
-@item 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
+@smallexample
+target> gdbserver /dev/com1 emacs foo.txt
+@end smallexample
-@item reserved
-@tab @code{y}
-@tab Reserved for future use
+@code{gdbserver} waits passively for the host @value{GDBN} to communicate
+with it.
-@item reserved
-@tab @code{Y}
-@tab Reserved for future use
+To use a TCP connection instead of a serial line:
-@item remove break or watchpoint @strong{(draft)}
-@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
-@tab
-See @samp{Z}.
+@smallexample
+target> gdbserver host:2345 emacs foo.txt
+@end smallexample
-@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.
+The only difference from the previous example is the first argument,
+specifying that you are communicating with the host @value{GDBN} via
+TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
+expect a TCP connection from machine @samp{host} to local TCP port 2345.
+(Currently, the @samp{host} part is ignored.) You can choose any number
+you want for the port number as long as it does not conflict with any
+TCP ports already in use on the target system (for example, @code{23} is
+reserved for @code{telnet}).@footnote{If you choose a port number that
+conflicts with another service, @code{gdbserver} prints an error message
+and exits.} You must use the same port number with the host @value{GDBN}
+@code{target remote} command.
-@item reserved
-@tab <other>
-@tab Reserved for future use
+On some targets, @code{gdbserver} can also attach to running programs.
+This is accomplished via the @code{--attach} argument. The syntax is:
-@end multitable
+@smallexample
+target> gdbserver @var{comm} --attach @var{pid}
+@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.
+@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.
-@multitable @columnfractions .4 .6
+@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 @code{S}@var{AA}
-@tab @var{AA} is the signal number
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@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.
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and
-@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.
+@smallexample
+(@value{GDBP}) target remote the-target:2345
+@end smallexample
-@item @code{X}@var{AA}
-@tab
-The process terminated with signal @var{AA}.
+@noindent
+communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
+For TCP connections, you must start up @code{gdbserver} prior to using
+the @code{target remote} command. Otherwise you may get an error whose
+text depends on the host system, but which usually looks something like
+@samp{Connection refused}.
+@end table
-@item @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.}
+@node NetWare
+@section Using the @code{gdbserve.nlm} program
-@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.
+@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}.
-@end multitable
+@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
+using the standard @value{GDBN} remote serial protocol.
-The following set and query packets have already been defined.
+@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.
-@multitable @columnfractions .2 .2 .6
+To use the server, you must tell it how to communicate with
+@value{GDBN}; the name of your program; and the arguments for your
+program. The syntax is:
-@item 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.
+@smallexample
+load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
+ [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
+@end smallexample
-@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'}).
+@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}.
-@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.
+For example, to debug Emacs with the argument @samp{foo.txt}and
+communicate with @value{GDBN} over serial port number 2 or board 1
+using a 19200@dmn{bps} connection:
-@item 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
+load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
+@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.
+@item On the @value{GDBN} host machine,
+you need an unstripped copy of your program, since @value{GDBN} needs
+symbols and debugging information. Start up @value{GDBN} as usual,
+using the name of the local copy of your program as the first argument.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600@dmn{bps}. After that, use @code{target
+remote} to establish communications with @code{gdbserve.nlm}. Its
+argument is a device name (usually a serial device, like
+@file{/dev/ttyb}). For example:
-@item 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}
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
-@item thread info request
-@tab @code{q}@code{P}@var{mode}@var{threadid}
-@tab
+@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
-@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.
+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
-@tab reply *
-@tab
-See @code{remote.c:remote_unpack_thread_info_response()}.
+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 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}: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:
+
+@smallexample
+target remote :1234
+@end smallexample
+@noindent
+
+Note that the colon is still required here.
+@end enumerate
+
+Now you can use all the usual commands to examine and change data and to
+step and continue the remote program.
+
+To resume the remote program and stop debugging it, use the @code{detach}
+command.
+
+@cindex interrupting remote programs
+@cindex remote programs, interrupting
+Whenever @value{GDBN} is waiting for the remote program, if you type the
+interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
+program. This may or may not succeed, depending in part on the hardware
+and the serial drivers the remote system uses. If you type the
+interrupt character once again, @value{GDBN} displays this prompt:
+
+@smallexample
+Interrupted while waiting for the program.
+Give up (and stop debugging it)? (y or n)
+@end smallexample
+
+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.
+
+
+@node Configurations
+@chapter Configuration-Specific Information
+
+While nearly all @value{GDBN} commands are available for all native and
+cross versions of the debugger, there are some exceptions. This chapter
+describes things that are only available in certain configurations.
+
+There are three major categories of configurations: native
+configurations, where the host and target are the same, embedded
+operating system configurations, which are usually the same for several
+different processor architectures, and bare embedded processors, which
+are quite different from each other.
+
+@menu
+* Native::
+* Embedded OS::
+* Embedded Processors::
+* Architectures::
+@end menu
+
+@node Native
+@section Native
+
+This section describes details specific to particular native
+configurations.
+
+@menu
+* HP-UX:: HP-UX
+* SVR4 Process Information:: SVR4 process information
+* DJGPP Native:: Features specific to the DJGPP port
+* Cygwin Native:: Features specific to the Cygwin port
+@end menu
+
+@node HP-UX
+@subsection HP-UX
+
+On HP-UX systems, if you refer to a function or variable name that
+begins with a dollar sign, @value{GDBN} searches for a user or system
+name first, before it searches for a convenience variable.
+
+@node SVR4 Process Information
+@subsection SVR4 process information
+
+@kindex /proc
+@cindex process image
+
+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.
+
+@table @code
+@kindex info proc
+@item info proc
+Summarize available information about the process.
+
+@kindex info proc mappings
+@item info proc mappings
+Report on the address ranges accessible in the program, with information
+on whether your program may read, write, or execute each range.
+@ignore
+@comment These sub-options of 'info proc' were not included when
+@comment procfs.c was re-written. Keep their descriptions around
+@comment against the day when someone finds the time to put them back in.
+@kindex info proc times
+@item info proc times
+Starting time, user CPU time, and system CPU time for your program and
+its children.
+
+@kindex info proc id
+@item info proc id
+Report on the process IDs related to your program: its own process ID,
+the ID of its parent, the process group ID, and the session ID.
+
+@kindex info proc status
+@item info proc status
+General information on the state of the process. If the process is
+stopped, this report includes the reason for stopping, and any signal
+received.
+
+@item info proc all
+Show all the above information about the process.
+@end ignore
+@end table
+
+@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:
+
+@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
+
+@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
+
+@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.
+
+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
+
+@value{GDBN} includes the ability to debug programs running on
+various real-time operating systems.
+
+@node VxWorks
+@subsection Using @value{GDBN} with VxWorks
+
+@cindex VxWorks
+
+@table @code
+
+@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.
+
+@end table
+
+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 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
+
+The following information on connecting to VxWorks was current when
+this manual was produced; newer releases of VxWorks may use revised
+procedures.
+
+@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}.
+
+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).
+
+@value{GDBN} comes up showing the prompt:
+
+@smallexample
+(vxgdb)
+@end smallexample
+
+@menu
+* VxWorks Connection:: Connecting to VxWorks
+* VxWorks Download:: VxWorks download
+* VxWorks Attach:: Running tasks
+@end menu
+
+@node VxWorks Connection
+@subsubsection Connecting to VxWorks
+
+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:
+
+@smallexample
+(vxgdb) target vxworks tt
+@end smallexample
+
+@need 750
+@value{GDBN} displays messages like these:
+
+@smallexample
+Attaching remote machine across net...
+Connected to tt.
+@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:
+
+@smallexample
+prog.o: No such file or directory.
+@end smallexample
+
+When this happens, add the appropriate directory to the search path with
+the @value{GDBN} command @code{path}, and execute the @code{target}
+command again.
+
+@node VxWorks Download
+@subsubsection VxWorks download
+
+@cindex download to VxWorks
+If you have connected to the VxWorks target and you want to debug an
+object that has not yet been loaded, you can use the @value{GDBN}
+@code{load} command to download a file from Unix to VxWorks
+incrementally. The object file given as an argument to the @code{load}
+command is actually opened twice: first by the VxWorks target in order
+to download the code, then by @value{GDBN} in order to read the symbol
+table. This can lead to problems if the current working directories on
+the two systems differ. If both systems have NFS mounted the same
+filesystems, you can avoid these problems by using absolute paths.
+Otherwise, it is simplest to set the working directory on both systems
+to the directory in which the object file resides, and then to reference
+the file by its name, without any path. For instance, a program
+@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
+and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
+program, type this on VxWorks:
+
+@smallexample
+-> cd "@var{vxpath}/vw/demo/rdb"
+@end smallexample
+
+@noindent
+Then, in @value{GDBN}, type:
+
+@smallexample
+(vxgdb) cd @var{hostpath}/vw/demo/rdb
+(vxgdb) load prog.o
+@end smallexample
+
+@value{GDBN} displays a response similar to this:
+
+@smallexample
+Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
+@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.)
+
+@node VxWorks Attach
+@subsubsection Running tasks
+
+@cindex running VxWorks tasks
+You can also attach to an existing task using the @code{attach} command as
+follows:
+
+@smallexample
+(vxgdb) attach @var{task}
+@end smallexample
+
+@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.
+
+@node Embedded Processors
+@section Embedded Processors
+
+This section goes into details specific to particular embedded
+configurations.
+
+
+@c OBSOLETE * A29K Embedded:: AMD A29K Embedded
+@menu
+* ARM:: ARM
+* H8/300:: Hitachi H8/300
+* H8/500:: Hitachi H8/500
+* i960:: Intel i960
+* M32R/D:: Mitsubishi M32R/D
+* M68K:: Motorola M68K
+* M88K:: Motorola M88K
+* MIPS Embedded:: MIPS Embedded
+* PA:: HP PA Embedded
+* PowerPC: PowerPC
+* SH:: Hitachi SH
+* Sparclet:: Tsqware Sparclet
+* Sparclite:: Fujitsu Sparclite
+* ST2000:: Tandem ST2000
+* Z8000:: Zilog Z8000
+@end menu
+
+@c OBSOLETE @node A29K Embedded
+@c OBSOLETE @subsection AMD A29K Embedded
+@c OBSOLETE
+@c OBSOLETE @menu
+@c OBSOLETE * A29K UDI::
+@c OBSOLETE * A29K EB29K::
+@c OBSOLETE * Comms (EB29K):: Communications setup
+@c OBSOLETE * gdb-EB29K:: EB29K cross-debugging
+@c OBSOLETE * Remote Log:: Remote log
+@c OBSOLETE @end menu
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE
+@c OBSOLETE @kindex target adapt
+@c OBSOLETE @item target adapt @var{dev}
+@c OBSOLETE Adapt monitor for A29K.
+@c OBSOLETE
+@c OBSOLETE @kindex target amd-eb
+@c OBSOLETE @item target amd-eb @var{dev} @var{speed} @var{PROG}
+@c OBSOLETE @cindex AMD EB29K
+@c OBSOLETE Remote PC-resident AMD EB29K board, attached over serial lines.
+@c OBSOLETE @var{dev} is the serial device, as for @code{target remote};
+@c OBSOLETE @var{speed} allows you to specify the linespeed; and @var{PROG} is the
+@c OBSOLETE name of the program to be debugged, as it appears to DOS on the PC.
+@c OBSOLETE @xref{A29K EB29K, ,EBMON protocol for AMD29K}.
+@c OBSOLETE
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node A29K UDI
+@c OBSOLETE @subsubsection A29K UDI
+@c OBSOLETE
+@c OBSOLETE @cindex UDI
+@c OBSOLETE @cindex AMD29K via UDI
+@c OBSOLETE
+@c OBSOLETE @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
+@c OBSOLETE protocol for debugging the a29k processor family. To use this
+@c OBSOLETE configuration with AMD targets running the MiniMON monitor, you need the
+@c OBSOLETE program @code{MONTIP}, available from AMD at no charge. You can also
+@c OBSOLETE use @value{GDBN} with the UDI-conformant a29k simulator program
+@c OBSOLETE @code{ISSTIP}, also available from AMD.
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE @item target udi @var{keyword}
+@c OBSOLETE @kindex udi
+@c OBSOLETE Select the UDI interface to a remote a29k board or simulator, where
+@c OBSOLETE @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
+@c OBSOLETE This file contains keyword entries which specify parameters used to
+@c OBSOLETE connect to a29k targets. If the @file{udi_soc} file is not in your
+@c OBSOLETE working directory, you must set the environment variable @samp{UDICONF}
+@c OBSOLETE to its pathname.
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node A29K EB29K
+@c OBSOLETE @subsubsection EBMON protocol for AMD29K
+@c OBSOLETE
+@c OBSOLETE @cindex EB29K board
+@c OBSOLETE @cindex running 29K programs
+@c OBSOLETE
+@c OBSOLETE AMD distributes a 29K development board meant to fit in a PC, together
+@c OBSOLETE with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
+@c OBSOLETE term, this development system is called the ``EB29K''. To use
+@c OBSOLETE @value{GDBN} from a Unix system to run programs on the EB29K board, you
+@c OBSOLETE must first connect a serial cable between the PC (which hosts the EB29K
+@c OBSOLETE board) and a serial port on the Unix system. In the following, we
+@c OBSOLETE assume you've hooked the cable between the PC's @file{COM1} port and
+@c OBSOLETE @file{/dev/ttya} on the Unix system.
+@c OBSOLETE
+@c OBSOLETE @node Comms (EB29K)
+@c OBSOLETE @subsubsection Communications setup
+@c OBSOLETE
+@c OBSOLETE The next step is to set up the PC's port, by doing something like this
+@c OBSOLETE in DOS on the PC:
+@c OBSOLETE
+@c OBSOLETE @smallexample
+@c OBSOLETE C:\> MODE com1:9600,n,8,1,none
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE This example---run on an MS DOS 4.0 system---sets the PC port to 9600
+@c OBSOLETE bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
+@c OBSOLETE you must match the communications parameters when establishing the Unix
+@c OBSOLETE end of the connection as well.
+@c OBSOLETE @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
+@c OBSOLETE @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
+@c OBSOLETE @c
+@c OBSOLETE @c It's optional, but it's unwise to omit it: who knows what is the
+@c OBSOLETE @c default value set when the DOS machines boots? "No retry" means that
+@c OBSOLETE @c the DOS serial device driver won't retry the operation if it fails;
+@c OBSOLETE @c I understand that this is needed because the GDB serial protocol
+@c OBSOLETE @c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99
+@c OBSOLETE
+@c OBSOLETE To give control of the PC to the Unix side of the serial line, type
+@c OBSOLETE the following at the DOS console:
+@c OBSOLETE
+@c OBSOLETE @smallexample
+@c OBSOLETE C:\> CTTY com1
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE (Later, if you wish to return control to the DOS console, you can use
+@c OBSOLETE the command @code{CTTY con}---but you must send it over the device that
+@c OBSOLETE had control, in our example over the @file{COM1} serial line.)
+@c OBSOLETE
+@c OBSOLETE From the Unix host, use a communications program such as @code{tip} or
+@c OBSOLETE @code{cu} to communicate with the PC; for example,
+@c OBSOLETE
+@c OBSOLETE @smallexample
+@c OBSOLETE cu -s 9600 -l /dev/ttya
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE The @code{cu} options shown specify, respectively, the linespeed and the
+@c OBSOLETE serial port to use. If you use @code{tip} instead, your command line
+@c OBSOLETE may look something like the following:
+@c OBSOLETE
+@c OBSOLETE @smallexample
+@c OBSOLETE tip -9600 /dev/ttya
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE Your system may require a different name where we show
+@c OBSOLETE @file{/dev/ttya} as the argument to @code{tip}. The communications
+@c OBSOLETE parameters, including which port to use, are associated with the
+@c OBSOLETE @code{tip} argument in the ``remote'' descriptions file---normally the
+@c OBSOLETE system table @file{/etc/remote}.
+@c OBSOLETE @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
+@c OBSOLETE @c the DOS side's comms setup? cu can support -o (odd
+@c OBSOLETE @c parity), -e (even parity)---apparently no settings for no parity or
+@c OBSOLETE @c for character size. Taken from stty maybe...? John points out tip
+@c OBSOLETE @c can set these as internal variables, eg ~s parity=none; man stty
+@c OBSOLETE @c suggests that it *might* work to stty these options with stdin or
+@c OBSOLETE @c stdout redirected... ---doc@cygnus.com, 25feb91
+@c OBSOLETE @c
+@c OBSOLETE @c There's nothing to be done for the "none" part of the DOS MODE
+@c OBSOLETE @c command. The rest of the parameters should be matched by the
+@c OBSOLETE @c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99
+@c OBSOLETE
+@c OBSOLETE @kindex EBMON
+@c OBSOLETE Using the @code{tip} or @code{cu} connection, change the DOS working
+@c OBSOLETE directory to the directory containing a copy of your 29K program, then
+@c OBSOLETE start the PC program @code{EBMON} (an EB29K control program supplied
+@c OBSOLETE with your board by AMD). You should see an initial display from
+@c OBSOLETE @code{EBMON} similar to the one that follows, ending with the
+@c OBSOLETE @code{EBMON} prompt @samp{#}---
+@c OBSOLETE
+@c OBSOLETE @smallexample
+@c OBSOLETE C:\> G:
+@c OBSOLETE
+@c OBSOLETE G:\> CD \usr\joe\work29k
+@c OBSOLETE
+@c OBSOLETE G:\USR\JOE\WORK29K> EBMON
+@c OBSOLETE Am29000 PC Coprocessor Board Monitor, version 3.0-18
+@c OBSOLETE Copyright 1990 Advanced Micro Devices, Inc.
+@c OBSOLETE Written by Gibbons and Associates, Inc.
+@c OBSOLETE
+@c OBSOLETE Enter '?' or 'H' for help
+@c OBSOLETE
+@c OBSOLETE PC Coprocessor Type = EB29K
+@c OBSOLETE I/O Base = 0x208
+@c OBSOLETE Memory Base = 0xd0000
+@c OBSOLETE
+@c OBSOLETE Data Memory Size = 2048KB
+@c OBSOLETE Available I-RAM Range = 0x8000 to 0x1fffff
+@c OBSOLETE Available D-RAM Range = 0x80002000 to 0x801fffff
+@c OBSOLETE
+@c OBSOLETE PageSize = 0x400
+@c OBSOLETE Register Stack Size = 0x800
+@c OBSOLETE Memory Stack Size = 0x1800
+@c OBSOLETE
+@c OBSOLETE CPU PRL = 0x3
+@c OBSOLETE Am29027 Available = No
+@c OBSOLETE Byte Write Available = Yes
+@c OBSOLETE
+@c OBSOLETE # ~.
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE Then exit the @code{cu} or @code{tip} program (done in the example by
+@c OBSOLETE typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
+@c OBSOLETE running, ready for @value{GDBN} to take over.
+@c OBSOLETE
+@c OBSOLETE For this example, we've assumed what is probably the most convenient
+@c OBSOLETE way to make sure the same 29K program is on both the PC and the Unix
+@c OBSOLETE system: a PC/NFS connection that establishes ``drive @file{G:}'' on the
+@c OBSOLETE PC as a file system on the Unix host. If you do not have PC/NFS or
+@c OBSOLETE something similar connecting the two systems, you must arrange some
+@c OBSOLETE other way---perhaps floppy-disk transfer---of getting the 29K program
+@c OBSOLETE from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
+@c OBSOLETE serial line.
+@c OBSOLETE
+@c OBSOLETE @node gdb-EB29K
+@c OBSOLETE @subsubsection EB29K cross-debugging
+@c OBSOLETE
+@c OBSOLETE Finally, @code{cd} to the directory containing an image of your 29K
+@c OBSOLETE program on the Unix system, and start @value{GDBN}---specifying as argument the
+@c OBSOLETE name of your 29K program:
+@c OBSOLETE
+@c OBSOLETE @smallexample
+@c OBSOLETE cd /usr/joe/work29k
+@c OBSOLETE @value{GDBP} myfoo
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @need 500
+@c OBSOLETE Now you can use the @code{target} command:
+@c OBSOLETE
+@c OBSOLETE @smallexample
+@c OBSOLETE target amd-eb /dev/ttya 9600 MYFOO
+@c OBSOLETE @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
+@c OBSOLETE @c emphasize that this is the name as seen by DOS (since I think DOS is
+@c OBSOLETE @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
+@c OBSOLETE @end smallexample
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE In this example, we've assumed your program is in a file called
+@c OBSOLETE @file{myfoo}. Note that the filename given as the last argument to
+@c OBSOLETE @code{target amd-eb} should be the name of the program as it appears to DOS.
+@c OBSOLETE In our example this is simply @code{MYFOO}, but in general it can include
+@c OBSOLETE a DOS path, and depending on your transfer mechanism may not resemble
+@c OBSOLETE the name on the Unix side.
+@c OBSOLETE
+@c OBSOLETE At this point, you can set any breakpoints you wish; when you are ready
+@c OBSOLETE to see your program run on the 29K board, use the @value{GDBN} command
+@c OBSOLETE @code{run}.
+@c OBSOLETE
+@c OBSOLETE To stop debugging the remote program, use the @value{GDBN} @code{detach}
+@c OBSOLETE command.
+@c OBSOLETE
+@c OBSOLETE To return control of the PC to its console, use @code{tip} or @code{cu}
+@c OBSOLETE once again, after your @value{GDBN} session has concluded, to attach to
+@c OBSOLETE @code{EBMON}. You can then type the command @code{q} to shut down
+@c OBSOLETE @code{EBMON}, returning control to the DOS command-line interpreter.
+@c OBSOLETE Type @kbd{CTTY con} to return command input to the main DOS console,
+@c OBSOLETE and type @kbd{~.} to leave @code{tip} or @code{cu}.
+@c OBSOLETE
+@c OBSOLETE @node Remote Log
+@c OBSOLETE @subsubsection Remote log
+@c OBSOLETE @cindex @file{eb.log}, a log file for EB29K
+@c OBSOLETE @cindex log file for EB29K
+@c OBSOLETE
+@c OBSOLETE The @code{target amd-eb} command creates a file @file{eb.log} in the
+@c OBSOLETE current working directory, to help debug problems with the connection.
+@c OBSOLETE @file{eb.log} records all the output from @code{EBMON}, including echoes
+@c OBSOLETE of the commands sent to it. Running @samp{tail -f} on this file in
+@c OBSOLETE another window often helps to understand trouble with @code{EBMON}, or
+@c OBSOLETE unexpected events on the PC side of the connection.
+
+@node ARM
+@subsection ARM
+
+@table @code
+
+@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
+
+@node H8/300
+@subsection Hitachi H8/300
+
+@table @code
+
+@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.
-@item remote command
-@tab @code{q}@code{Rcmd,}@var{COMMAND}
-@tab
+@kindex target e7000@r{, with H8/300}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi H8 and SH.
+
+@kindex target sh3@r{, with H8/300}
+@kindex target sh3e@r{, with H8/300}
+@item target sh3 @var{dev}
+@itemx target sh3e @var{dev}
+Hitachi SH-3 and SH-3E target systems.
+
+@end table
+
+@cindex download to H8/300 or H8/500
+@cindex H8/300 or H8/500 download
+@cindex download to Hitachi SH
+@cindex Hitachi SH download
+When you select remote debugging to a Hitachi SH, H8/300, or H8/500
+board, the @code{load} command downloads your program to the Hitachi
+board and also opens it as the current executable target for
+@value{GDBN} on your host (like the @code{file} command).
+
+@value{GDBN} needs to know these things to talk to your
+Hitachi SH, H8/300, or H8/500:
+
+@enumerate
@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}.
+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
-@tab reply @code{OK}
-@tab
-A command response with no output.
+what serial device connects your host to your Hitachi board (the first
+serial device available on your host is the default).
+
@item
-@tab reply @var{OUTPUT}
-@tab
-A command response with the hex encoded output string @var{OUTPUT}.
+what speed to use over the serial device.
+@end enumerate
+
+@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
+
+@node Hitachi Boards
+@subsubsection Connecting to Hitachi boards
+
+@c only for Unix hosts
+@kindex device
+@cindex serial device, Hitachi micros
+Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
+need to explicitly set the serial device. The default @var{port} is the
+first available port on your host. This is only necessary on Unix
+hosts, where it is typically something like @file{/dev/ttya}.
+
+@kindex speed
+@cindex serial line speed, Hitachi micros
+@code{@value{GDBN}} has another special command to set the communications
+speed: @samp{speed @var{bps}}. This command also is only used from Unix
+hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
+the DOS @code{mode} command (for instance,
+@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection).
+
+The @samp{device} and @samp{speed} commands are available only when you
+use a Unix host to debug your Hitachi microprocessor programs. If you
+use a DOS host,
+@value{GDBN} depends on an auxiliary terminate-and-stay-resident program
+called @code{asynctsr} to communicate with the development board
+through a PC serial port. You must also use the DOS @code{mode} command
+to set up the serial port on the DOS side.
+
+The following sample session illustrates the steps needed to start a
+program under @value{GDBN} control on an H8/300. The example uses a
+sample H8/300 program called @file{t.x}. The procedure is the same for
+the Hitachi SH and the H8/500.
+
+First hook up your development board. In this example, we use a
+board attached to serial port @code{COM2}; if you use a different serial
+port, substitute its name in the argument of the @code{mode} command.
+When you call @code{asynctsr}, the auxiliary comms program used by the
+debugger, you give it just the numeric part of the serial port's name;
+for example, @samp{asyncstr 2} below runs @code{asyncstr} on
+@code{COM2}.
+
+@smallexample
+C:\H8300\TEST> asynctsr 2
+C:\H8300\TEST> mode com2:9600,n,8,1,p
+
+Resident portion of MODE loaded
+
+COM2: 9600, n, 8, 1, p
+
+@end smallexample
+
+@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
+
+@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}.)
+
+@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
+
+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.
+
+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!
+
+Use the @sc{reset} button on the development board
+@itemize @bullet
@item
-@tab reply @code{E}@var{NN}
-@tab
-Indicate a badly formed request.
+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
@item
-@tab reply @samp{}
-@tab
-When @samp{q}@samp{Rcmd} is not recognized.
+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
-@end multitable
+In either case, @value{GDBN} sees the effect of a @sc{reset} on the
+development board as a ``normal exit'' of your program.
-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.
+@node Hitachi ICE
+@subsubsection Using the E7000 in-circuit emulator
-@multitable @columnfractions .5 .5
+@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 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 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 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}.
+@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
-@end multitable
+@node Hitachi Special
+@subsubsection Special @value{GDBN} commands for Hitachi micros
-Example sequence of a target being re-started. Notice how the restart
-does not get any direct output:
+Some @value{GDBN} commands are available only for the H8/300:
-@example
-<- @code{R00}
--> @code{+}
-@emph{target restarts}
-<- @code{?}
--> @code{+}
--> @code{T001:1234123412341234}
-<- @code{+}
-@end example
+@table @code
-Example sequence of a target being stepped by a single instruction:
+@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.
-@example
-<- @code{G1445...}
--> @code{+}
-<- @code{s}
--> @code{+}
-@emph{time passes}
--> @code{T001:1234123412341234}
-<- @code{+}
-<- @code{g}
--> @code{+}
--> @code{1455...}
-<- @code{+}
-@end example
+@end table
+
+@node H8/500
+@subsection H8/500
+
+@table @code
+
+@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}.
-@node Server
-@subsubsection Using the @code{gdbserver} program
+@end table
-@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.
+@node i960
+@subsection Intel i960
-@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.
+@table @code
-@value{GDBN} and @code{gdbserver} communicate via either a serial line
-or a TCP connection, using the standard @value{GDBN} remote serial
-protocol.
+@kindex target mon960
+@item target mon960 @var{dev}
+MON960 monitor for Intel i960.
-@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.
+@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}.
-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:
+@end table
-@smallexample
-target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
-@end smallexample
+@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:
-@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}:
+@itemize @bullet
+@item
+Through command line options specifying serial port, version of the
+Nindy protocol, and communications speed;
-@smallexample
-target> gdbserver /dev/com1 emacs foo.txt
-@end smallexample
+@item
+By responding to a prompt on startup;
-@code{gdbserver} waits passively for the host @value{GDBN} to communicate
-with it.
+@item
+By using the @code{target} command at any point during your @value{GDBN}
+session. @xref{Target Commands, ,Commands for managing targets}.
-To use a TCP connection instead of a serial line:
+@end itemize
-@smallexample
-target> gdbserver host:2345 emacs foo.txt
-@end smallexample
+@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}.
-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.
+@menu
+* Nindy Startup:: Startup with Nindy
+* Nindy Options:: Options for Nindy
+* Nindy Reset:: Nindy reset command
+@end menu
-@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:
+@node Nindy Startup
+@subsubsection Startup with Nindy
+
+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:
@smallexample
-(@value{GDBP}) target remote /dev/ttyb
+Attach /dev/ttyNN -- specify NN, or "quit" to quit:
@end smallexample
@noindent
-communicates with the server via serial line @file{/dev/ttyb}, and
+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}).
-@smallexample
-(@value{GDBP}) target remote the-target:2345
-@end smallexample
+@node Nindy Options
+@subsubsection Options for Nindy
-@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
+These are the startup options for beginning your @value{GDBN} session with a
+Nindy-960 board attached:
-@node NetWare
-@subsubsection Using the @code{gdbserve.nlm} program
+@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}).
-@kindex gdbserve.nlm
-@code{gdbserve.nlm} is a control program for NetWare systems, which
-allows you to connect your program with a remote @value{GDBN} via
-@code{target remote}.
+@item -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.
-@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
-using the standard @value{GDBN} remote serial protocol.
+@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
-@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.
+@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.
-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:
+@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
-@smallexample
-load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
- [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
-@end smallexample
+The standard @samp{-b} option controls the line speed used on the serial
+port.
-@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}.
+@c @group
+@node Nindy Reset
+@subsubsection Nindy reset command
-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:
+@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
-@smallexample
-load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
-@end smallexample
+@node M32R/D
+@subsection Mitsubishi M32R/D
-@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:
+@table @code
-@smallexample
-(@value{GDBP}) target remote /dev/ttyb
-@end smallexample
+@kindex target m32r
+@item target m32r @var{dev}
+Mitsubishi M32R/D ROM monitor.
-@noindent
-communications with the server via serial line @file{/dev/ttyb}.
@end table
-@node KOD
-@section Kernel Object Display
+@node M68K
+@subsection M68k
-@cindex kernel object display
-@cindex kernel object
-@cindex KOD
+The Motorola m68k configuration includes ColdFire support, and
+target command for the following ROM monitors.
-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.
+@table @code
-Use the @code{set os} command to set the operating system. This tells
-@value{GDBN} which kernel object display module to initialize:
+@kindex target abug
+@item target abug @var{dev}
+ABug ROM monitor for M68K.
-@example
-(@value{GDBP}) set os cisco
-@end example
+@kindex target cpu32bug
+@item target cpu32bug @var{dev}
+CPU32BUG monitor, running on a CPU32 (M68K) board.
+
+@kindex target dbug
+@item target dbug @var{dev}
+dBUG ROM monitor for Motorola ColdFire.
+
+@kindex target est
+@item target est @var{dev}
+EST-300 ICE monitor, running on a CPU32 (M68K) board.
-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:
+@kindex target rom68k
+@item target rom68k @var{dev}
+ROM 68K monitor, running on an M68K IDP board.
-@example
-(@value{GDBP}) info cisco
-List of Cisco Kernel Objects
-Object Description
-any Any and all objects
-@end example
+@end table
-Further subcommands can be used to query about particular objects known
-by the kernel.
+If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
+instead have only a single special target command:
-There is currently no way to determine whether a given operating system
-is supported other than to try it.
+@table @code
+@kindex target es1800
+@item target es1800 @var{dev}
+ES-1800 emulator for M68K.
-@node Configurations
-@chapter Configuration-Specific Information
+@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.
+[context?]
-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.
+@table @code
-@menu
-* Native::
-* Embedded OS::
-* Embedded Processors::
-* Architectures::
-@end menu
+@kindex target rombug
+@item target rombug @var{dev}
+ROMBUG ROM monitor for OS/9000.
-@node Native
-@section Native
+@end table
-This section describes details specific to particular native
-configurations.
+@node M88K
+@subsection M88K
-@menu
-* HP-UX:: HP-UX
-* SVR4 Process Information:: SVR4 process information
-@end menu
+@table @code
-@node HP-UX
-@subsection HP-UX
+@kindex target bug
+@item target bug @var{dev}
+BUG monitor, running on a MVME187 (m88k) board.
-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.
+@end table
-@node SVR4 Process Information
-@subsection SVR4 process information
+@node MIPS Embedded
+@subsection MIPS Embedded
-@kindex /proc
-@cindex process image
+@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}.
-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.
+@need 1000
+Use these @value{GDBN} commands to specify the connection to your target board:
@table @code
-@kindex info proc
-@item info proc
-Summarize available information about the process.
+@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.
-@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.
+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:
-@kindex info proc times
-@item info proc times
-Starting time, user CPU time, and system CPU time for your program and
-its children.
+@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
-@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 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}}.
-@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 target pmon @var{port}
+@kindex target pmon @var{port}
+PMON ROM monitor.
-@item info proc all
-Show all the above information about the process.
-@end table
+@item target ddb @var{port}
+@kindex target ddb @var{port}
+NEC's DDB variant of PMON for Vr4300.
-@node Embedded OS
-@section Embedded Operating Systems
+@item target lsi @var{port}
+@kindex target lsi @var{port}
+LSI variant of PMON.
-This section describes configurations involving the debugging of
-embedded operating systems that are available for several different
-architectures.
+@kindex target r3900
+@item target r3900 @var{dev}
+Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
-@menu
-* VxWorks:: Using @value{GDBN} with VxWorks
-@end menu
+@kindex target array
+@item target array @var{dev}
+Array Tech LSI33K RAID controller board.
-@value{GDBN} includes the ability to debug programs running on
-various real-time operating systems.
+@end table
-@node VxWorks
-@subsection Using @value{GDBN} with VxWorks
-@cindex VxWorks
+@noindent
+@value{GDBN} also supports these special commands for MIPS targets:
@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.
-@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.
+@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}.
-@end table
+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.
-On VxWorks, @code{load} links @var{filename} dynamically on the
-current target system as well as adding its symbols in @value{GDBN}.
+As usual, you can inquire about the @code{mipsfpu} variable with
+@samp{show mipsfpu}.
-@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.)
+@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}.
-@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.
+@item set timeout @var{seconds}
+@itemx set retransmit-timeout @var{seconds}
+@itemx show timeout
+@itemx show retransmit-timeout
+@cindex @code{timeout}, MIPS protocol
+@cindex @code{retransmit-timeout}, MIPS protocol
+@kindex set timeout
+@kindex show timeout
+@kindex set retransmit-timeout
+@kindex show retransmit-timeout
+You can control the timeout used while waiting for a packet, in the MIPS
+remote protocol, with the @code{set timeout @var{seconds}} command. The
+default is 5 seconds. Similarly, you can control the timeout used while
+waiting for an acknowledgement of a packet with the @code{set
+retransmit-timeout @var{seconds}} command. The default is 3 seconds.
+You can inspect both values with @code{show timeout} and @code{show
+retransmit-timeout}. (These commands are @emph{only} available when
+@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
+
+The timeout set by @code{set timeout} does not apply when @value{GDBN}
+is waiting for your program to stop. In that case, @value{GDBN} waits
+forever because it has no way of knowing how long the program is going
+to run before stopping.
@end table
-The following information on connecting to VxWorks was current when
-this manual was produced; newer releases of VxWorks may use revised
-procedures.
+@node PowerPC
+@subsection PowerPC
-@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}.
+@table @code
-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).
+@kindex target dink32
+@item target dink32 @var{dev}
+DINK32 ROM monitor.
-@value{GDBN} comes up showing the prompt:
+@kindex target ppcbug
+@item target ppcbug @var{dev}
+@kindex target ppcbug1
+@item target ppcbug1 @var{dev}
+PPCBUG ROM monitor for PowerPC.
-@example
-(vxgdb)
-@end example
+@kindex target sds
+@item target sds @var{dev}
+SDS monitor, running on a PowerPC board (such as Motorola's ADS).
-@menu
-* VxWorks Connection:: Connecting to VxWorks
-* VxWorks Download:: VxWorks download
-* VxWorks Attach:: Running tasks
-@end menu
+@end table
-@node VxWorks Connection
-@subsubsection Connecting to VxWorks
+@node PA
+@subsection HP PA Embedded
-The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
-network. To connect to a target whose host name is ``@code{tt}'', type:
+@table @code
-@example
-(vxgdb) target vxworks tt
-@end example
+@kindex target op50n
+@item target op50n @var{dev}
+OP50N monitor, running on an OKI HPPA board.
-@need 750
-@value{GDBN} displays messages like these:
+@kindex target w89k
+@item target w89k @var{dev}
+W89K monitor, running on a Winbond HPPA board.
-@smallexample
-Attaching remote machine across net...
-Connected to tt.
-@end smallexample
+@end table
-@need 1000
-@value{GDBN} then attempts to read the symbol tables of any object modules
-loaded into the VxWorks target since it was last booted. @value{GDBN} locates
-these files by searching the directories listed in the command search
-path (@pxref{Environment, ,Your program's environment}); if it fails
-to find an object file, it displays a message such as:
+@node SH
+@subsection Hitachi SH
-@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 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.
-@node VxWorks Download
-@subsubsection VxWorks download
+@kindex target e7000@r{, with Hitachi SH}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi SH.
-@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 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.
-@example
--> cd "@var{vxpath}/vw/demo/rdb"
-@end example
+@end table
-@noindent
-Then, in @value{GDBN}, type:
+@node Sparclet
+@subsection Tsqware Sparclet
-@example
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
-(vxgdb) load prog.o
-@end example
+@cindex Sparclet
-@value{GDBN} displays a response similar to this:
+@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.
-@smallexample
-Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
-@end smallexample
+@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
-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.)
+@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:
-@node VxWorks Attach
-@subsubsection Running tasks
+@smallexample
+sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
+@end smallexample
-@cindex running VxWorks tasks
-You can also attach to an existing task using the @code{attach} command as
-follows:
+You can use @code{objdump} to verify that the addresses are what you intended:
-@example
-(vxgdb) attach @var{task}
-@end example
+@smallexample
+sparclet-aout-objdump --headers --syms prog
+@end smallexample
-@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 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).
-@node Embedded Processors
-@section Embedded Processors
+@value{GDBN} comes up showing the prompt:
-This section goes into details specific to particular embedded
-configurations.
+@smallexample
+(gdbslet)
+@end smallexample
@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
+* Sparclet File:: Setting the file to debug
+* Sparclet Connection:: Connecting to Sparclet
+* Sparclet Download:: Sparclet download
+* Sparclet Execution:: Running and debugging
@end menu
-@node A29K Embedded
-@subsection AMD A29K Embedded
+@node Sparclet File
+@subsubsection Setting file to debug
+
+The @value{GDBN} command @code{file} lets you choose with program to debug.
-@menu
-* A29K UDI::
-* A29K EB29K::
-* Comms (EB29K):: Communications setup
-* gdb-EB29K:: EB29K cross-debugging
-* Remote Log:: Remote log
-@end menu
+@smallexample
+(gdbslet) file prog
+@end smallexample
-@table @code
+@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:
+
+@smallexample
+prog: No such file or directory.
+@end smallexample
-@kindex target adapt
-@item target adapt @var{dev}
-Adapt monitor for A29K.
+When this happens, add the appropriate directories to the search paths with
+the @value{GDBN} commands @code{path} and @code{dir}, and execute the
+@code{target} command again.
-@kindex target 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}.
+@node Sparclet Connection
+@subsubsection Connecting to Sparclet
-@end table
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
+To connect to a target on serial port ``@code{ttya}'', type:
-@node A29K UDI
-@subsubsection A29K UDI
+@smallexample
+(gdbslet) target sparclet /dev/ttya
+Remote target sparclet connected to /dev/ttya
+main () at ../prog.c:3
+@end smallexample
+
+@need 750
+@value{GDBN} displays messages like these:
-@cindex UDI
-@cindex AMD29K via UDI
+@smallexample
+Connected to ttya.
+@end smallexample
-@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 Sparclet Download
+@subsubsection Sparclet download
-@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
+@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:
+
+@smallexample
+(gdbslet) load prog 0x12010000
+Loading section .text, size 0xdb0 vma 0x12010000
+@end smallexample
-@node A29K EB29K
-@subsubsection EBMON protocol for AMD29K
+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.
-@cindex EB29K board
-@cindex running 29K programs
+@node Sparclet Execution
+@subsubsection Running and debugging
-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.
+@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.
-@node Comms (EB29K)
-@subsubsection Communications setup
+@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
-The next step is to set up the PC's port, by doing something like this
-in DOS on the PC:
+@node Sparclite
+@subsection Fujitsu Sparclite
-@example
-C:\> MODE com1:9600,n,8,1,none
-@end example
+@table @code
-@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
+@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.
-To give control of the PC to the Unix side of the serial line, type
-the following at the DOS console:
+@end table
-@example
-C:\> CTTY com1
-@end example
+@node ST2000
+@subsection Tandem ST2000
-@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.)
+@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
+STDBUG protocol.
-From the Unix host, use a communications program such as @code{tip} or
-@code{cu} to communicate with the PC; for example,
+To connect your ST2000 to the host system, see the manufacturer's
+manual. Once the ST2000 is physically attached, you can run:
-@example
-cu -s 9600 -l /dev/ttya
-@end example
+@smallexample
+target st2000 @var{dev} @var{speed}
+@end smallexample
@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:
+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}}.
-@example
-tip -9600 /dev/ttya
-@end example
+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.
-@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
+@cindex ST2000 auxiliary commands
+These auxiliary @value{GDBN} commands are available to help you with the ST2000
+environment:
-@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.
+@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.
-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.
+@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
-@node ARM
-@subsection ARM
+@node Z8000
+@subsection Zilog Z8000
-@table @code
+@cindex Z8000
+@cindex simulator, Z8000
+@cindex Zilog Z8000 simulator
-@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.
+When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
+a Z8000 simulator.
-@kindex target rdp
-@item target rdp @var{dev}
-ARM Demon monitor.
+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.
+@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
-@node H8/300
-@subsection Hitachi H8/300
+@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.
+
+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:
@table @code
-@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.
+@item cycles
+Counts clock-ticks in the simulator.
-@kindex target e7000@r{, with H8/300}
-@item target e7000 @var{dev}
-E7000 emulator for Hitachi H8 and SH.
+@item insts
+Counts instructions run in the simulator.
-@kindex target sh3@r{, with H8/300}
-@kindex target sh3e@r{, with H8/300}
-@item target sh3 @var{dev}
-@itemx target sh3e @var{dev}
-Hitachi SH-3 and SH-3E target systems.
+@item time
+Execution time in 60ths of a second.
@end table
-@cindex download to H8/300 or H8/500
-@cindex H8/300 or H8/500 download
-@cindex download to Hitachi SH
-@cindex Hitachi SH download
-When you select remote debugging to a Hitachi SH, H8/300, or H8/500
-board, the @code{load} command downloads your program to the Hitachi
-board and also opens it as the current executable target for
-@value{GDBN} on your host (like the @code{file} command).
-
-@value{GDBN} needs to know these things to talk to your
-Hitachi SH, H8/300, or H8/500:
-
-@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.)
+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
-what serial device connects your host to your Hitachi board (the first
-serial device available on your host is the default).
+@node Architectures
+@section Architectures
-@item
-what speed to use over the serial device.
-@end enumerate
+This section describes characteristics of architectures that affect
+all uses of @value{GDBN} with the architecture, both native and cross.
@menu
-* Hitachi Boards:: Connecting to Hitachi boards.
-* Hitachi ICE:: Using the E7000 In-Circuit Emulator.
-* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
+* A29K::
+* Alpha::
+* MIPS::
@end menu
-@node Hitachi Boards
-@subsubsection Connecting to Hitachi boards
+@node A29K
+@subsection A29K
-@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}.
+@table @code
-@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).
+@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 @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.
+@kindex show rstack_high_address
+@item show rstack_high_address
+Display the current limit of the register stack, on AMD 29000 family
+processors.
-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.
+@end table
-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}.
+@node Alpha
+@subsection Alpha
-@example
-C:\H8300\TEST> asynctsr 2
-C:\H8300\TEST> mode com2:9600,n,8,1,p
+See the following section.
-Resident portion of MODE loaded
+@node MIPS
+@subsection MIPS
-COM2: 9600, n, 8, 1, p
+@cindex stack on Alpha
+@cindex stack on MIPS
+@cindex Alpha stack
+@cindex MIPS stack
+Alpha- and MIPS-based computers use an unusual stack frame, which
+sometimes requires @value{GDBN} to search backward in the object code to
+find the beginning of a function.
+
+@cindex response time, MIPS debugging
+To improve response time (especially for embedded applications, where
+@value{GDBN} may be restricted to a slow serial line for this search)
+you may want to limit the size of this search, using one of these
+commands:
-@end example
+@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.
-@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
+@item show heuristic-fence-post
+Display the current limit.
+@end table
-@kindex target hms@r{, and serial protocol}
-Now that serial communications are set up, and the development board is
-connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
-the name of your program as the argument. @code{@value{GDBN}} prompts
-you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
-commands to begin your debugging session: @samp{target hms} to specify
-cross-debugging to the Hitachi board, and the @code{load} command to
-download your program to the board. @code{load} displays the names of
-the program's sections, and a @samp{*} for each 2K of data downloaded.
-(If you want to refresh @value{GDBN} data on symbols or on the
-executable file without downloading, use the @value{GDBN} commands
-@code{file} or @code{symbol-file}. These commands, and @code{load}
-itself, are described in @ref{Files,,Commands to specify files}.)
+@noindent
+These commands are available @emph{only} when @value{GDBN} is configured
+for debugging programs on Alpha or MIPS processors.
-@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
-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.
+@node Controlling GDB
+@chapter Controlling @value{GDBN}
-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!
+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.
-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
+@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
-@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 Prompt
+@section Prompt
-In either case, @value{GDBN} sees the effect of a @sc{reset} on the
-development board as a ``normal exit'' of your program.
+@cindex prompt
-@node Hitachi ICE
-@subsubsection Using the E7000 in-circuit emulator
+@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.
-@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:
+@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
-@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}).
+@kindex set prompt
+@item set prompt @var{newprompt}
+Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
-@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.
+@kindex show prompt
+@item show prompt
+Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
@end table
-@node Hitachi Special
-@subsubsection Special @value{GDBN} commands for Hitachi micros
+@node Editing
+@section Command editing
+@cindex readline
+@cindex command line editing
-Some @value{GDBN} commands are available only for the H8/300:
+@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.
+
+You may control the behavior of command line editing in @value{GDBN} with the
+command @code{set}.
@table @code
+@kindex set editing
+@cindex editing
+@item set editing
+@itemx set editing on
+Enable command line editing (enabled by default).
-@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.
+@item set editing off
+Disable command line editing.
+@kindex show editing
+@item show editing
+Show whether command line editing is enabled.
@end table
-@node H8/500
-@subsection H8/500
+@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.
-@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 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.
-@end table
+@item set history save off
+Stop recording command history in a file.
-@node i960
-@subsection Intel i960
+@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
-@table @code
+@cindex history expansion
+History expansion assigns special meaning to the character @kbd{!}.
+@ifset have-readline-appendices
+@xref{Event Designators}.
+@end ifset
-@kindex target mon960
-@item target mon960 @var{dev}
-MON960 monitor for Intel i960.
+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 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}.
+The commands to control history expansion are:
-@end table
+@table @code
+@kindex set history expansion
+@item set history expansion on
+@itemx set history expansion
+Enable history expansion. History expansion is off by default.
-@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:
+@item set history expansion off
+Disable history expansion.
-@itemize @bullet
-@item
-Through command line options specifying serial port, version of the
-Nindy protocol, and communications speed;
+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
-By responding to a prompt on startup;
+@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
-@item
-By using the @code{target} command at any point during your @value{GDBN}
-session. @xref{Target Commands, ,Commands for managing targets}.
+@table @code
+@kindex shows
+@item show commands
+Display the last ten commands in the command history.
-@end itemize
+@item show commands @var{n}
+Print ten commands centered on command number @var{n}.
-@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}.
+@item show commands +
+Print ten commands just after the commands last printed.
+@end table
-@menu
-* Nindy Startup:: Startup with Nindy
-* Nindy Options:: Options for Nindy
-* Nindy Reset:: Nindy reset command
-@end menu
+@node Screen Size
+@section Screen size
+@cindex size of screen
+@cindex pauses in output
-@node Nindy Startup
-@subsubsection Startup with Nindy
+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 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:
+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:
-@example
-Attach /dev/ttyNN -- specify NN, or "quit" to quit:
-@end example
+@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.
-@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}).
+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.
-@node Nindy Options
-@subsubsection Options for Nindy
+Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
+from wrapping its output.
+@end table
-These are the startup options for beginning your @value{GDBN} session with a
-Nindy-960 board attached:
+@node Numbers
+@section Numbers
+@cindex number representation
+@cindex entering numbers
+
+You can always enter numbers in octal, decimal, or hexadecimal in
+@value{GDBN} by the usual conventions: octal numbers begin with
+@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
+begin with @samp{0x}. Numbers that begin with none of these are, by
+default, entered in base 10; likewise, the default display for
+numbers---when no particular format is specified---is base 10. You can
+change the default base for both input and output with the @code{set
+radix} command.
@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}).
+@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
-@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.
+@smallexample
+set radix 012
+set radix 10.
+set radix 0xa
+@end smallexample
-@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
+@noindent
+sets the base to decimal. On the other hand, @samp{set radix 10}
+leaves the radix unchanged no matter what it was.
-@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.
+@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.
-@quotation
-@emph{Warning:} Many target systems do not have the hardware that this
-requires; it only works with a few boards.
-@end quotation
+@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 standard @samp{-b} option controls the line speed used on the serial
-port.
+@node Messages/Warnings
+@section Optional warnings and messages
-@c @group
-@node Nindy Reset
-@subsubsection Nindy reset command
+By default, @value{GDBN} is silent about its inner workings. If you are
+running on a slow machine, you may want to use the @code{set verbose}
+command. This makes @value{GDBN} tell you when it does a lengthy
+internal operation, so you will not think it has crashed.
+
+Currently, the messages controlled by @code{set verbose} are those
+which announce that the symbol table for a source file is being read;
+see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
@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.
+@kindex set verbose
+@item set verbose on
+Enables @value{GDBN} output of certain informational messages.
+
+@item set verbose off
+Disables @value{GDBN} output of certain informational messages.
+
+@kindex show verbose
+@item show verbose
+Displays whether @code{set verbose} is on or off.
@end table
-@c @end group
-@node M32R/D
-@subsection Mitsubishi M32R/D
+By default, if @value{GDBN} encounters bugs in the symbol table of an
+object file, it is silent; but if you are debugging a compiler, you may
+find this information useful (@pxref{Symbol Errors, ,Errors reading
+symbol files}).
@table @code
-@kindex target m32r
-@item target m32r @var{dev}
-Mitsubishi M32R/D ROM monitor.
+@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.
+
+@kindex show complaints
+@item show complaints
+Displays how many symbol complaints @value{GDBN} is permitted to produce.
@end table
-@node M68K
-@subsection M68k
+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:
-The Motorola m68k configuration includes ColdFire support, and
-target command for the following ROM monitors.
+@smallexample
+(@value{GDBP}) run
+The program being debugged has been started already.
+Start it from the beginning? (y or n)
+@end smallexample
-@table @code
+If you are willing to unflinchingly face the consequences of your own
+commands, you can disable this ``feature'':
-@kindex target abug
-@item target abug @var{dev}
-ABug ROM monitor for M68K.
+@table @code
-@kindex target cpu32bug
-@item target cpu32bug @var{dev}
-CPU32BUG monitor, running on a CPU32 (M68K) board.
+@kindex set confirm
+@cindex flinching
+@cindex confirmation
+@cindex stupid questions
+@item set confirm off
+Disables confirmation requests.
-@kindex target dbug
-@item target dbug @var{dev}
-dBUG ROM monitor for Motorola ColdFire.
+@item set confirm on
+Enables confirmation requests (the default).
-@kindex target est
-@item target est @var{dev}
-EST-300 ICE monitor, running on a CPU32 (M68K) board.
+@kindex show confirm
+@item show confirm
+Displays state of confirmation requests.
-@kindex target rom68k
-@item target rom68k @var{dev}
-ROM 68K monitor, running on an M68K IDP board.
+@end table
+@node Debugging Output
+@section Optional messages about internal happenings
+@table @code
+@kindex set debug arch
+@item set debug arch
+Turns on or off display of gdbarch debugging info. The default is off
+@kindex show debug arch
+@item show debug arch
+Displays the current state of displaying gdbarch debugging info.
+@kindex set debug event
+@item set debug event
+Turns on or off display of @value{GDBN} event debugging info. The
+default is off.
+@kindex show debug event
+@item show debug event
+Displays the current state of displaying @value{GDBN} event debugging
+info.
+@kindex set debug expression
+@item set debug expression
+Turns on or off display of @value{GDBN} expression debugging info. The
+default is off.
+@kindex show debug expression
+@item show debug expression
+Displays the current state of displaying @value{GDBN} expression
+debugging info.
+@kindex set debug overload
+@item set debug overload
+Turns on or off display of @value{GDBN} C@t{++} overload debugging
+info. This includes info such as ranking of functions, etc. The default
+is off.
+@kindex show debug overload
+@item show debug overload
+Displays the current state of displaying @value{GDBN} C@t{++} overload
+debugging info.
+@kindex set debug remote
+@cindex packets, reporting on stdout
+@cindex serial connections, debugging
+@item set debug remote
+Turns on or off display of reports on all packets sent back and forth across
+the serial line to the remote machine. The info is printed on the
+@value{GDBN} standard output stream. The default is off.
+@kindex show debug remote
+@item show debug remote
+Displays the state of display of remote packets.
+@kindex set debug serial
+@item set debug serial
+Turns on or off display of @value{GDBN} serial debugging info. The
+default is off.
+@kindex show debug serial
+@item show debug serial
+Displays the current state of displaying @value{GDBN} serial debugging
+info.
+@kindex set debug target
+@item set debug target
+Turns on or off display of @value{GDBN} target debugging info. This info
+includes what is going on at the target level of GDB, as it happens. The
+default is off.
+@kindex show debug target
+@item show debug target
+Displays the current state of displaying @value{GDBN} target debugging
+info.
+@kindex set debug varobj
+@item set debug varobj
+Turns on or off display of @value{GDBN} variable object debugging
+info. The default is off.
+@kindex show debug varobj
+@item show debug varobj
+Displays the current state of displaying @value{GDBN} variable object
+debugging info.
@end table
-If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
-instead have only a single special target command:
+@node Sequences
+@chapter Canned Sequences of Commands
-@table @code
+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.
-@kindex target es1800
-@item target es1800 @var{dev}
-ES-1800 emulator for M68K.
+@menu
+* Define:: User-defined commands
+* Hooks:: User-defined command hooks
+* Command Files:: Command files
+* Output:: Commands for controlled output
+@end menu
-@end table
+@node Define
+@section User-defined commands
-[context?]
+@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:
-@table @code
+@smallexample
+define adder
+ print $arg0 + $arg1 + $arg2
+@end smallexample
-@kindex target rombug
-@item target rombug @var{dev}
-ROMBUG ROM monitor for OS/9000.
+@noindent
+To execute the command use:
-@end table
+@smallexample
+adder 1 2 3
+@end smallexample
-@node M88K
-@subsection M88K
+@noindent
+This defines the command @code{adder}, which prints the sum of
+its three arguments. Note the arguments are text substitutions, so they may
+reference variables, use complex expressions, or even perform inferior
+functions calls.
@table @code
-@kindex target bug
-@item target bug @var{dev}
-BUG monitor, running on a MVME187 (m88k) board.
-
-@end table
-
-@node MIPS Embedded
-@subsection MIPS Embedded
-
-@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}.
-
-@need 1000
-Use these @value{GDBN} commands to specify the connection to your target board:
-
-@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.
+@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.
-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:
+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}.
-@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
+@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}.
-@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}}.
+@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.
-@item target pmon @var{port}
-@kindex target pmon @var{port}
-PMON ROM monitor.
+@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.
-@item target ddb @var{port}
-@kindex target ddb @var{port}
-NEC's DDB variant of PMON for Vr4300.
+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.
-@item target lsi @var{port}
-@kindex target lsi @var{port}
-LSI variant of PMON.
+@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 r3900
-@item target r3900 @var{dev}
-Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
+@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 array
-@item target array @var{dev}
-Array Tech LSI33K RAID controller board.
+@kindex show max-user-call-depth
+@kindex set max-user-call-depth
+@item show max-user-call-depth
+@item set max-user-call-depth
+The value of @code{max-user-call-depth} controls how many levels deep a
+user-defined call chain can go. Default is 1024.
@end table
+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.
-@noindent
-@value{GDBN} also supports these special commands for MIPS targets:
-
-@table @code
-@item set processor @var{args}
-@itemx show processor
-@kindex set processor @var{args}
-@kindex show processor
-Use the @code{set processor} command to set the type of MIPS
-processor when you want to access processor-type-specific registers.
-For example, @code{set processor @var{r3041}} tells @value{GDBN}
-to use the CPU registers appropriate for the 3041 chip.
-Use the @code{show processor} command to see what MIPS processor @value{GDBN}
-is using. Use the @code{info reg} command to see what registers
-@value{GDBN} is using.
-
-@item set mipsfpu double
-@itemx set mipsfpu single
-@itemx set mipsfpu none
-@itemx show mipsfpu
-@kindex set mipsfpu
-@kindex show mipsfpu
-@cindex MIPS remote floating point
-@cindex floating point, MIPS remote
-If your target board does not support the MIPS floating point
-coprocessor, you should use the command @samp{set mipsfpu none} (if you
-need this, you may wish to put the command in your @value{GDBN} init
-file). This tells @value{GDBN} how to find the return value of
-functions which return floating point values. It also allows
-@value{GDBN} to avoid saving the floating point registers when calling
-functions on the board. If you are using a floating point coprocessor
-with only single precision floating point support, as on the @sc{r4650}
-processor, use the command @samp{set mipsfpu single}. The default
-double precision floating point coprocessor may be selected using
-@samp{set mipsfpu double}.
-
-In previous versions the only choices were double precision or no
-floating point, so @samp{set mipsfpu on} will select double precision
-and @samp{set mipsfpu off} will select no floating point.
+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.
-As usual, you can inquire about the @code{mipsfpu} variable with
-@samp{show mipsfpu}.
+@node Hooks
+@section User-defined command hooks
+@cindex command hooks
+@cindex hooks, for commands
+@cindex hooks, pre-command
-@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}.
+@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.
-@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}.)
+@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.
-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
+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.
-@node PowerPC
-@subsection PowerPC
+@c It would be nice if hookpost could be passed a parameter indicating
+@c if the command it hooks executed properly or not. FIXME!
-@table @code
+@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.
-@kindex target dink32
-@item target dink32 @var{dev}
-DINK32 ROM monitor.
+For example, to ignore @code{SIGALRM} signals while
+single-stepping, but treat them normally during normal execution,
+you could define:
-@kindex target ppcbug
-@item target ppcbug @var{dev}
-@kindex target ppcbug1
-@item target ppcbug1 @var{dev}
-PPCBUG ROM monitor for PowerPC.
+@smallexample
+define hook-stop
+handle SIGALRM nopass
+end
-@kindex target sds
-@item target sds @var{dev}
-SDS monitor, running on a PowerPC board (such as Motorola's ADS).
+define hook-run
+handle SIGALRM pass
+end
-@end table
+define hook-continue
+handle SIGLARM pass
+end
+@end smallexample
-@node PA
-@subsection HP PA Embedded
+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:
-@table @code
+@smallexample
+define hook-echo
+echo <<<---
+end
-@kindex target op50n
-@item target op50n @var{dev}
-OP50N monitor, running on an OKI HPPA board.
+define hookpost-echo
+echo --->>>\n
+end
-@kindex target w89k
-@item target w89k @var{dev}
-W89K monitor, running on a Winbond HPPA board.
+(@value{GDBP}) echo Hello World
+<<<---Hello World--->>>
+(@value{GDBP})
-@end table
+@end smallexample
-@node SH
-@subsection Hitachi SH
+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).
-@table @code
+If you try to define a hook which does not match any known command, you
+get a warning from the @code{define} 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.
+@node Command Files
+@section Command files
-@kindex target e7000@r{, with Hitachi SH}
-@item target e7000 @var{dev}
-E7000 emulator for Hitachi SH.
+@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.
-@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.
+@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:
-@end table
+@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.}.
-@node Sparclet
-@subsection Tsqware Sparclet
+@item
+Processes command line options and operands.
-@cindex Sparclet
+@item
+Reads the init file (if any) in the current working directory.
-@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
+Reads command files specified by the @samp{-x} option.
+@end enumerate
-@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 init file in your home directory can set options (such as @samp{set
+complaints}) that affect subsequent processing of command line options
+and operands. Init files are not executed if you use the @samp{-nx}
+option (@pxref{Mode Options, ,Choosing modes}).
-@cindex 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:
+@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:
-@example
-sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
-@end example
+@cindex @file{.vxgdbinit}
+@itemize @bullet
+@item
+VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
-You can use @code{objdump} to verify that the addresses are what you intended:
+@cindex @file{.os68gdbinit}
+@item
+OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
-@example
-sparclet-aout-objdump --headers --syms prog
-@end example
+@cindex @file{.esgdbinit}
+@item
+ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
+@end itemize
-@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).
+You can also request the execution of a command file with the
+@code{source} command:
-@value{GDBN} comes up showing the prompt:
+@table @code
+@kindex source
+@item source @var{filename}
+Execute the command file @var{filename}.
+@end table
-@example
-(gdbslet)
-@end example
+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.
-@menu
-* Sparclet File:: Setting the file to debug
-* Sparclet Connection:: Connecting to Sparclet
-* Sparclet Download:: Sparclet download
-* Sparclet Execution:: Running and debugging
-@end menu
+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.
-@node Sparclet File
-@subsubsection Setting file to debug
+@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.
-The @value{GDBN} command @code{file} lets you choose with program to debug.
+@smallexample
+gdb < cmds > log 2>&1
+@end smallexample
-@example
-(gdbslet) file prog
-@end example
+(The syntax above will vary depending on the shell used.) This example
+will execute commands from the file @file{cmds}. All output and errors
+would be directed to @file{log}.
-@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:
+@node Output
+@section Commands for controlled output
+
+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.
+
+@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{ }}.
-@example
-prog: No such file or directory.
-@end example
+A backslash at the end of @var{text} can be used, as in C, to continue
+the command onto subsequent lines. For example,
-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.
+@smallexample
+echo This is some text\n\
+which is continued\n\
+onto several lines.\n
+@end smallexample
-@node Sparclet Connection
-@subsubsection Connecting to Sparclet
+produces the same output as
-The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
-To connect to a target on serial port ``@code{ttya}'', type:
+@smallexample
+echo This is some text\n
+echo which is continued\n
+echo onto several lines.\n
+@end smallexample
-@example
-(gdbslet) target sparclet /dev/ttya
-Remote target sparclet connected to /dev/ttya
-main () at ../prog.c:3
-@end example
+@kindex output
+@item output @var{expression}
+Print the value of @var{expression} and nothing but that value: no
+newlines, no @samp{$@var{nn} = }. The value is not entered in the
+value history either. @xref{Expressions, ,Expressions}, for more information
+on expressions.
-@need 750
-@value{GDBN} displays messages like these:
+@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.
-@example
-Connected to ttya.
-@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.
-@node Sparclet Download
-@subsubsection Sparclet download
+@smallexample
+printf (@var{string}, @var{expressions}@dots{});
+@end smallexample
-@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:
+For example, you can print two values in hex like this:
-@example
-(gdbslet) load prog 0x12010000
-Loading section .text, size 0xdb0 vma 0x12010000
-@end example
+@smallexample
+printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
+@end smallexample
-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 only backslash-escape sequences that you can use in the format
+string are the simple ones that consist of backslash followed by a
+letter.
+@end table
-@node Sparclet Execution
-@subsubsection Running and debugging
+@node TUI
+@chapter @value{GDBN} Text User Interface
+@cindex TUI
-@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.
+@menu
+* TUI Overview:: TUI overview
+* TUI Keys:: TUI key bindings
+* TUI Commands:: TUI specific commands
+* TUI Configuration:: TUI configuration variables
+@end menu
-@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
+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 Sparclite
-@subsection Fujitsu Sparclite
+@node TUI Overview
+@section TUI overview
-@table @code
+The TUI has two display modes that can be switched while
+@value{GDBN} runs:
-@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.
+@itemize @bullet
+@item
+A curses (or TUI) mode in which it displays several text
+windows on the terminal.
-@end table
+@item
+A standard mode which corresponds to the @value{GDBN} configured without
+the TUI.
+@end itemize
-@node ST2000
-@subsection Tandem ST2000
+In the TUI mode, @value{GDBN} can display several text window
+on the terminal:
-@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
-STDBUG protocol.
+@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.
-To connect your ST2000 to the host system, see the manufacturer's
-manual. Once the ST2000 is physically attached, you can run:
+@item source
+The source window shows the source file of the program. The current
+line as well as active breakpoints are displayed in this window.
+The current program position is shown with the @samp{>} marker and
+active breakpoints are shown with @samp{*} markers.
-@example
-target st2000 @var{dev} @var{speed}
-@end example
+@item assembly
+The assembly window shows the disassembly output of the 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}}.
+@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.
-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.
+@end table
-@cindex ST2000 auxiliary commands
-These auxiliary @value{GDBN} commands are available to help you with the ST2000
-environment:
+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:
-@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.
+@itemize @bullet
+@item
+source
-@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
+assembly
-@node Z8000
-@subsection Zilog Z8000
+@item
+source and assembly
-@cindex Z8000
-@cindex simulator, Z8000
-@cindex Zilog Z8000 simulator
+@item
+source and registers
-When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
-a Z8000 simulator.
+@item
+assembly and registers
-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.
+@end itemize
-@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
+@node TUI Keys
+@section TUI Key Bindings
+@cindex TUI key bindings
-@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.
+The TUI installs several key bindings in the readline keymaps
+(@pxref{Command Line Editing}).
+They allow to leave or enter in the TUI mode or they operate
+directly on the TUI layout and windows. The following key bindings
+are installed for both TUI mode and the @value{GDBN} standard mode.
-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:
+@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.
-@table @code
+@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 cycles
-Counts clock-ticks in the simulator.
+Think of this key binding as the Emacs @kbd{C-x 1} binding.
-@item insts
-Counts instructions run in the simulator.
+@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.
-@item time
-Execution time in 60ths of a second.
+Think of it as the Emacs @kbd{C-x 2} binding.
@end table
-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.
+The following key bindings are handled only by the TUI mode:
-@node Architectures
-@section Architectures
+@table @key
+@kindex PgUp
+@item PgUp
+Scroll the active window one page up.
-This section describes characteristics of architectures that affect
-all uses of @value{GDBN} with the architecture, both native and cross.
+@kindex PgDn
+@item PgDn
+Scroll the active window one page down.
-@menu
-* A29K::
-* Alpha::
-* MIPS::
-@end menu
+@kindex Up
+@item Up
+Scroll the active window one line up.
-@node A29K
-@subsection A29K
+@kindex Down
+@item Down
+Scroll the active window one line down.
-@table @code
+@kindex Left
+@item Left
+Scroll the active window one column left.
-@kindex set rstack_high_address
-@cindex AMD 29K register stack
-@cindex register stack, AMD29K
-@item set rstack_high_address @var{address}
-On AMD 29000 family processors, registers are saved in a separate
-@dfn{register stack}. There is no way for @value{GDBN} to determine the
-extent of this stack. Normally, @value{GDBN} just assumes that the
-stack is ``large enough''. This may result in @value{GDBN} referencing
-memory locations that do not exist. If necessary, you can get around
-this problem by specifying the ending address of the register stack with
-the @code{set rstack_high_address} command. The argument should be an
-address, which you probably want to precede with @samp{0x} to specify in
-hexadecimal.
+@kindex Right
+@item Right
+Scroll the active window one column right.
-@kindex show rstack_high_address
-@item show rstack_high_address
-Display the current limit of the register stack, on AMD 29000 family
-processors.
+@kindex C-L
+@item C-L
+Refresh the screen.
@end table
-@node Alpha
-@subsection Alpha
+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}.
-See the following section.
+@node TUI Commands
+@section TUI specific commands
+@cindex TUI commands
-@node MIPS
-@subsection MIPS
+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.
-@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.
+@table @code
+@item layout next
+@kindex layout next
+Display the next layout.
-@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:
+@item layout prev
+@kindex layout prev
+Display the previous layout.
-@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 layout src
+@kindex layout src
+Display the source window only.
-@item show heuristic-fence-post
-Display the current limit.
-@end table
+@item layout asm
+@kindex layout asm
+Display the assembly window only.
-@noindent
-These commands are available @emph{only} when @value{GDBN} is configured
-for debugging programs on Alpha or MIPS processors.
+@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.
-@node Controlling GDB
-@chapter Controlling @value{GDBN}
+@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.
-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.
+@item refresh
+@kindex refresh
+Refresh the screen. This is similar to using @key{C-L} key.
-@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
+@item update
+@kindex update
+Update the source window and the current execution point.
-@node Prompt
-@section Prompt
+@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.
-@cindex prompt
+@end table
-@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.
+@node TUI Configuration
+@section TUI configuration variables
+@cindex TUI configuration variables
-@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.
+The TUI has several configuration variables that control the
+appearance of windows on the terminal.
@table @code
-@kindex set prompt
-@item set prompt @var{newprompt}
-Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
+@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 show prompt
-@item show prompt
-Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
-@end table
+@item ascii
+Use ascii characters + - and | to draw the border.
-@node Editing
-@section Command editing
-@cindex readline
-@cindex command line editing
+@item acs
+Use the Alternate Character Set to draw the border. The border is
+drawn using character line graphics if the terminal supports them.
-@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.
+@end table
-You may control the behavior of command line editing in @value{GDBN} with the
-command @code{set}.
+@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}.
+@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
-@kindex set editing
-@cindex editing
-@item set editing
-@itemx set editing on
-Enable command line editing (enabled by default).
+@item normal
+Use normal attributes to display the border.
-@item set editing off
-Disable command line editing.
+@item standout
+Use standout mode.
-@kindex show editing
-@item show editing
-Show whether command line editing is enabled.
-@end table
+@item reverse
+Use reverse video mode.
-@node History
-@section Command history
+@item half
+Use half bright mode.
-@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 half-standout
+Use half bright and standout mode.
-@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.
+@item bold
+Use extra bright or bold mode.
-@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.
+@item bold-standout
+Use extra bright or bold and standout mode.
-@item set history save off
-Stop recording command history in a file.
+@end table
-@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
-@cindex history expansion
-History expansion assigns special meaning to the character @kbd{!}.
-@ifset have-readline-appendices
-@xref{Event Designators}.
-@end ifset
+@node Emacs
+@chapter Using @value{GDBN} under @sc{gnu} Emacs
-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.
+@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}.
-The commands to control history expansion are:
+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.)
-@table @code
-@kindex set history expansion
-@item set history expansion on
-@itemx set history expansion
-Enable history expansion. History expansion is off by default.
+Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
+things:
-@item set history expansion off
-Disable history expansion.
+@itemize @bullet
+@item
+All ``terminal'' input and output goes through the Emacs buffer.
+@end itemize
-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
+This applies both to @value{GDBN} commands and their output, and to the input
+and output done by the program you are debugging.
-@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
+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.
-@table @code
-@kindex shows
-@item show commands
-Display the last ten commands in the command history.
+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.
-@item show commands @var{n}
-Print ten commands centered on command number @var{n}.
+@itemize @bullet
+@item
+@value{GDBN} displays source code through Emacs.
+@end itemize
-@item show commands +
-Print ten commands just after the commands last printed.
-@end table
+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.
-@node Screen Size
-@section Screen size
-@cindex size of screen
-@cindex pauses in output
+Explicit @value{GDBN} @code{list} or search commands still produce output as
+usual, but you probably have no reason to use them from Emacs.
-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.
+@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.
+
+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
+
+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,
+
+@smallexample
+(setq gdb-command-name "mygdb")
+@end smallexample
+
+@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:
+
+@table @kbd
+@item C-h m
+Describe the features of Emacs' @value{GDBN} Mode.
+
+@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.
+
+@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.
+
+@item M-i
+Execute one instruction, like the @value{GDBN} @code{stepi} command; update
+display window accordingly.
+
+@item M-x gdb-nexti
+Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
+display window accordingly.
+
+@item C-c C-f
+Execute until exit from the selected stack frame, like the @value{GDBN}
+@code{finish} command.
+
+@item M-c
+Continue execution of your program, like the @value{GDBN} @code{continue}
+command.
+
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
+
+@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.
-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:
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
-@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.
+@item M-d
+Go down the number of frames indicated by the numeric argument, like the
+@value{GDBN} @code{down} command.
-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.
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
-Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
-from wrapping its output.
+@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 &}.
+
+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
-@node Numbers
-@section Numbers
-@cindex number representation
-@cindex entering numbers
+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.
-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.
+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
-@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 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.
-@smallexample
-set radix 012
-set radix 10.
-set radix 0xa
-@end smallexample
+@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
-@noindent
-sets the base to decimal. On the other hand, @samp{set radix 10}
-leaves the radix unchanged no matter what it was.
+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
-@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.
+@include annotate.texi
+@include gdbmi.texinfo
-@kindex show input-radix
-@item show input-radix
-Display the current default base for numeric input.
+@node GDB Bugs
+@chapter Reporting Bugs in @value{GDBN}
+@cindex bugs in @value{GDBN}
+@cindex reporting bugs in @value{GDBN}
-@kindex show output-radix
-@item show output-radix
-Display the current default base for numeric display.
-@end table
+Your bug reports play an essential role in making @value{GDBN} reliable.
-@node Messages/Warnings
-@section Optional warnings and messages
+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}.
-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.
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
-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}.
+@menu
+* Bug Criteria:: Have you found a bug?
+* Bug Reporting:: How to report bugs
+@end menu
-@table @code
-@kindex set verbose
-@item set verbose on
-Enables @value{GDBN} output of certain informational messages.
+@node Bug Criteria
+@section Have you found a bug?
+@cindex bug criteria
-@item set verbose off
-Disables @value{GDBN} output of certain informational messages.
+If you are not sure whether you have found a bug, here are some guidelines:
-@kindex show verbose
-@item show verbose
-Displays whether @code{set verbose} is on or off.
-@end table
+@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.
-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}).
+@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.)
-@table @code
+@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''.
-@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
+If you are an experienced user of debugging tools, your suggestions
+for improvement of @value{GDBN} are welcome in any case.
+@end itemize
-@kindex show complaints
-@item show complaints
-Displays how many symbol complaints @value{GDBN} is permitted to produce.
+@node Bug Reporting
+@section How to report bugs
+@cindex bug reports
+@cindex @value{GDBN} bugs, reporting
-@end table
+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.
-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:
+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...
-@example
-(@value{GDBP}) run
-The program being debugged has been started already.
-Start it from the beginning? (y or n)
-@end example
+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.
-If you are willing to unflinchingly face the consequences of your own
-commands, you can disable this ``feature'':
+@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}.
-@table @code
+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.
-@kindex set confirm
-@cindex flinching
-@cindex confirmation
-@cindex stupid questions
-@item set confirm off
-Disables confirmation requests.
+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!
-@item set confirm on
-Enables confirmation requests (the default).
+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.
-@kindex show confirm
-@item show confirm
-Displays state of confirmation requests.
+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.
-@end table
+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.
+
+To enable us to fix the bug, you should include all these things:
+
+@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}.
-@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
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of @value{GDBN}.
-@node Sequences
-@chapter Canned Sequences of Commands
+@item
+The type of machine you are using, and the operating system name and
+version number.
-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
+What compiler (and its version) was used to compile @value{GDBN}---e.g.
+``@value{GCC}--2.8.1''.
-@menu
-* Define:: User-defined commands
-* Hooks:: User-defined command hooks
-* Command Files:: Command files
-* Output:: Commands for controlled output
-@end menu
+@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.
-@node Define
-@section User-defined commands
+@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.
-@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:
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
-@smallexample
-define adder
- print $arg0 + $arg1 + $arg2
-@end smallexample
+@item
+A complete input script, and all necessary source files, that will
+reproduce the bug.
-@noindent
-To execute the command use:
+@item
+A description of what behavior you observe that you believe is
+incorrect. For example, ``It gets a fatal signal.''
-@smallexample
-adder 1 2 3
-@end smallexample
+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.
-@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.
+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.
-@table @code
+@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.
-@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.
+The line numbers in our development sources will not match those in your
+sources. Your line numbers would convey no useful information to us.
-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}.
+@end itemize
-@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}.
+Here are some things that are not necessary:
-@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.
+@itemize @bullet
+@item
+A description of the envelope of the bug.
-@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.
+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.
-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.
+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.
-@kindex help user-defined
-@item help user-defined
-List all user-defined commands, with the first line of the documentation
-(if any) for each.
+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.
-@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.
+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.
-@end table
+@item
+A patch for the bug.
-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.
+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.
-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.
+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.
-@node Hooks
-@section User-defined command hooks
-@cindex command hooks
-@cindex hooks, for commands
-@cindex hooks, pre-command
+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.
-@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.
+@item
+A guess about what the bug is or what it depends on.
-@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.
+Such guesses are usually wrong. Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
-It is valid for a hook to call the command which it hooks. If this
-occurs, the hook is not re-executed, thereby avoiding infinte recursion.
+@c 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
-@c It would be nice if hookpost could be passed a parameter indicating
-@c if the command it hooks executed properly or not. FIXME!
-@kindex stop@r{, a pseudo-command}
-In addition, a pseudo-command, @samp{stop} exists. Defining
-(@samp{hook-stop}) makes the associated commands execute every time
-execution stops in your program: before breakpoint commands are run,
-displays are printed, or the stack frame is printed.
+@node Formatting Documentation
+@appendix Formatting Documentation
-For example, to ignore @code{SIGALRM} signals while
-single-stepping, but treat them normally during normal execution,
-you could define:
+@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}.
-@example
-define hook-stop
-handle SIGALRM nopass
-end
+The release also includes the source for the reference card. You
+can format it, using @TeX{}, by typing:
-define hook-run
-handle SIGALRM pass
-end
+@smallexample
+make refcard.dvi
+@end smallexample
-define hook-continue
-handle SIGLARM pass
-end
-@end example
+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.
-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:
+@cindex documentation
-@example
-define hook-echo
-echo <<<---
-end
+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.
-define hookpost-echo
-echo --->>>\n
-end
+@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.
-(@value{GDBP}) echo Hello World
-<<<---Hello World--->>>
-(@value{GDBP})
+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 example
+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:
-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).
+@smallexample
+cd gdb
+make gdb.info
+@end smallexample
-If you try to define a hook which does not match any known command, you
-get a warning from the @code{define} command.
+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.
-@node Command Files
-@section Command files
+@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.
-@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.
+@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.
-@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:
+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:
-@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.}.
+@smallexample
+make gdb.dvi
+@end smallexample
-@item
-Processes command line options and operands.
+Then give @file{gdb.dvi} to your @sc{dvi} printing program.
-@item
-Reads the init file (if any) in the current working directory.
+@node Installing GDB
+@appendix Installing @value{GDBN}
+@cindex configuring @value{GDBN}
+@cindex installation
-@item
-Reads command files specified by the @samp{-x} option.
-@end enumerate
+@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 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}).
+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}.
-@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:
+For example, the @value{GDBN} version @value{GDBVN} distribution is in the
+@file{gdb-@value{GDBVN}} directory. That directory contains:
-@cindex @file{.vxgdbinit}
-@itemize @bullet
-@item
-VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
+@table @code
+@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
+script for configuring @value{GDBN} and all its supporting libraries
-@cindex @file{.os68gdbinit}
-@item
-OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
+@item gdb-@value{GDBVN}/gdb
+the source specific to @value{GDBN} itself
-@cindex @file{.esgdbinit}
-@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
-@end itemize
+@item gdb-@value{GDBVN}/bfd
+source for the Binary File Descriptor library
-You can also request the execution of a command file with the
-@code{source} command:
+@item gdb-@value{GDBVN}/include
+@sc{gnu} include files
-@table @code
-@kindex source
-@item source @var{filename}
-Execute the command file @var{filename}.
-@end table
+@item gdb-@value{GDBVN}/libiberty
+source for the @samp{-liberty} free software library
-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.
+@item gdb-@value{GDBVN}/opcodes
+source for the library of opcode tables and disassemblers
-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 gdb-@value{GDBVN}/readline
+source for the @sc{gnu} command-line interface
-@node Output
-@section Commands for controlled output
+@item gdb-@value{GDBVN}/glob
+source for the @sc{gnu} filename pattern-matching subroutine
-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.
+@item gdb-@value{GDBVN}/mmalloc
+source for the @sc{gnu} memory-mapped malloc package
+@end table
-@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 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.
-A backslash at the end of @var{text} can be used, as in C, to continue
-the command onto subsequent lines. For example,
+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.
-@example
-echo This is some text\n\
-which is continued\n\
-onto several lines.\n
-@end example
+For example:
+
+@smallexample
+cd gdb-@value{GDBVN}
+./configure @var{host}
+make
+@end smallexample
-produces the same output as
+@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.)
-@example
-echo This is some text\n
-echo which is continued\n
-echo onto several lines.\n
-@end example
+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.
-@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.
+@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:
-@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.
+@smallexample
+sh configure @var{host}
+@end smallexample
-@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.
+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).
-@example
-printf (@var{string}, @var{expressions}@dots{});
-@end example
+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.
-For example, you can print two values in hex like this:
+For example, with version @value{GDBVN}, type the following to configure only
+the @code{bfd} subdirectory:
@smallexample
-printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
+@group
+cd gdb-@value{GDBVN}/bfd
+../configure @var{host}
+@end group
@end smallexample
-The only backslash-escape sequences that you can use in the format
-string are the simple ones that consist of backslash followed by a
-letter.
-@end table
+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.
-@node Emacs
-@chapter Using @value{GDBN} under @sc{gnu} Emacs
+@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
-@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}.
+@node Separate Objdir
+@section Compiling @value{GDBN} in another directory
-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.)
+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.
-Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
-things:
+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.)
-@itemize @bullet
-@item
-All ``terminal'' input and output goes through the Emacs buffer.
-@end itemize
+For example, with version @value{GDBVN}, you can build @value{GDBN} in a
+separate directory for a Sun 4 like this:
-This applies both to @value{GDBN} commands and their output, and to the input
-and output done by the program you are debugging.
+@smallexample
+@group
+cd gdb-@value{GDBVN}
+mkdir ../gdb-sun4
+cd ../gdb-sun4
+../gdb-@value{GDBVN}/configure sun4
+make
+@end group
+@end smallexample
-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.
+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}.
-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.
+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}.
-@itemize @bullet
-@item
-@value{GDBN} displays source code through Emacs.
-@end itemize
+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).
-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.
+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.
-Explicit @value{GDBN} @code{list} or search commands still produce output as
-usual, but you probably have no reason to use them from Emacs.
+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.
-@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 Config Names
+@section Specifying names for hosts and targets
-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
+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:
-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,
+@smallexample
+@var{architecture}-@var{vendor}-@var{os}
+@end smallexample
-@example
-(setq gdb-command-name "mygdb")
-@end example
+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}.
-@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.
+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:
-In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
-addition to the standard Shell mode commands:
+@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
-@table @kbd
-@item C-h m
-Describe the features of Emacs' @value{GDBN} Mode.
+@noindent
+@code{config.sub} is also distributed in the @value{GDBN} source
+directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
-@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 Configure Options
+@section @code{configure} options
-@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.
+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}.
-@item M-i
-Execute one instruction, like the @value{GDBN} @code{stepi} command; update
-display window accordingly.
+@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
-@item M-x gdb-nexti
-Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
-display window accordingly.
+@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{--}.
-@item C-c C-f
-Execute until exit from the selected stack frame, like the @value{GDBN}
-@code{finish} command.
+@table @code
+@item --help
+Display a quick summary of how to invoke @code{configure}.
-@item M-c
-Continue execution of your program, like the @value{GDBN} @code{continue}
-command.
+@item --prefix=@var{dir}
+Configure the source to install programs and files under directory
+@file{@var{dir}}.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
+@item --exec-prefix=@var{dir}
+Configure the source to install programs under directory
+@file{@var{dir}}.
-@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.
+@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}.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
+@item --norecursion
+Configure only the directory level where @code{configure} is executed; do not
+propagate configuration to subdirectories.
-@item M-d
-Go down the number of frames indicated by the numeric argument, like the
-@value{GDBN} @code{down} command.
+@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.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
+There is no convenient way to generate a list of all available targets.
-@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 &}.
+@item @var{host} @dots{}
+Configure @value{GDBN} to run on the specified @var{host}.
-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.
+There is no convenient way to generate a list of all available hosts.
@end table
-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.
+There are many other options available as well, but they are generally
+needed for special purposes only.
-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.
+@node Maintenance Commands
+@appendix Maintenance Commands
+@cindex maintenance commands
+@cindex internal commands
-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.
+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.
-@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
+@table @code
+@kindex maint info breakpoints
+@item @anchor{maint info breakpoints}maint info breakpoints
+Using the same format as @samp{info breakpoints}, display both the
+breakpoints you've set explicitly, and those @value{GDBN} is using for
+internal purposes. Internal breakpoints are shown with negative
+breakpoint numbers. The type column identifies what kind of breakpoint
+is shown:
-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
+@table @code
+@item breakpoint
+Normal, explicitly set breakpoint.
-@include annotate.texi
-@include gdbmi.texinfo
+@item watchpoint
+Normal, explicitly set watchpoint.
-@node GDB Bugs
-@chapter Reporting Bugs in @value{GDBN}
-@cindex bugs in @value{GDBN}
-@cindex reporting bugs in @value{GDBN}
+@item longjmp
+Internal breakpoint, used to handle correctly stepping through
+@code{longjmp} calls.
-Your bug reports play an essential role in making @value{GDBN} reliable.
+@item longjmp resume
+Internal breakpoint at the target of a @code{longjmp}.
-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 until
+Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
-In order for a bug report to serve its purpose, you must include the
-information that enables us to fix the bug.
+@item finish
+Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
-@menu
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
-@end menu
+@item shlib events
+Shared library events.
-@node Bug Criteria
-@section Have you found a bug?
-@cindex bug criteria
+@end table
-If you are not sure whether you have found a bug, here are some guidelines:
+@end table
-@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.
-@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 Remote Protocol
+@appendix @value{GDBN} Remote Serial Protocol
-@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''.
+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}.
-@item
-If you are an experienced user of debugging tools, your suggestions
-for improvement of @value{GDBN} are welcome in any case.
-@end itemize
+In the examples below, @samp{<-} and @samp{->} are used to indicate
+transmitted and received data respectfully.
-@node Bug Reporting
-@section How to report bugs
-@cindex bug reports
-@cindex @value{GDBN} bugs, reporting
+@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}:
-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.
+@smallexample
+@code{$}@var{packet-data}@code{#}@var{checksum}
+@end smallexample
+@noindent
-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...
+@cindex checksum, for @value{GDBN} remote
+@noindent
+The two-digit @var{checksum} is computed as the modulo 256 sum of all
+characters between the leading @samp{$} and the trailing @samp{#} (an
+eight bit unsigned checksum).
+
+Implementors should note that prior to @value{GDBN} 5.0 the protocol
+specification also included an optional two-digit @var{sequence-id}:
-In any event, we also recommend that you send bug reports for
-@value{GDBN} to this addresses:
+@smallexample
+@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
+@end smallexample
-@example
-bug-gdb@@gnu.org
-@end example
+@cindex sequence-id, for @value{GDBN} remote
+@noindent
+That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
+has never output @var{sequence-id}s. Stubs that handle packets added
+since @value{GDBN} 5.0 must not accept @var{sequence-id}.
-@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}.
+@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):
-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.
+@smallexample
+<- @code{$}@var{packet-data}@code{#}@var{checksum}
+-> @code{+}
+@end smallexample
+@noindent
-As a last resort, send bug reports on paper to:
+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).
-@example
-@sc{gnu} Debugger Bugs
-Free Software Foundation Inc.
-59 Temple Place - Suite 330
-Boston, MA 02111-1307
-USA
-@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).
-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!
+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.
-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.
+Implementors should note that prior to @value{GDBN} 5.0, the character
+@samp{:} could not appear as the third character in a packet (as it
+would potentially conflict with the @var{sequence-id}).
+
+Response @var{data} can be run-length encoded to save space. A @samp{*}
+means that the next character is an @sc{ascii} encoding giving a repeat count
+which stands for that many repetitions of the character preceding the
+@samp{*}. The encoding is @code{n+29}, yielding a printable character
+where @code{n >=3} (which is where rle starts to win). The printable
+characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
+value greater than 126 should not be used.
-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.
+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.
-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.
+So:
+@smallexample
+"@code{0* }"
+@end smallexample
+@noindent
+means the same as "0000".
-To enable us to fix the bug, you should include all these things:
+The error response returned for some packets includes a two character
+error number. That number is not well defined.
-@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}.
+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.
-Without this, we will not know whether there is any point in looking for
-the bug in the current version of @value{GDBN}.
+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.
-@item
-The type of machine you are using, and the operating system name and
-version number.
+Below is a complete list of all currently defined @var{command}s and
+their corresponding response @var{data}:
+@page
+@multitable @columnfractions .30 .30 .40
+@item Packet
+@tab Request
+@tab Description
+@item extended mode
+@tab @code{!}
+@tab
+Enable extended mode. In extended mode, the remote server is made
+persistent. The @samp{R} packet is used to restart the program being
+debugged.
@item
-What compiler (and its version) was used to compile @value{GDBN}---e.g.
-``@value{GCC}--2.8.1''.
+@tab reply @samp{OK}
+@tab
+The remote target both supports and has enabled extended mode.
+@item last signal
+@tab @code{?}
+@tab
+Indicate the reason the target halted. The reply is the same as for step
+and continue.
@item
-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.
+@tab reply
+@tab see below
-@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.
-If we were to try to guess the arguments, we would probably guess wrong
-and then we might not encounter the bug.
+@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
-A complete input script, and all necessary source files, that will
-reproduce the bug.
-
+@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
-A description of what behavior you observe that you believe is
-incorrect. For example, ``It gets a fatal signal.''
+@tab reply @code{OK}
+@item
+@tab reply @code{E}@var{NN}
-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.
+@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.}
-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 set breakpoint @strong{(deprecated)}
+@tab @code{B}@var{addr},@var{mode}
+@tab
+Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
+breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and
+@samp{z} packets.}
+@item continue
+@tab @code{c}@var{addr}
+@tab
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+current address.
@item
-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.
-
-The line numbers in our development sources will not match those in your
-sources. Your line numbers would convey no useful information to us.
+@tab reply
+@tab see below
-@end itemize
+@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
-Here are some things that are not necessary:
+@item toggle debug @strong{(deprecated)}
+@tab @code{d}
+@tab
+toggle debug flag.
-@itemize @bullet
+@item detach
+@tab @code{D}
+@tab
+Detach @value{GDBN} from the remote system. Sent to the remote target before
+@value{GDBN} disconnects.
@item
-A description of the envelope of the bug.
+@tab reply @emph{no response}
+@tab
+@value{GDBN} does not check for any response after sending this packet.
-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 reserved
+@tab @code{e}
+@tab Reserved for future use
-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.
+@item reserved
+@tab @code{E}
+@tab 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 reserved
+@tab @code{f}
+@tab Reserved for future use
-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 reserved
+@tab @code{F}
+@tab Reserved for future use
+@item read registers
+@tab @code{g}
+@tab Read general registers.
@item
-A patch for the bug.
-
-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.
-
-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.
-
-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.
-
+@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
-A guess about what the bug is or what it depends on.
-
-Such guesses are usually wrong. Even we cannot guess right about such
-things without first using the debugger to find the facts.
-@end itemize
-
-@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
+@tab @code{E}@var{NN}
+@tab for an error.
+@item write regs
+@tab @code{G}@var{XX...}
+@tab
+See @samp{g} for a description of the @var{XX...} data.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
-@node Formatting Documentation
-@appendix Formatting Documentation
+@item reserved
+@tab @code{h}
+@tab 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 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
-The release also includes the source for the reference card. You
-can format it, using @TeX{}, by typing:
+@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.
-@example
-make refcard.dvi
-@end example
+@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.
-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.
+@item signal then cycle step @strong{(reserved)}
+@tab @code{I}
+@tab
+See @samp{i} and @samp{S} for likely syntax and semantics.
-@cindex documentation
+@item reserved
+@tab @code{j}
+@tab Reserved for future use
-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.
+@item reserved
+@tab @code{J}
+@tab Reserved for future use
-@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.
+@item kill request
+@tab @code{k}
+@tab
+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?)}.
-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}.
+@item reserved
+@tab @code{l}
+@tab Reserved for future use
-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:
+@item reserved
+@tab @code{L}
+@tab Reserved for future use
-@example
-cd gdb
-make gdb.info
-@end example
+@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
-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.
+@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).
-@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 reserved
+@tab @code{n}
+@tab Reserved for future use
-@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 reserved
+@tab @code{N}
+@tab Reserved for future use
-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:
+@item reserved
+@tab @code{o}
+@tab Reserved for future use
-@example
-make gdb.dvi
-@end example
+@item reserved
+@tab @code{O}
+@tab Reserved for future use
-Then give @file{gdb.dvi} to your @sc{dvi} printing program.
+@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.
-@node Installing GDB
-@appendix Installing @value{GDBN}
-@cindex configuring @value{GDBN}
-@cindex installation
+@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
-@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
+@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}.
-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 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.
-For example, the @value{GDBN} version @value{GDBVN} distribution is in the
-@file{gdb-@value{GDBVN}} directory. That directory contains:
+@item reset @strong{(deprecated)}
+@tab @code{r}
+@tab
+Reset the entire system.
-@table @code
-@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
-script for configuring @value{GDBN} and all its supporting libraries
+@item remote restart
+@tab @code{R}@var{XX}
+@tab
+Restart the program being debugged. @var{XX}, while needed, is ignored.
+This packet is only available in extended mode.
+@item
+@tab
+no reply
+@tab
+The @samp{R} packet has no reply.
-@item gdb-@value{GDBVN}/gdb
-the source specific to @value{GDBN} itself
+@item step
+@tab @code{s}@var{addr}
+@tab
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+same address.
+@item
+@tab reply
+@tab see below
-@item gdb-@value{GDBVN}/bfd
-source for the Binary File Descriptor library
+@item step with signal
+@tab @code{S}@var{sig}@code{;}@var{addr}
+@tab
+Like @samp{C} but step not continue.
+@item
+@tab reply
+@tab see below
-@item gdb-@value{GDBVN}/include
-@sc{gnu} include files
+@item search
+@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
+@tab
+Search backwards starting at address @var{addr} for a match with pattern
+@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
+bytes. @var{addr} must be at least 3 digits.
-@item gdb-@value{GDBVN}/libiberty
-source for the @samp{-liberty} free software library
+@item thread alive
+@tab @code{T}@var{XX}
+@tab Find out if the thread XX is alive.
+@item
+@tab reply @code{OK}
+@tab thread is still alive
+@item
+@tab reply @code{E}@var{NN}
+@tab thread is dead
-@item gdb-@value{GDBVN}/opcodes
-source for the library of opcode tables and disassemblers
+@item reserved
+@tab @code{u}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/readline
-source for the @sc{gnu} command-line interface
+@item reserved
+@tab @code{U}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/glob
-source for the @sc{gnu} filename pattern-matching subroutine
+@item reserved
+@tab @code{v}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/mmalloc
-source for the @sc{gnu} memory-mapped malloc package
-@end table
+@item reserved
+@tab @code{V}
+@tab Reserved for future use
-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 reserved
+@tab @code{w}
+@tab Reserved for future use
-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 reserved
+@tab @code{W}
+@tab Reserved for future use
-For example:
+@item reserved
+@tab @code{x}
+@tab Reserved for future use
-@example
-cd gdb-@value{GDBVN}
-./configure @var{host}
-make
-@end example
+@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
-@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 reserved
+@tab @code{y}
+@tab Reserved for future use
-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 reserved
+@tab @code{Y}
+@tab Reserved for future use
-@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:
+@item remove break or watchpoint @strong{(draft)}
+@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
+@tab
+See @samp{Z}.
-@example
-sh configure @var{host}
-@end 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.
-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).
+@item reserved
+@tab <other>
+@tab Reserved for future use
-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.
+@end multitable
-For example, with version @value{GDBVN}, type the following to configure only
-the @code{bfd} subdirectory:
+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.
-@example
-@group
-cd gdb-@value{GDBVN}/bfd
-../configure @var{host}
-@end group
-@end example
+@multitable @columnfractions .4 .6
-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 @code{S}@var{AA}
+@tab @var{AA} is the signal number
-@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
+@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.
-@node Separate Objdir
-@section Compiling @value{GDBN} in another directory
+@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.
-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.
+@item @code{X}@var{AA}
+@tab
+The process terminated with signal @var{AA}.
-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.)
+@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.}
-For example, with version @value{GDBVN}, you can build @value{GDBN} in a
-separate directory for a Sun 4 like this:
+@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.
-@example
-@group
-cd gdb-@value{GDBVN}
-mkdir ../gdb-sun4
-cd ../gdb-sun4
-../gdb-@value{GDBVN}/configure sun4
-make
-@end group
-@end example
+@end multitable
-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}.
+The following set and query packets have already been defined.
-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}.
+@multitable @columnfractions .2 .2 .6
-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 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 @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.
+@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'}).
-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.
+@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.
-@node Config Names
-@section Specifying names for hosts and targets
+@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()}.
-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:
+@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.
-@example
-@var{architecture}-@var{vendor}-@var{os}
-@end example
+@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}
-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}.
+@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()}.
-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:
+@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.
-@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
+@item
+@tab reply @samp{}
+@tab
+When @samp{q}@samp{Rcmd} is not recognized.
+@item symbol lookup
+@tab @code{qSymbol::}
+@tab
+Notify the target that @value{GDBN} is prepared to serve symbol lookup
+requests. Accept requests from the target for the values of symbols.
+@item
+@tab
+@tab
+@item
+@tab reply @code{OK}
+@tab
+The target does not need to look up any (more) symbols.
+@item
+@tab reply @code{qSymbol:}@var{sym_name}
+@tab
+@sp 2
@noindent
-@code{config.sub} is also distributed in the @value{GDBN} source
-directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
-
-@node Configure Options
-@section @code{configure} options
+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.
-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}.
+@item symbol value
+@tab @code{qSymbol:}@var{sym_value}:@var{sym_name}
+@tab
+@sp 1
+@noindent
+Set the value of SYM_NAME to SYM_VALUE.
+@item
+@tab
+@tab
+@var{sym_name} (hex encoded) is the name of a symbol whose value
+the target has previously requested.
+@item
+@tab
+@tab
+@var{sym_value} (hex) is the value for symbol @var{sym_name}.
+If @value{GDBN} cannot supply a value for @var{sym_name}, then this
+field will be empty.
+@item
+@tab reply @code{OK}
+@tab
+The target does not need to look up any (more) symbols.
+@item
+@tab reply @code{qSymbol:}@var{sym_name}
+@tab
+@sp 2
+@noindent
+The target requests the value of a new symbol @var{sym_name} (hex encoded).
+@value{GDBN} will continue to supply the values of symbols (if available),
+until the target ceases to request them.
-@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
+@end multitable
-@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{--}.
+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.
-@table @code
-@item --help
-Display a quick summary of how to invoke @code{configure}.
+@multitable @columnfractions .5 .5
-@item --prefix=@var{dir}
-Configure the source to install programs and files under directory
-@file{@var{dir}}.
+@item MIPS32
+@tab
+All registers are transfered as thirty-two bit quantities in the order:
+32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
+registers; fsr; fir; fp.
-@item --exec-prefix=@var{dir}
-Configure the source to install programs under directory
-@file{@var{dir}}.
+@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}.
-@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}.
+@end multitable
-@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...}
+-> @code{+}
+<- @code{s}
+-> @code{+}
+@emph{time passes}
+-> @code{T001:1234123412341234}
+<- @code{+}
+<- @code{g}
+-> @code{+}
+-> @code{1455...}
+<- @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