Subversion Repositories or1k

This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.

INFO-DIR-SECTION Programming & development tools.

START-INFO-DIR-ENTRY

* Gdb: (gdb).                     The GNU debugger.

END-INFO-DIR-ENTRY

   This file documents the GNU debugger GDB.

   This is the Eighth Edition, March 2000, of `Debugging with GDB: the

GNU Source-Level Debugger' for GDB Version 5.0.

   Copyright (C) 1988-2000 Free Software Foundation, Inc.

   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.

   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.

File: gdb.info,  Node: Messages/Warnings,  Next: Debugging Output,  Prev: Numbers,  Up: Controlling GDB

Optional warnings and messages

==============================

   By default, GDB is silent about its inner workings.  If you are

running on a slow machine, you may want to use the `set verbose'

command.  This makes GDB tell you when it does a lengthy internal

operation, so you will not think it has crashed.

   Currently, the messages controlled by `set verbose' are those which

announce that the symbol table for a source file is being read; see

`symbol-file' in *Note Commands to specify files: Files.

`set verbose on'

     Enables GDB output of certain informational messages.

`set verbose off'

     Disables GDB output of certain informational messages.

`show verbose'

     Displays whether `set verbose' is on or off.

   By default, if GDB encounters bugs in the symbol table of an object

file, it is silent; but if you are debugging a compiler, you may find

this information useful (*note Errors reading symbol files: Symbol

Errors.).

`set complaints LIMIT'

     Permits GDB to output LIMIT complaints about each type of unusual

     symbols before becoming silent about the problem.  Set LIMIT to

     zero to suppress all complaints; set it to a large number to

     prevent complaints from being suppressed.

`show complaints'

     Displays how many symbol complaints GDB is permitted to produce.

   By default, GDB is cautious, and asks what sometimes seems to be a

lot of stupid questions to confirm certain commands.  For example, if

you try to run a program which is already running:

     (gdb) run

     The program being debugged has been started already.

     Start it from the beginning? (y or n)

   If you are willing to unflinchingly face the consequences of your own

commands, you can disable this "feature":

`set confirm off'

     Disables confirmation requests.

`set confirm on'

     Enables confirmation requests (the default).

`show confirm'

     Displays state of confirmation requests.

File: gdb.info,  Node: Debugging Output,  Prev: Messages/Warnings,  Up: Controlling GDB

Optional messages about internal happenings

===========================================

`set debug arch'

     Turns on or off display of gdbarch debugging info. The default is

     off

`show debug arch'

     Displays the current state of displaying gdbarch debugging info.

`set debug event'

     Turns on or off display of GDB event debugging info. The default

     is off.

`show debug event'

     Displays the current state of displaying GDB event debugging info.

`set debug expression'

     Turns on or off display of GDB expression debugging info. The

     default is off.

`show debug expression'

     Displays the current state of displaying GDB expression debugging

     info.

`set debug overload'

     Turns on or off display of GDB C++ overload debugging info. This

     includes info such as ranking of functions, etc. The default is

     off.

`show debug overload'

     Displays the current state of displaying GDB C++ overload

     debugging info.

`set debug remote'

     Turns on or off display of reports on all packets sent back and

     forth across the serial line to the remote machine.  The info is

     printed on the GDB standard output stream. The default is off.

`show debug remote'

     Displays the state of display of remote packets.

`set debug serial'

     Turns on or off display of GDB serial debugging info. The default

     is off.

`show debug serial'

     Displays the current state of displaying GDB serial debugging info.

`set debug target'

     Turns on or off display of GDB target debugging info. This info

     includes what is going on at the target level of GDB, as it

     happens. The default is off.

`show debug target'

     Displays the current state of displaying GDB target debugging info.

`set debug varobj'

     Turns on or off display of GDB variable object debugging info. The

     default is off.

`show debug varobj'

     Displays the current state of displaying GDB variable object

     debugging info.

File: gdb.info,  Node: Sequences,  Next: Emacs,  Prev: Controlling GDB,  Up: Top

Canned Sequences of Commands

****************************

   Aside from breakpoint commands (*note Breakpoint command lists:

Break Commands.), GDB provides two ways to store sequences of commands

for execution as a unit: user-defined commands and command files.

* Menu:

* Define::                      User-defined commands

* Hooks::                       User-defined command hooks

* Command Files::               Command files

* Output::                      Commands for controlled output

File: gdb.info,  Node: Define,  Next: Hooks,  Up: Sequences

User-defined commands

=====================

   A "user-defined command" is a sequence of GDB commands to which you

assign a new name as a command.  This is done with the `define'

command.  User commands may accept up to 10 arguments separated by

whitespace.  Arguments are accessed within the user command via

$ARG0...$ARG9.  A trivial example:

     define adder

       print $arg0 + $arg1 + $arg2

To execute the command use:

     adder 1 2 3

This defines the command `adder', which prints the sum of its three

arguments.  Note the arguments are text substitutions, so they may

reference variables, use complex expressions, or even perform inferior

functions calls.

`define COMMANDNAME'

     Define a command named COMMANDNAME.  If there is already a command

     by that name, you are asked to confirm that you want to redefine

     it.

     The definition of the command is made up of other GDB command

     lines, which are given following the `define' command.  The end of

     these commands is marked by a line containing `end'.

`if'

     Takes a single argument, which is an expression to evaluate.  It

     is followed by a series of commands that are executed only if the

     expression is true (nonzero).  There can then optionally be a line

     `else', followed by a series of commands that are only executed if

     the expression was false.  The end of the list is marked by a line

     containing `end'.

`while'

     The syntax is similar to `if': the command takes a single argument,

     which is an expression to evaluate, and must be followed by the

     commands to execute, one per line, terminated by an `end'.  The

     commands are executed repeatedly as long as the expression

     evaluates to true.

`document COMMANDNAME'

     Document the user-defined command COMMANDNAME, so that it can be

     accessed by `help'.  The command COMMANDNAME must already be

     defined.  This command reads lines of documentation just as

     `define' reads the lines of the command definition, ending with

     `end'.  After the `document' command is finished, `help' on command

     COMMANDNAME displays the documentation you have written.

     You may use the `document' command again to change the

     documentation of a command.  Redefining the command with `define'

     does not change the documentation.

`help user-defined'

     List all user-defined commands, with the first line of the

     documentation (if any) for each.

`show user'

`show user COMMANDNAME'

     Display the GDB commands used to define COMMANDNAME (but not its

     documentation).  If no COMMANDNAME is given, display the

     definitions for all user-defined commands.

   When user-defined commands are executed, the commands of the

definition are not printed.  An error in any command stops execution of

the user-defined command.

   If used interactively, commands that would ask for confirmation

proceed without asking when used inside a user-defined command.  Many

GDB commands that normally print messages to say what they are doing

omit the messages when used in a user-defined command.

File: gdb.info,  Node: Hooks,  Next: Command Files,  Prev: Define,  Up: Sequences

User-defined command hooks

==========================

   You may define _hooks_, which are a special kind of user-defined

command.  Whenever you run the command `foo', if the user-defined

command `hook-foo' exists, it is executed (with no arguments) before

that command.

   In addition, a pseudo-command, `stop' exists.  Defining

(`hook-stop') makes the associated commands execute every time

execution stops in your program: before breakpoint commands are run,

displays are printed, or the stack frame is printed.

   For example, to ignore `SIGALRM' signals while single-stepping, but

treat them normally during normal execution, you could define:

     define hook-stop

     handle SIGALRM nopass

     end

     define hook-run

     handle SIGALRM pass

     end

     define hook-continue

     handle SIGLARM pass

     end

   You can define a hook for any single-word command in GDB, but not

for command aliases; you should define a hook for the basic command

name, e.g.  `backtrace' rather than `bt'.  If an error occurs during

the execution of your hook, execution of GDB commands stops and GDB

issues a prompt (before the command that you actually typed had a

chance to run).

   If you try to define a hook which does not match any known command,

you get a warning from the `define' command.

File: gdb.info,  Node: Command Files,  Next: Output,  Prev: Hooks,  Up: Sequences

Command files

=============

   A command file for GDB is a file of lines that are GDB commands.

Comments (lines starting with `#') may also be included.  An empty line

in a command file does nothing; it does not mean to repeat the last

command, as it would from the terminal.

   When you start GDB, it automatically executes commands from its

"init files".  These are files named `.gdbinit' on Unix, or `gdb.ini'

on DOS/Windows.  GDB reads the init file (if any) in your home

directory(1), then processes command line options and operands, and then

reads the init file (if any) in the current working directory.  This is

so the init file in your home directory can set options (such as `set

complaints') which affect the processing of the command line options

and operands.  The init files are not executed if you use the `-nx'

option; *note Choosing modes: Mode Options..

   On some configurations of GDB, the init file is known by a different

name (these are typically environments where a specialized form of GDB

may need to coexist with other forms, hence a different name for the

specialized version's init file).  These are the environments with

special init file names:

   * VxWorks (Wind River Systems real-time OS): `.vxgdbinit'

   * OS68K (Enea Data Systems real-time OS): `.os68gdbinit'

   * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit'

   You can also request the execution of a command file with the

`source' command:

`source FILENAME'

     Execute the command file FILENAME.

   The lines in a command file are executed sequentially.  They are not

printed as they are executed.  An error in any command terminates

execution of the command file.

   Commands that would ask for confirmation if used interactively

proceed without asking when used in a command file.  Many GDB commands

that normally print messages to say what they are doing omit the

messages when called from command files.

   ---------- Footnotes ----------

   (1) On DOS/Windows systems, the home directory is the one pointed to

by the `HOME' environment variable.

File: gdb.info,  Node: Output,  Prev: Command Files,  Up: Sequences

Commands for controlled output

==============================

   During the execution of a command file or a user-defined command,

normal GDB output is suppressed; the only output that appears is what is

explicitly printed by the commands in the definition.  This section

describes three commands useful for generating exactly the output you

want.

`echo TEXT'

     Print TEXT.  Nonprinting characters can be included in TEXT using

     C escape sequences, such as `\n' to print a newline.  *No newline

     is printed unless you specify one.* In addition to the standard C

     escape sequences, a backslash followed by a space stands for a

     space.  This is useful for displaying a string with spaces at the

     beginning or the end, since leading and trailing spaces are

     otherwise trimmed from all arguments.  To print ` and foo = ', use

     the command `echo \ and foo = \ '.

     A backslash at the end of TEXT can be used, as in C, to continue

     the command onto subsequent lines.  For example,

          echo This is some text\n\

          which is continued\n\

          onto several lines.\n

     produces the same output as

          echo This is some text\n

          echo which is continued\n

          echo onto several lines.\n

`output EXPRESSION'

     Print the value of EXPRESSION and nothing but that value: no

     newlines, no `$NN = '.  The value is not entered in the value

     history either.  *Note Expressions: Expressions, for more

     information on expressions.

`output/FMT EXPRESSION'

     Print the value of EXPRESSION in format FMT.  You can use the same

     formats as for `print'.  *Note Output formats: Output Formats, for

     more information.

`printf STRING, EXPRESSIONS...'

     Print the values of the EXPRESSIONS under the control of STRING.

     The EXPRESSIONS are separated by commas and may be either numbers

     or pointers.  Their values are printed as specified by STRING,

     exactly as if your program were to execute the C subroutine

          printf (STRING, EXPRESSIONS...);

     For example, you can print two values in hex like this:

          printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo

     The only backslash-escape sequences that you can use in the format

     string are the simple ones that consist of backslash followed by a

     letter.

File: gdb.info,  Node: Emacs,  Next: Annotations,  Prev: Sequences,  Up: Top

Using GDB under GNU Emacs

*************************

   A special interface allows you to use GNU Emacs to view (and edit)

the source files for the program you are debugging with GDB.

   To use this interface, use the command `M-x gdb' in Emacs.  Give the

executable file you want to debug as an argument.  This command starts

GDB as a subprocess of Emacs, with input and output through a newly

created Emacs buffer.

   Using GDB under Emacs is just like using GDB normally except for two

things:

   * All "terminal" input and output goes through the Emacs buffer.

   This applies both to GDB commands and their output, and to the input

and output done by the program you are debugging.

   This is useful because it means that you can copy the text of

previous commands and input them again; you can even use parts of the

output in this way.

   All the facilities of Emacs' Shell mode are available for interacting

with your program.  In particular, you can send signals the usual

way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop.

   * GDB displays source code through Emacs.

   Each time GDB displays a stack frame, Emacs automatically finds the

source file for that frame and puts an arrow (`=>') at the left margin

of the current line.  Emacs uses a separate buffer for source display,

and splits the screen to show both your GDB session and the source.

   Explicit GDB `list' or search commands still produce output as

usual, but you probably have no reason to use them from Emacs.

     _Warning:_ If the directory where your program resides is not your

     current directory, it can be easy to confuse Emacs about the

     location of the source files, in which case the auxiliary display

     buffer does not appear to show your source.  GDB can find programs

     by searching your environment's `PATH' variable, so the GDB input

     and output session proceeds normally; but Emacs does not get

     enough information back from GDB to locate the source files in

     this situation.  To avoid this problem, either start GDB mode from

     the directory where your program resides, or specify an absolute

     file name when prompted for the `M-x gdb' argument.

     A similar confusion can result if you use the GDB `file' command to

     switch to debugging a program in some other location, from an

     existing GDB buffer in Emacs.

   By default, `M-x gdb' calls the program called `gdb'.  If you need

to call GDB by a different name (for example, if you keep several

configurations around, with different names) you can set the Emacs

variable `gdb-command-name'; for example,

     (setq gdb-command-name "mygdb")

(preceded by `M-:' or `ESC :', or typed in the `*scratch*' buffer, or

in your `.emacs' file) makes Emacs call the program named "`mygdb'"

instead.

   In the GDB I/O buffer, you can use these special Emacs commands in

addition to the standard Shell mode commands:

`C-h m'

     Describe the features of Emacs' GDB Mode.

`M-s'

     Execute to another source line, like the GDB `step' command; also

     update the display window to show the current file and location.

`M-n'

     Execute to next source line in this function, skipping all function

     calls, like the GDB `next' command.  Then update the display window

     to show the current file and location.

`M-i'

     Execute one instruction, like the GDB `stepi' command; update

     display window accordingly.

`M-x gdb-nexti'

     Execute to next instruction, using the GDB `nexti' command; update

     display window accordingly.

`C-c C-f'

     Execute until exit from the selected stack frame, like the GDB

     `finish' command.

`M-c'

     Continue execution of your program, like the GDB `continue'

     command.

     _Warning:_ In Emacs v19, this command is `C-c C-p'.

`M-u'

     Go up the number of frames indicated by the numeric argument

     (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'

     command.

     _Warning:_ In Emacs v19, this command is `C-c C-u'.

`M-d'

     Go down the number of frames indicated by the numeric argument,

     like the GDB `down' command.

     _Warning:_ In Emacs v19, this command is `C-c C-d'.

`C-x &'

     Read the number where the cursor is positioned, and insert it at

     the end of the GDB I/O buffer.  For example, if you wish to

     disassemble code around an address that was displayed earlier,

     type `disassemble'; then move the cursor to the address display,

     and pick up the argument for `disassemble' by typing `C-x &'.

     You can customize this further by defining elements of the list

     `gdb-print-command'; once it is defined, you can format or

     otherwise process numbers picked up by `C-x &' before they are

     inserted.  A numeric argument to `C-x &' indicates that you wish

     special formatting, and also acts as an index to pick an element

     of the list.  If the list element is a string, the number to be

     inserted is formatted using the Emacs function `format'; otherwise

     the number is passed as an argument to the corresponding list

     element.

   In any source file, the Emacs command `C-x SPC' (`gdb-break') tells

GDB to set a breakpoint on the source line point is on.

   If you accidentally delete the source-display buffer, an easy way to

get it back is to type the command `f' in the GDB buffer, to request a

frame display; when you run under Emacs, this recreates the source

buffer if necessary to show you the context of the current frame.

   The source files displayed in Emacs are in ordinary Emacs buffers

which are visiting the source files in the usual way.  You can edit the

files with these buffers if you wish; but keep in mind that GDB

communicates with Emacs in terms of line numbers.  If you add or delete

lines from the text, the line numbers that GDB knows cease to

correspond properly with the code.

File: gdb.info,  Node: Annotations,  Next: GDB/MI,  Prev: Emacs,  Up: Top

GDB Annotations

***************

   This chapter describes annotations in GDB.  Annotations are designed

to interface GDB to graphical user interfaces or other similar programs

which want to interact with GDB at a relatively high level.

* Menu:

* 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::            GDB can be told to display something periodically.

* Prompting::           Annotations marking GDB's need for input.

* Errors::              Annotations for error messages.

* Breakpoint Info::     Information on breakpoints.

* Invalidation::        Some annotations describe things now invalid.

* 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.

File: gdb.info,  Node: Annotations Overview,  Next: Server Prefix,  Up: Annotations

What is an Annotation?

======================

   To produce annotations, start GDB with the `--annotate=2' option.

   Annotations start with a newline character, two `control-z'

characters, and the name of the annotation.  If there is no additional

information associated with this annotation, the name of the annotation

is followed immediately by a newline.  If there is additional

information, the name of the annotation is followed by a space, the

additional information, and a newline.  The additional information

cannot contain newline characters.

   Any output not beginning with a newline and two `control-z'

characters denotes literal output from GDB.  Currently there is no need

for GDB to output a newline followed by two `control-z' characters, but

if there was such a need, the annotations could be extended with an

`escape' annotation which means those three characters as output.

   A simple example of starting up GDB with annotations is:

     $ gdb --annotate=2

     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)

     ^Z^Zprompt

     quit

     ^Z^Zpost-prompt

     $

   Here `quit' is input to GDB; the rest is output from GDB.  The three

lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are

annotations; the rest is output from GDB.

File: gdb.info,  Node: Server Prefix,  Next: Value Annotations,  Prev: Annotations Overview,  Up: Annotations

The Server Prefix

=================

   To issue a command to GDB without affecting certain aspects of the

state which is seen by users, prefix it with `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  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 `output' command instead of the `print' command.

File: gdb.info,  Node: Value Annotations,  Next: Frame Annotations,  Prev: Server Prefix,  Up: Annotations

Values

======

   When a value is printed in various contexts, GDB uses annotations to

delimit the value from the surrounding text.

   If a value is printed using `print' and added to the value history,

the annotation looks like

     ^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS

     HISTORY-STRING

     ^Z^Zvalue-history-value

     THE-VALUE

     ^Z^Zvalue-history-end

   where HISTORY-NUMBER is the number it is getting in the value

history, HISTORY-STRING is a string, such as `$5 = ', which introduces

the value to the user, THE-VALUE is the output corresponding to the

value itself, and VALUE-FLAGS is `*' for a value which can be

dereferenced and `-' for a value which cannot.

   If the value is not added to the value history (it is an invalid

float or it is printed with the `output' command), the annotation is

similar:

     ^Z^Zvalue-begin VALUE-FLAGS

     THE-VALUE

     ^Z^Zvalue-end

   When GDB prints an argument to a function (for example, in the output

from the `backtrace' command), it annotates it as follows:

     ^Z^Zarg-begin

     ARGUMENT-NAME

     ^Z^Zarg-name-end

     SEPARATOR-STRING

     ^Z^Zarg-value VALUE-FLAGS

     THE-VALUE

     ^Z^Zarg-end

   where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is

text which separates the name from the value for the user's benefit

(such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as

in a `value-history-begin' annotation.

   When printing a structure, GDB annotates it as follows:

     ^Z^Zfield-begin VALUE-FLAGS

     FIELD-NAME

     ^Z^Zfield-name-end

     SEPARATOR-STRING

     ^Z^Zfield-value

     THE-VALUE

     ^Z^Zfield-end

   where FIELD-NAME is the name of the field, SEPARATOR-STRING is text

which separates the name from the value for the user's benefit (such as

`='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a

`value-history-begin' annotation.

   When printing an array, GDB annotates it as follows:

     ^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS

   where ARRAY-INDEX is the index of the first element being annotated

and VALUE-FLAGS has the same meaning as in a `value-history-begin'

annotation.  This is followed by any number of elements, where is

element can be either a single element:

     `,' WHITESPACE         ; omitted for the first element

     THE-VALUE

     ^Z^Zelt

   or a repeated element

     `,' WHITESPACE         ; omitted for the first element

     THE-VALUE

     ^Z^Zelt-rep NUMBER-OF-REPITITIONS

     REPETITION-STRING

     ^Z^Zelt-rep-end

   In both cases, THE-VALUE is the output for the value of the element

and WHITESPACE can contain spaces, tabs, and newlines.  In the repeated

case, NUMBER-OF-REPITITONS is the number of consecutive array elements

which contain that value, and REPETITION-STRING is a string which is

designed to convey to the user that repitition is being depicted.

   Once all the array elements have been output, the array annotation is

ended with

     ^Z^Zarray-section-end

File: gdb.info,  Node: Frame Annotations,  Next: Displays,  Prev: Value Annotations,  Up: Annotations

Frames

======

   Whenever GDB prints a frame, it annotates it.  For example, this

applies to frames printed when GDB stops, output from commands such as

`backtrace' or `up', etc.

   The frame annotation begins with

     ^Z^Zframe-begin LEVEL ADDRESS

     LEVEL-STRING

   where LEVEL is the number of the frame (0 is the innermost frame,

and other frames have positive numbers), ADDRESS is the address of the

code executing in that frame, and LEVEL-STRING is a string designed to

convey the level to the user.  ADDRESS is in the form `0x' followed by

one or more lowercase hex digits (note that this does not depend on the

language).  The frame ends with

     ^Z^Zframe-end

   Between these annotations is the main body of the frame, which can

consist of

   *      ^Z^Zfunction-call

          FUNCTION-CALL-STRING

     where 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

     function in the program being debugged.

   *      ^Z^Zsignal-handler-caller

          SIGNAL-HANDLER-CALLER-STRING

     where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to

     the user that this frame is associated with whatever mechanism is

     used by this operating system to call a signal handler (it is the

     frame which calls the signal handler, not the frame for the signal

     handler itself).

   * A normal frame.

     This can optionally (depending on whether this is thought of as

     interesting information for the user to see) begin with

          ^Z^Zframe-address

          ADDRESS

          ^Z^Zframe-address-end

          SEPARATOR-STRING

     where ADDRESS is the address executing in the frame (the same

     address as in the `frame-begin' annotation, but printed in a form

     which is intended for user consumption--in particular, the syntax

     varies depending on the language), and SEPARATOR-STRING is a string

     intended to separate this address from what follows for the user's

     benefit.

     Then comes

          ^Z^Zframe-function-name

          FUNCTION-NAME

          ^Z^Zframe-args

          ARGUMENTS

     where FUNCTION-NAME is the name of the function executing in the

     frame, or `??' if not known, and ARGUMENTS are the arguments to

     the frame, with parentheses around them (each argument is annotated

     individually as well, *note Value Annotations::).

     If source information is available, a reference to it is then

     printed:

          ^Z^Zframe-source-begin

          SOURCE-INTRO-STRING

          ^Z^Zframe-source-file

          FILENAME

          ^Z^Zframe-source-file-end

          :

          ^Z^Zframe-source-line

          LINE-NUMBER

          ^Z^Zframe-source-end

     where SOURCE-INTRO-STRING separates for the user's benefit the

     reference from the text which precedes it, FILENAME is the name of

     the source file, and LINE-NUMBER is the line number within that

     file (the first line is line 1).

     If GDB 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

          ^Z^Zframe-where

          INFORMATION

     Then, if source is to actually be displayed for this frame (for

     example, this is not true for output from the `backtrace'

     command), then a `source' annotation (*note Source Annotations::)

     is displayed.  Unlike most annotations, this is output instead of

     the normal text which would be output, not in addition.

File: gdb.info,  Node: Displays,  Next: Prompting,  Prev: Frame Annotations,  Up: Annotations

Displays

========

   When GDB is told to display something using the `display' command,

the results of the display are annotated:

     ^Z^Zdisplay-begin

     NUMBER

     ^Z^Zdisplay-number-end

     NUMBER-SEPARATOR

     ^Z^Zdisplay-format

     FORMAT

     ^Z^Zdisplay-expression

     EXPRESSION

     ^Z^Zdisplay-expression-end

     EXPRESSION-SEPARATOR

     ^Z^Zdisplay-value

     VALUE

     ^Z^Zdisplay-end

   where NUMBER is the number of the display, NUMBER-SEPARATOR is

intended to separate the number from what follows for the user, FORMAT

includes information such as the size, format, or other information

about how the value is being displayed, EXPRESSION is the expression

being displayed, EXPRESSION-SEPARATOR is intended to separate the

expression from the text that follows for the user, and VALUE is the

actual value being displayed.

File: gdb.info,  Node: Prompting,  Next: Errors,  Prev: Displays,  Up: Annotations

Annotation for GDB Input

========================

   When GDB 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.

   Different kinds of input each have a different "input type".  Each

input type has three annotations: a `pre-' annotation, which denotes

the beginning of any prompt which is being output, a plain annotation,

which denotes the end of the prompt, and then a `post-' annotation

which denotes the end of any echo which may (or may not) be associated

with the input.  For example, the `prompt' input type features the

following annotations:

     ^Z^Zpre-prompt

     ^Z^Zprompt

     ^Z^Zpost-prompt

   The input types are

`prompt'

     When GDB is prompting for a command (the main GDB prompt).

`commands'

     When GDB prompts for a set of commands, like in the `commands'

     command.  The annotations are repeated for each command which is

     input.

`overload-choice'

     When GDB wants the user to select between various overloaded

     functions.

`query'

     When GDB wants the user to confirm a potentially dangerous

     operation.

`prompt-for-continue'

     When GDB is asking the user to press return to continue.  Note:

     Don't expect this to work well; instead use `set height 0' to

     disable prompting.  This is because the counting of lines is buggy

     in the presence of annotations.

File: gdb.info,  Node: Errors,  Next: Breakpoint Info,  Prev: Prompting,  Up: Annotations

Errors

======

     ^Z^Zquit

   This annotation occurs right before GDB responds to an interrupt.

     ^Z^Zerror

   This annotation occurs right before GDB responds to an error.

   Quit and error annotations indicate that any annotations which GDB

was in the middle of may end abruptly.  For example, if a

`value-history-begin' annotation is followed by a `error', one cannot

expect to receive the matching `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 to the

top level.

   A quit or error annotation may be preceded by

     ^Z^Zerror-begin