@c @subtitle Third Edition---_GDBN__ version 4.0
@subtitle _GDBN__ version 4.0
@subtitle May 1991
-@author{Richard M. Stallman @hfill Free Software Foundation}
-@author{Roland H. Pesch @hfill Cygnus Support}
+@author{Richard M. Stallman@qquad @hfill Free Software Foundation}
+@author{Roland H. Pesch@qquad @hfill Cygnus Support}
@page
@tex
@node i960-Nindy Remote, EB29K Remote, Mode Options, Starting _GDBN__
@subsection _GDBN__ with a Remote i960 (Nindy)
+@cindex Nindy
+@cindex i960
@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
_GDBN__ is configured to control a remote Intel 960 using Nindy, you can
tell _GDBN__ how to connect to the 960 in several ways:
@cindex EB29K board
@cindex running 29K programs
-@cindex 29K
To use _GDBN__ from a Unix system to run programs on AMD's EB29K
board in a PC, you must first connect a serial cable between the PC
_if__(_VXWORKS__)
@node VxWorks Remote, , EB29K Remote, Starting _GDBN__
@subsection _GDBN__ and VxWorks
+@cindex VxWorks
_GDBN__ enables developers to spawn and debug tasks running on networked
VxWorks targets from a Unix host. Already-running tasks spawned from
the VxWorks shell can also be debugged. _GDBN__ uses code that runs on
@file{rdb.a} and are incorporated into the system image when source-level
debugging is enabled in the VxWorks configuration.
+@kindex{INCLUDE_RDB}
Defining @code{INCLUDE_RDB} in the VxWorks configuration file
@file{configAll.h} includes the RDB interface routines and spawns the
source debugging task @code{tRdbTask} when VxWorks is booted. For more
@node VxWorks download, VxWorks attach, VxWorks connection, VxWorks Remote
@subsubsection VxWorks Download
+@cindex download to VxWorks
If you have connected to the VxWorks target and you want to debug an
object that has not yet been loaded, you can use the _GDBN__ @code{load}
command to download a file from UNIX to VxWorks incrementally. The
@node VxWorks attach, , VxWorks download, VxWorks Remote
@subsubsection Running Tasks
+@cindex running VxWorks tasks
You can also attach to an existing task using the @code{attach} command as
follows:
#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
206 expand_input();
(_GDBP__) until
-blah
-195 for ( ; argc > 0; NEXTARG) {
+195 for ( ; argc > 0; NEXTARG) @{
@end example
In this case, (as for any C @code{for}-loop), the loop-step expression
@kindex info line
Print the starting and ending addresses of the compiled code for
source line @var{linespec}. You can specify source lines in any of the
-ways understood by the @code{break} command (@pxref{Set Breaks}).
+ways understood by the @code{list} command (@pxref{List}).
@end table
For example, we can use @code{info line} to inquire on where the object
code for the first line of function @code{m4_changequote} lies:
-@example
+@smallexample
(_GDBP__) info line m4_changecom
Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
-@end example
+@end smallexample
@noindent
We can also inquire (using @code{*@var{addr}} as the form for
@var{linespec}) what source line covers a particular address:
-@example
+@smallexample
(_GDBP__) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
-@end example
+@end smallexample
@kindex $_
After @code{info line}, the default address for the @code{x}
We can use @code{disassemble} to inspect the object code
range shown in the last @code{info line} example:
-@example
+@smallexample
(_GDBP__) disas 0x63e4 0x6404
Dump of assembler code from 0x63e4 to 0x6404:
0x63e4 <builtin_init+5340>: ble 0x63f8 <builtin_init+5360>
End of assembler dump.
(_GDBP__)
-@end example
+@end smallexample
@node Data, Symbols, Source, Top
@chapter Examining Data
even when it also displays the contents of those addresses. The default
is on. For example, this is what a stack frame display looks like, with
@code{set print address on}:
-@example
+@smallexample
(_GDBP__) f
-#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") at input.c:530
+#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
+ at input.c:530
530 if (lquote != def_lquote)
-@end example
+@end smallexample
@item set print address off
Do not print addresses when displaying their contents. For example,
file @var{filename}.
@end table
-@c FIXME: RMS comments not yet considered below this point
-@c ......................................................................
@node Altering, _GDBN__ Files, Symbols, Top
@chapter Altering Execution
If the beginning of the argument string of the @code{set} command
appears identical to a @code{set} subcommand, use the @code{set
variable} command instead of just @code{set}. This command is identical
-to @code{set} except for its lack of subcommands.
+to @code{set} except for its lack of subcommands. For example, a
+program might well have a variable @code{width}---which leads to
+an error if we try to set a new value with just @samp{set width=13}, as
+we might if @code{set width} didn't happen to be a _GDBN__ command:
+@example
+(_GDBP__) whatis width
+type = double
+(_GDBP__) p width
+$4 = 13
+(_GDBP__) set width=47
+Invalid syntax in expression.
+@end example
+@noindent
+The invalid expression, of course, is @samp{=47}. What we can do in
+order to actually set our program's variable @code{width} is
+@example
+(_GDBP__) set var width=47
+@end example
_GDBN__ allows more implicit conversions in assignments than C does; you can
freely store an integer value into a pointer variable or vice versa, and
an address of your own choosing, with the following commands:
@table @code
-@item jump @var{linenum}
+@item jump @var{linespec}
@kindex jump
-Resume execution at line number @var{linenum}. Execution will stop
-immediately if there is a breakpoint there.
+Resume execution at line @var{linespec}. Execution will stop
+immediately if there is a breakpoint there. @xref{List} for a
+description of the different forms of @var{linespec}.
The @code{jump} command does not change the current stack frame, or
the stack pointer, or the contents of any memory location or any
-register other than the program counter. If line @var{linenum} is in
+register other than the program counter. If line @var{linespec} is in
a different function from the one currently executing, the results may
be bizarre if the two functions expect different patterns of arguments or
of local variables. For this reason, the @code{jump} command requests
The most common occasion to use the @code{jump} command is to back up,
perhaps with more breakpoints set, over a portion of a program that has
-already executed.
+already executed, in order to examine its execution in more detail.
@group
@node Signaling, Returning, Jumping, Altering
@table @code
@item return
+@itemx return @var{expression}
@cindex returning from a function
@kindex return
You can cancel execution of a function call with the @code{return}
-command.
+command. If you give an
+@var{expression} argument, its value is used as the function's return
+value.
@end table
-This command abandons execution of a function. When you use
-@code{return}, _GDBN__ discards the selected stack frame (and all frames
-within it). You can think of this as making the discarded frame return
-prematurely. If you wish to specify a value to be returned, give that
-value as the argument to @code{return}.
+When you use @code{return}, _GDBN__ discards the selected stack frame
+(and all frames within it). You can think of this as making the
+discarded frame return prematurely. If you wish to specify a value to
+be returned, give that value as the argument to @code{return}.
This pops the selected stack frame (@pxref{Selection}), and any other
frames inside of it, leaving its caller as the innermost remaining
executed when you use the @code{run} command. If you do not specify a
directory and the file is not found in _GDBN__'s working directory,
-_GDBN__ will use the environment variable @code{PATH} as a list of
+_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 _GDBN__ and
your program, using the @code{path} command.
_fi__(_VXWORKS__)
_if__(_I960__)
+@cindex download to Nindy-960
With the Nindy interface to an Intel 960 board, @code{load} will
download @var{filename} to the 960 as well as adding its symbols in
_GDBN__.
@itemx info sharedlibrary
@kindex info sharedlibrary
@kindex info share
-Print the names of the shared libraries which are currently loaded.
+Print the names of the shared libraries which you have loaded with the
+@code{sharedlibrary} command.
@end table
@code{sharedlibrary} does not repeat automatically when you press
name @code{foo}, which may cause other problems if many symbols end up
with this name.
-@item unknown symbol type @code{0x@var{NN}}
+@item unknown symbol type @code{0x@var{nn}}
The symbol information contains new data types that _GDBN__ does not yet
-know how to read. @code{0x@var{NN}} is the symbol type of the misunderstood
+know how to read. @code{0x@var{nn}} is the symbol type of the misunderstood
information, in hexadecimal.
_GDBN__ circumvents the error by ignoring this symbol information. This
@code{complain}, then go up to the function @code{read_dbx_symtab} and
examine @code{*bufp} to see the symbol.
-@c @item stub type has NULL name
-@c
-@c FIXME, Mike Tiemann needs to write about what this means.
+@item stub type has NULL name
+_GDBN__ could not find the full definition for a struct or class.
-@item const/volatile indicator missing, got 'X'
+@ignore
+@c this is #if 0'd in dbxread.c as of (at least!) 17 may 1991
+@item const/volatile indicator missing, got '@var{X}'
-The symbol information for a C++ type is missing some information that
-the compiler should have output for it.
+The symbol information for a C++ member function is missing some
+information that the compiler should have output for it.
+@end ignore
@item C++ type mismatch between compiler and debugger
More than one target can potentially respond to a request. In
particular, when you access memory _GDBN__ will examine the three strata of
targets until it finds a target that can handle that particular address.
-
Strata are always examined in a fixed order: first a process if there is
one, then a core file if there is one, and finally an executable file if
there is one of those.
@kindex target remote
Remote serial target in _GDBN__-specific protocol. The argument @var{dev}
specifies what serial device to use for the connection (e.g.
-@code{/dev/ttya}). @xref{Remote}.
+@file{/dev/ttya}). @xref{Remote}.
_if__(_AMD29K__)
@item target amd-eb @var{dev} @var{speed} @var{PROG}
If you are trying to debug a program running on a machine that can't run
_GDBN__ in the usual way, it is often useful to use remote debugging. For
-example, you might be debugging an operating system kernel, or debugging
+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 _GDBN__ have special serial or TCP/IP interfaces
to make this work with particular debugging targets. In addition,
_GDBN__ comes with a generic serial protocol (specific to _GDBN__, but
-not specific to any particular target system) which you can adapt.
+not specific to any particular target system) which you can use if you
+write the remote stubs---the code that will run on the remote system to
+communicate with _GDBN__.
To use the _GDBN__ remote serial protocol, the program to be debugged on
-the remote machine needs to contain a debugging device driver which
-talks to _GDBN__ over the serial line. Several sample remote debugging
-drivers are distributed with _GDBN__; see the @file{README} file in the
-_GDBN__ distribution for more information.
+the remote machine needs to contain a debugging stub which talks to
+_GDBN__ over the serial line. Several working remote stubs are
+distributed with _GDBN__; see the @file{README} file in the _GDBN__
+distribution for more information.
For details of this communication protocol, see the comments in the
_GDBN__ source file @file{remote.c}.
called the @dfn{prompt}. This string is normally @samp{(_GDBP__)}. You
can change the prompt string with the @code{set prompt} command. For
instance, when debugging _GDBN__ with _GDBN__, it is useful to change
-the prompt in one of the _GDBN__<>s so that you tell which one you are
-talking to.
+the prompt in one of the _GDBN__<>s so that you can always tell which
+one you are talking to.
@table @code
@item set prompt @var{newprompt}
debugging sessions.
You may control the behavior of command line editing in _GDBN__ with the
-command @code{set}. You may check the status of any of these settings
-with the command @code{show}.
+command @code{set}.
@table @code
@kindex set editing
By default, if _GDBN__ encounters bugs in the symbol table of an object file,
it prints a single message about each type of problem it finds, then
-shuts up. You can suppress these messages, or allow more than one such
+shuts up (@pxref{Symbol Errors}). You can suppress these messages, or allow more than one such
message to be printed if you want to see how frequent the problems are.
-@xref{Symbol Errors}.
@table @code
@kindex set complaints
lot of stupid questions to confirm certain commands. For example, if
you try to run a program which is already running:
@example
-
(_GDBP__) run
The program being debugged has been started already.
Start it from the beginning? (y or n)
@node Sequences, Emacs, Controlling _GDBN__, Top
@chapter Canned Sequences of Commands
-Aside from breakpoint commands (@pxref{Break Commands}),_GDBN__ provides two
+Aside from breakpoint commands (@pxref{Break Commands}), _GDBN__ provides two
ways to store sequences of commands for execution as a unit:
user-defined commands and command files.
@dfn{init files}. These are files named @file{_GDBINIT__}. _GDBN__
reads the init file (if any) in your home directory and then the init
file (if any) in the current working directory. (The init files are not
-executed if the @samp{-nx} option is given.) You can also request the
-execution of a command file with the @code{source} command:
+executed if you use the @samp{-nx} option; @pxref{Mode Options}.) You
+can also request the execution of a command file with the @code{source}
+command:
@table @code
@item source @var{filename}
Print @var{text}. Nonprinting characters can be included in @var{text}
using C escape sequences, such as @samp{\n} to print a newline. @b{No
newline will be printed unless you specify one.} In addition to the
-standard C escape sequences a backslash followed by a space stands for a
+standard C escape sequences, a backslash followed by a space stands for a
space. This is useful for outputting a string with spaces at the
beginning or the end, since leading and trailing spaces are otherwise
trimmed from all arguments. Thus, to print @samp{@ and foo =@ }, use the
_GDBN__ buffer in Emacs.
@end quotation
-By default, @kbd{M-x gdb} calls the program called ``@code{gdb}''. If
+By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
you need to call _GDBN__ by a different name (for example, if you keep
several configurations around, with different names) you can set the
Emacs variable @code{gdb-command-name}; for example,
@code{finish} command.
@item M-c
-@c C-c C-p in emacs 19
-Continue execution of the program, like the _GDBN__ @code{continue} command.
+Continue execution of the program, like the _GDBN__ @code{continue}
+command. @emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
@item M-u
-@c C-c C-u in emacs 19
Go up the number of frames indicated by the numeric argument
(@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}),
-like the _GDBN__ @code{up} command.@refill
+like the _GDBN__ @code{up} command. @emph{Warning:} In Emacs v19, this
+command is @kbd{C-c C-u}.@refill
@item M-d
-@c C-c C-d in emacs 19
Go down the number of frames indicated by the numeric argument, like the
-_GDBN__ @code{down} command.
+_GDBN__ @code{down} command. @emph{Warning:} In Emacs v19, this command
+is @kbd{C-c C-d}.
@item C-x &
Read the number where the cursor is positioned, and insert it at the end
formatted using the Emacs function @code{format}; otherwise the number
is passed as an argument to the corresponding list element.
-@item M-x gdb-display-frame
-Explicitly request display of the source code surrounding the current
-frame location, in another window. _GDBN__ does this display automatically;
-but if, for example, you accidentally kill the buffer where it is
-displayed, this command is a way of getting it back.
@end table
In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
tells _GDBN__ to set a breakpoint on the source line point is on.
+If you accidentally delete the source-display buffer, an easy way to get
+it back is to type the command @code{f} in the _GDBN__ buffer, to
+request a frame display; when you run under Emacs, this will recreate
+the source buffer if necessary to show you the context of the current
+frame.
+
The source files displayed in Emacs are in ordinary Emacs buffers
which are visiting the source files in the usual way. You can edit
the files with these buffers if you wish; but keep in mind that _GDBN__
repeater. The mailing list and the newsgroup carry exactly the same
messages. Often people think of posting bug reports to the newsgroup
instead of mailing them. This appears to work, but it has one problem
-which can be crucial: a newsgroup posting does not contain a mail path
+which can be crucial: a newsgroup posting often lacks a mail path
back to the sender. Thus, if we need to ask for more information, we
may be unable to reach you. For this reason, it is better to send bug
reports to the mailing list.
you won't omit something important, list them all.
If we were to try to guess the arguments, we would probably guess wrong
-and then we would not encounter the bug.
+and then we might not encounter the bug.
@item
The type of machine you are using, and the operating system name and
A description of what behavior you observe that you believe is
incorrect. For example, ``It gets a fatal signal.''
-Of course, if the bug is that _GDBN__ gets a fatal signal, then we
-will certainly notice it. But if the bug is incorrect output, we might
-not notice unless it is glaringly wrong.
+Of course, if the bug is that _GDBN__ gets a fatal signal, then we will
+certainly notice it. But if the bug is incorrect output, we might not
+notice unless it is glaringly wrong. We are human, after all. You
+might as well not give us a chance to make a mistake.
Even if the problem you experience is a fatal signal, you should still
say so explicitly. Suppose something strange is going on, such as,
projects / platform / upstream / binutils.git / commitdiff