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 Ninth Edition, April 2001, of `Debugging with GDB: the

GNU Source-Level Debugger' for GDB Version 20010707.

   Copyright (C)

1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001

Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.1 or

any later version published by the Free Software Foundation; with the

Invariant Sections being "A Sample GDB Session" and "Free Software",

with the Front-Cover texts being "A GNU Manual," and with the

Back-Cover Texts as in (a) below.

   (a) The FSF's Back-Cover Text is: "You have freedom to copy and

modify this GNU Manual, like GNU software.  Copies published by the Free

Software Foundation raise funds for GNU development."

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.

   A hook may also be defined which is run after the command you

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

command `hookpost-foo' exists, it is executed (with no arguments) after

that command.  Post-execution hooks may exist simultaneously with

pre-execution hooks, for the same command.

   It is valid for a hook to call the command which it hooks.  If this

occurs, the hook is not re-executed, thereby avoiding infinte recursion.

   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

   As a further example, to hook at the begining and end of the `echo'

command, and to add extra text to the beginning and end of the message,

you could define:

     define hook-echo

     echo <<<---

     end

     define hookpost-echo

     echo --->>>\n

     end

     (gdb) echo Hello World

     <<<---Hello World--->>>

     (gdb)

   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 and `gdb.ini'

on DOS/Windows.  During startup, GDB does the following:

  1. Reads the init file (if any) in your home directory(1).

  2. Processes command line options and operands.

  3. Reads the init file (if any) in the current working directory.

  4. Reads command files specified by the `-x' option.

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

complaints') that affect subsequent processing of command line options

and operands.  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

   Any output between that and the quit or error annotation is the error

message.

   Warning messages are not yet annotated.

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

Information on Breakpoints

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

   The output from the `info breakpoints' command is annotated as

follows:

     ^Z^Zbreakpoints-headers

     HEADER-ENTRY

     ^Z^Zbreakpoints-table

where HEADER-ENTRY has the same syntax as an entry (see below) but

instead of containing data, it contains strings which are intended to

convey the meaning of each field to the user.  This is followed by any

number of entries.  If a field does not apply for this entry, it is

omitted.  Fields may contain trailing whitespace.  Each entry consists

of:

     ^Z^Zrecord

     ^Z^Zfield 0

     NUMBER

     ^Z^Zfield 1

     TYPE

     ^Z^Zfield 2

     DISPOSITION

     ^Z^Zfield 3

     ENABLE

     ^Z^Zfield 4

     ADDRESS

     ^Z^Zfield 5

     WHAT

     ^Z^Zfield 6

     FRAME

     ^Z^Zfield 7

     CONDITION

     ^Z^Zfield 8

     IGNORE-COUNT

     ^Z^Zfield 9

     COMMANDS

   Note that ADDRESS is intended for user consumption--the syntax

varies depending on the language.

   The output ends with

     ^Z^Zbreakpoints-table-end

File: gdb.info,  Node: Invalidation,  Next: Annotations for Running,  Prev: Breakpoint Info,  Up: Annotations

Invalidation Notices

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

   The following annotations say that certain pieces of state may have

changed.

`^Z^Zframes-invalid'

     The frames (for example, output from the `backtrace' command) may

     have changed.

`^Z^Zbreakpoints-invalid'

     The breakpoints may have changed.  For example, the user just

     added or deleted a breakpoint.

File: gdb.info,  Node: Annotations for Running,  Next: Source Annotations,  Prev: Invalidation,  Up: Annotations

Running the Program

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

   When the program starts executing due to a GDB command such as

`step' or `continue',

     ^Z^Zstarting

   is output.  When the program stops,

     ^Z^Zstopped

   is output.  Before the `stopped' annotation, a variety of

annotations describe how the program stopped.

`^Z^Zexited EXIT-STATUS'

     The program exited, and EXIT-STATUS is the exit status (zero for

     successful exit, otherwise nonzero).

`^Z^Zsignalled'

     The program exited with a signal.  After the `^Z^Zsignalled', the

     annotation continues:

          INTRO-TEXT

          ^Z^Zsignal-name

          NAME

          ^Z^Zsignal-name-end

          MIDDLE-TEXT

          ^Z^Zsignal-string

          STRING

          ^Z^Zsignal-string-end

          END-TEXT

     where NAME is the name of the signal, such as `SIGILL' or

     `SIGSEGV', and STRING is the explanation of the signal, such as

     `Illegal Instruction' or `Segmentation fault'.  INTRO-TEXT,

     MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no