Subversion Repositories or1k

INFO-DIR-SECTION Programming & development tools.

INFO-DIR-SECTION Programming & development tools.

START-INFO-DIR-ENTRY

START-INFO-DIR-ENTRY

* Gdb: (gdb).                     The GNU debugger.

* Gdb: (gdb).                     The GNU debugger.

END-INFO-DIR-ENTRY

END-INFO-DIR-ENTRY

   This file documents the GNU debugger GDB.

   This file documents the GNU debugger GDB.

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

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

GNU Source-Level Debugger' for GDB Version 5.0.

GNU Source-Level Debugger' for GDB Version 5.0.

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

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

   Permission is granted to make and distribute verbatim copies of this

   Permission is granted to make and distribute verbatim copies of this

manual provided the copyright notice and this permission notice are

manual provided the copyright notice and this permission notice are

preserved on all copies.

preserved on all copies.

   Permission is granted to copy and distribute modified versions of

   Permission is granted to copy and distribute modified versions of

this manual under the conditions for verbatim copying, provided also

this manual under the conditions for verbatim copying, provided also

that the entire resulting derived work is distributed under the terms

that the entire resulting derived work is distributed under the terms

of a permission notice identical to this one.

of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this

   Permission is granted to copy and distribute translations of this

manual into another language, under the above conditions for modified

manual into another language, under the above conditions for modified

versions.

versions.

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

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

Optional warnings and messages

Optional warnings and messages

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

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

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

   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'

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

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

operation, so you will not think it has crashed.

operation, so you will not think it has crashed.

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

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

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

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

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

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

`set verbose on'

`set verbose on'

     Enables GDB output of certain informational messages.

     Enables GDB output of certain informational messages.

`set verbose off'

`set verbose off'

     Disables GDB output of certain informational messages.

     Disables GDB output of certain informational messages.

`show verbose'

`show verbose'

     Displays whether `set verbose' is on or off.

     Displays whether `set verbose' is on or off.

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

   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

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

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

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

Errors.).

Errors.).

`set complaints LIMIT'

`set complaints LIMIT'

     Permits GDB to output LIMIT complaints about each type of unusual

     Permits GDB to output LIMIT complaints about each type of unusual

     symbols before becoming silent about the problem.  Set LIMIT to

     symbols before becoming silent about the problem.  Set LIMIT to

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

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

     prevent complaints from being suppressed.

     prevent complaints from being suppressed.

`show complaints'

`show complaints'

     Displays how many symbol complaints GDB is permitted to produce.

     Displays how many symbol complaints GDB is permitted to produce.

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

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

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

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

you try to run a program which is already running:

you try to run a program which is already running:

     (gdb) run

     (gdb) run

     The program being debugged has been started already.

     The program being debugged has been started already.

     Start it from the beginning? (y or n)

     Start it from the beginning? (y or n)

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

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

commands, you can disable this "feature":

commands, you can disable this "feature":

`set confirm off'

`set confirm off'

     Disables confirmation requests.

     Disables confirmation requests.

`set confirm on'

`set confirm on'

     Enables confirmation requests (the default).

     Enables confirmation requests (the default).

`show confirm'

`show confirm'

     Displays state of confirmation requests.

     Displays state of confirmation requests.

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

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

Optional messages about internal happenings

Optional messages about internal happenings

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

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

`set debug arch'

`set debug arch'

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

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

     off

     off

`show debug arch'

`show debug arch'

     Displays the current state of displaying gdbarch debugging info.

     Displays the current state of displaying gdbarch debugging info.

`set debug event'

`set debug event'

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

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

     is off.

     is off.

`show debug event'

`show debug event'

     Displays the current state of displaying GDB event debugging info.

     Displays the current state of displaying GDB event debugging info.

`set debug expression'

`set debug expression'

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

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

     default is off.

     default is off.

`show debug expression'

`show debug expression'

     Displays the current state of displaying GDB expression debugging

     Displays the current state of displaying GDB expression debugging

     info.

     info.

`set debug overload'

`set debug overload'

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

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

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

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

     off.

     off.

`show debug overload'

`show debug overload'

     Displays the current state of displaying GDB C++ overload

     Displays the current state of displaying GDB C++ overload

     debugging info.

     debugging info.

`set debug remote'

`set debug remote'

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

     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

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

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

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

`show debug remote'

`show debug remote'

     Displays the state of display of remote packets.

     Displays the state of display of remote packets.

`set debug serial'

`set debug serial'

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

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

     is off.

     is off.

`show debug serial'

`show debug serial'

     Displays the current state of displaying GDB serial debugging info.

     Displays the current state of displaying GDB serial debugging info.

`set debug target'

`set debug target'

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

     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

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

     happens. The default is off.

     happens. The default is off.

`show debug target'

`show debug target'

     Displays the current state of displaying GDB target debugging info.

     Displays the current state of displaying GDB target debugging info.

`set debug varobj'

`set debug varobj'

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

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

     default is off.

     default is off.

`show debug varobj'

`show debug varobj'

     Displays the current state of displaying GDB variable object

     Displays the current state of displaying GDB variable object

     debugging info.

     debugging info.

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

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

Canned Sequences of Commands

Canned Sequences of Commands

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

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

   Aside from breakpoint commands (*note Breakpoint command lists:

   Aside from breakpoint commands (*note Breakpoint command lists:

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

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

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

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

* Menu:

* Menu:

* Define::                      User-defined commands

* Define::                      User-defined commands

* Hooks::                       User-defined command hooks

* Hooks::                       User-defined command hooks

* Command Files::               Command files

* Command Files::               Command files

* Output::                      Commands for controlled output

* Output::                      Commands for controlled output

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

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

User-defined commands

User-defined commands

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

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

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

   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'

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

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

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

whitespace.  Arguments are accessed within the user command via

whitespace.  Arguments are accessed within the user command via

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

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

     define adder

     define adder

       print $arg0 + $arg1 + $arg2

       print $arg0 + $arg1 + $arg2

To execute the command use:

To execute the command use:

     adder 1 2 3

     adder 1 2 3

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

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

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

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

reference variables, use complex expressions, or even perform inferior

reference variables, use complex expressions, or even perform inferior

functions calls.

functions calls.

`define COMMANDNAME'

`define COMMANDNAME'

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

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

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

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

     it.

     it.

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

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

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

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

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

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

`if'

`if'

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

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

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

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

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

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

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

     `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

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

     containing `end'.

     containing `end'.

`while'

`while'

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

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

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

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

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

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

     commands are executed repeatedly as long as the expression

     commands are executed repeatedly as long as the expression

     evaluates to true.

     evaluates to true.

`document COMMANDNAME'

`document COMMANDNAME'

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

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

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

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

     defined.  This command reads lines of documentation just as

     defined.  This command reads lines of documentation just as

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

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

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

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

     COMMANDNAME displays the documentation you have written.

     COMMANDNAME displays the documentation you have written.

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

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

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

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

     does not change the documentation.

     does not change the documentation.

`help user-defined'

`help user-defined'

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

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

     documentation (if any) for each.

     documentation (if any) for each.

`show user'

`show user'

`show user COMMANDNAME'

`show user COMMANDNAME'

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

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

     documentation).  If no COMMANDNAME is given, display the

     documentation).  If no COMMANDNAME is given, display the

     definitions for all user-defined commands.

     definitions for all user-defined commands.

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

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

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

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

the user-defined command.

the user-defined command.

   If used interactively, commands that would ask for confirmation

   If used interactively, commands that would ask for confirmation

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

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

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

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

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

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

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

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

User-defined command hooks

User-defined command hooks

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

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

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

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

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

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

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

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

that command.

that command.

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

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

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

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

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

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

displays are printed, or the stack frame is printed.

displays are printed, or the stack frame is printed.

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

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

treat them normally during normal execution, you could define:

treat them normally during normal execution, you could define:

     define hook-stop

     define hook-stop

     handle SIGALRM nopass

     handle SIGALRM nopass

     end

     end

     define hook-run

     define hook-run

     handle SIGALRM pass

     handle SIGALRM pass

     end

     end

     define hook-continue

     define hook-continue

     handle SIGLARM pass

     handle SIGLARM pass

     end

     end

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

   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

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

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

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

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

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

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

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

chance to run).

chance to run).

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

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

you get a warning from the `define' command.

you get a warning from the `define' command.

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

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

Command files

Command files

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

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

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

   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

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

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

command, as it would from the terminal.

command, as it would from the terminal.

   When you start GDB, it automatically executes commands from its

   When you start GDB, it automatically executes commands from its

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

"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

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

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

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

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

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

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

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

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

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

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

option; *note Choosing modes: Mode Options..

option; *note Choosing modes: Mode Options..

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

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

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

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

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

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

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

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

special init file names:

special init file names:

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

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

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

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

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

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

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

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

`source' command:

`source' command:

`source FILENAME'

`source FILENAME'

     Execute the command file FILENAME.

     Execute the command file FILENAME.

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

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

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

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

execution of the command file.

execution of the command file.

   Commands that would ask for confirmation if used interactively

   Commands that would ask for confirmation if used interactively

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

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

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

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

messages when called from command files.

messages when called from command files.

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

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

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

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

by the `HOME' environment variable.

by the `HOME' environment variable.

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

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

Commands for controlled output

Commands for controlled output

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

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

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

   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

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

explicitly printed by the commands in the definition.  This section

explicitly printed by the commands in the definition.  This section

describes three commands useful for generating exactly the output you

describes three commands useful for generating exactly the output you

want.

want.

`echo TEXT'

`echo TEXT'

     Print TEXT.  Nonprinting characters can be included in TEXT using

     Print TEXT.  Nonprinting characters can be included in TEXT using

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

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

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

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

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

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

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

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

     beginning or the end, since leading and trailing spaces are

     beginning or the end, since leading and trailing spaces are

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

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

     the command `echo \ and foo = \ '.

     the command `echo \ and foo = \ '.

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

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

     the command onto subsequent lines.  For example,

     the command onto subsequent lines.  For example,

          echo This is some text\n\

          echo This is some text\n\

          which is continued\n\

          which is continued\n\

          onto several lines.\n

          onto several lines.\n

     produces the same output as

     produces the same output as

          echo This is some text\n

          echo This is some text\n

          echo which is continued\n

          echo which is continued\n

          echo onto several lines.\n

          echo onto several lines.\n

`output EXPRESSION'

`output EXPRESSION'

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

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

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

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

     history either.  *Note Expressions: Expressions, for more

     history either.  *Note Expressions: Expressions, for more

     information on expressions.

     information on expressions.

`output/FMT EXPRESSION'

`output/FMT EXPRESSION'

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

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

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

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

     more information.

     more information.

`printf STRING, EXPRESSIONS...'

`printf STRING, EXPRESSIONS...'

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

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

     The EXPRESSIONS are separated by commas and may be either numbers

     The EXPRESSIONS are separated by commas and may be either numbers

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

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

     exactly as if your program were to execute the C subroutine

     exactly as if your program were to execute the C subroutine

          printf (STRING, EXPRESSIONS...);

          printf (STRING, EXPRESSIONS...);

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

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

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

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

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

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

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

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

     letter.

     letter.

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

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

Using GDB under GNU Emacs

Using GDB under GNU Emacs

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

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

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

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

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

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

   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

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

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

created Emacs buffer.

created Emacs buffer.

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

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

things:

things:

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

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

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

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

and output done by the program you are debugging.

and output done by the program you are debugging.

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

   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

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

output in this way.

output in this way.

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

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

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

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.

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

   * GDB displays source code through Emacs.

   * GDB displays source code through Emacs.

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

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

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

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,

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     and output session proceeds normally; but Emacs does not get

     and output session proceeds normally; but Emacs does not get

     enough information back from GDB to locate the source files in

     enough information back from GDB to locate the source files in

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

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

     the directory where your program resides, or specify an absolute

     the directory where your program resides, or specify an absolute

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

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

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

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

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

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

     existing GDB buffer in Emacs.

     existing GDB buffer in Emacs.

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

   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

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

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

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

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

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

     (setq gdb-command-name "mygdb")

     (setq gdb-command-name "mygdb")

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

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

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

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

instead.

instead.

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

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

addition to the standard Shell mode commands:

addition to the standard Shell mode commands:

`C-h m'

`C-h m'

     Describe the features of Emacs' GDB Mode.

     Describe the features of Emacs' GDB Mode.

`M-s'

`M-s'

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

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

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

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

`M-n'

`M-n'

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

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

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

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

     to show the current file and location.

     to show the current file and location.

`M-i'

`M-i'

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

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

     display window accordingly.

     display window accordingly.

`M-x gdb-nexti'

`M-x gdb-nexti'

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

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

     display window accordingly.

     display window accordingly.

`C-c C-f'

`C-c C-f'

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

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

     `finish' command.

     `finish' command.

`M-c'

`M-c'

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

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

     command.

     command.

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

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

`M-u'

`M-u'

     Go up the number of frames indicated by the numeric argument

     Go up the number of frames indicated by the numeric argument

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

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

     command.

     command.

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

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

`M-d'

`M-d'

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

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

     like the GDB `down' command.

     like the GDB `down' command.

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

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

`C-x &'

`C-x &'

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

     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

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

     disassemble code around an address that was displayed earlier,

     disassemble code around an address that was displayed earlier,

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

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

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

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

     You can customize this further by defining elements of the list

     You can customize this further by defining elements of the list

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

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

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

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

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

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

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

     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

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

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

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

     the number is passed as an argument to the corresponding list

     the number is passed as an argument to the corresponding list

     element.

     element.

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

   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.

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

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

   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

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

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

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

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

   The source files displayed in Emacs are in ordinary Emacs buffers

   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

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

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

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

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

correspond properly with the code.

correspond properly with the code.

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

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

GDB Annotations

GDB Annotations

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

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

   This chapter describes annotations in GDB.  Annotations are designed

   This chapter describes annotations in GDB.  Annotations are designed

to interface GDB to graphical user interfaces or other similar programs

to interface GDB to graphical user interfaces or other similar programs

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

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

* Menu:

* Menu:

* Annotations Overview::  What annotations are; the general syntax.

* Annotations Overview::  What annotations are; the general syntax.

* Server Prefix::       Issuing a command without affecting user state.

* Server Prefix::       Issuing a command without affecting user state.

* Value Annotations::   Values are marked as such.

* Value Annotations::   Values are marked as such.

* Frame Annotations::   Stack frames are annotated.

* Frame Annotations::   Stack frames are annotated.

* Displays::            GDB can be told to display something periodically.

* Displays::            GDB can be told to display something periodically.

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

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

* Errors::              Annotations for error messages.

* Errors::              Annotations for error messages.

* Breakpoint Info::     Information on breakpoints.

* Breakpoint Info::     Information on breakpoints.

* Invalidation::        Some annotations describe things now invalid.

* Invalidation::        Some annotations describe things now invalid.

* Annotations for Running::

* Annotations for Running::

                        Whether the program is running, how it stopped, etc.

                        Whether the program is running, how it stopped, etc.

* Source Annotations::  Annotations describing source code.

* Source Annotations::  Annotations describing source code.

* TODO::                Annotations which might be added in the future.

* TODO::                Annotations which might be added in the future.

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

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

What is an Annotation?

What is an Annotation?

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

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

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

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

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

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

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

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

information associated with this annotation, the name of the annotation

information associated with this annotation, the name of the annotation

is followed immediately by a newline.  If there is additional

is followed immediately by a newline.  If there is additional

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

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

additional information, and a newline.  The additional information

additional information, and a newline.  The additional information

cannot contain newline characters.

cannot contain newline characters.

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

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

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

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

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

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

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

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

`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 GDB with annotations is:

     $ gdb --annotate=2

     $ gdb --annotate=2

     GNU GDB 5.0

     GNU GDB 5.0

     Copyright 2000 Free Software Foundation, Inc.

     Copyright 2000 Free Software Foundation, Inc.

     GDB is free software, covered by the GNU General Public License,

     GDB is free software, covered by the GNU General Public License,

     and you are welcome to change it and/or distribute copies of it

     and you are welcome to change it and/or distribute copies of it

     under certain conditions.

     under certain conditions.

     Type "show copying" to see the conditions.

     Type "show copying" to see the conditions.

     There is absolutely no warranty for GDB.  Type "show warranty"

     There is absolutely no warranty for GDB.  Type "show warranty"

     for details.

     for details.

     This GDB was configured as "sparc-sun-sunos4.1.3"

     This GDB was configured as "sparc-sun-sunos4.1.3"

     ^Z^Zpre-prompt

     ^Z^Zpre-prompt

     (gdb)

     (gdb)

     ^Z^Zprompt

     ^Z^Zprompt

     quit

     quit

     ^Z^Zpost-prompt

     ^Z^Zpost-prompt

     $

     $

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

   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

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

annotations; the rest is output from GDB.

annotations; the rest is output from GDB.

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

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

The Server Prefix

The Server Prefix

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

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

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

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

state which is seen by users, prefix it with `server '.  This means

state which is seen by users, prefix it with `server '.  This means

that this command will not affect the command history, nor will it

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

affect GDB's notion of which command to repeat if  is pressed on a

line by itself.

line by itself.

   The server prefix does not affect the recording of values into the

   The server prefix does not affect the recording of values into the

value history; to print a value without recording it into the value

value history; to print a value without recording it into the value

history, use the `output' command instead of the `print' command.

history, use the `output' command instead of the `print' command.

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

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

Values

Values

======

======

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

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

delimit the value from the surrounding text.

delimit the value from the surrounding text.

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

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

the annotation looks like

the annotation looks like

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

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

     HISTORY-STRING

     HISTORY-STRING

     ^Z^Zvalue-history-value

     ^Z^Zvalue-history-value

     THE-VALUE

     THE-VALUE

     ^Z^Zvalue-history-end

     ^Z^Zvalue-history-end

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

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

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

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

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

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

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

dereferenced and `-' for a value which cannot.

dereferenced and `-' for a value which cannot.

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

   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

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

similar:

similar:

     ^Z^Zvalue-begin VALUE-FLAGS

     ^Z^Zvalue-begin VALUE-FLAGS

     THE-VALUE

     THE-VALUE

     ^Z^Zvalue-end

     ^Z^Zvalue-end

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

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

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

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

     ^Z^Zarg-begin

     ^Z^Zarg-begin

     ARGUMENT-NAME

     ARGUMENT-NAME

     ^Z^Zarg-name-end

     ^Z^Zarg-name-end

     SEPARATOR-STRING

     SEPARATOR-STRING

     ^Z^Zarg-value VALUE-FLAGS

     ^Z^Zarg-value VALUE-FLAGS

     THE-VALUE

     THE-VALUE

     ^Z^Zarg-end

     ^Z^Zarg-end

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

   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

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

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

in a `value-history-begin' annotation.

in a `value-history-begin' annotation.

   When printing a structure, GDB annotates it as follows:

   When printing a structure, GDB annotates it as follows:

     ^Z^Zfield-begin VALUE-FLAGS

     ^Z^Zfield-begin VALUE-FLAGS

     FIELD-NAME

     FIELD-NAME

     ^Z^Zfield-name-end

     ^Z^Zfield-name-end

     SEPARATOR-STRING

     SEPARATOR-STRING

     ^Z^Zfield-value

     ^Z^Zfield-value

     THE-VALUE

     THE-VALUE

     ^Z^Zfield-end

     ^Z^Zfield-end

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

   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

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

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

`value-history-begin' annotation.

`value-history-begin' annotation.

   When printing an array, GDB annotates it as follows:

   When printing an array, GDB annotates it as follows:

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

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

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

   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'

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

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

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

element can be either a single element:

element can be either a single element:

     `,' WHITESPACE         ; omitted for the first element

     `,' WHITESPACE         ; omitted for the first element

     THE-VALUE

     THE-VALUE

     ^Z^Zelt

     ^Z^Zelt

   or a repeated element

   or a repeated element

     `,' WHITESPACE         ; omitted for the first element

     `,' WHITESPACE         ; omitted for the first element

     THE-VALUE

     THE-VALUE

     ^Z^Zelt-rep NUMBER-OF-REPITITIONS

     ^Z^Zelt-rep NUMBER-OF-REPITITIONS

     REPETITION-STRING

     REPETITION-STRING

     ^Z^Zelt-rep-end

     ^Z^Zelt-rep-end

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

   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

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

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

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

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

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

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

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

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

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

ended with

ended with

     ^Z^Zarray-section-end

     ^Z^Zarray-section-end

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

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

Frames

Frames

======

======

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

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

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

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

`backtrace' or `up', etc.

`backtrace' or `up', etc.

   The frame annotation begins with

   The frame annotation begins with

     ^Z^Zframe-begin LEVEL ADDRESS

     ^Z^Zframe-begin LEVEL ADDRESS

     LEVEL-STRING

     LEVEL-STRING

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

   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

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

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

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

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

language).  The frame ends with

language).  The frame ends with

     ^Z^Zframe-end

     ^Z^Zframe-end

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

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

consist of

consist of

   *      ^Z^Zfunction-call

   *      ^Z^Zfunction-call

          FUNCTION-CALL-STRING

          FUNCTION-CALL-STRING

     where FUNCTION-CALL-STRING is text designed to convey to the user

     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

     that this frame is associated with a function call made by GDB to a

     function in the program being debugged.

     function in the program being debugged.

   *      ^Z^Zsignal-handler-caller

   *      ^Z^Zsignal-handler-caller

          SIGNAL-HANDLER-CALLER-STRING

          SIGNAL-HANDLER-CALLER-STRING

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

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

     the user that this frame is associated with whatever mechanism is

     the user that this frame is associated with whatever mechanism is

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

     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

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

     handler itself).

     handler itself).

   * A normal frame.

   * A normal frame.

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

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

     interesting information for the user to see) begin with

     interesting information for the user to see) begin with

          ^Z^Zframe-address

          ^Z^Zframe-address

          ADDRESS

          ADDRESS

          ^Z^Zframe-address-end

          ^Z^Zframe-address-end

          SEPARATOR-STRING

          SEPARATOR-STRING

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

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

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

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

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

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

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

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

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

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

     benefit.

     benefit.

     Then comes

     Then comes

          ^Z^Zframe-function-name

          ^Z^Zframe-function-name

          FUNCTION-NAME

          FUNCTION-NAME

          ^Z^Zframe-args

          ^Z^Zframe-args

          ARGUMENTS

          ARGUMENTS

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

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

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

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

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

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

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

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

     printed:

     printed:

          ^Z^Zframe-source-begin

          ^Z^Zframe-source-begin

          SOURCE-INTRO-STRING

          SOURCE-INTRO-STRING

          ^Z^Zframe-source-file

          ^Z^Zframe-source-file

          FILENAME

          FILENAME

          ^Z^Zframe-source-file-end

          ^Z^Zframe-source-file-end

          :

          :

          ^Z^Zframe-source-line

          ^Z^Zframe-source-line

          LINE-NUMBER

          LINE-NUMBER

          ^Z^Zframe-source-end

          ^Z^Zframe-source-end

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

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

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

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

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

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

     file (the first line is line 1).

     file (the first line is line 1).

     If GDB prints some information about where the frame is from (which

     If GDB prints some information about where the frame is from (which

     library, which load segment, etc.; currently only done on the

     library, which load segment, etc.; currently only done on the

     RS/6000), it is annotated with

     RS/6000), it is annotated with

          ^Z^Zframe-where

          ^Z^Zframe-where

          INFORMATION

          INFORMATION

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

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

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

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

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

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

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

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

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

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

Displays

Displays

========

========

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

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

the results of the display are annotated:

the results of the display are annotated:

     ^Z^Zdisplay-begin

     ^Z^Zdisplay-begin

     NUMBER

     NUMBER

     ^Z^Zdisplay-number-end

     ^Z^Zdisplay-number-end

     NUMBER-SEPARATOR

     NUMBER-SEPARATOR

     ^Z^Zdisplay-format

     ^Z^Zdisplay-format

     FORMAT

     FORMAT

     ^Z^Zdisplay-expression

     ^Z^Zdisplay-expression

     EXPRESSION

     EXPRESSION

     ^Z^Zdisplay-expression-end

     ^Z^Zdisplay-expression-end

     EXPRESSION-SEPARATOR

     EXPRESSION-SEPARATOR

     ^Z^Zdisplay-value

     ^Z^Zdisplay-value

     VALUE

     VALUE

     ^Z^Zdisplay-end

     ^Z^Zdisplay-end

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

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

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

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

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

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

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

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

being displayed, EXPRESSION-SEPARATOR is intended to separate the

being displayed, EXPRESSION-SEPARATOR is intended to separate the

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

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

actual value being displayed.

actual value being displayed.

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

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

Annotation for GDB Input

Annotation for GDB Input

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

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

   When GDB prompts for input, it annotates this fact so it is possible

   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

to know when to send output, when the output from a given command is

over, etc.

over, etc.