\input texinfo @c -*-texinfo-*-
-@c Copyright 1988-2000
+@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
+@c 1999, 2000, 2001, 2002
@c Free Software Foundation, Inc.
@c
@c %**start of header
@syncodeindex fn cp
@c !!set GDB manual's edition---not the same as GDB version!
-@set EDITION Eighth
+@set EDITION Ninth
@c !!set GDB manual's revision date
-@set DATE March 2000
+@set DATE December 2001
@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.
of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
for @value{GDBN} Version @value{GDBVN}.
-Copyright (C) 1988-2000 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
+Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
+ 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``Free Software'' and ``Free Software Needs
+Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+(a) The Free Software Foundation's Back-Cover Text is: ``You have
+freedom to copy and modify this GNU Manual, like GNU software. Copies
+published by the Free Software Foundation raise funds for GNU
+development.''
@end ifinfo
@titlepage
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-2000 Free Software Foundation, Inc.
+Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
+1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
59 Temple Place - Suite 330, @*
Boston, MA 02111-1307 USA @*
ISBN 1-882114-77-9 @*
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``Free Software'' and ``Free Software Needs
+Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
+
+(a) The Free Software Foundation's Back-Cover Text is: ``You have
+freedom to copy and modify this GNU Manual, like GNU software. Copies
+published by the Free Software Foundation raise funds for GNU
+development.''
@end titlepage
@page
This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-2000 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
@menu
* Summary:: Summary of @value{GDBN}
* Stack:: Examining the stack
* Source:: Examining source files
* Data:: Examining data
+* 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
+* Remove Protocol:: GDB Remote Serial Protocol
+* GNU Free Documentation License:: The license for this documentation
* Index:: Index
@end menu
This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
-This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
+This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.
Copyright (C) 1988-2000 Free Software Foundation, Inc.
* 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.
* 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
+* Maintenance Commands:: Maintenance Commands
+* Remove Protocol:: GDB Remote Serial Protocol
+* GNU Free Documentation License:: The license for this documentation
* Index:: Index
@end menu
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.
David Johnson wrote the original COFF support; Pace Willison did
the original support for encapsulated COFF.
-Brent Benson of Harris Computer Systems contributed DWARF 2 support.
+Brent Benson of Harris Computer Systems contributed DWARF2 support.
Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
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
``process'', and there is often no way to get a core dump. @value{GDBN}
will warn you if it is unable to attach or to read core dumps.
+You can optionally have @code{@value{GDBP}} pass any arguments after the
+executable file to the inferior using @code{--args}. This option stops
+option processing.
+@example
+gdb --args gcc -O2 -c foo.c
+@end example
+This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
+@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
+
You can run @code{@value{GDBP}} without printing the front material, which describes
@value{GDBN}'s non-warranty, by specifying @code{-silent}:
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}
@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}.
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
command.
If you just want to see the list of alternatives in the first place, you
-can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
+can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
means @kbd{@key{META} ?}. You can type this either by holding down a
key designated as the @key{META} shift on your keyboard (if there is
one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
@value{GDBN} commands.
The most likely situation where you might need this is in typing the
-name of a C++ function. This is because C++ allows function overloading
-(multiple definitions of the same function, distinguished by argument
-type). For example, when you want to set a breakpoint you may need to
-distinguish whether you mean the version of @code{name} that takes an
-@code{int} parameter, @code{name(int)}, or the version that takes a
-@code{float} parameter, @code{name(float)}. To use the word-completion
-facilities in this situation, type a single quote @code{'} at the
-beginning of the function name. This alerts @value{GDBN} that it may need to
-consider more information than usual when you press @key{TAB} or
-@kbd{M-?} to request word completion:
+name of a C@t{++} function. This is because C@t{++} allows function
+overloading (multiple definitions of the same function, distinguished
+by argument type). For example, when you want to set a breakpoint you
+may need to distinguish whether you mean the version of @code{name}
+that takes an @code{int} parameter, @code{name(int)}, or the version
+that takes a @code{float} parameter, @code{name(float)}. To use the
+word-completion facilities in this situation, type a single quote
+@code{'} at the beginning of the function name. This alerts
+@value{GDBN} that it may need to consider more information than usual
+when you press @key{TAB} or @kbd{M-?} to request word completion:
@example
(@value{GDBP}) b 'bubble( @kbd{M-?}
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
@kindex path
@item path @var{directory}
Add @var{directory} to the front of the @code{PATH} environment variable
-(the search path for executables), for both @value{GDBN} and your program.
+(the search path for executables) that will be passed to your program.
+The value of @code{PATH} used by @value{GDBN} does not change.
You may specify several directory names, separated by whitespace or by a
system-dependent separator character (@samp{:} on Unix, @samp{;} on
MS-DOS and MS-Windows). If @var{directory} is already in the path, it
@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
@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:
@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
below.
@end quotation
-The @code{step} command only stops at the first instruction of a
-source line. This prevents the multiple stops that could otherwise occur in
-switch statements, for loops, etc. @code{step} continues to stop if a
-function that has debugging information is called within the line.
-In other words, @code{step} @emph{steps inside} any functions called
-within the line.
+The @code{step} command only stops at the first instruction of a source
+line. This prevents the multiple stops that could otherwise occur in
+@code{switch} statements, @code{for} loops, etc. @code{step} continues
+to stop if a function that has debugging information is called within
+the line. In other words, @code{step} @emph{steps inside} any functions
+called within the line.
Also, the @code{step} command only enters a function if there is line
number information for the function. Otherwise it acts like the
The @code{next} command only stops at the first instruction of a
source line. This prevents multiple stops that could otherwise occur in
-switch statements, for loops, etc.
+@code{switch} statements, @code{for} loops, etc.
+
+@kindex set step-mode
+@item set step-mode
+@cindex functions without line info, and stepping
+@cindex stepping into functions with no line info
+@itemx set step-mode on
+The @code{set step-mode on} command causes the @code{step} command to
+stop at the first instruction of a function which contains no debug line
+information rather than stepping over it.
+
+This is useful in cases where you may be interested in inspecting the
+machine instructions of a function which has no symbolic info and do not
+want @value{GDBN} to automatically skip over this function.
+
+@item set step-mode off
+Causes the @code{step} command to step over any functions which contains no
+debug information. This is the default.
@kindex finish
@item finish
signal.
@cindex handling signals
-Normally, @value{GDBN} is set up to ignore non-erroneous signals like @code{SIGALRM}
-(so as not to interfere with their role in the functioning of your program)
+Normally, @value{GDBN} is set up to let the non-erroneous signals like
+@code{SIGALRM} be silently passed to your program
+(so as not to interfere with their role in the program's functioning)
but to stop your program immediately whenever an error signal happens.
You can change these settings with the @code{handle} command.
@kindex handle
@item handle @var{signal} @var{keywords}@dots{}
-Change the way @value{GDBN} handles signal @var{signal}. @var{signal} can
-be the number of a signal or its name (with or without the @samp{SIG} at the
-beginning). The @var{keywords} say what change to make.
+Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
+can be the number of a signal or its name (with or without the
+@samp{SIG} at the beginning); a list of signal numbers of the form
+@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
+known signals. The @var{keywords} say what change to make.
@end table
@c @group
implies the @code{nostop} keyword as well.
@item pass
+@itemx noignore
@value{GDBN} should allow your program to see this signal; your program
can handle the signal, or else it may terminate if the signal is fatal
-and not handled.
+and not handled. @code{pass} and @code{noignore} are synonyms.
@item nopass
+@itemx ignore
@value{GDBN} should not allow your program to see this signal.
+@code{nopass} and @code{ignore} are synonyms.
@end table
@c @end group
command with @code{pass} or @code{nopass} to control whether your
program sees that signal when you continue.
+The default is set to @code{nostop}, @code{noprint}, @code{pass} for
+non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and
+@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the
+erroneous signals.
+
You can also use the @code{signal} command to prevent your program from
seeing a signal, or cause it to see a signal it normally would not see,
or to give it any signal at any time. For example, if your program stopped
* Convenience Vars:: Convenience variables
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
+* Memory Region Attributes:: Memory region attributes
@end menu
@node Expressions
(@value{GDBP}) p 'f2.c'::x
@end example
-@cindex C++ scope resolution
+@cindex C@t{++} scope resolution
This use of @samp{::} is very rarely in conflict with the very similar
-use of the same notation in C++. @value{GDBN} also supports use of the C++
+use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
scope resolution operator in @value{GDBN} expressions.
@c FIXME: Um, so what happens in one of those rare cases where it's in
@c conflict?? --mew
To 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 DWARF-2 (@samp{-gdwarf-2}), which is also an effective form for
+to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for
debug info. See @ref{Debugging Options,,Options for Debugging Your
Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
information.
@item a
@cindex unknown address, locating
+@cindex locate address
Print as an address, both absolute in hexadecimal and as an offset from
the nearest preceding symbol. You can use this format used to discover
where (in what function) an unknown address is located:
$3 = 0x54320 <_initialize_vx+396>
@end example
+@noindent
+The command @code{info symbol 0x54320} yields similar results.
+@xref{Symbols, info symbol}.
+
@item c
Regard as an integer and print it as a character constant.
@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
the ARM and x86 machines.
@end table
-@node Languages
-@chapter Using @value{GDBN} with Different Languages
-@cindex languages
+@node Memory Region Attributes
+@section Memory Region Attributes
+@cindex memory region attributes
-Although programming languages generally have common aspects, they are
-rarely expressed in the same manner. For instance, in ANSI C,
-dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
-Modula-2, it is accomplished by @code{p^}. Values can also be
-represented (and displayed) differently. Hex numbers in C appear as
-@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
+@dfn{Memory region attributes} allow you to describe special handling
+required by regions of your target's memory. @value{GDBN} uses attributes
+to determine whether to allow certain types of memory accesses; whether to
+use specific width accesses; and whether to cache target memory.
-@cindex working language
-Language-specific information is built into @value{GDBN} for some languages,
-allowing you to express operations like the above in your program's
-native language, and allowing @value{GDBN} to output values in a manner
-consistent with the syntax of your program's native language. The
-language you use to build expressions is called the @dfn{working
-language}.
+Defined memory regions can be individually enabled and disabled. When a
+memory region is disabled, @value{GDBN} uses the default attributes when
+accessing memory in that region. Similarly, if no memory regions have
+been defined, @value{GDBN} uses the default attributes when accessing
+all memory.
-@menu
-* Setting:: Switching between source languages
-* Show:: Displaying the language
-* Checks:: Type and range checks
-* Support:: Supported languages
-@end menu
+When a memory region is defined, it is given a number to identify it;
+to enable, disable, or remove a memory region, you specify that number.
-@node Setting
-@section Switching between source languages
+@table @code
+@kindex mem
+@item mem @var{address1} @var{address1} @var{attributes}@dots{}
+Define memory region bounded by @var{address1} and @var{address2}
+with attributes @var{attributes}@dots{}.
-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.
+@kindex delete mem
+@item delete mem @var{nums}@dots{}
+Remove memory region numbers @var{nums}.
-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}.
+@kindex disable mem
+@item disable mem @var{nums}@dots{}
+Disable memory region numbers @var{nums}.
+A disabled memory region is not forgotten.
+It may be enabled again later.
-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.
+@kindex enable mem
+@item enable mem @var{nums}@dots{}
+Enable memory region numbers @var{nums}.
-@menu
-* Filenames:: Filename extensions and languages.
-* Manually:: Setting the working language manually
-* Automatically:: Having @value{GDBN} infer the source language
-@end menu
+@kindex info mem
+@item info mem
+Print a table of all defined memory regions, with the following columns
+for each region.
-@node Filenames
-@subsection List of filename extensions and languages
+@table @emph
+@item Memory Region Number
+@item Enabled or Disabled.
+Enabled memory regions are marked with @samp{y}.
+Disabled memory regions are marked with @samp{n}.
-If a source file name ends in one of the following extensions, then
-@value{GDBN} infers that its language is the one indicated.
+@item Lo Address
+The address defining the inclusive lower bound of the memory region.
-@table @file
+@item Hi Address
+The address defining the exclusive upper bound of the memory region.
-@item .c
-C source file
+@item Attributes
+The list of attributes set for this memory region.
+@end table
+@end table
-@item .C
-@itemx .cc
-@itemx .cp
-@itemx .cpp
-@itemx .cxx
-@itemx .c++
-C++ source file
-@item .f
-@itemx .F
-Fortran source file
+@subsection Attributes
-@item .ch
-@itemx .c186
-@itemx .c286
-CHILL source file
+@subsubsection Memory Access Mode
+The access mode attributes set whether @value{GDBN} may make read or
+write accesses to a memory region.
-@item .mod
-Modula-2 source file
+While these attributes prevent @value{GDBN} from performing invalid
+memory accesses, they do nothing to prevent the target system, I/O DMA,
+etc. from accessing memory.
-@item .s
-@itemx .S
-Assembler source file. This actually behaves almost like C, but
-@value{GDBN} does not skip over function prologues when stepping.
+@table @code
+@item ro
+Memory is read only.
+@item wo
+Memory is write only.
+@item rw
+Memory is read/write (default).
@end table
-In addition, you may set the language associated with a filename
-extension. @xref{Show, , Displaying the language}.
+@subsubsection Memory Access Size
+The acccess size attributes tells @value{GDBN} to use specific sized
+accesses in the memory region. Often memory mapped device registers
+require specific sized accesses. If no access size attribute is
+specified, @value{GDBN} may use accesses of any size.
-@node Manually
-@subsection Setting the working language
+@table @code
+@item 8
+Use 8 bit memory accesses.
+@item 16
+Use 16 bit memory accesses.
+@item 32
+Use 32 bit memory accesses.
+@item 64
+Use 64 bit memory accesses.
+@end table
-If you allow @value{GDBN} to set the language automatically,
-expressions are interpreted the same way in your debugging session and
-your program.
+@c @subsubsection Hardware/Software Breakpoints
+@c The hardware/software breakpoint attributes set whether @value{GDBN}
+@c will use hardware or software breakpoints for the internal breakpoints
+@c used by the step, next, finish, until, etc. commands.
+@c
+@c @table @code
+@c @item hwbreak
+@c Always use hardware breakpoints
+@c @item swbreak (default)
+@c @end table
+
+@subsubsection Data Cache
+The data cache attributes set whether @value{GDBN} will cache target
+memory. While this generally improves performance by reducing debug
+protocol overhead, it can lead to incorrect results because @value{GDBN}
+does not know about volatile variables or memory mapped device
+registers.
-@kindex set language
-If you wish, you may set the language manually. To do this, issue the
-command @samp{set language @var{lang}}, where @var{lang} is the name of
-a language, such as
-@code{c} or @code{modula-2}.
-For a list of the supported languages, type @samp{set language}.
+@table @code
+@item cache
+Enable @value{GDBN} to cache target memory.
+@item nocache (default)
+Disable @value{GDBN} from caching target memory.
+@end table
-Setting the language manually prevents @value{GDBN} from updating the working
-language automatically. This can lead to confusion if you try
-to debug a program when the working language is not the same as the
-source language, when an expression is acceptable to both
-languages---but means different things. For instance, if the current
-source file were written in C, and @value{GDBN} was parsing Modula-2, a
-command such as:
+@c @subsubsection Memory Write Verification
+@c The memory write verification attributes set whether @value{GDBN}
+@c will re-reads data after each write to verify the write was successful.
+@c
+@c @table @code
+@c @item verify
+@c @item noverify (default)
+@c @end table
+
+@node 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.
-@example
-print a = b + c
-@end example
+@menu
+* Set Tracepoints::
+* Analyze Collected Data::
+* Tracepoint Variables::
+@end menu
-@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.
+@node Set Tracepoints
+@section Commands to Set Tracepoints
-@node Automatically
-@subsection Having @value{GDBN} infer the source language
+Before running such a @dfn{trace experiment}, an arbitrary number of
+tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a
+tracepoint has a number assigned to it by @value{GDBN}. Like with
+breakpoints, tracepoint numbers are successive integers starting from
+one. Many of the commands associated with tracepoints take the
+tracepoint number as their argument, to identify which tracepoint to
+work on.
-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.
+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 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.
+This section describes commands to set tracepoints and associated
+conditions and actions.
-@node Show
-@section Displaying the language
+@menu
+* Create and Delete Tracepoints::
+* Enable and Disable Tracepoints::
+* Tracepoint Passcounts::
+* Tracepoint Actions::
+* Listing Tracepoints::
+* Starting and Stopping Trace Experiment::
+@end menu
-The following commands help you find out which language is the
-working language, and also what language source files were written in.
+@node Create and Delete Tracepoints
+@subsection Create and Delete Tracepoints
-@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 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.
-@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.
+Here are some examples of using the @code{trace} command:
-@item info source
-Display the source language of this source file.
-@xref{Symbols, ,Examining the Symbol Table}, to identify the other
-information listed here.
+@smallexample
+(@value{GDBP}) @b{trace foo.c:121} // a source file and line number
+
+(@value{GDBP}) @b{trace +2} // 2 lines forward
+
+(@value{GDBP}) @b{trace my_function} // first source line of function
+
+(@value{GDBP}) @b{trace *my_function} // EXACT start address of function
+
+(@value{GDBP}) @b{trace *0x2117c4} // an address
+@end smallexample
+
+@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 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:
+@node Enable and Disable Tracepoints
+@subsection Enable and Disable 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 disable tracepoint
+@item disable tracepoint @r{[}@var{num}@r{]}
+Disable tracepoint @var{num}, or all tracepoints if no argument
+@var{num} is given. A disabled tracepoint will have no effect during
+the next trace experiment, but it is not forgotten. You can re-enable
+a disabled tracepoint using the @code{enable tracepoint} command.
-@item info extensions
-List all the filename extensions and the associated languages.
+@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
-@node Checks
-@section Type and range checking
+@node Tracepoint Passcounts
+@subsection Tracepoint Passcounts
-@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 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.
-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.
+Examples:
-@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.
+@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
-@menu
-* Type Checking:: An overview of type checking
-* Range Checking:: An overview of range checking
-@end menu
+@node Tracepoint Actions
+@subsection Tracepoint Action Lists
-@cindex type checking
-@cindex checks, type
-@node Type Checking
-@subsection An overview of type checking
+@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}.
-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,
+@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}.
@smallexample
-1 + 2 @result{} 3
-@exdent but
-@error{} 1 + 2.3
-@end smallexample
+(@value{GDBP}) @b{collect @var{data}} // collect some data
-The second example fails because the @code{CARDINAL} 1 is not
-type-compatible with the @code{REAL} 2.3.
+(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
-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.
+(@value{GDBP}) @b{end} // signals the end of actions.
+@end smallexample
-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.
+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.
-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.
+@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
-@value{GDBN} provides some additional commands for controlling the type checker:
+@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 set check@r{, type}
-@kindex set check type
-@kindex show check type
@table @code
-@item set check type auto
-Set type checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
-each language.
+@item $regs
+collect all registers
-@item set check type on
-@itemx set check type off
-Set type checking on or off, overriding the default setting for the
-current working language. Issue a warning if the setting does not
-match the language default. If any type mismatches occur in
-evaluating an expression while type checking is on, @value{GDBN} prints a
-message and aborts evaluation of the expression.
-
-@item set check type warn
-Cause the type checker to issue warnings, but to always attempt to
-evaluate the expression. Evaluating the expression may still
-be impossible for other reasons. For example, @value{GDBN} cannot add
-numbers and structures.
+@item $args
+collect all function arguments
-@item show type
-Show the current setting of the type checker, and whether or not @value{GDBN}
-is setting it automatically.
+@item $locals
+collect all local variables.
@end table
-@cindex range checking
-@cindex checks, range
-@node Range Checking
-@subsection An overview of range checking
+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.
-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.
+The command @code{info scope} (@pxref{Symbols, info scope}) is
+particularly useful for figuring out what data to collect.
-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.
+@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):
-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
+> while-stepping 12
+ > collect $regs, myglobal
+ > end
+>
+@end smallexample
-@example
-@var{m} + 1 @result{} @var{s}
-@end example
+@noindent
+You may abbreviate @code{while-stepping} as @code{ws} or
+@code{stepping}.
+@end table
-This, too, is specific to individual languages, and in some cases
-specific to individual compilers or machines. @xref{Support, ,
-Supported languages}, for further details on specific languages.
+@node Listing Tracepoints
+@subsection Listing Tracepoints
-@value{GDBN} provides some additional commands for controlling the range checker:
+@table @code
+@kindex info tracepoints
+@cindex information about tracepoints
+@item info tracepoints @r{[}@var{num}@r{]}
+Display information about the tracepoint @var{num}. If you don't specify
+a tracepoint number, displays information about all the tracepoints
+defined so far. For each tracepoint, the following information is
+shown:
+
+@itemize @bullet
+@item
+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 Starting and Stopping Trace Experiment
+@subsection Starting and Stopping Trace Experiment
-@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 tstart
+@cindex start a new trace experiment
+@cindex collected data discarded
+@item tstart
+This command takes no arguments. It starts the trace experiment, and
+begins collecting data. This has the side effect of discarding all
+the data collected in the trace buffer during the previous trace
+experiment.
-@item 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.
+@kindex tstop
+@cindex stop a running trace experiment
+@item tstop
+This command takes no arguments. It ends the trace experiment, and
+stops collecting data.
-@item 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).
+@strong{Note:} a trace experiment and data collection may stop
+automatically if any tracepoint's passcount is reached
+(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
-@item show range
-Show the current setting of the range checker, and whether or not it is
-being set automatically by @value{GDBN}.
+@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
-@node Support
-@section Supported languages
+Here is an example of the commands we described so far:
-@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.
+@smallexample
+(@value{GDBP}) @b{trace gdb_c_test}
+(@value{GDBP}) @b{actions}
+Enter actions for tracepoint #1, one per line.
+> collect $regs,$locals,$args
+> while-stepping 11
+ > collect $regs
+ > end
+> end
+(@value{GDBP}) @b{tstart}
+ [time passes @dots{}]
+(@value{GDBP}) @b{tstop}
+@end smallexample
-The following sections detail to what degree each source language is
-supported by @value{GDBN}. These sections are not meant to be language
-tutorials or references, but serve only as a reference guide to what the
-@value{GDBN} expression parser accepts, and what input and output
-formats should look like for different languages. There are many good
-books written on each of these languages; please look to these for a
-language reference or tutorial.
+
+@node Analyze Collected Data
+@section Using the collected data
+
+After the tracepoint experiment ends, you use @value{GDBN} commands
+for examining the trace data. The basic idea is that each tracepoint
+collects a trace @dfn{snapshot} every time it is hit and another
+snapshot every time it single-steps. All these snapshots are
+consecutively numbered from zero and go into a buffer, and you can
+examine them later. The way you examine them is to @dfn{focus} on a
+specific trace snapshot. When the remote stub is focused on a trace
+snapshot, it will respond to all @value{GDBN} requests for memory and
+registers by reading from the buffer which belongs to that snapshot,
+rather than from @emph{real} memory or registers of the program being
+debugged. This means that @strong{all} @value{GDBN} commands
+(@code{print}, @code{info registers}, @code{backtrace}, etc.) will
+behave as if we were currently debugging the program state as it was
+when the tracepoint occurred. Any requests for data that are not in
+the buffer will fail.
@menu
-* C:: C and C++
-* Modula-2:: Modula-2
-* Chill:: Chill
+* tfind:: How to select a trace snapshot
+* tdump:: How to display all data for a snapshot
+* save-tracepoints:: How to save tracepoints for a future run
@end menu
-@node C
-@subsection C and C++
+@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:
-@cindex C and C++
-@cindex expressions in C or C++
+@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
-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.
+Or, if we want to examine the variable @code{X} at each source line in
+the buffer:
-@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}).
+@smallexample
+(@value{GDBP}) @b{tfind start}
+(@value{GDBP}) @b{while ($trace_frame != -1)}
+> printf "Frame %d, X == %d\n", $trace_frame, X
+> tfind line
+> end
+
+Frame 0, X = 1
+Frame 7, X = 2
+Frame 13, X = 255
+@end smallexample
-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.
+@node tdump
+@subsection @code{tdump}
+@kindex tdump
+@cindex dump all data collected at tracepoint
+@cindex tracepoint data, display
+
+This command takes no arguments. It prints all the data collected at
+the current trace snapshot.
+
+@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'
+
+(@value{GDBP})
+@end smallexample
+
+@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
+
+@table @code
+@vindex $trace_frame
+@item (int) $trace_frame
+The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no
+snapshot is selected.
+
+@vindex $tracepoint
+@item (int) $tracepoint
+The tracepoint for the current trace snapshot.
+
+@vindex $trace_line
+@item (int) $trace_line
+The line number for the current trace snapshot.
+
+@vindex $trace_file
+@item (char []) $trace_file
+The source file for the current trace snapshot.
+
+@vindex $trace_func
+@item (char []) $trace_func
+The name of the function containing @code{$tracepoint}.
+@end table
+
+Note: @code{$trace_file} is not suitable for use in @code{printf},
+use @code{output} instead.
+
+Here's a simple example of using these convenience variables for
+stepping through all the trace snapshots and printing some of their
+data.
+
+@smallexample
+(@value{GDBP}) @b{tfind start}
+
+(@value{GDBP}) @b{while $trace_frame != -1}
+> output $trace_file
+> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
+> tfind
+> end
+@end smallexample
+
+@node Overlays
+@chapter Debugging Programs That Use Overlays
+@cindex overlays
+
+If your program is too large to fit completely in your target system's
+memory, you can sometimes use @dfn{overlays} to work around this
+problem. @value{GDBN} provides some support for debugging programs that
+use overlays.
@menu
-* C 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++
+* 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 Operators
-@subsubsection C and C++ operators
+@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.
-@cindex C and C++ operators
+@example
+@group
+ Data Instruction Larger
+Address Space Address Space Address Space
++-----------+ +-----------+ +-----------+
+| | | | | |
++-----------+ +-----------+ +-----------+<-- overlay 1
+| program | | main | | | load address
+| variables | | program | | overlay 1 |
+| and heap | | | ,---| |
++-----------+ | | | | |
+| | +-----------+ | +-----------+
++-----------+ | | | | |
+ mapped --->+-----------+ / +-----------+<-- overlay 2
+ address | overlay | <-' | overlay 2 | load address
+ | area | <-----| |
+ | | <---. +-----------+
+ | | | | |
+ +-----------+ | | |
+ | | | +-----------+<-- overlay 3
+ +-----------+ `--| | load address
+ | overlay 3 |
+ | |
+ +-----------+
+ | |
+ +-----------+
+
+ To map an overlay, copy its code from the larger address space
+ to the instruction address space. Since the overlays shown here
+ all use the same mapped address, only one may be mapped at a time.
+@end group
+@end example
-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.
+This diagram shows a system with separate data and instruction address
+spaces. For a system with a single address space for data and
+instructions, the diagram would be similar, except that the program
+variables and heap would share an address space with the main program
+and the overlay area.
-For the purposes of C and C++, the following definitions hold:
+An overlay loaded into instruction memory and ready for use is called a
+@dfn{mapped} overlay; its @dfn{mapped address} is its address in the
+instruction memory. An overlay not present (or only partially present)
+in instruction memory is called @dfn{unmapped}; its @dfn{load address}
+is its address in the larger memory. The mapped address is also called
+the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also
+called the @dfn{load memory address}, or @dfn{LMA}.
+
+Unfortunately, overlays are not a completely transparent way to adapt a
+program to limited instruction memory. They introduce a new set of
+global constraints you must keep in mind as you design your program:
@itemize @bullet
@item
-@emph{Integral types} include @code{int} with any of its storage-class
-specifiers; @code{char}; @code{enum}; and, for C++, @code{bool}.
+Before calling or returning to a function in an overlay, your program
+must make sure that overlay is actually mapped. Otherwise, the call or
+return will transfer control to the right address, but in the wrong
+overlay, and your program will probably crash.
@item
-@emph{Floating-point types} include @code{float}, @code{double}, and
-@code{long double} (if supported by the target platform).
+If the process of mapping an overlay is expensive on your system, you
+will need to choose your overlays carefully to minimize their effect on
+your program's performance.
@item
-@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
+The executable file you load onto your system must contain each
+overlay's instructions, appearing at the overlay's load address, not its
+mapped address. However, each overlay's instructions must be relocated
+and its symbols defined as if the overlay were at its mapped address.
+You can use GNU linker scripts to specify different load and relocation
+addresses for pieces of your program; see @ref{Overlay Description,,,
+ld.info, Using ld: the GNU linker}.
@item
-@emph{Scalar types} include all of the above.
+The procedure for loading executable files onto your system must be able
+to load their contents into the larger address space as well as the
+instruction and data spaces.
@end itemize
-@noindent
-The following operators are supported. They are listed here
-in order of increasing precedence:
+The overlay system described above is rather simple, and could be
+improved in many ways:
-@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.
+@itemize @bullet
-@item =
-Assignment. The value of an assignment expression is the value
-assigned. Defined on scalar types.
+@item
+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 @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
+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 ?:
-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
+You can use overlays to manage data, as well as instructions. In
+general, data overlays are even less transparent to your design than
+code overlays: whereas code overlays only require care when you call or
+return to functions, data overlays require care every time you access
+the data. Also, if you change the contents of a data overlay, you
+must copy its contents back out to its load address before you can copy a
+different data overlay into the same mapped area.
-@item ||
-Logical @sc{or}. Defined on integral types.
+@end itemize
-@item &&
-Logical @sc{and}. Defined on integral types.
-@item |
-Bitwise @sc{or}. Defined on integral 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 ^
-Bitwise exclusive-@sc{or}. Defined on integral types.
+@example
+(gdb) print main
+$3 = @{int ()@} 0x11a0 <main>
+@end example
+@noindent
+When overlay debugging is enabled, @value{GDBN} recognizes code in
+unmapped overlays, and prints the names of unmapped functions with
+asterisks around them. For example, if @code{foo} is a function in an
+unmapped overlay, @value{GDBN} prints it this way:
-@item &
-Bitwise @sc{and}. Defined on integral types.
+@example
+(gdb) overlay list
+No sections are mapped.
+(gdb) print foo
+$5 = @{int (int)@} 0x100000 <*foo*>
+@end example
+@noindent
+When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
+name normally:
-@item ==@r{, }!=
-Equality and inequality. Defined on scalar types. The value of these
-expressions is 0 for false and non-zero for true.
+@example
+(gdb) overlay list
+Section .ov.foo.text, loaded at 0x100000 - 0x100034,
+ mapped at 0x1016 - 0x104a
+(gdb) print foo
+$6 = @{int (int)@} 0x1016 <foo>
+@end example
-@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.
+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 <<@r{, }>>
-left shift, and right shift. 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 @@
-The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
-@item +@r{, }-
-Addition and subtraction. Defined on integral types, floating-point types and
-pointer types.
+@node Automatic Overlay Debugging
+@section Automatic Overlay Debugging
+@cindex automatic overlay debugging
-@item *@r{, }/@r{, }%
-Multiplication, division, and modulus. Multiplication and division are
-defined on integral and floating-point types. Modulus is defined on
-integral types.
+@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{, }--
-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.
+Here are the variables your overlay manager must define to support
+@value{GDBN}'s automatic overlay debugging:
-@item *
-Pointer dereferencing. Defined on pointer types. Same precedence as
-@code{++}.
+@table @asis
-@item &
-Address operator. Defined on variables. Same precedence as @code{++}.
+@item @code{_ovly_table}:
+This variable must be an array of the following structures:
-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.
+@example
+struct
+@{
+ /* The overlay's mapped address. */
+ unsigned long vma;
-@item -
-Negative. Defined on integral and floating-point types. Same
-precedence as @code{++}.
+ /* The size of the overlay, in bytes. */
+ unsigned long size;
-@item !
-Logical negation. Defined on integral types. Same precedence as
-@code{++}.
+ /* The overlay's load address. */
+ unsigned long lma;
-@item ~
-Bitwise complement operator. Defined on integral types. Same precedence as
-@code{++}.
+ /* Non-zero if the overlay is currently mapped;
+ zero otherwise. */
+ unsigned long mapped;
+@}
+@end example
+@item @code{_novlys}:
+This variable must be a four-byte signed integer, holding the total
+number of elements in @code{_ovly_table}.
-@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.
+@end table
-@item .*@r{, }->*
-Dereferences of pointers to members.
+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.
-@item []
-Array indexing. @code{@var{a}[@var{i}]} is defined as
-@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
-@item ()
-Function parameter list. Same precedence as @code{->}.
+@node Overlay Sample Program
+@section Overlay Sample Program
+@cindex overlay example program
-@item ::
-C++ scope resolution operator. Defined on @code{struct}, @code{union},
-and @code{class} types.
+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.
-@item ::
-Doubled colons also represent the @value{GDBN} scope operator
-(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
-above.
-@end table
+However, the @value{GDBN} source distribution does contain an overlaid
+program, with linker scripts for a few systems, as part of its test
+suite. The program consists of the following files from
+@file{gdb/testsuite/gdb.base}:
-If 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.
+@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:
-@menu
-* C Constants::
-@end menu
+@example
+$ d10v-elf-gcc -g -c overlays.c
+$ d10v-elf-gcc -g -c ovlymgr.c
+$ d10v-elf-gcc -g -c foo.c
+$ d10v-elf-gcc -g -c bar.c
+$ d10v-elf-gcc -g -c baz.c
+$ d10v-elf-gcc -g -c grbx.c
+$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
+ baz.o grbx.o -Wl,-Td10v.ld -o overlays
+@end example
-@node C Constants
-@subsubsection C and C++ constants
+The build process is identical for any other architecture, except that
+you must substitute the appropriate compiler and linker script for the
+target system for @code{d10v-elf-gcc} and @code{d10v.ld}.
-@cindex C and C++ constants
-@value{GDBN} allows you to express the constants of C and C++ in the
-following ways:
+@node Languages
+@chapter Using @value{GDBN} with Different Languages
+@cindex languages
-@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.
+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
-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.
+@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
-Enumerated constants consist of enumerated identifiers, or their
-integral equivalents.
+@menu
+* Setting:: Switching between source languages
+* Show:: Displaying the language
+* Checks:: Type and range checks
+* Support:: Supported languages
+@end menu
-@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.
+@node Setting
+@section Switching between source languages
-@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.
+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
-Pointer constants are an integral value. You can also write pointers
-to constants using the C operator @samp{&}.
+In addition to the working language, every source file that
+@value{GDBN} knows about has its own working language. For some object
+file formats, the compiler might indicate which language a particular
+source file is in. However, most of the time @value{GDBN} infers the
+language from the name of the file. The language of a source file
+controls whether C@t{++} names are demangled---this way @code{backtrace} can
+show each frame appropriately for its own language. There is no way to
+set the language of a source file from within @value{GDBN}, but you can
+set the language associated with a filename extension. @xref{Show, ,
+Displaying the language}.
-@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
+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 plus plus expressions::
-* C Defaults::
-* C Checks::
-
-* Debugging C::
+* Filenames:: Filename extensions and languages.
+* Manually:: Setting the working language manually
+* Automatically:: Having @value{GDBN} infer the source language
@end menu
-@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
+@node Filenames
+@subsection List of filename extensions and languages
-@enumerate
+If a source file name ends in one of the following extensions, then
+@value{GDBN} infers that its language is the one indicated.
-@cindex member functions
-@item
-Member function calls are allowed; you can use expressions like
+@table @file
-@example
-count = aml->GetOriginal(x, y)
-@end example
+@item .c
+C source file
-@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++.
+@item .C
+@itemx .cc
+@itemx .cp
+@itemx .cpp
+@itemx .cxx
+@itemx .c++
+C@t{++} source file
-@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.
+@item .f
+@itemx .F
+Fortran source file
-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 .ch
+@itemx .c186
+@itemx .c286
+CHILL source file
-Overload resolution is always performed, unless you have specified
-@code{set overload-resolution off}. @xref{Debugging C plus plus,
-,@value{GDBN} features for C++}.
+@item .mod
+Modula-2 source file
-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 .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
-The @value{GDBN} command-completion facility can simplify this;
-see @ref{Completion, ,Command completion}.
+In addition, you may set the language associated with a filename
+extension. @xref{Show, , Displaying the language}.
-@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.
+@node Manually
+@subsection Setting the working language
-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}.
+If you allow @value{GDBN} to set the language automatically,
+expressions are interpreted the same way in your debugging session and
+your program.
-@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
+@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}.
-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.
+Setting the language manually prevents @value{GDBN} from updating the working
+language automatically. This can lead to confusion if you try
+to debug a program when the working language is not the same as the
+source language, when an expression is acceptable to both
+languages---but means different things. For instance, if the current
+source file were written in C, and @value{GDBN} was parsing Modula-2, a
+command such as:
-@node C Defaults
-@subsubsection C and C++ defaults
+@example
+print a = b + c
+@end example
-@cindex C and C++ defaults
+@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.
-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.
+@node Automatically
+@subsection Having @value{GDBN} infer the source language
-If you allow @value{GDBN} to set the language automatically, it
-recognizes source files whose names end with @file{.c}, @file{.C}, or
-@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
-these files, it sets the working language to C or C++.
-@xref{Automatically, ,Having @value{GDBN} infer the source language},
-for further details.
+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.
-@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.
+This may not seem necessary for most programs, which are written
+entirely in one source language. However, program modules and libraries
+written in one source language can be used by a main program written in
+a different source language. Using @samp{set language auto} in this
+case frees you from having to set the working language manually.
-@node C Checks
-@subsubsection C and C++ type and range checks
+@node Show
+@section Displaying the language
-@cindex C and C++ checks
+The following commands help you find out which language is the
+working language, and also what language source files were written in.
-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:
+@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.
-@itemize @bullet
-@item
-The two variables are structured and have the same structure, union, or
-enumerated tag.
+@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
-The two variables have the same type name, or types that have been
-declared equivalent through @code{typedef}.
+@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
-@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
+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:
-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.
+@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 Debugging C
-@subsubsection @value{GDBN} and C
+@item info extensions
+List all the filename extensions and the associated languages.
+@end table
-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{@{...@}}.
+@node Checks
+@section Type and range checking
-The @code{@@} operator aids in the debugging of dynamic arrays, formed
-with pointers and a memory allocation function. @xref{Expressions,
-,Expressions}.
+@quotation
+@emph{Warning:} In this release, the @value{GDBN} commands for type and range
+checking are included, but they do not yet have any effect. This
+section documents the intended facilities.
+@end quotation
+@c FIXME remove warning when type/range code added
+
+Some languages are designed to guard you against making seemingly common
+errors through a series of compile- and run-time checks. These include
+checking the type of arguments to functions and operators, and making
+sure mathematical overflows are caught at run time. Checks such as
+these help to ensure a program's correctness once it has been compiled
+by eliminating type mismatches, and providing active checks for range
+errors when your program is running.
+
+@value{GDBN} can check for conditions like the above if you wish.
+Although @value{GDBN} does not check the statements in your program, it
+can check expressions entered directly into @value{GDBN} for evaluation via
+the @code{print} command, for example. As with the working language,
+@value{GDBN} can also decide whether or not to check automatically based on
+your program's source language. @xref{Support, ,Supported languages},
+for the default settings of supported languages.
@menu
-* Debugging C plus plus::
+* Type Checking:: An overview of type checking
+* Range Checking:: An overview of range checking
@end menu
-@node Debugging C plus plus
-@subsubsection @value{GDBN} features for C++
-
-@cindex commands for C++
+@cindex type checking
+@cindex checks, type
+@node Type Checking
+@subsection An overview of type checking
-Some @value{GDBN} commands are particularly useful with C++, and some are
-designed specifically for use with C++. Here is a summary:
+Some languages, such as Modula-2, are strongly typed, meaning that the
+arguments to operators and functions have to be of the correct type,
+otherwise an error occurs. These checks prevent type mismatch
+errors from ever causing any run-time problems. For example,
-@table @code
-@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}.
+@smallexample
+1 + 2 @result{} 3
+@exdent but
+@error{} 1 + 2.3
+@end smallexample
-@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}.
+The second example fails because the @code{CARDINAL} 1 is not
+type-compatible with the @code{REAL} 2.3.
-@cindex C++ exception handling
-@item catch throw
-@itemx catch catch
-Debug C++ exception handling using these commands. @xref{Set
-Catchpoints, , Setting catchpoints}.
+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.
-@cindex inheritance
-@item ptype @var{typename}
-Print inheritance relationships as well as other information for type
-@var{typename}.
-@xref{Symbols, ,Examining the Symbol Table}.
+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.
-@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}.
+Each language defines to what degree it is strict about type. For
+instance, both Modula-2 and C require the arguments to arithmetical
+operators to be numbers. In C, enumerated types and pointers can be
+represented as numbers, so that they are valid arguments to mathematical
+operators. @xref{Support, ,Supported languages}, for further
+details on specific languages.
-@item 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 type 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{, type}
+@kindex set check type
+@kindex show check type
+@table @code
+@item set check type auto
+Set type checking on or off based on the current working language.
+@xref{Support, ,Supported languages}, for the default settings for
+each language.
-@kindex 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 type on
+@itemx set check type off
+Set type checking on or off, overriding the default setting for the
+current working language. Issue a warning if the setting does not
+match the language default. If any type mismatches occur in
+evaluating an expression while type checking is on, @value{GDBN} prints a
+message and aborts evaluation of the expression.
-@item set 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 type warn
+Cause the type checker to issue warnings, but to always attempt to
+evaluate the expression. Evaluating the expression may still
+be impossible for other reasons. For example, @value{GDBN} cannot add
+numbers and structures.
-@item @r{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 type
+Show the current setting of the type checker, and whether or not @value{GDBN}
+is setting it automatically.
@end table
-@node Modula-2
-@subsection Modula-2
+@cindex range checking
+@cindex checks, range
+@node Range Checking
+@subsection An overview of range checking
-@cindex Modula-2, @value{GDBN} support
+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.
-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.
+For expressions you use in @value{GDBN} commands, you can tell
+@value{GDBN} to treat range errors in one of three ways: ignore them,
+always treat them as errors and abandon the expression, or issue
+warnings but evaluate the expression anyway.
+
+A range error can result from numerical overflow, from exceeding an
+array index bound, or when you type a constant that is not a member
+of any type. Some languages, however, do not treat overflows as an
+error. In many implementations of C, mathematical overflow causes the
+result to ``wrap around'' to lower values---for example, if @var{m} is
+the largest integer value, and @var{s} is the smallest, then
+
+@example
+@var{m} + 1 @result{} @var{s}
+@end example
+
+This, too, is specific to individual languages, and in some cases
+specific to individual compilers or machines. @xref{Support, ,
+Supported languages}, for further details on specific languages.
+
+@value{GDBN} provides some additional commands for controlling the range checker:
+
+@kindex set check@r{, range}
+@kindex set check range
+@kindex show check range
+@table @code
+@item set check range auto
+Set range checking on or off based on the current working language.
+@xref{Support, ,Supported languages}, for the default settings for
+each language.
+
+@item set check range on
+@itemx set check range off
+Set range checking on or off, overriding the default setting for the
+current working language. A warning is issued if the setting does not
+match the language default. If a range error occurs and range checking is on,
+then a message is printed and evaluation of the expression is aborted.
+
+@item set check range warn
+Output messages when the @value{GDBN} range checker detects a range error,
+but attempt to evaluate the expression anyway. Evaluating the
+expression may still be impossible for other reasons, such as accessing
+memory that the process does not own (a typical example from many Unix
+systems).
+
+@item show range
+Show the current setting of the range checker, and whether or not it is
+being set automatically by @value{GDBN}.
+@end table
+
+@node Support
+@section Supported languages
+
+@value{GDBN} supports C, C@t{++}, Fortran, Java, Chill, assembly, and Modula-2.
+@c This is false ...
+Some @value{GDBN} features may be used in expressions regardless of the
+language you use: the @value{GDBN} @code{@@} and @code{::} operators,
+and the @samp{@{type@}addr} construct (@pxref{Expressions,
+,Expressions}) can be used with the constructs of any supported
+language.
+
+The following sections detail to what degree each source language is
+supported by @value{GDBN}. These sections are not meant to be language
+tutorials or references, but serve only as a reference guide to what the
+@value{GDBN} expression parser accepts, and what input and output
+formats should look like for different languages. There are many good
+books written on each of these languages; please look to these for a
+language reference or tutorial.
-@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:
-
-@itemize @bullet
+often defined on groups of types.
-@item
-@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
-their subranges.
+For the purposes of C and C@t{++}, the following definitions hold:
-@item
-@emph{Character types} consist of @code{CHAR} and its subranges.
+@itemize @bullet
@item
-@emph{Floating-point types} consist of @code{REAL}.
+@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{Pointer types} consist of anything declared as @code{POINTER TO
-@var{type}}.
+@emph{Floating-point types} include @code{float}, @code{double}, and
+@code{long double} (if supported by the target platform).
@item
-@emph{Scalar types} consist of all of the above.
+@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
@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 @@
-The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+@item &
+Bitwise @sc{and}. Defined on integral types.
-@item +@r{, }-
-Addition and subtraction on integral and floating-point types, or union
-and difference on set 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 *
-Multiplication on integral and floating-point types, or set intersection
-on set types.
+@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 /
-Division on floating-point types, or symmetric set difference on set
-types. Same precedence as @code{*}.
+@item <<@r{, }>>
+left shift, and right shift. Defined on integral types.
-@item DIV@r{, }MOD
-Integer division and remainder. Defined on integral types. Same
-precedence as @code{*}.
+@item @@
+The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
-@item -
-Negative. Defined on @code{INTEGER} and @code{REAL} data.
+@item +@r{, }-
+Addition and subtraction. Defined on integral types, floating-point types and
+pointer types.
-@item ^
-Pointer dereferencing. Defined on pointer types.
-
-@item NOT
-Boolean negation. Defined on boolean types. Same precedence as
-@code{^}.
-
-@item .
-@code{RECORD} field selector. Defined on @code{RECORD} data. Same
-precedence as @code{^}.
-
-@item []
-Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
-
-@item ()
-Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
-as @code{^}.
+@item *@r{, }/@r{, }%
+Multiplication, division, and modulus. Multiplication and division are
+defined on integral and floating-point types. Modulus is defined on
+integral types.
-@item ::@r{, }.
-@value{GDBN} and Modula-2 scope operators.
-@end table
+@item ++@r{, }--
+Increment and decrement. When appearing before a variable, the
+operation is performed before the variable is used in an expression;
+when appearing after it, the variable's value is used before the
+operation takes place.
-@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 *
+Pointer dereferencing. Defined on pointer types. Same precedence as
+@code{++}.
-@cindex Modula-2 built-ins
-@node Built-In Func/Proc
-@subsubsection Built-in functions and procedures
+@item &
+Address operator. Defined on variables. Same precedence as @code{++}.
-Modula-2 also makes available several built-in procedures and functions.
-In describing these, the following metavariables are used:
+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.
-@table @var
+@item -
+Negative. Defined on integral and floating-point types. Same
+precedence as @code{++}.
-@item a
-represents an @code{ARRAY} variable.
+@item !
+Logical negation. Defined on integral types. Same precedence as
+@code{++}.
-@item c
-represents a @code{CHAR} constant or variable.
+@item ~
+Bitwise complement operator. Defined on integral types. Same precedence as
+@code{++}.
-@item i
-represents a variable or constant of integral type.
-@item m
-represents an identifier that belongs to a set. Generally used in the
-same function with the metavariable @var{s}. The type of @var{s} should
-be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
+@item .@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 n
-represents a variable or constant of integral or floating-point type.
+@item .*@r{, }->*
+Dereferences of pointers to members.
-@item r
-represents a variable or constant of floating-point type.
+@item []
+Array indexing. @code{@var{a}[@var{i}]} is defined as
+@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
-@item t
-represents a type.
+@item ()
+Function parameter list. Same precedence as @code{->}.
-@item v
-represents a variable.
+@item ::
+C@t{++} scope resolution operator. Defined on @code{struct}, @code{union},
+and @code{class} types.
-@item x
-represents a variable or constant of one of many types. See the
-explanation of the function for details.
+@item ::
+Doubled colons also represent the @value{GDBN} scope operator
+(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
+above.
@end table
-All Modula-2 built-in procedures also return a result, described below.
-
-@table @code
-@item ABS(@var{n})
-Returns the absolute value of @var{n}.
-
-@item CAP(@var{c})
-If @var{c} is a lower case letter, it returns its upper case
-equivalent, otherwise it returns its argument.
-
-@item CHR(@var{i})
-Returns the character whose ordinal value is @var{i}.
-
-@item DEC(@var{v})
-Decrements the value in the variable @var{v} by one. Returns the new value.
-
-@item DEC(@var{v},@var{i})
-Decrements the value in the variable @var{v} by @var{i}. Returns the
-new value.
+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.
-@item EXCL(@var{m},@var{s})
-Removes the element @var{m} from the set @var{s}. Returns the new
-set.
+@menu
+* C Constants::
+@end menu
-@item FLOAT(@var{i})
-Returns the floating point equivalent of the integer @var{i}.
+@node C Constants
+@subsubsection C and C@t{++} constants
-@item HIGH(@var{a})
-Returns the index of the last member of @var{a}.
+@cindex C and C@t{++} constants
-@item INC(@var{v})
-Increments the value in the variable @var{v} by one. Returns the new value.
+@value{GDBN} allows you to express the constants of C and C@t{++} in the
+following ways:
-@item INC(@var{v},@var{i})
-Increments the value in the variable @var{v} by @var{i}. Returns the
-new value.
+@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 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
+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 MAX(@var{t})
-Returns the maximum value of the type @var{t}.
+@item
+Enumerated constants consist of enumerated identifiers, or their
+integral equivalents.
-@item MIN(@var{t})
-Returns the minimum value of the type @var{t}.
+@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 ODD(@var{i})
-Returns boolean TRUE if @var{i} is an odd number.
+@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 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
+Pointer constants are an integral value. You can also write pointers
+to constants using the C operator @samp{&}.
-@item SIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+@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 TRUNC(@var{r})
-Returns the integral part of @var{r}.
+@menu
+* C plus plus expressions::
+* C Defaults::
+* C Checks::
-@item VAL(@var{t},@var{i})
-Returns the member of the type @var{t} whose ordinal value is @var{i}.
-@end table
+* Debugging C::
+@end menu
+@node C plus plus expressions
+@subsubsection C@t{++} expressions
+
+@cindex expressions in C@t{++}
+@value{GDBN} expression handling can interpret most C@t{++} expressions.
+
+@cindex C@t{++} support, not in @sc{coff}
+@cindex @sc{coff} versus C@t{++}
+@cindex C@t{++} and object formats
+@cindex object formats and C@t{++}
+@cindex a.out and C@t{++}
+@cindex @sc{ecoff} and C@t{++}
+@cindex @sc{xcoff} and C@t{++}
+@cindex @sc{elf}/stabs and C@t{++}
+@cindex @sc{elf}/@sc{dwarf} and C@t{++}
+@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
+@c periodically whether this has happened...
@quotation
-@emph{Warning:} Sets and their operations are not yet supported, so
-@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
-an error.
+@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
-@cindex Modula-2 constants
-@node M2 Constants
-@subsubsection Constants
-
-@value{GDBN} allows you to express the constants of Modula-2 in the following
-ways:
-
-@itemize @bullet
+@enumerate
+@cindex member functions
@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}.
+Member function calls are allowed; you can use expressions like
-@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.
+@example
+count = aml->GetOriginal(x, y)
+@end example
+@vindex this@r{, inside C@t{++} member functions}
+@cindex namespace in C@t{++}
@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}.
+While a member function is active (in the selected stack frame), your
+expressions have the same namespace available as the member function;
+that is, @value{GDBN} allows implicit references to the class instance
+pointer @code{this} following the same rules as C@t{++}.
+@cindex call overloaded functions
+@cindex overloaded functions, calling
+@cindex type conversions in C@t{++}
@item
-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.
+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
-Enumerated constants consist of an enumerated identifier.
+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
-Boolean constants consist of the identifiers @code{TRUE} and
-@code{FALSE}.
+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
-Pointer constants consist of integral values only.
+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
-Set constants are not yet supported.
-@end itemize
+The @value{GDBN} command-completion facility can simplify this;
+see @ref{Completion, ,Command completion}.
-@node M2 Defaults
-@subsubsection Modula-2 defaults
-@cindex Modula-2 defaults
+@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.
-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.
+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}.
-If you allow @value{GDBN} to set the language automatically, then entering
-code compiled from a file whose name ends with @file{.mod} sets the
-working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
-the language automatically}, for further details.
+@item
+@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
-@node Deviations
-@subsubsection Deviations from standard Modula-2
-@cindex Modula-2, deviations from
+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.
-A few changes have been made to make Modula-2 programs easier to debug.
-This is done primarily via loosening its type strictness:
+@node C Defaults
+@subsubsection C and C@t{++} defaults
-@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 C and C@t{++} defaults
-@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.
+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.
-@item
-The assignment operator (@code{:=}) returns the value of its right-hand
-argument.
+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.
-@item
-All built-in procedures both modify @emph{and} return their argument.
-@end itemize
+@c Type checking is (a) primarily motivated by Modula-2, and (b)
+@c unimplemented. If (b) changes, it might make sense to let this node
+@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
-@node M2 Checks
-@subsubsection Modula-2 type and range checks
-@cindex Modula-2 checks
+@node C Checks
+@subsubsection C and C@t{++} type and range checks
-@quotation
-@emph{Warning:} in this release, @value{GDBN} does not yet perform type or
-range checking.
-@end quotation
-@c FIXME remove warning when type/range checks added
+@cindex C and C@t{++} checks
-@value{GDBN} considers two Modula-2 variables type equivalent if:
+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
-They are of types that have been declared equivalent via a @code{TYPE
-@var{t1} = @var{t2}} statement
+The two variables are structured and have the same structure, union, or
+enumerated tag.
@item
-They have been declared on the same line. (Note: This is true of the
-@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
-@end itemize
-
-As long as type checking is enabled, any attempt to combine variables
-whose types are not equivalent is an error.
+The two variables have the same type name, or types that have been
+declared equivalent through @code{typedef}.
-Range checking is done on all mathematical operations, assignment, array
-index bounds, and all built-in functions and procedures.
+@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
-@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
+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.
-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:
+@node Debugging C
+@subsubsection @value{GDBN} and C
-@example
+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{@{...@}}.
-@var{module} . @var{id}
-@var{scope} :: @var{id}
-@end example
+The @code{@@} operator aids in the debugging of dynamic arrays, formed
+with pointers and a memory allocation function. @xref{Expressions,
+,Expressions}.
-@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.
+@menu
+* Debugging C plus plus::
+@end menu
-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}.
+@node Debugging C plus plus
+@subsubsection @value{GDBN} features for C@t{++}
-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}.
+@cindex commands for C@t{++}
-@node GDB/M2
-@subsubsection @value{GDBN} and Modula-2
+Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
+designed specifically for use with C@t{++}. Here is a summary:
-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.
+@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}.
-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.
+@cindex overloading in C@t{++}
+@item rbreak @var{regex}
+Setting breakpoints using regular expressions is helpful for setting
+breakpoints on overloaded functions that are not members of any special
+classes.
+@xref{Set Breaks, ,Setting breakpoints}.
-@cindex @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.
+@cindex C@t{++} exception handling
+@item catch throw
+@itemx catch catch
+Debug C@t{++} exception handling using these commands. @xref{Set
+Catchpoints, , Setting catchpoints}.
-@node Chill
-@subsection Chill
+@cindex inheritance
+@item ptype @var{typename}
+Print inheritance relationships as well as other information for type
+@var{typename}.
+@xref{Symbols, ,Examining the Symbol Table}.
-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.
+@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}.
-@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 set print object
+@itemx show print object
+Choose whether to print derived (actual) or declared types of objects.
+@xref{Print Settings, ,Print settings}.
-@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 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}).)
-@node How modes are displayed
-@subsubsection How modes are displayed
+@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.
-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 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.
-@c FIXME: this @table's contents effectively disable @code by using @r
-@c on every @item. So why does it need @code?
-@table @code
-@item @r{@emph{Discrete modes:}}
-@itemize @bullet
-@item
-@emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT,
-UINT, LONG, ULONG},
-@item
-@emph{Boolean Mode} which is predefined by @code{BOOL},
-@item
-@emph{Character Mode} which is predefined by @code{CHAR},
-@item
-@emph{Set Mode} which is displayed by the keyword @code{SET}.
-@smallexample
-(@value{GDBP}) ptype x
-type = SET (karli = 10, susi = 20, fritzi = 100)
-@end smallexample
-If the type is an unnumbered set the set element values are omitted.
-@item
-@emph{Range Mode} which is displayed by
-@smallexample
-@code{type = <basemode>(<lower bound> : <upper bound>)}
-@end smallexample
-where @code{<lower bound>, <upper bound>} can be of any discrete literal
-expression (e.g. set element names).
-@end itemize
+@item @r{Overloaded symbol names}
+You can specify a particular definition of an overloaded symbol, using
+the same notation that is used to declare such symbols in C@t{++}: type
+@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
+also use the @value{GDBN} command-line word completion facilities to list the
+available choices, or to finish the type list for you.
+@xref{Completion,, Command completion}, for details on how to do this.
+@end table
-@item @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
+@node Modula-2
+@subsection Modula-2
-@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
+@cindex Modula-2, @value{GDBN} support
-@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.
+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.
-@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
+@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:
-@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.
+@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
+their subranges.
+
@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
+@emph{Character types} consist of @code{CHAR} and its subranges.
-@item @r{@emph{Timing Modes:}}
-@itemize @bullet
@item
-@emph{Duration Mode} which is predefined by @code{DURATION}
+@emph{Floating-point types} consist of @code{REAL}.
+
@item
-@emph{Absolute Time Mode} which is predefined by @code{TIME}
-@end itemize
+@emph{Pointer types} consist of anything declared as @code{POINTER TO
+@var{type}}.
-@item @r{@emph{Real Modes:}}
-Real Modes are predefined with @code{REAL} and @code{LONG_REAL}.
+@item
+@emph{Scalar types} consist of all of the above.
-@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
+@emph{Set types} consist of @code{SET} and @code{BITSET} types.
+
@item
-@emph{Bit String Mode} which is displayed by
-@smallexample
-@code{BOOLS(<string
-length>)}
-@end smallexample
+@emph{Boolean types} consist of @code{BOOLEAN}.
@end itemize
-@item @r{@emph{Array Mode:}}
-The Array Mode is displayed by the keyword @code{ARRAY(<range>)}
-followed by the element mode (which may in turn be an array mode).
-@smallexample
-(@value{GDBP}) ptype x
-type = ARRAY (1:42)
- ARRAY (1:20)
- SET (karli = 10, susi = 20, fritzi = 100)
-@end smallexample
+@noindent
+The following operators are supported, and appear in order of
+increasing precedence:
-@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
+@table @code
+@item ,
+Function argument or array index separator.
-@node Locations
-@subsubsection Locations and their accesses
+@item :=
+Assignment. The value of @var{var} @code{:=} @var{value} is
+@var{value}.
-A location in Chill is an object which can contain values.
+@item <@r{, }>
+Less than, greater than on integral, floating-point, or enumerated
+types.
-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 <=@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 pseudo-location @code{RESULT} (or @code{result}) can be used to
-display or change the result of a currently-active procedure:
+@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.
-@smallexample
-set result := EXPR
-@end smallexample
+@item IN
+Set membership. Defined on set types and the types of their members.
+Same precedence as @code{<}.
-@noindent
-This does the same as the Chill action @code{RESULT EXPR} (which
-is not available in @value{GDBN}).
+@item OR
+Boolean disjunction. Defined on boolean types.
-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 AND@r{, }&
+Boolean conjunction. Defined on boolean types.
-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 @@
+The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
-@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 +@r{, }-
+Addition and subtraction on integral and floating-point types, or union
+and difference on set types.
-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 *
+Multiplication on integral and floating-point types, or set intersection
+on set types.
-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 /
+Division on floating-point types, or symmetric set difference on set
+types. Same precedence as @code{*}.
-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}.
+@item DIV@r{, }MOD
+Integer division and remainder. Defined on integral types. Same
+precedence as @code{*}.
-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.
+@item -
+Negative. Defined on @code{INTEGER} and @code{REAL} data.
-@smallexample
-(@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX
-@end smallexample
+@item ^
+Pointer dereferencing. Defined on pointer types.
-@node Values and their Operations
-@subsubsection Values and their Operations
+@item NOT
+Boolean negation. Defined on boolean types. Same precedence as
+@code{^}.
-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 .
+@code{RECORD} field selector. Defined on @code{RECORD} data. Same
+precedence as @code{^}.
-This section describes how values have to be specified and which
-operations are legal to be used with such values.
+@item []
+Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
-@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 ()
+Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
+as @code{^}.
-@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 ::@r{, }.
+@value{GDBN} and Modula-2 scope operators.
+@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
+@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 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
+@node Built-In Func/Proc
+@subsubsection Built-in functions and procedures
+@cindex Modula-2 built-ins
-@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.
+Modula-2 also makes available several built-in procedures and functions.
+In describing these, the following metavariables are used:
-@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.
+@table @var
-@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 a
+represents an @code{ARRAY} variable.
-@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 c
+represents a @code{CHAR} constant or variable.
-@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 i
+represents a variable or constant of integral type.
-@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 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 duration mode locations are represented by @code{ULONG} literals.
+@item n
+represents a variable or constant of integral or floating-point type.
-Values of time mode locations appear as
-@smallexample
-@code{TIME(<secs>:<nsecs>)}
-@end smallexample
+@item r
+represents a variable or constant of floating-point type.
+@item t
+represents a type.
-@ignore
-This is not implemented yet:
-@item Built-in Value
-@noindent
-The following built in functions are provided:
+@item v
+represents a variable.
-@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 x
+represents a variable or constant of one of many types. See the
+explanation of the function for details.
@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}:
+All Modula-2 built-in procedures also return a result, described below.
@table @code
-@item @code{OR, ORIF, XOR}
-@itemx @code{AND, ANDIF}
-@itemx @code{NOT}
-Logical operators defined over operands of boolean mode.
+@item ABS(@var{n})
+Returns the absolute value of @var{n}.
-@item @code{=, /=}
-Equality and inequality operators defined over all modes.
+@item CAP(@var{c})
+If @var{c} is a lower case letter, it returns its upper case
+equivalent, otherwise it returns its argument.
-@item @code{>, >=}
-@itemx @code{<, <=}
-Relational operators defined over predefined modes.
+@item CHR(@var{i})
+Returns the character whose ordinal value is @var{i}.
-@item @code{+, -}
-@itemx @code{*, /, MOD, REM}
-Arithmetic operators defined over predefined modes.
+@item DEC(@var{v})
+Decrements the value in the variable @var{v} by one. Returns the new value.
-@item @code{-}
-Change sign operator.
+@item DEC(@var{v},@var{i})
+Decrements the value in the variable @var{v} by @var{i}. Returns the
+new value.
-@item @code{//}
-String concatenation operator.
+@item EXCL(@var{m},@var{s})
+Removes the element @var{m} from the set @var{s}. Returns the new
+set.
-@item @code{()}
-String repetition operator.
+@item FLOAT(@var{i})
+Returns the floating point equivalent of the integer @var{i}.
-@item @code{->}
-Referenced location operator which can be used either to take the
-address of a location (@code{->loc}), or to dereference a reference
-location (@code{loc->}).
+@item HIGH(@var{a})
+Returns the index of the last member of @var{a}.
-@item @code{OR, XOR}
-@itemx @code{AND}
-@itemx @code{NOT}
-Powerset and bitstring operators.
+@item INC(@var{v})
+Increments the value in the variable @var{v} by one. Returns the new value.
-@item @code{>, >=}
-@itemx @code{<, <=}
-Powerset inclusion operators.
+@item INC(@var{v},@var{i})
+Increments the value in the variable @var{v} by @var{i}. Returns the
+new value.
-@item @code{IN}
-Membership operator.
-@end table
+@item INCL(@var{m},@var{s})
+Adds the element @var{m} to the set @var{s} if it is not already
+there. Returns the new set.
+
+@item MAX(@var{t})
+Returns the maximum value of the type @var{t}.
+
+@item MIN(@var{t})
+Returns the minimum value of the type @var{t}.
+
+@item ODD(@var{i})
+Returns boolean TRUE if @var{i} is an odd number.
+
+@item ORD(@var{x})
+Returns the ordinal value of its argument. For example, the ordinal
+value of a character is its @sc{ascii} value (on machines supporting the
+@sc{ascii} character set). @var{x} must be of an ordered type, which include
+integral, character and enumerated types.
+
+@item SIZE(@var{x})
+Returns the size of its argument. @var{x} can be a variable or a type.
+
+@item TRUNC(@var{r})
+Returns the integral part of @var{r}.
+
+@item VAL(@var{t},@var{i})
+Returns the member of the type @var{t} whose ordinal value is @var{i}.
@end table
-@node Chill type and range checks
-@subsubsection Chill type and range checks
+@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
-@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.
+@cindex Modula-2 constants
+@node M2 Constants
+@subsubsection Constants
-Range checking is done on all mathematical operations, assignment, array
-index bounds and all built in procedures.
+@value{GDBN} allows you to express the constants of Modula-2 in the following
+ways:
-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.
+@itemize @bullet
-All checks can be disabled by the @value{GDBN} command @code{set check
-off}.
+@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}.
-@ignore
-@c Deviations from the Chill Standard Z200/88
-see last paragraph ?
-@end ignore
+@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 defaults
-@subsubsection Chill defaults
+@item
+Character constants consist of a single character enclosed by a pair of
+like quotes, either single (@code{'}) or double (@code{"}). They may
+also be expressed by their ordinal value (their @sc{ascii} value, usually)
+followed by a @samp{C}.
+
+@item
+String constants consist of a sequence of characters enclosed by a
+pair of like quotes, either single (@code{'}) or double (@code{"}).
+Escape sequences in the style of C are also allowed. @xref{C
+Constants, ,C and C@t{++} constants}, for a brief explanation of escape
+sequences.
+
+@item
+Enumerated constants consist of an enumerated identifier.
+
+@item
+Boolean constants consist of the identifiers @code{TRUE} and
+@code{FALSE}.
+
+@item
+Pointer constants consist of integral values only.
+
+@item
+Set constants are not yet supported.
+@end itemize
+
+@node M2 Defaults
+@subsubsection Modula-2 defaults
+@cindex Modula-2 defaults
If type and range checking are set automatically by @value{GDBN}, they
both default to @code{on} whenever the working language changes to
-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 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}.
+@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 whatis
-Print the data type of @code{$}, the last value in the value history.
+@value{GDBN} considers two Modula-2 variables type equivalent if:
-@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}}.
+@itemize @bullet
+@item
+They are of types that have been declared equivalent via a @code{TYPE
+@var{t1} = @var{t2}} statement
-@item ptype @var{expr}
-@itemx ptype
-Print a description of the type of expression @var{expr}. @code{ptype}
-differs from @code{whatis} by printing a detailed description, instead
-of just the name of the type.
+@item
+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
-For example, for this variable declaration:
+As long as type checking is enabled, any attempt to combine variables
+whose types are not equivalent is an error.
-@example
-struct complex @{double real; double imag;@} v;
-@end example
+Range checking is done on all mathematical operations, assignment, array
+index bounds, and all built-in functions and procedures.
-@noindent
-the two commands give this output:
+@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
-@example
-@group
-(@value{GDBP}) whatis v
-type = struct complex
-(@value{GDBP}) ptype v
-type = struct complex @{
- double real;
- double imag;
-@}
-@end group
+There are a few subtle differences between the Modula-2 scope operator
+(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
+similar syntax:
+
+@example
+
+@var{module} . @var{id}
+@var{scope} :: @var{id}
@end example
@noindent
-As with @code{whatis}, using @code{ptype} without an argument refers to
-the type of @code{$}, the last value in the value history.
+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.
-@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}.
+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}.
-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.
+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 source
-@item info source
-Show the name of the current source file---that is, the source file for
-the function containing the current point of execution---and the language
-it was written in.
+@node GDB/M2
+@subsubsection @value{GDBN} and Modula-2
-@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.
+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 functions
-@item info functions
-Print the names and data types of all defined functions.
+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.
-@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}.
+@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 variables
-@item info variables
-Print the names and data types of all variables that are declared
-outside of functions (i.e., excluding local variables).
+@node Chill
+@subsection Chill
-@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}.
+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.
-@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
+@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.
-@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:
+@menu
+* How modes are displayed:: How modes are displayed
+* Locations:: Locations and their accesses
+* Values and their Operations:: Values and their Operations
+* Chill type and range checks::
+* Chill defaults::
+@end menu
+
+@node How modes are displayed
+@subsubsection How modes are displayed
+
+The Chill Datatype- (Mode) support of @value{GDBN} is directly related
+with the functionality of the @sc{gnu} Chill compiler, and therefore deviates
+slightly from the standard specification of the Chill language. The
+provided modes are:
+@c FIXME: this @table's contents effectively disable @code by using @r
+@c on every @item. So why does it need @code?
@table @code
-@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.
-
-@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{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
-@node Altering
-@chapter Altering Execution
+@item @r{@emph{Real Modes:}}
+Real Modes are predefined with @code{REAL} and @code{LONG_REAL}.
-Once you think you have found an error in your program, you might want to
-find out for certain whether correcting the apparent error would lead to
-correct results in the rest of the run. You can find the answer by
-experiment, using the @value{GDBN} features for altering execution of the
-program.
-
-For example, you can store new values into variables or memory
-locations, give your program a signal, restart it at a different
-address, or even return prematurely from a function.
-
-@menu
-* Assignment:: Assignment to variables
-* Jumping:: Continuing at a different address
-* Signaling:: Giving your program a signal
-* Returning:: Returning from a function
-* Calling:: Calling your program's functions
-* Patching:: Patching your program
-@end menu
+@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
-@node Assignment
-@section Assignment to variables
+@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
-@cindex assignment
-@cindex setting variables
-To alter the value of a variable, evaluate an assignment expression.
-@xref{Expressions, ,Expressions}. For example,
+@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
-@example
-print x=4
-@end example
+@node Locations
+@subsubsection Locations and their accesses
-@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.
+A location in Chill is an object which can contain values.
-@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.
+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}.
-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 pseudo-location @code{RESULT} (or @code{result}) can be used to
+display or change the result of a currently-active procedure:
-@example
-(@value{GDBP}) whatis width
-type = double
-(@value{GDBP}) p width
-$4 = 13
-(@value{GDBP}) set width=47
-Invalid syntax in expression.
-@end example
+@smallexample
+set result := EXPR
+@end smallexample
@noindent
-The invalid expression, of course, is @samp{=47}. In
-order to actually set the program's variable @code{width}, use
+This does the same as the Chill action @code{RESULT EXPR} (which
+is not available in @value{GDBN}).
-@example
-(@value{GDBP}) set var width=47
-@end example
+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{->}.
-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}:
+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
-@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
+@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 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
+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 g=4
-@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
-@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
-
-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{OR, ORIF, XOR}
+@itemx @code{AND, ANDIF}
+@itemx @code{NOT}
+Logical operators defined over operands of boolean mode.
-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{=, /=}
+Equality and inequality operators defined over all modes.
-@node Patching
-@section Patching programs
+@item @code{>, >=}
+@itemx @code{<, <=}
+Relational operators defined over predefined modes.
-@cindex patching binaries
-@cindex writing into executables
-@cindex writing into corefiles
+@item @code{+, -}
+@itemx @code{*, /, MOD, REM}
+Arithmetic operators defined over predefined modes.
-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{-}
+Change sign 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 concatenation 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{()}
+String repetition operator.
-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{->}
+Referenced location operator which can be used either to take the
+address of a location (@code{->loc}), or to dereference a reference
+location (@code{loc->}).
-@item show write
-@kindex show write
-Display whether executable files and core files are opened for writing
-as well as reading.
-@end table
+@item @code{OR, XOR}
+@itemx @code{AND}
+@itemx @code{NOT}
+Powerset and bitstring operators.
-@node GDB Files
-@chapter @value{GDBN} Files
+@item @code{>, >=}
+@itemx @code{<, <=}
+Powerset inclusion operators.
-@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.
+@item @code{IN}
+Membership operator.
+@end table
+@end table
-@menu
-* Files:: Commands to specify files
-* Symbol Errors:: Errors reading symbol files
-@end menu
+@node Chill type and range checks
+@subsubsection Chill type and range checks
-@node Files
-@section Commands to specify files
+@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.
-@cindex symbol table
-@cindex core dump file
+Range checking is done on all mathematical operations, assignment, array
+index bounds and all built in procedures.
-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}}).
+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.
-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.
+All checks can be disabled by the @value{GDBN} command @code{set check
+off}.
-@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.
+@ignore
+@c Deviations from the Chill Standard Z200/88
+see last paragraph ?
+@end ignore
-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.
+@node Chill defaults
+@subsubsection Chill defaults
-@item file
-@code{file} with no argument makes @value{GDBN} discard any information it
-has on both executable file and the symbol table.
+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.
-@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.
+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 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.
+@node Symbols
+@chapter Examining the Symbol Table
-@code{symbol-file} with no argument clears out @value{GDBN} information on your
-program's symbol table.
+The commands described in this chapter allow you to inquire about the
+symbols (names of variables, functions and types) defined in your
+program. This information is inherent in the text of your program and
+does not change as your program executes. @value{GDBN} finds it in your
+program's symbol table, in the file indicated when you started @value{GDBN}
+(@pxref{File Options, ,Choosing files}), or by one of the
+file-management commands (@pxref{Files, ,Commands to specify files}).
-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}.
+@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,
-@code{symbol-file} does not repeat if you press @key{RET} again after
-executing it once.
+@example
+p 'foo.c'::x
+@end example
-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.
+@noindent
+looks up the value of @code{x} in the scope of the file @file{foo.c}.
-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.
+@table @code
+@kindex info address
+@cindex address of a symbol
+@item info address @var{symbol}
+Describe where the data for @var{symbol} is stored. For a register
+variable, this says which register it is kept in. For a non-register
+local variable, this prints the stack-frame offset at which the variable
+is always stored.
-The 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}.)
+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.
-We have not implemented the two-stage strategy for COFF yet. When the
-symbol table is stored in COFF format, @code{symbol-file} reads the
-symbol table data in full right away. Note that ``stabs-in-COFF''
-still does the two-stage strategy, since the debug info is actually
-in stabs format.
+@kindex 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:
-@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.
+@example
+(@value{GDBP}) info symbol 0x54320
+_initialize_vx + 396 in section .text
+@end example
-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.
+@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.
-You can use both options together, to make sure the auxiliary symbol
-file has all the symbol information for your program.
+@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}.
-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.
+@item whatis
+Print the data type of @code{$}, the last value in the value history.
-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.
+@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}}.
-@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 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.
-@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.
+For example, for this variable declaration:
-@code{core-file} with no argument specifies that no core file is
-to be used.
+@example
+struct complex @{double real; double imag;@} v;
+@end example
-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}).
+@noindent
+the two commands give this output:
-@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.
+@example
+@group
+(@value{GDBP}) whatis v
+type = struct complex
+(@value{GDBP}) ptype v
+type = struct complex @{
+ double real;
+ double imag;
+@}
+@end group
+@end example
-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.
+@noindent
+As with @code{whatis}, using @code{ptype} without an argument refers to
+the type of @code{$}, the last value in the value history.
-@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+@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}.
-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}.
+This command differs from @code{ptype} in two ways: first, like
+@code{whatis}, it does not print a detailed description; second, it
+lists all source files where a type is defined.
-@kindex add-shared-symbol-file
-@item add-shared-symbol-file
-The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
-operating system for the Motorola 88k. @value{GDBN} automatically looks for
-shared libraries, however if @value{GDBN} does not find yours, you can run
-@code{add-shared-symbol-file}. It takes no arguments.
+@kindex info 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 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.
+@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 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.
+@noindent
+This command is especially useful for determining what data to collect
+during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
+collect}.
-@end table
+@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.
-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 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 shared libraries
-@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
-libraries.
+@kindex info functions
+@item info functions
+Print the names and data types of all defined functions.
-@value{GDBN} automatically loads symbol definitions from shared libraries
-when you use the @code{run} command, or when you examine a core file.
-(Before you issue the @code{run} command, @value{GDBN} does not understand
-references to a function in a shared library, however---unless you are
-debugging a core file).
+@item info 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.
-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.
+@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 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 info variables @var{regexp}
+Print the names and data types of all variables (except for local
+variables) whose names contain a match for regular expression
+@var{regexp}.
+
+@ignore
+This was never implemented.
+@kindex info methods
+@item info methods
+@itemx info methods @var{regexp}
+The @code{info methods} command permits the user to examine all defined
+methods within C@t{++} program, or (with the @var{regexp} argument) a
+specific set of methods found in the various C@t{++} classes. Many
+C@t{++} classes provide a large number of methods. Thus, the output
+from the @code{ptype} command can be overwhelming and hard to use. The
+@code{info-methods} command filters the methods, printing only those
+which match the regular-expression @var{regexp}.
+@end ignore
+
+@cindex reloading symbols
+Some systems allow individual object files that make up your program to
+be replaced without stopping and restarting your program. For example,
+in VxWorks you can simply recompile a defective object file and keep on
+running. If you are running on one of these systems, you can allow
+@value{GDBN} to reload the symbols for automatically relinked modules:
@table @code
-@kindex 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.
+@item set symbol-reloading off
+Do not replace symbol definitions when encountering object files of the
+same name more than once. This is the default state; if you are not
+running on a system that permits automatic relinking of modules, you
+should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
+may discard symbols when linking large programs, that may contain
+several modules (from different directories or libraries) with the same
+name.
+
+@kindex show symbol-reloading
+@item show symbol-reloading
+Show the current @code{on} or @code{off} setting.
@end table
-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 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.
-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.
+A change in the setting of this subcommand will not take effect until
+the next time symbols for a file are loaded.
-To display or set the threshold, use the commands:
+@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
-@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.
+@kindex show opaque-type-resolution
+@item show opaque-type-resolution
+Show whether opaque types are resolved or not.
-@kindex show auto-solib-add
-@item show auto-solib-add
-Display the current autoloading size threshold, in megabytes.
+@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
-
-While reading a symbol file, @value{GDBN} occasionally encounters problems,
-such as symbol types it does not recognize, or known bugs in compiler
-output. By default, @value{GDBN} does not notify you of such problems, since
-they are relatively common and primarily of interest to people
-debugging compilers. If you are interested in seeing information
-about ill-constructed symbol tables, you can either ask @value{GDBN} to print
-only one message about each such type of problem, no matter how many
-times the problem occurs; or you can ask @value{GDBN} to print more messages,
-to see how many times the problems occur, with the @code{set
-complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
-messages}).
-
-The messages currently printed, and their meanings, include:
+@node Altering
+@chapter Altering Execution
-@table @code
-@item inner block not inside outer block in @var{symbol}
+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 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.
+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.
-@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.
+@menu
+* Assignment:: Assignment to variables
+* Jumping:: Continuing at a different address
+* Signaling:: Giving your program a signal
+* Returning:: Returning from a function
+* Calling:: Calling your program's functions
+* Patching:: Patching your program
+@end menu
-@item block at @var{address} out of order
+@node Assignment
+@section Assignment to variables
-The symbol information for symbol scope blocks should occur in
-order of increasing addresses. This error indicates that it does not
-do so.
+@cindex assignment
+@cindex setting variables
+To alter the value of a variable, evaluate an assignment expression.
+@xref{Expressions, ,Expressions}. For example,
-@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}.)
+@example
+print x=4
+@end example
-@item bad block start address patched
+@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.
-The symbol information for a symbol scope block has a start address
-smaller than the address of the preceding source line. This is known
-to occur in the SunOS 4.1.1 (and earlier) C compiler.
+@kindex 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.
-@value{GDBN} circumvents the problem by treating the symbol scope block as
-starting on the previous source line.
+If the beginning of the argument string of the @code{set} command
+appears identical to a @code{set} subcommand, use the @code{set
+variable} command instead of just @code{set}. This command is identical
+to @code{set} except for its lack of subcommands. For example, if your
+program has a variable @code{width}, you get an error if you try to set
+a new value with just @samp{set width=13}, because @value{GDBN} has the
+command @code{set width}:
-@item bad string table offset in symbol @var{n}
+@example
+(@value{GDBP}) whatis width
+type = double
+(@value{GDBP}) p width
+$4 = 13
+(@value{GDBP}) set width=47
+Invalid syntax in expression.
+@end example
-@cindex foo
-Symbol number @var{n} contains a pointer into the string table which is
-larger than the size of the string table.
+@noindent
+The invalid expression, of course, is @samp{=47}. In
+order to actually set the program's variable @code{width}, use
-@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.
+@example
+(@value{GDBP}) set var width=47
+@end example
-@item unknown symbol type @code{0x@var{nn}}
+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}:
-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.
+@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
-@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.
+@noindent
+The program variable @code{g} did not change, and you silently set the
+@code{gnutarget} to an invalid value. In order to set the variable
+@code{g}, use
-@item stub type has NULL name
+@example
+(@value{GDBP}) set var g=4
+@end example
-@value{GDBN} could not find the full definition for a struct or class.
+@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 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.
+To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
+construct to generate a value of specified type at a specified address
+(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
+to memory location @code{0x83040} as an integer (which implies a certain size
+and representation in memory), and
-@item info mismatch between compiler and debugger
+@example
+set @{int@}0x83040 = 4
+@end example
-@value{GDBN} could not parse a type specification output by the compiler.
+@noindent
+stores the value 4 into that memory location.
-@end table
+@node Jumping
+@section Continuing at a different address
-@node Targets
-@chapter Specifying a Debugging Target
+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:
-@cindex debugging target
-@kindex target
+@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}.
-A @dfn{target} is the execution environment occupied by your program.
+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.
-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}).
+@item jump *@var{address}
+Resume execution at the instruction at address @var{address}.
+@end table
-@menu
-* Active Targets:: Active targets
-* Target Commands:: Commands for managing targets
-* Byte Order:: Choosing target byte order
-* Remote:: Remote debugging
-* KOD:: Kernel Object Display
+@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,
-@end menu
+@example
+set $pc = 0x485
+@end example
-@node Active Targets
-@section Active targets
+@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}.
-@cindex stacking targets
-@cindex active targets
-@cindex multiple targets
+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.
-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.
+@c @group
+@node Signaling
+@section Giving your program 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.)
+@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.
-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.
+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.
-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}).
+@code{signal} does not repeat when you press @key{RET} a second time
+after executing the command.
+@end table
+@c @end group
-@node Target Commands
-@section Commands for managing targets
+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.
-@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.
+@node Returning
+@section Returning from a function
-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}).
+@table @code
+@cindex returning from a function
+@kindex return
+@item return
+@itemx return @var{expression}
+You can cancel execution of a function call with the @code{return}
+command. If you give an
+@var{expression} argument, its value is used as the function's return
+value.
+@end table
-@item 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.
-
-Many remote targets require you to download the executable's code
-once you've successfully established a connection.
-
-@table @code
-
-@kindex load @var{filename}
-@item load @var{filename}
-Depending on what remote debugging facilities are configured into
-@value{GDBN}, the @code{load} command may be available. Where it exists, it
-is meant to make @var{filename} (an executable) available for debugging
-on the remote system---by downloading, or dynamic linking, for example.
-@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
-the @code{add-symbol-file} command.
+@node GDB Files
+@chapter @value{GDBN} 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{}}''
+@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.
-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.
+@menu
+* Files:: Commands to specify files
+* Symbol Errors:: Errors reading symbol files
+@end menu
-@code{load} does not repeat if you press @key{RET} again after using it.
-@end table
+@node Files
+@section Commands to specify files
-@node Byte Order
-@section Choosing target byte order
+@cindex symbol table
+@cindex core dump file
-@cindex choosing target byte order
-@cindex target byte order
+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}}).
-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.
+Occasionally it is necessary to change to a different file during a
+@value{GDBN} session. Or you may run @value{GDBN} and forget to specify
+a file you want to use. In these situations the @value{GDBN} commands
+to specify new files are useful.
@table @code
-@kindex set endian big
-@item set endian big
-Instruct @value{GDBN} to assume the target is big-endian.
+@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.
-@kindex set endian little
-@item set endian little
-Instruct @value{GDBN} to assume the target is little-endian.
+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.
-@kindex set endian auto
-@item set endian auto
-Instruct @value{GDBN} to use the byte order associated with the
-executable.
+@item file
+@code{file} with no argument makes @value{GDBN} discard any information it
+has on both executable file and the symbol table.
-@item show endian
-Display @value{GDBN}'s current idea of the target byte order.
+@kindex exec-file
+@item exec-file @r{[} @var{filename} @r{]}
+Specify that the program to be run (but not the symbol table) is found
+in @var{filename}. @value{GDBN} searches the environment variable @code{PATH}
+if necessary to locate your program. Omitting @var{filename} means to
+discard information on the executable file.
-@end 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.
-Note that these commands merely adjust interpretation of symbolic
-data on the host, and that they have absolutely no effect on the
-target system.
+@code{symbol-file} with no argument clears out @value{GDBN} information on your
+program's symbol table.
-@node Remote
-@section Remote debugging
-@cindex remote debugging
+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}.
-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.
+@code{symbol-file} does not repeat if you press @key{RET} again after
+executing it once.
-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}.
+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.
-Other remote targets may be available in your
-configuration of @value{GDBN}; use @code{help target} to list them.
+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.
-@menu
-* Remote Serial:: @value{GDBN} remote serial protocol
-@end menu
+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}.)
-@node Remote Serial
-@subsection The @value{GDBN} remote serial protocol
+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.
-@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:
+@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.
-@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.
+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.
-@item
-A C subroutine library to support your program's
-subroutine calls, notably managing input and output.
+You can use both options together, to make sure the auxiliary symbol
+file has all the symbol information for your program.
-@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 auxiliary symbol file for a program called @var{myprog} is called
+@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
+than the corresponding executable), @value{GDBN} always attempts to use
+it when you debug @var{myprog}; no special options or commands are
+needed.
-The 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:
+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.
-@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}).
+@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 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 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.
-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
+@code{core-file} with no argument specifies that no core file is
+to be used.
-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.
+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}).
-@cindex remote serial stub list
-These working remote stubs are distributed with @value{GDBN}:
+@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.
-@table @code
+The symbol table of the file @var{filename} is added to the symbol table
+originally read with the @code{symbol-file} command. You can use the
+@code{add-symbol-file} command any number of times; the new symbol data
+thus read keeps adding to the old. To discard all old symbol data
+instead, use the @code{symbol-file} command without any arguments.
-@item i386-stub.c
-@cindex @file{i386-stub.c}
-@cindex Intel
-@cindex i386
-For Intel 386 and compatible architectures.
+@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:
-@item m68k-stub.c
-@cindex @file{m68k-stub.c}
-@cindex Motorola 680x0
-@cindex m680x0
-For Motorola 680x0 architectures.
+@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
-@item sh-stub.c
-@cindex @file{sh-stub.c}
-@cindex Hitachi
-@cindex SH
-For Hitachi SH architectures.
+@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 sparc-stub.c
-@cindex @file{sparc-stub.c}
-@cindex Sparc
-For @sc{sparc} architectures.
+@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
-@item sparcl-stub.c
-@cindex @file{sparcl-stub.c}
-@cindex Fujitsu
-@cindex SparcLite
-For Fujitsu @sc{sparclite} 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}.
+
+@kindex add-shared-symbol-file
+@item add-shared-symbol-file
+The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
+operating system for the Motorola 88k. @value{GDBN} automatically looks for
+shared libraries, however if @value{GDBN} does not find yours, you can run
+@code{add-shared-symbol-file}. It takes no arguments.
+
+@kindex section
+@item section
+The @code{section} command changes the base address of section SECTION of
+the exec file to ADDR. This can be used if the exec file does not contain
+section addresses, (such as in the a.out format), or when the addresses
+specified in the file itself are wrong. Each section must be changed
+separately. The @code{info files} command, described below, lists all
+the sections and their addresses.
+
+@kindex info files
+@kindex info target
+@item info files
+@itemx info target
+@code{info files} and @code{info target} are synonymous; both print the
+current target (@pxref{Targets, ,Specifying a Debugging Target}),
+including the names of the executable and core dump files currently in
+use by @value{GDBN}, and the files from which symbols were loaded. The
+command @code{help target} lists all possible targets rather than
+current ones.
+@kindex maint info sections
+@item maint info sections
+Another command that can give you extra information about program sections
+is @code{maint info sections}. In addition to the section information
+displayed by @code{info files}, this command displays the flags and file
+offset of each section in the executable and core dump files. In addition,
+@code{maint info sections} provides the following command options (which
+may be arbitrarily combined):
+
+@table @code
+@item ALLOBJ
+Display sections for all loaded object files, including shared libraries.
+@item @var{sections}
+Display info only for named @var{sections}.
+@item @var{section-flags}
+Display info only for sections for which @var{section-flags} are true.
+The section flags that @value{GDBN} currently knows about are:
+@table @code
+@item ALLOC
+Section will have space allocated in the process when loaded.
+Set for all sections except those containing debug information.
+@item LOAD
+Section will be loaded from the file into the child process memory.
+Set for pre-initialized code and data, clear for @code{.bss} sections.
+@item RELOC
+Section needs to be relocated before loading.
+@item READONLY
+Section cannot be modified by the child process.
+@item CODE
+Section contains executable code only.
+@item DATA
+Section contains data only (no executable code).
+@item ROM
+Section will reside in ROM.
+@item CONSTRUCTOR
+Section contains data for constructor/destructor lists.
+@item HAS_CONTENTS
+Section is not empty.
+@item NEVER_LOAD
+An instruction to the linker to not output the section.
+@item COFF_SHARED_LIBRARY
+A notification to the linker that the section contains
+COFF shared library information.
+@item IS_COMMON
+Section contains common symbols.
+@end table
+@end table
@end table
-The @file{README} file in the @value{GDBN} distribution may list other
-recently added stubs.
+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.
-@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
+@cindex shared libraries
+@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
+libraries.
-@node Stub Contents
-@subsubsection What the stub can do for you
+@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).
-@cindex remote serial stub
-The debugging stub for your architecture supplies these three
-subroutines:
+On HP-UX, if the program loads a library explicitly, @value{GDBN}
+automatically loads the symbols at the time of the @code{shl_load} call.
+
+@c FIXME: some @value{GDBN} release may permit some refs to undef
+@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
+@c FIXME...lib; check this from time to time when updating manual
+
+There are times, however, when you may wish to not automatically load
+symbol definitions from shared libraries, such as when they are
+particularly large or there are many of them.
+
+To control the automatic loading of shared library symbols, use the
+commands:
@table @code
-@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.
+@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}.
-@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.
+@kindex show auto-solib-add
+@item show auto-solib-add
+Display the current autoloading mode.
+@end table
-@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.
+To explicitly load shared library symbols, use the @code{sharedlibrary}
+command:
-@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.
+@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.
-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.
+@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
-@node Bootstrapping
-@subsubsection What you must do for the stub
+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.
-@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.
+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.
-First of all you need to tell the stub how to communicate with the
-serial port.
+To display or set the threshold, use the commands:
@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 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).
-@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 show auto-solib-limit
+@item show auto-solib-limit
+Display the current autoloading size threshold, in megabytes.
@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.
+@node Symbol Errors
+@section Errors reading symbol files
-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}).
+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}).
-Other routines you need to supply are:
+The messages currently printed, and their meanings, include:
@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.
+@item inner block not inside outer block in @var{symbol}
-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
+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.
-@noindent
-You must also make sure this library routine is available:
+@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.
-@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 block at @var{address} out of order
-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 for symbol scope blocks should occur in
+order of increasing addresses. This error indicates that it does not
+do so.
+@value{GDBN} does not circumvent this problem, and has trouble
+locating symbols in the source file whose symbols it is reading. (You
+can often determine what source file is affected by specifying
+@code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and
+messages}.)
-@node Debug Session
-@subsubsection Putting it all together
+@item bad block start address patched
-@cindex remote serial debugging summary
-In summary, when your program is ready to debug, you must follow these
-steps.
+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.
-@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} circumvents the problem by treating the symbol scope block as
+starting on the previous source line.
-@item
-Insert these lines near the top of your program:
+@item bad string table offset in symbol @var{n}
-@example
-set_debug_traps();
-breakpoint();
-@end example
+@cindex foo
+Symbol number @var{n} contains a pointer into the string table which is
+larger than the size of the string table.
-@item
-For the 680x0 stub only, you need to provide a variable called
-@code{exceptionHook}. Normally you just use:
+@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.
-@example
-void (*exceptionHook)() = 0;
-@end example
+@item unknown symbol type @code{0x@var{nn}}
-@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.
+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
-Compile and link together: your program, the @value{GDBN} debugging stub for
-your target architecture, and the supporting subroutines.
+@value{GDBN} circumvents the error by ignoring this symbol information.
+This usually allows you to debug your program, though certain symbols
+are not accessible. If you encounter such a problem and feel like
+debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
+on @code{complain}, then go up to the function @code{read_dbx_symtab}
+and examine @code{*bufp} to see the symbol.
-@item
-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 stub type has NULL 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.
+@value{GDBN} could not find the full definition for a struct or class.
-@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 const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
+The symbol information for a C@t{++} member function is missing some
+information that recent versions of the compiler should have output for
+it.
-@item
-@cindex serial line, @code{target remote}
-Establish communication using the @code{target remote} command.
-Its argument specifies how to communicate with the target
-machine---either via a devicename attached to a direct serial line, or a
-TCP port (usually to a terminal server which in turn has a serial line
-to the target). For example, to use a serial line connected to the
-device named @file{/dev/ttyb}:
+@item info mismatch between compiler and debugger
-@example
-target remote /dev/ttyb
-@end example
+@value{GDBN} could not parse a type specification output by the compiler.
-@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}:
+@end table
-@example
-target remote manyfarms:2828
-@end example
-@end enumerate
+@node Targets
+@chapter Specifying a Debugging Target
-Now you can use all the usual commands to examine and change data and to
-step and continue the remote program.
+@cindex debugging target
+@kindex target
-To resume the remote program and stop debugging it, use the @code{detach}
-command.
+A @dfn{target} is the execution environment occupied by your program.
-@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:
+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}).
-@example
-Interrupted while waiting for the program.
-Give up (and stop debugging it)? (y or n)
-@end example
+@menu
+* Active Targets:: Active targets
+* Target Commands:: Commands for managing targets
+* Byte Order:: Choosing target byte order
+* Remote:: Remote debugging
+* KOD:: Kernel Object Display
-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.
+@end menu
-@node Protocol
-@subsubsection Communication protocol
+@node Active Targets
+@section Active targets
-@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 stacking targets
+@cindex active targets
+@cindex multiple 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}.
+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.
-In the examples below, @samp{<-} and @samp{->} are used to indicate
-transmitted and received data respectfully.
+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.)
-@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}:
+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.
-@example
-@code{$}@var{packet-data}@code{#}@var{checksum}
-@end example
-@noindent
+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 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).
+@node Target Commands
+@section Commands for managing targets
-Implementors should note that prior to @value{GDBN} 5.0 the protocol
-specification also included an optional two-digit @var{sequence-id}:
+@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.
-@example
-@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
-@end example
+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.
-@cindex sequence-id, for @value{GDBN} remote
-@noindent
-That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
-has never output @var{sequence-id}s. Stubs that handle packets added
-since @value{GDBN} 5.0 must not accept @var{sequence-id}.
+The @code{target} command does not repeat if you press @key{RET} again
+after executing the command.
-@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):
+@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}).
-@example
-<- @code{$}@var{packet-data}@code{#}@var{checksum}
--> @code{+}
-@end example
-@noindent
+@item help target @var{name}
+Describe a particular target, including any parameters necessary to
+select it.
-The host (@value{GDBN}) sends @var{command}s, and the target (the
-debugging stub incorporated in your program) sends a @var{response}. In
-the case of step and continue @var{command}s, the response is only sent
-when the operation has completed (the target has again stopped).
+@kindex 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.
-@var{packet-data} consists of a sequence of characters with the
-exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
-exceptions).
+@quotation
+@emph{Warning:} To specify a file format with @code{set gnutarget},
+you must know the actual BFD name.
+@end quotation
-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.
+@noindent
+@xref{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}).
+@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
-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.
+Here are some common targets (available, or not, depending on the GDB
+configuration):
-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.
+@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}}.
-So:
+@kindex target core
+@item target core @var{filename}
+A core dump file. @samp{target core @var{filename}} is the same as
+@samp{core-file @var{filename}}.
+
+@kindex target remote
+@item target remote @var{dev}
+Remote serial target in GDB-specific protocol. The argument @var{dev}
+specifies what serial device to use for the connection (e.g.
+@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote}
+supports the @code{load} command. This is only useful if you have
+some other way of getting the stub to the target system, and you can put
+it somewhere in memory where it won't get clobbered by the download.
+
+@kindex target sim
+@item target sim
+Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
+In general,
@example
-"@code{0* }"
+ target sim
+ load
+ run
@end example
@noindent
-means the same as "0000".
+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}.
-The error response returned for some packets includes a two character
-error number. That number is not well defined.
+@end table
-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.
+Some configurations may include these targets as well:
-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.
+@table @code
-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
+@kindex target nrom
+@item target nrom @var{dev}
+NetROM ROM emulator. This target only supports downloading.
-@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.
+@end table
-@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
+Different targets are available on different configurations of @value{GDBN};
+your configuration may have more or fewer targets.
+Many remote targets require you to download the executable's code
+once you've successfully established a connection.
-@item reserved
-@tab @code{a}
-@tab Reserved for future use
+@table @code
-@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}
+@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 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.}
+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 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.}
+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 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
+@code{load} does not repeat if you press @key{RET} again after using it.
+@end table
-@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
+@node Byte Order
+@section Choosing target byte order
-@item toggle debug @strong{(deprecated)}
-@tab @code{d}
-@tab
-toggle debug flag.
+@cindex choosing target byte order
+@cindex target byte order
-@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.
+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 reserved
-@tab @code{e}
-@tab Reserved for future use
+@table @code
+@kindex set endian big
+@item set endian big
+Instruct @value{GDBN} to assume the target is big-endian.
-@item reserved
-@tab @code{E}
-@tab Reserved for future use
+@kindex set endian little
+@item set endian little
+Instruct @value{GDBN} to assume the target is little-endian.
-@item reserved
-@tab @code{f}
-@tab Reserved for future use
+@kindex set endian auto
+@item set endian auto
+Instruct @value{GDBN} to use the byte order associated with the
+executable.
-@item reserved
-@tab @code{F}
-@tab Reserved for future use
+@item show endian
+Display @value{GDBN}'s current idea of the target byte order.
-@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.
+@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
+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{h}
-@tab Reserved for future use
+@node Remote
+@section Remote debugging
+@cindex remote debugging
-@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
+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.
-@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.
+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 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.
+Other remote targets may be available in your
+configuration of @value{GDBN}; use @code{help target} to list them.
-@item signal then cycle step @strong{(reserved)}
-@tab @code{I}
-@tab
-See @samp{i} and @samp{S} for likely syntax and semantics.
+@node KOD
+@section Kernel Object Display
-@item reserved
-@tab @code{j}
-@tab Reserved for future use
+@cindex kernel object display
+@cindex kernel object
+@cindex KOD
-@item reserved
-@tab @code{J}
-@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 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?)}.
+Use the @code{set os} command to set the operating system. This tells
+@value{GDBN} which kernel object display module to initialize:
-@item reserved
-@tab @code{l}
-@tab Reserved for future use
+@example
+(@value{GDBP}) set os cisco
+@end example
-@item reserved
-@tab @code{L}
-@tab Reserved for future use
+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 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
+@example
+(@value{GDBP}) info cisco
+List of Cisco Kernel Objects
+Object Description
+any Any and all objects
+@end example
-@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).
+Further subcommands can be used to query about particular objects known
+by the kernel.
-@item reserved
-@tab @code{n}
-@tab Reserved for future use
+There is currently no way to determine whether a given operating system
+is supported other than to try it.
-@item reserved
-@tab @code{N}
-@tab Reserved for future use
-@item reserved
-@tab @code{o}
-@tab Reserved for future use
+@node Remote Debugging
+@chapter Debugging remote programs
-@item reserved
-@tab @code{O}
-@tab Reserved for future use
+@menu
+* Server:: Using the gdbserver program
+* NetWare:: Using the gdbserve.nlm program
+* remote stub:: Implementing a remote stub
+@end menu
-@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 Server
+@section Using the @code{gdbserver} program
-@item write reg
-@tab @code{P}@var{n...}@code{=}@var{r...}
-@tab
-Write register @var{n...} with value @var{r...}, which contains two hex
-digits for each byte in the register (target byte order).
-@item
-@tab reply @code{OK}
-@tab for success
-@item
-@tab reply @code{E}@var{NN}
-@tab for an error
+@kindex 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 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}.
+@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 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.
+@value{GDBN} and @code{gdbserver} communicate via either a serial line
+or a TCP connection, using the standard @value{GDBN} remote serial
+protocol.
-@item reset @strong{(deprecated)}
-@tab @code{r}
-@tab
-Reset the entire system.
+@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 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}.
+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 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
+@smallexample
+target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
+@end smallexample
-@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
+@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 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.
+@smallexample
+target> gdbserver /dev/com1 emacs foo.txt
+@end smallexample
-@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
+@code{gdbserver} waits passively for the host @value{GDBN} to communicate
+with it.
-@item reserved
-@tab @code{u}
-@tab Reserved for future use
+To use a TCP connection instead of a serial line:
-@item reserved
-@tab @code{U}
-@tab Reserved for future use
+@smallexample
+target> gdbserver host:2345 emacs foo.txt
+@end smallexample
-@item reserved
-@tab @code{v}
-@tab Reserved for future use
+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 @code{V}
-@tab Reserved for future use
+@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 reserved
-@tab @code{w}
-@tab Reserved for future use
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
-@item reserved
-@tab @code{W}
-@tab Reserved for future use
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and
-@item reserved
-@tab @code{x}
-@tab Reserved for future use
+@smallexample
+(@value{GDBP}) target remote the-target:2345
+@end smallexample
-@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
+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 reserved
-@tab @code{y}
-@tab Reserved for future use
+@node NetWare
+@section Using the @code{gdbserve.nlm} program
-@item reserved
-@tab @code{Y}
-@tab Reserved for future use
+@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 remove break or watchpoint @strong{(draft)}
-@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
-@tab
-See @samp{Z}.
+@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
+using the standard @value{GDBN} remote serial protocol.
-@item insert break or watchpoint @strong{(draft)}
-@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
-@tab
-@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
-breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
-@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
-bytes. For a software breakpoint, @var{length} specifies the size of
-the instruction to be patched. For hardware breakpoints and watchpoints
-@var{length} specifies the memory region to be monitored. To avoid
-potential problems with duplicate packets, the operations should be
-implemented in an idempotent way.
-@item
-@tab reply @code{E}@var{NN}
-@tab for an error
-@item
-@tab reply @code{OK}
-@tab for success
-@item
-@tab @samp{}
-@tab If not supported.
-
-@item reserved
-@tab <other>
-@tab Reserved for future use
-
-@end multitable
+@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.
-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.
+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:
-@multitable @columnfractions .4 .6
+@smallexample
+load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
+ [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
+@end smallexample
-@item @code{S}@var{AA}
-@tab @var{AA} is the signal number
+@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 @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.
+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 @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
+load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
+@end smallexample
-@item @code{X}@var{AA}
-@tab
-The process terminated with signal @var{AA}.
+@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 @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)}
-@tab
-@var{AA} = signal number; @var{t...} = address of symbol "_start";
-@var{d...} = base of data section; @var{b...} = base of bss section.
-@emph{Note: only used by Cisco Systems targets. The difference between
-this reply and the "qOffsets" query is that the 'N' packet may arrive
-spontaneously whereas the 'qOffsets' is a query initiated by the host
-debugger.}
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
-@item @code{O}@var{XX...}
-@tab
-@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time
-while the program is running and the debugger should continue to wait
-for 'W', 'T', etc.
+@noindent
+communications with the server via serial line @file{/dev/ttyb}.
+@end table
-@end multitable
+@node remote stub
+@section Implementing a remote stub
-The following set and query packets have already been defined.
+@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.)
-@multitable @columnfractions .2 .2 .6
+@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:
-@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.
+@enumerate
@item
-@tab reply *
-@tab Any other reply implies the old pid.
+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 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'}).
+A C subroutine library to support your program's
+subroutine calls, notably managing input and output.
-@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.
+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
-@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 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:
-@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.
+@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 query sect offs
-@tab @code{q}@code{Offsets}
-@tab
-Get section offsets that the target used when re-locating the downloaded
-image. @emph{Note: while a @code{Bss} offset is included in the
-response, @value{GDBN} ignores this and instead applies the @code{Data}
-offset to the @code{Bss} section.}
-@item
-@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
+@item 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}.
-@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()}.
+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
-@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.
+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.
-@item
-@tab reply @samp{}
-@tab
-When @samp{q}@samp{Rcmd} is not recognized.
+@cindex remote serial stub list
+These working remote stubs are distributed with @value{GDBN}:
-@end multitable
+@table @code
-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.
+@item i386-stub.c
+@cindex @file{i386-stub.c}
+@cindex Intel
+@cindex i386
+For Intel 386 and compatible architectures.
-@multitable @columnfractions .5 .5
+@item m68k-stub.c
+@cindex @file{m68k-stub.c}
+@cindex Motorola 680x0
+@cindex m680x0
+For Motorola 680x0 architectures.
-@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 sh-stub.c
+@cindex @file{sh-stub.c}
+@cindex Hitachi
+@cindex SH
+For Hitachi SH architectures.
-@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 sparc-stub.c
+@cindex @file{sparc-stub.c}
+@cindex Sparc
+For @sc{sparc} architectures.
-@end multitable
+@item sparcl-stub.c
+@cindex @file{sparcl-stub.c}
+@cindex Fujitsu
+@cindex SparcLite
+For Fujitsu @sc{sparclite} architectures.
-Example sequence of a target being re-started. Notice how the restart
-does not get any direct output:
+@end table
-@example
-<- @code{R00}
--> @code{+}
-@emph{target restarts}
-<- @code{?}
--> @code{+}
--> @code{T001:1234123412341234}
-<- @code{+}
-@end example
+The @file{README} file in the @value{GDBN} distribution may list other
+recently added stubs.
-Example sequence of a target being stepped by a single instruction:
+@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
-@example
-<- @code{G1445...}
--> @code{+}
-<- @code{s}
--> @code{+}
-@emph{time passes}
--> @code{T001:1234123412341234}
-<- @code{+}
-<- @code{g}
--> @code{+}
--> @code{1455...}
-<- @code{+}
-@end example
+@node Stub Contents
+@subsection What the stub can do for you
-@node Server
-@subsubsection Using the @code{gdbserver} program
+@cindex remote serial stub
+The debugging stub for your architecture supplies these three
+subroutines:
-@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.
+@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.
-@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 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.
-@value{GDBN} and @code{gdbserver} communicate via either a serial line
-or a TCP connection, using the standard @value{GDBN} remote serial
-protocol.
+@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.
-@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 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.
-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:
+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
-@smallexample
-target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
-@end smallexample
+@node Bootstrapping
+@subsection What you must do for the stub
-@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}:
+@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.
-@smallexample
-target> gdbserver /dev/com1 emacs foo.txt
-@end smallexample
+First of all you need to tell the stub how to communicate with the
+serial port.
-@code{gdbserver} waits passively for the host @value{GDBN} to communicate
-with it.
+@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.
-To use a TCP connection instead of a serial line:
+@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
-@smallexample
-target> gdbserver host:2345 emacs foo.txt
-@end smallexample
+@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.
-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.
+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}).
-@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:
+Other routines you need to supply are:
-@smallexample
-(@value{GDBP}) target remote /dev/ttyb
-@end smallexample
+@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.
-@noindent
-communicates with the server via serial line @file{/dev/ttyb}, and
+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}.
-@smallexample
-(@value{GDBP}) target remote the-target:2345
-@end smallexample
+@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.
-@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}.
+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
-@node NetWare
-@subsubsection Using the @code{gdbserve.nlm} program
+@noindent
+You must also make sure this library routine is available:
-@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}.
+@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
-@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
-using the standard @value{GDBN} remote serial protocol.
+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.
-@table @emph
-@item On the target machine,
-you need to have a copy of the program you want to debug.
-@code{gdbserve.nlm} does not need your program's symbol table, so you
-can strip the program if necessary to save space. @value{GDBN} on the
-host system does all the symbol handling.
-To use the server, you must tell it how to communicate with
-@value{GDBN}; the name of your program; and the arguments for your
-program. The syntax is:
+@node Debug Session
+@subsection Putting it all together
-@smallexample
-load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
- [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
-@end smallexample
+@cindex remote serial debugging summary
+In summary, when your program is ready to debug, you must follow these
+steps.
-@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}.
+@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
-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
+Insert these lines near the top of your program:
-@smallexample
-load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
-@end smallexample
+@example
+set_debug_traps();
+breakpoint();
+@end example
-@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
+For the 680x0 stub only, you need to provide a variable called
+@code{exceptionHook}. Normally you just use:
-@smallexample
-(@value{GDBP}) target remote /dev/ttyb
-@end smallexample
+@example
+void (*exceptionHook)() = 0;
+@end example
@noindent
-communications with the server via serial line @file{/dev/ttyb}.
-@end table
+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.
-@node KOD
-@section Kernel Object Display
+@item
+Compile and link together: your program, the @value{GDBN} debugging stub for
+your target architecture, and the supporting subroutines.
-@cindex kernel object display
-@cindex kernel object
-@cindex KOD
+@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.
-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
+@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.
-Use the @code{set os} command to set the operating system. This tells
-@value{GDBN} which kernel object display module to initialize:
+@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}:
@example
-(@value{GDBP}) set os cisco
+target remote /dev/ttyb
@end example
-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:
+@cindex TCP port, @code{target remote}
+To use a TCP connection, use an argument of the form
+@code{@var{host}:port}. For example, to connect to port 2828 on a
+terminal server named @code{manyfarms}:
@example
-(@value{GDBP}) info cisco
-List of Cisco Kernel Objects
-Object Description
-any Any and all objects
+target remote manyfarms:2828
@end example
-Further subcommands can be used to query about particular objects known
-by the kernel.
+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:
-There is currently no way to determine whether a given operating system
-is supported other than to try it.
+@example
+target remote :1234
+@end example
+@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:
+
+@example
+Interrupted while waiting for the program.
+Give up (and stop debugging it)? (y or n)
+@end example
+
+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
@menu
* HP-UX:: HP-UX
* SVR4 Process Information:: SVR4 process information
+* DJGPP Native:: Features specific to the DJGPP port
@end menu
@node HP-UX
@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
@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 Embedded OS
This section goes into details specific to particular embedded
configurations.
+
+@c OBSOLETE * A29K Embedded:: AMD A29K Embedded
@menu
-* A29K Embedded:: AMD A29K Embedded
* ARM:: ARM
* H8/300:: Hitachi H8/300
* H8/500:: Hitachi H8/500
* Z8000:: Zilog Z8000
@end menu
-@node A29K Embedded
-@subsection AMD A29K Embedded
+@c OBSOLETE @node A29K Embedded
+@c OBSOLETE @subsection AMD A29K Embedded
+@c OBSOLETE
+@c OBSOLETE @menu
+@c OBSOLETE * A29K UDI::
+@c OBSOLETE * A29K EB29K::
+@c OBSOLETE * Comms (EB29K):: Communications setup
+@c OBSOLETE * gdb-EB29K:: EB29K cross-debugging
+@c OBSOLETE * Remote Log:: Remote log
+@c OBSOLETE @end menu
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE
+@c OBSOLETE @kindex target adapt
+@c OBSOLETE @item target adapt @var{dev}
+@c OBSOLETE Adapt monitor for A29K.
+@c OBSOLETE
+@c OBSOLETE @kindex target amd-eb
+@c OBSOLETE @item target amd-eb @var{dev} @var{speed} @var{PROG}
+@c OBSOLETE @cindex AMD EB29K
+@c OBSOLETE Remote PC-resident AMD EB29K board, attached over serial lines.
+@c OBSOLETE @var{dev} is the serial device, as for @code{target remote};
+@c OBSOLETE @var{speed} allows you to specify the linespeed; and @var{PROG} is the
+@c OBSOLETE name of the program to be debugged, as it appears to DOS on the PC.
+@c OBSOLETE @xref{A29K EB29K, ,EBMON protocol for AMD29K}.
+@c OBSOLETE
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node A29K UDI
+@c OBSOLETE @subsubsection A29K UDI
+@c OBSOLETE
+@c OBSOLETE @cindex UDI
+@c OBSOLETE @cindex AMD29K via UDI
+@c OBSOLETE
+@c OBSOLETE @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
+@c OBSOLETE protocol for debugging the a29k processor family. To use this
+@c OBSOLETE configuration with AMD targets running the MiniMON monitor, you need the
+@c OBSOLETE program @code{MONTIP}, available from AMD at no charge. You can also
+@c OBSOLETE use @value{GDBN} with the UDI-conformant a29k simulator program
+@c OBSOLETE @code{ISSTIP}, also available from AMD.
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE @item target udi @var{keyword}
+@c OBSOLETE @kindex udi
+@c OBSOLETE Select the UDI interface to a remote a29k board or simulator, where
+@c OBSOLETE @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
+@c OBSOLETE This file contains keyword entries which specify parameters used to
+@c OBSOLETE connect to a29k targets. If the @file{udi_soc} file is not in your
+@c OBSOLETE working directory, you must set the environment variable @samp{UDICONF}
+@c OBSOLETE to its pathname.
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node A29K EB29K
+@c OBSOLETE @subsubsection EBMON protocol for AMD29K
+@c OBSOLETE
+@c OBSOLETE @cindex EB29K board
+@c OBSOLETE @cindex running 29K programs
+@c OBSOLETE
+@c OBSOLETE AMD distributes a 29K development board meant to fit in a PC, together
+@c OBSOLETE with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
+@c OBSOLETE term, this development system is called the ``EB29K''. To use
+@c OBSOLETE @value{GDBN} from a Unix system to run programs on the EB29K board, you
+@c OBSOLETE must first connect a serial cable between the PC (which hosts the EB29K
+@c OBSOLETE board) and a serial port on the Unix system. In the following, we
+@c OBSOLETE assume you've hooked the cable between the PC's @file{COM1} port and
+@c OBSOLETE @file{/dev/ttya} on the Unix system.
+@c OBSOLETE
+@c OBSOLETE @node Comms (EB29K)
+@c OBSOLETE @subsubsection Communications setup
+@c OBSOLETE
+@c OBSOLETE The next step is to set up the PC's port, by doing something like this
+@c OBSOLETE in DOS on the PC:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE C:\> MODE com1:9600,n,8,1,none
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE This example---run on an MS DOS 4.0 system---sets the PC port to 9600
+@c OBSOLETE bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
+@c OBSOLETE you must match the communications parameters when establishing the Unix
+@c OBSOLETE end of the connection as well.
+@c OBSOLETE @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
+@c OBSOLETE @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
+@c OBSOLETE @c
+@c OBSOLETE @c It's optional, but it's unwise to omit it: who knows what is the
+@c OBSOLETE @c default value set when the DOS machines boots? "No retry" means that
+@c OBSOLETE @c the DOS serial device driver won't retry the operation if it fails;
+@c OBSOLETE @c I understand that this is needed because the GDB serial protocol
+@c OBSOLETE @c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99
+@c OBSOLETE
+@c OBSOLETE To give control of the PC to the Unix side of the serial line, type
+@c OBSOLETE the following at the DOS console:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE C:\> CTTY com1
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE (Later, if you wish to return control to the DOS console, you can use
+@c OBSOLETE the command @code{CTTY con}---but you must send it over the device that
+@c OBSOLETE had control, in our example over the @file{COM1} serial line.)
+@c OBSOLETE
+@c OBSOLETE From the Unix host, use a communications program such as @code{tip} or
+@c OBSOLETE @code{cu} to communicate with the PC; for example,
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE cu -s 9600 -l /dev/ttya
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE The @code{cu} options shown specify, respectively, the linespeed and the
+@c OBSOLETE serial port to use. If you use @code{tip} instead, your command line
+@c OBSOLETE may look something like the following:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE tip -9600 /dev/ttya
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE Your system may require a different name where we show
+@c OBSOLETE @file{/dev/ttya} as the argument to @code{tip}. The communications
+@c OBSOLETE parameters, including which port to use, are associated with the
+@c OBSOLETE @code{tip} argument in the ``remote'' descriptions file---normally the
+@c OBSOLETE system table @file{/etc/remote}.
+@c OBSOLETE @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
+@c OBSOLETE @c the DOS side's comms setup? cu can support -o (odd
+@c OBSOLETE @c parity), -e (even parity)---apparently no settings for no parity or
+@c OBSOLETE @c for character size. Taken from stty maybe...? John points out tip
+@c OBSOLETE @c can set these as internal variables, eg ~s parity=none; man stty
+@c OBSOLETE @c suggests that it *might* work to stty these options with stdin or
+@c OBSOLETE @c stdout redirected... ---doc@cygnus.com, 25feb91
+@c OBSOLETE @c
+@c OBSOLETE @c There's nothing to be done for the "none" part of the DOS MODE
+@c OBSOLETE @c command. The rest of the parameters should be matched by the
+@c OBSOLETE @c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99
+@c OBSOLETE
+@c OBSOLETE @kindex EBMON
+@c OBSOLETE Using the @code{tip} or @code{cu} connection, change the DOS working
+@c OBSOLETE directory to the directory containing a copy of your 29K program, then
+@c OBSOLETE start the PC program @code{EBMON} (an EB29K control program supplied
+@c OBSOLETE with your board by AMD). You should see an initial display from
+@c OBSOLETE @code{EBMON} similar to the one that follows, ending with the
+@c OBSOLETE @code{EBMON} prompt @samp{#}---
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE C:\> G:
+@c OBSOLETE
+@c OBSOLETE G:\> CD \usr\joe\work29k
+@c OBSOLETE
+@c OBSOLETE G:\USR\JOE\WORK29K> EBMON
+@c OBSOLETE Am29000 PC Coprocessor Board Monitor, version 3.0-18
+@c OBSOLETE Copyright 1990 Advanced Micro Devices, Inc.
+@c OBSOLETE Written by Gibbons and Associates, Inc.
+@c OBSOLETE
+@c OBSOLETE Enter '?' or 'H' for help
+@c OBSOLETE
+@c OBSOLETE PC Coprocessor Type = EB29K
+@c OBSOLETE I/O Base = 0x208
+@c OBSOLETE Memory Base = 0xd0000
+@c OBSOLETE
+@c OBSOLETE Data Memory Size = 2048KB
+@c OBSOLETE Available I-RAM Range = 0x8000 to 0x1fffff
+@c OBSOLETE Available D-RAM Range = 0x80002000 to 0x801fffff
+@c OBSOLETE
+@c OBSOLETE PageSize = 0x400
+@c OBSOLETE Register Stack Size = 0x800
+@c OBSOLETE Memory Stack Size = 0x1800
+@c OBSOLETE
+@c OBSOLETE CPU PRL = 0x3
+@c OBSOLETE Am29027 Available = No
+@c OBSOLETE Byte Write Available = Yes
+@c OBSOLETE
+@c OBSOLETE # ~.
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE Then exit the @code{cu} or @code{tip} program (done in the example by
+@c OBSOLETE typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
+@c OBSOLETE running, ready for @value{GDBN} to take over.
+@c OBSOLETE
+@c OBSOLETE For this example, we've assumed what is probably the most convenient
+@c OBSOLETE way to make sure the same 29K program is on both the PC and the Unix
+@c OBSOLETE system: a PC/NFS connection that establishes ``drive @file{G:}'' on the
+@c OBSOLETE PC as a file system on the Unix host. If you do not have PC/NFS or
+@c OBSOLETE something similar connecting the two systems, you must arrange some
+@c OBSOLETE other way---perhaps floppy-disk transfer---of getting the 29K program
+@c OBSOLETE from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
+@c OBSOLETE serial line.
+@c OBSOLETE
+@c OBSOLETE @node gdb-EB29K
+@c OBSOLETE @subsubsection EB29K cross-debugging
+@c OBSOLETE
+@c OBSOLETE Finally, @code{cd} to the directory containing an image of your 29K
+@c OBSOLETE program on the Unix system, and start @value{GDBN}---specifying as argument the
+@c OBSOLETE name of your 29K program:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE cd /usr/joe/work29k
+@c OBSOLETE @value{GDBP} myfoo
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @need 500
+@c OBSOLETE Now you can use the @code{target} command:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE target amd-eb /dev/ttya 9600 MYFOO
+@c OBSOLETE @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
+@c OBSOLETE @c emphasize that this is the name as seen by DOS (since I think DOS is
+@c OBSOLETE @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE In this example, we've assumed your program is in a file called
+@c OBSOLETE @file{myfoo}. Note that the filename given as the last argument to
+@c OBSOLETE @code{target amd-eb} should be the name of the program as it appears to DOS.
+@c OBSOLETE In our example this is simply @code{MYFOO}, but in general it can include
+@c OBSOLETE a DOS path, and depending on your transfer mechanism may not resemble
+@c OBSOLETE the name on the Unix side.
+@c OBSOLETE
+@c OBSOLETE At this point, you can set any breakpoints you wish; when you are ready
+@c OBSOLETE to see your program run on the 29K board, use the @value{GDBN} command
+@c OBSOLETE @code{run}.
+@c OBSOLETE
+@c OBSOLETE To stop debugging the remote program, use the @value{GDBN} @code{detach}
+@c OBSOLETE command.
+@c OBSOLETE
+@c OBSOLETE To return control of the PC to its console, use @code{tip} or @code{cu}
+@c OBSOLETE once again, after your @value{GDBN} session has concluded, to attach to
+@c OBSOLETE @code{EBMON}. You can then type the command @code{q} to shut down
+@c OBSOLETE @code{EBMON}, returning control to the DOS command-line interpreter.
+@c OBSOLETE Type @kbd{CTTY con} to return command input to the main DOS console,
+@c OBSOLETE and type @kbd{~.} to leave @code{tip} or @code{cu}.
+@c OBSOLETE
+@c OBSOLETE @node Remote Log
+@c OBSOLETE @subsubsection Remote log
+@c OBSOLETE @cindex @file{eb.log}, a log file for EB29K
+@c OBSOLETE @cindex log file for EB29K
+@c OBSOLETE
+@c OBSOLETE The @code{target amd-eb} command creates a file @file{eb.log} in the
+@c OBSOLETE current working directory, to help debug problems with the connection.
+@c OBSOLETE @file{eb.log} records all the output from @code{EBMON}, including echoes
+@c OBSOLETE of the commands sent to it. Running @samp{tail -f} on this file in
+@c OBSOLETE another window often helps to understand trouble with @code{EBMON}, or
+@c OBSOLETE unexpected events on the PC side of the connection.
-@menu
-* A29K UDI::
-* A29K EB29K::
-* Comms (EB29K):: Communications setup
-* gdb-EB29K:: EB29K cross-debugging
-* Remote Log:: Remote log
-@end menu
+@node ARM
+@subsection ARM
@table @code
-@kindex target adapt
-@item target adapt @var{dev}
-Adapt monitor for A29K.
+@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 amd-eb
-@item target amd-eb @var{dev} @var{speed} @var{PROG}
-@cindex AMD EB29K
-Remote PC-resident AMD EB29K board, attached over serial lines.
-@var{dev} is the serial device, as for @code{target remote};
-@var{speed} allows you to specify the linespeed; and @var{PROG} is the
-name of the program to be debugged, as it appears to DOS on the PC.
-@xref{A29K EB29K, ,EBMON protocol for AMD29K}.
+@kindex target rdp
+@item target rdp @var{dev}
+ARM Demon monitor.
@end table
-@node A29K UDI
-@subsubsection A29K UDI
-
-@cindex UDI
-@cindex AMD29K via UDI
-
-@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 H8/300
+@subsection Hitachi H8/300
@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
-@node A29K EB29K
-@subsubsection EBMON protocol for AMD29K
+@kindex target hms@r{, with H8/300}
+@item target hms @var{dev}
+A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host.
+Use special commands @code{device} and @code{speed} to control the serial
+line and the communications speed used.
-@cindex EB29K board
-@cindex running 29K programs
+@kindex target e7000@r{, with H8/300}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi H8 and SH.
-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.
+@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.
-@node Comms (EB29K)
-@subsubsection Communications setup
+@end table
-The next step is to set up the PC's port, by doing something like this
-in DOS on the PC:
-
-@example
-C:\> MODE com1:9600,n,8,1,none
-@end example
-
-@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
-
-To give control of the PC to the Unix side of the serial line, type
-the following at the DOS console:
-
-@example
-C:\> CTTY com1
-@end example
-
-@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.)
-
-From the Unix host, use a communications program such as @code{tip} or
-@code{cu} to communicate with the PC; for example,
-
-@example
-cu -s 9600 -l /dev/ttya
-@end example
-
-@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:
-
-@example
-tip -9600 /dev/ttya
-@end example
-
-@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
-
-@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.
-
-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.
-
-@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.
-
-@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).
+@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:
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 CPO registers appropriate for the 3041 chip.
+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.
debugging info.
@kindex set debug overload
@item set debug overload
-Turns on or off display of @value{GDBN} C++ overload debugging
+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++ overload
+Displays the current state of displaying @value{GDBN} C@t{++} overload
debugging info.
@kindex set debug remote
@cindex packets, reporting on stdout
@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:
+@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP
+port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the
+limitations of file names imposed by DOS filesystems.}.
+During startup, @value{GDBN} does the following:
@enumerate
@item
normally print messages to say what they are doing omit the messages
when called from command files.
+@value{GDBN} also accepts command input from standard input. In this
+mode, normal output goes to standard output and error output goes to
+standard error. Errors in a command file supplied on standard input do
+not terminate execution of the command file --- execution continues with
+the next command.
+
+@example
+gdb < cmds > log 2>&1
+@end example
+
+(The syntax above will vary depending on the shell used.) This example
+will execute commands from the file @file{cmds}. All output and errors
+would be directed to @file{log}.
+
@node Output
@section Commands for controlled output
letter.
@end table
+@node TUI
+@chapter @value{GDBN} Text User Interface
+@cindex TUI
+
+@menu
+* TUI Overview:: TUI overview
+* TUI Keys:: TUI key bindings
+* TUI Commands:: TUI specific commands
+* TUI Configuration:: TUI configuration variables
+@end menu
+
+The @value{GDBN} Text User Interface, TUI in short,
+is a terminal interface which uses the @code{curses} library
+to show the source file, the assembly output, the program registers
+and @value{GDBN} commands in separate text windows.
+The TUI is available only when @value{GDBN} is configured
+with the @code{--enable-tui} configure option (@pxref{Configure Options}).
+
+@node TUI Overview
+@section TUI overview
+
+The TUI has two display modes that can be switched while
+@value{GDBN} runs:
+
+@itemize @bullet
+@item
+A curses (or TUI) mode in which it displays several text
+windows on the terminal.
+
+@item
+A standard mode which corresponds to the @value{GDBN} configured without
+the TUI.
+@end itemize
+
+In the TUI mode, @value{GDBN} can display several text window
+on the terminal:
+
+@table @emph
+@item command
+This window is the @value{GDBN} command window with the @value{GDBN}
+prompt and the @value{GDBN} outputs. The @value{GDBN} input is still
+managed using readline but through the TUI. The @emph{command}
+window is always visible.
+
+@item source
+The source window shows the source file of the program. The current
+line as well as active breakpoints are displayed in this window.
+The current program position is shown with the @samp{>} marker and
+active breakpoints are shown with @samp{*} markers.
+
+@item assembly
+The assembly window shows the disassembly output of the program.
+
+@item register
+This window shows the processor registers. It detects when
+a register is changed and when this is the case, registers that have
+changed are highlighted.
+
+@end table
+
+The source, assembly and register windows are attached to the thread
+and the frame position. They are updated when the current thread
+changes, when the frame changes or when the program counter changes.
+These three windows are arranged by the TUI according to several
+layouts. The layout defines which of these three windows are visible.
+The following layouts are available:
+
+@itemize @bullet
+@item
+source
+
+@item
+assembly
+
+@item
+source and assembly
+
+@item
+source and registers
+
+@item
+assembly and registers
+
+@end itemize
+
+@node TUI Keys
+@section TUI Key Bindings
+@cindex TUI key bindings
+
+The TUI installs several key bindings in the readline keymaps
+(@pxref{Command Line Editing}).
+They allow to leave or enter in the TUI mode or they operate
+directly on the TUI layout and windows. The following key bindings
+are installed for both TUI mode and the @value{GDBN} standard mode.
+
+@table @kbd
+@kindex C-x C-a
+@item C-x C-a
+@kindex C-x a
+@itemx C-x a
+@kindex C-x A
+@itemx C-x A
+Enter or leave the TUI mode. When the TUI mode is left,
+the curses window management is left and @value{GDBN} operates using
+its standard mode writing on the terminal directly. When the TUI
+mode is entered, the control is given back to the curses windows.
+The screen is then refreshed.
+
+@kindex C-x 1
+@item C-x 1
+Use a TUI layout with only one window. The layout will
+either be @samp{source} or @samp{assembly}. When the TUI mode
+is not active, it will switch to the TUI mode.
+
+Think of this key binding as the Emacs @kbd{C-x 1} binding.
+
+@kindex C-x 2
+@item C-x 2
+Use a TUI layout with at least two windows. When the current
+layout shows already two windows, a next layout with two windows is used.
+When a new layout is chosen, one window will always be common to the
+previous layout and the new one.
+
+Think of it as the Emacs @kbd{C-x 2} binding.
+
+@end table
+
+The following key bindings are handled only by the TUI mode:
+
+@table @key
+@kindex PgUp
+@item PgUp
+Scroll the active window one page up.
+
+@kindex PgDn
+@item PgDn
+Scroll the active window one page down.
+
+@kindex Up
+@item Up
+Scroll the active window one line up.
+
+@kindex Down
+@item Down
+Scroll the active window one line down.
+
+@kindex Left
+@item Left
+Scroll the active window one column left.
+
+@kindex Right
+@item Right
+Scroll the active window one column right.
+
+@kindex C-L
+@item C-L
+Refresh the screen.
+
+@end table
+
+In the TUI mode, the arrow keys are used by the active window
+for scrolling. This means they are not available for readline. It is
+necessary to use other readline key bindings such as @key{C-p}, @key{C-n},
+@key{C-b} and @key{C-f}.
+
+@node TUI Commands
+@section TUI specific commands
+@cindex TUI commands
+
+The TUI has specific commands to control the text windows.
+These commands are always available, that is they do not depend on
+the current terminal mode in which @value{GDBN} runs. When @value{GDBN}
+is in the standard mode, using these commands will automatically switch
+in the TUI mode.
+
+@table @code
+@item layout next
+@kindex layout next
+Display the next layout.
+
+@item layout prev
+@kindex layout prev
+Display the previous layout.
+
+@item layout src
+@kindex layout src
+Display the source window only.
+
+@item layout asm
+@kindex layout asm
+Display the assembly window only.
+
+@item layout split
+@kindex layout split
+Display the source and assembly window.
+
+@item layout regs
+@kindex layout regs
+Display the register window together with the source or assembly window.
+
+@item focus next | prev | src | asm | regs | split
+@kindex focus
+Set the focus to the named window.
+This command allows to change the active window so that scrolling keys
+can be affected to another window.
+
+@item refresh
+@kindex refresh
+Refresh the screen. This is similar to using @key{C-L} key.
+
+@item update
+@kindex update
+Update the source window and the current execution point.
+
+@item winheight @var{name} +@var{count}
+@itemx winheight @var{name} -@var{count}
+@kindex winheight
+Change the height of the window @var{name} by @var{count}
+lines. Positive counts increase the height, while negative counts
+decrease it.
+
+@end table
+
+@node TUI Configuration
+@section TUI configuration variables
+@cindex TUI configuration variables
+
+The TUI has several configuration variables that control the
+appearance of windows on the terminal.
+
+@table @code
+@item set tui border-kind @var{kind}
+@kindex set tui border-kind
+Select the border appearance for the source, assembly and register windows.
+The possible values are the following:
+@table @code
+@item space
+Use a space character to draw the border.
+
+@item ascii
+Use ascii characters + - and | to draw the border.
+
+@item acs
+Use the Alternate Character Set to draw the border. The border is
+drawn using character line graphics if the terminal supports them.
+
+@end table
+
+@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
+@item normal
+Use normal attributes to display the border.
+
+@item standout
+Use standout mode.
+
+@item reverse
+Use reverse video mode.
+
+@item half
+Use half bright mode.
+
+@item half-standout
+Use half bright and standout mode.
+
+@item bold
+Use extra bright or bold mode.
+
+@item bold-standout
+Use extra bright or bold and standout mode.
+
+@end table
+
+@end table
+
@node Emacs
@chapter Using @value{GDBN} under @sc{gnu} Emacs
There are many other options available as well, but they are generally
needed for special purposes only.
+@node Maintenance Commands
+@appendix Maintenance Commands
+@cindex maintenance commands
+@cindex internal commands
+
+In addition to commands intended for @value{GDBN} users, @value{GDBN}
+includes a number of commands intended for @value{GDBN} developers.
+These commands are provided here for reference.
+
+@table @code
+@kindex maint info breakpoints
+@item @anchor{maint info breakpoints}maint info breakpoints
+Using the same format as @samp{info breakpoints}, display both the
+breakpoints you've set explicitly, and those @value{GDBN} is using for
+internal purposes. Internal breakpoints are shown with negative
+breakpoint numbers. The type column identifies what kind of breakpoint
+is shown:
+
+@table @code
+@item breakpoint
+Normal, explicitly set breakpoint.
+
+@item watchpoint
+Normal, explicitly set watchpoint.
+
+@item longjmp
+Internal breakpoint, used to handle correctly stepping through
+@code{longjmp} calls.
+
+@item longjmp resume
+Internal breakpoint at the target of a @code{longjmp}.
+
+@item until
+Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
+
+@item finish
+Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
+
+@item shlib events
+Shared library events.
+
+@end table
+
+@end table
+
+
+@node Remove Protocol
+@appendix @value{GDBN} Remote Serial Protocol
+
+There may be occasions when you need to know something about the
+protocol---for example, if there is only one serial port to your target
+machine, you might want your program to do something special if it
+recognizes a packet meant for @value{GDBN}.
+
+In the examples below, @samp{<-} and @samp{->} are used to indicate
+transmitted and received data respectfully.
+
+@cindex protocol, @value{GDBN} remote serial
+@cindex serial protocol, @value{GDBN} remote
+@cindex remote serial protocol
+All @value{GDBN} commands and responses (other than acknowledgments) are
+sent as a @var{packet}. A @var{packet} is introduced with the character
+@samp{$}, the actual @var{packet-data}, and the terminating character
+@samp{#} followed by a two-digit @var{checksum}:
+
+@example
+@code{$}@var{packet-data}@code{#}@var{checksum}
+@end example
+@noindent
+
+@cindex checksum, for @value{GDBN} remote
+@noindent
+The two-digit @var{checksum} is computed as the modulo 256 sum of all
+characters between the leading @samp{$} and the trailing @samp{#} (an
+eight bit unsigned checksum).
+
+Implementors should note that prior to @value{GDBN} 5.0 the protocol
+specification also included an optional two-digit @var{sequence-id}:
+
+@example
+@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
+@end example
+
+@cindex sequence-id, for @value{GDBN} remote
+@noindent
+That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
+has never output @var{sequence-id}s. Stubs that handle packets added
+since @value{GDBN} 5.0 must not accept @var{sequence-id}.
+
+@cindex acknowledgment, for @value{GDBN} remote
+When either the host or the target machine receives a packet, the first
+response expected is an acknowledgment: either @samp{+} (to indicate
+the package was received correctly) or @samp{-} (to request
+retransmission):
+
+@example
+<- @code{$}@var{packet-data}@code{#}@var{checksum}
+-> @code{+}
+@end example
+@noindent
+
+The host (@value{GDBN}) sends @var{command}s, and the target (the
+debugging stub incorporated in your program) sends a @var{response}. In
+the case of step and continue @var{command}s, the response is only sent
+when the operation has completed (the target has again stopped).
+
+@var{packet-data} consists of a sequence of characters with the
+exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
+exceptions).
+
+Fields within the packet should be separated using @samp{,} @samp{;} or
+@samp{:}. Except where otherwise noted all numbers are represented in
+HEX with leading zeros suppressed.
+
+Implementors should note that prior to @value{GDBN} 5.0, the character
+@samp{:} could not appear as the third character in a packet (as it
+would potentially conflict with the @var{sequence-id}).
+
+Response @var{data} can be run-length encoded to save space. A @samp{*}
+means that the next character is an @sc{ascii} encoding giving a repeat count
+which stands for that many repetitions of the character preceding the
+@samp{*}. The encoding is @code{n+29}, yielding a printable character
+where @code{n >=3} (which is where rle starts to win). The printable
+characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
+value greater than 126 should not be used.
+
+Some remote systems have used a different run-length encoding mechanism
+loosely refered to as the cisco encoding. Following the @samp{*}
+character are two hex digits that indicate the size of the packet.
+
+So:
+@example
+"@code{0* }"
+@end example
+@noindent
+means the same as "0000".
+
+The error response returned for some packets includes a two character
+error number. That number is not well defined.
+
+For any @var{command} not supported by the stub, an empty response
+(@samp{$#00}) should be returned. That way it is possible to extend the
+protocol. A newer @value{GDBN} can tell if a packet is supported based
+on that response.
+
+A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
+@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
+optional.
+
+Below is a complete list of all currently defined @var{command}s and
+their corresponding response @var{data}:
+@page
+@multitable @columnfractions .30 .30 .40
+@item Packet
+@tab Request
+@tab Description
+
+@item extended mode
+@tab @code{!}
+@tab
+Enable extended mode. In extended mode, the remote server is made
+persistent. The @samp{R} packet is used to restart the program being
+debugged.
+@item
+@tab reply @samp{OK}
+@tab
+The remote target both supports and has enabled extended mode.
+
+@item last signal
+@tab @code{?}
+@tab
+Indicate the reason the target halted. The reply is the same as for step
+and continue.
+@item
+@tab reply
+@tab see below
+
+
+@item reserved
+@tab @code{a}
+@tab Reserved for future use
+
+@item set program arguments @strong{(reserved)}
+@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
+@tab
+@item
+@tab
+@tab
+Initialized @samp{argv[]} array passed into program. @var{arglen}
+specifies the number of bytes in the hex encoded byte stream @var{arg}.
+See @file{gdbserver} for more details.
+@item
+@tab reply @code{OK}
+@item
+@tab reply @code{E}@var{NN}
+
+@item set baud @strong{(deprecated)}
+@tab @code{b}@var{baud}
+@tab
+Change the serial line speed to @var{baud}. JTC: @emph{When does the
+transport layer state change? When it's received, or after the ACK is
+transmitted. In either case, there are problems if the command or the
+acknowledgment packet is dropped.} Stan: @emph{If people really wanted
+to add something like this, and get it working for the first time, they
+ought to modify ser-unix.c to send some kind of out-of-band message to a
+specially-setup stub and have the switch happen "in between" packets, so
+that from remote protocol's point of view, nothing actually
+happened.}
+
+@item set breakpoint @strong{(deprecated)}
+@tab @code{B}@var{addr},@var{mode}
+@tab
+Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
+breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and
+@samp{z} packets.}
+
+@item continue
+@tab @code{c}@var{addr}
+@tab
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+current address.
+@item
+@tab reply
+@tab see below
+
+@item continue with signal
+@tab @code{C}@var{sig}@code{;}@var{addr}
+@tab
+Continue with signal @var{sig} (hex signal number). If
+@code{;}@var{addr} is omitted, resume at same address.
+@item
+@tab reply
+@tab see below
+
+@item toggle debug @strong{(deprecated)}
+@tab @code{d}
+@tab
+toggle debug flag.
+
+@item detach
+@tab @code{D}
+@tab
+Detach @value{GDBN} from the remote system. Sent to the remote target before
+@value{GDBN} disconnects.
+@item
+@tab reply @emph{no response}
+@tab
+@value{GDBN} does not check for any response after sending this packet.
+
+@item reserved
+@tab @code{e}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{E}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{f}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{F}
+@tab Reserved for future use
+
+@item read registers
+@tab @code{g}
+@tab Read general registers.
+@item
+@tab reply @var{XX...}
+@tab
+Each byte of register data is described by two hex digits. The bytes
+with the register are transmitted in target byte order. The size of
+each register and their position within the @samp{g} @var{packet} are
+determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} and
+@var{REGISTER_NAME} macros. The specification of several standard
+@code{g} packets is specified below.
+@item
+@tab @code{E}@var{NN}
+@tab for an error.
+
+@item write regs
+@tab @code{G}@var{XX...}
+@tab
+See @samp{g} for a description of the @var{XX...} data.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+
+@item reserved
+@tab @code{h}
+@tab Reserved for future use
+
+@item set thread
+@tab @code{H}@var{c}@var{t...}
+@tab
+Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
+@samp{G}, et.al.). @var{c} = @samp{c} for thread used in step and
+continue; @var{t...} can be -1 for all threads. @var{c} = @samp{g} for
+thread used in other operations. If zero, pick a thread, any thread.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+
+@c FIXME: JTC:
+@c 'H': How restrictive (or permissive) is the thread model. If a
+@c thread is selected and stopped, are other threads allowed
+@c to continue to execute? As I mentioned above, I think the
+@c semantics of each command when a thread is selected must be
+@c described. For example:
+@c
+@c 'g': If the stub supports threads and a specific thread is
+@c selected, returns the register block from that thread;
+@c otherwise returns current registers.
+@c
+@c 'G' If the stub supports threads and a specific thread is
+@c selected, sets the registers of the register block of
+@c that thread; otherwise sets current registers.
+
+@item cycle step @strong{(draft)}
+@tab @code{i}@var{addr}@code{,}@var{nnn}
+@tab
+Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
+present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
+step starting at that address.
+
+@item signal then cycle step @strong{(reserved)}
+@tab @code{I}
+@tab
+See @samp{i} and @samp{S} for likely syntax and semantics.
+
+@item reserved
+@tab @code{j}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{J}
+@tab Reserved for future use
+
+@item kill request
+@tab @code{k}
+@tab
+FIXME: @emph{There is no description of how operate when a specific
+thread context has been selected (ie. does 'k' kill only that thread?)}.
+
+@item reserved
+@tab @code{l}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{L}
+@tab Reserved for future use
+
+@item read memory
+@tab @code{m}@var{addr}@code{,}@var{length}
+@tab
+Read @var{length} bytes of memory starting at address @var{addr}.
+Neither @value{GDBN} nor the stub assume that sized memory transfers are assumed
+using word alligned accesses. FIXME: @emph{A word aligned memory
+transfer mechanism is needed.}
+@item
+@tab reply @var{XX...}
+@tab
+@var{XX...} is mem contents. Can be fewer bytes than requested if able
+to read only part of the data. Neither @value{GDBN} nor the stub assume that
+sized memory transfers are assumed using word alligned accesses. FIXME:
+@emph{A word aligned memory transfer mechanism is needed.}
+@item
+@tab reply @code{E}@var{NN}
+@tab @var{NN} is errno
+
+@item write mem
+@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...}
+@tab
+Write @var{length} bytes of memory starting at address @var{addr}.
+@var{XX...} is the data.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab
+for an error (this includes the case where only part of the data was
+written).
+
+@item reserved
+@tab @code{n}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{N}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{o}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{O}
+@tab Reserved for future use
+
+@item read reg @strong{(reserved)}
+@tab @code{p}@var{n...}
+@tab
+See write register.
+@item
+@tab return @var{r....}
+@tab The hex encoded value of the register in target byte order.
+
+@item write reg
+@tab @code{P}@var{n...}@code{=}@var{r...}
+@tab
+Write register @var{n...} with value @var{r...}, which contains two hex
+digits for each byte in the register (target byte order).
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+
+@item general query
+@tab @code{q}@var{query}
+@tab
+Request info about @var{query}. In general @value{GDBN} queries
+have a leading upper case letter. Custom vendor queries should use a
+company prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may
+optionally be followed by a @samp{,} or @samp{;} separated list. Stubs
+must ensure that they match the full @var{query} name.
+@item
+@tab reply @code{XX...}
+@tab Hex encoded data from query. The reply can not be empty.
+@item
+@tab reply @code{E}@var{NN}
+@tab error reply
+@item
+@tab reply @samp{}
+@tab Indicating an unrecognized @var{query}.
+
+@item general set
+@tab @code{Q}@var{var}@code{=}@var{val}
+@tab
+Set value of @var{var} to @var{val}. See @samp{q} for a discussing of
+naming conventions.
+
+@item reset @strong{(deprecated)}
+@tab @code{r}
+@tab
+Reset the entire system.
+
+@item remote restart
+@tab @code{R}@var{XX}
+@tab
+Restart the program being debugged. @var{XX}, while needed, is ignored.
+This packet is only available in extended mode.
+@item
+@tab
+no reply
+@tab
+The @samp{R} packet has no reply.
+
+@item step
+@tab @code{s}@var{addr}
+@tab
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+same address.
+@item
+@tab reply
+@tab see below
+
+@item step with signal
+@tab @code{S}@var{sig}@code{;}@var{addr}
+@tab
+Like @samp{C} but step not continue.
+@item
+@tab reply
+@tab see below
+
+@item search
+@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
+@tab
+Search backwards starting at address @var{addr} for a match with pattern
+@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
+bytes. @var{addr} must be at least 3 digits.
+
+@item thread alive
+@tab @code{T}@var{XX}
+@tab Find out if the thread XX is alive.
+@item
+@tab reply @code{OK}
+@tab thread is still alive
+@item
+@tab reply @code{E}@var{NN}
+@tab thread is dead
+
+@item reserved
+@tab @code{u}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{U}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{v}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{V}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{w}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{W}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{x}
+@tab Reserved for future use
+
+@item write mem (binary)
+@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
+@tab
+@var{addr} is address, @var{length} is number of bytes, @var{XX...} is
+binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
+escaped using @code{0x7d}.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+
+@item reserved
+@tab @code{y}
+@tab Reserved for future use
+
+@item reserved
+@tab @code{Y}
+@tab Reserved for future use
+
+@item remove break or watchpoint @strong{(draft)}
+@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
+@tab
+See @samp{Z}.
+
+@item insert break or watchpoint @strong{(draft)}
+@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
+@tab
+@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
+breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
+@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
+bytes. For a software breakpoint, @var{length} specifies the size of
+the instruction to be patched. For hardware breakpoints and watchpoints
+@var{length} specifies the memory region to be monitored. To avoid
+potential problems with duplicate packets, the operations should be
+implemented in an idempotent way.
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab @samp{}
+@tab If not supported.
+
+@item reserved
+@tab <other>
+@tab Reserved for future use
+
+@end multitable
+
+The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
+receive any of the below as a reply. In the case of the @samp{C},
+@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
+when the target halts. In the below the exact meaning of @samp{signal
+number} is poorly defined. In general one of the UNIX signal numbering
+conventions is used.
+
+@multitable @columnfractions .4 .6
+
+@item @code{S}@var{AA}
+@tab @var{AA} is the signal number
+
+@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
+@tab
+@var{AA} = two hex digit signal number; @var{n...} = register number
+(hex), @var{r...} = target byte ordered register contents, size defined
+by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} =
+thread process ID, this is a hex integer; @var{n...} = other string not
+starting with valid hex digit. @value{GDBN} should ignore this
+@var{n...}, @var{r...} pair and go on to the next. This way we can
+extend the protocol.
+
+@item @code{W}@var{AA}
+@tab
+The process exited, and @var{AA} is the exit status. This is only
+applicable for certains sorts of targets.
+
+@item @code{X}@var{AA}
+@tab
+The process terminated with signal @var{AA}.
+
+@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)}
+@tab
+@var{AA} = signal number; @var{t...} = address of symbol "_start";
+@var{d...} = base of data section; @var{b...} = base of bss section.
+@emph{Note: only used by Cisco Systems targets. The difference between
+this reply and the "qOffsets" query is that the 'N' packet may arrive
+spontaneously whereas the 'qOffsets' is a query initiated by the host
+debugger.}
+
+@item @code{O}@var{XX...}
+@tab
+@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time
+while the program is running and the debugger should continue to wait
+for 'W', 'T', etc.
+
+@end multitable
+
+The following set and query packets have already been defined.
+
+@multitable @columnfractions .2 .2 .6
+
+@item current thread
+@tab @code{q}@code{C}
+@tab Return the current thread id.
+@item
+@tab reply @code{QC}@var{pid}
+@tab
+Where @var{pid} is a HEX encoded 16 bit process id.
+@item
+@tab reply *
+@tab Any other reply implies the old pid.
+
+@item all thread ids
+@tab @code{q}@code{fThreadInfo}
+@item
+@tab @code{q}@code{sThreadInfo}
+@tab
+Obtain a list of active thread ids from the target (OS). Since there
+may be too many active threads to fit into one reply packet, this query
+works iteratively: it may require more than one query/reply sequence to
+obtain the entire list of threads. The first query of the sequence will
+be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
+sequence will be the @code{qs}@code{ThreadInfo} query.
+@item
+@tab
+@tab NOTE: replaces the @code{qL} query (see below).
+@item
+@tab reply @code{m}@var{<id>}
+@tab A single thread id
+@item
+@tab reply @code{m}@var{<id>},@var{<id>...}
+@tab a comma-separated list of thread ids
+@item
+@tab reply @code{l}
+@tab (lower case 'el') denotes end of list.
+@item
+@tab
+@tab
+In response to each query, the target will reply with a list of one
+or more thread ids, in big-endian hex, separated by commas. GDB will
+respond to each reply with a request for more thread ids (using the
+@code{qs} form of the query), until the target responds with @code{l}
+(lower-case el, for @code{'last'}).
+
+@item extra thread info
+@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id}
+@tab
+@item
+@tab
+@tab
+Where @var{<id>} is a thread-id in big-endian hex.
+Obtain a printable string description of a thread's attributes from
+the target OS. This string may contain anything that the target OS
+thinks is interesting for @value{GDBN} to tell the user about the thread.
+The string is displayed in @value{GDBN}'s @samp{info threads} display.
+Some examples of possible thread extra info strings are "Runnable", or
+"Blocked on Mutex".
+@item
+@tab reply @var{XX...}
+@tab
+Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the
+printable string containing the extra information about the thread's
+attributes.
+
+@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
+@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
+@tab
+@item
+@tab
+@tab
+Obtain thread information from RTOS. Where: @var{startflag} (one hex
+digit) is one to indicate the first query and zero to indicate a
+subsequent query; @var{threadcount} (two hex digits) is the maximum
+number of threads the response packet can contain; and @var{nextthread}
+(eight hex digits), for subsequent queries (@var{startflag} is zero), is
+returned in the response as @var{argthread}.
+@item
+@tab
+@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo}
+query (see above).
+@item
+@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...}
+@tab
+@item
+@tab
+@tab
+Where: @var{count} (two hex digits) is the number of threads being
+returned; @var{done} (one hex digit) is zero to indicate more threads
+and one indicates no further threads; @var{argthreadid} (eight hex
+digits) is @var{nextthread} from the request packet; @var{thread...} is
+a sequence of thread IDs from the target. @var{threadid} (eight hex
+digits). See @code{remote.c:parse_threadlist_response()}.
+
+@item compute CRC of memory block
+@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
+@tab
+@item
+@tab reply @code{E}@var{NN}
+@tab An error (such as memory fault)
+@item
+@tab reply @code{C}@var{CRC32}
+@tab A 32 bit cyclic redundancy check of the specified memory region.
+
+@item query sect offs
+@tab @code{q}@code{Offsets}
+@tab
+Get section offsets that the target used when re-locating the downloaded
+image. @emph{Note: while a @code{Bss} offset is included in the
+response, @value{GDBN} ignores this and instead applies the @code{Data}
+offset to the @code{Bss} section.}
+@item
+@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
+
+@item thread info request
+@tab @code{q}@code{P}@var{mode}@var{threadid}
+@tab
+@item
+@tab
+@tab
+Returns information on @var{threadid}. Where: @var{mode} is a hex
+encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
+@item
+@tab reply *
+@tab
+See @code{remote.c:remote_unpack_thread_info_response()}.
+
+@item remote command
+@tab @code{q}@code{Rcmd,}@var{COMMAND}
+@tab
+@item
+@tab
+@tab
+@var{COMMAND} (hex encoded) is passed to the local interpreter for
+execution. Invalid commands should be reported using the output string.
+Before the final result packet, the target may also respond with a
+number of intermediate @code{O}@var{OUTPUT} console output
+packets. @emph{Implementors should note that providing access to a
+stubs's interpreter may have security implications}.
+@item
+@tab reply @code{OK}
+@tab
+A command response with no output.
+@item
+@tab reply @var{OUTPUT}
+@tab
+A command response with the hex encoded output string @var{OUTPUT}.
+@item
+@tab reply @code{E}@var{NN}
+@tab
+Indicate a badly formed request.
+
+@item
+@tab reply @samp{}
+@tab
+When @samp{q}@samp{Rcmd} is not recognized.
+
+@item symbol lookup
+@tab @code{qSymbol::}
+@tab
+Notify the target that @value{GDBN} is prepared to serve symbol lookup
+requests. Accept requests from the target for the values of symbols.
+@item
+@tab
+@tab
+@item
+@tab reply @code{OK}
+@tab
+The target does not need to look up any (more) symbols.
+@item
+@tab reply @code{qSymbol:}@var{sym_name}
+@tab
+@sp 2
+@noindent
+The target requests the value of symbol @var{sym_name} (hex encoded).
+@value{GDBN} may provide the value by using the
+@code{qSymbol:}@var{sym_value}:@var{sym_name}
+message, described below.
+
+@item symbol value
+@tab @code{qSymbol:}@var{sym_value}:@var{sym_name}
+@tab
+@sp 1
+@noindent
+Set the value of SYM_NAME to SYM_VALUE.
+@item
+@tab
+@tab
+@var{sym_name} (hex encoded) is the name of a symbol whose value
+the target has previously requested.
+@item
+@tab
+@tab
+@var{sym_value} (hex) is the value for symbol @var{sym_name}.
+If @value{GDBN} cannot supply a value for @var{sym_name}, then this
+field will be empty.
+@item
+@tab reply @code{OK}
+@tab
+The target does not need to look up any (more) symbols.
+@item
+@tab reply @code{qSymbol:}@var{sym_name}
+@tab
+@sp 2
+@noindent
+The target requests the value of a new symbol @var{sym_name} (hex encoded).
+@value{GDBN} will continue to supply the values of symbols (if available),
+until the target ceases to request them.
+
+@end multitable
+
+The following @samp{g}/@samp{G} packets have previously been defined.
+In the below, some thirty-two bit registers are transferred as sixty-four
+bits. Those registers should be zero/sign extended (which?) to fill the
+space allocated. Register bytes are transfered in target byte order.
+The two nibbles within a register byte are transfered most-significant -
+least-significant.
+
+@multitable @columnfractions .5 .5
+
+@item MIPS32
+@tab
+All registers are transfered as thirty-two bit quantities in the order:
+32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
+registers; fsr; fir; fp.
+
+@item MIPS64
+@tab
+All registers are transfered as sixty-four bit quantities (including
+thirty-two bit registers such as @code{sr}). The ordering is the same
+as @code{MIPS32}.
+
+@end multitable
+
+Example sequence of a target being re-started. Notice how the restart
+does not get any direct output:
+
+@example
+<- @code{R00}
+-> @code{+}
+@emph{target restarts}
+<- @code{?}
+-> @code{+}
+-> @code{T001:1234123412341234}
+<- @code{+}
+@end example
+
+Example sequence of a target being stepped by a single instruction:
+
+@example
+<- @code{G1445...}
+-> @code{+}
+<- @code{s}
+-> @code{+}
+@emph{time passes}
+-> @code{T001:1234123412341234}
+<- @code{+}
+<- @code{g}
+-> @code{+}
+-> @code{1455...}
+<- @code{+}
+@end example
+
+
+@include fdl.texi
+
@node Index
@unnumbered Index
projects / deliverable / binutils-gdb.git / blobdiff