diff options
| -rw-r--r-- | gdb/doc/gdb.texinfo | 798 |
1 files changed, 418 insertions, 380 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index b50904a..d017a17 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1,11 +1,29 @@ \input texinfo -@setfilename gdb.info +@setfilename _GDBP__.info +@c +@c NOTE: this manual is marked up for preprocessing with a collection +@c of m4 macros called "pretex.m4". If you see <_if__> and <_fi__> +@c scattered around the source, you have the full source before +@c preprocessing; if you don't, you have the source configured for +@c _HOST__ architectures (and you can of course get the full source, +@c with all configurations, from wherever you got this). +_if__(0) + +THIS IS THE FULL SOURCE. The full source needs to be run through m4 +before either tex- or info- formatting: for example, + m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo +will produce (assuming your path finds either GNU or SysV m4; Berkeley +won't do) a file suitable for formatting. See the text in "pretex.m4" +for a fuller explanation (and the macro definitions). + +_fi__(0) +@c @synindex ky cp @c FOR UPDATES LEADING TO THIS DRAFT, GDB CHANGELOG CONSULTED BETWEEN: @c Tue Feb 26 01:47:07 1991 Cygnus John Gilmore (cygnus at yuba) @c Sat Dec 22 02:51:40 1990 John Gilmore (gnu at cygint) @ifinfo -This file documents the GNU debugger GDB. +This file documents the GNU debugger _GDBN__. Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc. @@ -35,20 +53,28 @@ original English. @end ifinfo @smallbook @setchapternewpage odd -@settitle Using GDB (v4.0) +_if__(_GENERIC__) +@settitle Using _GDBN__ (v4.0) +_fi__(_GENERIC__) +_if__(!_GENERIC__) +@settitle Using _GDBN__ v4.0 (_HOST__) +_fi__(!_GENERIC__) @iftex @c @finalout @end iftex @titlepage -@title{Using GDB} +@title{Using _GDBN__} @subtitle{A Guide to the GNU Source-Level Debugger} +_if__(!_GENERIC__) +@subtitle{On _HOST__ Systems} +_fi__(!_GENERIC__) @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 4.0 +@c @subtitle Third Edition---_GDBN__ version 4.0 +@subtitle _GDBN__ version 4.0 @subtitle January 1991 @author{Richard M. Stallman} -@author{(Revised by Roland Pesch for Cygnus Support)} +@author{Roland H. Pesch (Cygnus Support)} @page @tex @@ -84,14 +110,13 @@ original English. @page @node Top, New Features, (dir), (dir) -@unnumbered Summary of GDB +@unnumbered Summary of _GDBN__ -The purpose of a debugger such as GDB is to allow you to see what is +The purpose of a debugger such as _GDBN__ is to allow you to see what is going on ``inside'' another program while it executes---or what another -program was doing at the moment it crashed. We call the other program -``your program'' or ``the program being debugged''. +program was doing at the moment it crashed. -GDB can do four main kinds of things (plus other things in support of +_GDBN__ can do four main kinds of things (plus other things in support of these) to help you catch bugs in the act: @enumerate @@ -109,13 +134,13 @@ Change things in your program, so you can experiment with correcting the effects of one bug and go on to learn about another. @end enumerate -GDB can be used to debug programs written in C and C++. Pascal support +_GDBN__ can be used to debug programs written in C and C++. Pascal support is being implemented, and Fortran support will be added when a GNU -Fortran compiler is written. +Fortran compiler is ready. @node Free Software,,, @unnumberedsec Free Software -GDB is Free Software, protected by the GNU General Public License (GPL). +_GDBN__ is Free Software, protected by the 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 freedom to modify that copy (which means that they must get access to @@ -130,25 +155,25 @@ from anyone else. For full details, @pxref{License}. @node New Features, Invocation, Top, Top -@unnumbered New Features in GDB version 4.0 +@unnumbered New Features in _GDBN__ version 4.0 @itemize @bullet @item TARGETS: Using the new command @samp{target}, you can select at runtime whether you are debugging local files, local processes, standalone systems over the serial port, realtime systems over a TCP/IP -connection, etc. GDB now uses a function vector to mediate access to +connection, etc. _GDBN__ now uses a function vector to mediate access to all the different possible targets, making it much easier to add support for new remote protocols. @item -WATCHPOINTS: GDB now sports watchpoints as well as breakpoints. You can +WATCHPOINTS: _GDBN__ now sports watchpoints as well as breakpoints. You can use a watchpoint to stop execution whenever the value of an expression changes, without having to predict a particular place in the inferior process where this may happen. @item -OBJECT CODE FORMATS: GDB uses a new scheme called Binary File +OBJECT CODE FORMATS: _GDBN__ uses a new scheme called Binary File Descriptors (BFD) to permit it to switch dynamically, without reconfiguration or recompilation, between different object-file formats. Formats currently supported are COFF, a.out, and the new @@ -159,35 +184,35 @@ are being converted to use it. @item CONFIGURATION: You must still choose a particular machine architecture -and operating system for GDB's host and target systems when GDB is built. +and operating system for _GDBN__'s host and target systems when _GDBN__ is built. The script @samp{config.gdb} now handles specification of separate host and target configurations. @item -INTERACTION: GDB now uses the GNU @code{readline} interface to read its +INTERACTION: _GDBN__ now uses the GNU @code{readline} interface to read its input; this provides inline editing of commands, using the familiar -Emacs or VI keymaps, and command-history support. The user interface -to GDB's control variables has been simplified and consolidated in two +Emacs or @code{vi} keymaps, and command-history support. The user interface +to _GDBN__'s control variables has been simplified and consolidated in two commands, @samp{set} and @samp{show}. Output lines are now broken at readable places, rather than overflowing onto the next line. @item -SOURCE LANGUAGE: GDB now understands C++ source as well as C. Multiple +SOURCE LANGUAGE: _GDBN__ now understands C++ source as well as C. Multiple inheritance is supported when used with G++ 2.0. There is also limited -support for C++ exception handling: GDB can break when an exception is +support for C++ exception handling: _GDBN__ can break when an exception is raised, before the stack is peeled back to the exception handler's context. You can suppress output of machine-level addresses, displaying only source language information. @item -PORTS: GDB has been ported to the following new architectures: +PORTS: _GDBN__ has been ported to the following new architectures: AT&T 3b1, Acorn RISC machine, HP300 running HPUX, big- and little- endian MIPS machines, Motorola 88k, Sun 386i, and Sun 3 running SunOS 4. In addition, the following are supported as targets only: AMD 29k, Intel 960, and Wind River's VxWorks. @item -SHARED LIBRARIES: GDB 4.0 supports SunOS shared libraries. +SHARED LIBRARIES: _GDBN__ 4.0 supports SunOS shared libraries. @item WORK IN PROGRESS: kernel debugging for BSD and Mach systems; Tahoe and @@ -196,23 +221,23 @@ HPPA architecture support. @end itemize @node Invocation, User Interface, New Features, Top -@chapter Starting GDB +@chapter Starting _GDBN__ -GDB is invoked with the shell command @samp{gdb}. Once started, it reads +_GDBN__ is invoked with the shell command @samp{_GDBP__}. Once started, it reads commands from the terminal until you tell it to exit. -The most usual way to start GDB is with one argument or two, specifying +The most usual way to start _GDBN__ is with one argument or two, specifying an executable program as the argument: @example -gdb program +_GDBP__ program @end example @noindent or you can start with both an executable program and a core file specified: @example -gdb program core +_GDBP__ program core @end example -You can get more detailed control over how GDB starts up using some of +You can get more detailed control over how _GDBN__ starts up using some of the command-line options. All the options and command line arguments given are processed @@ -220,7 +245,7 @@ in sequential order. The order makes a difference when the @samp{-x} option is used. @node File Options, Mode Options, Invocation, Invocation -@section File-specifying Options and Arguments +@section Options and Arguments to Choose Files As shown above, any arguments other than options specify an executable file and core file; that is, the first argument encountered with no @@ -244,18 +269,18 @@ file. Use file @var{file} as a core dump to examine. @item -x @var{file} -Execute GDB commands from file @var{file}. @xref{Command Files}. +Execute _GDBN__ commands from file @var{file}. @xref{Command Files}. @item -d @var{directory} Add @var{directory} to the path to search for source files. @end table @node Mode Options, Remote i960-Nindy, File Options, Invocation -@section Mode Options +@section Options to Choose Modes @table @code @item -nx -Do not execute commands from the init files @file{.gdbinit}. +Do not execute commands from the init files @file{._GDBP__init}. Normally, the commands in these files are executed after all the command options and arguments have been processed. @xref{Command Files}. @@ -263,45 +288,46 @@ Files}. @item -q ``Quiet''. Do not print the introductory and copyright messages. These messages are also suppressed in batch mode, or if an executable file name is -specified on the GDB command line. +specified on the _GDBN__ command line. @item -batch Run in batch mode. Exit with code @code{0} after processing all the command -files specified with @samp{-x} (and @file{.gdbinit}, if not inhibited). -Exit with nonzero status if an error occurs in executing the GDB +files specified with @samp{-x} (and @file{._GDBP__init}, if not inhibited). +Exit with nonzero status if an error occurs in executing the _GDBN__ commands in the command files. -Batch mode may be useful for running GDB as a filter, for example to +Batch mode may be useful for running _GDBN__ as a filter, for example to download and run a program on another computer; in order to make this more useful, the message @example Program exited normally. @end example @noindent -(which is ordinarily issued whenever a program running under GDB control +(which is ordinarily issued whenever a program running under _GDBN__ control terminates) is not issued when running in batch mode. @item -fullname -This option is used when Emacs runs GDB as a subprocess. It tells GDB +This option is used when Emacs runs _GDBN__ as a subprocess. It tells _GDBN__ to output the full file name and line number in a standard, recognizable fashion each time a stack frame is displayed (which includes each time the program stops). This recognizable format looks like two @samp{\032} characters, followed by the file name, line number and character position separated by colons, and a newline. The -Emacs-to-GDB interface program uses the two @samp{\032} characters as +Emacs-to-_GDBN__ interface program uses the two @samp{\032} characters as a signal to display the source code for the frame. @item -b @var{bps} Set the line speed (baud rate or bps) of any serial interface used by -GDB for remote debugging. +_GDBN__ for remote debugging. @end table +_if__(_I960__) @node i960-Nindy Remote,,, -@section GDB with a Remote Intel 960 (Nindy) +@section _GDBN__ 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 -Nindy, you can tell GDB how to connect to the 960 in several ways: +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: @itemize @bullet @item @@ -311,12 +337,15 @@ Through command line options specifying device, baud rate, and protocol; By responding to a prompt on startup; @item -By using the @samp{target} command at any point during your GDB session. +By using the @samp{target} command at any point during your _GDBN__ session. @end itemize +@node Nindy Startup,,, +@subsection Startup with Nindy + The command-line options for Nindy are detailed below. If you simply -start @code{gdb960} without using options to specify a serial port, you are -prompted for it, @emph{before} you reach the ordinary GDB prompt: +start @code{_GDBP__} without using options to specify a serial port, you are +prompted for it, @emph{before} you reach the ordinary _GDBN__ prompt: @example Attach /dev/ttyNN -- specify NN, or "quit" to quit: @end example @@ -325,36 +354,39 @@ You can, if you choose, simply start up with no Nindy connection by responding to the prompt with an empty line. If you do this, and later wish to attach to Nindy, use @samp{target} (@pxref{Target Commands}). -These are the startup options for beginning your GDB session with a +@node Nindy Options,,, +@subsection Options for Nindy + +These are the startup options for beginning your _GDBN__ session with a Nindy-960 board attached: @table @code @item -r @var{port} Specify the serial port name of a serial interface to be used to connect -to the target system. This option is only available when GDB is +to the target system. This option is only available when _GDBN__ is configured for the Intel 960 target architecture. You may specify @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a device name in @samp{/dev} (e.g. @samp{-r ttya}), or simply the unique suffix for a specific @code{tty} (e.g. @samp{-r a}). @item -O -(An uppercase letter ``O'', not a zero.) Specify that GDB should use +(An uppercase letter ``O'', not a zero.) Specify that _GDBN__ should use the ``old'' Nindy monitor protocol to connect to the target system. -This option is only available when GDB is configured for the Intel 960 +This option is only available when _GDBN__ is configured for the Intel 960 target architecture. @quotation @emph{Warning:} if you specify @samp{-O}, but are actually trying to connect to a target system using the current protocol, the connection -will fail appearing to be a speed mismatch, and GDB will repeatedly +will fail appearing to be a speed mismatch, and _GDBN__ will repeatedly attempt to reconnect at several different line speeds. You can abort this process with an interrupt. @end quotation @item -brk -Specify that GDB should first send a @samp{BREAK} signal to the target +Specify that _GDBN__ should first send a @samp{BREAK} signal to the target system, in an attempt to reset it, before connecting to a Nindy target. -This option is only available when GDB is configured for the Intel 960 +This option is only available when _GDBN__ is configured for the Intel 960 target architecture. @quotation @@ -366,22 +398,24 @@ requires; it only works with a few boards. The standard @samp{-b} option controls the line speed used on the serial port. +_fi__(_I960__) -@node AMD29K Remote,,, -@section Starting GDB with a Remote AMD 29K +_if__(_AMD29K__) +@node EB29K Remote,,, +@section Starting _GDBN__ with a Remote EB29K @cindex EB29K board @cindex running 29K programs @cindex 29K -To use GDB from a Unix system to run programs on an EB29K +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 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 +@node Comms (EB29K),,, +@subsection 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 @@ -405,8 +439,6 @@ C> CTTY com1 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 @@ -426,8 +458,6 @@ parameters must be entered in the ``remote'' descriptions file used by @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 @@ -436,32 +466,31 @@ 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 +C> ~. +@end example -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. +Then exit the @code{cu} or @code{tip} program (done in the example by +typing @code{~.}). @code{EBMON} will keep running, ready for _GDBN__ 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 +from the Unix system to the PC; _GDBN__ will @emph{not} download it over the serial line. -@node gdb-EB29K +@node _GDBP__-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 +program on the Unix system, and start _GDBN__---specifying as argument the name of your 29K program: @example cd /usr/joe/work29k -gdb myfoo +_GDBP__ myfoo @end example Now you can use the @code{target} command: @example @@ -480,16 +509,16 @@ 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 +to see your program run on the 29K board, use the _GDBN__ command @example run @end example -To stop debugging the remote program, use the GDB @samp{detach} +To stop debugging the remote program, use the _GDBN__ @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 +once again, after your _GDBN__ 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, @@ -499,17 +528,18 @@ and type @samp{~.} to leave @code{tip} or @code{cu}. @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 +The @samp{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. +_fi__(_AMD29K__) @node User Interface, Files, Invocation, Top -@chapter GDB Commands and Displays +@chapter _GDBN__ Commands and Displays -A GDB command is a single line of input. There is no limit on how long +A _GDBN__ command is a single line of input. There is no limit on how long it can be. It starts with a command name, which is followed by arguments whose meaning depends on the command name. For example, the command @samp{step} accepts an argument which is the number of times to step, @@ -517,7 +547,7 @@ as in @samp{step 5}. You can also use the @samp{step} command with no arguments. Some command names do not allow any arguments. @cindex abbreviation -GDB command names may always be truncated if that abbreviation is +_GDBN__ command names may always be truncated if that abbreviation is unambiguous. Other possible command abbreviations are listed in the documentation of the individual commands. Sometimes even ambiguous abbreviations are allowed; for example, @samp{s} is specially defined as @@ -525,7 +555,7 @@ equivalent to @samp{step} even though there are other commands whose names start with @samp{s}. @cindex repeating commands -A blank line as input to GDB means to repeat the previous command. +A blank line as input to _GDBN__ means to repeat the previous command. Certain commands will not repeat this way; these are commands for which unintentional repetition might cause trouble and which you are unlikely to want to repeat. Certain others (@samp{list} and @samp{x}) act @@ -542,7 +572,7 @@ This is useful mainly in command files (@xref{Command Files}). @item help @itemx help @var{category} @itemx help @var{command} -You can always ask GDB itself for information on its commands, using the +You can always ask _GDBN__ itself for information on its commands, using the command @samp{help}. With a command name as argument, it will display a paragraph on how to use the command. Used with no arguments, @samp{help} displays a short list of named categories of commands; you @@ -551,49 +581,49 @@ in a category. @kindex info version @item info version -As GDB evolves, new commands are introduced, and old ones may wither -away. If multiple versions of GDB are in use at your site, it may -occasionally be useful to make sure what version of GDB you're running. -GDB announces its version whenever it starts up; but you can make it +As _GDBN__ evolves, new commands are introduced, and old ones may wither +away. If multiple versions of _GDBN__ are in use at your site, it may +occasionally be useful to make sure what version of _GDBN__ you're running. +_GDBN__ announces its version whenever it starts up; but you can make it repeat this information with the @samp{info version} command. @end table @cindex prompt -GDB indicates its readiness to read a command by printing a string -called the @dfn{prompt}. This string is normally @samp{(gdb)}. You can +_GDBN__ indicates its readiness to read a command by printing a string +called the @dfn{prompt}. This string is normally @samp{(_GDBP__)}. You can change the prompt string with the @samp{set prompt} command. For -instance, when debugging GDB with GDB, it is useful to change the prompt -in one of the GDBs so that you tell which one you are talking to. +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. @table @code @item set prompt @var{newprompt} @kindex set prompt -Directs GDB to use @var{newprompt} as its prompt string henceforth. +Directs _GDBN__ to use @var{newprompt} as its prompt string henceforth. @kindex show prompt @item show prompt Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} @end table -@cindex exiting GDB +@cindex exiting _GDBN__ @kindex quit -To exit GDB, use the @samp{quit} command (abbreviated @samp{q}), or type +To exit _GDBN__, use the @samp{quit} command (abbreviated @samp{q}), or type an end-of-file character (usually @ctrl{d}). An interrupt (often -@ctrl{c}) will not exit from GDB, but rather will terminate the action -of any GDB command that is in progress and return to GDB command level. -It is safe to type the interrupt character at any time because GDB does +@ctrl{c}) will not exit from _GDBN__, but rather will terminate the action +of any _GDBN__ command that is in progress and return to _GDBN__ command level. +It is safe to type the interrupt character at any time because _GDBN__ does not allow it to take effect until a time when it is safe. @cindex readline @cindex command line editing @cindex history substitution -GDB reads its input commands via the @code{readline} interface. This +_GDBN__ reads its input commands via the @code{readline} interface. This GNU library provides consistent behavior for programs which provide a command line interface to the user. Advantages are @samp{emacs}-style or @samp{vi}-style inline editing of commands, @samp{csh}-like history substitution, and a storage and recall of command history across debugging sessions. -You may control the behavior of command line editing in GDB with the +You may control the behavior of command line editing in _GDBN__ with the command @samp{set}. You may check the status of any of these settings with the command @samp{show}. @@ -614,8 +644,8 @@ Show whether command line editing is enabled. @cindex history file @kindex set history file @item set history file @var{filename} -Set the name of the GDB command history file to @samp{filename}. This is -the file from which GDB will read an initial command history +Set the name of the _GDBN__ command history file to @samp{filename}. This is +the file from which _GDBN__ will read an initial command history list or to which it will write this list when it exits. This list is accessed through history expansion or through the history command editing characters listed below. This file defaults to the @@ -626,16 +656,16 @@ value of the environmental variable @code{GDBHISTFILE}, or to @kindex set history write @item set history write @itemx set history write on -Make GDB record command history in a file, whose name may be specified with the +Make _GDBN__ record command history in a file, whose name may be specified with the @samp{set history file} command. By default, this option is disabled. @item set history write off -Make GDB stop recording command history in a file. +Make _GDBN__ stop recording command history in a file. @cindex history size @kindex set history size @item set history size @var{size} -Set the number of commands which GDB will keep in its history list. +Set the number of commands which _GDBN__ will keep in its history list. This defaults to the value of the environmental variable @code{HISTSIZE}, or to 256 if this variable is not set. @end table @@ -673,14 +703,14 @@ or @samp{vi} may wish to read it. @xref{Command Line Editing}. @itemx show history write @itemx show history size @itemx show history expansion -These commands display the state of the GDB history parameters. +These commands display the state of the _GDBN__ history parameters. @samp{show history} by itself displays all four states. @kindex show @kindex info set @item show @itemx info set -This chapter introduces a number of internal GDB variables that you +This chapter introduces a number of internal _GDBN__ variables that you can control with the @samp{set} command, and display with the @samp{show} command. A number of others are introduced throughout the manual. To display all the settable parameters and their current @@ -702,41 +732,41 @@ Print ten commands just after the commands last printed. @end table -Occasionally it is useful to execute a shell command from within GDB. +Occasionally it is useful to execute a shell command from within _GDBN__. This can be done with the @samp{shell} command. @table @code @item shell @var{command string} @kindex shell @cindex shell escape -Directs GDB to invoke an inferior shell to execute @var{command string}. -The environment variable @code{SHELL} is used if it exists, otherwise GDB +Directs _GDBN__ to invoke an inferior shell to execute @var{command string}. +The environment variable @code{SHELL} is used if it exists, otherwise _GDBN__ uses @samp{/bin/sh}. @end table The utility @samp{make} is often needed in development environments. -You don't have to use the @samp{shell} command for this purpose in GDB: +You don't have to use the @samp{shell} command for this purpose in _GDBN__: @table @code @item make @dots{} @kindex make @cindex calling make -Causes GDB to execute an inferior @code{make} program with the specified +Causes _GDBN__ to execute an inferior @code{make} program with the specified arguments. This is equivalent to @samp{shell make @dots{}}. @end table @cindex screen size @cindex pauses in output -Certain commands to GDB may produce large amounts of information output -to the screen. To help you read all of it, GDB pauses and asks you for +Certain commands to _GDBN__ may produce large amounts of information output +to the screen. To help you read all of it, _GDBN__ pauses and asks you for input at the end of each page of output. Type @key{RET} when you want -to continue the output. Normally GDB knows the size of the screen from +to continue the output. Normally _GDBN__ knows the size of the screen from the termcap data base together with the value of the @code{TERM} environment variable and the @code{stty rows} and @code{stty cols} settings. If this is not correct, you can override it with the @samp{set screen-height} and @samp{set screen-width} commands: -GDB also uses the screen width setting to determine when to wrap lines +_GDBN__ also uses the screen width setting to determine when to wrap lines of output. Depending what is being printed, it tries to break the line at a readable place, rather than simply letting it overflow onto the following line. @@ -754,14 +784,14 @@ These @samp{set} commands specify a screen height of @var{lpp} lines and a screen width of @var{cpl} characters. The associated @samp{show} commands display the current settings. -If you specify a height of zero lines, GDB will not pause during output +If you specify a height of zero lines, _GDBN__ will 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. @end table @cindex number representation @cindex entering numbers -You can always enter numbers in octal, decimal, or hexadecimal in GDB by +You can always enter numbers in octal, decimal, or hexadecimal in _GDBN__ by the usual conventions: octal numbers begin with @samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}. Numbers that begin with none of these are, by default, entered in base @@ -793,9 +823,9 @@ Display the current default base for numeric input and display. @end table -By default, GDB is silent about its inner workings. If you are running +By default, _GDBN__ is silent about its inner workings. If you are running on a slow machine, you may want to use the @samp{set verbose} command. -It will make GDB tell you when it does a lengthy internal operation, so +It will make _GDBN__ tell you when it does a lengthy internal operation, so you won't think it has crashed. Currently, the messages controlled by @samp{set verbose} are those which @@ -812,17 +842,17 @@ see @samp{symbol-file} in @ref{Files}). @table @code @kindex set verbose @item set verbose on -Enables GDB's output of certain informational messages. +Enables _GDBN__'s output of certain informational messages. @item set verbose off -Disables GDB's output of certain informational messages. +Disables _GDBN__'s output of certain informational messages. @kindex show verbose @item show verbose Displays whether @samp{set verbose} is on or off. @end table -By default, if GDB encounters bugs in the symbol table of an object file, +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 message to be printed if you want to see how frequent the problems are. @@ -831,22 +861,22 @@ message to be printed if you want to see how frequent the problems are. @table @code @kindex set complaints @item set complaints @var{limit} -Permits GDB to output @var{limit} complaints about each type of unusual +Permits _GDBN__ to output @var{limit} complaints about each type of unusual symbols before becoming silent about the problem. Set @var{limit} to zero to suppress all complaints; set it to a large number to prevent complaints from being suppressed. @kindex show complaints @item show complaints -Displays how many symbol complaints GDB is permitted to produce. +Displays how many symbol complaints _GDBN__ is permitted to produce. @end table -By default, GDB is cautious, and asks what sometimes seem to be a lot of +By default, _GDBN__ is cautious, and asks what sometimes seem to be a lot of stupid questions. For example, if you try to run a program which is already running: @example -(gdb) run +(_GDBP__) run The program being debugged has been started already. Start it from the beginning? (y or n) @end example @@ -870,23 +900,23 @@ Displays state of cautious questions. @end table @node Files, Compilation, User Interface, Top -@chapter Specifying GDB's Files +@chapter Specifying _GDBN__'s Files @cindex core dump file @cindex executable file @cindex symbol table -GDB needs to know the file name of the program to be debugged, both in +_GDBN__ needs to know the file name of the program to be debugged, both in order to read its symbol table and in order to start the program. To -debug a core dump of a previous run, GDB must be told the file name of +debug a core dump of a previous run, _GDBN__ must be told the file name of the core dump. The usual way to specify the executable and core dump file names is with -the command arguments given when you start GDB, as discussed in +the command arguments given when you start _GDBN__, as discussed in @pxref{Invocation}. But occasionally it is necessary to change to a different file during a -GDB session. Or you may run GDB and forget to specify the files you -want to use. In these situations the GDB commands to specify new files +_GDBN__ session. Or you may run _GDBN__ and forget to specify the files you +want to use. In these situations the _GDBN__ commands to specify new files are useful. @table @code @@ -895,7 +925,7 @@ are useful. Use @var{filename} as the program to be debugged. It is read for its symbols, for getting the contents of pure memory, and it is the program executed when you use the @samp{run} command. If you do not specify a -directory and the file is not found in GDB's working directory, GDB will +directory and the file is not found in _GDBN__'s working directory, _GDBN__ will use the environment variable @code{PATH} as a list of directories to search, just as the shell does when looking for a program to run. @@ -905,7 +935,7 @@ table become unspecified. @item exec-file @var{filename} @kindex exec-file Specify that the program to be run (but not the symbol table) is found -in @var{filename}. GDB will search the environment variable @code{PATH} +in @var{filename}. _GDBN__ will search the environment variable @code{PATH} if necessary to locate the program. @item symbol-file @var{filename} @@ -914,14 +944,14 @@ Read symbol table information from file @var{filename}. @code{PATH} is searched when necessary. Use the @samp{file} command to get both symbol table and program to run from the same file. -@samp{symbol-file} with no argument clears out GDB's information on your +@samp{symbol-file} with no argument clears out _GDBN__'s information on your program's symbol table. -The @samp{symbol-file} command causes GDB to forget the contents of its +The @samp{symbol-file} command causes _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 -the old symbol table data being discarded inside GDB. +the old symbol table data being discarded inside _GDBN__. On some kinds of object files, the @samp{symbol-file} command does not actually read the symbol table in full right away. Instead, it scans @@ -929,7 +959,7 @@ the symbol table quickly to find which source files and which symbols are present. The details are read later, one source file at a time, when they are needed. -The purpose of this two-stage reading strategy is to make GDB start up +The purpose of this two-stage reading strategy is to make _GDBN__ start up faster. For the most part, it is invisible except for occasional pauses while the symbol table details for a particular source file are being read. (The @samp{set verbose} command can turn these pauses into @@ -939,14 +969,14 @@ When the symbol table is stored in COFF format, @samp{symbol-file} does read the symbol table data in full right away. We haven't implemented the two-stage strategy for COFF yet. -When GDB is configured for a particular environment, it will understand +When _GDBN__ is configured for a particular environment, it will understand debugging information in whatever format is the standard generated for -that environment; you may use either the GNU compiler GCC, or other +that environment; you may use either the GNU compiler _GCC__, or other compilers that adhere to the local conventions. Best results are -usually obtained from GCC; for example, using GCC you can generate +usually obtained from _GCC__; for example, using _GCC__ you can generate debugging information for optimized code. -While the symbol file is being read, GDB will occasionally encounter +While the symbol file is being read, _GDBN__ will occasionally encounter problems, such as symbol types it does not recognize, or known bugs in compiler output. By default, it prints one message about each such type of problem, no matter how many times the problem occurs. You can @@ -962,7 +992,7 @@ The messages currently printed, and their meanings, are: The symbol information shows where symbol scopes begin and end (such as at the start of a function or a block of statements). This error indicates that an inner scope block is not fully contained -in its outer scope blocks. GDB circumvents the problem by treating +in its outer scope blocks. _GDBN__ circumvents the problem by treating the inner block as if it had the same scope as the outer block. @var{symbol} may be ``(don't know)'' if the outer block is not a function. @@ -971,7 +1001,7 @@ a function. The symbol information for symbol scope blocks should occur in order of increasing addresses. This error indicates that it does not -do so. GDB does not circumvent this problem, and will have trouble +do so. _GDBN__ does not circumvent this problem, and will have trouble locating symbols in the source file whose symbols being read. (You can often determine what source file is affected by turning on @samp{info verbose}. @xref{User Interface}.) @@ -980,13 +1010,13 @@ can often determine what source file is affected by turning on The symbol information for a symbol scope block has a start address smaller than the address of the preceding source line. This is known -to occur in the SunOS 4.1.1 (and earlier) C compiler. GDB circumvents +to occur in the SunOS 4.1.1 (and earlier) C compiler. _GDBN__ circumvents the problem by treating the symbol scope block as starting on the previous source line. @comment @item{encountered DBX-style class variable debugging information. @comment You seem to have compiled your program with "g++ -g0" instead of "g++ -g". -@comment Therefore GDB will not know about your class variables} +@comment Therefore _GDBN__ will not know about your class variables} @comment @comment This error indicates that the symbol information produced for a C++ @comment program includes zero-size fields, which indicated static fields in @@ -996,18 +1026,18 @@ previous source line. @item bad string table offset in symbol @var{n} Symbol number @var{n} contains a pointer into the string table which is -larger than the size of the string table. GDB circumvents the problem +larger than the size of the string table. _GDBN__ circumvents the problem by considering the symbol to have the name @code{foo}, which may cause other problems if many symbols end up with this name. @cindex{foo} @item unknown symbol type @code{0xNN} -The symbol information contains new data types that GDB does not yet +The symbol information contains new data types that _GDBN__ does not yet know how to read. @code{0xNN} is the symbol type of the misunderstood -information, in hexadecimal. GDB circumvents the error by ignoring +information, in hexadecimal. _GDBN__ circumvents the error by ignoring this symbol information. This will usually allow the program to be debugged, though certain symbols will not be accessible. If you -encounter such a problem and feel like debugging it, you can debug gdb +encounter such a problem and feel like debugging it, you can debug _GDBP__ with itself, breakpoint on "complain", then go "up" to read_dbx_symtab() and examine *bufp to see the symbol. @@ -1033,14 +1063,14 @@ for some C++ object. @kindex core-file Specify the whereabouts of a core dump file to be used as the ``contents of memory''. Traditionally, core files contain only some parts of the -address space of the process that generated them; GDB can access the +address space of the process that generated them; _GDBN__ can access the executable file itself for other parts. @samp{core-file} with no argument specifies that no core file is to be used. Note that the core file is ignored when your program is actually running -under GDB. So, if you have been running the program and you wish to +under _GDBN__. So, if you have been running the program and you wish to debug a core file instead, you must kill the subprocess in which the program is running. To do this, use the @samp{kill} command (@pxref{Kill Process}). @@ -1058,13 +1088,13 @@ The @samp{add-syms} command reads additional symbol table information from the file @var{filename}. You would use this command when that file 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; GDB cannot figure this out for itself. +file has been loaded; _GDBN__ cannot figure this out for itself. The symbol table of the file @var{filename} is added to the symbol table originally read with the @samp{symbol-file} command. You can use the @samp{add-syms} command any number of times; the new symbol data thus read keeps adding to the old. The @samp{symbol-file} command forgets -all the symbol data GDB has read. +all the symbol data _GDBN__ has read. @item info files @itemx info target @@ -1072,7 +1102,7 @@ all the symbol data GDB has read. @kindex info target @samp{info files} and @samp{info target} are synonymous; both print the current targets (@pxref{Targets}), including the names of the -executable and core dump files currently in use by GDB, and the files +executable and core dump files currently in use by _GDBN__, and the files from which symbols were loaded. Beware: the similar command @samp{info targets} lists all possible @@ -1081,14 +1111,14 @@ targets rather than current ones. @end table While all three file-specifying commands allow both absolute and relative -file names as arguments, GDB always converts the file name to an absolute +file names as arguments, _GDBN__ always converts the file name to an absolute one and remembers it that way. @kindex sharedlibrary @kindex share @cindex shared libraries -GDB supports the SunOS shared library format. Symbols from a shared +_GDBN__ supports the SunOS shared library format. Symbols from a shared library cannot be referenced before the shared library has been linked with the program. (That is to say, after one types @samp{run} and the function @code{main()} has been entered; or when examining core @@ -1137,20 +1167,20 @@ correct, but there's no sense in pushing your luck. Some things do not work as well with @samp{-g -O} as with just @samp{-g}, particularly on machines with instruction scheduling. If in doubt, recompile with @samp{-g} alone, and if this fixes the problem, -please report it as a bug (including a test case---@pxref{GDB Bugs}). +please report it as a bug (including a test case---@pxref{_GDBN__ Bugs}). -Older versions of the GNU C compiler, GCC, permitted a variant option -@samp{-gg} for debugging information. GDB no longer supports this format; +Older versions of the GNU C compiler, _GCC__, permitted a variant option +@samp{-gg} for debugging information. _GDBN__ no longer supports this format; if your GNU C compiler has this option, do not use it. @ignore -@comment As far as I know, there are no cases in which GDB will +@comment As far as I know, there are no cases in which _GDBN__ will @comment produce strange output in this case. (but no promises). If your program includes archives made with the @code{ar} program, and if the object files used as input to @code{ar} were compiled without the -@samp{-g} option and have names longer than 15 characters, GDB will get +@samp{-g} option and have names longer than 15 characters, _GDBN__ will get confused reading the program's symbol table. No error message will be -given, but GDB may behave strangely. The reason for this problem is a +given, but _GDBN__ may behave strangely. The reason for this problem is a deficiency in the Unix archive file format, which cannot represent file names longer than 15 characters. @@ -1166,10 +1196,10 @@ option or use shorter file names. Alternatively, use a version of GNU A @dfn{target} is an interface between the debugger and a particular kind of file or process. -Often, you will be able to run GDB in the same host environment as the +Often, you will be able to run _GDBN__ in the same host environment as the 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 +When you need more flexibility---for example, running _GDBN__ on a physically separate host, controlling standalone systems over a serial port, or realtime systems over a TCP/IP connection---you can use the @samp{target} command. @@ -1191,7 +1221,7 @@ allows you to (for example) start a process and inspect its activity without abandoning your work on a core file. More than one target can potentially respond to a request. In -particular, when you access memory GDB will walk down the three strata of +particular, when you access memory _GDBN__ will walk down 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 @@ -1210,7 +1240,7 @@ choosing a particular running process as a new target. @xref{Attach}. @table @code @item target @var{type} @var{parameters} -Connects the GDB host environment to a target machine or process. A +Connects the _GDBN__ host environment to a target machine or process. A target is typically a protocol for talking to debugging facilities. You use the argument @var{type} to specify the type or protocol of the target machine; for example, @samp{target vxworks} for a TCP/IP link to @@ -1235,7 +1265,7 @@ all available ones. @samp{info files} gives the same information as @samp{info target} (@pxref{Files}). @end table -Here are some common targets (available, or not, depending on GDB +Here are some common targets (available, or not, depending on _GDBN__ configuration): @table @code @@ -1251,10 +1281,11 @@ A core dump file. @samp{target core @var{filename}} is the same as @item target remote @var{dev} @kindex target remote -Remote serial target in gdb-specific protocol. The argument @var{dev} +Remote serial target in _GDBP__-specific protocol. The argument @var{dev} specifies what serial device to use for the connection (e.g. @code{/dev/ttya}). +_if__(_AMD29K__) @item target amd-eb @var{dev} @var{speed} @var{PROG} @kindex target amd-eb @cindex AMD EB29K @@ -1264,30 +1295,37 @@ Remote PC-resident AMD EB29K board, attached over serial lines. name of the program to be debugged, as it appears to DOS on the PC. @xref{AMD29K Remote}. +_fi__(_AMD29K__) +_if__(_I960__) @item target nindy @var{devicename} @kindex target nindy 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. @samp{/dev/ttya}. +_fi__(_I960__) +_if__(_VXWORKS__) @item target vxworks @var{machinename} @kindex target vxworks A VxWorks system, attached via TCP/IP. The argument @var{machinename} is the target system's machine name or IP address. +_fi__(_VXWORKS__) @end table -Different targets are available on different configurations of GDB; your +_if__(_GENERIC__) +Different targets are available on different configurations of _GDBN__; your configuration may have more or fewer targets. +_fi__(_GENERIC__) @node Running, Stopping, Targets, Top -@chapter Running Programs Under GDB +@chapter Running Programs Under _GDBN__ @cindex running @kindex run -To start your program under GDB, use the @samp{run} command. Except on +To start your program under _GDBN__, use the @samp{run} command. Except on VxWorks, the program must already have been specified using the -@samp{file} or @samp{exec-file} command, or with an argument to GDB +@samp{file} or @samp{exec-file} command, or with an argument to _GDBN__ (@pxref{Files}). On targets that support processes, @samp{run} creates an inferior @@ -1296,7 +1334,7 @@ process and makes that process run your program. On other targets, program. The execution of a program is affected by certain information it -receives from its superior. GDB provides ways to specify this +receives from its superior. _GDBN__ provides ways to specify this information, which you must do @i{before} starting the program. (You can change it after starting the program, but such changes do not affect the program unless you start it over again.) This information may be @@ -1312,14 +1350,14 @@ describing the arguments. In Unix systems, you can control which shell is used with the @code{SHELL} environment variable. @item The @i{environment.} -The program normally inherits its environment from GDB, but you can -use the GDB commands @samp{set environment} and +The program normally inherits its environment from _GDBN__, but you can +use the _GDBN__ commands @samp{set environment} and @samp{unset environment} to change parts of the environment that will be given to the program.@refill @item The @i{working directory.} -The program inherits its working directory from GDB. You can set GDB's -working directory with the @samp{cd} command in GDB. +The program inherits its working directory from _GDBN__. You can set _GDBN__'s +working directory with the @samp{cd} command in _GDBN__. @end table When you issue the @samp{run} command, your program begins to execute @@ -1331,7 +1369,7 @@ you may evaluate expressions that involve calls to functions in the inferior, using the @samp{print} or @samp{call} commands. @xref{Data}. If the modification time of your symbol file has changed since the last -time GDB read its symbols, GDB will discard its symbol table and re-read +time _GDBN__ read its symbols, _GDBN__ will discard its symbol table and re-read it. In this process, it tries to retain your current breakpoints. @menu @@ -1340,7 +1378,7 @@ it. In this process, it tries to retain your current breakpoints. * 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. +* Attach:: Debugging a process started outside _GDBN__. * Kill Process:: Getting rid of the child process running your program. @end menu @@ -1395,7 +1433,7 @@ your program when it is started. @itemx set environment @var{varname} = @var{value} @kindex set environment Sets environment variable @var{varname} to @var{value}, for your program -only, not for GDB itself. @var{value} may be any string; the values of +only, not for _GDBN__ itself. @var{value} may be any string; the values of environment variables are just strings, and any interpretation is supplied by your program itself. The @var{value} parameter is optional; if it is eliminated, the variable is set to a null value. @@ -1426,22 +1464,22 @@ abbreviated @samp{d e}. @cindex working directory (of your program) Each time you start your program with @samp{run}, it inherits its -working directory from the current working directory of GDB. GDB's +working directory from the current working directory of _GDBN__. _GDBN__'s working directory is initially whatever it inherited from its parent process (typically the shell), but you can specify a new working -directory in GDB with the @samp{cd} command. +directory in _GDBN__ with the @samp{cd} command. -The GDB working directory also serves as a default for the commands -that specify files for GDB to operate on. @xref{Files}. +The _GDBN__ working directory also serves as a default for the commands +that specify files for _GDBN__ to operate on. @xref{Files}. @table @code @item cd @var{directory} @kindex cd -Set GDB's working directory to @var{directory}. +Set _GDBN__'s working directory to @var{directory}. @item pwd @kindex pwd -Print GDB's working directory. +Print _GDBN__'s working directory. @end table @node Input/Output, Attach, Working Directory, Running @@ -1451,8 +1489,8 @@ Print GDB's working directory. @cindex i/o @cindex terminal @cindex controlling terminal -By default, the program you run under GDB does input and output to the same -terminal that GDB uses. +By default, the program you run under _GDBN__ does input and output to the same +terminal that _GDBN__ uses. You can redirect the program's input and/or output using @samp{sh}-style redirection commands in the @samp{run} command. For example, @@ -1486,7 +1524,7 @@ controlling terminal. When you use the @samp{tty} command or redirect input in the @samp{run} command, only the @emph{input for your program} is affected. The input -for GDB still comes from your terminal. +for _GDBN__ still comes from your terminal. @node Attach, Kill Process, Input/Output, Running @section Debugging an Already-Running Process @@ -1500,7 +1538,7 @@ target supports processes. (@samp{info files} will show your active targets). The command takes as argument a process ID. You specify a process ID to debug an already-running process that was -started outside of GDB. (The usual way to find out the process-id of +started outside of _GDBN__. (The usual way to find out the process-id of a Unix process is with the @code{ps} utility, or with the @code{jobs -l} shell command.) In this case, you must have permission to send the process a signal, and it must have the same effective user ID as the @@ -1510,22 +1548,22 @@ debugger. When using @samp{attach}, you should first use the @samp{file} command to specify the program running in the process and load its symbol table. -The first thing GDB does after arranging to debug the process is to stop -it. You can examine and modify an attached process with all the GDB +The first thing _GDBN__ does after arranging to debug the process is to stop +it. You can examine and modify an attached process with all the _GDBN__ commands that ordinarily available when you start processes with @samp{run}. You can insert breakpoints; you can step and continue; you can modify storage. If you would rather the process continue running, -you may use the @samp{continue} command after attaching GDB to the +you may use the @samp{continue} command after attaching _GDBN__ to the process. @kindex detach When you have finished debugging the attached process, you can use the -@samp{detach} command to release it from GDB's control. Detaching +@samp{detach} command to release it from _GDBN__'s control. Detaching the process continues its execution. After the @samp{detach} command, -that process and GDB become completely independent once more, and you +that process and _GDBN__ become completely independent once more, and you are ready to @samp{attach} another process or start one with @samp{run}. -If you exit GDB or use the @samp{run} command while you have an attached +If you exit _GDBN__ or use the @samp{run} command while you have an attached process, you kill that process. By default, you will be asked for confirmation if you try to do either of these things; you can control whether or not this happens by using the @samp{set caution} command @@ -1537,21 +1575,21 @@ whether or not this happens by using the @samp{set caution} command @table @code @item kill @kindex kill -Kill the child process in which your program is running under GDB. +Kill the child process in which your program is running under _GDBN__. @end table -This command is useful if you wish to debug a core dump instead. GDB +This command is useful if you wish to debug a core dump instead. _GDBN__ ignores any core dump file if it is actually running the program. On some operating systems, you can't execute your program in another -process while breakpoints are active inside GDB. The @samp{kill} +process while breakpoints are active inside _GDBN__. The @samp{kill} command is also useful in this situation, if you wish to run the program outside the debugger. The @samp{kill} command is also useful if you wish to recompile and relink the program, since on many systems it is impossible to modify an executable file which is running in a process. In this case, when you -next type @samp{run}, GDB will notice that the file has changed, and +next type @samp{run}, _GDBN__ will notice that the file has changed, and will re-read the symbol table (while trying to preserve your current breakpoint settings). @@ -1565,7 +1603,7 @@ investigate and find out why. @menu * Signals:: Fatal signals in your program just stop it; - then you can use GDB to see what is going on. + then you can use _GDBN__ 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. @@ -1594,12 +1632,12 @@ program has not specified in advance some other way to handle the signal. @code{SIGINT} does not indicate an error in the program, but it is normally fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program. -GDB has the ability to detect any occurrence of a signal in the program -running under GDB's control. You can tell GDB in advance what to do for +_GDBN__ has the ability to detect any occurrence of a signal in the program +running under _GDBN__'s control. You can tell _GDBN__ in advance what to do for each kind of signal. @cindex handling signals -Normally, GDB is set up to ignore non-erroneous signals like @code{SIGALRM} +Normally, _GDBN__ is set up to ignore non-erroneous signals like @code{SIGALRM} (so as not to interfere with their role in the functioning of the program) but to stop the program immediately whenever an error signal happens. You can change these settings with the @samp{handle} command. @@ -1607,13 +1645,13 @@ You can change these settings with the @samp{handle} command. @table @code @item info signal @kindex info signal -Print a table of all the kinds of signals and how GDB has been told to +Print a table of all the kinds of signals and how _GDBN__ has been told to handle each one. You can use this to see the signal numbers of all the defined types of signals. @item handle @var{signal} @var{keywords}@dots{} @kindex handle -Change the way GDB handles signal @var{signal}. @var{signal} can be the +Change the way _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 @@ -1623,33 +1661,33 @@ Their full names are @table @code @item nostop -GDB should not stop the program when this signal happens. It may +_GDBN__ should not stop the program when this signal happens. It may still print a message telling you that the signal has come in. @item stop -GDB should stop the program when this signal happens. This implies +_GDBN__ should stop the program when this signal happens. This implies the @samp{print} keyword as well. @item print -GDB should print a message when this signal happens. +_GDBN__ should print a message when this signal happens. @item noprint -GDB should not mention the occurrence of the signal at all. This +_GDBN__ should not mention the occurrence of the signal at all. This implies the @samp{nostop} keyword as well. @item pass -GDB should allow the program to see this signal; the program will be +_GDBN__ should allow the program to see this signal; the program will be able to handle the signal, or may be terminated if the signal is fatal and not handled. @item nopass -GDB should not allow the program to see this signal. +_GDBN__ should not allow the program to see this signal. @end table When a signal has been set to stop the program, the program cannot see the signal until you continue. It will see the signal then, if @samp{pass} is in effect for the signal in question @i{at that time}. In other words, -after GDB reports a signal, you can use the @samp{handle} command with +after _GDBN__ reports a signal, you can use the @samp{handle} command with @samp{pass} or @samp{nopass} to control whether that signal will be seen by the program when you later continue it. @@ -1662,7 +1700,7 @@ or to give it any signal at any time. @xref{Signaling}. @cindex breakpoints A @dfn{breakpoint} makes your program stop whenever a certain point in the -program is reached. You set breakpoints explicitly with GDB commands, +program is reached. You set breakpoints explicitly with _GDBN__ commands, specifying the place where the program should stop by line number, function name or exact address in the program. You can add various other conditions to control whether the program will stop. @@ -1703,13 +1741,13 @@ Watchpoints currently execute two orders of magnitude more slowly than other breakpoints, but this can well be worth it to catch errors where you have no clue what part of your program is the culprit. Some processors provide special hardware to implement this feature; future -releases of GDB will use such hardware if it is available. +releases of _GDBN__ will use such hardware if it is available. @end table @menu * Set Breaks:: How to establish breakpoints. -* Exception Handling:: How GDB supports exception handling for C++. +* Exception Handling:: How _GDBN__ 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. @@ -1761,11 +1799,11 @@ Set a breakpoint at the next instruction to be executed in the selected stack frame (@pxref{Stack}). In any selected frame but the innermost, this will cause the program to stop as soon as control returns to that frame. This is equivalent to a @samp{finish} command in the frame -inside the selected frame. If this is done in the innermost frame, GDB +inside the selected frame. If this is done in the innermost frame, _GDBN__ will stop the next time it reaches the current location; this may be useful inside of loops. -GDB normally ignores breakpoints when it resumes execution, until at +_GDBN__ normally ignores breakpoints when it resumes execution, until at least one instruction has been executed. If it did not do this, you would be unable to proceed past a breakpoint without first disabling the breakpoint. This rule applies whether or not the breakpoint already @@ -1800,7 +1838,7 @@ disabled, made conditional, etc., in the standard ways. Set a watchpoint for an expression. @end table -GDB allows you to set any number of breakpoints at the same place in the +_GDBN__ allows you to set any number of breakpoints at the same place in the program. There is nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (@pxref{Conditions}). @@ -1808,7 +1846,7 @@ breakpoints are conditional, this is even useful (@pxref{Conditions}). @subsection Breakpoints and Exceptions @cindex exception handlers -Some languages, such as GNU C++, implement exception handling. GDB +Some languages, such as GNU C++, implement exception handling. _GDBN__ can be used to examine what caused the program to raise an exception and to list the exceptions the program is prepared to handle at a given point in time. @@ -1846,16 +1884,16 @@ to catch. You can use @samp{info catch} to list active exception handlers; @pxref{Frame Info}. -There are currently some limitations to exception handling in GDB. +There are currently some limitations to exception handling in _GDBN__. These will be corrected in a future release. @itemize @bullet @item -If you call a function interactively, GDB will normally return +If you call a function interactively, _GDBN__ will normally return control to you when the function has finished executing. If the call raises an exception, however, the call may bypass the mechanism that returns control to the user and cause the program to simply continue -running until it hits a breakpoint, catches a signal that GDB is +running until it hits a breakpoint, catches a signal that _GDBN__ is listening for, or exits. @item You cannot raise an exception interactively. @@ -1877,7 +1915,7 @@ With the @samp{clear} command you can delete breakpoints according to where they are in the program. With the @samp{delete} command you can delete individual breakpoints by specifying their breakpoint numbers. -It is not necessary to delete a breakpoint to proceed past it. GDB +It is not necessary to delete a breakpoint to proceed past it. _GDBN__ automatically ignores breakpoints on the first instruction to be executed when you continue execution without changing the execution address. @@ -1995,7 +2033,7 @@ the program stops only if the condition is true. Break conditions may have side effects, and may even call functions in your program. These may sound like strange things to do, but their effects are completely predictable unless there is another enabled breakpoint at the -same address. (In that case, GDB might see the other breakpoint first and +same address. (In that case, _GDBN__ might see the other breakpoint first and stop the program without checking the condition of this one.) Note that breakpoint commands are usually more convenient and flexible for the purpose of performing side effects when a breakpoint is reached @@ -2039,7 +2077,7 @@ is reached. @kindex ignore Set the ignore count of breakpoint number @var{bnum} to @var{count}. The next @var{count} times the breakpoint is reached, your program's -execution will not stop; other than to decrement the ignore count, GDB +execution will not stop; other than to decrement the ignore count, _GDBN__ takes no action. To make the breakpoint stop the next time it is reached, specify @@ -2098,7 +2136,7 @@ You can use breakpoint commands to start the program up again. Simply use the @samp{cont} command, or @samp{step}, or any other command to resume execution. However, if you do this, any further commands in the same breakpoint's command list are ignored. When the program stops -again, GDB will act according to the cause of that stop. +again, _GDBN__ will act according to the cause of that stop. @kindex silent If the first command specified is @samp{silent}, the usual message about @@ -2144,7 +2182,7 @@ end One deficiency in the operation of automatically continuing breakpoints under Unix appears when your program uses raw mode for the terminal. -GDB switches back to its own terminal modes (not raw) before executing +_GDBN__ switches back to its own terminal modes (not raw) before executing commands, and then must switch back to raw mode when your program is continued. This causes any pending terminal input to be lost. In the GNU system, this will be fixed by changing the behavior of @@ -2173,7 +2211,7 @@ nontrivial conditions for performing the side effects, the operators @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 +attempting to run or continue a program with a breakpoint will cause _GDBN__ to stop the other process. When this happens, you have three ways to proceed: @@ -2183,8 +2221,8 @@ When this happens, you have three ways to proceed: Remove or disable the breakpoints, then continue. @item -Suspend GDB, and copy the file containing the program to a new name. -Resume GDB and use the @samp{exec-file} command to specify that GDB +Suspend _GDBN__, and copy the file containing the program to a new name. +Resume _GDBN__ and use the @samp{exec-file} command to specify that _GDBN__ should run the program under that name. Then start the program again. @item @@ -2357,16 +2395,16 @@ call and the local variables of the function that was called. All the stack frames are allocated in a region of memory called the @dfn{call stack}. -When your program stops, the GDB commands for examining the stack allow you +When your program stops, the _GDBN__ commands for examining the stack allow you to see all of this information. -One of the stack frames is @dfn{selected} by GDB and many GDB commands +One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands refer implicitly to the selected frame. In particular, whenever you ask -GDB for the value of a variable in the program, the value is found in the -selected frame. There are special GDB commands to select whichever frame +_GDBN__ for the value of a variable in the program, the value is found in the +selected frame. There are special _GDBN__ commands to select whichever frame you are interested in. -When the program stops, GDB automatically selects the currently executing +When the program stops, _GDBN__ automatically selects the currently executing frame and describes it briefly as the @samp{frame} command does (@pxref{Frame Info, Info}). @@ -2409,25 +2447,25 @@ in a register called the @dfn{frame pointer register} while execution is going on in that frame. @cindex frame number -GDB assigns numbers to all existing stack frames, starting with zero for +_GDBN__ assigns numbers to all existing stack frames, starting with zero for the innermost frame, one for the frame that called it, and so on upward. These numbers do not really exist in your program; they are to give you a -way of talking about stack frames in GDB commands. +way of talking about stack frames in _GDBN__ commands. @cindex selected frame -Many GDB commands refer implicitly to one stack frame, called the +Many _GDBN__ commands refer implicitly to one stack frame, called the @dfn{selected} stack frame. You can select any frame using one set of -GDB commands, and then other commands will operate on that frame. When -your program stops, GDB automatically selects the innermost frame. +_GDBN__ commands, and then other commands will operate on that frame. When +your program stops, _GDBN__ automatically selects the innermost frame. @cindex frameless execution Some compilers allow functions to be compiled to run without a frame -reserved for them on the stack. (For example, the GCC option +reserved for them on the stack. (For example, the _GCC__ option @samp{-fomit-frame-pointer} will generate functions without a frame.) This is occasionally done with heavily used library functions to save -the frame setup time. GDB has limited facilities for dealing with these +the frame setup time. _GDBN__ has limited facilities for dealing with these function invocations; if the innermost function invocation has no stack -frame, GDB will give it a virtual stack frame of 0 and correctly allow +frame, _GDBN__ will give it a virtual stack frame of 0 and correctly allow tracing of the function call chain. Results are undefined if a function invocation besides the innermost one is frameless. @@ -2511,7 +2549,7 @@ frame. @item frame @var{addr} Select the frame at address @var{addr}. This is useful mainly if the chaining of stack frames has been damaged by a bug, making it -impossible for GDB to assign numbers properly to all frames. In +impossible for _GDBN__ to assign numbers properly to all frames. In addition, this can be useful when the program has multiple stacks and switches between them. @@ -2551,7 +2589,7 @@ ten lines centered on the point of execution in the frame. @xref{List}. These two commands are variants of @samp{up} and @samp{down}, respectively; they differ in that they do their work silently, without causing display of the new frame. They are intended primarily for use -in GDB command scripts, where the output might be unnecessary and +in _GDBN__ command scripts, where the output might be unnecessary and distracting. @end table @@ -2611,10 +2649,10 @@ exception handlers, visit the associated frame (using the @samp{up}, @node Source, Data, Stack, Top @chapter Examining Source Files -GDB knows which source files your program was compiled from, and -can print parts of their text. When your program stops, GDB +_GDBN__ knows which source files your program was compiled from, and +can print parts of their text. When your program stops, _GDBN__ spontaneously prints the line it stopped in. Likewise, when you -select a stack frame (@pxref{Selection}), GDB prints the line +select a stack frame (@pxref{Selection}), _GDBN__ prints the line which execution in that frame has stopped in. You can also print parts of source files by explicit command. @@ -2771,8 +2809,8 @@ this command with as little as @samp{rev}. Executable programs sometimes do not record the directories of the source files from which they were compiled, just the names. Even when they do, the directories could be moved between the compilation and your debugging -session. GDB remembers a list of directories to search for source files; -this is called the @dfn{source path}. Each time GDB wants a source file, +session. _GDBN__ remembers a list of directories to search for source files; +this is called the @dfn{source path}. Each time _GDBN__ wants a source file, it tries all the directories in the list, in the order they are present in the list, until it finds a file with the desired name. Note that the executable search path is @emph{not} used for this purpose. Neither is @@ -2780,16 +2818,16 @@ the current working directory, unless it happens to be in the source path. If it can't find a source file in the source path, and the object program -records what directory it was compiled in, GDB tries that directory too. +records what directory it was compiled in, _GDBN__ tries that directory too. If the source path is empty, and there is no record of the compilation -directory, GDB will, as a last resort, look in the current directory. +directory, _GDBN__ will, as a last resort, look in the current directory. -Whenever you reset or rearrange the source path, GDB will clear out +Whenever you reset or rearrange the source path, _GDBN__ will clear out any information it has cached about where source files are found, where each line is in the file, etc. @kindex directory -When you start GDB, its source path is empty. +When you start _GDBN__, its source path is empty. To add other directories, use the @samp{directory} command. @table @code @@ -2808,7 +2846,7 @@ Print the source path: show which directories it contains. @end table Because the @samp{directory} command, when used with arguments, adds to -the front of the source path, it can affect files that GDB has already +the front of the source path, it can affect files that _GDBN__ has already found. If the source path contains directories that you do not want, and these directories contain misleading files with names matching your source files, the way to correct the situation is as follows: @@ -2864,9 +2902,9 @@ specified format. @section Expressions @cindex expressions -Many different GDB commands accept an expression and compute its value. +Many different _GDBN__ commands accept an expression and compute its value. Any kind of constant, variable or operator defined by the programming -language you are using is legal in an expression in GDB. This includes +language you are using is legal in an expression in _GDBN__. This includes conditional expressions, function calls, casts and string constants. It unfortunately does not include symbols defined by preprocessor @code{#define} commands, or C++ expressions involving @samp{::}, the @@ -2876,7 +2914,7 @@ Casts are supported in all languages, not just in C, because it is so useful to cast a number into a pointer so as to examine a structure at that address in memory. -GDB supports three kinds of operator in addition to those of programming +_GDBN__ supports three kinds of operator in addition to those of programming languages: @table @code @@ -2944,8 +2982,8 @@ Here @var{block} is the name of the source file whose variable you want. @cindex name resolution (C++) Unfortunately, this use of @samp{::} conflicts with the very similar use -of the same notation in C++; accordingly, GDB does not support use of -the C++ name resolution operator in GDB expressions. +of the same notation in C++; accordingly, _GDBN__ does not support use of +the C++ name resolution operator in _GDBN__ expressions. @node Arrays, Format options, Variables, Data @section Artificial Arrays @@ -2987,25 +3025,25 @@ after you had printed it out.) @section Format options @cindex format options -GDB provides a few ways to control how arrays, structures, and symbols are +_GDBN__ provides a few ways to control how arrays, structures, and symbols are printed. @table @code @item set array-max @var{number-of-elements} @kindex set array-max -If GDB is printing a large array, it will stop printing after it has +If _GDBN__ is printing a large array, it will stop printing after it has printed the number of elements set by the @samp{set array-max} command. This limit also applies to the display of strings. @item show array-max @kindex show array-max -Display the number of elements of a large array that GDB will print +Display the number of elements of a large array that _GDBN__ will print before losing patience. @item set arrayprint @itemx set arrayprint on @kindex set arrayprint -GDB will pretty print arrays. This format is more convenient to read, +_GDBN__ will pretty print arrays. This format is more convenient to read, but uses more space. The default is off. @item set arrayprint off. @@ -3054,7 +3092,7 @@ Show whether C++ virtual function tables are pretty printed, or not. @item set addressprint @item set addressprint on @kindex set addressprint -GDB will print memory addresses in stack traces, structure values, pointer +_GDBN__ will print memory addresses in stack traces, structure values, pointer values, breakpoints, etc. The default is on. @item set addressprint off @@ -3066,7 +3104,7 @@ Show whether or not addresses are to be printed. @item set prettyprint on @kindex set prettyprint -Cause GDB to print structures in an indented format with one member per +Cause _GDBN__ to print structures in an indented format with one member per line, like this: @example @@ -3081,7 +3119,7 @@ $1 = @{ @end example @item set prettyprint off -Cause GDB to print structures in a compact format, like this: +Cause _GDBN__ to print structures in a compact format, like this: @smallexample $1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \ @@ -3093,19 +3131,19 @@ This is the default format. @item show prettyprint @kindex show prettyprint -Show which format GDB will use to print structures. +Show which format _GDBN__ will use to print structures. @item set unionprint on @kindex set unionprint -Tell GDB to print unions which are contained in structures. This is the +Tell _GDBN__ to print unions which are contained in structures. This is the default setting. @item set unionprint off -Tell GDB not to print unions which are contained in structures. +Tell _GDBN__ not to print unions which are contained in structures. @item show unionprint @kindex show unionprint -Ask GDB whether or not it will print unions which are contained in +Ask _GDBN__ whether or not it will print unions which are contained in structures. For example, given the declarations @@ -3146,7 +3184,7 @@ $1 = @{it = Tree, form = @{...@}@} @cindex formatted output @cindex output formats -GDB normally prints all values according to their data types. Sometimes +_GDBN__ normally prints all values according to their data types. Sometimes this is not what you want. For example, you might want to print a number in hex, or a pointer in decimal. Or you might want to view data in memory at a certain address as a character string or an instruction. These things @@ -3176,7 +3214,7 @@ Print as an address, both absolute in hex and as an offset from the nearest preceding symbol. This format can be used to discover where (in what function) an unknown address is located: @example -(gdb) p/a 0x54320 +(_GDBP__) p/a 0x54320 $3 = 0x54320 <_initialize_vx+396> @end example @@ -3197,7 +3235,7 @@ p/x $pc @noindent Note that no space is required before the slash; this is because command -names in GDB cannot contain a slash. +names in _GDBN__ cannot contain a slash. To reprint the last value in the value history with a different format, you can use the @samp{print} command with just a format and no @@ -3258,7 +3296,7 @@ Many assemblers and cpu designers still use `word' for a 16-bit quantity, as a holdover from specific predecessor machines of the 1970's that really did use two-byte words. But more generally the term `word' has always referred to the size of quantity that a machine normally operates on and -stores in its registers. This is 32 bits for all the machines that GDB +stores in its registers. This is 32 bits for all the machines that _GDBN__ runs on. @item g @@ -3349,7 +3387,7 @@ in which the format and address are allowed to default. @kindex $__ The addresses and contents printed by the @samp{x} command are not put in the value history because there is often too much of them and they would -get in the way. Instead, GDB makes these values available for subsequent +get in the way. Instead, _GDBN__ makes these values available for subsequent use in expressions as values of the convenience variables @code{$_} and @code{$__}. @@ -3368,7 +3406,7 @@ address printed if several units were printed on the last line of output. If you find that you want to print the value of an expression frequently (to see how it changes), you might want to add it to the @dfn{automatic -display list} so that GDB will print its value each time the program stops. +display list} so that _GDBN__ will print its value each time the program stops. Each expression added to the list is given a number to identify it; to remove an expression from the list, you specify that number. The automatic display looks like this: @@ -3443,7 +3481,7 @@ because they refer to automatic variables not currently available. @section Value History @cindex value history -Values printed by the @samp{print} command are saved in GDB's @dfn{value +Values printed by the @samp{print} command are saved in _GDBN__'s @dfn{value history} so that you can refer to them in other expressions. Values are kept until the symbol table is re-read or discarded (for example with the @samp{file} or @samp{symbol-file} commands). When the symbol table @@ -3516,9 +3554,9 @@ Print ten history values just after the values last printed. @section Convenience Variables @cindex convenience variables -GDB provides @dfn{convenience variables} that you can use within GDB to +_GDBN__ provides @dfn{convenience variables} that you can use within _GDBN__ to hold on to a value and refer to it later. These variables exist entirely -within GDB; they are not part of your program, and setting a convenience +within _GDBN__; they are not part of your program, and setting a convenience variable has no effect on further execution of your program. That's why you can use them freely. @@ -3562,7 +3600,7 @@ print bar[$i++]->contents @i{@dots{}repeat that command by typing @key{RET}.} @end example -Some convenience variables are created automatically by GDB and given +Some convenience variables are created automatically by _GDBN__ and given values likely to be useful. @table @code @@ -3595,7 +3633,7 @@ different name. For example, on the SPARC, @code{info registers} displays the processor status register as @code{$psr} but you can also refer to it as @code{$ps}. -GDB always considers the contents of an ordinary register as an integer +_GDBN__ always considers the contents of an ordinary register as an integer when the register is examined in this way. Some machines have special registers which can hold nothing but floating point; these registers are considered floating point. There is no way to refer to the contents of an @@ -3608,7 +3646,7 @@ the operating system is not the same one that your program normally 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, GDB normally works with the virtual format only (the format that +cases, _GDBN__ normally works with the virtual format only (the format that makes sense for your program), but the @samp{info registers} command prints the data in both formats. @@ -3670,7 +3708,7 @@ off the stack, regardless of machine architecture, use @samp{return}; The commands described in this section allow you to inquire about the symbols (names of variables, functions and types) defined in your -program. This information is found by GDB in the symbol table loaded by +program. This information is found by _GDBN__ in the symbol table loaded by the @samp{symbol-file} command; it is inherent in the text of your program and does not change as the program executes. @@ -3764,7 +3802,7 @@ file @var{filename}. Once you think you have found an error in the program, you might want to find out for certain whether correcting the apparent error would lead to correct results in the rest of the run. You can find the answer by -experiment, using the GDB features for altering execution of the +experiment, using the _GDBN__ features for altering execution of the program. For example, you can store new values into variables or memory @@ -3813,7 +3851,7 @@ appears identical to a @samp{set} subcommand, it may be necessary to use the @samp{set variable} command. This command is identical to @samp{set} except for its lack of subcommands. -GDB allows more implicit conversions in assignments than C does; you can +_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 any structure can be converted to any other structure that is the same length or shorter. @@ -3944,7 +3982,7 @@ the value history, if it is not void. @node Sequences, Emacs, Altering, Top @chapter Canned Sequences of Commands -Aside from breakpoint commands (@pxref{Break Commands}),GDB 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. @@ -3959,7 +3997,7 @@ user-defined commands and command files. @section User-Defined Commands @cindex user-defined command -A @dfn{user-defined command} is a sequence of GDB commands to which you +A @dfn{user-defined command} is a sequence of _GDBN__ commands to which you assign a new name as a command. This is done with the @samp{define} command. @@ -3969,7 +4007,7 @@ command. Define a command named @var{commandname}. If there is already a command by that name, you are asked to confirm that you want to redefine it. -The definition of the command is made up of other GDB command lines, +The definition of the command is made up of other _GDBN__ command lines, which are given following the @samp{define} command. The end of these commands is marked by a line containing @samp{end}. @@ -3992,7 +4030,7 @@ commands of the definition are not printed. An error in any command stops execution of the user-defined command. Commands that would ask for confirmation if used interactively proceed -without asking when used inside a user-defined command. Many GDB commands +without asking when used inside a user-defined command. Many _GDBN__ commands that normally print messages to say what they are doing omit the messages when used in user-defined command. @@ -4000,15 +4038,15 @@ when used in user-defined command. @section Command Files @cindex command files -A command file for GDB is a file of lines that are GDB commands. Comments +A command file for _GDBN__ is a file of lines that are _GDBN__ commands. Comments (lines starting with @samp{#}) 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} -When you start GDB, it first executes commands from its @dfn{init files}. -These are files named @file{.gdbinit}. GDB reads the init file (if any) +@cindex @file{._GDBP__init} +When you start _GDBN__, it first executes commands from its @dfn{init files}. +These are files named @file{._GDBP__init}. _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 @@ -4025,7 +4063,7 @@ printed as they are executed. An error in any command terminates execution of the command file. Commands that would ask for confirmation if used interactively proceed -without asking when used in a command file. Many GDB commands that +without asking when used in a command file. Many _GDBN__ commands that normally print messages to say what they are doing omit the messages when used in a command file. @@ -4104,25 +4142,25 @@ letter. @end table @node Emacs, Remote, Sequences, Top -@chapter Using GDB under GNU Emacs +@chapter Using _GDBN__ under GNU Emacs @cindex emacs A special interface allows you to use GNU Emacs to view (and edit) the source files for the program you are debugging with -GDB. +_GDBN__. To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the executable file you want to debug as an argument. This command starts -GDB as a subprocess of Emacs, with input and output through a newly +_GDBN__ as a subprocess of Emacs, with input and output through a newly created Emacs buffer. -Using GDB under Emacs is just like using GDB normally except for two +Using _GDBN__ under Emacs is just like using _GDBN__ normally except for two things: @itemize @bullet @item All ``terminal'' input and output goes through the Emacs buffer. This -applies both to GDB commands and their output, and to the input and +applies both to _GDBN__ commands and their output, and to the input and output done by the program you are debugging. This is useful because it means that you can copy the text of previous @@ -4132,13 +4170,13 @@ in this way. All the facilities of Emacs' Shell mode are available for this purpose. @item -GDB displays source code through Emacs. Each time GDB displays a +_GDBN__ displays source code through Emacs. Each time _GDBN__ displays a stack frame, Emacs automatically finds the source file for that frame and puts an arrow (@samp{=>}) at the left margin of the current line. Emacs uses a separate buffer for source display, and splits the window -to show both your GDB session and the source. +to show both your _GDBN__ session and the source. -Explicit GDB @samp{list} or search commands still produce output as +Explicit _GDBN__ @samp{list} or search commands still produce output as usual, but you probably will have no reason to use them. @end itemize @@ -4146,20 +4184,20 @@ usual, but you probably will have no reason to use them. @emph{Warning:} If the directory where your program resides is not your current directory, it can be easy to confuse Emacs about the location of the source files, in which case the auxiliary display buffer will not -appear to show your source. GDB can find programs by searching your -environment's @samp{PATH} variable, so the GDB I/O session will proceed -normally; but Emacs doesn't get enough information back from GDB to +appear to show your source. _GDBN__ can find programs by searching your +environment's @samp{PATH} variable, so the _GDBN__ I/O session will proceed +normally; but Emacs doesn't get enough information back from _GDBN__ to locate the source files in this situation. To avoid this problem, -either start GDB mode from the directory where your program resides, or +either start _GDBN__ mode from the directory where your program resides, or specify a full path name when prompted for the @kbd{M-x gdb} argument. -A similar confusion can result if you use the GDB @samp{file} command to +A similar confusion can result if you use the _GDBN__ @samp{file} command to switch to debugging a program in some other location, from an existing -GDB I/O buffer in Emacs. +_GDBN__ I/O buffer in Emacs. @end quotation By default, @kbd{M-x gdb} calls the program called ``@code{gdb}''. If -you need to call GDB by a different name (for example, if you keep +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, @example @@ -4170,52 +4208,52 @@ Emacs variable @code{gdb-command-name}; for example, in your @samp{.emacs} file) will make Emacs call the program named ``@code{mygdb}'' instead. -In the GDB I/O buffer, you can use these special Emacs commands in +In the _GDBN__ I/O buffer, you can use these special Emacs commands in addition to the standard Shell mode commands: @table @kbd @item C-h m -Describe the features of Emacs' GDB Mode. +Describe the features of Emacs' _GDBN__ Mode. @item M-s -Execute to another source line, like the GDB @samp{step} command; also +Execute to another source line, like the _GDBN__ @samp{step} command; also update the display window to show the current file and location. @item M-n Execute to next source line in this function, skipping all function -calls, like the GDB @samp{next} command. Then update the display window +calls, like the _GDBN__ @samp{next} command. Then update the display window to show the current file and location. @item M-i -Execute one instruction, like the GDB @samp{stepi} command; update +Execute one instruction, like the _GDBN__ @samp{stepi} command; update display window accordingly. @item M-x gdb-nexti -Execute to next instruction, using the GDB @samp{nexti} command; update +Execute to next instruction, using the _GDBN__ @samp{nexti} command; update display window accordingly. @item C-c C-f -Execute until exit from the selected stack frame, like the GDB +Execute until exit from the selected stack frame, like the _GDBN__ @samp{finish} command. @item M-c @comment C-c C-p in emacs 19 -Continue execution of the program, like the GDB @samp{cont} command. +Continue execution of the program, like the _GDBN__ @samp{cont} command. @item M-u @comment 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 GDB @samp{up} command.@refill +like the _GDBN__ @samp{up} command.@refill @item M-d @comment C-c C-d in emacs 19 Go down the number of frames indicated by the numeric argument, like the -GDB @samp{down} command. +_GDBN__ @samp{down} command. @item C-x & Read the number where the cursor is positioned, and insert it at the end -of the GDB I/O buffer. For example, if you wish to disassemble code +of the _GDBN__ I/O buffer. For example, if you wish to disassemble code around an address that was displayed earlier, type @kbd{disassemble}; then move the cursor to the address display, and pick up the argument for @samp{disassemble} by typing @kbd{C-x &}. @@ -4231,19 +4269,19 @@ 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. GDB does this display automatically; +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 GDB to set a breakpoint on the source line point is on. +tells _GDBN__ to set a breakpoint on the source line point is on. 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 GDB +the files with these buffers if you wish; but keep in mind that _GDBN__ communicates with Emacs in terms of line numbers. If you add or -delete lines from the text, the line numbers that GDB knows will cease +delete lines from the text, the line numbers that _GDBN__ knows will cease to correspond properly to the code. @comment The following dropped because Epoch is nonstandard. Reactivate @@ -4259,36 +4297,36 @@ environment. Users of this environment can use a new command, each value is printed in its own window. @end ignore -@node Remote, GDB Bugs, Emacs, Top +@node Remote, _GDBN__ Bugs, Emacs, Top @chapter Remote Debugging @cindex remote debugging If you are trying to debug a program running on a machine that can't run -GDB in the usual way, it is often useful to use remote debugging. For +_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 a small system which does not have a general purpose operating system -powerful enough to run a full-featured debugger. Currently GDB supports +powerful enough to run a full-featured debugger. Currently _GDBN__ supports remote debugging over a serial connection, and (using Sun RPC) over a TCP/IP connection. The program to be debugged on the remote machine needs to contain a -debugging device driver which talks to GDB over the serial line. The -same version of GDB that is used ordinarily can be used for this. -Several sample remote debugging drivers are distributed with GDB; see -the @file{README} file in the GDB distribution for more information. +debugging device driver which talks to _GDBN__ over the serial line. The +same version of _GDBN__ that is used ordinarily can be used for this. +Several sample remote debugging drivers are distributed with _GDBN__; see +the @file{README} file in the _GDBN__ distribution for more information. @menu * Remote Commands:: Commands used to start and finish remote debugging. @end menu -For details of the communication protocol, see the comments in the GDB +For details of the communication protocol, see the comments in the _GDBN__ source file @file{remote.c}. @node Remote Commands, , Remote, Remote @section Commands for Remote Debugging -To start remote debugging, first run GDB and specify as an executable file -the program that is running in the remote machine. This tells GDB how +To start remote debugging, first run _GDBN__ and specify as an executable file +the program that is running in the remote machine. This tells _GDBN__ how to find the program's symbols and the contents of its pure text. Then establish communication using the @samp{target remote} command with a device name as an argument. For example: @@ -4308,7 +4346,7 @@ To resume the remote program and stop debugging it, use the @samp{detach} command. Other remote targets be available in your -configuration of GDB; use @samp{info targets} to list them. +configuration of _GDBN__; use @samp{info targets} to list them. @table @code @item reset @@ -4319,18 +4357,18 @@ has been equipped with a circuit to perform a hard reset (or some other interesting action) when a break is detected. @end table -@node GDB Bugs, Installing GDB, Remote, Top +@node _GDBN__ Bugs, Installing _GDBN__, Remote, Top @comment node-name, next, previous, up -@chapter Reporting Bugs in GDB -@cindex Bugs in GDB -@cindex Reporting Bugs in GDB +@chapter Reporting Bugs in _GDBN__ +@cindex Bugs in _GDBN__ +@cindex Reporting Bugs in _GDBN__ -Your bug reports play an essential role in making GDB reliable. +Your bug reports play an essential role in making _GDBN__ reliable. Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the important function of a bug report is to help -the entire community by making the next version of GDB work better. Bug -reports are your contribution to the maintenance of GDB. +the entire community by making the next version of _GDBN__ work better. Bug +reports are your contribution to the maintenance of _GDBN__. In order for a bug report to serve its purpose, you must include the information that makes for fixing the bug. @@ -4340,7 +4378,7 @@ information that makes for fixing the bug. * Bug Reporting:: How to Report Bugs @end menu -@node Bug Criteria, Bug Reporting, GDB Bugs, GDB Bugs +@node Bug Criteria, Bug Reporting, _GDBN__ Bugs, _GDBN__ Bugs @section Have You Found a Bug? @cindex Bug Criteria @@ -4351,25 +4389,25 @@ If you are not sure whether you have found a bug, here are some guidelines: @cindex Fatal Signal @cindex Core Dump If the debugger gets a fatal signal, for any input whatever, that is a -GDB bug. Reliable debuggers never crash. +_GDBN__ bug. Reliable debuggers never crash. @item @cindex error on Valid Input -If GDB produces an error message for valid input, that is a bug. +If _GDBN__ produces an error message for valid input, that is a bug. @item @cindex Invalid Input -If GDB does not produce an error message for invalid input, +If _GDBN__ does not produce an error message for invalid input, that is a bug. However, you should note that your idea of ``invalid input'' might be our idea of ``an extension'' or ``support for traditional practice''. @item If you are an experienced user of debugging tools, your suggestions -for improvement of GDB are welcome in any case. +for improvement of _GDBN__ are welcome in any case. @end itemize -@node Bug Reporting, , Bug Criteria, GDB Bugs +@node Bug Reporting, , Bug Criteria, _GDBN__ Bugs @section How to Report Bugs @cindex Bug Reports @cindex Compiler Bugs, Reporting @@ -4379,7 +4417,7 @@ for improvement of GDB are welcome in any case. @comment "info@cygnus.com"---the latter will reach all of Cygnus) @comment is welcome. A number of companies and individuals offer support for GNU products. -If you obtained GDB from a support organization, we recommend you +If you obtained _GDBN__ from a support organization, we recommend you contact that organization first. Among these organizations are Cygnus Support (Palo Alto CA, USA); C2V @@ -4392,7 +4430,7 @@ Emacs distribution. Numerous individual consultants are also listed there. @comment END NEUTRAL+HELPFUL section -In any event, we also recommend that you send bug reports for GDB to one +In any event, we also recommend that you send bug reports for _GDBN__ to one of these addresses: @example @@ -4401,7 +4439,7 @@ bug-gdb@@prep.ai.mit.edu @end example @strong{Do not send bug reports to @samp{info-gdb}, or to -@samp{help-gdb}, or to any newsgroups.} Most users of GDB do not want to +@samp{help-gdb}, or to any newsgroups.} Most users of _GDBN__ do not want to receive bug reports. Those that do, have asked to be on @samp{bug-gdb}. The mailing list @samp{bug-gdb} has a newsgroup which serves as a @@ -4449,22 +4487,22 @@ To enable us to fix the bug, you should include all these things: @itemize @bullet @item -The version of GDB. GDB announces it on startup; you can also print it +The version of _GDBN__. _GDBN__ announces it on startup; you can also print it at any time using @samp{info version}. Without this, we won't know whether there is any point in looking for -the bug in the current version of GDB. +the bug in the current version of _GDBN__. @item A complete input script, and all necessary source files, that will reproduce the bug. @item -What compiler (and its version) was used to compile GDB---e.g. -``GCC-1.37.1''. +What compiler (and its version) was used to compile _GDBN__---e.g. +``_GCC__-1.37.1''. @item -What compiler (and its version) was used to compile GDB. +What compiler (and its version) was used to compile _GDBN__. @item The command arguments you gave the compiler to compile that example and @@ -4482,13 +4520,13 @@ version number. 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 GDB gets a fatal signal, then we +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. Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, -your copy of GDB is out of synch, or you have encountered a +your copy of _GDBN__ is out of synch, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you @i{told} us to expect a crash, then when ours fails to crash, we would know that the bug was not @@ -4496,8 +4534,8 @@ happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations. @item -If you wish to suggest changes to the GDB source, send us context -diffs. If you even discuss something in the GDB source, refer to +If you wish to suggest changes to the _GDBN__ source, send us context +diffs. If you even discuss something in the _GDBN__ source, refer to it by context, not by line number. The line numbers in our development sources don't match those in your @@ -4536,7 +4574,7 @@ the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. -Sometimes with a program as complicated as GDB it is very hard to +Sometimes with a program as complicated as _GDBN__ it is very hard to construct an example that will make the program follow a certain path through the code. If you don't send us the example, we won't be able to construct one, so we won't be able to verify that the bug is fixed. @@ -4557,12 +4595,12 @@ things without first using the debugger to find the facts. @include readline/inc-history.texinfo @end iftex -@node Installing GDB, License, GDB Bugs, Top -@appendix Installing GDB -@cindex configuring GDB +@node Installing _GDBN__, License, _GDBN__ Bugs, Top +@appendix Installing _GDBN__ +@cindex configuring _GDBN__ @cindex installation -The script @samp{config.gdb} automates the process of preparing GDB for +The script @samp{config.gdb} automates the process of preparing _GDBN__ for installation; you can then use @samp{make} to actually build it. For example, @@ -4572,38 +4610,38 @@ make @end example @noindent -is all that's required to install GDB on a Sun 3 running SunOS 4. +is all that's required to install _GDBN__ on a Sun 3 running SunOS 4. @table @code @kindex config.gdb @item config.gdb @var{machine} @itemx config.gdb -srcdir=@var{dir} @var{machine} -This is the most usual way of configuring GDB; to debug programs running -on the same machine as GDB itself. If you wish to build the GDB binaries +This is the most usual way of configuring _GDBN__; to debug programs running +on the same machine as _GDBN__ itself. If you wish to build the _GDBN__ binaries in a completely different directory from the sources, specify a path to the source directory using the @samp{-srcdir} option. @item config.gdb -host @cindex host environments -Display a list of supported host environments for GDB. +Display a list of supported host environments for _GDBN__. @item config.gdb @var{host} @var{target} @itemx config.gdb -srcdir=@var{dir} @var{host} @var{target} @cindex cross-debugging -GDB can also be used as a cross-debugger, running on a machine of one +_GDBN__ can also be used as a cross-debugger, running on a machine of one type while debugging a program running on a machine of another type. You configure it this way by specifying first the @var{host}, then the @var{target} environment on the @code{config.gdb} argument list; the -@var{host} is where GDB runs, and the @var{target} is where your program +@var{host} is where _GDBN__ runs, and the @var{target} is where your program runs. @xref{Remote}. Again, you can use @samp{-srcdir} to specify a -path to the GDB source. +path to the _GDBN__ source. @item config.gdb -target @cindex target environments -Display a list of supported target environments for GDB. +Display a list of supported target environments for _GDBN__. @end table -@node License, Commands, Installing GDB, Top +@node License,,, @unnumbered GNU GENERAL PUBLIC LICENSE @center Version 1, February 1989 |