diff options
Diffstat (limited to 'gdb')
| -rw-r--r-- | gdb/doc/ChangeLog | 10 | ||||
| -rw-r--r-- | gdb/doc/annotate.texi | 268 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 111 |
3 files changed, 266 insertions, 123 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 7e1eb34..f707426 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,13 @@ +2000-03-16 Eli Zaretskii <eliz@is.elta.co.il> + + * gdb.texinfo (main menu): Add Annotations. + (File Options): Add @cindex entries for each command-line option. + Document --epoch, --annotate, --async, --interpreter, --write, + --statistics, and --version. + + * annotate.texi: Convert to a chapter. Use @value{GDBN} instead + of GDB. + 2000-02-23 Jim Blandy <jimb@redhat.com> * gdbint.texinfo (FUNCTION_START_OFFSET): Document. diff --git a/gdb/doc/annotate.texi b/gdb/doc/annotate.texi index 9d5850d..cd7cdf7 100644 --- a/gdb/doc/annotate.texi +++ b/gdb/doc/annotate.texi @@ -1,85 +1,93 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename annotate.info -@settitle GDB Annotations -@setchapternewpage off -@c %**end of header - -@set EDITION 0.5 -@set DATE May 1994 - -@ifinfo -This file documents GDB annotations. - -This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB -Annotations}. Copyright 1994 Free Software Foundation - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end ifinfo - -@titlepage -@title GDB Annotations -@subtitle Edition @value{EDITION} -@subtitle @value{DATE} -@author Cygnus Support -@page -@vskip 0pt plus 1filll -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Copyright @copyright{} 1994 Free Software Foundation -@end titlepage - -@ifinfo -@node Top -@top GDB Annotations - -This file describes annotations in GDB, the GNU symbolic debugger. -Annotations are designed to interface GDB to graphical user interfaces -or other similar programs which want to interact with GDB at a +@c \input texinfo @c -*-texinfo-*- +@c @c %**start of header +@c @setfilename annotate.info +@c @settitle GDB Annotations +@c @setchapternewpage off +@c @c %**end of header + +@c @set EDITION 0.5 +@c @set DATE May 1994 + +@c @ifinfo +@c This file documents GDB annotations. + +@c This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB +@c Annotations}. Copyright 1994 Free Software Foundation + +@c Permission is granted to make and distribute verbatim copies of +@c this manual provided the copyright notice and this permission notice +@c are preserved on all copies. +@c @end ignore + +@c @ignore +@c Permission is granted to process this file through TeX and print the +@c results, provided the printed document carries copying permission +@c notice identical to this one except for the removal of this paragraph +@c (this paragraph not being relevant to the printed manual). + +@c @end ignore +@c Permission is granted to copy and distribute modified versions of this +@c manual under the conditions for verbatim copying, provided also that the +@c entire resulting derived work is distributed under the terms of a +@c permission notice identical to this one. + +@c Permission is granted to copy and distribute translations of this manual +@c into another language, under the above conditions for modified versions. +@c @end ifinfo + +@c @titlepage +@c @title GDB Annotations +@c @subtitle Edition @value{EDITION} +@c @subtitle @value{DATE} +@c @author Cygnus Support +@c @page +@c @vskip 0pt plus 1filll +@c Permission is granted to make and distribute verbatim copies of +@c this manual provided the copyright notice and this permission notice +@c are preserved on all copies. + +@c Copyright @copyright{} 1994 Free Software Foundation +@c @end titlepage + +@c @ifinfo +@c @node Top +@c @top GDB Annotations + +@syncodeindex fn cp + +@node Annotations +@chapter @value{GDBN} Annotations + +This chapter describes annotations in @value{GDBN}, the GNU symbolic debugger. +Annotations are designed to interface @value{GDBN} to graphical user interfaces +or other similar programs which want to interact with @value{GDBN} at a relatively high level. +@ignore This is Edition @value{EDITION}, @value{DATE}. +@end ignore @menu -* General:: What annotations are; the general syntax. -* Server:: Issuing a command without affecting user state. -* Values:: Values are marked as such. -* Frames:: Stack frames are annotated. -* Displays:: GDB can be told to display something periodically. -* Prompting:: Annotations marking GDB's need for input. +* Annotations Overview:: What annotations are; the general syntax. +* Server Prefix:: Issuing a command without affecting user state. +* Value Annotations:: Values are marked as such. +* Frame Annotations:: Stack frames are annotated. +* Displays:: @value{GDBN} can be told to display something periodically. +* Prompting:: Annotations marking @value{GDBN}'s need for input. * Errors:: Annotations for error messages. * Breakpoint Info:: Information on breakpoints. * Invalidation:: Some annotations describe things now invalid. -* Running:: Whether the program is running, how it stopped, etc. -* Source:: Annotations describing source code. +* Annotations for Running:: + Whether the program is running, how it stopped, etc. +* Source Annotations:: Annotations describing source code. * TODO:: Annotations which might be added in the future. -* Index:: Index @end menu -@end ifinfo -@node General -@chapter What is an Annotation? +@node Annotations Overview +@section What is an Annotation? +@cindex annotations -To produce annotations, start GDB with the @code{--annotate=2} option. +To produce annotations, start @value{GDBN} with the @code{--annotate=2} option. Annotations start with a newline character, two @samp{control-z} characters, and the name of the annotation. If there is no additional @@ -90,20 +98,22 @@ additional information, and a newline. The additional information cannot contain newline characters. Any output not beginning with a newline and two @samp{control-z} -characters denotes literal output from GDB. Currently there is no need -for GDB to output a newline followed by two @samp{control-z} characters, +characters denotes literal output from @value{GDBN}. Currently there is no need +for @value{GDBN} to output a newline followed by two @samp{control-z} characters, but if there was such a need, the annotations could be extended with an @samp{escape} annotation which means those three characters as output. -A simple example of starting up GDB with annotations is: +A simple example of starting up @value{GDBN} with annotations is: -@example +@smallexample $ gdb --annotate=2 -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.12.3 (sparc-sun-sunos4.1.3), -Copyright 1994 Free Software Foundation, Inc. +GNU GDB 5.0 +Copyright 2000 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, and you are +welcome to change it and/or distribute copies of it under certain conditions. +Type "show copying" to see the conditions. +There is absolutely no warranty for GDB. Type "show warranty" for details. +This GDB was configured as "sparc-sun-sunos4.1.3" ^Z^Zpre-prompt (gdb) @@ -112,29 +122,31 @@ quit ^Z^Zpost-prompt $ -@end example +@end smallexample -Here @samp{quit} is input to GDB; the rest is output from GDB. The three +Here @samp{quit} is input to @value{GDBN}; the rest is output from @value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z} -character) are annotations; the rest is output from GDB. +character) are annotations; the rest is output from @value{GDBN}. -@node Server -@chapter The Server Prefix +@node Server Prefix +@section The Server Prefix +@cindex server prefix for annotations -To issue a command to GDB without affecting certain aspects of the state +To issue a command to @value{GDBN} without affecting certain aspects of the state which is seen by users, prefix it with @samp{server }. This means that this command will not affect the command history, nor will it affect -GDB's notion of which command to repeat if @key{RET} is pressed on a +@value{GDBN}'s notion of which command to repeat if @key{RET} is pressed on a line by itself. The server prefix does not affect the recording of values into the value history; to print a value without recording it into the value history, use the @code{output} command instead of the @code{print} command. -@node Values -@chapter Values +@node Value Annotations +@section Values -When a value is printed in various contexts, GDB uses annotations to +@cindex annotations for values +When a value is printed in various contexts, @value{GDBN} uses annotations to delimit the value from the surrounding text. @findex value-history-begin @@ -172,7 +184,7 @@ or it is printed with the @code{output} command), the annotation is similar: @findex arg-name-end @findex arg-value @findex arg-end -When GDB prints an argument to a function (for example, in the output +When @value{GDBN} prints an argument to a function (for example, in the output from the @code{backtrace} command), it annotates it as follows: @example @@ -195,7 +207,7 @@ for the user's benefit (such as @samp{=}), and @var{value-flags} and @findex field-name-end @findex field-value @findex field-end -When printing a structure, GDB annotates it as follows: +When printing a structure, @value{GDBN} annotates it as follows: @example ^Z^Zfield-begin @var{value-flags} @@ -212,7 +224,7 @@ is text which separates the name from the value for the user's benefit (such as @samp{=}), and @var{value-flags} and @var{the-value} have the same meanings as in a @code{value-history-begin} annotation. -When printing an array, GDB annotates it as follows: +When printing an array, @value{GDBN} annotates it as follows: @example ^Z^Zarray-section-begin @var{array-index} @var{value-flags} @@ -257,11 +269,12 @@ ended with ^Z^Zarray-section-end @end example -@node Frames -@chapter Frames +@node Frame Annotations +@section Frames -Whenever GDB prints a frame, it annotates it. For example, this applies -to frames printed when GDB stops, output from commands such as +@cindex annotations for frames +Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies +to frames printed when @value{GDBN} stops, output from commands such as @code{backtrace} or @code{up}, etc. @findex frame-begin @@ -296,7 +309,7 @@ consist of @end example where @var{function-call-string} is text designed to convey to the user -that this frame is associated with a function call made by GDB to a +that this frame is associated with a function call made by @value{GDBN} to a function in the program being debugged. @item @@ -347,7 +360,7 @@ Then comes where @var{function-name} is the name of the function executing in the frame, or @samp{??} if not known, and @var{arguments} are the arguments to the frame, with parentheses around them (each argument is annotated -individually as well @pxref{Values}). +individually as well, @pxref{Value Annotations}). @findex frame-source-begin @findex frame-source-file @@ -374,7 +387,7 @@ the source file, and @var{line-number} is the line number within that file (the first line is line 1). @findex frame-where -If GDB prints some information about where the frame is from (which +If @value{GDBN} prints some information about where the frame is from (which library, which load segment, etc.; currently only done on the RS/6000), it is annotated with @@ -391,7 +404,7 @@ output, not in addition. @end itemize @node Displays -@chapter Displays +@section Displays @findex display-begin @findex display-number-end @@ -400,7 +413,8 @@ output, not in addition. @findex display-expression-end @findex display-value @findex display-end -When GDB is told to display something using the @code{display} command, +@cindex annotations for display +When @value{GDBN} is told to display something using the @code{display} command, the results of the display are annotated: @example @@ -428,9 +442,10 @@ to separate the expression from the text that follows for the user, and @var{value} is the actual value being displayed. @node Prompting -@chapter Annotation for GDB Input +@section Annotation for @value{GDBN} Input -When GDB prompts for input, it annotates this fact so it is possible +@cindex annotations for prompts +When @value{GDBN} prompts for input, it annotates this fact so it is possible to know when to send output, when the output from a given command is over, etc. @@ -455,60 +470,61 @@ The input types are @findex prompt @findex post-prompt @item prompt -When GDB is prompting for a command (the main GDB prompt). +When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). @findex pre-commands @findex commands @findex post-commands @item commands -When GDB prompts for a set of commands, like in the @code{commands} +When @value{GDBN} prompts for a set of commands, like in the @code{commands} command. The annotations are repeated for each command which is input. @findex pre-overload-choice @findex overload-choice @findex post-overload-choice @item overload-choice -When GDB wants the user to select between various overloaded functions. +When @value{GDBN} wants the user to select between various overloaded functions. @findex pre-query @findex query @findex post-query @item query -When GDB wants the user to confirm a potentially dangerous operation. +When @value{GDBN} wants the user to confirm a potentially dangerous operation. @findex pre-prompt-for-continue @findex prompt-for-continue @findex post-prompt-for-continue @item prompt-for-continue -When GDB is asking the user to press return to continue. Note: Don't +When @value{GDBN} is asking the user to press return to continue. Note: Don't expect this to work well; instead use @code{set height 0} to disable prompting. This is because the counting of lines is buggy in the presence of annotations. @end table @node Errors -@chapter Errors +@section Errors +@cindex annotations for errors, warnings and interrupts @findex quit @example ^Z^Zquit @end example -This annotation occurs right before GDB responds to an interrupt. +This annotation occurs right before @value{GDBN} responds to an interrupt. @findex error @example ^Z^Zerror @end example -This annotation occurs right before GDB responds to an error. +This annotation occurs right before @value{GDBN} responds to an error. -Quit and error annotations indicate that any annotations which GDB was +Quit and error annotations indicate that any annotations which @value{GDBN} was in the middle of may end abruptly. For example, if a @code{value-history-begin} annotation is followed by a @code{error}, one cannot expect to receive the matching @code{value-history-end}. One cannot expect not to receive it either, however; an error annotation -does not necessarily mean that GDB is immediately returning all the way +does not necessarily mean that @value{GDBN} is immediately returning all the way to the top level. @findex error-begin @@ -526,8 +542,9 @@ Warning messages are not yet annotated. @c range_error(), and possibly other places. @node Breakpoint Info -@chapter Information on Breakpoints +@section Information on Breakpoints +@cindex annotations for breakpoints The output from the @code{info breakpoints} command is annotated as follows: @findex breakpoints-headers @@ -582,8 +599,9 @@ The output ends with @end example @node Invalidation -@chapter Invalidation Notices +@section Invalidation Notices +@cindex annotations for invalidation messages The following annotations say that certain pieces of state may have changed. @@ -601,12 +619,13 @@ The breakpoints may have changed. For example, the user just added or deleted a breakpoint. @end table -@node Running -@chapter Running the Program +@node Annotations for Running +@section Running the Program +@cindex annotations for running programs @findex starting @findex stopping -When the program starts executing due to a GDB command such as +When the program starts executing due to a @value{GDBN} command such as @code{step} or @code{continue}, @example @@ -657,7 +676,7 @@ user's benefit and have no particular format. @findex signal @item ^Z^Zsignal -The syntax of this annotation is just like @code{signalled}, but GDB is +The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is just saying that the program received the signal, not that it was terminated with it. @@ -670,8 +689,9 @@ The program hit breakpoint number @var{number}. The program hit watchpoint number @var{number}. @end table -@node Source -@chapter Displaying Source +@node Source Annotations +@section Displaying Source +@cindex annotations for source display @findex source The following annotation is used instead of displaying source code: @@ -693,7 +713,7 @@ followed by one or more lowercase hex digits (note that this does not depend on the language). @node TODO -@chapter Annotations We Might Want in the Future +@section Annotations We Might Want in the Future @format - target-invalid @@ -709,9 +729,11 @@ depend on the language). notices. @end format +@ignore @node Index @unnumbered Index @printindex fn +@end ignore -@bye +@c @bye diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 63f3355..620368d 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -146,6 +146,7 @@ Copyright (C) 1988-1999 Free Software Foundation, Inc. * Controlling GDB:: Controlling @value{GDBN} * Sequences:: Canned sequences of commands * Emacs:: Using @value{GDBN} under @sc{gnu} Emacs +* Annotations:: @value{GDBN}'s annotations interface. * GDB Bugs:: Reporting bugs in @value{GDBN} * Formatting Documentation:: How to format and print @value{GDBN} documentation @@ -749,22 +750,33 @@ them, so long as enough of the option is present to be unambiguous. (If you prefer, you can flag option arguments with @samp{--} rather than @samp{-}, though we illustrate the more usual convention.) +@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This +@c way, both those who look for -foo and --foo in the index, will find +@c it. + @table @code @item -symbols @var{file} @itemx -s @var{file} +@cindex @code{--symbols} +@cindex @code{-s} Read symbol table from file @var{file}. @item -exec @var{file} @itemx -e @var{file} +@cindex @code{--exec} +@cindex @code{-e} Use file @var{file} as the executable file to execute when appropriate, and for examining pure data in conjunction with a core dump. @item -se @var{file} +@cindex @code{--se} Read symbol table from file @var{file} and use it as the executable file. @item -core @var{file} @itemx -c @var{file} +@cindex @code{--core} +@cindex @code{-c} Use file @var{file} as a core dump to examine. @item -c @var{number} @@ -774,15 +786,21 @@ case @samp{-c} specifies that file as a core dump to read). @item -command @var{file} @itemx -x @var{file} +@cindex @code{--command} +@cindex @code{-x} Execute @value{GDBN} commands from file @var{file}. @xref{Command Files,, Command files}. @item -directory @var{directory} @itemx -d @var{directory} +@cindex @code{--directory} +@cindex @code{-d} Add @var{directory} to the path to search for source files. @item -m @itemx -mapped +@cindex @code{--mapped} +@cindex @code{-m} @emph{Warning: this option depends on operating system facilities that are not supported on all systems.}@* If memory-mapped files are available on your system through the @code{mmap} @@ -800,6 +818,8 @@ table. It cannot be shared across multiple host platforms. @item -r @itemx -readnow +@cindex @code{--readnow} +@cindex @code{-r} Read each symbol file's entire symbol table immediately, rather than the default, which is to read it incrementally as it is needed. This makes startup slower, but makes future operations faster. @@ -825,6 +845,8 @@ batch mode or quiet mode. @table @code @item -nx @itemx -n +@cindex @code{--nx} +@cindex @code{-n} Do not execute commands found in any initialization files (normally called @file{.gdbinit}, or @file{gdb.ini} on PCs). Normally, @value{GDBN} executes the commands in these files after all the command @@ -832,11 +854,16 @@ options and arguments have been processed. @xref{Command Files,,Command files}. @item -quiet +@itemx -silent @itemx -q +@cindex @code{--quiet} +@cindex @code{--silent} +@cindex @code{-q} ``Quiet''. Do not print the introductory and copyright messages. These messages are also suppressed in batch mode. @item -batch +@cindex @code{--batch} Run in batch mode. Exit with status @code{0} after processing all the command files specified with @samp{-x} (and all commands from initialization files, if not inhibited with @samp{-n}). Exit with @@ -858,21 +885,28 @@ mode. @item -nowindows @itemx -nw +@cindex @code{--nowindows} +@cindex @code{-nw} ``No windows''. If @value{GDBN} comes with a graphical user interface (GUI) built in, then this option tells GDB to only use the command-line interface. If no GUI is available, this option has no effect. @item -windows @itemx -w +@cindex @code{--windows} +@cindex @code{-w} If @value{GDBN} includes a GUI, then this option requires it to be used if possible. @item -cd @var{directory} +@cindex @code{--cd} Run @value{GDBN} using @var{directory} as its working directory, instead of the current directory. @item -fullname @itemx -f +@cindex @code{--fullname} +@cindex @code{-f} @sc{gnu} Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells @value{GDBN} to output the full file name and line number in a standard, recognizable fashion each time a stack frame is @@ -883,17 +917,65 @@ and a newline. The Emacs-to-@value{GDBN} interface program uses the two @samp{\032} characters as a signal to display the source code for the frame. +@item -epoch +@cindex @code{--epoch} +The Epoch Emacs-@value{GDBN} interface sets this option when it runs +@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print +routines so as to allow Epoch to display values of expressions in a +separate window. + +@item -annotate @var{level} +@cindex @code{--annotate} +This option sets the @dfn{annotation level} inside @value{GDBN}. Its +effect is identical to using @samp{set annotate @var{level}} +(@pxref{Annotations}). +Annotation level controls how much information does @value{GDBN} print +together with its prompt, values of expressions, source lines, and other +types of output. Level 0 is the normal, level 1 is for use when +@value{GDBN} is run as a subprocess of @sc{gnu} Emacs, level 2 is the +maximum annotation suitable for programs that control @value{GDBN}. + +@item -async +@cindex @code{--async} +Use the asynchronous event loop for the command-line interface. +@value{GDBN} processes all events, such as user keyboard input, via a +special event loop. This allows @value{GDBN} to accept and process user +commands in parallel with the debugged process being +run@footnote{@value{GDBN} built with @sc{djgpp} tools for +MS-DOS/MS-Windows supports this mode of operation, but the event loop is +suspended when the debuggee runs.}, so you don't need to wait for +control to return to @value{GDBN} before you type the next command. +(@emph{Note:} as of version 5.0, the target side of the asynchronous +operation is not yet in place, so @samp{-async} does not work fully +yet.) +@c FIXME: when the target side of the event loop is done, the above NOTE +@c should be removed. + +When the standard input is connected to a terminal device, @value{GDBN} +uses the asynchronous event loop by default, unless disabled by the +@samp{-noasync} option. + +@item -noasync +@cindex @code{--noasync} +Disable the asynchronous event loop for the command-line interface. + @item -baud @var{bps} @itemx -b @var{bps} +@cindex @code{--baud} +@cindex @code{-b} Set the line speed (baud rate or bits per second) of any serial interface used by @value{GDBN} for remote debugging. @item -tty @var{device} +@itemx -t @var{device} +@cindex @code{--tty} +@cindex @code{-t} Run using @var{device} for your program's standard input and output. @c FIXME: kingdon thinks there is more to -tty. Investigate. @c resolve the situation of these eventually @c @item -tui +@c @cindex @code{--tui} @c Use a Terminal User Interface. For information, use your Web browser to @c read the file @file{TUI.html}, which is usually installed in the @c directory @code{/opt/langtools/wdb/doc} on HP-UX systems. Do not use @@ -901,11 +983,38 @@ Run using @var{device} for your program's standard input and output. @c @value{GDBN} under @sc{gnu} Emacs}). @c @item -xdb +@c @cindex @code{--xdb} @c Run in XDB compatibility mode, allowing the use of certain XDB commands. @c For information, see the file @file{xdb_trans.html}, which is usually @c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX @c systems. +@item -interpreter @var{interp} +@cindex @code{--interpreter} +Use the interpreter @var{interp} for interface with the controlling +program or device. This option is meant to be set by programs which +communicate with @value{GDBN} using it as a back end. For example, +@samp{--interpreter=mi} causes @value{GDBN} to use the @dfn{gdbmi +interface}. +@c FIXME: There should be an @xref here to the GDB/MI docs, but +@c gdbmi.texi doesn't have a single node to reference! + +@item -write +@cindex @code{--write} +Open the executable and core files for both reading and writing. This +is equivalent to the @samp{set write on} command inside @value{GDBN} +(@pxref{Patching}). + +@item -statistics +@cindex @code{--statistics} +This option causes @value{GDBN} to print statistics about time and +memory usage after it completes each command and returns to the prompt. + +@item -version +@cindex @code{--version} +This option causes @value{GDBN} to print its version number and +no-warranty blurb, and exit. + @end table @node Quitting GDB @@ -11866,6 +11975,8 @@ environment. Users of this environment can use a new command, each value is printed in its own window. @end ignore +@include annotate.texi + @node GDB Bugs @chapter Reporting Bugs in @value{GDBN} @cindex bugs in @value{GDBN} |