Subversion Repositories or1k

This is gdbint.info, produced by makeinfo version 4.0 from

This is gdbint.info, produced by makeinfo version 4.0 from

./gdbint.texinfo.

./gdbint.texinfo.

INFO-DIR-SECTION Programming & development tools.

INFO-DIR-SECTION Programming & development tools.

START-INFO-DIR-ENTRY

START-INFO-DIR-ENTRY

START-INFO-DIR-ENTRY

START-INFO-DIR-ENTRY

* Gdb-Internals: (gdbint).      The GNU debugger's internals.

* Gdb-Internals: (gdbint).      The GNU debugger's internals.

END-INFO-DIR-ENTRY

END-INFO-DIR-ENTRY

END-INFO-DIR-ENTRY

END-INFO-DIR-ENTRY

   This file documents the internals of the GNU debugger GDB.

   This file documents the internals of the GNU debugger GDB.

Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001    Free

Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001    Free

Software Foundation, Inc.  Contributed by Cygnus Solutions.  Written by

Software Foundation, Inc.  Contributed by Cygnus Solutions.  Written by

John Gilmore.  Second Edition by Stan Shebs.

John Gilmore.  Second Edition by Stan Shebs.

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

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

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

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

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

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

Invariant Sections being "Algorithms" and "Porting GDB", with the

Invariant Sections being "Algorithms" and "Porting GDB", with the

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

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

as in (a) below.

as in (a) below.

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

   (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

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

Software Foundation raise funds for GNU development."

Software Foundation raise funds for GNU development."

File: gdbint.info,  Node: Top,  Next: Requirements,  Up: (dir)

File: gdbint.info,  Node: Top,  Next: Requirements,  Up: (dir)

Scope of this Document

Scope of this Document

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

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

   This document documents the internals of the GNU debugger, GDB.  It

   This document documents the internals of the GNU debugger, GDB.  It

includes description of GDB's key algorithms and operations, as well as

includes description of GDB's key algorithms and operations, as well as

the mechanisms that adapt GDB to specific hosts and targets.

the mechanisms that adapt GDB to specific hosts and targets.

* Menu:

* Menu:

* Requirements::

* Requirements::

* Overall Structure::

* Overall Structure::

* Algorithms::

* Algorithms::

* User Interface::

* User Interface::

* Symbol Handling::

* Symbol Handling::

* Language Support::

* Language Support::

* Host Definition::

* Host Definition::

* Target Architecture Definition::

* Target Architecture Definition::

* Target Vector Definition::

* Target Vector Definition::

* Native Debugging::

* Native Debugging::

* Support Libraries::

* Support Libraries::

* Coding::

* Coding::

* Porting GDB::

* Porting GDB::

* Testsuite::

* Testsuite::

* Hints::

* Hints::

* Index::

* Index::

File: gdbint.info,  Node: Requirements,  Next: Overall Structure,  Prev: Top,  Up: Top

File: gdbint.info,  Node: Requirements,  Next: Overall Structure,  Prev: Top,  Up: Top

Requirements

Requirements

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

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

   Before diving into the internals, you should understand the formal

   Before diving into the internals, you should understand the formal

requirements and other expectations for GDB.  Although some of these

requirements and other expectations for GDB.  Although some of these

may seem obvious, there have been proposals for GDB that have run

may seem obvious, there have been proposals for GDB that have run

counter to these requirements.

counter to these requirements.

   First of all, GDB is a debugger.  It's not designed to be a front

   First of all, GDB is a debugger.  It's not designed to be a front

panel for embedded systems.  It's not a text editor.  It's not a shell.

panel for embedded systems.  It's not a text editor.  It's not a shell.

It's not a programming environment.

It's not a programming environment.

   GDB is an interactive tool.  Although a batch mode is available,

   GDB is an interactive tool.  Although a batch mode is available,

GDB's primary role is to interact with a human programmer.

GDB's primary role is to interact with a human programmer.

   GDB should be responsive to the user.  A programmer hot on the trail

   GDB should be responsive to the user.  A programmer hot on the trail

of a nasty bug, and operating under a looming deadline, is going to be

of a nasty bug, and operating under a looming deadline, is going to be

very impatient of everything, including the response time to debugger

very impatient of everything, including the response time to debugger

commands.

commands.

   GDB should be relatively permissive, such as for expressions.  While

   GDB should be relatively permissive, such as for expressions.  While

the compiler should be picky (or have the option to be made picky),

the compiler should be picky (or have the option to be made picky),

since source code lives for a long time usuazlly, the programmer doing

since source code lives for a long time usuazlly, the programmer doing

debugging shouldn't be spending time figuring out to mollify the

debugging shouldn't be spending time figuring out to mollify the

debugger.

debugger.

   GDB will be called upon to deal with really large programs.

   GDB will be called upon to deal with really large programs.

Executable sizes of 50 to 100 megabytes occur regularly, and we've

Executable sizes of 50 to 100 megabytes occur regularly, and we've

heard reports of programs approaching 1 gigabyte in size.

heard reports of programs approaching 1 gigabyte in size.

   GDB should be able to run everywhere.  No other debugger is

   GDB should be able to run everywhere.  No other debugger is

available for even half as many configurations as GDB supports.

available for even half as many configurations as GDB supports.

File: gdbint.info,  Node: Overall Structure,  Next: Algorithms,  Prev: Requirements,  Up: Top

File: gdbint.info,  Node: Overall Structure,  Next: Algorithms,  Prev: Requirements,  Up: Top

Overall Structure

Overall Structure

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

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

   GDB consists of three major subsystems: user interface, symbol

   GDB consists of three major subsystems: user interface, symbol

handling (the "symbol side"), and target system handling (the "target

handling (the "symbol side"), and target system handling (the "target

side").

side").

   The user interface consists of several actual interfaces, plus

   The user interface consists of several actual interfaces, plus

supporting code.

supporting code.

   The symbol side consists of object file readers, debugging info

   The symbol side consists of object file readers, debugging info

interpreters, symbol table management, source language expression

interpreters, symbol table management, source language expression

parsing, type and value printing.

parsing, type and value printing.

   The target side consists of execution control, stack frame analysis,

   The target side consists of execution control, stack frame analysis,

and physical target manipulation.

and physical target manipulation.

   The target side/symbol side division is not formal, and there are a

   The target side/symbol side division is not formal, and there are a

number of exceptions.  For instance, core file support involves symbolic

number of exceptions.  For instance, core file support involves symbolic

elements (the basic core file reader is in BFD) and target elements (it

elements (the basic core file reader is in BFD) and target elements (it

supplies the contents of memory and the values of registers).  Instead,

supplies the contents of memory and the values of registers).  Instead,

this division is useful for understanding how the minor subsystems

this division is useful for understanding how the minor subsystems

should fit together.

should fit together.

The Symbol Side

The Symbol Side

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

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

   The symbolic side of GDB can be thought of as "everything you can do

   The symbolic side of GDB can be thought of as "everything you can do

in GDB without having a live program running".  For instance, you can

in GDB without having a live program running".  For instance, you can

look at the types of variables, and evaluate many kinds of expressions.

look at the types of variables, and evaluate many kinds of expressions.

The Target Side

The Target Side

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

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

   The target side of GDB is the "bits and bytes manipulator".

   The target side of GDB is the "bits and bytes manipulator".

Although it may make reference to symbolic info here and there, most of

Although it may make reference to symbolic info here and there, most of

the target side will run with only a stripped executable available--or

the target side will run with only a stripped executable available--or

even no executable at all, in remote debugging cases.

even no executable at all, in remote debugging cases.

   Operations such as disassembly, stack frame crawls, and register

   Operations such as disassembly, stack frame crawls, and register

display, are able to work with no symbolic info at all.  In some cases,

display, are able to work with no symbolic info at all.  In some cases,

such as disassembly, GDB will use symbolic info to present addresses

such as disassembly, GDB will use symbolic info to present addresses

relative to symbols rather than as raw numbers, but it will work either

relative to symbols rather than as raw numbers, but it will work either

way.

way.

Configurations

Configurations

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

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

   "Host" refers to attributes of the system where GDB runs.  "Target"

   "Host" refers to attributes of the system where GDB runs.  "Target"

refers to the system where the program being debugged executes.  In

refers to the system where the program being debugged executes.  In

most cases they are the same machine, in which case a third type of

most cases they are the same machine, in which case a third type of

"Native" attributes come into play.

"Native" attributes come into play.

   Defines and include files needed to build on the host are host

   Defines and include files needed to build on the host are host

support.  Examples are tty support, system defined types, host byte

support.  Examples are tty support, system defined types, host byte

order, host float format.

order, host float format.

   Defines and information needed to handle the target format are target

   Defines and information needed to handle the target format are target

dependent.  Examples are the stack frame format, instruction set,

dependent.  Examples are the stack frame format, instruction set,

breakpoint instruction, registers, and how to set up and tear down the

breakpoint instruction, registers, and how to set up and tear down the

stack to call a function.

stack to call a function.

   Information that is only needed when the host and target are the

   Information that is only needed when the host and target are the

same, is native dependent.  One example is Unix child process support;

same, is native dependent.  One example is Unix child process support;

if the host and target are not the same, doing a fork to start the

if the host and target are not the same, doing a fork to start the

target process is a bad idea.  The various macros needed for finding the

target process is a bad idea.  The various macros needed for finding the

registers in the `upage', running `ptrace', and such are all in the

registers in the `upage', running `ptrace', and such are all in the

native-dependent files.

native-dependent files.

   Another example of native-dependent code is support for features that

   Another example of native-dependent code is support for features that

are really part of the target environment, but which require `#include'

are really part of the target environment, but which require `#include'

files that are only available on the host system.  Core file handling

files that are only available on the host system.  Core file handling

and `setjmp' handling are two common cases.

and `setjmp' handling are two common cases.

   When you want to make GDB work "native" on a particular machine, you

   When you want to make GDB work "native" on a particular machine, you

have to include all three kinds of information.

have to include all three kinds of information.

File: gdbint.info,  Node: Algorithms,  Next: User Interface,  Prev: Overall Structure,  Up: Top

File: gdbint.info,  Node: Algorithms,  Next: User Interface,  Prev: Overall Structure,  Up: Top

Algorithms

Algorithms

**********

**********

   GDB uses a number of debugging-specific algorithms.  They are often

   GDB uses a number of debugging-specific algorithms.  They are often

not very complicated, but get lost in the thicket of special cases and

not very complicated, but get lost in the thicket of special cases and

real-world issues.  This chapter describes the basic algorithms and

real-world issues.  This chapter describes the basic algorithms and

mentions some of the specific target definitions that they use.

mentions some of the specific target definitions that they use.

Frames

Frames

======

======

   A frame is a construct that GDB uses to keep track of calling and

   A frame is a construct that GDB uses to keep track of calling and

called functions.

called functions.

   `FRAME_FP' in the machine description has no meaning to the

   `FRAME_FP' in the machine description has no meaning to the

machine-independent part of GDB, except that it is used when setting up

machine-independent part of GDB, except that it is used when setting up

a new frame from scratch, as follows:

a new frame from scratch, as follows:

           create_new_frame (read_register (FP_REGNUM), read_pc ()));

           create_new_frame (read_register (FP_REGNUM), read_pc ()));

   Other than that, all the meaning imparted to `FP_REGNUM' is imparted

   Other than that, all the meaning imparted to `FP_REGNUM' is imparted

by the machine-dependent code.  So, `FP_REGNUM' can have any value that

by the machine-dependent code.  So, `FP_REGNUM' can have any value that

is convenient for the code that creates new frames.

is convenient for the code that creates new frames.

(`create_new_frame' calls `INIT_EXTRA_FRAME_INFO' if it is defined;

(`create_new_frame' calls `INIT_EXTRA_FRAME_INFO' if it is defined;

that is where you should use the `FP_REGNUM' value, if your frames are

that is where you should use the `FP_REGNUM' value, if your frames are

nonstandard.)

nonstandard.)

   Given a GDB frame, define `FRAME_CHAIN' to determine the address of

   Given a GDB frame, define `FRAME_CHAIN' to determine the address of

the calling function's frame.  This will be used to create a new GDB

the calling function's frame.  This will be used to create a new GDB

frame struct, and then `INIT_EXTRA_FRAME_INFO' and `INIT_FRAME_PC' will

frame struct, and then `INIT_EXTRA_FRAME_INFO' and `INIT_FRAME_PC' will

be called for the new frame.

be called for the new frame.

Breakpoint Handling

Breakpoint Handling

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

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

   In general, a breakpoint is a user-designated location in the program

   In general, a breakpoint is a user-designated location in the program

where the user wants to regain control if program execution ever reaches

where the user wants to regain control if program execution ever reaches

that location.

that location.

   There are two main ways to implement breakpoints; either as

   There are two main ways to implement breakpoints; either as

"hardware" breakpoints or as "software" breakpoints.

"hardware" breakpoints or as "software" breakpoints.

   Hardware breakpoints are sometimes available as a builtin debugging

   Hardware breakpoints are sometimes available as a builtin debugging

features with some chips.  Typically these work by having dedicated

features with some chips.  Typically these work by having dedicated

register into which the breakpoint address may be stored.  If the PC

register into which the breakpoint address may be stored.  If the PC

(shorthand for "program counter") ever matches a value in a breakpoint

(shorthand for "program counter") ever matches a value in a breakpoint

registers, the CPU raises an exception and reports it to GDB.

registers, the CPU raises an exception and reports it to GDB.

   Another possibility is when an emulator is in use; many emulators

   Another possibility is when an emulator is in use; many emulators

include circuitry that watches the address lines coming out from the

include circuitry that watches the address lines coming out from the

processor, and force it to stop if the address matches a breakpoint's

processor, and force it to stop if the address matches a breakpoint's

address.

address.

   A third possibility is that the target already has the ability to do

   A third possibility is that the target already has the ability to do

breakpoints somehow; for instance, a ROM monitor may do its own

breakpoints somehow; for instance, a ROM monitor may do its own

software breakpoints.  So although these are not literally "hardware

software breakpoints.  So although these are not literally "hardware

breakpoints", from GDB's point of view they work the same; GDB need not

breakpoints", from GDB's point of view they work the same; GDB need not

do nothing more than set the breakpoint and wait for something to

do nothing more than set the breakpoint and wait for something to

happen.

happen.

   Since they depend on hardware resources, hardware breakpoints may be

   Since they depend on hardware resources, hardware breakpoints may be

limited in number; when the user asks for more, GDB will start trying

limited in number; when the user asks for more, GDB will start trying

to set software breakpoints.  (On some architectures, notably the

to set software breakpoints.  (On some architectures, notably the

32-bit x86 platforms, GDB cannot alsways know whether there's enough

32-bit x86 platforms, GDB cannot alsways know whether there's enough

hardware resources to insert all the hardware breakpoints and

hardware resources to insert all the hardware breakpoints and

watchpoints.  On those platforms, GDB prints an error message only when

watchpoints.  On those platforms, GDB prints an error message only when

the program being debugged is continued.)

the program being debugged is continued.)

   Software breakpoints require GDB to do somewhat more work.  The

   Software breakpoints require GDB to do somewhat more work.  The

basic theory is that GDB will replace a program instruction with a

basic theory is that GDB will replace a program instruction with a

trap, illegal divide, or some other instruction that will cause an

trap, illegal divide, or some other instruction that will cause an

exception, and then when it's encountered, GDB will take the exception

exception, and then when it's encountered, GDB will take the exception

and stop the program.  When the user says to continue, GDB will restore

and stop the program.  When the user says to continue, GDB will restore

the original instruction, single-step, re-insert the trap, and continue

the original instruction, single-step, re-insert the trap, and continue

on.

on.

   Since it literally overwrites the program being tested, the program

   Since it literally overwrites the program being tested, the program

area must be writeable, so this technique won't work on programs in

area must be writeable, so this technique won't work on programs in

ROM.  It can also distort the behavior of programs that examine

ROM.  It can also distort the behavior of programs that examine

themselves, although such a situation would be highly unusual.

themselves, although such a situation would be highly unusual.

   Also, the software breakpoint instruction should be the smallest

   Also, the software breakpoint instruction should be the smallest

size of instruction, so it doesn't overwrite an instruction that might

size of instruction, so it doesn't overwrite an instruction that might

be a jump target, and cause disaster when the program jumps into the

be a jump target, and cause disaster when the program jumps into the

middle of the breakpoint instruction.  (Strictly speaking, the

middle of the breakpoint instruction.  (Strictly speaking, the

breakpoint must be no larger than the smallest interval between

breakpoint must be no larger than the smallest interval between

instructions that may be jump targets; perhaps there is an architecture

instructions that may be jump targets; perhaps there is an architecture

where only even-numbered instructions may jumped to.)  Note that it's

where only even-numbered instructions may jumped to.)  Note that it's

possible for an instruction set not to have any instructions usable for

possible for an instruction set not to have any instructions usable for

a software breakpoint, although in practice only the ARC has failed to

a software breakpoint, although in practice only the ARC has failed to

define such an instruction.

define such an instruction.

   The basic definition of the software breakpoint is the macro

   The basic definition of the software breakpoint is the macro

`BREAKPOINT'.

`BREAKPOINT'.

   Basic breakpoint object handling is in `breakpoint.c'.  However,

   Basic breakpoint object handling is in `breakpoint.c'.  However,

much of the interesting breakpoint action is in `infrun.c'.

much of the interesting breakpoint action is in `infrun.c'.

Single Stepping

Single Stepping

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

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

Signal Handling

Signal Handling

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

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

Thread Handling

Thread Handling

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

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

Inferior Function Calls

Inferior Function Calls

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

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

Longjmp Support

Longjmp Support

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

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

   GDB has support for figuring out that the target is doing a

   GDB has support for figuring out that the target is doing a

`longjmp' and for stopping at the target of the jump, if we are

`longjmp' and for stopping at the target of the jump, if we are

stepping.  This is done with a few specialized internal breakpoints,

stepping.  This is done with a few specialized internal breakpoints,

which are visible in the output of the `maint info breakpoint' command.

which are visible in the output of the `maint info breakpoint' command.

   To make this work, you need to define a macro called

   To make this work, you need to define a macro called

`GET_LONGJMP_TARGET', which will examine the `jmp_buf' structure and

`GET_LONGJMP_TARGET', which will examine the `jmp_buf' structure and

extract the longjmp target address.  Since `jmp_buf' is target

extract the longjmp target address.  Since `jmp_buf' is target

specific, you will need to define it in the appropriate `tm-TARGET.h'

specific, you will need to define it in the appropriate `tm-TARGET.h'

file.  Look in `tm-sun4os4.h' and `sparc-tdep.c' for examples of how to

file.  Look in `tm-sun4os4.h' and `sparc-tdep.c' for examples of how to

do this.

do this.

Watchpoints

Watchpoints

===========

===========

   Watchpoints are a special kind of breakpoints (*note breakpoints:

   Watchpoints are a special kind of breakpoints (*note breakpoints:

Algorithms.) which break when data is accessed rather than when some

Algorithms.) which break when data is accessed rather than when some

instruction is executed.  When you have data which changes without your

instruction is executed.  When you have data which changes without your

knowing what code does that, watchpoints are the silver bullet to hunt

knowing what code does that, watchpoints are the silver bullet to hunt

down and kill such bugs.

down and kill such bugs.

   Watchpoints can be either hardware-assisted or not; the latter type

   Watchpoints can be either hardware-assisted or not; the latter type

is known as "software watchpoints."  GDB always uses hardware-assisted

is known as "software watchpoints."  GDB always uses hardware-assisted

watchpoints if they are available, and falls back on software

watchpoints if they are available, and falls back on software

watchpoints otherwise.  Typical situations where GDB will use software

watchpoints otherwise.  Typical situations where GDB will use software

watchpoints are:

watchpoints are:

   * The watched memory region is too large for the underlying hardware

   * The watched memory region is too large for the underlying hardware

     watchpoint support.  For example, each x86 debug register can

     watchpoint support.  For example, each x86 debug register can

     watch up to 4 bytes of memory, so trying to watch data structures

     watch up to 4 bytes of memory, so trying to watch data structures

     whose size is more than 16 bytes will cause GDB to use software

     whose size is more than 16 bytes will cause GDB to use software

     watchpoints.

     watchpoints.

   * The value of the expression to be watched depends on data held in

   * The value of the expression to be watched depends on data held in

     registers (as opposed to memory).

     registers (as opposed to memory).

   * Too many different watchpoints requested.  (On some architectures,

   * Too many different watchpoints requested.  (On some architectures,

     this situation is impossible to detect until the debugged program

     this situation is impossible to detect until the debugged program

     is resumed.)  Note that x86 debug registers are used both for

     is resumed.)  Note that x86 debug registers are used both for

     hardware breakpoints and for watchpoints, so setting too many

     hardware breakpoints and for watchpoints, so setting too many

     hardware breakpoints might cause watchpoint insertion to fail.

     hardware breakpoints might cause watchpoint insertion to fail.

   * No hardware-assisted watchpoints provided by the target

   * No hardware-assisted watchpoints provided by the target

     implementation.

     implementation.

   Software watchpoints are very slow, since GDB needs to single-step

   Software watchpoints are very slow, since GDB needs to single-step

the program being debugged and test the value of the watched

the program being debugged and test the value of the watched

expression(s) after each instruction.  The rest of this section is

expression(s) after each instruction.  The rest of this section is

mostly irrelevant for software watchpoints.

mostly irrelevant for software watchpoints.

   GDB uses several macros and primitives to support hardware

   GDB uses several macros and primitives to support hardware

watchpoints:

watchpoints:

`TARGET_HAS_HARDWARE_WATCHPOINTS'

`TARGET_HAS_HARDWARE_WATCHPOINTS'

     If defined, the target supports hardware watchpoints.

     If defined, the target supports hardware watchpoints.

`TARGET_CAN_USE_HARDWARE_WATCHPOINT (TYPE, COUNT, OTHER)'

`TARGET_CAN_USE_HARDWARE_WATCHPOINT (TYPE, COUNT, OTHER)'

     Return the number of hardware watchpoints of type TYPE that are

     Return the number of hardware watchpoints of type TYPE that are

     possible to be set.  The value is positive if COUNT watchpoints of

     possible to be set.  The value is positive if COUNT watchpoints of

     this type can be set, zero if setting watchpoints of this type is

     this type can be set, zero if setting watchpoints of this type is

     not supported, and negative if COUNT is more than the maximum

     not supported, and negative if COUNT is more than the maximum

     number of watchpoints of type TYPE that can be set.  OTHER is

     number of watchpoints of type TYPE that can be set.  OTHER is

     non-zero if other types of watchpoints are currently enabled (there

     non-zero if other types of watchpoints are currently enabled (there

     are architectures which cannot set watchpoints of different types

     are architectures which cannot set watchpoints of different types

     at the same time).

     at the same time).

`TARGET_REGION_OK_FOR_HW_WATCHPOINT (ADDR, LEN)'

`TARGET_REGION_OK_FOR_HW_WATCHPOINT (ADDR, LEN)'

     Return non-zero if hardware watchpoints can be used to watch a

     Return non-zero if hardware watchpoints can be used to watch a

     region whose address is ADDR and whose length in bytes is LEN.

     region whose address is ADDR and whose length in bytes is LEN.

`TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (SIZE)'

`TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (SIZE)'

     Return non-zero if hardware watchpoints can be used to watch a

     Return non-zero if hardware watchpoints can be used to watch a

     region whose size is SIZE.  GDB only uses this macro as a

     region whose size is SIZE.  GDB only uses this macro as a

     fall-back, in case `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is not

     fall-back, in case `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is not

     defined.

     defined.

`TARGET_DISABLE_HW_WATCHPOINTS (PID)'

`TARGET_DISABLE_HW_WATCHPOINTS (PID)'

     Disables watchpoints in the process identified by PID.  This is

     Disables watchpoints in the process identified by PID.  This is

     used, e.g., on HP-UX which provides operations to disable and

     used, e.g., on HP-UX which provides operations to disable and

     enable the page-level memory protection that implements hardware

     enable the page-level memory protection that implements hardware

     watchpoints on that platform.

     watchpoints on that platform.

`TARGET_ENABLE_HW_WATCHPOINTS (PID)'

`TARGET_ENABLE_HW_WATCHPOINTS (PID)'

     Enables watchpoints in the process identified by PID.  This is

     Enables watchpoints in the process identified by PID.  This is

     used, e.g., on HP-UX which provides operations to disable and

     used, e.g., on HP-UX which provides operations to disable and

     enable the page-level memory protection that implements hardware

     enable the page-level memory protection that implements hardware

     watchpoints on that platform.

     watchpoints on that platform.

`TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT (PID,START,LEN)'

`TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT (PID,START,LEN)'

     Some addresses may not be profitable to use hardware to watch, or

     Some addresses may not be profitable to use hardware to watch, or

     may be difficult to understand when the addressed object is out of

     may be difficult to understand when the addressed object is out of

     scope, and hence should not be watched with hardware watchpoints.

     scope, and hence should not be watched with hardware watchpoints.

     On some targets, this may have severe performance penalties, such

     On some targets, this may have severe performance penalties, such

     that we might as well use regular watchpoints, and save (possibly

     that we might as well use regular watchpoints, and save (possibly

     precious) hardware watchpoints for other locations.

     precious) hardware watchpoints for other locations.

`target_insert_watchpoint (ADDR, LEN, TYPE)'

`target_insert_watchpoint (ADDR, LEN, TYPE)'

`target_remove_watchpoint (ADDR, LEN, TYPE)'

`target_remove_watchpoint (ADDR, LEN, TYPE)'

     Insert or remove a hardware watchpoint starting at ADDR, for LEN

     Insert or remove a hardware watchpoint starting at ADDR, for LEN

     bytes.  TYPE is the watchpoint type, one of the possible values of

     bytes.  TYPE is the watchpoint type, one of the possible values of

     the enumerated data type `target_hw_bp_type', defined by

     the enumerated data type `target_hw_bp_type', defined by

     `breakpoint.h' as follows:

     `breakpoint.h' as follows:

           enum target_hw_bp_type

           enum target_hw_bp_type

             {

             {

               hw_write   = 0, /* Common (write) HW watchpoint */

               hw_write   = 0, /* Common (write) HW watchpoint */

               hw_read    = 1, /* Read    HW watchpoint */

               hw_read    = 1, /* Read    HW watchpoint */

               hw_access  = 2, /* Access (read or write) HW watchpoint */

               hw_access  = 2, /* Access (read or write) HW watchpoint */

               hw_execute = 3  /* Execute HW breakpoint */

               hw_execute = 3  /* Execute HW breakpoint */

             };

             };

     These two macros should return 0 for success, non-zero for failure.

     These two macros should return 0 for success, non-zero for failure.

`target_remove_hw_breakpoint (ADDR, SHADOW)'

`target_remove_hw_breakpoint (ADDR, SHADOW)'

`target_insert_hw_breakpoint (ADDR, SHADOW)'

`target_insert_hw_breakpoint (ADDR, SHADOW)'

     Insert or remove a hardware-assisted breakpoint at address ADDR.

     Insert or remove a hardware-assisted breakpoint at address ADDR.

     Returns zero for success, non-zero for failure.  SHADOW is the

     Returns zero for success, non-zero for failure.  SHADOW is the

     real contents of the byte where the breakpoint has been inserted;

     real contents of the byte where the breakpoint has been inserted;

     it is generally not valid when hardware breakpoints are used, but

     it is generally not valid when hardware breakpoints are used, but

     since no other code touches these values, the implementations of

     since no other code touches these values, the implementations of

     the above two macros can use them for their internal purposes.

     the above two macros can use them for their internal purposes.

`target_stopped_data_address ()'

`target_stopped_data_address ()'

     If the inferior has some watchpoint that triggered, return the

     If the inferior has some watchpoint that triggered, return the

     address associated with that watchpoint.  Otherwise, return zero.

     address associated with that watchpoint.  Otherwise, return zero.

`DECR_PC_AFTER_HW_BREAK'

`DECR_PC_AFTER_HW_BREAK'

     If defined, GDB decrements the program counter by the value of

     If defined, GDB decrements the program counter by the value of

     `DECR_PC_AFTER_HW_BREAK' after a hardware break-point.  This

     `DECR_PC_AFTER_HW_BREAK' after a hardware break-point.  This

     overrides the value of `DECR_PC_AFTER_BREAK' when a breakpoint

     overrides the value of `DECR_PC_AFTER_BREAK' when a breakpoint

     that breaks is a hardware-assisted breakpoint.

     that breaks is a hardware-assisted breakpoint.

`HAVE_STEPPABLE_WATCHPOINT'

`HAVE_STEPPABLE_WATCHPOINT'

     If defined to a non-zero value, it is not necessary to disable a

     If defined to a non-zero value, it is not necessary to disable a

     watchpoint to step over it.

     watchpoint to step over it.

`HAVE_NONSTEPPABLE_WATCHPOINT'

`HAVE_NONSTEPPABLE_WATCHPOINT'

     If defined to a non-zero value, GDB should disable a watchpoint to

     If defined to a non-zero value, GDB should disable a watchpoint to

     step the inferior over it.

     step the inferior over it.

`HAVE_CONTINUABLE_WATCHPOINT'

`HAVE_CONTINUABLE_WATCHPOINT'

     If defined to a non-zero value, it is possible to continue the

     If defined to a non-zero value, it is possible to continue the

     inferior after a watchpoint has been hit.

     inferior after a watchpoint has been hit.

`CANNOT_STEP_HW_WATCHPOINTS'

`CANNOT_STEP_HW_WATCHPOINTS'

     If this is defined to a non-zero value, GDB will remove all

     If this is defined to a non-zero value, GDB will remove all

     watchpoints before stepping the inferior.

     watchpoints before stepping the inferior.

`STOPPED_BY_WATCHPOINT (WAIT_STATUS)'

`STOPPED_BY_WATCHPOINT (WAIT_STATUS)'

     Return non-zero if stopped by a watchpoint.  WAIT_STATUS is of the

     Return non-zero if stopped by a watchpoint.  WAIT_STATUS is of the

     type `struct target_waitstatus', defined by `target.h'.

     type `struct target_waitstatus', defined by `target.h'.

x86 Watchpoints

x86 Watchpoints

---------------

---------------

   The 32-bit Intel x86 (a.k.a. ia32) processors feature special debug

   The 32-bit Intel x86 (a.k.a. ia32) processors feature special debug

registers designed to facilitate debugging.  GDB provides a generic

registers designed to facilitate debugging.  GDB provides a generic

library of functions that x86-based ports can use to implement support

library of functions that x86-based ports can use to implement support

for watchpoints and hardware-assisted breakpoints.  This subsection

for watchpoints and hardware-assisted breakpoints.  This subsection

documents the x86 watchpoint facilities in GDB.

documents the x86 watchpoint facilities in GDB.

   To use the generic x86 watchpoint support, a port should do the

   To use the generic x86 watchpoint support, a port should do the

following:

following:

   * Define the macro `I386_USE_GENERIC_WATCHPOINTS' somewhere in the

   * Define the macro `I386_USE_GENERIC_WATCHPOINTS' somewhere in the

     target-dependent headers.

     target-dependent headers.

   * Include the `config/i386/nm-i386.h' header file _after_ defining

   * Include the `config/i386/nm-i386.h' header file _after_ defining

     `I386_USE_GENERIC_WATCHPOINTS'.

     `I386_USE_GENERIC_WATCHPOINTS'.

   * Add `i386-nat.o' to the value of the Make variable `NATDEPFILES'

   * Add `i386-nat.o' to the value of the Make variable `NATDEPFILES'

     (*note NATDEPFILES: Native Debugging.) or `TDEPFILES' (*note

     (*note NATDEPFILES: Native Debugging.) or `TDEPFILES' (*note

     TDEPFILES: Target Architecture Definition.).

     TDEPFILES: Target Architecture Definition.).

   * Provide implementations for the `I386_DR_LOW_*' macros described

   * Provide implementations for the `I386_DR_LOW_*' macros described

     below.  Typically, each macro should call a target-specific

     below.  Typically, each macro should call a target-specific

     function which does the real work.

     function which does the real work.

   The x86 watchpoint support works by maintaining mirror images of the

   The x86 watchpoint support works by maintaining mirror images of the

debug registers.  Values are copied between the mirror images and the

debug registers.  Values are copied between the mirror images and the

real debug registers via a set of macros which each target needs to

real debug registers via a set of macros which each target needs to

provide:

provide:

`I386_DR_LOW_SET_CONTROL (VAL)'

`I386_DR_LOW_SET_CONTROL (VAL)'

     Set the Debug Control (DR7) register to the value VAL.

     Set the Debug Control (DR7) register to the value VAL.

`I386_DR_LOW_SET_ADDR (IDX, ADDR)'

`I386_DR_LOW_SET_ADDR (IDX, ADDR)'

     Put the address ADDR into the debug register number IDX.

     Put the address ADDR into the debug register number IDX.

`I386_DR_LOW_RESET_ADDR (IDX)'

`I386_DR_LOW_RESET_ADDR (IDX)'

     Reset (i.e. zero out) the address stored in the debug register

     Reset (i.e. zero out) the address stored in the debug register

     number IDX.

     number IDX.

`I386_DR_LOW_GET_STATUS'

`I386_DR_LOW_GET_STATUS'

     Return the value of the Debug Status (DR6) register.  This value is

     Return the value of the Debug Status (DR6) register.  This value is

     used immediately after it is returned by `I386_DR_LOW_GET_STATUS',

     used immediately after it is returned by `I386_DR_LOW_GET_STATUS',

     so as to support per-thread status register values.

     so as to support per-thread status register values.

   For each one of the 4 debug registers (whose indices are from 0 to 3)

   For each one of the 4 debug registers (whose indices are from 0 to 3)

that store addresses, a reference count is maintained by GDB, to allow

that store addresses, a reference count is maintained by GDB, to allow

sharing of debug registers by several watchpoints.  This allows users

sharing of debug registers by several watchpoints.  This allows users

to define several watchpoints that watch the same expression, but with

to define several watchpoints that watch the same expression, but with

different conditions and/or commands, without wasting debug registers

different conditions and/or commands, without wasting debug registers

which are in short supply.  GDB maintains the reference counts

which are in short supply.  GDB maintains the reference counts

internally, targets don't have to do anything to use this feature.

internally, targets don't have to do anything to use this feature.

   The x86 debug registers can each watch a region that is 1, 2, or 4

   The x86 debug registers can each watch a region that is 1, 2, or 4

bytes long.  The ia32 architecture requires that each watched region be

bytes long.  The ia32 architecture requires that each watched region be

appropriately aligned: 2-byte region on 2-byte boundary, 4-byte region

appropriately aligned: 2-byte region on 2-byte boundary, 4-byte region

on 4-byte boundary.  However, the x86 watchpoint support in GDB can

on 4-byte boundary.  However, the x86 watchpoint support in GDB can

watch unaligned regions and regions larger than 4 bytes (up to 16

watch unaligned regions and regions larger than 4 bytes (up to 16

bytes) by allocating several debug registers to watch a single region.

bytes) by allocating several debug registers to watch a single region.

This allocation of several registers per a watched region is also done

This allocation of several registers per a watched region is also done

automatically without target code intervention.

automatically without target code intervention.

   The generic x86 watchpoint support provides the following API for the

   The generic x86 watchpoint support provides the following API for the

GDB's application code:

GDB's application code:

`i386_region_ok_for_watchpoint (ADDR, LEN)'

`i386_region_ok_for_watchpoint (ADDR, LEN)'

     The macro `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is set to call this

     The macro `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is set to call this

     function.  It counts the number of debug registers required to

     function.  It counts the number of debug registers required to

     watch a given region, and returns a non-zero value if that number

     watch a given region, and returns a non-zero value if that number

     is less than 4, the number of debug registers available to x86

     is less than 4, the number of debug registers available to x86

     processors.

     processors.

`i386_stopped_data_address (void)'

`i386_stopped_data_address (void)'

     The macros `STOPPED_BY_WATCHPOINT' and

     The macros `STOPPED_BY_WATCHPOINT' and

     `target_stopped_data_address' are set to call this function.  The

     `target_stopped_data_address' are set to call this function.  The

     argument passed to `STOPPED_BY_WATCHPOINT' is ignored.  This

     argument passed to `STOPPED_BY_WATCHPOINT' is ignored.  This

     function examines the breakpoint condition bits in the DR6 Debug

     function examines the breakpoint condition bits in the DR6 Debug

     Status register, as returned by the `I386_DR_LOW_GET_STATUS'

     Status register, as returned by the `I386_DR_LOW_GET_STATUS'

     macro, and returns the address associated with the first bit that

     macro, and returns the address associated with the first bit that

     is set in DR6.

     is set in DR6.

`i386_insert_watchpoint (ADDR, LEN, TYPE)'

`i386_insert_watchpoint (ADDR, LEN, TYPE)'

`i386_remove_watchpoint (ADDR, LEN, TYPE)'

`i386_remove_watchpoint (ADDR, LEN, TYPE)'

     Insert or remove a watchpoint.  The macros

     Insert or remove a watchpoint.  The macros

     `target_insert_watchpoint' and `target_remove_watchpoint' are set

     `target_insert_watchpoint' and `target_remove_watchpoint' are set

     to call these functions.  `i386_insert_watchpoint' first looks for

     to call these functions.  `i386_insert_watchpoint' first looks for

     a debug register which is already set to watch the same region for

     a debug register which is already set to watch the same region for

     the same access types; if found, it just increments the reference

     the same access types; if found, it just increments the reference

     count of that debug register, thus implementing debug register

     count of that debug register, thus implementing debug register

     sharing between watchpoints.  If no such register is found, the

     sharing between watchpoints.  If no such register is found, the

     function looks for a vacant debug register, sets its mirrorred

     function looks for a vacant debug register, sets its mirrorred

     value to ADDR, sets the mirrorred value of DR7 Debug Control

     value to ADDR, sets the mirrorred value of DR7 Debug Control

     register as appropriate for the LEN and TYPE parameters, and then

     register as appropriate for the LEN and TYPE parameters, and then

     passes the new values of the debug register and DR7 to the

     passes the new values of the debug register and DR7 to the

     inferior by calling `I386_DR_LOW_SET_ADDR' and

     inferior by calling `I386_DR_LOW_SET_ADDR' and

     `I386_DR_LOW_SET_CONTROL'.  If more than one debug register is

     `I386_DR_LOW_SET_CONTROL'.  If more than one debug register is

     required to cover the given region, the above process is repeated

     required to cover the given region, the above process is repeated

     for each debug register.

     for each debug register.

     `i386_remove_watchpoint' does the opposite: it resets the address

     `i386_remove_watchpoint' does the opposite: it resets the address

     in the mirrorred value of the debug register and its read/write and

     in the mirrorred value of the debug register and its read/write and

     length bits in the mirrorred value of DR7, then passes these new

     length bits in the mirrorred value of DR7, then passes these new

     values to the inferior via `I386_DR_LOW_RESET_ADDR' and

     values to the inferior via `I386_DR_LOW_RESET_ADDR' and

     `I386_DR_LOW_SET_CONTROL'.  If a register is shared by several

     `I386_DR_LOW_SET_CONTROL'.  If a register is shared by several

     watchpoints, each time a `i386_remove_watchpoint' is called, it

     watchpoints, each time a `i386_remove_watchpoint' is called, it

     decrements the reference count, and only calls

     decrements the reference count, and only calls

     `I386_DR_LOW_RESET_ADDR' and `I386_DR_LOW_SET_CONTROL' when the

     `I386_DR_LOW_RESET_ADDR' and `I386_DR_LOW_SET_CONTROL' when the

     count goes to zero.

     count goes to zero.

`i386_insert_hw_breakpoint (ADDR, SHADOW'

`i386_insert_hw_breakpoint (ADDR, SHADOW'

`i386_remove_hw_breakpoint (ADDR, SHADOW)'

`i386_remove_hw_breakpoint (ADDR, SHADOW)'

     These functions insert and remove hardware-assisted breakpoints.

     These functions insert and remove hardware-assisted breakpoints.

     The macros `target_insert_hw_breakpoint' and

     The macros `target_insert_hw_breakpoint' and

     `target_remove_hw_breakpoint' are set to call these functions.

     `target_remove_hw_breakpoint' are set to call these functions.

     These functions work like `i386_insert_watchpoint' and

     These functions work like `i386_insert_watchpoint' and

     `i386_remove_watchpoint', respectively, except that they set up

     `i386_remove_watchpoint', respectively, except that they set up

     the debug registers to watch instruction execution, and each

     the debug registers to watch instruction execution, and each

     hardware-assisted breakpoint always requires exactly one debug

     hardware-assisted breakpoint always requires exactly one debug

     register.

     register.

`i386_stopped_by_hwbp (void)'

`i386_stopped_by_hwbp (void)'

     This function returns non-zero if the inferior has some watchpoint

     This function returns non-zero if the inferior has some watchpoint

     or hardware breakpoint that triggered.  It works like

     or hardware breakpoint that triggered.  It works like

     `i386_stopped_data_address', except that it doesn't return the

     `i386_stopped_data_address', except that it doesn't return the

     address whose watchpoint triggered.

     address whose watchpoint triggered.

`i386_cleanup_dregs (void)'

`i386_cleanup_dregs (void)'

     This function clears all the reference counts, addresses, and

     This function clears all the reference counts, addresses, and

     control bits in the mirror images of the debug registers.  It

     control bits in the mirror images of the debug registers.  It

     doesn't affect the actual debug registers in the inferior process.

     doesn't affect the actual debug registers in the inferior process.

*Notes:*

*Notes:*

  1. x86 processors support setting watchpoints on I/O reads or writes.

  1. x86 processors support setting watchpoints on I/O reads or writes.

     However, since no target supports this (as of March 2001), and

     However, since no target supports this (as of March 2001), and

     since `enum target_hw_bp_type' doesn't even have an enumeration

     since `enum target_hw_bp_type' doesn't even have an enumeration

     for I/O watchpoints, this feature is not yet available to GDB

     for I/O watchpoints, this feature is not yet available to GDB

     running on x86.

     running on x86.

  2. x86 processors can enable watchpoints locally, for the current task

  2. x86 processors can enable watchpoints locally, for the current task

     only, or globally, for all the tasks.  For each debug register,

     only, or globally, for all the tasks.  For each debug register,

     there's a bit in the DR7 Debug Control register that determines

     there's a bit in the DR7 Debug Control register that determines

     whether the associated address is watched locally or globally.  The

     whether the associated address is watched locally or globally.  The

     current implementation of x86 watchpoint support in GDB always

     current implementation of x86 watchpoint support in GDB always

     sets watchpoints to be locally enabled, since global watchpoints

     sets watchpoints to be locally enabled, since global watchpoints

     might interfere with the underlying OS and are probably

     might interfere with the underlying OS and are probably

     unavailable in many platforms.

     unavailable in many platforms.

File: gdbint.info,  Node: User Interface,  Next: Symbol Handling,  Prev: Algorithms,  Up: Top

File: gdbint.info,  Node: User Interface,  Next: Symbol Handling,  Prev: Algorithms,  Up: Top

User Interface

User Interface

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

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

   GDB has several user interfaces.  Although the command-line interface

   GDB has several user interfaces.  Although the command-line interface

is the most common and most familiar, there are others.

is the most common and most familiar, there are others.

Command Interpreter

Command Interpreter

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

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

   The command interpreter in GDB is fairly simple.  It is designed to

   The command interpreter in GDB is fairly simple.  It is designed to

allow for the set of commands to be augmented dynamically, and also has

allow for the set of commands to be augmented dynamically, and also has

a recursive subcommand capability, where the first argument to a

a recursive subcommand capability, where the first argument to a

command may itself direct a lookup on a different command list.

command may itself direct a lookup on a different command list.

   For instance, the `set' command just starts a lookup on the

   For instance, the `set' command just starts a lookup on the

`setlist' command list, while `set thread' recurses to the

`setlist' command list, while `set thread' recurses to the

`set_thread_cmd_list'.

`set_thread_cmd_list'.

   To add commands in general, use `add_cmd'.  `add_com' adds to the

   To add commands in general, use `add_cmd'.  `add_com' adds to the

main command list, and should be used for those commands.  The usual

main command list, and should be used for those commands.  The usual

place to add commands is in the `_initialize_XYZ' routines at the ends

place to add commands is in the `_initialize_XYZ' routines at the ends

of most source files.

of most source files.

   Before removing commands from the command set it is a good idea to

   Before removing commands from the command set it is a good idea to

deprecate them for some time.  Use `deprecate_cmd' on commands or

deprecate them for some time.  Use `deprecate_cmd' on commands or

aliases to set the deprecated flag.  `deprecate_cmd' takes a `struct

aliases to set the deprecated flag.  `deprecate_cmd' takes a `struct

cmd_list_element' as it's first argument.  You can use the return value

cmd_list_element' as it's first argument.  You can use the return value

from `add_com' or `add_cmd' to deprecate the command immediately after

from `add_com' or `add_cmd' to deprecate the command immediately after

it is created.

it is created.

   The first time a comamnd is used the user will be warned and offered

   The first time a comamnd is used the user will be warned and offered

a replacement (if one exists). Note that the replacement string passed

a replacement (if one exists). Note that the replacement string passed

to `deprecate_cmd' should be the full name of the command, i.e. the

to `deprecate_cmd' should be the full name of the command, i.e. the

entire string the user should type at the command line.

entire string the user should type at the command line.

UI-Independent Output--the `ui_out' Functions

UI-Independent Output--the `ui_out' Functions

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

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

   The `ui_out' functions present an abstraction level for the GDB

   The `ui_out' functions present an abstraction level for the GDB

output code.  They hide the specifics of different user interfaces

output code.  They hide the specifics of different user interfaces

supported by GDB, and thus free the programmer from the need to write

supported by GDB, and thus free the programmer from the need to write

several versions of the same code, one each for every UI, to produce

several versions of the same code, one each for every UI, to produce

output.

output.

Overview and Terminology

Overview and Terminology

------------------------

------------------------

   In general, execution of each GDB command produces some sort of

   In general, execution of each GDB command produces some sort of

output, and can even generate an input request.

output, and can even generate an input request.

   Output can be generated for the following purposes:

   Output can be generated for the following purposes:

   * to display a _result_ of an operation;

   * to display a _result_ of an operation;

   * to convey _info_ or produce side-effects of a requested operation;

   * to convey _info_ or produce side-effects of a requested operation;

   * to provide a _notification_ of an asynchronous event (including

   * to provide a _notification_ of an asynchronous event (including

     progress indication of a prolonged asynchronous operation);

     progress indication of a prolonged asynchronous operation);

   * to display _error messages_ (including warnings);

   * to display _error messages_ (including warnings);

   * to show _debug data_;

   * to show _debug data_;

   * to _query_ or prompt a user for input (a special case).

   * to _query_ or prompt a user for input (a special case).

This section mainly concentrates on how to build result output,

This section mainly concentrates on how to build result output,

although some of it also applies to other kinds of output.

although some of it also applies to other kinds of output.

   Generation of output that displays the results of an operation

   Generation of output that displays the results of an operation

involves one or more of the following:

involves one or more of the following:

   * output of the actual data

   * output of the actual data

   * formatting the output as appropriate for console output, to make it

   * formatting the output as appropriate for console output, to make it

     easily readable by humans

     easily readable by humans

   * machine oriented formatting-a more terse formatting to allow for

   * machine oriented formatting-a more terse formatting to allow for

     easy parsing by programs which read GDB's output

     easy parsing by programs which read GDB's output

   * annotation, whose purpose is to help a GUI (such as GDBTK or

   * annotation, whose purpose is to help a GUI (such as GDBTK or

     Emacs) to identify interesting parts in the output

     Emacs) to identify interesting parts in the output

   The `ui_out' routines take care of the first three aspects.

   The `ui_out' routines take care of the first three aspects.

Annotations are provided by separate annotation routines.  Note that

Annotations are provided by separate annotation routines.  Note that

use of annotations for an interface between a GUI and GDB is deprecated.

use of annotations for an interface between a GUI and GDB is deprecated.

   Output can be in the form of a single item, which we call a "field";

   Output can be in the form of a single item, which we call a "field";

a "list" of fields; or a "table", which is a list of fields with a

a "list" of fields; or a "table", which is a list of fields with a

header.  In a BNF-like form:

header.  In a BNF-like form:

      ::= any single item of data kept by gdb ;;

      ::= any single item of data kept by gdb ;;

      ::= {  } ;;

      ::= {  } ;;

      ::= 
 {  } ;;
        
      ::= 
 {  } ;;
      
      

        

        

      
      

        
     
 ::= {  } ;;
        
     
 ::= {  } ;;
      
      

        

        

      
      

        
      ::=