Info file gdb.info, produced by Makeinfo, -*- Text -*- from input
file gdb-all.texi.

   This file documents the GNU debugger GDB.

   Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of
this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this
manual under the conditions for verbatim copying, provided also that
the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for
modified versions, except that the section entitled "GNU General
Public License" may be included in a translation approved by the
Free Software Foundation instead of in the original English.


File: gdb.info,  Node: Type Checking,  Next: Range Checking,  Prev: Checks,  Up: Checks

An overview of type checking
----------------------------

   Some languages, such as Modula-2, are strongly typed, meaning that
the arguments to operators and functions have to be of the correct
type, otherwise an error occurs.  These checks prevent type mismatch
errors from ever causing any run-time problems.  For example,

     1 + 2 => 3
     error--> 1 + 2.3

   The second example fails because the `CARDINAL' 1 is not
type-compatible with the `REAL' 2.3.

   For expressions you use in GDB commands, you can tell the GDB type
checker to skip checking; to treat any mismatches as errors and
abandon the expression; or only issue warnings when type mismatches
occur, but evaluate the expression anyway.  When you choose the last
of these, GDB evaluates expressions like the second example above,
but also issues a warning.

   Even though you may turn type checking off, other type-based
reasons may prevent GDB from evaluating an expression.  For
instance, GDB does not know how to add an `int' and a `struct foo'. 
These particular type errors have nothing to do with the language in
use, and usually arise from expressions, such as the one described
above, which make little sense to evaluate anyway.

   Each language defines to what degree it is strict about type.  For
instance, both Modula-2 and C require the arguments to arithmetical
operators to be numbers.  In C, enumerated types and pointers can be
represented as numbers, so that they are valid arguments to
mathematical operators.  *Note Supported Languages: Support, for
futher details on specific languages.

   GDB provides some additional commands for controlling the type
checker:

`set check type auto'
     Set type checking on or off based on the current working language.
     *Note Supported Languages: Support, for the default settings
     for each language.

`set check type on'
`set check type off'
     Set type checking on or off, overriding the default setting for
     the current working language.  Issue a warning if the setting
     does not match the language's default.  If any type mismatches
     occur in evaluating an expression while typechecking is on, GDB
     prints a message and aborts evaluation of the expression.

`set check type warn'
     Cause the type checker to issue warnings, but to always attempt
     to evaluate the expression.  Evaluating the expression may
     still be impossible for other reasons.  For example, GDB cannot
     add numbers and structures.

`show type'
     Show the current setting of the type checker, and whether or not
     GDB is setting it automatically.


File: gdb.info,  Node: Range Checking,  Prev: Type Checking,  Up: Checks

An overview of Range Checking
-----------------------------

   In some languages (such as Modula-2), it is an error to exceed the
bounds of a type; this is enforced with run-time checks.  Such range
checking is meant to ensure program correctness by making sure
computations do not overflow, or indices on an array element access
do not exceed the bounds of the array.

   For expressions you use in GDB commands, you can tell GDB to
ignore range errors; to always treat them as errors and abandon the
expression; or to issue warnings when a range error occurs but
evaluate the expression anyway.

   A range error can result from numerical overflow, from exceeding
an array index bound, or when you type in a constant that is not a
member of any type.  Some languages, however, do not treat overflows
as an error.  In many implementations of C, mathematical overflow
causes the result to "wrap around" to lower values--for example, if
M is the largest integer value, and S is the smallest, then

     M + 1 => S

   This, too, is specific to individual languages, and in some cases
specific to individual compilers or machines.  *Note  Supported
Languages: Support, for further details on specific languages.

   GDB provides some additional commands for controlling the range
checker:

`set check range auto'
     Set range checking on or off based on the current working
     language.
     *Note Supported Languages: Support, for the default settings
     for each language.

`set check range on'
`set check range off'
     Set range checking on or off, overriding the default setting for
     the current working language.  A warning is issued if the
     setting does not match the language's default.  If a range
     error occurs, then a message is printed and evaluation of the
     expression is aborted.

`set check range warn'
     Output messages when the GDB range checker detects a range
     error, but attempt to evaluate the expression anyway. 
     Evaluating the expression may still be impossible for other
     reasons, such as accessing memory that the process does not own
     (a typical example from many UNIX systems).

`show range'
     Show the current setting of the range checker, and whether or
     not it is being set automatically by GDB.


File: gdb.info,  Node: Support,  Prev: Checks,  Up: Languages

Supported Languages
===================

   GDB 4.2 supports C, C++, and Modula-2.  The syntax for C and C++
is so closely related that GDB does not distinguish the two.  Some
GDB features may be used in expressions regardless of the language
you use: the GDB `@' and `::' operators, and the `{type}addr'
construct (*note Expressions::.) can be used with the constructs of
any of the supported languages.

   The following sections detail to what degree each of these source
languages is supported by GDB.  These sections are not meant to be
language tutorials or references, but serve only as a reference
guide to what the GDB expression parser will accept, and what input
and output formats should look like for different languages.  There
are many good books written on each of these languages; please look
to these for a language reference or tutorial.

* Menu:

* C::                           C and C++
* Modula-2::                    Modula-2


File: gdb.info,  Node: C,  Next: Modula-2,  Prev: Support,  Up: Support

C and C++
---------

   Since C and C++ are so closely related, GDB does not distinguish
between them when interpreting the expressions recognized in GDB
commands.

   The C++ debugging facilities are jointly implemented by the GNU
C++ compiler and GDB.  Therefore, to debug your C++ code
effectively, you must compile your C++ programs with the GNU C++
compiler, `g++'.

* Menu:

* C Operators::                 C and C++ Operators
* C Constants::                 C and C++ Constants
* Cplusplus expressions::       C++ Expressions
* C Defaults::                  Default settings for C and C++
* C Checks::                    C and C++ Type and Range Checks
* Debugging C::                 GDB and C
* Debugging C plus plus::       Special features for C++


File: gdb.info,  Node: C Operators,  Next: C Constants,  Prev: C,  Up: C

C and C++ Operators
...................

   Operators must be defined on values of specific types.  For
instance, `+' is defined on numbers, but not on structures. 
Operators are often defined on groups of types.  For the purposes of
C and C++, the following definitions hold:

   * *Integral types* include `int' with any of its storage-class
     specifiers, `char', and `enum's.

   * *Floating-point types* include `float' and `double'.

   * *Pointer types* include all types defined as `(TYPE *)'.

   * *Scalar types* include all of the above.

The following operators are supported.  They are listed here in order
of increasing precedence:

`,'
     The comma or sequencing operator.  Expressions in a
     comma-separated list are evaluated from left to right, with the
     result of the entire expression being the last expression
     evaluated.

`='
     Assignment.  The value of an assignment expression is the value
     assigned.  Defined on scalar types.

`OP='
     Used in an expression of the form A OP`=' B, and translated to A
     `=' A OP B.  OP`=' and `=' have the same precendence.  OP is
     any one of the operators `|', `^', `&', `<<', `>>', `+', `-',
     `*', `/', `%'.

`?:'
     The ternary operator.  `A ? B : C' can be thought of as:  if A
     then B else C.  A should be of an integral type.

`||'
     Logical OR.  Defined on integral types.

`&&'
     Logical AND.  Defined on integral types.

`|'
     Bitwise OR.  Defined on integral types.

`^'
     Bitwise exclusive-OR.  Defined on integral types.

`&'
     Bitwise AND.  Defined on integral types.

`==, !='
     Equality and inequality.  Defined on scalar types.  The value of
     these expressions is 0 for false and non-zero for true.

`<, >, <=, >='
     Less than, greater than, less than or equal, greater than or
     equal.  Defined on scalar types.  The value of these
     expressions is 0 for false and non-zero for true.

`<<, >>'
     left shift, and right shift.  Defined on integral types.

`@'
     The GDB "artificial array" operator (*note Expressions::.).

`+, -'
     Addition and subtraction.  Defined on integral types,
     floating-point types and pointer types.

`*, /, %'
     Multiplication, division, and modulus.  Multiplication and
     division are defined on integral and floating-point types. 
     Modulus is defined on integral types.

`++, --'
     Increment and decrement.  When appearing before a variable, the
     operation is performed before the variable is used in an
     expression; when appearing after it, the variable's value is
     used before the operation takes place.

`*'
     Pointer dereferencing.  Defined on pointer types.  Same
     precedence as `++'.

`&'
     Address operator.  Defined on variables.  Same precedence as `++'.

`-'
     Negative.  Defined on integral and floating-point types.  Same
     precedence as `++'.

`!'
     Logical negation.  Defined on integral types.  Same precedence
     as `++'.

`~'
     Bitwise complement operator.  Defined on integral types.  Same
     precedence as `++'.

`., ->'
     Structure member, and pointer-to-structure member.  For
     convenience, GDB regards the two as equivalent, choosing
     whether to dereference a pointer based on the stored type
     information.  Defined on `struct's and `union's.

`[]'
     Array indexing.  `A[I]' is defined as `*(A+I)'.  Same precedence
     as `->'.

`()'
     Function parameter list.  Same precedence as `->'.

`::'
     C++ scope resolution operator.  Defined on `struct', `union',
     and `class' types.

`::'
     The GDB scope operator (*note Expressions::.).  Same precedence
     as `::', above.


File: gdb.info,  Node: C Constants,  Next: Cplusplus expressions,  Prev: C Operators,  Up: C

C and C++ Constants
...................

   GDB allows you to express the constants of C and C++ in the
following ways:

   * Integer constants are a sequence of digits.  Octal constants are
     specified by a leading `0' (ie. zero), and hexadecimal
     constants by a leading `0x' or `0X'.  Constants may also end
     with an `l', specifying that the constant should be treated as
     a `long' value.

   * Floating point constants are a sequence of digits, followed by a
     decimal point, followed by a sequence of digits, and optionally
     followed by an exponent.  An exponent is of the form:
     `e[[+]|-]NNN', where NNN is another sequence of digits.  The
     `+' is optional for positive exponents.

   * Enumerated constants consist of enumerated identifiers, or their
     integral equivalents.

   * Character constants are a single character surrounded by single
     quotes (`''), or a number--the ordinal value of the
     corresponding character (usually its ASCII value).  Within
     quotes, the single character may be represented by a letter or
     by "escape sequences", which are of the form `\NNN', where NNN
     is the octal representation of the character's ordinal value;
     or of the form `\X', where `X' is a predefined special
     character--for example, `\n' for newline.

   * String constants are a sequence of character constants
     surrounded by double quotes (`"').

   * Pointer constants are an integral value.


File: gdb.info,  Node: Cplusplus expressions,  Next: C Defaults,  Prev: C Constants,  Up: C

C++ Expressions
...............

   GDB's expression handling has the following extensions to
interpret a significant subset of C++ expressions:

  1. Member function calls are allowed; you can use expressions like

          count = aml->GetOriginal(x, y)

  2. While a member function is active (in the selected stack frame),
     your expressions have the same namespace available as the
     member function; that is, GDB allows implicit references to the
     class instance pointer `this' following the same rules as C++.

  3. You can call overloaded functions; GDB will resolve the function
     call to the right definition, with one restriction--you must
     use arguments of the type required by the function that you
     want to call.  GDB will not perform conversions requiring
     constructors or user-defined type operators.

  4. GDB understands variables declared as C++ references; you can
     use them in expressions just as you do in C++ source--they are
     automatically dereferenced.

        In the parameter list shown when GDB displays a frame, the
     values of reference variables are not displayed (unlike other
     variables); this avoids clutter, since references are often
     used for large structures.  The *address* of a reference
     variable is always shown, unless you've specified `set print
     address off'.

  5. GDB supports the C++ name resolution operator `::'--your
     expressions can use it just as expressions in your program do. 
     Since one scope may be defined in another, you can use `::'
     repeatedly if necessary, for example in an expression like
     `SCOPE1::SCOPE2::NAME'.  GDB also allows resolving name scope
     by reference to source files, in both C and C++ debugging;
     *note Variables::..


File: gdb.info,  Node: C Defaults,  Next: C Checks,  Prev: Cplusplus expressions,  Up: C

C and C++ Defaults
..................

   If you allow GDB to set type and range checking automatically,
they both default to `off' whenever the working language changes to
C/C++.  This happens regardless of whether you, or GDB, selected the
working language.

   If you allow GDB to set the language automatically, it sets the
working language to C/C++ on entering code compiled from a source
file whose name ends with `.c' or `.cc'.  *Note Having GDB infer the
source language: Automatically, for further details.


File: gdb.info,  Node: C Checks,  Next: Debugging C,  Prev: C Defaults,  Up: C

C and C++ Type and Range Checks
...............................

     *Warning:* in this release, GDB does not yet perform type or
     range checking.

   By default, when GDB parses C or C++ expressions, type checking is
not used.  However, if you turn type checking on, GDB will consider
two variables type equivalent if:

   * The two variables are structured and have the same structure,
     union, or enumerated tag.

   * Two two variables have the same type name, or types that have
     been declared equivalent through `typedef'.

   Range checking, if turned on, is done on mathematical operations. 
Array indices are not checked, since they are often used to index a
pointer that is not itself an array.


File: gdb.info,  Node: Debugging C,  Next: Debugging C plus plus,  Prev: C Checks,  Up: C

GDB and C
.........

   The `set print union' and `show print union' commands apply to the
`union' type.  When set to `on', any `union' that is inside a
`struct' or `class' will also be printed.  Otherwise, it will appear
as `{...}'.

   The `@' operator aids in the debugging of dynamic arrays, formed
with pointers and a memory allocation function.  (*note
Expressions::.)


File: gdb.info,  Node: Debugging C plus plus,  Prev: Debugging C,  Up: C

GDB Commands for C++
....................

   Some GDB commands are particularly useful with C++, and some are
designed specifically for use with C++.  Here is a summary:

`breakpoint menus'
     When you want a breakpoint in a function whose name is
     overloaded, GDB's breakpoint menus help you specify which
     function definition you want.  *Note Breakpoint Menus::.

`rbreak REGEX'
     Setting breakpoints using regular expressions is helpful for
     setting breakpoints on overloaded functions that are not
     members of any special classes.  *Note Set Breaks::.

`catch EXCEPTIONS'
`info catch'
     Debug C++ exception handling using these commands.  *Note
     Exception Handling::.

`ptype TYPENAME'
     Print inheritance relationships as well as other information for
     type TYPENAME.  *Note Symbols::.

`set print demangle'
`show print demangle'
`set print asm-demangle'
`show print asm-demangle'
     Control whether C++ symbols display in their source form, both
     when displaying code as C++ source and when displaying
     disassemblies.  *Note Print Settings::.

`set print object'
`show print object'
     Choose whether to print derived (actual) or declared types of
     objects.  *Note Print Settings::.

`set print vtbl'
`show print vtbl'
     Control the format for printing virtual function tables.  *Note
     Print Settings::.


File: gdb.info,  Node: Modula-2,  Prev: C,  Up: Support

Modula-2
--------

   The extensions made to GDB to support Modula-2 support output from
the GNU Modula-2 compiler (which is currently being developed). 
Other Modula-2 compilers are not currently supported, and attempting
to debug executables produced by them will most likely result in an
error as GDB reads in the executable's symbol table.

* Menu:

* M2 Operators::                Built-in operators
* Builtin Func/Proc::           Built-in Functions and Procedures
* M2 Constants::                Modula-2 Constants
* M2 Defaults::                 Default settings for Modula-2
* Deviations::                  Deviations from standard Modula-2
* M2 Checks::                   Modula-2 Type and Range Checks
* M2 Scope::                    The scope operators `::' and `.'
* GDB/M2::                      GDB and Modula-2


File: gdb.info,  Node: M2 Operators,  Next: Builtin Func/Proc,  Prev: Modula-2,  Up: Modula-2

Operators
.........

   Operators must be defined on values of specific types.  For
instance, `+' is defined on numbers, but not on structures. 
Operators are often defined on groups of types.  For the purposes of
Modula-2, the following definitions hold:

   * *Integral types* consist of `INTEGER', `CARDINAL', and their
     subranges.

   * *Character types* consist of `CHAR' and its subranges.

   * *Floating-point types* consist of `REAL'.

   * *Pointer types* consist of anything declared as `POINTER TO TYPE'.

   * *Scalar types* consist of all of the above.

   * *Set types* consist of `SET's and `BITSET's.

   * *Boolean types* consist of `BOOLEAN'.

The following operators are supported, and appear in order of
increasing
precedence:

`,'
     Function argument or array index separator.

`:='
     Assignment.  The value of VAR `:=' VALUE is VALUE.

`<, >'
     Less than, greater than on integral, floating-point, or
     enumerated types.

`<=, >='
     Less than, greater than, less than or equal to, greater than or
     equal to on integral, floating-point and enumerated types, or
     set inclusion on set types.  Same precedence as `<'.

`=, <>, #'
     Equality and two ways of expressing inequality, valid on scalar
     types.  Same precedence as `<'.  In GDB scripts, only `<>' is
     available for inequality, since `#' conflicts with the script
     comment character.

`IN'
     Set membership.  Defined on set types and the types of their
     members.  Same precedence as `<'.

`OR'
     Boolean disjunction.  Defined on boolean types.

`AND, &'
     Boolean conjuction.  Defined on boolean types.

`@'
     The GDB "artificial array" operator (*note Expressions::.).

`+, -'
     Addition and subtraction on integral and floating-point types,
     or union and difference on set types.

`*'
     Multiplication on integral and floating-point types, or set
     intersection on set types.

`/'
     Division on floating-point types, or symmetric set difference on
     set types.  Same precedence as `*'.

`DIV, MOD'
     Integer division and remainder.  Defined on integral types. 
     Same precedence as `*'.

`-'
     Negative. Defined on `INTEGER's and `REAL's.

`^'
     Pointer dereferencing.  Defined on pointer types.

`NOT'
     Boolean negation.  Defined on boolean types.  Same precedence as
     `^'.

`.'
     `RECORD' field selector.  Defined on `RECORD's.  Same precedence
     as `^'.

`[]'
     Array indexing.  Defined on `ARRAY's.  Same precedence as `^'.

`()'
     Procedure argument list.  Defined on `PROCEDURE's.  Same
     precedence as `^'.

`::, .'
     GDB and Modula-2 scope operators.

     *Warning:* Sets and their operations are not yet supported, so
     GDB will treat the use of the operator `IN', or the use of
     operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>='
     on sets as an error.


File: gdb.info,  Node: Builtin Func/Proc,  Next: M2 Constants,  Prev: M2 Operators,  Up: Modula-2

Built-in Functions and Procedures
.................................

   Modula-2 also makes available several built-in procedures and
functions.  In describing these, the following metavariables are used:

A
     represents an `ARRAY' variable.

C
     represents a `CHAR' constant or variable.

I
     represents a variable or constant of integral type.

M
     represents an identifier that belongs to a set.  Generally used
     in the same function with the metavariable S.  The type of S
     should be `SET OF MTYPE' (where MTYPE is the type of M.

N
     represents a variable or constant of integral or floating-point
     type.

R
     represents a variable or constant of floating-point type.

T
     represents a type.

V
     represents a variable.

X
     represents a variable or constant of one of many types.  See the
     explanation of the function for details.

   All Modula-2 built-in procedures also return a result, described
below.

`ABS(N)'
     Returns the absolute value of N.

`CAP(C)'
     If C is a lower case letter, it returns its upper case
     equivalent, otherwise it returns its argument

`CHR(I)'
     Returns the character whose ordinal value is I.

`DEC(V)'
     Decrements the value in the variable V.  Returns the new value.

`DEC(V,I)'
     Decrements the value in the variable V by I.  Returns the new
     value.

`EXCL(M,S)'
     Removes the element M from the set S.  Returns the new set.

`FLOAT(I)'
     Returns the floating point equivalent of the integer I.

`HIGH(A)'
     Returns the index of the last member of A.

`INC(V)'
     Increments the value in the variable V.  Returns the new value.

`INC(V,I)'
     Increments the value in the variable V by I.  Returns the new
     value.

`INCL(M,S)'
     Adds the element M to the set S if it is not already there. 
     Returns the new set.

`MAX(T)'
     Returns the maximum value of the type T.

`MIN(T)'
     Returns the minimum value of the type T.

`ODD(I)'
     Returns boolean TRUE if I is an odd number.

`ORD(X)'
     Returns the ordinal value of its argument.  For example, the
     ordinal value of a character is its ASCII value (on machines
     supporting the ASCII character set).  X must be of an ordered
     type, which include integral, character and enumerated types.

`SIZE(X)'
     Returns the size of its argument.  X can be a variable or a type.

`TRUNC(R)'
     Returns the integral part of R.

`VAL(T,I)'
     Returns the member of the type T whose ordinal value is I.

     *Warning:*  Sets and their operations are not yet supported, so
     GDB will treat the use of procedures `INCL' and `EXCL' as an
     error.


File: gdb.info,  Node: M2 Constants,  Next: M2 Defaults,  Prev: Builtin Func/Proc,  Up: Modula-2

Constants
.........

   GDB allows you to express the constants of Modula-2 in the
following ways:

   * Integer constants are simply a sequence of digits.  When used in
     an expression, a constant is interpreted to be type-compatible
     with the rest of the expression.  Hexadecimal integers are
     specified by a trailing `H', and octal integers by a trailing
     `B'.

   * Floating point constants appear as a sequence of digits,
     followed by a decimal point and another sequence of digits.  An
    
     optional exponent can then be specified, in the form
     `E[+|-]NNN', where `[+|-]NNN' is the desired exponent.  All of
     the digits of the floating point constant must be valid decimal
     (base 10) digits.

   * Character constants consist of a single character enclosed by a
     pair of like quotes, either single (`'') or double (`"').  They
     may also be expressed by their ordinal value (their ASCII
     value, usually) followed by a `C'.

   * String constants consist of a sequence of characters enclosed by
     a pair of like quotes, either single (`'') or double (`"'). 
     Escape sequences in the style of C are also allowed.  *Note C
     Constants::, for a brief explanation of escape sequences.

   * Enumerated constants consist of an enumerated identifier.

   * Boolean constants consist of the identifiers `TRUE' and `FALSE'.

   * Pointer constants consist of integral values only.

   * Set constants are not yet supported.


File: gdb.info,  Node: M2 Defaults,  Next: Deviations,  Prev: M2 Constants,  Up: Modula-2

Modula-2 Defaults
.................

   If type and range checking are set automatically by GDB, they both
default to `on' whenever the working language changes to Modula-2. 
This happens regardless of whether you, or GDB, selected the working
language.

   If you allow GDB to set the language automatically, then entering
code compiled from a file whose name ends with `.mod' will set the
working language to Modula-2. *Note Having GDB set the language
automatically:
Automatically,
for further details.


File: gdb.info,  Node: Deviations,  Next: M2 Checks,  Prev: M2 Defaults,  Up: Modula-2

Deviations from Standard Modula-2
.................................

   A few changes have been made to make Modula-2 programs easier to
debug.  This is done primarily via loosening its type strictness:

   * Unlike in standard Modula-2, pointer constants can be formed by
     integers.  This allows you to modify pointer variables during
     debugging.  (In standard Modula-2, the actual address contained
     in a pointer variable is hidden from you; it can only be
     modified through direct assignment to another pointer variable
     or expression that returned a pointer.)

   * C escape sequences can be used in strings and characters to
     represent non-printable characters.  GDB will print out strings
     with these escape sequences embedded.  Single non-printable
     characters are printed using the `CHR(NNN)' format.

   * The assignment operator (`:=') returns the value of its
     right-hand argument.

   * All builtin procedures both modify *and* return their argument.


File: gdb.info,  Node: M2 Checks,  Next: M2 Scope,  Prev: Deviations,  Up: Modula-2

Modula-2 Type and Range Checks
..............................

     *Warning:* in this release, GDB does not yet perform type or
     range checking.

   GDB considers two Modula-2 variables type equivalent if:

   * They are of types that have been declared equivalent via a `TYPE
     T1 = T2' statement

   * They have been declared on the same line.  (Note:  This is true
     of the GNU Modula-2 compiler, but it may not be true of other
     compilers.)

   As long as type checking is enabled, any attempt to combine
variables whose types are not equivalent is an error.

   Range checking is done on all mathematical operations, assignment,
array index bounds, and all builtin functions and procedures.


File: gdb.info,  Node: M2 Scope,  Next: GDB/M2,  Prev: M2 Checks,  Up: Modula-2

The scope operators `::' and `.'
................................

   There are a few subtle differences between the Modula-2 scope
operator (`.') and the GDB scope operator (`::').  The two have
similar
syntax:


     MODULE . ID
     SCOPE :: ID

where SCOPE is the name of a module or a procedure, MODULE the name
of a module, and ID is any delcared identifier within the program,
except another module.

   Using the `::' operator makes GDB search the scope specified by
SCOPE for the identifier ID.  If it is not found in the specified
scope, then GDB will search all scopes enclosing the one specified
by SCOPE.

   Using the `.' operator makes GDB search the current scope for the
identifier specified by ID that was imported from the definition
module specified by MODULE.  With this operator, it is an error if
the identifier ID was not imported from definition module MODULE, or
if ID is not an identifier in MODULE.


File: gdb.info,  Node: GDB/M2,  Prev: M2 Scope,  Up: Modula-2

GDB and Modula-2
................

   Some GDB commands have little use when debugging Modula-2 programs.
Five subcommands of `set print' and `show print' apply specifically
to C and C++: `vtbl', `demangle', `asm-demangle', `object', and
`union'.  The first four apply to C++, and the last to C's `union'
type, which has no direct analogue in Modula-2.

   The `@' operator (*note Expressions::.), while available while
using any language, is not useful with Modula-2.  Its intent is to
aid the debugging of "dynamic arrays", which cannot be created in
Modula-2 as they can in C or C++.  However, because an address can
be
specified by an integral constant, the construct `{TYPE}ADREXP' is
still useful.  (*note Expressions::.)

   In GDB scripts, the Modula-2 inequality operator `#' is
interpreted as the beginning of a comment.  Use `<>' instead.


File: gdb.info,  Node: Symbols,  Next: Altering,  Prev: Languages,  Up: Top

Examining the Symbol Table
**************************

   The commands described in this section allow you to inquire about
the symbols (names of variables, functions and types) defined in
your program.  This information is inherent in the text of your
program and does not change as the program executes.  GDB finds it
in
your program's symbol table, in the file indicated when you started
GDB (*note File Options::.), or by one of the file-management
commands (*note Files::.).

`info address SYMBOL'
     Describe where the data for SYMBOL is stored.  For a register
     variable, this says which register it is kept in.  For a
     non-register local variable, this prints the stack-frame offset
     at which the variable is always stored.

     Note the contrast with `print &SYMBOL', which does not work at
     all for a register variables, and for a stack local variable
     prints the exact address of the current instantiation of the
     variable.

`whatis EXP'
     Print the data type of expression EXP.  EXP is not actually
     evaluated, and any side-effecting operations (such as
     assignments or function calls) inside it do not take place. 
    
     *Note Expressions::.

`whatis'
     Print the data type of `$', the last value in the value history.

`ptype TYPENAME'
     Print a description of data type TYPENAME.  TYPENAME may be the
     name of a type, or for C code it may have the form `struct
     STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'.

`ptype EXP'
`ptype'
     Print a description of the type of expression EXP.  `ptype'
     differs from `whatis' by printing a detailed description,
     instead of just the name of the type.  For example, if your
     program declares a variable as

          struct complex {double real; double imag;} v;

     compare the output of the two commands:

          (gdb) whatis v
          type = struct complex
          (gdb) ptype v
          type = struct complex {
              double real;
              double imag;
          }

     As with `whatis', using `ptype' without an argument refers to
     the type of `$', the last value in the value history.

`info types REGEXP'
`info types'
     Print a brief description of all types whose name matches REGEXP
     (or all types in your program, if you supply no argument). 
     Each complete typename is matched as though it were a complete
     line; thus, `i type value' gives information on all types in
     your program whose name includes the string `value', but `i
     type ^value$' gives information only on types whose complete
     name is `value'.

     This command differs from `ptype' in two ways: first, like
     `whatis', it does not print a detailed description; second, it
     lists all source files where a type is defined.

`info source'
     Show the name of the current source file--that is, the source
     file for the function containing the current point of
     execution--and the language it was written in.

`info sources'
     Print the names of all source files in the program for which
     there is debugging information, organized into two lists: files
     whose symbols have already been read, and files whose symbols
     will be read when needed.

`info functions'
     Print the names and data types of all defined functions.

`info functions REGEXP'
     Print the names and data types of all defined functions whose
     names contain a match for regular expression REGEXP.  Thus,
     `info fun step' finds all functions whose names include `step';
     `info fun ^step' finds those whose names start with `step'.

`info variables'
     Print the names and data types of all variables that are
     declared outside of functions (i.e., excluding local variables).

`info variables REGEXP'
     Print the names and data types of all variables (except for
     local variables) whose names contain a match for regular
     expression REGEXP.

`printsyms FILENAME'
`printpsyms FILENAME'
     Write a dump of debugging symbol data into the file FILENAME. 
     These commands are used to debug the GDB symbol-reading code. 
     Only symbols with debugging data are included.  If you use
     `printsyms', GDB includes all the symbols for which it has
     already collected full details: that is, FILENAME reflects
     symbols for only those files whose symbols GDB has read.  You
     can use the command `info sources' to find out which files
     these are.  If you use `printpsyms', the dump also shows
     information about symbols that GDB only knows partially--that
     is, symbols defined in files that GDB has skimmed, but not yet
     read completely.  The description of `symbol-file' describes
     how GDB reads symbols; both commands are described under *Note
     Files::.


File: gdb.info,  Node: Altering,  Next: GDB Files,  Prev: Symbols,  Up: Top

Altering Execution
******************

   Once you think you have found an error in the program, you might
want to find out for certain whether correcting the apparent error
would lead to correct results in the rest of the run.  You can find
the answer by experiment, using the GDB features for altering
execution of the program.

   For example, you can store new values into variables or memory
locations, give the program a signal, restart it at a different
address, or even return prematurely from a function to its caller.

* Menu:

* Assignment::                  Assignment to Variables
* Jumping::                     Continuing at a Different Address
* Signaling::                   Giving the Program a Signal
* Returning::                   Returning from a Function
* Calling::                     Calling your Program's Functions
* Patching::                    Patching your Program


File: gdb.info,  Node: Assignment,  Next: Jumping,  Prev: Altering,  Up: Altering

Assignment to Variables
=======================

   To alter the value of a variable, evaluate an assignment expression.
*Note Expressions::.  For example,

     print x=4

would store the value 4 into the variable `x', and then print the
value
of the assignment expression (which is 4).  *Note Languages::, for
more information on operators in supported languages.

   If you are not interested in seeing the value of the assignment,
use
the `set' command instead of the `print' command.  `set' is really
the same as `print' except that the expression's value is not
printed and is not put in the value history (*note Value
History::.).  The expression is evaluated only for its effects.

   If the beginning of the argument string of the `set' command
appears
identical to a `set' subcommand, use the `set variable' command
instead of just `set'.  This command is identical to `set' except
for its lack of subcommands.  For example, a program might well have
a variable `width'--which leads to an error if we try to set a new
value with just `set width=13', as we might if `set width' didn't
happen to be a GDB command:

     (gdb) whatis width
     type = double
     (gdb) p width
     $4 = 13
     (gdb) set width=47
     Invalid syntax in expression.

The invalid expression, of course, is `=47'.  What we can do in order
to actually set our program's variable `width' is

     (gdb) set var width=47

   GDB allows more implicit conversions in assignments than C does;
you can freely store an integer value into a pointer variable or
vice
versa, and any structure can be converted to any other structure
that is the same length or shorter.

   To store values into arbitrary places in memory, use the `{...}'
construct to generate a value of specified type at a specified
address (*note Expressions::.).  For example, `{int}0x83040' refers
to memory location `0x83040' as an integer (which implies a certain
size and representation in memory), and

     set {int}0x83040 = 4

stores the value 4 into that memory location.


File: gdb.info,  Node: Jumping,  Next: Signaling,  Prev: Assignment,  Up: Altering

Continuing at a Different Address
=================================

   Ordinarily, when you continue the program, you do so at the place
where it stopped, with the `continue' command.  You can instead
continue at an address of your own choosing, with the following
commands:

`jump LINESPEC'
     Resume execution at line LINESPEC.  Execution will stop
     immediately if there is a breakpoint there.  *Note List:: for a
     description of the different forms of LINESPEC.

     The `jump' command does not change the current stack frame, or
     the stack pointer, or the contents of any memory location or
     any register other than the program counter.  If line LINESPEC
     is in a different function from the one currently executing,
     the results may be bizarre if the two functions expect
     different patterns of arguments or of local variables.  For
     this
     reason, the `jump' command requests confirmation if the
     specified line is not in the function currently executing. 
     However, even bizarre results are predictable if you are well
     acquainted with the machine-language code of the program.

`jump *ADDRESS'
     Resume execution at the instruction at address ADDRESS.

   You can get much the same effect as the `jump' command by storing
a new value into the register `$pc'.  The difference is that this
does not start the program running; it only changes the address
where it *will* run when it is continued.  For example,

     set $pc = 0x485

causes the next `continue' command or stepping command to execute at
address 0x485, rather than at the address where the program stopped.
*Note Continuing and Stepping::.

   The most common occasion to use the `jump' command is to back up,
perhaps with more breakpoints set, over a portion of a program that
has already executed, in order to examine its execution in more
detail.


File: gdb.info,  Node: Signaling,  Next: Returning,  Prev: Jumping,  Up: Altering

Giving the Program a Signal
===========================

`signal SIGNALNUM'
     Resume execution where the program stopped, but give it
     immediately the signal number SIGNALNUM.

     Alternatively, if SIGNALNUM is zero, continue execution without
     giving a signal.  This is useful when the program stopped on
     account of a signal and would ordinary see the signal when
     resumed with the `continue' command; `signal 0' causes it to
     resume without a signal.

     `signal' does not repeat when you press RET a second time after
     executing the command.


File: gdb.info,  Node: Returning,  Next: Calling,  Prev: Signaling,  Up: Altering

Returning from a Function
=========================

`return'
`return EXPRESSION'
     You can cancel execution of a function call with the `return'
     command.  If you give an EXPRESSION argument, its value is used
     as the function's return value.

   When you use `return', GDB discards the selected stack frame (and
all frames within it).  You can think of this as making the
discarded frame return prematurely.  If you wish to specify a value
to be returned, give that value as the argument to `return'.

   This pops the selected stack frame (*note Selection::.), and any
other frames inside of it, leaving its caller as the innermost
remaining frame.  That frame becomes selected.  The specified value
is stored in the registers used for returning values of functions.

   The `return' command does not resume execution; it leaves the
program stopped in the state that would exist if the function had
just returned.  In contrast, the `finish' command (*note Continuing
and Stepping::.) resumes execution until the selected stack frame
returns naturally.


File: gdb.info,  Node: Calling,  Next: Patching,  Prev: Returning,  Up: Altering

Calling your Program's Functions
================================

`call EXPR'
     Evaluate the expression EXPR without displaying `void' returned
     values.

   You can use this variant of the `print' command if you want to
execute a function from your program, but without cluttering the
output with `void' returned values.  The result is printed and saved
in the value history, if it is not void.


File: gdb.info,  Node: Patching,  Prev: Calling,  Up: Altering

Patching your Program
=====================

   By default, GDB opens the file containing your program's
executable code (or the corefile) read-only.  This prevents
accidental
alterations to machine code; but it also prevents you from
intentionally patching your program's binary.

   If you'd like to be able to patch the binary, you can specify that
explicitly with the `set write' command.  For example, you might
want to turn on internal debugging flags, or even to make emergency
repairs.

`set write on'
`set write off'
     If you specify `set write on', GDB will open executable and core
     files for both reading and writing; if you specify `set write
     off' (the default), GDB will open them read-only.

     If you've already loaded a file, you must load it again (using
     the `exec-file' or `core-file' command) after changing `set
     write', for your new setting to take effect.

`show write'
     Display whether executable files and core files will be opened
     for writing as well as reading.


File: gdb.info,  Node: GDB Files,  Next: Targets,  Prev: Altering,  Up: Top

GDB's Files
***********

* Menu:

* Files::                       Commands to Specify Files
* Symbol Errors::               Errors Reading Symbol Files

