diff options
| -rw-r--r-- | gdb/doc/gdb.texinfo | 1875 |
1 files changed, 1071 insertions, 804 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 88574d4..49c7221 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -8,17 +8,18 @@ @c _HOST__ architectures (and you can of course get the full source, @c with all configurations, from wherever you got this). _if__(0) +_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 + m4 pretex.m4 none.m4 m680x0.m4 gdb.texinfo >gdb-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). - +_1__ _fi__(0) @c -@synindex ky cp +@syncodeindex 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) @@ -220,14 +221,176 @@ HPPA architecture support. @end itemize -@node Invocation, User Interface, New Features, Top -@chapter Starting _GDBN__ +@node Sample Session,,, +@chapter A Sample _GDB__ Session + +You can use this manual at your leisure to read all about _GDBN__. +However, a handful of commands are enough to get started using the +debugger. This chapter illustrates these commands. + +In this sample session, we emphasize user input like this: @var{input}, +to make it easier to pick out from the surrounding output. + +We'll be using _GDBN__ to inspect GNU @code{m4} (a generic macro +processor). + +_0__@smallexample +$ @var{cd gm4/common} + +$ @var{_GDBP__ m4} +Reading symbol data from m4...done. +@end smallexample + +@noindent +_GDBN__ only reads enough symbol data to know where to find the rest +when needed; as a result, the first prompt comes up very quickly. + +@smallexample +(_GDBP__) @var{break m4_changequote} +Breakpoint 1 at 0x59d4: file builtin.c, line 812. +@end smallexample + +@noindent +We've chosen to see how the @code{m4} builtin @samp{changequote} +works. We know the relevant subroutine is @samp{m4_changequote} (from +inspecting the source), so we set a breakpoint there. + +@smallexample +(_GDBP__) @var{run} +Starting program: /s1/gnu/src/gm4/common/m4 +@var{`usual' quotes <not these>} +usual quotes <not these> +@end smallexample + +@noindent +Now we've started @code{m4} running under _GDBN__ control; while we don't touch +the @samp{m4_changequote} subroutine, the program runs as usual. + +@smallexample +@var{changequote(<,>)} + +Breakpoint 1, m4_changequote (argc=3, argv=0x2b958) at builtin.c:812 +812 if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3)) +@end smallexample +@noindent +Once we've encountered the breakpoint, _GDBN__ suspends execution +of our program, displaying information about where it stopped. + +@smallexample +(_GDBP__) @var{s} +bad_argc (name=0xf833cfb4<Address 0xf833cfb4 out of + bounds>, argc=3, min=1, max=3) at builtin.c:230 +230 if (min > 0 && argc < min) @{ +@end smallexample +@noindent +We single-stepped with the command @samp{s}; since there was a subroutine +call, we've stopped in the first line of that subroutine, not in the next line +of @code{m4_changequote}. + +The command @samp{next} would have taken us to the next line of the same +subroutine. Now that we've stopped deeper in the stack, we can use the +@samp{backtrace} command (which can also be spelled @samp{bt}) to get +information about where we are. + +@smallexample +(_GDBP__) @var{bt} +#0 bad_argc (name=0xf833cfb4<Address 0xf833cfb4 out of bounds>, argc=3, + min=1, max=3) at builtin.c:230 +#1 0x59ec in m4_changequote (argc=3, argv=0x2b958) at builtin.c:812 +#2 0x6e38 in expand_macro (sym=0x2b060) at macro.c:242 +#3 0x6840 in expand_token (obs=0x0, t=176224, td=0xf7fffb08) at macro.c:71 +#4 0x6794 in expand_input () at macro.c:40 +#5 0x28dc in main (argc=0, argv=0xf7fffbf8) at m4.c:174 +@end smallexample + +@noindent +We'll tell _GDBN__ to finish execution of this subroutine, to get back +to @code{m4_changequote}. + +@smallexample +(_GDBP__) @var{finish} +Run till exit from #0 bad_argc (name=0xf833cfb4<Address 0xf833cfb4 out of + bounds>, argc=3, min=1, max=3) at builtin.c:230 +0x59ec in m4_changequote (argc=3, argv=0x2b958) at builtin.c:812 +812 if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3)) +Value returned is $1 = false +(_GDBP__) @var{s} +815 lquote = (argc >= 2) ? TOKEN_DATA_TEXT(argv[1])[0] : DEF_LQUOTE; +(_GDBP__) @var{whatis lquote} +type = char +(_GDBP__) @var{p lquote} +$2 = 96 '`' +@end smallexample + +@noindent +When we stepped to another line, @code{m4} was about to set a variable +@samp{lquote}; we inspected its type with @samp{whatis} and its value +with @samp{p} (the @samp{print} command). We can see some context by +displaying the surrounding source code, with the @samp{l} (@code{list}) +command. + +@smallexample +(_GDBP__) @var{l} +810 token_data **argv; +811 @{ +812 if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3)) +813 return; +814 +815 lquote = (argc >= 2) ? TOKEN_DATA_TEXT(argv[1])[0] : DEF_LQUOTE; +816 rquote = (argc >= 3) ? TOKEN_DATA_TEXT(argv[2])[0] : DEF_RQUOTE; +817 @} +818 +819 /* +(_GDBP__) @var{s} +816 rquote = (argc >= 3) ? TOKEN_DATA_TEXT(argv[2])[0] : DEF_RQUOTE; +(_GDBP__) @var{s} +817 @} +(_GDBP__) @var{p lquote} +$3 = 60 '<' +(_GDBP__) @var{p rquote} +$4 = 62 '>' +@end smallexample + +@noindent +We proceeded past another line with @samp{s}, and inspected the new +values of @code{m4}'s internal variables @code{rquote} and +@code{lquote}. + +Since we're done with our inspection of this subroutine, we'll tell +_GDBN__ to allow @code{m4} to continue running, with the @samp{c} +(@code{continue}) command: + +@smallexample +(_GDBP__) @var{c} +Continuing. + +@var{`usual' quotes <not these>} +`usual' quotes not these + +Program exited normally. +(_GDBP__) @var{quit} + +$ +_1__@end smallexample + +@noindent +Finally, when we ended the @code{m4} run, _GDBN__ told us +``@code{Program exited normally.}'' We ended our _GDBN__ session with +the _GDBN__ @samp{quit} command. + + +@node Starting and Stopping,,, +@chapter Starting and Stopping + +@node Starting _GDBN__,,, +@section Starting _GDBN__ _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 _GDBN__ is with one argument or two, specifying -an executable program as the argument: +You can start by just calling @samp{_GDBP__} with no arguments or +options; but the most usual way to start _GDBN__ is with one argument or +two, specifying an executable program as the argument: @example _GDBP__ program @end example @@ -245,7 +408,7 @@ in sequential order. The order makes a difference when the @samp{-x} option is used. @node File Options, Mode Options, Invocation, Invocation -@section Options and Arguments to Choose Files +@subsection 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 @@ -275,8 +438,8 @@ Execute _GDBN__ commands from file @var{file}. @xref{Command Files}. Add @var{directory} to the path to search for source files. @end table -@node Mode Options, Remote i960-Nindy, File Options, Invocation -@section Options to Choose Modes +@node Mode Options, , , +@subsection Options to Choose Modes @table @code @item -nx @@ -323,7 +486,7 @@ _GDBN__ for remote debugging. _if__(_I960__) @node i960-Nindy Remote,,, -@section _GDBN__ with a Remote Intel 960 (Nindy) +@subsection _GDBN__ with a Remote Intel 960 (Nindy) ``Nindy'' is the name of a Rom Monitor program for Intel 960 target systems. When _GDBN__ is configured to control a remote Intel 960 using @@ -341,7 +504,7 @@ By using the @samp{target} command at any point during your _GDBN__ session. @end itemize @node Nindy Startup,,, -@subsection Startup with Nindy +@subsubsection Startup with Nindy The command-line options for Nindy are detailed below. If you simply start @code{_GDBP__} without using options to specify a serial port, you are @@ -355,7 +518,7 @@ 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}). @node Nindy Options,,, -@subsection Options for Nindy +@subsubsection Options for Nindy These are the startup options for beginning your _GDBN__ session with a Nindy-960 board attached: @@ -402,7 +565,7 @@ _fi__(_I960__) _if__(_AMD29K__) @node EB29K Remote,,, -@section Starting _GDBN__ with a Remote EB29K +@subsection _GDBN__ with a Remote EB29K @cindex EB29K board @cindex running 29K programs @@ -415,12 +578,12 @@ you've hooked the cable between the PC's @samp{COM1} port and @samp{/dev/ttya} on the Unix system. @node Comms (EB29K),,, -@subsection Communications Setup +@subsubsection 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 +_0__@example C:\> MODE com1:9600,n,8,1,none -@end example +_1__@end example @noindent This example---run on an MS DOS 4.0 system---sets the PC port to 9600 bps, no parity, eight data bits, one stop bit, and no ``retry'' action; @@ -431,9 +594,9 @@ end of the connection as well. To give control of the PC to the Unix side of the serial line, type the following at the DOS console: -@example +_0__@example C:\> CTTY com1 -@end example +_1__@end example @noindent (Later, if you wish to return control to the DOS console, you can use the command @samp{CTTY con}---but you must send it over the device that @@ -472,7 +635,7 @@ start the PC program @samp{EBMON} (an EB29K control program supplied with your board by AMD). You should see an initial display from @code{EBMON} similar to the one in our example, ending with the @code{EBMON} prompt @samp{#}--- -@example +_0__@example C:\> g: G:\> CD \usr\joe\work29k @@ -501,7 +664,7 @@ Am29027 Available = No Byte Write Available = Yes # ~. -@end example +_1__@end example Then exit the @code{cu} or @code{tip} program (done in the example by typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} will keep @@ -516,8 +679,8 @@ other way---perhaps floppy-disk transfer---of getting the 29K program from the Unix system to the PC; _GDBN__ will @emph{not} download it over the serial line. -@node _GDBP__-EB29K -@subsection EB29K cross-debugging +@node _GDBP__-EB29K,,, +@subsubsection EB29K cross-debugging Finally, @code{cd} to the directory containing an image of your 29K program on the Unix system, and start _GDBN__---specifying as argument the name of your 29K program: @@ -558,7 +721,7 @@ Type @samp{CTTY con} to return command input to the main DOS console, and type @samp{~.} to leave @code{tip} or @code{cu}. @node Remote Log, , Remote Commands, Remote -@subsection Remote Log +@subsubsection Remote Log @kindex eb.log @cindex log file for EB29K The @samp{target amd-eb} command creates a file @file{eb.log} in the @@ -569,204 +732,28 @@ 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 _GDBN__ Commands and Displays - -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, -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 -_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 -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 _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 -differently when repeated because that is more useful. - -@kindex # -@cindex comment -A line of input starting with @samp{#} is a comment; it does nothing. -This is useful mainly in command files (@xref{Command Files}). - -@cindex online documentation -@kindex help -@table @code -@item help -@itemx help @var{category} -@itemx help @var{command} -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 -can then use @samp{help @var{category}} to list the individual commands -in a category. - -@kindex info version -@item info version -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 -_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 _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 _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 - +@node Stopping _GDBN__,,, +@section Stopping _GDBN__ @cindex exiting _GDBN__ @kindex quit 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 _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 -_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 _GDBN__ with the -command @samp{set}. You may check the status of any of these settings -with the command @samp{show}. - -@table @code -@kindex set editing -@cindex editing -@item set editing -@itemx set editing on -Enable command line editing (enabled by default). - -@item set editing off -Disable command line editing. - -@kindex show editing -@item show editing -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 _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 -value of the environmental variable @code{GDBHISTFILE}, or to -@code{./.gdb_history} if this variable is not set. - -@cindex history write -@kindex set history write -@item set history write -@itemx set history write on -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 _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 _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 - -@cindex history expansion -History expansion assigns special meaning to the character @samp{!} -(@pxref{Event Designators}). Since @samp{!} is also the logical not -operator in C, history expansion is off by default. If you decide to -enable history expansion with the @samp{set history expansion on} -command, you may sometimes need to follow @samp{!} (when it is used as -logical not, in an expression) with a space or a tab to prevent it from -being expanded. The @code{readline} history facilities will not attempt -substitution on the strings @samp{!=} and @samp{!(}, even when history -expansion is enabled. - -The commands to control history expansion are: - -@table @code - -@kindex set history expansion -@item set history expansion on -@itemx set history expansion -Enable history expansion. History expansion is off by default. +an end-of-file character (usually @kbd{C-d}). -@item set history expansion off -Disable history expansion. - -The @code{readline} code comes with more complete documentation of -editing and history expansion features. Users unfamiliar with @samp{emacs} -or @samp{vi} may wish to read it. @xref{Command Line Editing}. - -@kindex show history -@item show history -@itemx show history file -@itemx show history write -@itemx show history size -@itemx show history expansion -These commands display the state of the _GDBN__ history parameters. -@samp{show history} by itself displays all four states. +@cindex interrupt +An interrupt (often @kbd{C-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. -@kindex show -@kindex info set -@item show -@itemx info set -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 -values, you can use @samp{show} with no arguments; you may also use -@samp{info set}. Both commands produce the same display. +If you've been using _GDBN__ to control an attached process or device, +you can release it with the @samp{detach} command; @pxref{Attach}. -@end table - -@table @code -@kindex info editing -@item info editing -Display the last ten commands in the command history. - -@item info editing @var{n} -Print ten commands centered on command number @var{n}. - -@item info editing + -Print ten commands just after the commands last printed. - -@end table - -Occasionally it is useful to execute a shell command from within _GDBN__. -This can be done with the @samp{shell} command. +@node Shell Commands,,, +@section Shell Commands +If you just need to execute occasional shell commands during your +debugging session, there's no need to stop or suspend _GDBN__; you can +just use the @samp{shell} command. @table @code @item shell @var{command string} @@ -788,396 +775,146 @@ 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 _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 _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: +@node Commands,,, +@chapter _GDBN__ Commands -_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. +@node Command Syntax,,, +@section Command Syntax +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, +as in @samp{step 5}. You can also use the @samp{step} command with +no arguments. Some command names do not allow any arguments. -@table @code -@item set screen-height @var{lpp} -@itemx show screen-height -@itemx set screen-width @var{cpl} -@itemx show screen-width -@kindex set screen-height -@kindex set screen-width -@kindex show screen-width -@kindex show screen-height -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. +@cindex abbreviation +_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 +equivalent to @samp{step} even though there are other commands whose +names start with @samp{s}. -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 repeating commands +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 +differently when repeated because that is more useful. -@cindex number representation -@cindex entering numbers -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 -10; likewise, the default display for numbers---when no particular -format is specified---is base 10. You can change the default base for -both input and output with the @samp{set radix} command. +@kindex # +@cindex comment +A line of input starting with @samp{#} is a comment; it does nothing. +This is useful mainly in command files (@xref{Command Files}). -@table @code -@kindex set radix -@item set radix @var{base} -Set the default base for numeric input and display. Supported choices -for @var{base} are decimal 8, 10, 16. @var{base} must itself be -specified either unambiguously or using the current default radix; for -example, any of +@node Help,,, +@section Getting Help +@cindex online documentation +@kindex help +You can always ask _GDBN__ itself for information on its commands, using the +command @samp{help}. +@table @code +@item help +Used with no arguments, @samp{help} displays a short list of named +categories of commands: @example -set radix 012 -set radix 10. -set radix 0xa +(_GDBP__) help +List of classes of commands: + +running -- Running the program +stack -- Examining the stack +data -- Examining data +breakpoints -- Making program stop at certain points +files -- Specifying and examining files +status -- Status inquiries +support -- Support facilities +user-defined -- User-defined commands +aliases -- Aliases of other commands +obscure -- Obscure features + +Type "help" followed by a class name for a list of commands in that class. +Type "help" followed by command name for full documentation. +Command name abbreviations are allowed if unambiguous. +(_GDBP__) @end example -@noindent -will set the base to decimal. On the other hand, @samp{set radix 10} -will leave the radix unchanged no matter what it was. - -@kindex show radix -@item show radix -Display the current default base for numeric input and display. - -@end table - -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 _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 -announce that the symbol table for a source file is being read -(@pxref{Files}, in the description of the command -@samp{symbol-file}). -@c The following is the right way to do it, but emacs 18.55 doesn't support -@c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo -@c is released. -@ignore -see @samp{symbol-file} in @ref{Files}). -@end ignore - -@table @code -@kindex set verbose -@item set verbose on -Enables _GDBN__'s output of certain informational messages. - -@item set verbose off -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 _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. -@xref{Files}. - -@table @code -@kindex set complaints -@item set complaints @var{limit} -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 _GDBN__ is permitted to produce. -@end table - -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: +@item help @var{category} +Using one of the general help categories as an argument, you can get a +list of the individual commands in a category. For example, here is the +help display for category @samp{status}: @example +(_GDBP__) help status +Status inquiries. -(_GDBP__) run -The program being debugged has been started already. -Start it from the beginning? (y or n) -@end example +List of commands: -If you're willing to unflinchingly face the consequences of your own -commands, you can disable this ``feature'': +show -- Generic command for showing things set with "set" +info -- Generic command for printing status -@table @code -@kindex set caution -@cindex flinching -@cindex stupid questions -@item set caution off -Disables cautious questions. - -@item set caution on -Enables cautious questions (the default). +Type "help" followed by command name for full documentation. +Command name abbreviations are allowed if unambiguous. +(_GDBP__) +@end example -@item show caution -@kindex show caution -Displays state of cautious questions. +@item help @var{command} +With a command name as @samp{help} argument, _GDBN__ will display a +short paragraph on how to use that command. @end table -@node Files, Compilation, User Interface, Top -@chapter Specifying _GDBN__'s Files - -@cindex core dump file -@cindex executable file -@cindex symbol table -_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, _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 _GDBN__, as discussed in -@pxref{Invocation}. - -But occasionally it is necessary to change to a different file during a -_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 -@item file @var{filename} -@kindex file -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 _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. - -@samp{file} with no argument makes both executable file and symbol -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}. _GDBN__ will search the environment variable @code{PATH} -if necessary to locate the program. - -@item symbol-file @var{filename} -@kindex symbol-file -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 _GDBN__'s information on your -program's symbol table. - -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 _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 -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 _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 -messages if desired. @xref{User Interface}). - -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 _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 -compilers that adhere to the local conventions. Best results are -usually obtained from _GCC__; for example, using _GCC__ you can generate -debugging information for optimized code. - -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 -ask it to print more messages, to see how many times the problems occur, -or can shut the messages off entirely, with the @samp{set -complaints} command (@xref{User Interface}). - -The messages currently printed, and their meanings, are: +In addition to @samp{help}, you can use the _GDBN__ commands @samp{info} +and @samp{show} to inquire about the state of your program, or the state +of _GDBN__ itself. Both commands support many ``sub-commands'', or +topics of inquiry; this manual introduces each of them in the +appropriate context. The listings under ``@code{info}'' and under +``@code{show}'' in the Index point to all the sub-commands +(@pxref{Index}). @table @code -@item inner block not inside outer block in @var{symbol} - -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. _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. - -@item block at @var{address} out of order - -The symbol information for symbol scope blocks should occur in -order of increasing addresses. This error indicates that it does not -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}.) - -@item bad block start address patched - -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. _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 _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 -@comment a previous release of the G++ compiler. This message is probably -@comment obsolete. -@comment -@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. _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 _GDBN__ does not yet -know how to read. @code{0xNN} is the symbol type of the misunderstood -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 _GDBP__ -with itself, breakpoint on "complain", then go "up" to -read_dbx_symtab() and examine *bufp to see the symbol. - -@c @item stub type has NULL name -@c -@c FIXME, Mike Tiemann needs to write about what this means. - -@item const/volatile indicator missing, got 'X' - -The symbol information for a C++ type is missing some information that -the compiler should have output for it. - -@item C++ type mismatch between compiler and debugger - -The debugger could not parse a type specification output by the compiler -for some C++ object. - -@end table - -@item core-file @var{filename} -@itemx core @var{filename} -@kindex core -@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; _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 _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}). - -@item load @var{filename} -@kindex load -This command will dynamically link @var{filename} on the current target, -performing any necessary downloads, then add @var{filename}'s symbol -table in the same way as the @samp{add-syms} command. - -@item add-syms @var{filename} @var{address} -@kindex add-syms -@cindex dynamic linking -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; _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 _GDBN__ has read. - -@item info files -@itemx info target -@kindex info files -@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 _GDBN__, and the files -from which symbols were loaded. +@kindex info +@item info +This command is for describing the state of your program; for example, +it can list the arguments given to your program (@samp{info args}), the +registers currently in use (@samp{info registers}), or the breakpoints +you've set (@samp{info breakpoints}). You can get a complete list of +the @code{info} sub-commands with @samp{help info}. -Beware: the similar command @samp{info targets} lists all possible -targets rather than current ones. - -@end table - -While all three file-specifying commands allow both absolute and relative -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 - -_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 -files.) Once the shared library has been linked in, you can use the -following commands: - -@table @code -@item sharedlibrary @var{regex} -@itemx share @var{regex} -Load shared object library symbols for files matching a UNIX regular -expression. +@kindex show +@item show +In contrast, @samp{show} is for describing the state of _GDBN__ itself. +You can change most of the things you can @code{show}, by using the +related command @samp{set}; for example, you can control what number +system is used for displays with @samp{set radix}, or simply inquire +which possibility is currently in use with @samp{show radix}. -@item share -@itemx sharedlibrary -Load symbols for all shared libraries. +@kindex info set +To display all the settable parameters and their current +values, you can use @samp{show} with no arguments; you may also use +@samp{info set}. Both commands produce the same display. +@c FIXME: "info set" violates the rule that "info" is for state of +@c FIXME...program. Ck w/ GNU: "info set" to be called something else, +@c FIXME...or change desc of rule---eg "state of prog and debugging session"? + + +@kindex show version +@item show version +@c FIXME: chgd to "show version" from "info". Verify John doing same to GDBv4. +This @samp{show} subcommand is one of those with no corresponding +@samp{set} subcommand. 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. It is also useful to include this +information in _GDBN__ bug-reports. _GDBN__ announces its version +number if you start it with no arguments; but you can make it give this +information on request, with the @samp{show version} command. -@item info share -@itemx info sharedlibrary -@kindex info sharedlibrary -@kindex info share -Print the names of the shared libraries which are currently loaded. @end table +@node Running,,, +@chapter Running Programs Under _GDBN__ -@node Compilation, Targets, Files, Top -@chapter Compiling for Debugging +@node Compilation,,, +@section Compiling for Debugging In order to debug a program effectively, you need to ask for debugging information when you compile it. This debugging information is stored @@ -1222,138 +959,10 @@ option or use shorter file names. Alternatively, use a version of GNU @code{ar} dated more recently than August 1989. @end ignore -@node Targets, Running, Compilation, Top -@chapter Specifying a Debugging Target -@cindex debugging target -@kindex target -A @dfn{target} is an interface between the debugger and a particular -kind of file or process. - -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 _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. - -@menu -* Active Targets:: Active Targets -* Target Commands:: Commands for Managing Targets -@end menu - -@node Active Targets, Target Commands, Targets, Targets -@section Active Targets -@cindex stacking targets -@cindex active targets -@cindex multiple targets - -Targets are managed in three @dfn{strata} that correspond to different -classes of target: processes, core files, and executable files. This -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 _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 -one, then a core file if there is one, and finally an executable file if -there is one of those. - -When you specify a new target in a given stratum, it replaces any target -previously in that stratum. - -To get rid of a target without replacing it, use the @samp{detach} -command. The related command @samp{attach} provides you with a way of -choosing a particular running process as a new target. @xref{Attach}. - -@node Target Commands, , Active Targets, Targets -@section Commands for Managing Targets - -@table @code -@item target @var{type} @var{parameters} -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 -a VxWorks system. - -Further @var{parameters} are interpreted by the target protocol, but -typically include things like device names or host names to connect -with, process numbers, and baud rates. Executing -@example - target @var{type} -@end example - -@noindent -(without any parameters) will issue a message about what -parameters are required for that target type. - -@item info targets -@kindex info targets -Displays the names of all targets available. Beware: the similar -command @samp{info target} displays targets currently in use rather than -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 _GDBN__ -configuration): - -@table @code -@item target exec @var{prog} -@kindex target exec -An executable file. @samp{target exec @var{prog}} is the same as -@samp{exec-file @var{prog}}. - -@item target core @var{filename} -@kindex target core -A core dump file. @samp{target core @var{filename}} is the same as -@samp{core-file @var{filename}}. - -@item target remote @var{dev} -@kindex target remote -Remote serial target in _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 -Remote PC-resident AMD EB29K board, attached over serial lines. -@var{dev} is the serial device, as for @samp{target remote}; -@samp{speed} allows you to specify the linespeed; and @var{PROG} is the -name of the program to be debugged, as it appears to DOS on the PC. -@xref{AMD29K Remote}. - -_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 - -_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 _GDBN__ +@node Starting,,, +@section Starting your Program +@cindex starting @cindex running @kindex run To start your program under _GDBN__, use the @samp{run} command. Except on @@ -1528,9 +1137,9 @@ 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, -@example +_0__@example run > outfile -@end example +_1__@end example @noindent starts the program, diverting its output to the file @file{outfile}. @@ -2139,7 +1748,7 @@ is not checked. Once the ignore count reaches zero, the condition will be checked. Note that you could achieve the effect of the ignore count with a -condition such as @w{@samp{$foo-- <= 0}} using a debugger convenience +condition such as _0__@w{@samp{$foo-- <= 0}}_1__ using a debugger convenience variable that is decremented each time. @xref{Convenience Vars}. @node Break Commands, Error in Breakpoints, Conditions, Breakpoints @@ -2185,7 +1794,7 @@ controlled output are often useful in silent breakpoints. @xref{Output}. For example, here is how you could use breakpoint commands to print the value of @code{x} at entry to @code{foo} whenever it is positive. -@example +_0__@example break foo if x>0 commands silent @@ -2194,7 +1803,7 @@ output x echo \n cont end -@end example +_1__@end example One application for breakpoint commands is to correct one bug so you can test another. Put a breakpoint just after the erroneous line of code, give @@ -3248,7 +2857,7 @@ nearest preceding symbol. This format can be used to discover where (in what function) an unknown address is located: @example (_GDBP__) p/a 0x54320 -$3 = 0x54320 <_initialize_vx+396> +_0__$3 = 0x54320 <_initialize_vx+396>_1__ @end example @@ -3627,11 +3236,11 @@ Abbreviated @samp{i con}. One of the ways to use a convenience variable is as a counter to be incremented or a pointer to be advanced. For example: -@example +_0__@example set $i = 0 print bar[$i++]->contents @i{@dots{}repeat that command by typing @key{RET}.} -@end example +_1__@end example Some convenience variables are created automatically by _GDBN__ and given values likely to be useful. @@ -3868,7 +3477,7 @@ the value of the assignment expression (which is 4). All the assignment operators of C are supported, including the increment operators @samp{++} and @samp{--}, and combining -assignments such as @samp{+=} and @samp{<<=}. +assignments such as @samp{+=} and _0__@samp{<<=}_1__. @kindex set @kindex set variable @@ -4012,6 +3621,725 @@ execute some piece of your program, but without cluttering the output with @code{void} returned values. The result is printed and saved in the value history, if it is not void. +@node Files,,, +@chapter _GDBN__'s Files + +@section Commands to Specify Files +@cindex core dump file +@cindex symbol table +_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, _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 _GDBN__, as discussed in +@pxref{Invocation}. + +But occasionally it is necessary to change to a different file during a +_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 +@item file @var{filename} +@cindex executable file +@kindex file +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 _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. + +@samp{file} with no argument makes both executable file and symbol +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}. _GDBN__ will search the environment variable @code{PATH} +if necessary to locate the program. + +@item symbol-file @var{filename} +@kindex symbol-file +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 _GDBN__'s information on your +program's symbol table. + +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 _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 +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 _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 +messages if desired. @xref{User Interface}). + +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 _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 +compilers that adhere to the local conventions. Best results are +usually obtained from _GCC__; for example, using _GCC__ you can generate +debugging information for optimized code. + +@item core-file @var{filename} +@itemx core @var{filename} +@kindex core +@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; _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 _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}). + +@item load @var{filename} +@kindex load +This command will dynamically link @var{filename} on the current target, +performing any necessary downloads, then add @var{filename}'s symbol +table in the same way as the @samp{add-syms} command. + +@item add-syms @var{filename} @var{address} +@kindex add-syms +@cindex dynamic linking +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; _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 _GDBN__ has read. + +@item info files +@itemx info target +@kindex info files +@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 _GDBN__, and the files +from which symbols were loaded. + +Beware: the similar command @samp{info targets} lists all possible +targets rather than current ones. + +@end table + +While all three file-specifying commands allow both absolute and relative +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 + +_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 +files.) Once the shared library has been linked in, you can use the +following commands: + +@table @code +@item sharedlibrary @var{regex} +@itemx share @var{regex} +Load shared object library symbols for files matching a UNIX regular +expression. + +@item share +@itemx sharedlibrary +Load symbols for all shared libraries. + +@item info share +@itemx info sharedlibrary +@kindex info sharedlibrary +@kindex info share +Print the names of the shared libraries which are currently loaded. +@end table + +@section Errors Reading Symbols +While a 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 +ask it to print more messages, to see how many times the problems occur, +or can shut the messages off entirely, with the @samp{set +complaints} command (@xref{User Interface}). + +The messages currently printed, and their meanings, are: + +@table @code +@item inner block not inside outer block in @var{symbol} + +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. _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. + +@item block at @var{address} out of order + +The symbol information for symbol scope blocks should occur in +order of increasing addresses. This error indicates that it does not +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}.) + +@item bad block start address patched + +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. _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 _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 +@comment a previous release of the G++ compiler. This message is probably +@comment obsolete. +@comment +@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. _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 _GDBN__ does not yet +know how to read. @code{0xNN} is the symbol type of the misunderstood +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 _GDBP__ +with itself, breakpoint on "complain", then go "up" to +read_dbx_symtab() and examine *bufp to see the symbol. + +@c @item stub type has NULL name +@c +@c FIXME, Mike Tiemann needs to write about what this means. + +@item const/volatile indicator missing, got 'X' + +The symbol information for a C++ type is missing some information that +the compiler should have output for it. + +@item C++ type mismatch between compiler and debugger + +The debugger could not parse a type specification output by the compiler +for some C++ object. + +@end table + +@node Targets, Running, Compilation, Top +@chapter Specifying a Debugging Target +@cindex debugging target +@kindex target +A @dfn{target} is an interface between the debugger and a particular +kind of file or process. + +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 _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. + +@menu +* Active Targets:: Active Targets +* Target Commands:: Commands for Managing Targets +@end menu + +@node Active Targets, Target Commands, Targets, Targets +@section Active Targets +@cindex stacking targets +@cindex active targets +@cindex multiple targets + +Targets are managed in three @dfn{strata} that correspond to different +classes of target: processes, core files, and executable files. This +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 _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 +one, then a core file if there is one, and finally an executable file if +there is one of those. + +When you specify a new target in a given stratum, it replaces any target +previously in that stratum. + +To get rid of a target without replacing it, use the @samp{detach} +command. The related command @samp{attach} provides you with a way of +choosing a particular running process as a new target. @xref{Attach}. + +@node Target Commands, , Active Targets, Targets +@section Commands for Managing Targets + +@table @code +@item target @var{type} @var{parameters} +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 +a VxWorks system. + +Further @var{parameters} are interpreted by the target protocol, but +typically include things like device names or host names to connect +with, process numbers, and baud rates. Executing +@example + target @var{type} +@end example + +@noindent +(without any parameters) will issue a message about what +parameters are required for that target type. + +@item info targets +@kindex info targets +Displays the names of all targets available. Beware: the similar +command @samp{info target} displays targets currently in use rather than +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 _GDBN__ +configuration): + +@table @code +@item target exec @var{prog} +@kindex target exec +An executable file. @samp{target exec @var{prog}} is the same as +@samp{exec-file @var{prog}}. + +@item target core @var{filename} +@kindex target core +A core dump file. @samp{target core @var{filename}} is the same as +@samp{core-file @var{filename}}. + +@item target remote @var{dev} +@kindex target remote +Remote serial target in _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 +Remote PC-resident AMD EB29K board, attached over serial lines. +@var{dev} is the serial device, as for @samp{target remote}; +@samp{speed} allows you to specify the linespeed; and @var{PROG} is the +name of the program to be debugged, as it appears to DOS on the PC. +@xref{EB29K 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 + +_if__(_GENERIC__) +Different targets are available on different configurations of _GDBN__; your +configuration may have more or fewer targets. +_fi__(_GENERIC__) + +@node Remote,,, +@section Remote Debugging +@cindex remote debugging + +If you are trying to debug a program running on a machine that can't run +_GDBN__ in the usual way, it is often useful to use remote debugging. For +example, you might be debugging an operating system kernel, or debugging +a small system which does not have a general purpose operating system +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 _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 _GDBN__ +source file @file{remote.c}. + +@node Remote Commands, , Remote, Remote +@subsection Commands for Remote Debugging + +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: + +@example +target remote /dev/ttyb +@end example + +@noindent +if the serial line is connected to the device named @file{/dev/ttyb}. This +will stop the remote machine if it is not already stopped. + +Now you can use all the usual commands to examine and change data and to +step and continue the remote program. + +To resume the remote program and stop debugging it, use the @samp{detach} +command. + +Other remote targets be available in your +configuration of _GDBN__; use @samp{info targets} to list them. + +@table @code +@item reset +@kindex reset +For a target attached through a serial line, this command sends a +``break'' to the remote target system; this is only useful if the target +has been equipped with a circuit to perform a hard reset (or some other +interesting action) when a break is detected. +@end table + +@node Controlling _GDBN__,,, +@chapter Controlling _GDBN__ + +You can alter many aspects of _GDBN__'s interaction with you by using +the @samp{set} command. + +@node Prompt,,, +@section Prompt +@cindex prompt +_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 _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 _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 + +@node Editing/History,,, +@section Command Editing and History +@cindex readline +@cindex command line editing +@cindex history substitution +_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 _GDBN__ with the +command @samp{set}. You may check the status of any of these settings +with the command @samp{show}. + +@table @code +@kindex set editing +@cindex editing +@item set editing +@itemx set editing on +Enable command line editing (enabled by default). + +@item set editing off +Disable command line editing. + +@kindex show editing +@item show editing +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 _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 +value of the environmental variable @code{GDBHISTFILE}, or to +@code{./.gdb_history} if this variable is not set. + +@cindex history write +@kindex set history write +@item set history write +@itemx set history write on +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 _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 _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 + +@cindex history expansion +History expansion assigns special meaning to the character @samp{!} +(@pxref{Event Designators}). Since @samp{!} is also the logical not +operator in C, history expansion is off by default. If you decide to +enable history expansion with the @samp{set history expansion on} +command, you may sometimes need to follow @samp{!} (when it is used as +logical not, in an expression) with a space or a tab to prevent it from +being expanded. The @code{readline} history facilities will not attempt +substitution on the strings @samp{!=} and @samp{!(}, even when history +expansion is enabled. + +The commands to control history expansion are: + +@table @code + +@kindex set history expansion +@item set history expansion on +@itemx set history expansion +Enable history expansion. History expansion is off by default. + +@item set history expansion off +Disable history expansion. + +The @code{readline} code comes with more complete documentation of +editing and history expansion features. Users unfamiliar with @samp{emacs} +or @samp{vi} may wish to read it. @xref{Command Line Editing}. + +@kindex show history +@item show history +@itemx show history file +@itemx show history write +@itemx show history size +@itemx show history expansion +These commands display the state of the _GDBN__ history parameters. +@samp{show history} by itself displays all four states. + +@end table + +@table @code +@kindex info editing +@item info editing +Display the last ten commands in the command history. + +@item info editing @var{n} +Print ten commands centered on command number @var{n}. + +@item info editing + +Print ten commands just after the commands last printed. + +@end table + +@node Screen Size,,, +@section Screen Size +@cindex size of screen +@cindex pauses in output +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 _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: + +_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. + +@table @code +@item set screen-height @var{lpp} +@itemx show screen-height +@itemx set screen-width @var{cpl} +@itemx show screen-width +@kindex set screen-height +@kindex set screen-width +@kindex show screen-width +@kindex show screen-height +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, _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 + +@node Numbers,,, +@section Numbers +@cindex number representation +@cindex entering numbers +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 +10; likewise, the default display for numbers---when no particular +format is specified---is base 10. You can change the default base for +both input and output with the @samp{set radix} command. + +@table @code +@kindex set radix +@item set radix @var{base} +Set the default base for numeric input and display. Supported choices +for @var{base} are decimal 8, 10, 16. @var{base} must itself be +specified either unambiguously or using the current default radix; for +example, any of + +@example +set radix 012 +set radix 10. +set radix 0xa +@end example + +@noindent +will set the base to decimal. On the other hand, @samp{set radix 10} +will leave the radix unchanged no matter what it was. + +@kindex show radix +@item show radix +Display the current default base for numeric input and display. + +@end table + +@node Messages/Warnings,,, +@section Optional Warnings and Messages +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 _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 +announce that the symbol table for a source file is being read +(@pxref{Files}, in the description of the command +@samp{symbol-file}). +@c The following is the right way to do it, but emacs 18.55 doesn't support +@c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo +@c is released. +@ignore +see @samp{symbol-file} in @ref{Files}). +@end ignore + +@table @code +@kindex set verbose +@item set verbose on +Enables _GDBN__'s output of certain informational messages. + +@item set verbose off +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 _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. +@xref{Files}. + +@table @code +@kindex set complaints +@item set complaints @var{limit} +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 _GDBN__ is permitted to produce. +@end table + +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 + +(_GDBP__) run +The program being debugged has been started already. +Start it from the beginning? (y or n) +@end example + +If you're willing to unflinchingly face the consequences of your own +commands, you can disable this ``feature'': + +@table @code +@kindex set caution +@cindex flinching +@cindex stupid questions +@item set caution off +Disables cautious questions. + +@item set caution on +Enables cautious questions (the default). + +@item show caution +@kindex show caution +Displays state of cautious questions. +@end table + @node Sequences, Emacs, Altering, Top @chapter Canned Sequences of Commands @@ -4205,7 +4533,7 @@ All the facilities of Emacs' Shell mode are available for this purpose. @item _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. +and puts an arrow (_0__@samp{=>}_1__) at the left margin of the current line. Emacs uses a separate buffer for source display, and splits the window to show both your _GDBN__ session and the source. @@ -4330,66 +4658,6 @@ environment. Users of this environment can use a new command, each value is printed in its own window. @end ignore -@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 -_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 _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 _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 _GDBN__ -source file @file{remote.c}. - -@node Remote Commands, , Remote, Remote -@section Commands for Remote Debugging - -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: - -@example -target remote /dev/ttyb -@end example - -@noindent -if the serial line is connected to the device named @file{/dev/ttyb}. This -will stop the remote machine if it is not already stopped. - -Now you can use all the usual commands to examine and change data and to -step and continue the remote program. - -To resume the remote program and stop debugging it, use the @samp{detach} -command. - -Other remote targets be available in your -configuration of _GDBN__; use @samp{info targets} to list them. - -@table @code -@item reset -@kindex reset -For a target attached through a serial line, this command sends a -``break'' to the remote target system; this is only useful if the target -has been equipped with a circuit to perform a hard reset (or some other -interesting action) when a break is detected. -@end table - @node _GDBN__ Bugs, Installing _GDBN__, Remote, Top @comment node-name, next, previous, up @chapter Reporting Bugs in _GDBN__ @@ -4445,23 +4713,12 @@ for improvement of _GDBN__ are welcome in any case. @cindex Bug Reports @cindex Compiler Bugs, Reporting -@comment The following is meant to be neutral and helpful, not just a plug for -@comment Cygnus; feedback on the issue (to "pesch@cygnus.com" or -@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 _GDBN__ from a support organization, we recommend you contact that organization first. -Among these organizations are Cygnus Support (Palo Alto CA, USA); C2V -(Paris, France); Dynamix Corporation (King of Prussia PA, USA); The Nice -Computer Company (Perth, Australia); Optimal Solutions (Seattle WA, -USA); and The Pharos Group (Las Cruces NM, USA). - -Full contact information is in the file @samp{etc/SERVICE} in the GNU -Emacs distribution. Numerous individual consultants are also listed -there. -@comment END NEUTRAL+HELPFUL section +Contact information for many support companies and individuals is +available in the file @samp{etc/SERVICE} in the GNU Emacs distribution. In any event, we also recommend that you send bug reports for _GDBN__ to one of these addresses: @@ -4520,8 +4777,8 @@ To enable us to fix the bug, you should include all these things: @itemize @bullet @item -The version of _GDBN__. _GDBN__ announces it on startup; you can also print it -at any time using @samp{info version}. +The version of _GDBN__. _GDBN__ announces it if you start with no +arguments; you can also print it at any time using @samp{show version}. Without this, we won't know whether there is any point in looking for the bug in the current version of _GDBN__. @@ -4972,15 +5229,25 @@ Ty Coon, President of Vice That's all there is to it! -@node Commands, Concepts, License, Top -@unnumbered Command Index - -@printindex ky - -@node Concepts, , Commands, Top +@node Index,,, @unnumbered Index @printindex cp +@tex +% I think something like @colophon should be in texinfo. In the +% meantime: +\long\def\colophon{\hbox to0pt{}\vfill +\centerline{The body of this manual is set in} +\centerline{\fontname\tenrm,} +\centerline{with headings in {\bf\fontname\tenbf}} +\centerline{and examples in {\tt\fontname\tentt}.} +\centerline{{\it\fontname\tenit\/} and} +\centerline{{\sl\fontname\tensl\/}} +\centerline{are used for emphasis.}\vfill} +\page\colophon +% Blame: pesch@cygnus.com, 28mar91. +@end tex + @contents @bye |