included in a translation approved by the author instead of in the
original English.
@end ifinfo
-@c @smallbook
+@smallbook
@setchapternewpage odd
-@settitle Using GDB (v3.94)
+@settitle Using GDB (v4.0)
@iftex
-@finalout
+@c @finalout
@end iftex
@titlepage
@title{Using GDB}
@sp 1
@c Maybe crank this up to "Fourth Edition" when released at FSF
@c @subtitle Third Edition---GDB version 4.0
-@subtitle GDB version 3.94
+@subtitle GDB version 4.0
@subtitle January 1991
@author{Richard M. Stallman}
@author{(Revised by Roland Pesch for Cygnus Support)}
is being implemented, and Fortran support will be added when a GNU
Fortran compiler is written.
+@node Free Software,,,
@unnumberedsec Free Software
GDB is Free Software, protected by the GNU General Public License (GPL).
The GPL gives you the freedom to copy or adapt a licensed
For full details, @pxref{License}.
-@menu
-* New Features:: New Features in GDB version 3.94
-* Invocation:: Starting GDB
-* User Interface:: GDB Commands and Displays
-* Files:: Specifying GDB's Files
-* Compilation:: Compiling Your Program for Debugging
-* Targets:: Specifying a Debugging Target
-* Running:: Running Your Program Under GDB
-* Stopping:: Stopping and Continuing
-* Stack:: Examining the Stack
-* Source:: Examining Source Files
-* Data:: Examining Data
-* Symbols:: Examining the Symbol Table
-* Altering:: Altering Execution
-* Sequences:: Canned Sequences of Commands
-* Emacs:: Using GDB under GNU Emacs
-* Remote:: Remote Debugging
-* GDB Bugs:: Reporting Bugs in GDB
-* Installing GDB:: Installing GDB
-* License:: GNU GENERAL PUBLIC LICENSE
-* Commands:: Command Index
-* Concepts:: Index
-
- --- The Detailed Node Listing ---
-
-Starting GDB
-
-* File Options:: File-specifying Options and Arguments
-* Mode Options:: Mode Options
-* Remote i960-Nindy:: Starting GDB with a Remote Intel 960 (Nindy)
-
-Specifying a Debugging Target
-
-* Active Targets:: Active Targets
-* Target Commands:: Commands for Managing Targets
-
-Running Your Program Under GDB
-
-* Arguments:: Specifying the arguments for your program.
-* Environment:: Specifying the environment for your program.
-* Working Directory:: Specifying the working directory for giving
- to your program when it is run.
-* Input/Output:: Specifying the program's standard input and output.
-* Attach:: Debugging a process started outside GDB.
-* Kill Process:: Getting rid of the child process running your program.
-
-Stopping and Continuing
-
-* Signals:: Fatal signals in your program just stop it;
- then you can use GDB to see what is going on.
-* Breakpoints:: Breakpoints let you stop your program when it
- reaches a specified point in the code.
- an expression changes.
-* Continuing:: Resuming execution until the next signal or breakpoint.
-* Stepping:: Stepping runs the program a short distance and
- then stops it wherever it has come to.
-
-Breakpoints
-
-* Set Breaks:: How to establish breakpoints.
-* Exception Handling:: How GDB supports exception handling for C++.
-* Delete Breaks:: How to remove breakpoints no longer needed.
-* Disabling:: How to disable breakpoints (turn them off temporarily).
-* Conditions:: Making extra conditions on whether to stop.
-* Break Commands:: Commands to be executed at a breakpoint.
-* Error in Breakpoints::
-
-Examining the Stack
-
-* Frames:: Explanation of stack frames and terminology.
-* Backtrace:: Summarizing many frames at once.
-* Selection:: How to select a stack frame.
-* Frame Info:: Information on a Frame
-
-Examining Source Files
-
-* List:: Using the @samp{list} command to print source files.
-* Search:: Commands for searching source files.
-* Source Path:: Specifying the directories to search for source files.
-
-Examining Data
-
-* Expressions:: Expressions that can be computed and printed.
-* Variables:: Using your program's variables in expressions.
-* Arrays:: Examining part of memory as an array.
-* Format options:: Controlling how structures and arrays are printed.
-* Output formats:: Specifying formats for printing values.
-* Auto Display:: Printing certain expressions whenever program stops.
-* Value History:: Referring to values previously printed.
-* Convenience Vars:: Giving names to values for future reference.
-* Registers:: Referring to and storing in machine registers.
-
-Output formats
-
-* Memory:: Examining Memory
-
-Altering Execution
-
-* Assignment:: Altering variable values or memory contents.
-* Jumping:: Altering control flow.
-* Signaling:: Making signals happen in the program.
-* Returning:: Making a function return prematurely.
-* Calling:: Calling functions from your program
-
-Canned Sequences of Commands
-
-* Define:: User-defined commands.
-* Command Files:: Command files.
-* Output:: Controlled output commands useful in
- user-defined commands and command files.
-
-Remote Debugging
-
-* Remote Commands:: Commands used to start and finish remote debugging.
-
-Reporting Bugs in GDB
-
-* Bug Criteria:: Have You Found a Bug?
-* Bug Reporting:: How to Report Bugs
-@end menu
-
@node New Features, Invocation, Top, Top
-@unnumbered New Features in GDB version 3.94
+@unnumbered New Features in GDB version 4.0
@itemize @bullet
@item
29k, Intel 960, and Wind River's VxWorks.
@item
-SHARED LIBRARIES: GDB 3.94 supports SunOS shared libraries.
+SHARED LIBRARIES: GDB 4.0 supports SunOS shared libraries.
@item
WORK IN PROGRESS: kernel debugging for BSD and Mach systems; Tahoe and
gdb program core
@end example
-You can get more detailed control over how GDB starts up using a number
-of command-line options.
+You can get more detailed control over how GDB starts up using some of
+the command-line options.
All the options and command line arguments given are processed
in sequential order. The order makes a difference when the
@samp{-x} option is used.
-@menu
-* File Options:: File-specifying Options and Arguments
-* Mode Options:: Mode Options
-* Remote i960-Nindy:: Starting GDB with a Remote Intel 960 (Nindy)
-@end menu
-
@node File Options, Mode Options, Invocation, Invocation
@section File-specifying Options and Arguments
-As shown in the example, any arguments other
-than options specify an executable file and core file; that is, the
-first argument encountered with no associated option flag is equivalent
-to a @samp{-se} option, and the second, if any, is equivalent to a
-@samp{-c} option.
+As shown above, any arguments other than options specify an executable
+file and core file; that is, the first argument encountered with no
+associated option flag is equivalent to a @samp{-se} option, and the
+second, if any, is equivalent to a @samp{-c} option.
@table @code
@item -s @var{file}
GDB for remote debugging.
@end table
-@node Remote i960-Nindy, , Mode Options, Invocation
-@section Starting GDB with a Remote Intel 960 (Nindy)
+@node i960-Nindy Remote,,,
+@section GDB with a Remote Intel 960 (Nindy)
``Nindy'' is the name of a Rom Monitor program for Intel 960 target
systems. When GDB is configured to control a remote Intel 960 using
The standard @samp{-b} option controls the line speed used on the serial
port.
+@node AMD29K Remote,,,
+@section Starting GDB with a Remote AMD 29K
+
+@cindex EB29K board
+@cindex running 29K programs
+@cindex 29K
+
+To use GDB from a Unix system to run programs on an EB29K
+board in a PC, you must first connect a serial cable between the PC
+and a serial port on the Unix system. In the following, we assume
+you've hooked the cable between the PC's @samp{COM1} port and
+@samp{/dev/ttya} on the Unix system.
+
+@node PC Comms (EB29K),,,
+@subsection PC Communications Setup
+The next step is to set up the PC's port, by doing something like the
+following in DOS on the PC:
+@example
+C> MODE com1:9600,n,8,1,none
+@end example
+@noindent
+This example---run on an MS DOS 4.0 system---sets the PC port to 9600
+bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
+you must match the communications parameters when establishing the Unix
+end of the connection as well.
+@c FIXME: Who knows what this "no retry action" crud from the DOS manual may
+@c mean? It's optional; leave it out? ---pesch@cygnus.com, 25feb91
+
+To give control of the PC to the Unix side of the serial line, type
+the following at the DOS console:
+@example
+C> CTTY com1
+@end example
+@noindent
+(Later, if you wish to return control to the DOS console, you can use
+the command @samp{CTTY con}---but you must send it over the device that
+had control, in our example over the @samp{com1} serial line).
+
+@node Unix Comms (EB29K),,,
+@subsection Unix Communications Setup
+From the Unix host, use a communications program such as @code{tip} or
+@code{cu} to communicate with the PC; for example,
+@example
+cu -s 9600 -l /dev/ttya
+@end example
+@noindent
+The @code{cu} options shown specify, respectively, the linespeed and the
+serial port to use. If you use @code{tip} instead, the corresponding
+parameters must be entered in the ``remote'' descriptions file used by
+@code{tip}---normally the system table @file{/etc/remote}.
+@c FIXME: What if anything needs doing to match the "n,8,1,none" part of
+@c the DOS side's comms setup? cu can support -o (odd
+@c parity), -e (even parity)---apparently no settings for no parity or
+@c for character size. Taken from stty maybe...? John points out tip
+@c can set these as internal variables, eg ~s parity=none; man stty
+@c suggests that it *might* work to stty these options with stdin or
+@c stdout redirected... is it worth experimenting? Maybe if the literal
+@c combinations of things typed here don't work? ---pesch@cygnus.com, 25feb91
+
+@node EBMON,,,
+@subsection Using EBMON
+@kindex EBMON
+Using the @samp{tip} or @samp{cu} connection, change the DOS working
+directory to the directory containing a copy of your 29K program, then
+start the PC program @samp{EBMON} (an EB29K control program supplied
+with your board by AMD):
+@example
+C> CD g:\usr\joe\work29k
+C> EBMON
+@end example
+@c FIXME: insert EBMON banner display here. ---pesch@cygnus.com, 25feb91
+
+Then close the @code{cu} or @code{tip} connection (by typing @samp{~.}
+for example). @code{EBMON} will keep running, ready for GDB to take
+over.
+
+@node 29K Program,,,
+@subsection Your 29K Program
+For this example, we've assumed what is probably the most convenient
+way to make sure the same 29K program is on both the PC and the Unix
+system: a PC/NFS connection that establishes ``drive'' @code{g:} on the
+PC as a file system on the Unix host. If you don't have PC/NFS or
+something similar connecting the two systems, you must arrange some
+other way---perhaps floppy-disk transfer---of getting the 29K program
+from the Unix system to the PC; GDB will @emph{not} download it over the
+serial line.
+
+@node gdb-EB29K
+@subsection EB29K cross-debugging
+Finally, @code{cd} to the directory containing an image of your 29K
+program on the Unix system, and start GDB---specifying as argument the
+name of your 29K program:
+@example
+cd /usr/joe/work29k
+gdb myfoo
+@end example
+Now you can use the @code{target} command:
+@example
+target amd-eb /dev/ttya 9600 MYFOO
+@end example
+@c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
+@c emphasize that this is the name as seen by DOS (since I think DOS is
+@c single-minded about case of letters). ---pesch@cygnus.com, 25feb91
+
+@noindent
+In this example, we've assumed your program is in a file called
+@samp{myfoo}. Note that the filename given as the last argument to
+@samp{target amd-eb} should be the name of the program as it appears to DOS.
+In our example it is simply @samp{MYFOO}, but in general it can include
+a DOS path, and depending on your transfer mechanism may not resemble
+the name on the Unix side.
+
+At this point, you can set any breakpoints you wish; when you're ready
+to see your program run on the 29K board, use the GDB command
+@example
+run
+@end example
+
+To stop debugging the remote program, use the GDB @samp{detach}
+command.
+
+To return control of the PC to its console, use @code{tip} or @code{cu}
+once again, after your GDB session has concluded, to attach to
+@code{EBMON}. You can then type the command @samp{q} to shut down
+@code{EBMON}, returning control to the DOS command-line interpreter.
+Type @samp{CTTY con} to return command input to the main DOS console,
+and type @samp{~.} to leave @code{tip} or @code{cu}.
+
+@node Remote Log, , Remote Commands, Remote
+@subsection Remote Log
+@kindex eb.log
+@cindex log file for EB29K
+The GDB @code{target amd-eb} command creates a file @file{eb.log} in the
+current working directory, to help debug problems with the connection.
+@file{eb.log} records all the output from @code{EBMON}, including echoes
+of the commands sent to it. Running @samp{tail -f} on this file in
+another window often helps to debug trouble with @code{EBMON}, or
+unexpected events on the PC side of the connection.
@node User Interface, Files, Invocation, Top
@chapter GDB Commands and Displays
@node Compilation, Targets, Files, Top
-@chapter Compiling Your Program for Debugging
+@chapter Compiling for Debugging
In order to debug a program effectively, you need to ask for debugging
information when you compile it. This debugging information is stored
kind of file or process.
Often, you will be able to run GDB in the same host environment as the
-program you are debugging; in that case, the debugging target is
+program you are debugging; in that case, the debugging target can just be
specified as a side effect of the @samp{file} or @samp{core} commands.
When you need more flexibility---for example, running GDB on a
physically separate host, controlling standalone systems over a
configuration):
@table @code
-@item target remote @var{dev}
-@kindex target remote
-Remote serial target in gdb-specific protocol. The argument @var{dev}
-specifies what serial device to use for the connection (e.g.
-@code{/dev/ttya}).
-
@item target exec @var{prog}
@kindex target exec
An executable file. @samp{target exec @var{prog}} is the same as
A core dump file. @samp{target core @var{filename}} is the same as
@samp{core-file @var{filename}}.
+@item target remote @var{dev}
+@kindex target remote
+Remote serial target in gdb-specific protocol. The argument @var{dev}
+specifies what serial device to use for the connection (e.g.
+@code{/dev/ttya}).
+
+@item target amd-eb @var{dev} @var{speed} @var{PROG}
+@kindex target amd-eb
+@cindex AMD EB29K
+Remote PC-resident AMD EB29K board, attached over serial lines.
+@var{dev} is the serial device, as for @samp{target remote};
+@samp{speed} allows you to specify the linespeed; and @var{PROG} is the
+name of the program to be debugged, as it appears to DOS on the PC.
+@xref{AMD29K Remote}.
+
@item target nindy @var{devicename}
@kindex target nindy
An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
configuration may have more or fewer targets.
@node Running, Stopping, Targets, Top
-@chapter Running Your Program Under GDB
+@chapter Running Programs Under GDB
@cindex running
@kindex run
breakpoints are conditional, this is even useful (@pxref{Conditions}).
@node Exception Handling, Delete Breaks, Set Breaks, Breakpoints
-@subsection Breakpoints and Exception Handling
+@subsection Breakpoints and Exceptions
@cindex exception handlers
Some languages, such as GNU C++, implement exception handling. GDB
@node Delete Breaks, Disabling, Exception Handling, Breakpoints
@subsection Deleting Breakpoints
-@cindex clearing breakpoints and watchpoints
-@cindex deleting breakpoints and watchpoints
+@cindex clearing breakpoints, watchpoints
+@cindex deleting breakpoints, watchpoints
It is often necessary to eliminate a breakpoint once it has done its job
and you no longer want the program to stop there. This is called
@dfn{deleting} the breakpoint. A breakpoint that has been deleted no
@samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
@node Error in Breakpoints, , Break Commands, Breakpoints
-@subsection ``Cannot Insert Breakpoints'' Error
+@subsection ``Cannot Insert Breakpoints''
+@c FIXME: "cannot insert breakpoints" error, v unclear.
+@c Q in pending mail to Gilmore. ---pesch@cygnus.com, 26mar91
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 will cause GDB
@end ifinfo
@page
-@unnumberedsec How to Apply These Terms to Your New Programs
+@unnumberedsec Applying These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to humanity, the best way to achieve this is to make it
projects / external / binutils.git / commitdiff