Subversion Repositories or1k

This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.

INFO-DIR-SECTION Programming & development tools.
START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY

   This file documents the GNU debugger GDB.

   This is the Ninth Edition, April 2001, of `Debugging with GDB: the
GNU Source-Level Debugger' for GDB Version 20010707.

   Copyright (C)
1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "A Sample GDB Session" and "Free Software",
with the Front-Cover texts being "A GNU Manual," and with the
Back-Cover Texts as in (a) below.

   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development."


File: gdb.info,  Node: Built-In 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 by one.  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 by one.  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 treats the use of procedures `INCL' and `EXCL' as an error.


File: gdb.info,  Node: M2 Constants,  Next: M2 Defaults,  Prev: Built-In 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 and C++
     constants: 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' sets 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 prints 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 built-in 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 built-in 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 declared identifier within your 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 searches 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 the C `union' type, which
has no direct analogue in Modula-2.

   The `@' operator (*note Expressions: Expressions.), while available
with 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.

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


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

Chill
-----

   The extensions made to GDB to support Chill only support output from
the GNU Chill compiler.  Other Chill compilers are not currently
supported, and attempting to debug executables produced by them is most
likely to give an error as GDB reads in the executable's symbol table.

   This section covers the Chill related topics and the features of GDB
which support these topics.

* Menu:

* How modes are displayed::        How modes are displayed
* Locations::                        Locations and their accesses
* Values and their Operations:: Values and their Operations
* Chill type and range checks::
* Chill defaults::


File: gdb.info,  Node: How modes are displayed,  Next: Locations,  Up: Chill

How modes are displayed
.......................

   The Chill Datatype- (Mode) support of GDB is directly related with
the functionality of the GNU Chill compiler, and therefore deviates
slightly from the standard specification of the Chill language. The
provided modes are:

`_Discrete modes:_'
        * _Integer Modes_ which are predefined by `BYTE, UBYTE, INT,
          UINT, LONG, ULONG',

        * _Boolean Mode_ which is predefined by `BOOL',

        * _Character Mode_ which is predefined by `CHAR',

        * _Set Mode_ which is displayed by the keyword `SET'.
               (gdb) ptype x
               type = SET (karli = 10, susi = 20, fritzi = 100)
          If the type is an unnumbered set the set element values are
          omitted.

        * _Range Mode_ which is displayed by
               `type = <basemode>(<lower bound> : <upper bound>)'
          where `<lower bound>, <upper bound>' can be of any discrete
          literal expression (e.g. set element names).

`_Powerset Mode:_'
     A Powerset Mode is displayed by the keyword `POWERSET' followed by
     the member mode of the powerset.  The member mode can be any
     discrete mode.
          (gdb) ptype x
          type = POWERSET SET (egon, hugo, otto)

`_Reference Modes:_'
        * _Bound Reference Mode_ which is displayed by the keyword `REF'
          followed by the mode name to which the reference is bound.

        * _Free Reference Mode_ which is displayed by the keyword `PTR'.

`_Procedure mode_'
     The procedure mode is displayed by `type = PROC(<parameter list>)
     <return mode> EXCEPTIONS (<exception list>)'. The `<parameter
     list>' is a list of the parameter modes.  `<return mode>' indicates
     the mode of the result of the procedure if any.  The exceptionlist
     lists all possible exceptions which can be raised by the procedure.

`_Synchronization Modes:_'
        * _Event Mode_ which is displayed by
               `EVENT (<event length>)'
          where `(<event length>)' is optional.

        * _Buffer Mode_ which is displayed by
               `BUFFER (<buffer length>)<buffer element mode>'
          where `(<buffer length>)' is optional.

`_Timing Modes:_'
        * _Duration Mode_ which is predefined by `DURATION'

        * _Absolute Time Mode_ which is predefined by `TIME'

`_Real Modes:_'
     Real Modes are predefined with `REAL' and `LONG_REAL'.

`_String Modes:_'
        * _Character String Mode_ which is displayed by
               `CHARS(<string length>)'
          followed by the keyword `VARYING' if the String Mode is a
          varying mode

        * _Bit String Mode_ which is displayed by
               `BOOLS(<string
               length>)'

`_Array Mode:_'
     The Array Mode is displayed by the keyword `ARRAY(<range>)'
     followed by the element mode (which may in turn be an array mode).
          (gdb) ptype x
          type = ARRAY (1:42)
                    ARRAY (1:20)
                       SET (karli = 10, susi = 20, fritzi = 100)

`_Structure Mode_'
     The Structure mode is displayed by the keyword `STRUCT(<field
     list>)'.  The `<field list>' consists of names and modes of fields
     of the structure.  Variant structures have the keyword `CASE
     <field> OF <variant fields> ESAC' in their field list.  Since the
     current version of the GNU Chill compiler doesn't implement tag
     processing (no runtime checks of variant fields, and therefore no
     debugging info), the output always displays all variant fields.
          (gdb) ptype str
          type = STRUCT (
              as x,
              bs x,
              CASE bs OF
              (karli):
                  cs a
              (ott):
                  ds x
              ESAC
          )


File: gdb.info,  Node: Locations,  Next: Values and their Operations,  Prev: How modes are displayed,  Up: Chill

Locations and their accesses
............................

   A location in Chill is an object which can contain values.

   A value of a location is generally accessed by the (declared) name of
the location.  The output conforms to the specification of values in
Chill programs.  How values are specified is the topic of the next
section, *Note Values and their Operations::.

   The pseudo-location `RESULT' (or `result') can be used to display or
change the result of a currently-active procedure:

     set result := EXPR

This does the same as the Chill action `RESULT EXPR' (which is not
available in GDB).

   Values of reference mode locations are printed by `PTR(<hex value>)'
in case of a free reference mode, and by `(REF <reference mode>)
(<hex-value>)' in case of a bound reference.  `<hex value>' represents
the address where the reference points to.  To access the value of the
location referenced by the pointer, use the dereference operator `->'.

   Values of procedure mode locations are displayed by
     `{ PROC
     (<argument modes> ) <return mode> } <address> <name of procedure
     location>'
   `<argument modes>' is a list of modes according to the parameter
specification of the procedure and `<address>' shows the address of the
entry point.

   Substructures of string mode-, array mode- or structure mode-values
(e.g. array slices, fields of structure locations) are accessed using
certain operations which are described in the next section, *Note
Values and their Operations::.

   A location value may be interpreted as having a different mode using
the location conversion.  This mode conversion is written as `<mode
name>(<location>)'.  The user has to consider that the sizes of the
modes have to be equal otherwise an error occurs.  Furthermore, no range
checking of the location against the destination mode is performed, and
therefore the result can be quite confusing.

     (gdb) print int (s(3 up 4)) XXX TO be filled in !! XXX


File: gdb.info,  Node: Values and their Operations,  Next: Chill type and range checks,  Prev: Locations,  Up: Chill

Values and their Operations
...........................

   Values are used to alter locations, to investigate complex
structures in more detail or to filter relevant information out of a
large amount of data.  There are several (mode dependent) operations
defined which enable such investigations.  These operations are not
only applicable to constant values but also to locations, which can
become quite useful when debugging complex structures.  During parsing
the command line (e.g. evaluating an expression) GDB treats location
names as the values behind these locations.

   This section describes how values have to be specified and which
operations are legal to be used with such values.

`Literal Values'
     Literal values are specified in the same manner as in GNU Chill
     programs.  For detailed specification refer to the GNU Chill
     implementation Manual chapter 1.5.

`Tuple Values'
     A tuple is specified by `<mode name>[<tuple>]', where `<mode
     name>' can be omitted if the mode of the tuple is unambiguous.
     This unambiguity is derived from the context of a evaluated
     expression.  `<tuple>' can be one of the following:

        * _Powerset Tuple_

        * _Array Tuple_

        * _Structure Tuple_ Powerset tuples, array tuples and structure
          tuples are specified in the same manner as in Chill programs
          refer to z200/88 chpt 5.2.5.

`String Element Value'
     A string element value is specified by
          `<string value>(<index>)'
     where `<index>' is a integer expression.  It delivers a character
     value which is equivalent to the character indexed by `<index>' in
     the string.

`String Slice Value'
     A string slice value is specified by `<string value>(<slice
     spec>)', where `<slice spec>' can be either a range of integer
     expressions or specified by `<start expr> up <size>'.  `<size>'
     denotes the number of elements which the slice contains.  The
     delivered value is a string value, which is part of the specified
     string.

`Array Element Values'
     An array element value is specified by `<array value>(<expr>)' and
     delivers a array element value of the mode of the specified array.

`Array Slice Values'
     An array slice is specified by `<array value>(<slice spec>)', where
     `<slice spec>' can be either a range specified by expressions or by
     `<start expr> up <size>'.  `<size>' denotes the number of
     arrayelements the slice contains.  The delivered value is an array
     value which is part of the specified array.

`Structure Field Values'
     A structure field value is derived by `<structure value>.<field
     name>', where `<field name>' indicates the name of a field
     specified in the mode definition of the structure.  The mode of
     the delivered value corresponds to this mode definition in the
     structure definition.

`Procedure Call Value'
     The procedure call value is derived from the return value of the
     procedure(1).

     Values of duration mode locations are represented by `ULONG'
     literals.

     Values of time mode locations appear as
          `TIME(<secs>:<nsecs>)'

`Zero-adic Operator Value'
     The zero-adic operator value is derived from the instance value
     for the current active process.

`Expression Values'
     The value delivered by an expression is the result of the
     evaluation of the specified expression.  If there are error
     conditions (mode incompatibility, etc.) the evaluation of
     expressions is aborted with a corresponding error message.
     Expressions may be parenthesised which causes the evaluation of
     this expression before any other expression which uses the result
     of the parenthesised expression.  The following operators are
     supported by GDB:

    ``OR, ORIF, XOR''
    ``AND, ANDIF''
    ``NOT''
          Logical operators defined over operands of boolean mode.

    ``=, /=''
          Equality and inequality operators defined over all modes.

    ``>, >=''
    ``<, <=''
          Relational operators defined over predefined modes.

    ``+, -''
    ``*, /, MOD, REM''
          Arithmetic operators defined over predefined modes.

    ``-''
          Change sign operator.

    ``//''
          String concatenation operator.

    ``()''
          String repetition operator.

    ``->''
          Referenced location operator which can be used either to take
          the address of a location (`->loc'), or to dereference a
          reference location (`loc->').

    ``OR, XOR''
    ``AND''
    ``NOT''
          Powerset and bitstring operators.

    ``>, >=''
    ``<, <=''
          Powerset inclusion operators.

    ``IN''
          Membership operator.

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

   (1) If a procedure call is used for instance in an expression, then
this procedure is called with all its side effects.  This can lead to
confusing results if used carelessly.


File: gdb.info,  Node: Chill type and range checks,  Next: Chill defaults,  Prev: Values and their Operations,  Up: Chill

Chill type and range checks
...........................

   GDB considers two Chill variables mode equivalent if the sizes of
the two modes are equal.  This rule applies recursively to more complex
datatypes which means that complex modes are treated equivalent if all
element modes (which also can be complex modes like structures, arrays,
etc.) have the same size.

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

   Strong type checks are forced using the GDB command `set check
strong'.  This enforces strong type and range checks on all operations
where Chill constructs are used (expressions, built in functions, etc.)
in respect to the semantics as defined in the z.200 language
specification.

   All checks can be disabled by the GDB command `set check off'.


File: gdb.info,  Node: Chill defaults,  Prev: Chill type and range checks,  Up: Chill

Chill defaults
..............

   If type and range checking are set automatically by GDB, they both
default to `on' whenever the working language changes to Chill.  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 `.ch' sets the working
language to Chill.  *Note Having GDB set the language automatically:
Automatically, for further details.


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

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

   The commands described in this chapter 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 your program executes.  GDB finds it in your
program's symbol table, in the file indicated when you started GDB
(*note Choosing files: File Options.), or by one of the file-management
commands (*note Commands to specify files: Files.).

   Occasionally, you may need to refer to symbols that contain unusual
characters, which GDB ordinarily treats as word delimiters.  The most
frequent case is in referring to static variables in other source files
(*note Program variables: Variables.).  File names are recorded in
object files as debugging symbols, but GDB would ordinarily parse a
typical file name, like `foo.c', as the three words `foo' `.' `c'.  To
allow GDB to recognize `foo.c' as a single symbol, enclose it in single
quotes; for example,

     p 'foo.c'::x

looks up the value of `x' in the scope of the file `foo.c'.

`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 variable, and for a stack local variable prints the
     exact address of the current instantiation of the variable.

`info symbol ADDR'
     Print the name of a symbol which is stored at the address ADDR.
     If no symbol is stored exactly at ADDR, GDB prints the nearest
     symbol and an offset from it:

          (gdb) info symbol 0x54320
          _initialize_vx + 396 in section .text

     This is the opposite of the `info address' command.  You can use
     it to find out the name of a variable or a function given its
     address.

`whatis EXPR'
     Print the data type of expression EXPR.  EXPR is not actually
     evaluated, and any side-effecting operations (such as assignments
     or function calls) inside it do not take place.  *Note
     Expressions: 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 `class
     CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum
     ENUM-TAG'.

`ptype EXPR'
`ptype'
     Print a description of the type of expression EXPR.  `ptype'
     differs from `whatis' by printing a detailed description, instead
     of just the name of the type.

     For example, for this variable declaration:

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

     the two commands give this output:

          (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 names match 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 names include 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 scope ADDR'
     List all the variables local to a particular scope.  This command
     accepts a location--a function name, a source line, or an address
     preceded by a `*', and prints all the variables local to the scope
     defined by that location.  For example:

          (gdb) info scope command_line_handler
          Scope for command_line_handler:
          Symbol rl is an argument at stack/frame offset 8, length 4.
          Symbol linebuffer is in static storage at address 0x150a18, length 4.
          Symbol linelength is in static storage at address 0x150a1c, length 4.
          Symbol p is a local variable in register $esi, length 4.
          Symbol p1 is a local variable in register $ebx, length 4.
          Symbol nline is a local variable in register $edx, length 4.
          Symbol repeat is a local variable at frame offset -8, length 4.

     This command is especially useful for determining what data to
     collect during a "trace experiment", see *Note collect: Tracepoint
     Actions.

`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 your 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.

     Some systems allow individual object files that make up your
     program to be replaced without stopping and restarting your
     program.  For example, in VxWorks you can simply recompile a
     defective object file and keep on running.  If you are running on
     one of these systems, you can allow GDB to reload the symbols for
     automatically relinked modules:

    `set symbol-reloading on'
          Replace symbol definitions for the corresponding source file
          when an object file with a particular name is seen again.

    `set symbol-reloading off'
          Do not replace symbol definitions when encountering object
          files of the same name more than once.  This is the default
          state; if you are not running on a system that permits
          automatic relinking of modules, you should leave
          `symbol-reloading' off, since otherwise GDB may discard
          symbols when linking large programs, that may contain several
          modules (from different directories or libraries) with the
          same name.

    `show symbol-reloading'
          Show the current `on' or `off' setting.

`set opaque-type-resolution on'
     Tell GDB to resolve opaque types.  An opaque type is a type
     declared as a pointer to a `struct', `class', or `union'--for
     example, `struct MyType *'--that is used in one source file
     although the full declaration of `struct MyType' is in another
     source file.  The default is on.

     A change in the setting of this subcommand will not take effect
     until the next time symbols for a file are loaded.

`set opaque-type-resolution off'
     Tell GDB not to resolve opaque types.  In this case, the type is
     printed as follows:
          {<no data fields>}

`show opaque-type-resolution'
     Show whether opaque types are resolved or not.

`maint print symbols FILENAME'
`maint print psymbols FILENAME'
`maint print msymbols 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 `maint print
     symbols', 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 `maint print psymbols' instead, the dump shows information
     about symbols that GDB only knows partially--that is, symbols
     defined in files that GDB has skimmed, but not yet read
     completely.  Finally, `maint print msymbols' dumps just the
     minimal symbol information required for each object file from
     which GDB has read some symbols.  *Note Commands to specify files:
     Files, for a discussion of how GDB reads symbols (in the
     description of `symbol-file').


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

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

   Once you think you have found an error in your 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 your program a signal, restart it at a different
address, or even return prematurely from a function.

* Menu:

* Assignment::                  Assignment to variables
* Jumping::                     Continuing at a different address
* Signaling::                   Giving your 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,  Up: Altering

Assignment to variables
=======================

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

     print x=4

stores the value 4 into the variable `x', and then prints the value of
the assignment expression (which is 4).  *Note Using GDB with Different
Languages: 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: 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, if your program has a variable `width',
you get an error if you try to set a new value with just `set
width=13', because GDB has the command `set width':

     (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'.  In order to actually set
the program's variable `width', use

     (gdb) set var width=47

   Because the `set' command has many subcommands that can conflict
with the names of program variables, it is a good idea to use the `set
variable' command instead of just `set'.  For example, if your program
has a variable `g', you run into problems if you try to set a new value
with just `set g=4', because GDB has the command `set gnutarget',
abbreviated `set g':

     (gdb) whatis g
     type = double
     (gdb) p g
     $1 = 1
     (gdb) set g=4
     (gdb) p g
     $2 = 1
     (gdb) r
     The program being debugged has been started already.
     Start it from the beginning? (y or n) y
     Starting program: /home/smith/cc_progs/a.out
     "/home/smith/cc_progs/a.out": can't open to read symbols:
                                      Invalid bfd target.
     (gdb) show g
     The current BFD target is "=4".

The program variable `g' did not change, and you silently set the
`gnutarget' to an invalid value.  In order to set the variable `g', use

     (gdb) set var g=4

   GDB allows more implicit conversions in assignments than C; you can
freely store an integer value into a pointer variable or vice versa,
and you can convert any structure 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: 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 your 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 stops again
     immediately if there is a breakpoint there.  *Note Printing source
     lines: List, for a description of the different forms of LINESPEC.
     It is common practice to use the `tbreak' command in conjunction
     with `jump'.  *Note Setting breakpoints: Set Breaks.

     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 your program.

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

   On many systems, 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 your program running; it only changes the
address of where it _will_ run when you continue.  For example,

     set $pc = 0x485

makes the next `continue' command or stepping command execute at
address `0x485', rather than at the address where your program stopped.
*Note Continuing and stepping: 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 your program a signal
============================

`signal SIGNAL'
     Resume execution where your program stopped, but immediately give
     it the signal SIGNAL.  SIGNAL can be the name or the number of a
     signal.  For example, on many systems `signal 2' and `signal
     SIGINT' are both ways of sending an interrupt signal.

     Alternatively, if SIGNAL is zero, continue execution without
     giving a signal.  This is useful when your 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.

   Invoking the `signal' command is not the same as invoking the `kill'
utility from the shell.  Sending a signal with `kill' causes GDB to
decide what to do with the signal depending on the signal handling
tables (*note Signals::).  The `signal' command passes the signal
directly to your program.


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 Selecting a frame:
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: Continuing and Stepping.) resumes execution until the
selected stack frame returns naturally.


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

Calling program 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.  If the result is not void, it is printed
and saved in the value history.

   For the A29K, a user-controlled variable `call_scratch_address',
specifies the location of a scratch area to be used when GDB calls a
function in the target.  This is necessary because the usual method of
putting the scratch area on the stack does not work in systems that
have separate instruction and data spaces.


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

Patching programs
=================

   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 opens executable and core files
     for both reading and writing; if you specify `set write off' (the
     default), GDB opens them read-only.

     If you have 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 are opened for
     writing as well as reading.


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

GDB Files
*********

   GDB needs to know the file name of the program to be debugged, both
in order to read its symbol table and in order to start your program.
To debug a core dump of a previous run, you must also tell GDB the name
of the core dump file.

* Menu:

* Files::                       Commands to specify files
* Symbol Errors::               Errors reading symbol files