@ifclear CONLY
You can use @value{GDBN} to debug programs written in C or C++. For
-more information, @xref{C}.
+more information, see @ref{C,,C and C++}.
@ifset MOD2
-@c I use "MOD2" as a "miscellaneous languages" flag here. According to
-@c a comment in all-cfg.texi, there should be separate flags for chill
-@c and Pascal, but that seems kind of silly since we only mention them
-@c in passing--IMHO the manual should be configurable as little as we
-@c can get away with -kingdon.
+@c "MOD2" used as a "miscellaneous languages" flag here.
+@c This is acceptable while there is no real doc for Chill and Pascal.
Support for Modula-2 and Chill is partial. For information on Modula-2,
-@xref{Modula-2}; there is no further documentation on Chill yet.
+see @ref{Modula-2,,Modula-2}; there is no further documentation on Chill yet.
-Pascal programs which use sets, subranges, file variables, or nested
-functions will not currently work. @value{GDBN} does not support
+Debugging pascal programs which use sets, subranges, file variables, or nested
+functions does not currently work. @value{GDBN} does not support
entering expressions, printing values, etc. using Pascal syntax.
@end ifset
@ifset FORTRAN
GDB 4 can debug programs and core files that use SunOS, SVR4, or IBM RS/6000
shared libraries.
+@item Threads
+On some systems, GDB 4 has facilities to debug multi-thread programs.
+
@item Reference Card
GDB 4 has a reference card. @xref{Formatting Documentation,,Formatting
the Documentation}, for instructions about how to print it.
variables). On the other hand, each thread has its own registers and
execution stack, and perhaps private memory.
-@value{GDBN} provides several facilities for debugging multi-thread
+@value{GDBN} provides these facilities for debugging multi-thread
programs:
@itemize @bullet
@c included GDB's numeric thread handle, so you could just go to that
@c thread without first checking `info threads'.
Whenever @value{GDBN} detects a new thread in your program, it displays
-the system's identification for it with a message in the form @samp{[New
-@var{systag}]}. @var{systag} is a thread identifier whose form varies
-depending on the particular system. For example, on LynxOS, you might
-see
+the target system's identification for the thread with a message in the
+form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
+whose form varies depending on the particular system. For example, on
+LynxOS, you might see
@example
[New process 35 thread 27]
program. @value{GDBN} displays for each thread (in this order):
@enumerate
-@item the @value{GDBN} thread number
+@item the thread number assigned by @value{GDBN}
-@item the system's @var{systag} thread identifier
+@item the target system's thread identifier (@var{systag})
@item the current stack frame summary for that thread
@end enumerate
@table @code
@item thread @var{threadno}
+@kindex thread @var{threadno}
Make thread number @var{threadno} the current thread. The command
argument @var{threadno} is the internal @value{GDBN} thread number, as
shown in the first field of the @samp{info threads} display.
@xref{Thread Stops,,Stopping and starting multi-thread programs}, for
more information about how @value{GDBN} behaves when you stop and start
programs with multiple threads.
+
+@xref{Set Watchpoints,,Setting watchpoints}, for information about
+watchpoints in programs with multiple threads.
@end ifclear
@node Stopping
breakpoints on all threads, or on a particular thread.
@table @code
-@cindex br
+@cindex breakpoints and threads
+@cindex thread breakpoints
@kindex break @dots{} thread @var{threadno}
@item break @var{linespec} thread @var{threadno}
@itemx break @var{linespec} thread @var{threadno} if @dots{}
Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
-particular thread reaches this breakpoint. @var{threadno} is one of
-GDB's numeric thread identifiers, shown in the first column of
-the @samp{info threads} display.
-
-You can use the @code{thread} qualifier on conditional breakpoints as
-well; in this case, place @samp{thread @var{threadno}} before the
-breakpoint condition.
+particular thread reaches this breakpoint. @var{threadno} is one of the
+numeric thread identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info threads} display.
If you do not specify @samp{thread @var{threadno}} when you set a
breakpoint, the breakpoint applies to @emph{all} threads of your
program.
+
+You can use the @code{thread} qualifier on conditional breakpoints as
+well; in this case, place @samp{thread @var{threadno}} before the
+breakpoint condition, like this:
+
+@smallexample
+(gdb) break frik.c:13 thread 28 if bartab > lim
+@end smallexample
@end table
@cindex stopped threads
like @code{step} or @code{next}.
In particular, @value{GDBN} cannot single-step all threads in lockstep.
-Since thread scheduling is up to your host operating system, rather than
-controlled by @value{GDBN}, other threads may execute more than one
-statement while the current thread completes a single step.
-Moreover, in general other threads stop in the middle of a statement,
-rather than at a clean statement boundary, when the program stops.
+Since thread scheduling is up to your debugging target's operating
+system (not controlled by @value{GDBN}), other threads may
+execute more than one statement while the current thread completes a
+single step. Moreover, in general other threads stop in the middle of a
+statement, rather than at a clean statement boundary, when the program
+stops.
You might even find your program stopped in another thread after
continuing or even single-stepping. This happens whenever some other
@kindex g++
@cindex GNU C++
The C++ debugging facilities are jointly implemented by the GNU C++
-compiler and @value{GDBN}. Therefore, to debug your C++ code effectively,
-you must compile your C++ programs with the GNU C++ compiler,
-@code{g++}. Also, you must be using the stabs debugging format; see the
-documentation for the GNU C++ compiler for more information on how to
-select that format.
-
-In particular, cfront based compilers such as Sun's C++ are not fully
-supported.
+compiler and @value{GDBN}. Therefore, to debug your C++ code
+effectively, you must compile your C++ programs with the GNU C++
+compiler, @code{g++}.
+
+For best results when debugging C++ programs, use the stabs debugging
+format. You can select that format explicitly with the @code{g++}
+command-line options @samp{-gstabs} or @samp{-gstabs+}. See
+@ref{Debugging Options,,Options for Debugging Your Program or GNU CC,
+gcc.info, Using GNU CC}, for more information.
@end ifclear
@ifset CONLY
@node C
@end ifset
The file is loaded at whatever address is specified in the executable.
-For some object file formats, like a.out, the object file format fixes
-the address and so it won't necessarily match the address you gave to
-the linker.
+For some object file formats, you can specify the load address when you
+link the program; for other formats, like a.out, the object file format
+specifies a fixed address.
+@c FIXME! This would be a good place for an xref to the GNU linker doc.
@ifset VXWORKS
On VxWorks, @code{load} will dynamically link @var{filename} on the
different name is used to allow you to distinguish the two if you wish.
@end table
+@cindex control C, and remote debugging
+@cindex interrupting remote targets
If you want @value{GDBN} to be able to stop your program while it is
running, you need to use an interrupt-driven serial driver, and arrange
-for it to stop when it receives a control C character (getting it to
-return the proper status to GDB probably requires changes to the
-standard stub; one quick and dirty way is to just execute a breakpoint
-instruction. @value{GDBN} will return a SIGTRAP instead of a SIGINT).
-That is the character which @value{GDBN} uses to tell the remote system
-to stop.
+for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
+character). That is the character which @value{GDBN} uses to tell the
+remote system to stop.
+
+Getting the debugging target to return the proper status to @value{GDBN}
+probably requires changes to the standard stub; one quick and dirty way
+is to just execute a breakpoint instruction (the ``dirty'' part is that
+@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
Other routines you need to supply are:
because it is a much smaller program than @value{GDBN} itself. It is
also easier to port than all of @value{GDBN}, so you may be able to get
started more quickly on a new system by using @code{gdbserver}.
+Finally, if you develop code for real-time systems, you may find that
+the tradeoffs involved in real-time operation make it more convenient to
+do as much development work as possible on another system, for example
+by cross-compiling. You can use @code{gdbserver} to make a similar
+choice for debugging.
@value{GDBN} and @code{gdbserver} communicate via either a serial line
or a TCP connection, using the standard @value{GDBN} remote serial
protocol.
@table @emph
-@item On the target,
+@item On the target machine,
you need to have a copy of the program you want to debug.
@code{gdbserver} does not need your program's symbol table, so you can
strip the program if necessary to save space. @value{GDBN} on the host
system does all the symbol handling.
-To use the server, you must tell it how to communicate with @value{GDB};
+To use the server, you must tell it how to communicate with @value{GDBN};
the name of your program; and the arguments for your program. The
syntax is:
@end smallexample
@var{comm} is either a device name (to use a serial line) or a TCP
-hostname and portnumber. For example, to debug emacs with the argument
+hostname and portnumber. For example, to debug Emacs with the argument
@samp{foo.txt} and communicate with @value{GDBN} over the serial port
@file{/dev/com1}:
expect a TCP connection from machine @samp{host} to local TCP port 2345.
(Currently, the @samp{host} part is ignored.) You can choose any number
you want for the port number as long as it does not conflict with any
-TCP ports already in use on the target system.@footnote{If you choose a
-port number that conflicts with another service, @code{gdbserver} prints
-an error message and exits.} You must use the same port number with the
-host @value{GDBN} @code{target remote} command.
-
-@item On the host,
-you need an unstripped copy of your program, since
-@value{GDBN} needs symbols and debugging information. Start up
-@value{GDBN} as usual, using the name of the local copy of your program
-as the first argument. (You may also need the
-@samp{--baud} option if the serial line is running at anything other than 9600 bps.)
-After that, use @code{target remote} to establish communications with @code{gdbserver}. Its argument is either
-a device name (usually a serial device, like @file{/dev/ttyb}), or a TCP
-port descriptof in the form @code{@var{host}:@var{PORT}}. For example:
+TCP ports already in use on the target system (for example, @code{23} is
+reserved for @code{telnet}).@footnote{If you choose a port number that
+conflicts with another service, @code{gdbserver} prints an error message
+and exits.} You must use the same port number with the host @value{GDBN}
+@code{target remote} command.
+
+@item On the @value{GDBN} host machine,
+you need an unstripped copy of your program, since @value{GDBN} needs
+symbols and debugging information. Start up @value{GDBN} as usual,
+using the name of the local copy of your program as the first argument.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600 bps.) After that, use @code{target
+remote} to establish communications with @code{gdbserver}. Its argument
+is either a device name (usually a serial device, like
+@file{/dev/ttyb}), or a TCP port descriptor in the form
+@code{@var{host}:@var{PORT}}. For example:
@smallexample
(@value{GDBP}) target remote /dev/ttyb
@end smallexample
@noindent
-communicates via a TCP connection to port 2345 on host @file{the-target}.
+communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
For TCP connections, you must start up @code{gdbserver} prior to using
the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
MIPS board attached to a serial line. This is available when
you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
+@noindent
+Use these @value{GDBN} commands to specify the connection to your target board:
+
+@table @code
+@item target mips @var{port}
@kindex target mips @var{port}
To run a program on the board, start up @code{@value{GDBP}} with the
name of your program as the argument. To connect to the board, use the
been downloaded to the board, you may use the @code{load} command to
download it. You can then use all the usual @value{GDBN} commands.
-You can also specify @var{port} as a TCP connection (for instance, to a
-serial line managed by a terminal concentrator), using the syntax
-@code{@var{hostname}:@var{portnumber}}.
+For example, this sequence connects to the target board through a serial
+port, and loads and runs a program called @var{prog} through the
+debugger:
+
+@example
+host$ @value{GDBP} @var{prog}
+GDB is free software and @dots{}
+(gdb) target mips /dev/ttyb
+(gdb) load @var{prog}
+(gdb) run
+@end example
+
+@item target mips @var{hostname}:@var{portnumber}
+On some @value{GDBN} host configurations, you can specify a TCP
+connection (for instance, to a serial line managed by a terminal
+concentrator) instead of a serial port, using the syntax
+@samp{@var{hostname}:@var{portnumber}}.
+@end table
+
+@noindent
+@value{GDBN} also supports these special commands for MIPS targets:
+@table @code
+@item set mipsfpu off
+@itemx show mipsfpu
+@kindex set mipsfpu off
+@kindex show mipsfpu
+@cindex MIPS remote floating point
+@cindex floating point, MIPS remote
+If your target board does not support the MIPS floating point
+coprocessor, you should use the command @samp{set mipsfpu off} (if you
+need this, you may wish to put the command in your @value{GDBINIT}
+file). This tells @value{GDBN} how to find the return value of
+functions which return floating point values. It also allows
+@value{GDBN} to avoid saving the floating point registers when calling
+functions on the board. (As usual, you can inquire about the
+@code{mipsfpu} variable with @samp{show mipsfpu}.)
+
+@item set remotedebug @var{n}
+@itemx show remotedebug
+@kindex set remotedebug
+@kindex show remotedebug
@cindex @code{remotedebug}, MIPS protocol
+@cindex MIPS @code{remotedebug} protocol
@c FIXME! For this to be useful, you must know something about the MIPS
@c FIXME...protocol. Where is it described?
You can see some debugging information about communications with the board
-by setting the @code{remotedebug} variable. If you set it to 1 using
-@samp{set remotedebug 1} every packet will be displayed. If you set it
-to 2 every character will be displayed. You can check the current value
+by setting the @code{remotedebug} variable. If you set it to @code{1} using
+@samp{set remotedebug 1}, every packet is displayed. If you set it
+to @code{2}, every character is displayed. You can check the current value
at any time with the command @samp{show remotedebug}.
+@item set timeout @var{seconds}
+@itemx set retransmit-timeout @var{seconds}
+@itemx show timeout
+@itemx show retransmit-timeout
@cindex @code{timeout}, MIPS protocol
@cindex @code{retransmit-timeout}, MIPS protocol
@kindex set timeout
You can inspect both values with @code{show timeout} and @code{show
retransmit-timeout}. (These commands are @emph{only} available when
@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
-
-@kindex set mipsfpu off
-@cindex MIPS remote floating point
-@cindex floating point, MIPS remote
-If your target board does not support the MIPS floating point
-coprocessor, you should use the command @samp{set mipsfpu off} (you may
-wish to put this in your @value{GDBINIT} file). This tells @value{GDBN}
-how to find the return value of functions which return floating point
-values. It also allows @value{GDBN} to avoid saving the floating point
-registers when calling functions on the board.
+@end table
@end ifset
@ifset SIMS
projects / binutils-gdb.git / commitdiff