\input texinfo @c -*-texinfo-*-
-@c Copyright 1988-1999
+@c Copyright 1988-2000
@c Free Software Foundation, Inc.
@c
-@c %**start of header
+@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@c of @set vars. However, you can override filename with makeinfo -o.
@setfilename gdb.info
@finalout
@syncodeindex ky cp
-@c readline appendices use @vindex
+@c readline appendices use @vindex, @findex and @ftable,
+@c annotate.texi and gdbmi use @findex.
@syncodeindex vr cp
+@syncodeindex fn cp
@c !!set GDB manual's edition---not the same as GDB version!
-@set EDITION Seventh
+@set EDITION Eighth
@c !!set GDB manual's revision date
-@set DATE February 1999
+@set DATE March 2000
-@c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly.
+@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.
@c This is a dir.info fragment to support semi-automated addition of
-@c manuals to an info tree. zoo@cygnus.com is developing this facility.
+@c manuals to an info tree.
@dircategory Programming & development tools.
@direntry
* Gdb: (gdb). The @sc{gnu} debugger.
This file documents the @sc{gnu} debugger @value{GDBN}.
-This is the @value{EDITION} Edition, @value{DATE},
+This is the @value{EDITION} Edition, @value{DATE},
of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
for @value{GDBN} Version @value{GDBVN}.
-Copyright (C) 1988-1999 Free Software Foundation, Inc.
+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
@sp 1
@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
@subtitle @value{DATE}
-@author Richard M. Stallman and Roland H. Pesch
+@author Richard Stallman, Roland Pesch, Stan Shebs, et al.
@page
@tex
{\parskip=0pt
}
@end tex
-@c ISBN seems to be wrong...
-
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-1999 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2000 Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
59 Temple Place - Suite 330, @*
Boston, MA 02111-1307 USA @*
-Printed copies are available for $20 each. @*
-ISBN 1-882114-11-6 @*
+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
@end titlepage
@page
-
-@node Top, Summary, (dir), (dir)
@ifinfo
+@node Top, Summary, (dir), (dir)
+
@top Debugging with @value{GDBN}
This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
-This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
+This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-1999 Free Software Foundation, Inc.
+Copyright (C) 1988-2000 Free Software Foundation, Inc.
+
+@menu
+* Summary:: Summary of @value{GDBN}
+* Sample Session:: A sample @value{GDBN} session
+
+* Invocation:: Getting in and out of @value{GDBN}
+* Commands:: @value{GDBN} commands
+* Running:: Running programs under @value{GDBN}
+* Stopping:: Stopping and continuing
+* Stack:: Examining the stack
+* Source:: Examining source files
+* Data:: Examining data
+
+* Languages:: Using @value{GDBN} with different languages
+
+* Symbols:: Examining the symbol table
+* Altering:: Altering execution
+* GDB Files:: @value{GDBN} files
+* Targets:: Specifying a debugging target
+* Configurations:: Configuration-specific information
+* Controlling GDB:: Controlling @value{GDBN}
+* Sequences:: Canned sequences of commands
+* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
+* Annotations:: @value{GDBN}'s annotation interface.
+* GDB/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
+* Index:: Index
+@end menu
+
@end ifinfo
+
+@c the replication sucks, but this avoids a texinfo 3.12 lameness
+
+@ifhtml
+@node Top
+
+@top Debugging with @value{GDBN}
+
+This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
+
+This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
+@value{GDBVN}.
+
+Copyright (C) 1988-2000 Free Software Foundation, Inc.
+
@menu
* Summary:: Summary of @value{GDBN}
* Sample Session:: A sample @value{GDBN} session
* Controlling GDB:: Controlling @value{GDBN}
* Sequences:: Canned sequences of commands
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
-* Annotations:: @value{GDBN}'s annotations interface.
+* Annotations:: @value{GDBN}'s annotation interface.
* GDB Bugs:: Reporting bugs in @value{GDBN}
* Formatting Documentation:: How to format and print @value{GDBN} documentation
* Index:: Index
@end menu
-@node Summary, Sample Session, Top, Top
+@end ifhtml
+
+@c TeX can handle the contents at the start but makeinfo 3.12 can not
+@iftex
+@contents
+@end iftex
+
+@node Summary
@unnumbered Summary of @value{GDBN}
The purpose of a debugger such as @value{GDBN} is to allow you to see what is
* Contributors:: Contributors to GDB
@end menu
-@node Free Software, Contributors, Summary, Summary
+@node Free Software
@unnumberedsec Free software
-@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
+@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
General Public License
(GPL). The GPL gives you the freedom to copy or adapt a licensed
program---but every person getting a copy also gets with it the
you have these freedoms and that you cannot take these freedoms away
from anyone else.
-@node Contributors, , Free Software, Summary
+@node Contributors
@unnumberedsec Contributors to @value{GDBN}
Richard Stallman was the original author of @value{GDBN}, and of many
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);
Jim Blandy (release 4.18);
Jason Molenda (release 4.17);
Stan Shebs (release 4.14);
Andrew Beers of SUNY Buffalo wrote the language-switching code, the
Modula-2 support, and contributed the Languages chapter of this manual.
-Fred Fish wrote most of the support for Unix System Vr4.
+Fred Fish wrote most of the support for Unix System Vr4.
He also enhanced the command-completion support to cover C++ overloaded
symbols.
Zuhn have made contributions both large and small.
-@node Sample Session, Invocation, Summary, Top
+@node Sample Session
@chapter A Sample @value{GDBN} Session
You can use this manual at your leisure to read all about @value{GDBN}.
@c FIXME: this falsifies the exact text played out, to permit smallbook
@c FIXME... format to come out better.
@value{GDBN} is free software and you are welcome to distribute copies
- of it under certain conditions; type "show copying" to see
+ of it under certain conditions; type "show copying" to see
the conditions.
-There is absolutely no warranty for @value{GDBN}; type "show warranty"
+There is absolutely no warranty for @value{GDBN}; type "show warranty"
for details.
@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
@smallexample
@b{changequote(<QUOTE>,<UNQUOTE>)}
-Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
+Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
at builtin.c:879
879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
@end smallexample
(@value{GDBP}) @b{bt}
#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
at input.c:530
-#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
+#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
at builtin.c:882
#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
(@value{GDBP}) @b{quit}
@end smallexample
-@node Invocation, Commands, Sample Session, Top
+@node Invocation
@chapter Getting In and Out of @value{GDBN}
This chapter discusses how to start @value{GDBN}, and how to get out of it.
-The essentials are:
+The essentials are:
@itemize @bullet
-@item
+@item
type @samp{@value{GDBP}} to start @value{GDBN}.
-@item
+@item
type @kbd{quit} or @kbd{C-d} to exit.
@end itemize
* Shell Commands:: How to use shell commands inside @value{GDBN}
@end menu
-@node Invoking GDB, Quitting GDB, Invocation, Invocation
+@node Invoking GDB
@section Invoking @value{GDBN}
Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
The command-line options described here are designed
to cover a variety of situations; in some environments, some of these
-options may effectively be unavailable.
+options may effectively be unavailable.
The most usual way to start @value{GDBN} is with one argument,
specifying an executable program:
* Mode Options:: Choosing modes
@end menu
-@node File Options, Mode Options, Invoking GDB, Invoking GDB
+@node File Options
@subsection Choosing files
When @value{GDBN} starts, it reads any arguments other than options as
@emph{Warning: this option depends on operating system facilities that are not
supported on all systems.}@*
If memory-mapped files are available on your system through the @code{mmap}
-system call, you can use this option
+system call, you can use this option
to have @value{GDBN} write the symbols from your
program into a reusable file in the current directory. If the program you are debugging is
called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.
gdb -batch -nx -mapped -readnow programname
@end example
-@node Mode Options, , File Options, Invoking GDB
+@node Mode Options
@subsection Choosing modes
You can run @value{GDBN} in various alternative modes---for example, in
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}.
-@c FIXME: There should be an @xref here to the GDB/MI docs, but
-@c gdbmi.texi doesn't have a single node to reference!
+interface} (@pxref{GDB/MI, , The @sc{gdb/mi} Interface}).
@item -write
@cindex @code{--write}
@end table
-@node Quitting GDB, Shell Commands, Invoking GDB, Invocation
+@node Quitting GDB
@section Quitting @value{GDBN}
@cindex exiting @value{GDBN}
@cindex leaving @value{GDBN}
@table @code
@kindex quit @r{[}@var{expression}@r{]}
-@kindex q
+@kindex q @r{(@code{quit})}
@item quit @r{[}@var{expression}@r{]}
@itemx q
To exit @value{GDBN}, use the @code{quit} command (abbreviated
device, you can release it with the @code{detach} command
(@pxref{Attach, ,Debugging an already-running process}).
-@node Shell Commands, , Quitting GDB, Invocation
+@node Shell Commands
@section Shell commands
If you need to execute occasional shell commands during your
arguments. This is equivalent to @samp{shell make @var{make-args}}.
@end table
-@node Commands, Running, Invocation, Top
+@node Commands
@chapter @value{GDBN} Commands
You can abbreviate a @value{GDBN} command to the first few letters of the command
* Help:: How to ask @value{GDBN} for help
@end menu
-@node Command Syntax, Completion, Commands, Commands
+@node Command Syntax
@section Command syntax
A @value{GDBN} command is a single line of input. There is no limit on
arguments to the @code{help} command.
@cindex repeating commands
-@kindex RET
+@kindex RET @r{(repeat last command)}
A blank line as input to @value{GDBN} (typing just @key{RET}) means to
repeat the previous command. Certain commands (for example, @code{run})
will not repeat this way; these are commands whose unintentional
@key{RET} too many in this situation, @value{GDBN} disables command
repetition after any command that generates this sort of display.
-@kindex #
+@kindex # @r{(a comment)}
@cindex comment
Any text from a @kbd{#} to the end of the line is a comment; it does
nothing. This is useful mainly in command files (@pxref{Command
Files,,Command files}).
-@node Completion, Help, Command Syntax, Commands
+@node Completion
@section Command completion
@cindex completion
@example
(@value{GDBP}) b make_ @key{TAB}
@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
-make_a_section_from_file make_environ
-make_abs_section make_function_type
-make_blockvector make_pointer_type
-make_cleanup make_reference_type
+make_a_section_from_file make_environ
+make_abs_section make_function_type
+make_blockvector make_pointer_type
+make_cleanup make_reference_type
make_command make_symbol_completion_list
(@value{GDBP}) b make_
@end example
see @ref{Debugging C plus plus, ,@value{GDBN} features for C++}.
-@node Help, , Completion, Commands
+@node Help
@section Getting help
@cindex online documentation
@kindex help
-You can always ask @value{GDBN} itself for information on its commands,
+You can always ask @value{GDBN} itself for information on its commands,
using the command @code{help}.
@table @code
-@kindex h
+@kindex h @r{(@code{help})}
@item help
@itemx h
You can use @code{help} (abbreviated @code{h}) with no arguments to
stopping the program
user-defined -- User-defined commands
-Type "help" followed by a class name for a list of
+Type "help" followed by a class name for a list of
commands in that class.
-Type "help" followed by command name for full
+Type "help" followed by command name for full
documentation.
Command name abbreviations are allowed if unambiguous.
(@value{GDBP})
show -- Generic command for showing things
about the debugger
-Type "help" followed by command name for full
+Type "help" followed by command name for full
documentation.
Command name abbreviations are allowed if unambiguous.
(@value{GDBP})
@noindent results in:
@smallexample
-@group
-set symbol-reloading -- Set dynamic symbol table reloading multiple times in one run
-show symbol-reloading -- Show dynamic symbol table reloading multiple times in one run
-@end group
+@c @group
+set symbol-reloading -- Set dynamic symbol table reloading
+ multiple times in one run
+show symbol-reloading -- Show dynamic symbol table reloading
+ multiple times in one run
+@c @end group
@end smallexample
@kindex complete
@c @group
@table @code
@kindex info
-@kindex i
+@kindex i @r{(@code{info})}
@item info
This command (abbreviated @code{i}) is for describing the state of your
program. For example, you can list the arguments given to your program
@kindex set
@item set
-You can assign the result of an expression to an environment variable with
+You can assign the result of an expression to an environment variable with
@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
@code{set prompt $}.
@kindex show
@item show
-In contrast to @code{info}, @code{show} is for describing the state of
+In contrast to @code{info}, @code{show} is for describing the state of
@value{GDBN} itself.
You can change most of the things you can @code{show}, by using the
related command @code{set}; for example, you can control what number
@end table
-@node Running, Stopping, Commands, Top
+@node Running
@chapter Running Programs Under @value{GDBN}
When you run a program under @value{GDBN}, you must first generate
* Processes:: Debugging programs with multiple processes
@end menu
-@node Compilation, Starting, Running, Running
+@node Compilation
@section Compiling for debugging
In order to debug a program effectively, you need to generate
format; if your @sc{gnu} C compiler has this option, do not use it.
@need 2000
-@node Starting, Arguments, Compilation, Running
+@node Starting
@section Starting your program
@cindex starting
@cindex running
@table @code
@kindex run
+@kindex r @r{(@code{run})}
@item run
@itemx r
Use the @code{run} command to start your program under @value{GDBN}.
table, and reads it again. When it does this, @value{GDBN} tries to retain
your current breakpoints.
-@node Arguments, Environment, Starting, Running
+@node Arguments
@section Your program's arguments
@cindex arguments (to your program)
The arguments to your program can be specified by the arguments of the
-@code{run} command.
+@code{run} command.
They are passed to a shell, which expands wildcard characters and
performs redirection of I/O, and thence to your program. Your
@code{SHELL} environment variable (if it exists) specifies what shell
@code{run} with no arguments uses the same arguments used by the previous
@code{run}, or those set by the @code{set args} command.
-@kindex set args
@table @code
+@kindex set args
@item set args
Specify the arguments to be used the next time your program is run. If
@code{set args} has no arguments, @code{run} executes your program
Show the arguments to give your program when it is started.
@end table
-@node Environment, Working Directory, Arguments, Running
+@node Environment
@section Your program's environment
@cindex environment (of your program)
files that are only run when you sign on, such as @file{.login} or
@file{.profile}.
-@node Working Directory, Input/Output, Environment, Running
+@node Working Directory
@section Your program's working directory
@cindex working directory (of your program)
Print the @value{GDBN} working directory.
@end table
-@node Input/Output, Attach, Working Directory, Running
+@node Input/Output
@section Your program's input and output
@cindex redirection
@cindex i/o
@cindex terminal
By default, the program you run under @value{GDBN} does input and output to
-the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
+the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
to its own terminal modes to interact with you, but it records the terminal
modes your program was using and switches back to them when you continue
running your program.
command, only the input @emph{for your program} is affected. The input
for @value{GDBN} still comes from your terminal.
-@node Attach, Kill Process, Input/Output, Running
+@node Attach
@section Debugging an already-running process
@kindex attach
@cindex attach
confirm} command (@pxref{Messages/Warnings, ,Optional warnings and
messages}).
-@node Kill Process, Threads, Attach, Running
+@node Kill Process
@section Killing the child process
@table @code
reads the symbol table again (while trying to preserve your current
breakpoint settings).
-@node Threads, Processes, Kill Process, Running
+@node Threads
@section Debugging programs with multiple threads
@cindex threads of execution
@item automatic notification of new threads
@item @samp{thread @var{threadno}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
+@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
@end itemize
This thread is called the @dfn{current thread}. Debugging commands show
program information from the perspective of the current thread.
-@kindex New @var{systag}
+@cindex @code{New} @var{systag} message
@cindex thread identifier (system)
@c FIXME-implementors!! It would be more helpful if the [New...] message
@c included GDB's numeric thread handle, so you could just go to that
@c program?
@c (2) *Is* there necessarily a first thread always? Or do some
@c multithread systems permit starting a program with multiple
-@c threads ab initio?
+@c threads ab initio?
@cindex thread number
@cindex thread identifier (GDB)
An asterisk @samp{*} to the left of the @value{GDBN} thread number
indicates the current thread.
-For example,
+For example,
@end table
@c end table here to get a little more width for example
number---a small integer assigned in thread-creation order---with each
thread in your program.
-@kindex New @var{systag}
-@cindex thread identifier (system)
+@cindex @code{New} @var{systag} message, on HP-UX
+@cindex thread identifier (system), on HP-UX
@c FIXME-implementors!! It would be more helpful if the [New...] message
@c included GDB's numeric thread handle, so you could just go to that
@c thread without first checking `info threads'.
@end example
@noindent
-when @value{GDBN} notices a new thread.
+when @value{GDBN} notices a new thread.
@table @code
@kindex info threads
An asterisk @samp{*} to the left of the @value{GDBN} thread number
indicates the current thread.
-For example,
+For example,
@end table
@c end table here to get a little more width for example
@example
(@value{GDBP}) info threads
- * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") at quicksort.c:137
- 2 system thread 26606 0x7b0030d8 in __ksleep () from /usr/lib/libc.2
- 1 system thread 27905 0x7b003498 in _brk () from /usr/lib/libc.2
+ * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
+ at quicksort.c:137
+ 2 system thread 26606 0x7b0030d8 in __ksleep () \@*
+ from /usr/lib/libc.2
+ 1 system thread 27905 0x7b003498 in _brk () \@*
+ from /usr/lib/libc.2
@end example
@table @code
@noindent
As with the @samp{[New @dots{}]} message, the form of the text after
@samp{Switching to} depends on your system's conventions for identifying
-threads.
+threads.
@kindex thread apply
@item thread apply [@var{threadno}] [@var{all}] @var{args}
more threads. Specify the numbers of the threads that you want affected
with the command argument @var{threadno}. @var{threadno} is the internal
@value{GDBN} thread number, as shown in the first field of the @samp{info
-threads} display. To apply a command to all threads, use
-@code{thread apply all} @var{args}.
+threads} display. To apply a command to all threads, use
+@code{thread apply all} @var{args}.
@end table
@cindex automatic thread selection
@xref{Set Watchpoints,,Setting watchpoints}, for information about
watchpoints in programs with multiple threads.
-@node Processes, , Threads, Running
+@node Processes
@section Debugging programs with multiple processes
@cindex fork, debugging programs which call
a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
Catchpoints, ,Setting catchpoints}.
-@node Stopping, Stack, Running, Top
+@node Stopping
@chapter Stopping and Continuing
The principal purposes of using a debugger are so that you can stop your
* Thread Stops:: Stopping and starting multi-thread programs
@end menu
-@node Breakpoints, Continuing and Stepping, Stopping, Stopping
+@node Breakpoints
@section Breakpoints, watchpoints, and catchpoints
@cindex breakpoints
* Error in Breakpoints:: ``Cannot insert breakpoints''
@end menu
-@node Set Breaks, Set Watchpoints, Breakpoints, Breakpoints
+@node Set Breaks
@subsection Setting breakpoints
-@c FIXME LMB what does GDB do if no code on line of breakpt?
+@c FIXME LMB what does GDB do if no code on line of breakpt?
@c consider in particular declaration with/without initialization.
@c
@c FIXME 2 is there stuff on this already? break at fun start, already init?
@kindex break
-@kindex b
-@kindex $bpnum
+@kindex b @r{(@code{break})}
+@vindex $bpnum@r{, convenience variable}
@cindex latest breakpoint
Breakpoints are set with the @code{break} command (abbreviated
-@code{b}). The debugger convenience variable @samp{$bpnum} records the
-number of the breakpoints you've set most recently; see @ref{Convenience
+@code{b}). The debugger convenience variable @samp{$bpnum} records the
+number of the breakpoint you've set most recently; see @ref{Convenience
Vars,, Convenience variables}, for a discussion of what you can do with
convenience variables.
@table @code
@item break @var{function}
-Set a breakpoint at entry to function @var{function}.
+Set a breakpoint at entry to function @var{function}.
When using source languages that permit overloading of symbols, such as
C++, @var{function} may refer to more than one possible place to break.
@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation.
@item thbreak @var{args}
Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
are the same as for the @code{hbreak} command and the breakpoint is set in
-the same way. However, like the @code{tbreak} command,
+the same way. However, like the @code{tbreak} command,
the breakpoint is automatically deleted after the
first time your program stops there. Also, like the @code{hbreak}
-command, the breakpoint requires hardware support and some target hardware
-may not have this support. @xref{Disabling, ,Disabling breakpoints}.
+command, the breakpoint requires hardware support and some target hardware
+may not have this support. @xref{Disabling, ,Disabling breakpoints}.
See also @ref{Conditions, ,Break conditions}.
@kindex rbreak
number @var{n} as argument lists only that breakpoint. The
convenience variable @code{$_} and the default examining-address for
the @code{x} command are set to the address of the last breakpoint
-listed (@pxref{Memory, ,Examining memory}).
+listed (@pxref{Memory, ,Examining memory}).
@noindent
@code{info break} displays a count of the number of times the breakpoint
@end table
-@node Set Watchpoints, Set Catchpoints, Set Breaks, Breakpoints
+@node Set Watchpoints
@subsection Setting watchpoints
@cindex setting watchpoints
watchpoints, in contrast, watch an expression in all threads.)
@end quotation
-@node Set Catchpoints, Delete Breaks, Set Watchpoints, Breakpoints
+@node Set Catchpoints
@subsection Setting catchpoints
@cindex catchpoints, setting
@cindex exception handlers
raised.
-@node Delete Breaks, Disabling, Set Catchpoints, Breakpoints
+@node Delete Breaks
@subsection Deleting breakpoints
@cindex clearing breakpoints, watchpoints, catchpoints
@cindex delete breakpoints
@kindex delete
-@kindex d
+@kindex d @r{(@code{delete})}
@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
ranges specified as arguments. If no argument is specified, delete all
confirm off}). You can abbreviate this command as @code{d}.
@end table
-@node Disabling, Conditions, Delete Breaks, Breakpoints
+@node Disabling
@subsection Disabling breakpoints
@kindex disable breakpoints
@table @code
@kindex disable breakpoints
@kindex disable
-@kindex dis
+@kindex dis @r{(@code{disable})}
@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
Disable the specified breakpoints---or all breakpoints, if none are
listed. A disabled breakpoint has no effect but is not forgotten. All
breakpoints; see @ref{Continuing and Stepping, ,Continuing and
stepping}.)
-@node Conditions, Break Commands, Disabling, Breakpoints
+@node Conditions
@subsection Break conditions
@cindex conditional breakpoints
@cindex breakpoint conditions
@c FIXME what is scope of break condition expr? Context where wanted?
-@c in particular for a watchpoint?
+@c in particular for a watchpoint?
The simplest sort of breakpoint breaks every time your program reaches a
specified place. You can also specify a @dfn{condition} for a
breakpoint. A condition is just a Boolean expression in your
Ignore counts apply to breakpoints, watchpoints, and catchpoints.
-@node Break Commands, Breakpoint Menus, Conditions, Breakpoints
+@node Break Commands
@subsection Breakpoint command lists
@cindex breakpoint commands
end
@end example
-@node Breakpoint Menus, Error in Breakpoints, Break Commands, Breakpoints
+@node Breakpoint Menus
@subsection Breakpoint menus
@cindex overloading
@cindex symbol overloading
@end smallexample
@c @ifclear BARETARGET
-@node Error in Breakpoints, , Breakpoint Menus, Breakpoints
+@node Error in Breakpoints
@subsection ``Cannot insert breakpoints''
@c
@c FIXME!! 14/6/95 Is there a real example of this? Let's use it.
@c
Under some operating systems, breakpoints cannot be used in a program if
any other process is running that program. In this situation,
-attempting to run or continue a program with a breakpoint causes
+attempting to run or continue a program with a breakpoint causes
@value{GDBN} to print an error message:
@example
Remove or disable the breakpoints, then continue.
@item
-Suspend @value{GDBN}, and copy the file containing your program to a new
+Suspend @value{GDBN}, and copy the file containing your program to a new
name. Resume @value{GDBN} and use the @code{exec-file} command to specify
-that @value{GDBN} should run your program under that name.
+that @value{GDBN} should run your program under that name.
Then start your program again.
@item
hardware-assisted breakpoints and watchpoints, and then continue.
-@node Continuing and Stepping, Signals, Breakpoints, Stopping
+@node Continuing and Stepping
@section Continuing and stepping
@cindex stepping
@table @code
@kindex continue
-@kindex c
-@kindex fg
+@kindex c @r{(@code{continue})}
+@kindex fg @r{(resume foreground execution)}
@item continue @r{[}@var{ignore-count}@r{]}
@itemx c @r{[}@var{ignore-count}@r{]}
@itemx fg @r{[}@var{ignore-count}@r{]}
@table @code
@kindex step
-@kindex s
+@kindex s @r{(@code{step})}
@item step
Continue running your program until control reaches a different source
line, then stop it and return control to @value{GDBN}. This command is
Also, the @code{step} command only enters a function if there is line
number information for the function. Otherwise it acts like the
-@code{next} command. This avoids problems when using @code{cc -gl}
+@code{next} command. This avoids problems when using @code{cc -gl}
on MIPS machines. Previously, @code{step} entered subroutines if there
-was any debugging information about the routine.
+was any debugging information about the routine.
@item step @var{count}
Continue running as in @code{step}, but do so @var{count} times. If a
@var{count} steps, stepping stops right away.
@kindex next
-@kindex n
+@kindex n @r{(@code{next})}
@item next @r{[}@var{count}@r{]}
Continue to the next source line in the current (innermost) stack frame.
This is similar to @code{step}, but function calls that appear within
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.
+switch statements, for loops, etc.
@kindex finish
@item finish
,Returning from a function}).
@kindex until
-@kindex u
+@kindex u @r{(@code{until})}
@item until
@itemx u
Continue running until a source line past the current line, in the
and hence is quicker than @code{until} without an argument.
@kindex stepi
-@kindex si
+@kindex si @r{(@code{stepi})}
@item stepi
@itemx stepi @var{arg}
@itemx si
@need 750
@kindex nexti
-@kindex ni
+@kindex ni @r{(@code{nexti})}
@item nexti
@itemx nexti @var{arg}
@itemx ni
An argument is a repeat count, as in @code{next}.
@end table
-@node Signals, Thread Stops, Continuing and Stepping, Stopping
+@node Signals
@section Signals
@cindex signals
@kindex handle
@item handle @var{signal} @var{keywords}@dots{}
-Change the way @value{GDBN} handles signal @var{signal}. @var{signal} can
+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.
@end table
execution; but your program would probably terminate immediately as
a result of the fatal signal once it saw the signal. To prevent this,
you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
-program a signal}.
+program a signal}.
-@node Thread Stops, , Signals, Stopping
+@node Thread Stops
@section Stopping and starting multi-thread programs
When your program has multiple threads (@pxref{Threads,, Debugging
@cindex threads, continuing
Conversely, whenever you restart the program, @emph{all} threads start
executing. @emph{This is true even when single-stepping} with commands
-like @code{step} or @code{next}.
+like @code{step} or @code{next}.
In particular, @value{GDBN} cannot single-step all threads in lockstep.
Since thread scheduling is up to your debugging target's operating
@end table
-@node Stack, Source, Stopping, Top
+@node Stack
@chapter Examining the Stack
When your program has stopped, the first thing you need to know is where it
stopped and how it got there.
@cindex call stack
-Each time your program performs a function call, information about the call
-is generated.
-That information includes the location of the call in your program,
-the arguments of the call,
+Each time your program performs a function call, information about the call
+is generated.
+That information includes the location of the call in your program,
+the arguments of the call,
and the local variables of the function being called.
-The information is saved in a block of data called a @dfn{stack frame}.
+The information is saved in a block of data called a @dfn{stack frame}.
The stack frames are allocated in a region of memory called the @dfn{call
stack}.
interested in. @xref{Selection, ,Selecting a frame}.
When your program stops, @value{GDBN} automatically selects the
-currently executing frame and describes it briefly, similar to the
+currently executing frame and describes it briefly, similar to the
@code{frame} command (@pxref{Frame Info, ,Information about a frame}).
@menu
@end menu
-@node Frames, Backtrace, Stack, Stack
+@node Frames
@section Stack frames
@cindex frame, definition
they are assigned by @value{GDBN} to give you a way of designating stack
frames in @value{GDBN} commands.
-@c below produces an acceptable overful hbox. --mew 13aug1993
+@c The -fomit-frame-pointer below perennially causes hbox overflow
+@c underflow problems.
@cindex frameless execution
Some compilers provide a way to compile functions so that they operate
-without stack frames. (For example, the @code{@value{GCC}} option
-@samp{-fomit-frame-pointer} generates functions without a frame.)
+without stack frames. (For example, the @value{GCC} option
+@example
+@samp{-fomit-frame-pointer}
+@end example
+generates functions without a frame.)
This is occasionally done with heavily used library functions to save
the frame setup time. @value{GDBN} has limited facilities for dealing
with these function invocations. If the innermost function invocation
@table @code
@kindex frame@r{, command}
+@cindex current stack frame
@item frame @var{args}
-The @code{frame} command allows you to move from one stack frame to another,
+The @code{frame} command allows you to move from one stack frame to another,
and to print the stack frame you select. @var{args} may be either the
-address of the frame or the stack frame number. Without an argument,
-@code{frame} prints the current stack frame.
+address of the frame or the stack frame number. Without an argument,
+@code{frame} prints the current stack frame.
@kindex select-frame
+@cindex selecting frame silently
@item select-frame
The @code{select-frame} command allows you to move from one stack frame
to another without printing the frame. This is the silent version of
@code{frame}.
@end table
-@node Backtrace, Selection, Frames, Stack
+@node Backtrace
@section Backtraces
@cindex backtraces
@table @code
@kindex backtrace
-@kindex bt
+@kindex bt @r{(@code{backtrace})}
@item backtrace
@itemx bt
Print a backtrace of the entire stack: one line per frame for all
@kindex where
@kindex info stack
-@kindex info s
+@kindex info s @r{(@code{info stack})}
The names @code{where} and @code{info stack} (abbreviated @code{info s})
are additional aliases for @code{backtrace}.
@smallexample
@group
-#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
+#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
value, indicating that your program has stopped at the beginning of the
code for line @code{993} of @code{builtin.c}.
-@node Selection, Frame Info, Backtrace, Stack
+@node Selection
@section Selecting a frame
Most commands for examining the stack and other data in your program work on
@table @code
@kindex frame@r{, selecting}
-@kindex f
+@kindex f @r{(@code{frame})}
@item frame @var{n}
@itemx f @var{n}
Select frame number @var{n}. Recall that frame zero is the innermost
that have existed longer. @var{n} defaults to one.
@kindex down
-@kindex do
+@kindex do @r{(@code{down})}
@item down @var{n}
Move @var{n} frames down the stack. For positive numbers @var{n}, this
advances toward the innermost frame, to lower frame numbers, to frames
All of these commands end by printing two lines of output describing the
frame. The first line shows the frame number, the function name, the
arguments, and the source file and line number of execution in that
-frame. The second line shows the text of that source line.
+frame. The second line shows the text of that source line.
@need 1000
For example:
distracting.
@end table
-@node Frame Info, , Selection, Stack
+@node Frame Info
@section Information about a frame
There are several other commands to print information about the selected
@xref{Selection, ,Selecting a frame}.
@kindex info frame
-@kindex info f
+@kindex info f @r{(@code{info frame})}
@item info frame
@itemx info f
This command prints a verbose description of the selected stack frame,
including:
@itemize @bullet
-@item
-the address of the frame
+@item
+the address of the frame
@item
the address of the next frame down (called by this frame)
@item
@end table
-@node Source, Data, Stack, Top
+@node Source
@chapter Examining Source Files
@value{GDBN} can print parts of your program's source, since the debugging
* Machine Code:: Source and machine code
@end menu
-@node List, Search, Source, Source
+@node List
@section Printing source lines
@kindex list
-@kindex l
+@kindex l @r{(@code{list})}
To print lines from a source file, use the @code{list} command
-(abbreviated @code{l}). By default, ten lines are printed.
+(abbreviated @code{l}). By default, ten lines are printed.
There are several ways to specify what part of the file you want to print.
Here are the forms of the @code{list} command most commonly used:
@var{address} may be any expression.
@end table
-@node Search, Source Path, List, Source
+@node Search
@section Searching source files
@cindex searching
@kindex reverse-search
@itemx search @var{regexp}
The command @samp{forward-search @var{regexp}} checks each line,
starting with the one following the last line listed, for a match for
-@var{regexp}. It lists the line that is found. You can use the
+@var{regexp}. It lists the line that is found. You can use the
synonym @samp{search @var{regexp}} or abbreviate the command name as
@code{fo}.
this command as @code{rev}.
@end table
-@node Source Path, Machine Code, Search, Source
+@node Source Path
@section Specifying source directories
@cindex source path
@kindex cdir
@kindex cwd
-@kindex $cdir
-@kindex $cwd
+@vindex $cdir@r{, convenience variable}
+@vindex $cwdr@r{, convenience variable}
@cindex compilation directory
@cindex current directory
@cindex working directory
directories in one command.
@end enumerate
-@node Machine Code, , Source Path, Source
+@node Machine Code
@section Source and machine code
You can use the command @code{info line} to map source lines to program
addresses (and vice versa), and the command @code{disassemble} to display
a range of addresses as machine instructions. When run under @sc{gnu} Emacs
mode, the @code{info line} command causes the arrow to point to the
-line specified. Also, @code{info line} prints addresses in symbolic form as
+line specified. Also, @code{info line} prints addresses in symbolic form as
well as hex.
@table @code
@end smallexample
@cindex @code{$_} and @code{info line}
-@kindex x@r{, and }@code{info line}
+@kindex x@r{(examine), and} info line
After @code{info line}, the default address for the @code{x} command
is changed to the starting address of the line, so that @samp{x/i} is
sufficient to begin examining the machine code (@pxref{Memory,
@end table
-@node Data, Languages, Source, Top
+@node Data
@chapter Examining Data
@cindex printing data
* Floating Point Hardware:: Floating point hardware
@end menu
-@node Expressions, Variables, Data, Data
+@node Expressions
@section Expressions
@cindex expressions
@value{GDBN} supports array constants in expressions input by
the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
-you can use the command @code{print @{1, 2, 3@}} to build up an array in
+you can use the command @code{print @{1, 2, 3@}} to build up an array in
memory that is @code{malloc}ed in the target program.
Because C is so widespread, most of the expressions shown in examples in
normally supposed to reside at @var{addr}.
@end table
-@node Variables, Arrays, Expressions, Data
+@node Variables
@section Program variables
The most common kind of expression to use is the name of a variable
global (or file-static)
@end itemize
-@noindent or
+@noindent or
@itemize @bullet
@item
visible according to the scope rules of the
programming language from the point of execution in that frame
-@end itemize
+@end itemize
@noindent This means that in the function
@cindex colon-colon, context for variables/functions
@iftex
@c info cannot cope with a :: index entry, but why deprive hard copy readers?
-@kindex ::
+@cindex @code{::}, context for variables/functions
@end iftex
@example
@var{file}::@var{variable}
information.
-@node Arrays, Output Formats, Variables, Data
+@node Arrays
@section Artificial arrays
@cindex artificial array
-@kindex @@
+@kindex @@@r{, referencing memory as an array}
It is often useful to print out several successive objects of the
same type in memory; a section of an array, or an array of
dynamically determined size for which only a pointer exists in the
@dots{}
@end example
-@node Output Formats, Memory, Arrays, Data
+@node Output Formats
@section Output formats
@cindex formatted output
you can use the @code{print} command with just a format and no
expression. For example, @samp{p/x} reprints the last value in hex.
-@node Memory, Auto Display, Output Formats, Data
+@node Memory
@section Examining memory
You can use the command @code{x} (for ``examine'') to examine memory in
@cindex examining memory
@table @code
-@kindex x
+@kindex x @r{(examine memory)}
@item x/@var{nfu} @var{addr}
@itemx x @var{addr}
@itemx x
are from the last memory unit printed; this is not the same as the last
address printed if several units were printed on the last line of output.
-@node Auto Display, Print Settings, Memory, Data
+@node Auto Display
@section Automatic display
@cindex automatic display
@cindex display of expressions
automatically. The next time your program stops where @code{last_char}
is meaningful, you can enable the display expression once again.
-@node Print Settings, Value History, Auto Display, Data
+@node Print Settings
@section Print settings
@cindex format options
@item set print max-symbolic-offset @var{max-offset}
Tell @value{GDBN} to only display the symbolic form of an address if the
offset between the closest earlier symbol and the address is less than
-@var{max-offset}. The default is 0, which tells @value{GDBN}
+@var{max-offset}. The default is 0, which tells @value{GDBN}
to always print the symbolic form of an address if any symbol precedes it.
@kindex show print max-symbolic-offset
@kindex set print pretty
@item set print pretty on
-Cause @value{GDBN} to print structures in an indented format with one member
+Cause @value{GDBN} to print structures in an indented format with one member
per line, like this:
@smallexample
@kindex set print union
@item set print union on
-Tell @value{GDBN} to print unions which are contained in structures. This
+Tell @value{GDBN} to print unions which are contained in structures. This
is the default setting.
@item set print union off
@smallexample
typedef enum @{Tree, Bug@} Species;
typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
-typedef enum @{Caterpillar, Cocoon, Butterfly@}
+typedef enum @{Caterpillar, Cocoon, Butterfly@}
Bug_forms;
struct thing @{
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++ compiler (@code{g++}) encoding algorithm.
This is the default.
@item hp
Show whether C++ virtual function tables are pretty printed, or not.
@end table
-@node Value History, Convenience Vars, Print Settings, Data
+@node Value History
@section Value history
@cindex value history
-Values printed by the @code{print} command are saved in the @value{GDBN}
-@dfn{value history}. This allows you to refer to them in other expressions.
-Values are kept until the symbol table is re-read or discarded
-(for example with the @code{file} or @code{symbol-file} commands).
-When the symbol table changes, the value history is discarded,
-since the values may contain pointers back to the types defined in the
+Values printed by the @code{print} command are saved in the @value{GDBN}
+@dfn{value history}. This allows you to refer to them in other expressions.
+Values are kept until the symbol table is re-read or discarded
+(for example with the @code{file} or @code{symbol-file} commands).
+When the symbol table changes, the value history is discarded,
+since the values may contain pointers back to the types defined in the
symbol table.
@cindex @code{$}
Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
same effect as @samp{show values +}.
-@node Convenience Vars, Registers, Value History, Data
+@node Convenience Vars
@section Convenience variables
@cindex convenience variables
values likely to be useful.
@table @code
-@kindex $_
+@vindex $_@r{, convenience variable}
@item $_
The variable @code{$_} is automatically set by the @code{x} command to
the last address examined (@pxref{Memory, ,Examining memory}). Other
except when set by the @code{x} command, in which case it is a pointer
to the type of @code{$__}.
-@kindex $__
+@vindex $__@r{, convenience variable}
@item $__
The variable @code{$__} is automatically set by the @code{x} command
to the value found in the last address examined. Its type is chosen
to match the format in which the data was printed.
@item $_exitcode
-@kindex $_exitcode
+@vindex $_exitcode@r{, convenience variable}
The variable @code{$_exitcode} is automatically set to the exit code when
the program being debugged terminates.
@end table
begins with a dollar sign, @value{GDBN} searches for a user or system
name first, before it searches for a convenience variable.
-@node Registers, Floating Point Hardware, Convenience Vars, Data
+@node Registers
@section Registers
@cindex registers
@item info registers @var{regname} @dots{}
Print the @dfn{relativized} value of each specified register @var{regname}.
-As discussed in detail below, register values are normally relative to
-the selected stack frame. @var{regname} may be any register name valid on
+As discussed in detail below, register values are normally relative to
+the selected stack frame. @var{regname} may be any register name valid on
the machine you are using, with or without the initial @samp{$}.
@end table
sees. For example, the registers of the 68881 floating point
coprocessor are always saved in ``extended'' (raw) format, but all C
programs expect to work with ``double'' (virtual) format. In such
-cases, @value{GDBN} normally works with the virtual format only (the format
+cases, @value{GDBN} normally works with the virtual format only (the format
that makes sense for your program), but the @code{info registers} command
prints the data in both formats.
@value{GDBN} is unable to locate the saved registers, the selected stack
frame makes no difference.
-@node Floating Point Hardware, , Registers, Data
+@node Floating Point Hardware
@section Floating point hardware
@cindex floating point
the ARM and x86 machines.
@end table
-@node Languages, Symbols, Data, Top
+@node Languages
@chapter Using @value{GDBN} with Different Languages
@cindex languages
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
+represented (and displayed) differently. Hex numbers in C appear as
@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
@cindex working language
* Support:: Supported languages
@end menu
-@node Setting, Show, Languages, Languages
+@node Setting
@section Switching between source languages
There are two ways to control the working language---either have @value{GDBN}
Displaying the language}.
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
+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
* Automatically:: Having @value{GDBN} infer the source language
@end menu
-@node Filenames, Manually, Setting, Setting
+@node Filenames
@subsection List of filename extensions and languages
If a source file name ends in one of the following extensions, then
In addition, you may set the language associated with a filename
extension. @xref{Show, , Displaying the language}.
-@node Manually, Automatically, Filenames, Setting
+@node Manually
@subsection Setting the working language
If you allow @value{GDBN} to set the language automatically,
@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
+a language, such as
@code{c} or @code{modula-2}.
For a list of the supported languages, type @samp{set language}.
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 Automatically, , Manually, Setting
+@node Automatically
@subsection Having @value{GDBN} infer the source language
To have @value{GDBN} set the working language automatically, use
a different source language. Using @samp{set language auto} in this
case frees you from having to set the working language manually.
-@node Show, Checks, Setting, Languages
+@node Show
@section Displaying the language
The following commands help you find out which language is the
build and compute expressions that may involve variables in your program.
@item info frame
-Display the source language for this frame. This language becomes the
+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
+@xref{Frame Info, ,Information about a frame}, to identify the other
information listed here.
@item info source
Display the source language of this source file.
-@xref{Symbols, ,Examining the Symbol Table}, to identify the other
+@xref{Symbols, ,Examining the Symbol Table}, to identify the other
information listed here.
@end table
List all the filename extensions and the associated languages.
@end table
-@node Checks, Support, Show, Languages
+@node Checks
@section Type and range checking
@quotation
@cindex type checking
@cindex checks, type
-@node Type Checking, Range Checking, Checks, Checks
+@node Type Checking
@subsection An overview of type checking
Some languages, such as Modula-2, are strongly typed, meaning that the
The second example fails because the @code{CARDINAL} 1 is not
type-compatible with the @code{REAL} 2.3.
-For the expressions you use in @value{GDBN} commands, you can tell the
-@value{GDBN} type checker to skip checking;
-to treat any mismatches as errors and abandon the expression;
-or to only issue warnings when type mismatches occur,
+For the expressions you use in @value{GDBN} commands, you can tell the
+@value{GDBN} type checker to skip checking;
+to treat any mismatches as errors and abandon the expression;
+or to only issue warnings when type mismatches occur,
but evaluate the expression anyway. When you choose the last of
these, @value{GDBN} evaluates expressions like the second example above, but
also issues a warning.
-Even if you turn type checking off, there may be other reasons
-related to type that prevent @value{GDBN} from evaluating an expression.
-For instance, @value{GDBN} does not know how to add an @code{int} and
-a @code{struct foo}. These particular type errors have nothing to do
-with the language in use, and usually arise from expressions, such as
+Even if you turn type checking off, there may be other reasons
+related to type that prevent @value{GDBN} from evaluating an expression.
+For instance, @value{GDBN} does not know how to add an @code{int} and
+a @code{struct foo}. These particular type errors have nothing to do
+with the language in use, and usually arise from expressions, such as
the one described above, which make little sense to evaluate anyway.
Each language defines to what degree it is strict about type. For
numbers and structures.
@item show type
-Show the current setting of the type checker, and whether or not @value{GDBN}
+Show the current setting of the type checker, and whether or not @value{GDBN}
is setting it automatically.
@end table
@cindex range checking
@cindex checks, range
-@node Range Checking, , Type Checking, Checks
+@node Range Checking
@subsection An overview of range checking
In some languages (such as Modula-2), it is an error to exceed the
being set automatically by @value{GDBN}.
@end table
-@node Support, , Checks, Languages
+@node Support
@section Supported languages
@value{GDBN} supports C, C++, Fortran, Java, Chill, assembly, and Modula-2.
* Chill:: Chill
@end menu
-@node C, Modula-2, Support, Support
+@node C
@subsection C and C++
@cindex C and C++
to both languages. Whenever this is the case, we discuss those languages
together.
-@cindex C++
-@kindex g++
+@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
* Debugging C plus plus:: @value{GDBN} features for C++
@end menu
-@node C Operators, C Constants, C, C
+@node C Operators
@subsubsection C and C++ operators
@cindex C and C++ operators
Operators must be defined on values of specific types. For instance,
@code{+} is defined on numbers, but not on structures. Operators are
-often defined on groups of types.
+often defined on groups of types.
For the purposes of C and C++, the following definitions hold:
predefined meaning.
@menu
-* C Constants::
+* C Constants::
@end menu
-@node C Constants, C plus plus expressions, C Operators, C
+@node C Constants
@subsubsection C and C++ constants
@cindex C and C++ constants
@end itemize
@menu
-* C plus plus expressions::
-* C Defaults::
-* C Checks::
+* C plus plus expressions::
+* C Defaults::
+* C Checks::
-* Debugging C::
+* Debugging C::
@end menu
-@node C plus plus expressions, C Defaults, C Constants, C
+@node C plus plus expressions
@subsubsection C++ expressions
@cindex expressions in C++
count = aml->GetOriginal(x, y)
@end example
-@kindex this
+@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
@cindex reference declarations
@item
-@value{GDBN} understands variables declared as C++ references; you can use
+@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.
objects, calling functions in a base subobject, casting objects, and
invoking user-defined operators.
-@node C Defaults, C Checks, C plus plus expressions, C
+@node C Defaults
@subsubsection C and C++ defaults
@cindex C and C++ defaults
@c unimplemented. If (b) changes, it might make sense to let this node
@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
-@node C Checks, Debugging C, C Defaults, C
+@node C Checks
@subsubsection C and C++ type and range checks
@cindex C and C++ checks
indices are not checked, since they are often used to index a pointer
that is not itself an array.
-@node Debugging C, Debugging C plus plus, C Checks, C
+@node Debugging C
@subsubsection @value{GDBN} and C
The @code{set print union} and @code{show print union} commands apply to
,Expressions}.
@menu
-* Debugging C plus plus::
+* Debugging C plus plus::
@end menu
-@node Debugging C plus plus, , Debugging C, C
+@node Debugging C plus plus
@subsubsection @value{GDBN} features for C++
@cindex commands for C++
@xref{Completion,, Command completion}, for details on how to do this.
@end table
-@node Modula-2, Chill, C, Support
+@node Modula-2
@subsection Modula-2
@cindex Modula-2, @value{GDBN} support
* GDB/M2:: @value{GDBN} and Modula-2
@end menu
-@node M2 Operators, Built-In Func/Proc, Modula-2, Modula-2
+@node M2 Operators
@subsubsection Operators
@cindex Modula-2 operators
@end quotation
@cindex Modula-2 built-ins
-@node Built-In Func/Proc, M2 Constants, M2 Operators, Modula-2
+@node Built-In Func/Proc
@subsubsection Built-in functions and procedures
Modula-2 also makes available several built-in procedures and functions.
@end quotation
@cindex Modula-2 constants
-@node M2 Constants, M2 Defaults, Built-In Func/Proc, Modula-2
+@node M2 Constants
@subsubsection Constants
@value{GDBN} allows you to express the constants of Modula-2 in the following
Set constants are not yet supported.
@end itemize
-@node M2 Defaults, Deviations, M2 Constants, Modula-2
+@node M2 Defaults
@subsubsection Modula-2 defaults
@cindex Modula-2 defaults
working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
the language automatically}, for further details.
-@node Deviations, M2 Checks, M2 Defaults, Modula-2
+@node Deviations
@subsubsection Deviations from standard Modula-2
@cindex Modula-2, deviations from
All built-in procedures both modify @emph{and} return their argument.
@end itemize
-@node M2 Checks, M2 Scope, Deviations, Modula-2
+@node M2 Checks
@subsubsection Modula-2 type and range checks
@cindex Modula-2 checks
Range checking is done on all mathematical operations, assignment, array
index bounds, and all built-in functions and procedures.
-@node M2 Scope, GDB/M2, M2 Checks, Modula-2
+@node M2 Scope
@subsubsection The scope operators @code{::} and @code{.}
@cindex scope
-@kindex .
+@cindex @code{.}, Modula-2 scope operator
@cindex colon, doubled as scope operator
@ifinfo
-@kindex colon-colon@r{, in Modula-2}
+@vindex colon-colon@r{, in Modula-2}
@c Info cannot handle :: but TeX can.
@end ifinfo
@iftex
-@kindex ::
+@vindex ::@r{, in Modula-2}
@end iftex
There are a few subtle differences between the Modula-2 scope operator
module @var{module}, or if @var{id} is not an identifier in
@var{module}.
-@node GDB/M2, , M2 Scope, Modula-2
+@node GDB/M2
@subsubsection @value{GDBN} and Modula-2
Some @value{GDBN} commands have little use when debugging Modula-2 programs.
In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
interpreted as the beginning of a comment. Use @code{<>} instead.
-@node Chill, , Modula-2, Support
+@node Chill
@subsection Chill
The extensions made to @value{GDBN} to support Chill only support output
* 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 type and range checks::
* Chill defaults::
@end menu
-@node How modes are displayed, Locations, Chill, Chill
+@node How modes are displayed
@subsubsection How modes are displayed
The Chill Datatype- (Mode) support of @value{GDBN} is directly related
@emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT,
UINT, LONG, ULONG},
@item
-@emph{Boolean Mode} which is predefined by @code{BOOL},
+@emph{Boolean Mode} which is predefined by @code{BOOL},
@item
-@emph{Character Mode} which is predefined by @code{CHAR},
+@emph{Character Mode} which is predefined by @code{CHAR},
@item
@emph{Set Mode} which is displayed by the keyword @code{SET}.
@smallexample
@end smallexample
If the type is an unnumbered set the set element values are omitted.
@item
-@emph{Range Mode} which is displayed by @code{type = <basemode>
-(<lower bound> : <upper bound>)}, where @code{<lower bound>, <upper
-bound>} can be of any discrete literal expression (e.g. set element
-names).
+@emph{Range Mode} which is displayed by
+@smallexample
+@code{type = <basemode>(<lower bound> : <upper bound>)}
+@end smallexample
+where @code{<lower bound>, <upper bound>} can be of any discrete literal
+expression (e.g. set element names).
@end itemize
@item @r{@emph{Powerset Mode:}}
@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.
+type, and is therefore not really of interest.
@end ignore
-@item @r{@emph{Synchronization Modes:}}
+@item @r{@emph{Synchronization Modes:}}
@itemize @bullet
@item
-@emph{Event Mode} which is displayed by @code{EVENT (<event length>)},
+@emph{Event Mode} which is displayed by
+@smallexample
+@code{EVENT (<event length>)}
+@end smallexample
where @code{(<event length>)} is optional.
@item
-@emph{Buffer Mode} which is displayed by @code{BUFFER (<buffer length>)
-<buffer element mode>}, where @code{(<buffer length>)} is optional.
+@emph{Buffer Mode} which is displayed by
+@smallexample
+@code{BUFFER (<buffer length>)<buffer element mode>}
+@end smallexample
+where @code{(<buffer length>)} is optional.
@end itemize
-@item @r{@emph{Timing Modes:}}
+@item @r{@emph{Timing Modes:}}
@itemize @bullet
@item
@emph{Duration Mode} which is predefined by @code{DURATION}
@item @r{@emph{String Modes:}}
@itemize @bullet
@item
-@emph{Character String Mode} which is displayed by @code{CHARS(<string
-length>)}, followed by the keyword @code{VARYING} if the String Mode is
-a varying mode
+@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 @code{BOOLS(<string
-length>)}.
+@emph{Bit String Mode} which is displayed by
+@smallexample
+@code{BOOLS(<string
+length>)}
+@end smallexample
@end itemize
@item @r{@emph{Array Mode:}}
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)
+type = ARRAY (1:42)
+ ARRAY (1:20)
SET (karli = 10, susi = 20, fritzi = 100)
@end smallexample
-@item @r{@emph{Structure Mode}}
+@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>
@end smallexample
@end table
-@node Locations, Values and their Operations, How modes are displayed, Chill
+@node Locations
@subsubsection Locations and their accesses
A location in Chill is an object which can contain values.
value of the location referenced by the pointer, use the dereference
operator @samp{->}.
-Values of procedure mode locations are displayed by @code{@{ PROC
+Values of procedure mode locations are displayed by
+@smallexample
+@code{@{ PROC
(<argument modes> ) <return mode> @} <address> <name of procedure
-location>}. @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.
+location>}
+@end smallexample
+@code{<argument modes>} is a list of modes according to the parameter
+specification of the procedure and @code{<address>} shows the address of
+the entry point.
@ignore
Locations of instance modes are displayed just like a structure with two
(@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX
@end smallexample
-@node Values and their Operations, Chill type and range checks, Locations, Chill
+@node Values and their Operations
@subsubsection Values and their Operations
Values are used to alter locations, to investigate complex structures in
@c FIXME: if the Chill Manual is a Texinfo documents, the above should
@c be converted to a @ref.
-@ignore
+@ignore
@itemize @bullet
@item
@emph{Integer Literals} are specified in the same manner as in Chill
@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.
+procedure value or the empty instance value.
@item
@emph{Character String Literals} are defined by a sequence of characters
@end itemize
@item String Element Value
-A string element value is specified by @code{<string value>(<index>)},
+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.
Values of duration mode locations are represented by @code{ULONG} literals.
-Values of time mode locations are represented by @code{TIME(<secs>:<nsecs>)}.
+Values of time mode locations appear as
+@smallexample
+@code{TIME(<secs>:<nsecs>)}
+@end smallexample
+
@ignore
This is not implemented yet:
@end table
@end table
-@node Chill type and range checks, Chill defaults, Values and their Operations, Chill
+@node Chill type and range checks
@subsubsection Chill type and range checks
@value{GDBN} considers two Chill variables mode equivalent if the sizes
All checks can be disabled by the @value{GDBN} command @code{set check
off}.
-@ignore
+@ignore
@c Deviations from the Chill Standard Z200/88
see last paragraph ?
@end ignore
-@node Chill defaults, , Chill type and range checks, Chill
+@node Chill defaults
@subsubsection Chill defaults
If type and range checking are set automatically by @value{GDBN}, they
working language to Chill. @xref{Automatically, ,Having @value{GDBN} set
the language automatically}, for further details.
-@node Symbols, Altering, Languages, Top
+@node Symbols
@chapter Examining the Symbol Table
The commands described in this chapter allow you to inquire about the
object file with a particular name is seen again.
@item set symbol-reloading off
-Do not replace symbol definitions when re-encountering object files of
-the same name. This is the default state; if you are not running on a
-system that permits automatically relinking modules, you should leave
-@code{symbol-reloading} off, since otherwise @value{GDBN} may discard symbols
-when linking large programs, that may contain several modules (from
-different directories or libraries) with the same name.
+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
@value{GDBN} reads symbols (in the description of @code{symbol-file}).
@end table
-@node Altering, GDB Files, Symbols, Top
+@node Altering
@chapter Altering Execution
Once you think you have found an error in your program, you might want to
* Patching:: Patching your program
@end menu
-@node Assignment, Jumping, Altering, Altering
+@node Assignment
@section Assignment to variables
@cindex assignment
@noindent
stores the value 4 into the variable @code{x}, and then prints the
-value of the assignment expression (which is 4).
+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 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.
+"/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
@noindent
stores the value 4 into that memory location.
-@node Jumping, Signaling, Assignment, Altering
+@node Jumping
@section Continuing at a different address
Ordinarily, when you continue your program, you do so at the place where
detail.
@c @group
-@node Signaling, Returning, Jumping, Altering
+@node Signaling
@section Giving your program a signal
@table @code
passes the signal directly to your program.
-@node Returning, Calling, Signaling, Altering
+@node Returning
@section Returning from a function
@table @code
and Stepping, ,Continuing and stepping}) resumes execution until the
selected stack frame returns naturally.
-@node Calling, Patching, Returning, Altering
+@node Calling
@section Calling program functions
@cindex calling functions
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.
+with @code{void} returned values. If the result is not void, it
+is printed and saved in the value history.
For the A29K, a user-controlled variable @code{call_scratch_address},
specifies the location of a scratch area to be used when @value{GDBN}
method of putting the scratch area on the stack does not work in systems
that have separate instruction and data spaces.
-@node Patching, , Calling, Altering
+@node Patching
@section Patching programs
@cindex patching binaries
as well as reading.
@end table
-@node GDB Files, Targets, Altering, Top
+@node GDB Files
@chapter @value{GDBN} Files
@value{GDBN} needs to know the file name of the program to be debugged,
* Symbol Errors:: Errors reading symbol files
@end menu
-@node Files, Symbol Errors, GDB Files, GDB Files
+@node Files
@section Commands to specify files
@cindex symbol table
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}
+directory and the file is not found in the @value{GDBN} working directory,
+@value{GDBN} uses the environment variable @code{PATH} as a list of
+directories to search, just as the shell does when looking for a program
+to run. You can change the value of this variable, for both @value{GDBN}
and your program, using the @code{path} command.
-On systems with memory-mapped files, an auxiliary file
+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),
+@code{symbol-file}, or @code{add-symbol-file}, described below),
for more information.
@item file
@code{symbol-file} with no argument clears out @value{GDBN} information on your
program's symbol table.
-The @code{symbol-file} command causes @value{GDBN} to forget the contents
+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
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.
+entire symbol table available.
If memory-mapped files are available on your system through the
@code{mmap} system call, you can use another option, @samp{-mapped}, to
@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} @var{address} @var{data_address} @var{bss_address}
-@itemx add-symbol-file @var{filename} @r{-T}@var{section} @var{address}
+@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 specify up to three addresses, in which
-case they are taken to be the addresses of the text, data, and bss
-segments respectively. For complicated cases, you can specify an
-arbitrary number of @samp{@r{-T}@var{section} @var{address}} pairs, to
-give an explicit section name and base address for that section. You
-can specify any @var{address} as an expression.
+this out for itself. You can additionally specify an arbitrary number
+of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit
+section name and base address for that section. You can specify any
+@var{address} as an expression.
The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command. You can use the
@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
+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
+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.
Display the current autoloading size threshold, in megabytes.
@end table
-@node Symbol Errors, , Files, GDB Files
+@node Symbol Errors
@section Errors reading symbol files
While reading a symbol file, @value{GDBN} occasionally encounters problems,
@end table
-@node Targets, Configurations, GDB Files, Top
+@node Targets
@chapter Specifying a Debugging Target
@cindex debugging target
@end menu
-@node Active Targets, Target Commands, Targets, Targets
+@node Active Targets
@section Active targets
@cindex stacking targets
the @code{attach} command (@pxref{Attach, ,Debugging an already-running
process}).
-@node Target Commands, Byte Order, Active Targets, Targets
+@node Target Commands
@section Commands for managing targets
@table @code
@kindex set gnutarget
@item set gnutarget @var{args}
-@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
+@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,
+a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
+with the @code{set gnutarget} command. Unlike most @code{target} commands,
with @code{gnutarget} the @code{target} refers to a program, not a machine.
@quotation
@noindent
@xref{Files, , Commands to specify files}.
-@kindex show gnutarget
+@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},
@end table
-Different targets are available on different configurations of @value{GDBN};
+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
@code{load} does not repeat if you press @key{RET} again after using it.
@end table
-@node Byte Order, Remote, Target Commands, Targets
+@node Byte Order
@section Choosing target byte order
@cindex choosing target byte order
@cindex target byte order
-@kindex set endian big
-@kindex set endian little
-@kindex set endian auto
-@kindex show endian
Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
offer the ability to run either big-endian or little-endian byte
data on the host, and that they have absolutely no effect on the
target system.
-@node Remote, KOD, Byte Order, Targets
+@node Remote
@section Remote debugging
@cindex remote debugging
If you are trying to debug a program running on a machine that cannot run
-@value{GDBN} in the usual way, it is often useful to use remote debugging.
-For example, you might use remote debugging on an operating system kernel,
+@value{GDBN} in the usual way, it is often useful to use remote debugging.
+For example, you might use remote debugging on an operating system kernel,
or on a small system which does not have a general purpose operating system
powerful enough to run a full-featured debugger.
Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
to make this work with particular debugging targets. In addition,
-@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
+@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}.
* Remote Serial:: @value{GDBN} remote serial protocol
@end menu
-@node Remote Serial, , Remote, Remote
+@node Remote Serial
@subsection The @value{GDBN} remote serial protocol
@cindex remote serial debugging, overview
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
+@item
A C subroutine library to support your program's
subroutine calls, notably managing input and output.
@table @code
@item i386-stub.c
-@kindex i386-stub.c
+@cindex @file{i386-stub.c}
@cindex Intel
@cindex i386
For Intel 386 and compatible architectures.
@item m68k-stub.c
-@kindex m68k-stub.c
+@cindex @file{m68k-stub.c}
@cindex Motorola 680x0
@cindex m680x0
For Motorola 680x0 architectures.
@item sh-stub.c
-@kindex sh-stub.c
+@cindex @file{sh-stub.c}
@cindex Hitachi
@cindex SH
For Hitachi SH architectures.
@item sparc-stub.c
-@kindex sparc-stub.c
+@cindex @file{sparc-stub.c}
@cindex Sparc
For @sc{sparc} architectures.
@item sparcl-stub.c
-@kindex sparcl-stub.c
+@cindex @file{sparcl-stub.c}
@cindex Fujitsu
@cindex SparcLite
For Fujitsu @sc{sparclite} architectures.
* NetWare:: Using the `gdbserve.nlm' program
@end menu
-@node Stub Contents, Bootstrapping, Remote Serial, Remote Serial
+@node Stub Contents
@subsubsection What the stub can do for you
@cindex remote serial stub
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.
+machine.
@item breakpoint
@cindex @code{breakpoint} subroutine, remote
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.
+@value{GDBN} session gets control.
Call @code{breakpoint} if none of these is true, or if you simply want
to make certain your program stops at a predetermined point for the
start of your debugging session.
@end table
-@node Bootstrapping, Debug Session, Stub Contents, Remote Serial
+@node Bootstrapping
@subsubsection What you must do for the stub
@cindex remote stub, support routines
@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
+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
subroutines which @code{@value{GCC}} generates as inline code.
-@node Debug Session, Protocol, Bootstrapping, Remote Serial
+@node Debug Session
@subsubsection Putting it all together
@cindex remote serial debugging summary
@enumerate
@item
-Make sure you have the supporting low-level routines
+Make sure you have defined the supporting low-level routines
(@pxref{Bootstrapping,,What you must do for the stub}):
@display
@code{getDebugChar}, @code{putDebugChar},
@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
+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.
remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
goes back to waiting.
-@node Protocol, Server, Debug Session, Remote Serial
+@node Protocol
@subsubsection Communication protocol
@cindex debugging stub, example
@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{$}, this is followed by an optional two-digit
-@var{sequence-id} and the character @samp{:}, the actual
-@var{packet-data}, and the terminating character @samp{#} followed by a
-two-digit @var{checksum}:
+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
-or, with the optional @var{sequence-id}:
-@example
-@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
-@end example
@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{#} (that
-consisting of both the optional @var{sequence-id}@code{:} and the actual
-@var{packet-data}) (an eight bit unsigned checksum).
+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
-The two-digit @var{sequence-id}, when present, is returned with the
-acknowledgment. Beyond that its meaning is poorly defined.
-@value{GDBN} is not known to output @var{sequence-id}s.
+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
-> @code{+}
@end example
@noindent
-If the received packet included a @var{sequence-id} than that is
-appended to a positive acknowledgment:
-
-@example
-<- @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
--> @code{+}@var{sequence-id}
-@end example
The host (@value{GDBN}) sends @var{command}s, and the target (the
debugging stub incorporated in your program) sends a @var{response}. In
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 an
-exception). @samp{:} can not appear as the third character in a packet.
-Fields within the packet should be separated using @samp{,} and @samp{;}
-(unfortunately some packets chose to use @samp{:}). Except where
-otherwise noted all numbers are represented in HEX with leading zeros
-suppressed.
+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
@noindent
means the same as "0000".
-The error response, returned for some packets includes a two character
+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
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 ops @emph{(optional)}
+@item extended ops
@tab @code{!}
@tab
Use the extended remote protocol. Sticky---only needs to be set once.
-The extended remote protocol support the @samp{R} packet.
+The extended remote protocol supports the @samp{R} packet.
@item
@tab reply @samp{}
@tab
@item reserved
@tab @code{a}
-@tab Reserved for future use
+@tab Reserved for future use
-@item set program arguments @strong{(reserved)} @emph{(optional)}
+@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.
@tab reply
@tab see below
-@item continue with signal @emph{(optional)}
+@item continue with signal
@tab @code{C}@var{sig}@code{;}@var{addr}
@tab
Continue with signal @var{sig} (hex signal number). If
@tab reply
@tab see below
-@item toggle debug @emph{(deprecated)}
+@item toggle debug @strong{(deprecated)}
@tab @code{d}
@tab
toggle debug flag.
-@item detach @emph{(optional)}
+@item detach
@tab @code{D}
@tab
Detach @value{GDBN} from the remote system. Sent to the remote target before
@item
@tab reply @emph{no response}
@tab
-@value{GDBN} does not check for any response after sending this packet
+@value{GDBN} does not check for any response after sending this packet.
@item reserved
@tab @code{e}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{E}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{f}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{F}
-@tab Reserved for future use
+@tab Reserved for future use
@item read registers
@tab @code{g}
@item reserved
@tab @code{h}
-@tab Reserved for future use
+@tab Reserved for future use
-@item set thread @emph{(optional)}
+@item set thread
@tab @code{H}@var{c}@var{t...}
@tab
Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
@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 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 selected, sets the registers of the register block of
@c that thread; otherwise sets current registers.
-@item cycle step @strong{(draft)} @emph{(optional)}
+@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)} @emph{(optional)}
+@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
+@tab Reserved for future use
-@item kill request @emph{(optional)}
+@item kill request
@tab @code{k}
@tab
FIXME: @emph{There is no description of how operate when a specific
@item reserved
@tab @code{l}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{L}
-@tab Reserved for future use
+@tab Reserved for future use
@item read memory
@tab @code{m}@var{addr}@code{,}@var{length}
@item reserved
@tab @code{n}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{N}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{o}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{O}
-@tab Reserved for future use
+@tab Reserved for future use
@item read reg @strong{(reserved)}
@tab @code{p}@var{n...}
@tab return @var{r....}
@tab The hex encoded value of the register in target byte order.
-@item write reg @emph{(optional)}
+@item write reg
@tab @code{P}@var{n...}@code{=}@var{r...}
@tab
Write register @var{n...} with value @var{r...}, which contains two hex
@tab reply @code{E}@var{NN}
@tab for an error
-@item general query @emph{(optional)}
+@item general query
@tab @code{q}@var{query}
@tab
-Request info about @var{query}. In general @value{GDBN} @var{query}'s
+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
@tab reply @samp{}
@tab Indicating an unrecognized @var{query}.
-@item general set @emph{(optional)}
+@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 @emph{(deprecated)}
+@item reset @strong{(deprecated)}
@tab @code{r}
@tab
Reset the entire system.
-@item remote restart @emph{(optional)}
+@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}.
-@item step @emph{(optional)}
+@item step
@tab @code{s}@var{addr}
@tab
@var{addr} is address to resume. If @var{addr} is omitted, resume at
@tab reply
@tab see below
-@item step with signal @emph{(optional)}
+@item step with signal
@tab @code{S}@var{sig}@code{;}@var{addr}
@tab
Like @samp{C} but step not continue.
@tab reply
@tab see below
-@item search @emph{(optional)}
+@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 @emph{(optional)}
+@item thread alive
@tab @code{T}@var{XX}
@tab Find out if the thread XX is alive.
@item
@item
@tab reply @code{E}@var{NN}
@tab thread is dead
-
+
@item reserved
@tab @code{u}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{U}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{v}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{V}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{w}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{W}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{x}
-@tab Reserved for future use
+@tab Reserved for future use
-@item write mem (binary) @emph{(optional)}
+@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
@item reserved
@tab @code{y}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{Y}
-@tab Reserved for future use
+@tab Reserved for future use
-@item remove break or watchpoint @strong{(draft)} @emph{(optional)}
+@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)} @emph{(optional)}
+@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
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 ident-potentent way.
+implemented in an idempotent way.
@item
@tab reply @code{E}@var{NN}
@tab for an error
@item reserved
@tab <other>
-@tab Reserved for future use
+@tab Reserved for future use
@end multitable
@tab
The process terminated with signal @var{AA}.
-@item @code{N}@var{AA}@code{;}@var{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb} @strong{(obsolete)}
+@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)}
@tab
-@var{AA} = signal number; @var{tttttttt} = address of symbol "_start";
-@var{dddddddd} = base of data section; @var{bbbbbbbb} = 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.}
+@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
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
+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 reply @code{m}@var{<id>}
@tab A single thread id
@item
-@tab reply @code{m}@var{<id>,}@var{<id>...}
+@tab reply @code{m}@var{<id>},@var{<id>...}
@tab a comma-separated list of thread ids
@item
@tab reply @code{l}
(lower-case el, for @code{'last'}).
@item extra thread info
-@tab @code{qfThreadExtraInfo,}@var{<id>}
+@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id}
@tab
@item
@tab
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
+Some examples of possible thread extra info strings are "Runnable", or
"Blocked on Mutex".
@item
@tab reply @var{XX...}
@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
@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
<- @code{+}
@end example
-@kindex set remotedebug@r{, serial protocol}
-@kindex show remotedebug@r{, serial protocol}
-@cindex packets, reporting on stdout
-@cindex serial connections, debugging
-If you have trouble with the serial connection, you can use the command
-@code{set remotedebug}. This makes @value{GDBN} report on all packets sent
-back and forth across the serial line to the remote machine. The
-packet-debugging information is printed on the @value{GDBN} standard output
-stream. @code{set remotedebug off} turns it off, and @code{show
-remotedebug} shows you its current state.
-
-@node Server, NetWare, Protocol, Remote Serial
+@node Server
@subsubsection Using the @code{gdbserver} program
@kindex gdbserver
@samp{Connection refused}.
@end table
-@node NetWare, , Server, Remote Serial
+@node NetWare
@subsubsection Using the @code{gdbserve.nlm} program
@kindex gdbserve.nlm
@value{GDBN}; the name of your program; and the arguments for your
program. The syntax is:
-@smallexample
+@smallexample
load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
[ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
@end smallexample
to 0, @var{baud} defaults to 9600@dmn{bps}.
For example, to debug Emacs with the argument @samp{foo.txt}and
-communicate with @value{GDBN} over serial port number 2 or board 1
+communicate with @value{GDBN} over serial port number 2 or board 1
using a 19200@dmn{bps} connection:
@smallexample
communications with the server via serial line @file{/dev/ttyb}.
@end table
-@node KOD, , Remote, Targets
+@node KOD
@section Kernel Object Display
@cindex kernel object display
is supported other than to try it.
-@node Configurations, Controlling GDB, Targets, Top
+@node Configurations
@chapter Configuration-Specific Information
While nearly all @value{GDBN} commands are available for all native and
* Architectures::
@end menu
-@node Native, Embedded OS, Configurations, Configurations
+@node Native
@section Native
This section describes details specific to particular native
* SVR4 Process Information:: SVR4 process information
@end menu
-@node HP-UX, SVR4 Process Information, Native, Native
+@node HP-UX
@subsection HP-UX
On HP-UX systems, if you refer to a function or variable name that
begins with a dollar sign, @value{GDBN} searches for a user or system
name first, before it searches for a convenience variable.
-@node SVR4 Process Information, , HP-UX, Native
+@node SVR4 Process Information
@subsection SVR4 process information
@kindex /proc
Show all the above information about the process.
@end table
-@node Embedded OS, Embedded Processors, Native, Configurations
+@node Embedded OS
@section Embedded Operating Systems
This section describes configurations involving the debugging of
@value{GDBN} includes the ability to debug programs running on
various real-time operating systems.
-@node VxWorks, , Embedded OS, Embedded OS
+@node VxWorks
@subsection Using @value{GDBN} with VxWorks
@cindex VxWorks
@table @code
@item VxWorks-timeout @var{args}
@kindex vxworks-timeout
-All VxWorks-based targets now support the option @code{vxworks-timeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses to rpc's. You might use this if
-your VxWorks target is a slow software simulator or is on the far side
+All VxWorks-based targets now support the option @code{vxworks-timeout}.
+This option is set by the user, and @var{args} represents the number of
+seconds @value{GDBN} waits for responses to rpc's. You might use this if
+your VxWorks target is a slow software simulator or is on the far side
of a thin network line.
@end table
* VxWorks Attach:: Running tasks
@end menu
-@node VxWorks Connection, VxWorks Download, VxWorks, VxWorks
+@node VxWorks Connection
@subsubsection Connecting to VxWorks
The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
@value{GDBN} displays messages like these:
@smallexample
-Attaching remote machine across net...
+Attaching remote machine across net...
Connected to tt.
@end smallexample
the @value{GDBN} command @code{path}, and execute the @code{target}
command again.
-@node VxWorks Download, VxWorks Attach, VxWorks Connection, VxWorks
+@node VxWorks Download
@subsubsection VxWorks download
@cindex download to VxWorks
Then, in @value{GDBN}, type:
@example
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
+(vxgdb) cd @var{hostpath}/vw/demo/rdb
(vxgdb) load prog.o
@end example
debugger's data structures that reference the target system's symbol
table.)
-@node VxWorks Attach, , VxWorks Download, VxWorks
+@node VxWorks Attach
@subsubsection Running tasks
@cindex running VxWorks tasks
or suspended when you attach to it. Running tasks are suspended at
the time of attachment.
-@node Embedded Processors, Architectures, Embedded OS, Configurations
+@node Embedded Processors
@section Embedded Processors
This section goes into details specific to particular embedded
* Z8000:: Zilog Z8000
@end menu
-@node A29K Embedded, ARM, Embedded Processors, Embedded Processors
+@node A29K Embedded
@subsection AMD A29K Embedded
@menu
@end table
-@node A29K UDI, A29K EB29K, A29K Embedded, A29K Embedded
+@node A29K UDI
@subsubsection A29K UDI
@cindex UDI
to its pathname.
@end table
-@node A29K EB29K, Comms (EB29K), A29K UDI, A29K Embedded
+@node A29K EB29K
@subsubsection EBMON protocol for AMD29K
@cindex EB29K board
assume you've hooked the cable between the PC's @file{COM1} port and
@file{/dev/ttya} on the Unix system.
-@node Comms (EB29K), gdb-EB29K, A29K EB29K, A29K Embedded
+@node Comms (EB29K)
@subsubsection Communications setup
The next step is to set up the PC's port, by doing something like this
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 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
from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
serial line.
-@node gdb-EB29K, Remote Log, Comms (EB29K), A29K Embedded
+@node gdb-EB29K
@subsubsection EB29K cross-debugging
Finally, @code{cd} to the directory containing an image of your 29K
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, , gdb-EB29K, A29K Embedded
+@node Remote Log
@subsubsection Remote log
-@kindex eb.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
another window often helps to understand trouble with @code{EBMON}, or
unexpected events on the PC side of the connection.
-@node ARM, H8/300, A29K Embedded, Embedded Processors
+@node ARM
@subsection ARM
@table @code
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, H8/500, ARM, Embedded Processors
+@node H8/300
@subsection Hitachi H8/300
@table @code
@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:
+Hitachi SH, H8/300, or H8/500:
@enumerate
@item
* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
@end menu
-@node Hitachi Boards, Hitachi ICE, H8/300, H8/300
+@node Hitachi Boards
@subsubsection Connecting to Hitachi boards
@c only for Unix hosts
@smallexample
(eg-C:\H8300\TEST) @value{GDBP} t.x
@value{GDBN} is free software and you are welcome to distribute copies
- of it under certain conditions; type "show copying" to see
+ of it under certain conditions; type "show copying" to see
the conditions.
-There is absolutely no warranty for @value{GDBN}; type "show warranty"
+There is absolutely no warranty for @value{GDBN}; type "show warranty"
for details.
@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
(@value{GDBP}) target hms
In either case, @value{GDBN} sees the effect of a @sc{reset} on the
development board as a ``normal exit'' of your program.
-@node Hitachi ICE, Hitachi Special, Hitachi Boards, H8/300
+@node Hitachi ICE
@subsubsection Using the E7000 in-circuit emulator
@kindex target e7000@r{, with Hitachi ICE}
specify its hostname; @value{GDBN} uses @code{telnet} to connect.
@end table
-@node Hitachi Special, , Hitachi ICE, H8/300
+@node Hitachi Special
@subsubsection Special @value{GDBN} commands for Hitachi micros
Some @value{GDBN} commands are available only for the H8/300:
@end table
-@node H8/500, i960, H8/300, Embedded Processors
+@node H8/500
@subsection H8/500
@table @code
@end table
-@node i960, M32R/D, H8/500, Embedded Processors
+@node i960
@subsection Intel i960
@table @code
@item target mon960 @var{dev}
MON960 monitor for Intel i960.
+@kindex target nindy
@item target nindy @var{devicename}
An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
the name of the serial device to use for the connection, e.g.
By using the @code{target} command at any point during your @value{GDBN}
session. @xref{Target Commands, ,Commands for managing targets}.
-@kindex target nindy
-@item target nindy @var{devicename}
-An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
-the name of the serial device to use for the connection, e.g.
-@file{/dev/ttya}.
-
@end itemize
@cindex download to Nindy-960
* Nindy Reset:: Nindy reset command
@end menu
-@node Nindy Startup, Nindy Options, i960, i960
+@node Nindy Startup
@subsubsection Startup with Nindy
If you simply start @code{@value{GDBP}} without using any command-line
reach the ordinary @value{GDBN} prompt:
@example
-Attach /dev/ttyNN -- specify NN, or "quit" to quit:
+Attach /dev/ttyNN -- specify NN, or "quit" to quit:
@end example
@noindent
with an empty line. If you do this and later wish to attach to Nindy,
use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
-@node Nindy Options, Nindy Reset, Nindy Startup, i960
+@node Nindy Options
@subsubsection Options for Nindy
These are the startup options for beginning your @value{GDBN} session with a
port.
@c @group
-@node Nindy Reset, , Nindy Options, i960
+@node Nindy Reset
@subsubsection Nindy reset command
@table @code
@end table
@c @end group
-@node M32R/D, M68K, i960, Embedded Processors
+@node M32R/D
@subsection Mitsubishi M32R/D
@table @code
@end table
-@node M68K, M88K, M32R/D, Embedded Processors
+@node M68K
@subsection M68k
The Motorola m68k configuration includes ColdFire support, and
@end table
-@node M88K, MIPS Embedded, M68K, Embedded Processors
+@node M88K
@subsection M88K
@table @code
@end table
-@node MIPS Embedded, PowerPC, M88K, Embedded Processors
+@node MIPS Embedded
@subsection MIPS Embedded
@cindex MIPS boards
@kindex show processor
Use the @code{set processor} command to set the type of MIPS
processor when you want to access processor-type-specific registers.
-For example, @code{set processor @var{r3041}} tells @value{GDBN}
+For example, @code{set processor @var{r3041}} tells @value{GDBN}
to use the CPO registers appropriate for the 3041 chip.
-Use the @code{show processor} command to see what MIPS processor @value{GDBN}
+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.
+@value{GDBN} is using.
@item set mipsfpu double
@itemx set mipsfpu single
to run before stopping.
@end table
-@node PowerPC, PA, MIPS Embedded, Embedded Processors
+@node PowerPC
@subsection PowerPC
@table @code
@end table
-@node PA, SH, PowerPC, Embedded Processors
+@node PA
@subsection HP PA Embedded
@table @code
@end table
-@node SH, Sparclet, PA, Embedded Processors
+@node SH
@subsection Hitachi SH
@table @code
@end table
-@node Sparclet, Sparclite, SH, Embedded Processors
+@node Sparclet
@subsection Tsqware Sparclet
@cindex Sparclet
-@value{GDBN} enables developers to debug tasks running on
-Sparclet targets from a Unix host.
+@value{GDBN} enables developers to debug tasks running on
+Sparclet targets from a Unix host.
@value{GDBN} uses code that runs on
both the Unix host and on the Sparclet target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host.
+@code{@value{GDBP}} is installed and executed on the Unix host.
@table @code
-@item timeout @var{args}
+@item remotetimeout @var{args}
@kindex remotetimeout
-@value{GDBN} supports the option @code{remotetimeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses.
+@value{GDBN} supports the option @code{remotetimeout}.
+This option is set by the user, and @var{args} represents the number of
+seconds @value{GDBN} waits for responses.
@end table
-@kindex Compiling
-When compiling for debugging, include the options @samp{-g} to get debug
+@cindex compiling, on Sparclet
+When compiling for debugging, include the options @samp{-g} to get debug
information and @samp{-Ttext} to relocate the program to where you wish to
-load it on the target. You may also want to add the options @samp{-n} or
+load it on the target. You may also want to add the options @samp{-n} or
@samp{-N} in order to reduce the size of the sections. Example:
@example
sparclet-aout-objdump --headers --syms prog
@end example
-@kindex Running
+@cindex running, on Sparclet
Once you have set
your Unix execution search path to find @value{GDBN}, you are ready to
-run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
+run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
(or @code{sparclet-aout-gdb}, depending on your installation).
@value{GDBN} comes up showing the prompt:
* Sparclet File:: Setting the file to debug
* Sparclet Connection:: Connecting to Sparclet
* Sparclet Download:: Sparclet download
-* Sparclet Execution:: Running and debugging
+* Sparclet Execution:: Running and debugging
@end menu
-@node Sparclet File, Sparclet Connection, Sparclet, Sparclet
+@node Sparclet File
@subsubsection Setting file to debug
The @value{GDBN} command @code{file} lets you choose with program to debug.
@end example
When this happens, add the appropriate directories to the search paths with
-the @value{GDBN} commands @code{path} and @code{dir}, and execute the
+the @value{GDBN} commands @code{path} and @code{dir}, and execute the
@code{target} command again.
-@node Sparclet Connection, Sparclet Download, Sparclet File, Sparclet
+@node Sparclet Connection
@subsubsection Connecting to Sparclet
The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
@example
(gdbslet) target sparclet /dev/ttya
Remote target sparclet connected to /dev/ttya
-main () at ../prog.c:3
+main () at ../prog.c:3
@end example
@need 750
Connected to ttya.
@end example
-@node Sparclet Download, Sparclet Execution, Sparclet Connection, Sparclet
+@node Sparclet Download
@subsubsection Sparclet download
@cindex download to Sparclet
-Once connected to the Sparclet target,
+Once connected to the Sparclet target,
you can use the @value{GDBN}
@code{load} command to download the file from the host to the target.
The file name and load offset should be given as arguments to the @code{load}
command.
-Since the file format is aout, the program must be loaded to the starting
+Since the file format is aout, the program must be loaded to the starting
address. You can use @code{objdump} to find out what this value is. The load
offset is an offset which is added to the VMA (virtual memory address)
of each of the file's sections.
Loading section .text, size 0xdb0 vma 0x12010000
@end example
-If the code is loaded at a different address then what the program was linked
-to, you may need to use the @code{section} and @code{add-symbol-file} commands
+If the code is loaded at a different address then what the program was linked
+to, you may need to use the @code{section} and @code{add-symbol-file} commands
to tell @value{GDBN} where to map the symbol table.
-@node Sparclet Execution, , Sparclet Download, Sparclet
+@node Sparclet Execution
@subsubsection Running and debugging
@cindex running and debugging Sparclet programs
You can now begin debugging the task using @value{GDBN}'s execution control
-commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
+commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
manual for the list of commands.
@example
(gdbslet) b main
Breakpoint 1 at 0x12010000: file prog.c, line 3.
-(gdbslet) run
+(gdbslet) run
Starting program: prog
Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
3 char *symarg = 0;
(gdbslet) step
4 char *execarg = "hello!";
-(gdbslet)
+(gdbslet)
@end example
-@node Sparclite, ST2000, Sparclet, Embedded Processors
+@node Sparclite
@subsection Fujitsu Sparclite
@table @code
@kindex target sparclite
@item target sparclite @var{dev}
-Fujitsu sparclite boards, used only for the purpose of loading.
-You must use an additional command to debug the program.
-For example: target remote @var{dev} using @value{GDBN} standard
+Fujitsu sparclite boards, used only for the purpose of loading.
+You must use an additional command to debug the program.
+For example: target remote @var{dev} using @value{GDBN} standard
remote protocol.
@end table
-@node ST2000, Z8000, Sparclite, Embedded Processors
+@node ST2000
@subsection Tandem ST2000
@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
@end table
-@node Z8000, , ST2000, Embedded Processors
+@node Z8000
@subsection Zilog Z8000
@cindex Z8000
conditional breakpoint that suspends only after at least 5000
simulated clock ticks.
-@node Architectures, , Embedded Processors, Configurations
+@node Architectures
@section Architectures
This section describes characteristics of architectures that affect
* MIPS::
@end menu
-@node A29K, Alpha, Architectures, Architectures
+@node A29K
@subsection A29K
@table @code
@end table
-@node Alpha, MIPS, A29K, Architectures
+@node Alpha
@subsection Alpha
See the following section.
-@node MIPS, , Alpha, Architectures
+@node MIPS
@subsection MIPS
@cindex stack on Alpha
commands:
@table @code
-@cindex @code{heuristic-fence-post} (Alpha,MIPS)
+@cindex @code{heuristic-fence-post} (Alpha, MIPS)
@item set heuristic-fence-post @var{limit}
Restrict @value{GDBN} to examining at most @var{limit} bytes in its
search for the beginning of a function. A value of @var{0} (the
for debugging programs on Alpha or MIPS processors.
-@node Controlling GDB, Sequences, Configurations, Top
+@node Controlling GDB
@chapter Controlling @value{GDBN}
You can alter the way @value{GDBN} interacts with you by using the
* Screen Size:: Screen size
* Numbers:: Numbers
* Messages/Warnings:: Optional warnings and messages
+* Debugging Output:: Optional messages about internal happenings
@end menu
-@node Prompt, Editing, Controlling GDB, Controlling GDB
+@node Prompt
@section Prompt
@cindex prompt
called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
can change the prompt string with the @code{set prompt} command. For
instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
-the prompt in one of the @value{GDBN} sessions so that you can always tell
+the prompt in one of the @value{GDBN} sessions so that you can always tell
which one you are talking to.
@emph{Note:} @code{set prompt} does not add a space for you after the
Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
@end table
-@node Editing, History, Prompt, Controlling GDB
+@node Editing
@section Command editing
@cindex readline
@cindex command line editing
Show whether command line editing is enabled.
@end table
-@node History, Screen Size, Editing, Controlling GDB
+@node History
@section Command history
@value{GDBN} can keep track of the commands you type during your
@end table
@table @code
-@kindex show commands
+@kindex shows
@item show commands
Display the last ten commands in the command history.
Print ten commands just after the commands last printed.
@end table
-@node Screen Size, Numbers, History, Controlling GDB
+@node Screen Size
@section Screen size
@cindex size of screen
@cindex pauses in output
a screen width of @var{cpl} characters. The associated @code{show}
commands display the current settings.
-If you specify a height of zero lines, @value{GDBN} does not pause during
-output no matter how long the output is. This is useful if output is to a
+If you specify a height of zero lines, @value{GDBN} does not pause during
+output no matter how long the output is. This is useful if output is to a
file or to an editor buffer.
Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
from wrapping its output.
@end table
-@node Numbers, Messages/Warnings, Screen Size, Controlling GDB
+@node Numbers
@section Numbers
@cindex number representation
@cindex entering numbers
Display the current default base for numeric display.
@end table
-@node Messages/Warnings, , Numbers, Controlling GDB
+@node Messages/Warnings
@section Optional warnings and messages
By default, @value{GDBN} is silent about its inner workings. If you are
@end table
-@node Sequences, Emacs, Controlling GDB, Top
+@node Debugging Output
+@section Optional messages about internal happenings
+@table @code
+@kindex set debug arch
+@item set debug arch
+Turns on or off display of gdbarch debugging info. The default is off
+@kindex show debug arch
+@item show debug arch
+Displays the current state of displaying gdbarch debugging info.
+@kindex set debug event
+@item set debug event
+Turns on or off display of @value{GDBN} event debugging info. The
+default is off.
+@kindex show debug event
+@item show debug event
+Displays the current state of displaying @value{GDBN} event debugging
+info.
+@kindex set debug expression
+@item set debug expression
+Turns on or off display of @value{GDBN} expression debugging info. The
+default is off.
+@kindex show debug expression
+@item show debug expression
+Displays the current state of displaying @value{GDBN} expression
+debugging info.
+@kindex set debug overload
+@item set debug overload
+Turns on or off display of @value{GDBN} C++ overload debugging
+info. This includes info such as ranking of functions, etc. The default
+is off.
+@kindex show debug overload
+@item show debug overload
+Displays the current state of displaying @value{GDBN} C++ overload
+debugging info.
+@kindex set debug remote
+@cindex packets, reporting on stdout
+@cindex serial connections, debugging
+@item set debug remote
+Turns on or off display of reports on all packets sent back and forth across
+the serial line to the remote machine. The info is printed on the
+@value{GDBN} standard output stream. The default is off.
+@kindex show debug remote
+@item show debug remote
+Displays the state of display of remote packets.
+@kindex set debug serial
+@item set debug serial
+Turns on or off display of @value{GDBN} serial debugging info. The
+default is off.
+@kindex show debug serial
+@item show debug serial
+Displays the current state of displaying @value{GDBN} serial debugging
+info.
+@kindex set debug target
+@item set debug target
+Turns on or off display of @value{GDBN} target debugging info. This info
+includes what is going on at the target level of GDB, as it happens. The
+default is off.
+@kindex show debug target
+@item show debug target
+Displays the current state of displaying @value{GDBN} target debugging
+info.
+@kindex set debug varobj
+@item set debug varobj
+Turns on or off display of @value{GDBN} variable object debugging
+info. The default is off.
+@kindex show debug varobj
+@item show debug varobj
+Displays the current state of displaying @value{GDBN} variable object
+debugging info.
+@end table
+
+@node Sequences
@chapter Canned Sequences of Commands
Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
* Output:: Commands for controlled output
@end menu
-@node Define, Hooks, Sequences, Sequences
+@node Define
@section User-defined commands
@cindex user-defined command
@noindent
This defines the command @code{adder}, which prints the sum of
-its three arguments. Note the arguments are text substitutions, so they may
+its three arguments. Note the arguments are text substitutions, so they may
reference variables, use complex expressions, or even perform inferior
functions calls.
@kindex document
@item document @var{commandname}
Document the user-defined command @var{commandname}, so that it can be
-accessed by @code{help}. The command @var{commandname} must already be
-defined. This command reads lines of documentation just as @code{define}
-reads the lines of the command definition, ending with @code{end}.
-After the @code{document} command is finished, @code{help} on command
+accessed by @code{help}. The command @var{commandname} must already be
+defined. This command reads lines of documentation just as @code{define}
+reads the lines of the command definition, ending with @code{end}.
+After the @code{document} command is finished, @code{help} on command
@var{commandname} displays the documentation you have written.
You may use the @code{document} command again to change the
stops execution of the user-defined command.
If used interactively, commands that would ask for confirmation proceed
-without asking when used inside a user-defined command. Many @value{GDBN}
-commands that normally print messages to say what they are doing omit the
+without asking when used inside a user-defined command. Many @value{GDBN}
+commands that normally print messages to say what they are doing omit the
messages when used in a user-defined command.
-@node Hooks, Command Files, Define, Sequences
+@node Hooks
@section User-defined command hooks
@cindex command hooks
@cindex hooks, for commands
If you try to define a hook which does not match any known command, you
get a warning from the @code{define} command.
-@node Command Files, Output, Hooks, Sequences
+@node Command Files
@section Command files
@cindex command files
-A command file for @value{GDBN} is a file of lines that are @value{GDBN}
-commands. Comments (lines starting with @kbd{#}) may also be included.
-An empty line in a command file does nothing; it does not mean to repeat
+A command file for @value{GDBN} is a file of lines that are @value{GDBN}
+commands. Comments (lines starting with @kbd{#}) may also be included.
+An empty line in a command file does nothing; it does not mean to repeat
the last command, as it would from the terminal.
@cindex init file
@cindex @file{.gdbinit}
@cindex @file{gdb.ini}
When you start @value{GDBN}, it automatically executes commands from its
-@dfn{init files}. These are files named @file{.gdbinit} on Unix, or
-@file{gdb.ini} on DOS/Windows. @value{GDBN} reads the init file (if
-any) in your home directory@footnote{On DOS/Windows systems, the home
-directory is the one pointed to by the @code{HOME} environment
-variable.}, then processes command line options and operands, and then
-reads the init file (if any) in the current working directory. This is
-so the init file in your home directory can set options (such as
-@code{set complaints}) which affect the processing of the command line
-options and operands. The init files are not executed if you use the
-@samp{-nx} option; @pxref{Mode Options, ,Choosing modes}.
+@dfn{init files}. These are files named @file{.gdbinit} on Unix and
+@file{gdb.ini} on DOS/Windows. During startup, @value{GDBN} does the
+following:
+
+@enumerate
+@item
+Reads the init file (if any) in your home directory@footnote{On
+DOS/Windows systems, the home directory is the one pointed to by the
+@code{HOME} environment variable.}.
+
+@item
+Processes command line options and operands.
+
+@item
+Reads the init file (if any) in the current working directory.
+
+@item
+Reads command files specified by the @samp{-x} option.
+@end enumerate
+
+The init file in your home directory can set options (such as @samp{set
+complaints}) that affect subsequent processing of command line options
+and operands. Init files are not executed if you use the @samp{-nx}
+option (@pxref{Mode Options, ,Choosing modes}).
@cindex init file name
On some configurations of @value{GDBN}, the init file is known by a
different name for the specialized version's init file). These are the
environments with special init file names:
-@kindex .vxgdbinit
+@cindex @file{.vxgdbinit}
@itemize @bullet
@item
-VxWorks (Wind River Systems real-time OS): @samp{.vxgdbinit}
+VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
-@kindex .os68gdbinit
+@cindex @file{.os68gdbinit}
@item
-OS68K (Enea Data Systems real-time OS): @samp{.os68gdbinit}
+OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
-@kindex .esgdbinit
+@cindex @file{.esgdbinit}
@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @samp{.esgdbinit}
+ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
@end itemize
You can also request the execution of a command file with the
normally print messages to say what they are doing omit the messages
when called from command files.
-@node Output, , Command Files, Sequences
+@node Output
@section Commands for controlled output
During the execution of a command file or a user-defined command, normal
In addition to the standard C escape sequences, a backslash followed
by a space stands for a space. This is useful for displaying a
string with spaces at the beginning or the end, since leading and
-trailing spaces are otherwise trimmed from all arguments.
+trailing spaces are otherwise trimmed from all arguments.
To print @samp{@w{ }and foo =@w{ }}, use the command
@samp{echo \@w{ }and foo = \@w{ }}.
@item output @var{expression}
Print the value of @var{expression} and nothing but that value: no
newlines, no @samp{$@var{nn} = }. The value is not entered in the
-value history either. @xref{Expressions, ,Expressions}, for more information
+value history either. @xref{Expressions, ,Expressions}, for more information
on expressions.
@item output/@var{fmt} @var{expression}
letter.
@end table
-@node Emacs, Annotations, Sequences, Top
+@node Emacs
@chapter Using @value{GDBN} under @sc{gnu} Emacs
@cindex Emacs
@kindex Epoch
@kindex inspect
-Version 18 of @sc{gnu} Emacs has a built-in window system
+Version 18 of @sc{gnu} Emacs has a built-in window system
called the @code{epoch}
environment. Users of this environment can use a new command,
@code{inspect} which performs identically to @code{print} except that
each value is printed in its own window.
@end ignore
-@node Annotations, GDB Bugs, Emacs, Top
-@chapter @value{GDBN} Annotations
@include annotate.texi
+@include gdbmi.texinfo
-@node GDB Bugs, Command Line Editing, Annotations, Top
+@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
@cindex bugs in @value{GDBN}
@cindex reporting bugs in @value{GDBN}
* Bug Reporting:: How to report bugs
@end menu
-@node Bug Criteria, Bug Reporting, GDB Bugs, GDB Bugs
+@node Bug Criteria
@section Have you found a bug?
@cindex bug criteria
for improvement of @value{GDBN} are welcome in any case.
@end itemize
-@node Bug Reporting, , Bug Criteria, GDB Bugs
+@node Bug Reporting
@section How to report bugs
@cindex bug reports
@cindex @value{GDBN} bugs, reporting
things without first using the debugger to find the facts.
@end itemize
-@c The readline documentation is distributed with the readline code
+@c The readline documentation is distributed with the readline code
@c and consists of the two following files:
@c rluser.texinfo
@c inc-hist.texinfo
@c Use -I with makeinfo to point to the appropriate directory,
@c environment var TEXINPUTS with TeX.
-
-@node Command Line Editing, Using History Interactively, GDB Bugs, Top
-@chapter Command Line Editing
@include rluser.texinfo
-
-
-@node Using History Interactively, Formatting Documentation, Command Line Editing, Top
-@chapter Using History Interactively
@include inc-hist.texinfo
-@node Formatting Documentation, Installing GDB, Using History Interactively, Top
+@node Formatting Documentation
@appendix Formatting Documentation
@cindex @value{GDBN} reference card
make refcard.dvi
@end example
-The @value{GDBN} reference card is designed to print in @dfn{landscape}
-mode on US ``letter'' size paper;
+The @value{GDBN} reference card is designed to print in @dfn{landscape}
+mode on US ``letter'' size paper;
that is, on a sheet 11 inches wide by 8.5 inches
high. You will need to specify this form of printing as an option to
your @sc{dvi} output program.
Then give @file{gdb.dvi} to your @sc{dvi} printing program.
-@node Installing GDB, Index, Formatting Documentation, Top
+@node Installing GDB
@appendix Installing @value{GDBN}
@cindex configuring @value{GDBN}
@cindex installation
installation procedures since publishing this manual.}
@end iftex
-The @value{GDBN} distribution includes all the source code you need for
-@value{GDBN} in a single directory, whose name is usually composed by
+The @value{GDBN} distribution includes all the source code you need for
+@value{GDBN} in a single directory, whose name is usually composed by
appending the version number to @samp{gdb}.
For example, the @value{GDBN} version @value{GDBVN} distribution is in the
* Configure Options:: Summary of options for configure
@end menu
-@node Separate Objdir, Config Names, Installing GDB, Installing GDB
+@node Separate Objdir
@section Compiling @value{GDBN} in another directory
If you want to run @value{GDBN} versions for several host or target machines,
would be the same as the argument to @samp{--srcdir}, you can leave out
the @samp{--srcdir} option; it is assumed.)
-For example, with version @value{GDBVN}, you can build @value{GDBN} in a
+For example, with version @value{GDBVN}, you can build @value{GDBN} in a
separate directory for a Sun 4 like this:
@example
@file{gdb-sun4/gdb}.
One popular reason to build several @value{GDBN} configurations in separate
-directories is to configure @value{GDBN} for cross-compiling (where
-@value{GDBN} runs on one machine---the @dfn{host}---while debugging
-programs that run on another machine---the @dfn{target}).
+directories is to configure @value{GDBN} for cross-compiling (where
+@value{GDBN} runs on one machine---the @dfn{host}---while debugging
+programs that run on another machine---the @dfn{target}).
You specify a cross-debugging target by
giving the @samp{--target=@var{target}} option to @code{configure}.
if they are NFS-mounted on each of the hosts); they will not interfere
with each other.
-@node Config Names, Configure Options, Separate Objdir, Installing GDB
+@node Config Names
@section Specifying names for hosts and targets
The specifications used for hosts and targets in the @code{configure}
@code{config.sub} is also distributed in the @value{GDBN} source
directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
-@node Configure Options, , Config Names, Installing GDB
+@node Configure Options
@section @code{configure} options
Here is a summary of the @code{configure} options and arguments that
There are many other options available as well, but they are generally
needed for special purposes only.
-
-@node Index, , Installing GDB, Top
+
+@node Index
@unnumbered Index
@printindex cp
% Blame: doc@cygnus.com, 1991.
@end tex
+@c TeX can handle the contents at the start but makeinfo 3.12 can not
+@ifinfo
@contents
+@end ifinfo
+@ifhtml
+@contents
+@end ifhtml
+
@bye