\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
-@ifnottex
+@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
+@value{GDBVN}.
+
+Copyright (C) 1988-2000 Free Software Foundation, Inc.
+
+@menu
+* Summary:: Summary of @value{GDBN}
+* Sample Session:: A sample @value{GDBN} session
+
+* Invocation:: Getting in and out of @value{GDBN}
+* Commands:: @value{GDBN} commands
+* Running:: Running programs under @value{GDBN}
+* Stopping:: Stopping and continuing
+* Stack:: Examining the stack
+* Source:: Examining source files
+* Data:: Examining data
+
+* Languages:: Using @value{GDBN} with different languages
+
+* Symbols:: Examining the symbol table
+* Altering:: Altering execution
+* GDB Files:: @value{GDBN} files
+* Targets:: Specifying a debugging target
+* Configurations:: Configuration-specific information
+* Controlling GDB:: Controlling @value{GDBN}
+* Sequences:: Canned sequences of commands
+* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
+* Annotations:: @value{GDBN}'s annotation interface.
+* GDB/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-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
* 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
-@end ifnottex
+@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}
@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
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.
@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)
@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
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:
@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}.
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}
@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
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
@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
@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
@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}.
@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
@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.
@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
@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
@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
@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
@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
@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
@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
@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
@section Stopping and starting multi-thread programs
@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
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
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
@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)
@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:
@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
@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:
@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}.
@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
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,
@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
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}
@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
@cindex examining memory
@table @code
-@kindex x
+@kindex x @r{(examine memory)}
@item x/@var{nfu} @var{addr}
@itemx x @var{addr}
@itemx x
@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
@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{$}
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
@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.
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
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
@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}.
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
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
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
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
@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
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.
,Expressions}.
@menu
-* Debugging C plus plus::
+* Debugging C plus plus::
@end menu
@node Debugging C plus plus
@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
* 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
@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>
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
@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:
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
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
@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
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}
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.
@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
@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
@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}.
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.
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
@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
@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.
@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
@tab reply *
@tab Any other reply implies the old pid.
-@item compute CRC of memory block
-@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
+@item all thread ids
+@tab @code{q}@code{fThreadInfo}
+@item
+@tab @code{q}@code{sThreadInfo}
@tab
+Obtain a list of active thread ids from the target (OS). Since there
+may be too many active threads to fit into one reply packet, this query
+works iteratively: it may require more than one query/reply sequence to
+obtain the entire list of threads. The first query of the sequence will
+be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
+sequence will be the @code{qs}@code{ThreadInfo} query.
@item
-@tab reply @code{E}@var{NN}
-@tab An error (such as memory fault)
+@tab
+@tab NOTE: replaces the @code{qL} query (see below).
@item
-@tab reply @code{C}@var{CRC32}
-@tab A 32 bit cyclic redundancy check of the specified memory region.
+@tab reply @code{m}@var{<id>}
+@tab A single thread id
+@item
+@tab reply @code{m}@var{<id>},@var{<id>...}
+@tab a comma-separated list of thread ids
+@item
+@tab reply @code{l}
+@tab (lower case 'el') denotes end of list.
+@item
+@tab
+@tab
+In response to each query, the target will reply with a list of one
+or more thread ids, in big-endian hex, separated by commas. GDB will
+respond to each reply with a request for more thread ids (using the
+@code{qs} form of the query), until the target responds with @code{l}
+(lower-case el, for @code{'last'}).
+
+@item extra thread info
+@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id}
+@tab
+@item
+@tab
+@tab
+Where @var{<id>} is a thread-id in big-endian hex.
+Obtain a printable string description of a thread's attributes from
+the target OS. This string may contain anything that the target OS
+thinks is interesting for @value{GDBN} to tell the user about the thread.
+The string is displayed in @value{GDBN}'s @samp{info threads} display.
+Some examples of possible thread extra info strings are "Runnable", or
+"Blocked on Mutex".
+@item
+@tab reply @var{XX...}
+@tab
+Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the
+printable string containing the extra information about the thread's
+attributes.
@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
(eight hex digits), for subsequent queries (@var{startflag} is zero), is
returned in the response as @var{argthread}.
@item
+@tab
+@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo}
+query (see above).
+@item
@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...}
@tab
@item
a sequence of thread IDs from the target. @var{threadid} (eight hex
digits). See @code{remote.c:parse_threadlist_response()}.
+@item compute CRC of memory block
+@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
+@tab
+@item
+@tab reply @code{E}@var{NN}
+@tab An error (such as memory fault)
+@item
+@tab reply @code{C}@var{CRC32}
+@tab A 32 bit cyclic redundancy check of the specified memory region.
+
@item query sect offs
@tab @code{q}@code{Offsets}
@tab
@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
@subsubsection Using the @code{gdbserver} program
@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
@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
@value{GDBN} displays messages like these:
@smallexample
-Attaching remote machine across net...
+Attaching remote machine across net...
Connected to tt.
@end smallexample
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
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
@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
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.
@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
@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
@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
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
@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
@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
@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
@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
@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
@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
@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
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
* Screen Size:: Screen size
* Numbers:: Numbers
* Messages/Warnings:: Optional warnings and messages
+* Debugging Output:: Optional messages about internal happenings
@end menu
@node 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
@end table
@table @code
-@kindex show commands
+@kindex shows
@item show commands
Display the last ten commands in the command history.
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}
@end table
+@node Debugging Output
+@section Optional messages about internal happenings
+@table @code
+@kindex set debug arch
+@item set debug arch
+Turns on or off display of gdbarch debugging info. The default is off
+@kindex show debug arch
+@item show debug arch
+Displays the current state of displaying gdbarch debugging info.
+@kindex set debug event
+@item set debug event
+Turns on or off display of @value{GDBN} event debugging info. The
+default is off.
+@kindex show debug event
+@item show debug event
+Displays the current state of displaying @value{GDBN} event debugging
+info.
+@kindex set debug expression
+@item set debug expression
+Turns on or off display of @value{GDBN} expression debugging info. The
+default is off.
+@kindex show debug expression
+@item show debug expression
+Displays the current state of displaying @value{GDBN} expression
+debugging info.
+@kindex set debug overload
+@item set debug overload
+Turns on or off display of @value{GDBN} C++ 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
@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
@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
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}
@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
@end ignore
@include annotate.texi
+@include gdbmi.texinfo
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
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
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.
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
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}.
There are many other options available as well, but they are generally
needed for special purposes only.
-
+
@node Index
@unnumbered Index
% Blame: doc@cygnus.com, 1991.
@end tex
+@c TeX can handle the contents at the start but makeinfo 3.12 can not
+@ifinfo
@contents
+@end ifinfo
+@ifhtml
+@contents
+@end ifhtml
+
@bye