Subversion Repositories or1k

@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,1995,2000,2001 Free Software Foundation, Inc.

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

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

@c any later version published by the Free Software Foundation; with no

@c Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''

@c and with the Back-Cover Texts as in (a) below.

@c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify

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

@c Software Foundation raise funds for GNU development.''

@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,1995,2000,2001 Free Software Foundation

@c  @end titlepage

@c  @ifinfo

@c  @node Top

@c  @top GDB Annotations

@c  @syncodeindex fn cp

@node Annotations

@chapter @value{GDBN} Annotations

This chapter describes annotations in @value{GDBN}.  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

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

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

@end menu

@node Annotations Overview

@section What is an Annotation?

@cindex annotations

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

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 @samp{control-z}

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 @value{GDBN} with annotations is:

@smallexample

$ 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

$

@end smallexample

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 @value{GDBN}.

@node Server Prefix

@section The Server Prefix

@cindex server prefix for annotations

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 @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 Value Annotations

@section Values

@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

@findex value-history-value

@findex value-history-end

If a value is printed using @code{print} and added to the value history,

the annotation looks like

@smallexample

^Z^Zvalue-history-begin @var{history-number} @var{value-flags}

@var{history-string}

^Z^Zvalue-history-value

@var{the-value}

^Z^Zvalue-history-end

@end smallexample

@noindent

where @var{history-number} is the number it is getting in the value

history, @var{history-string} is a string, such as @samp{$5 = }, which

introduces the value to the user, @var{the-value} is the output

corresponding to the value itself, and @var{value-flags} is @samp{*} for

a value which can be dereferenced and @samp{-} for a value which cannot.

@findex value-begin

@findex value-end

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

or it is printed with the @code{output} command), the annotation is similar:

@smallexample

^Z^Zvalue-begin @var{value-flags}

@var{the-value}

^Z^Zvalue-end

@end smallexample

@findex arg-begin

@findex arg-name-end

@findex arg-value

@findex arg-end

When @value{GDBN} prints an argument to a function (for example, in the output

from the @code{backtrace} command), it annotates it as follows:

@smallexample

^Z^Zarg-begin

@var{argument-name}

^Z^Zarg-name-end

@var{separator-string}

^Z^Zarg-value @var{value-flags}

@var{the-value}

^Z^Zarg-end

@end smallexample

@noindent

where @var{argument-name} is the name of the argument,

@var{separator-string} 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.

@findex field-begin

@findex field-name-end

@findex field-value

@findex field-end

When printing a structure, @value{GDBN} annotates it as follows:

@smallexample

^Z^Zfield-begin @var{value-flags}

@var{field-name}

^Z^Zfield-name-end

@var{separator-string}

^Z^Zfield-value

@var{the-value}

^Z^Zfield-end

@end smallexample

@noindent

where @var{field-name} is the name of the field, @var{separator-string}

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, @value{GDBN} annotates it as follows:

@smallexample

^Z^Zarray-section-begin @var{array-index} @var{value-flags}

@end smallexample

@noindent

where @var{array-index} is the index of the first element being

annotated and @var{value-flags} has the same meaning as in a

@code{value-history-begin} annotation.  This is followed by any number

of elements, where is element can be either a single element:

@findex elt

@smallexample

@samp{,} @var{whitespace}         ; @r{omitted for the first element}

@var{the-value}

^Z^Zelt

@end smallexample

or a repeated element

@findex elt-rep

@findex elt-rep-end

@smallexample

@samp{,} @var{whitespace}         ; @r{omitted for the first element}

@var{the-value}

^Z^Zelt-rep @var{number-of-repititions}

@var{repetition-string}

^Z^Zelt-rep-end

@end smallexample

In both cases, @var{the-value} is the output for the value of the

element and @var{whitespace} can contain spaces, tabs, and newlines.  In

the repeated case, @var{number-of-repititons} is the number of

consecutive array elements which contain that value, and

@var{repetition-string} is a string which is designed to convey to the

user that repitition is being depicted.

@findex array-section-end

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

ended with

@smallexample

^Z^Zarray-section-end

@end smallexample

@node Frame Annotations

@section Frames

@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

The frame annotation begins with

@smallexample

^Z^Zframe-begin @var{level} @var{address}

@var{level-string}

@end smallexample

@noindent

where @var{level} is the number of the frame (0 is the innermost frame,

and other frames have positive numbers), @var{address} is the address of

the code executing in that frame, and @var{level-string} is a string

designed to convey the level to the user.  @var{address} is in the form

@samp{0x} followed by one or more lowercase hex digits (note that this

does not depend on the language).  The frame ends with

@findex frame-end

@smallexample

^Z^Zframe-end

@end smallexample

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

consist of

@itemize @bullet

@item

@findex function-call

@smallexample

^Z^Zfunction-call

@var{function-call-string}

@end smallexample

where @var{function-call-string} is text designed to convey to the user

that this frame is associated with a function call made by @value{GDBN} to a

function in the program being debugged.

@item

@findex signal-handler-caller

@smallexample

^Z^Zsignal-handler-caller

@var{signal-handler-caller-string}

@end smallexample

where @var{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).

@item

A normal frame.

@findex frame-address

@findex frame-address-end

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

interesting information for the user to see) begin with

@smallexample

^Z^Zframe-address

@var{address}

^Z^Zframe-address-end

@var{separator-string}

@end smallexample

where @var{address} is the address executing in the frame (the same

address as in the @code{frame-begin} annotation, but printed in a form

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

depending on the language), and @var{separator-string} is a string

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

benefit.

@findex frame-function-name

@findex frame-args

Then comes

@smallexample

^Z^Zframe-function-name

@var{function-name}

^Z^Zframe-args

@var{arguments}

@end smallexample

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{Value Annotations}).

@findex frame-source-begin

@findex frame-source-file

@findex frame-source-file-end

@findex frame-source-line

@findex frame-source-end

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

@smallexample

^Z^Zframe-source-begin

@var{source-intro-string}

^Z^Zframe-source-file

@var{filename}

^Z^Zframe-source-file-end

:

^Z^Zframe-source-line

@var{line-number}

^Z^Zframe-source-end

@end smallexample

where @var{source-intro-string} separates for the user's benefit the

reference from the text which precedes it, @var{filename} is the name of

the source file, and @var{line-number} is the line number within that

file (the first line is line 1).

@findex frame-where

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

@smallexample

^Z^Zframe-where

@var{information}

@end smallexample

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

this is not true for output from the @code{backtrace} command), then a

@code{source} annotation (@pxref{Source Annotations}) is displayed.  Unlike

most annotations, this is output instead of the normal text which would be

output, not in addition.

@end itemize

@node Displays

@section Displays

@findex display-begin

@findex display-number-end

@findex display-format

@findex display-expression

@findex display-expression-end

@findex display-value

@findex display-end

@cindex annotations for display

When @value{GDBN} is told to display something using the @code{display} command,

the results of the display are annotated:

@smallexample

^Z^Zdisplay-begin

@var{number}

^Z^Zdisplay-number-end

@var{number-separator}

^Z^Zdisplay-format

@var{format}

^Z^Zdisplay-expression

@var{expression}

^Z^Zdisplay-expression-end

@var{expression-separator}

^Z^Zdisplay-value

@var{value}

^Z^Zdisplay-end

@end smallexample

@noindent

where @var{number} is the number of the display, @var{number-separator}

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

@var{format} includes information such as the size, format, or other

information about how the value is being displayed, @var{expression} is

the expression being displayed, @var{expression-separator} is intended

to separate the expression from the text that follows for the user,

and @var{value} is the actual value being displayed.

@node Prompting

@section Annotation for @value{GDBN} Input

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

Different kinds of input each have a different @dfn{input type}.  Each

input type has three annotations: a @code{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 @code{post-}

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

associated with the input.  For example, the @code{prompt} input type

features the following annotations:

@smallexample

^Z^Zpre-prompt

^Z^Zprompt

^Z^Zpost-prompt

@end smallexample

The input types are

@table @code

@findex pre-prompt

@findex prompt

@findex post-prompt

@item 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 @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 @value{GDBN} wants the user to select between various overloaded functions.

@findex pre-query

@findex query

@findex post-query

@item query

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 @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

@section Errors

@cindex annotations for errors, warnings and interrupts

@findex quit

@smallexample

^Z^Zquit

@end smallexample

This annotation occurs right before @value{GDBN} responds to an interrupt.

@findex error

@smallexample

^Z^Zerror

@end smallexample

This annotation occurs right before @value{GDBN} responds to an error.

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 @value{GDBN} is immediately returning all the way

to the top level.

@findex error-begin

A quit or error annotation may be preceded by

@smallexample

^Z^Zerror-begin

@end smallexample

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

message.

Warning messages are not yet annotated.

@c If we want to change that, need to fix warning(), type_error(),

@c range_error(), and possibly other places.

@node Breakpoint Info

@section Information on Breakpoints

@cindex annotations for breakpoints

The output from the @code{info breakpoints} command is annotated as follows:

@findex breakpoints-headers

@findex breakpoints-table

@smallexample

^Z^Zbreakpoints-headers

@var{header-entry}

^Z^Zbreakpoints-table

@end smallexample

@noindent

where @var{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:

@findex record

@findex field

@smallexample

^Z^Zrecord

^Z^Zfield 0

@var{number}

^Z^Zfield 1

@var{type}

^Z^Zfield 2

@var{disposition}

^Z^Zfield 3

@var{enable}

^Z^Zfield 4

@var{address}

^Z^Zfield 5

@var{what}

^Z^Zfield 6

@var{frame}

^Z^Zfield 7

@var{condition}

^Z^Zfield 8

@var{ignore-count}

^Z^Zfield 9

@var{commands}

@end smallexample

Note that @var{address} is intended for user consumption---the syntax

varies depending on the language.

The output ends with

@findex breakpoints-table-end

@smallexample

^Z^Zbreakpoints-table-end

@end smallexample

@node Invalidation

@section Invalidation Notices

@cindex annotations for invalidation messages

The following annotations say that certain pieces of state may have

changed.

@table @code

@findex frames-invalid

@item ^Z^Zframes-invalid

The frames (for example, output from the @code{backtrace} command) may

have changed.

@findex breakpoints-invalid

@item ^Z^Zbreakpoints-invalid

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

deleted a breakpoint.

@end table

@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 @value{GDBN} command such as

@code{step} or @code{continue},

@smallexample

^Z^Zstarting

@end smallexample

is output.  When the program stops,

@smallexample

^Z^Zstopped

@end smallexample

is output.  Before the @code{stopped} annotation, a variety of

annotations describe how the program stopped.

@table @code

@findex exited

@item ^Z^Zexited @var{exit-status}

The program exited, and @var{exit-status} is the exit status (zero for

successful exit, otherwise nonzero).

@findex signalled

@findex signal-name

@findex signal-name-end

@findex signal-string

@findex signal-string-end

@item ^Z^Zsignalled

The program exited with a signal.  After the @code{^Z^Zsignalled}, the

annotation continues:

@smallexample

@var{intro-text}

^Z^Zsignal-name

@var{name}

^Z^Zsignal-name-end

@var{middle-text}

^Z^Zsignal-string

@var{string}

^Z^Zsignal-string-end

@var{end-text}

@end smallexample

@noindent

where @var{name} is the name of the signal, such as @code{SIGILL} or

@code{SIGSEGV}, and @var{string} is the explanation of the signal, such

as @code{Illegal Instruction} or @code{Segmentation fault}.

@var{intro-text}, @var{middle-text}, and @var{end-text} are for the

user's benefit and have no particular format.

@findex signal

@item ^Z^Zsignal

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.

@findex breakpoint

@item ^Z^Zbreakpoint @var{number}

The program hit breakpoint number @var{number}.

@findex watchpoint

@item ^Z^Zwatchpoint @var{number}

The program hit watchpoint number @var{number}.

@end table

@node Source Annotations

@section Displaying Source

@cindex annotations for source display

@findex source

The following annotation is used instead of displaying source code:

@smallexample

^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}

@end smallexample

where @var{filename} is an absolute file name indicating which source

file, @var{line} is the line number within that file (where 1 is the

first line in the file), @var{character} is the character position

within the file (where 0 is the first character in the file) (for most

debug formats this will necessarily point to the beginning of a line),

@var{middle} is @samp{middle} if @var{addr} is in the middle of the

line, or @samp{beg} if @var{addr} is at the beginning of the line, and

@var{addr} is the address in the target program associated with the

source which is being displayed.  @var{addr} is in the form @samp{0x}

followed by one or more lowercase hex digits (note that this does not

depend on the language).

@node TODO

@section Annotations We Might Want in the Future

@format

    - target-invalid

      the target might have changed (registers, heap contents, or

      execution status).  For performance, we might eventually want

      to hit `registers-invalid' and `all-registers-invalid' with

      greater precision

    - systematic annotation for set/show parameters (including

      invalidation notices).

    - similarly, `info' returns a list of candidates for invalidation

      notices.

@end format

@ignore

@node Index

@unnumbered Index

@printindex fn

@end ignore

@c @bye