d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
3821a5a9e4
freebsd-dev/gnu/usr.bin/gdb/doc/gdb.info-4
Paul Richards ea8c7ac7d0 GDB-4.12 from ports with support for shlibs but not the kernel. 
This is a greatly pared down version of the full gdb-4.12, all the
config stuff has been removed and the supporting libraries have
been stripped to a minimum. This is a 1.1.5 only port, I'll do a
more complete port for 2.0 which will have all the config stuff
and will install the gnu support libraries as system libraries like
we do for readline.

There wasn't much point for 1.1.5 since only gdb would use them so I
went for saving space instead. For 2.0 I'll config all the
other gnu tools to use them as well.
1994-06-10 13:42:18 +00:00

1350 lines
49 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This is Info file ./gdb.info, produced by Makeinfo-1.52 from the input
file gdb.texinfo.
START-INFO-DIR-ENTRY
* Gdb:: The GNU debugger.
END-INFO-DIR-ENTRY
This file documents the GNU debugger GDB.
This is Edition 4.09, August 1993, of `Debugging with GDB: the GNU
Source-Level Debugger' for GDB Version 4.11.
Copyright (C) 1988, '89, '90, '91, '92, '93 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 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.

File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data
Registers
=========
You can refer to machine register contents, in expressions, as
variables with names starting with `$'. The names of registers are
different for each machine; use `info registers' to see the names used
on your machine.
`info registers'
Print the names and values of all registers except floating-point
registers (in the selected stack frame).
`info all-registers'
Print the names and values of all registers, including
floating-point registers.
`info registers REGNAME ...'
Print the relativized value of each specified register REGNAME.
rEGNAME may be any register name valid on the machine you are
using, with or without the initial `$'.
GDB has four "standard" register names that are available (in
expressions) on most machines--whenever they do not conflict with an
architecture's canonical mnemonics for registers. The register names
`$pc' and `$sp' are used for the program counter register and the stack
pointer. `$fp' is used for a register that contains a pointer to the
current stack frame, and `$ps' is used for a register that contains the
processor status. For example, you could print the program counter in
hex with
p/x $pc
or print the instruction to be executed next with
x/i $pc
or add four to the stack pointer(1) with
set $sp += 4
Whenever possible, these four standard register names are available
on your machine even though the machine has different canonical
mnemonics, so long as there is no conflict. The `info registers'
command shows the canonical names. For example, on the SPARC, `info
registers' displays the processor status register as `$psr' but you can
also refer to it as `$ps'.
GDB always considers the contents of an ordinary register as an
integer when the register is examined in this way. Some machines have
special registers which can hold nothing but floating point; these
registers are considered to have floating point values. There is no way
to refer to the contents of an ordinary register as floating point value
(although you can *print* it as a floating point value with `print/f
$REGNAME').
Some registers have distinct "raw" and "virtual" data formats. This
means that the data format in which the register contents are saved by
the operating system is not the same one that your program normally
sees. For example, the registers of the 68881 floating point
coprocessor are always saved in "extended" (raw) format, but all C
programs expect to work with "double" (virtual) format. In such cases,
GDB normally works with the virtual format only (the format that makes
sense for your program), but the `info registers' command prints the
data in both formats.
Normally, register values are relative to the selected stack frame
(*note Selecting a frame: Selection.). This means that you get the
value that the register would contain if all stack frames farther in
were exited and their saved registers restored. In order to see the
true contents of hardware registers, you must select the innermost
frame (with `frame 0').
However, GDB must deduce where registers are saved, from the machine
code generated by your compiler. If some registers are not saved, or if
GDB is unable to locate the saved registers, the selected stack frame
will make no difference.
`set rstack_high_address ADDRESS'
On AMD 29000 family processors, registers are saved in a separate
"register stack". There is no way for GDB to determine the extent
of this stack. Normally, GDB just assumes that the stack is "large
enough". This may result in GDB referencing memory locations that
do not exist. If necessary, you can get around this problem by
specifying the ending address of the register stack with the `set
rstack_high_address' command. The argument should be an address,
which you will probably want to precede with `0x' to specify in
hexadecimal.
`show rstack_high_address'
Display the current limit of the register stack, on AMD 29000
family processors.
---------- Footnotes ----------
(1) This is a way of removing one word from the stack, on machines
where stacks grow downward in memory (most machines, nowadays). This
assumes that the innermost stack frame is selected; setting `$sp' is
not allowed when other stack frames are selected. To pop entire frames
off the stack, regardless of machine architecture, use `return'; *note
Returning from a function: Returning..

File: gdb.info, Node: Floating Point Hardware, Prev: Registers, Up: Data
Floating point hardware
=======================
Depending on the host machine architecture, GDB may be able to give
you more information about the status of the floating point hardware.
`info float'
Display hardware-dependent information about the floating point
unit. The exact contents and layout vary depending on the
floating point chip; on some platforms, `info float' is not
available at all.

File: gdb.info, Node: Languages, Next: Symbols, Prev: Data, Up: Top
Using GDB with Different Languages
**********************************
Although programming languages generally have common aspects, they
are rarely expressed in the same manner. For instance, in ANSI C,
dereferencing a pointer `p' is accomplished by `*p', but in Modula-2,
it is accomplished by `p^'. Values can also be represented (and
displayed) differently. Hex numbers in C are written like `0x1ae',
while in Modula-2 they appear as `1AEH'.
Language-specific information is built into GDB for some languages,
allowing you to express operations like the above in your program's
native language, and allowing GDB to output values in a manner
consistent with the syntax of your program's native language. The
language you use to build expressions, called the "working language",
can be selected manually, or GDB can set it automatically.
* Menu:
* Setting:: Switching between source languages
* Show:: Displaying the language
* Checks:: Type and range checks
* Support:: Supported languages

File: gdb.info, Node: Setting, Next: Show, Up: Languages
Switching between source languages
==================================
There are two ways to control the working language--either have GDB
set it automatically, or select it manually yourself. You can use the
`set language' command for either purpose. On startup, GDB defaults to
setting the language automatically.
* Menu:
* Manually:: Setting the working language manually
* Automatically:: Having GDB infer the source language

File: gdb.info, Node: Manually, Next: Automatically, Up: Setting
Setting the working language
----------------------------
If you allow GDB to set the language automatically, expressions are
interpreted the same way in your debugging session and your program.
If you wish, you may set the language manually. To do this, issue
the command `set language LANG', where LANG is the name of a language,
such as `c' or `modula-2'. For a list of the supported languages, type
`set language'.
Setting the language manually prevents GDB from updating the working
language automatically. This can lead to confusion if you try to debug
a program when the working language is not the same as the source
language, when an expression is acceptable to both languages--but means
different things. For instance, if the current source file were
written in C, and GDB was parsing Modula-2, a command such as:
print a = b + c
might not have the effect you intended. In C, this means to add `b'
and `c' and place the result in `a'. The result printed would be the
value of `a'. In Modula-2, this means to compare `a' to the result of
`b+c', yielding a `BOOLEAN' value.

File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting
Having GDB infer the source language
------------------------------------
To have GDB set the working language automatically, use `set
language local' or `set language auto'. GDB then infers the language
that a program was written in by looking at the name of its source
files, and examining their extensions:
`*.mod'
Modula-2 source file
`*.c'
C source file
`*.C'
`*.cc'
C++ source file
This information is recorded for each function or procedure in a
source file. When your program stops in a frame (usually by
encountering a breakpoint), GDB sets the working language to the
language recorded for the function in that frame. If the language for
a frame is unknown (that is, if the function or block corresponding to
the frame was defined in a source file that does not have a recognized
extension), the current working language is not changed, and GDB issues
a warning.
This may not seem necessary for most programs, which are written
entirely in one source language. However, program modules and libraries
written in one source language can be used by a main program written in
a different source language. Using `set language auto' in this case
frees you from having to set the working language manually.

File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages
Displaying the language
=======================
The following commands will help you find out which language is the
working language, and also what language source files were written in.
`show language'
Display the current working language. This is the language you
can use with commands such as `print' to build and compute
expressions that may involve variables in your program.
`info frame'
Among the other information listed here (*note Information about a
frame: Frame Info.) is the source language for this frame. This
is the language that will become the working language if you ever
use an identifier that is in this frame.
`info source'
Among the other information listed here (*note Examining the
Symbol Table: Symbols.) is the source language of this source file.

File: gdb.info, Node: Checks, Next: Support, Prev: Show, Up: Languages
Type and range checking
=======================
*Warning:* In this release, the GDB commands for type and range
checking are included, but they do not yet have any effect. This
section documents the intended facilities.
Some languages are designed to guard you against making seemingly
common errors through a series of compile- and run-time checks. These
include checking the type of arguments to functions and operators, and
making sure mathematical overflows are caught at run time. Checks such
as these help to ensure a program's correctness once it has been
compiled by eliminating type mismatches, and providing active checks
for range errors when your program is running.
GDB can check for conditions like the above if you wish. Although
GDB will not check the statements in your program, it can check
expressions entered directly into GDB for evaluation via the `print'
command, for example. As with the working language, GDB can also
decide whether or not to check automatically based on your program's
source language. *Note Supported languages: Support, for the default
settings of supported languages.
* Menu:
* Type Checking:: An overview of type checking
* Range Checking:: An overview of range checking

File: gdb.info, Node: Type Checking, Next: Range Checking, 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
but
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 further 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 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 treat
range errors in one of three ways: ignore them, always treat them as
errors and abandon the expression, or issue warnings but evaluate the
expression anyway.
A range error can result from numerical overflow, from exceeding an
array index bound, or when you type 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 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 supports C, C++, and Modula-2. 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:
Expressions.) can be used with the constructs of any supported language.
The following sections detail to what degree each source language 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, Up: Support
C and C++
---------
Since C and C++ are so closely related, many features of GDB apply
to both languages. Whenever this is the case, we discuss both languages
together.
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
* Cplus 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, 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'.
* *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:
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 `++'.
For debugging C++, GDB implements a use of `&' beyond what is
allowed in the C++ language itself: you can use `&(&REF)' (or, if
you prefer, simply `&&REF') to examine the address where a C++
reference variable (declared with `&REF') is stored.
`-'
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' and `union' data.
`[]'
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.
`::'
Doubled colons also represent the GDB scope operator (*note
Expressions: Expressions.). Same precedence as `::', above.

File: gdb.info, Node: C Constants, Next: Cplus 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 a letter `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. You can also write
pointers to constants using the C operator `&'.
* Array constants are comma-separated lists surrounded by braces `{'
and `}'; for example, `{1,2,3}' is a three-element array of
integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and
`{&"hi", &"there", &"fred"}' is a three-element array of pointers.

File: gdb.info, Node: Cplus expressions, Next: C Defaults, Prev: C Constants, Up: C
C++ expressions
---------------
GDB expression handling has a number of extensions to interpret a
significant subset of C++ expressions.
*Warning:* Most of these extensions depend on the use of additional
debugging information in the symbol table, and thus require a rich,
extendable object code format. In particular, if your system uses
a.out, MIPS ECOFF, RS/6000 XCOFF, or Sun ELF with stabs extensions
to the symbol table, these facilities are all available. Where
the object code format is standard COFF, on the other hand, most
of the C++ support in GDB will *not* work, nor can it. For the
standard SVr4 debugging format, DWARF in ELF, the standard is
still evolving, so the C++ support in GDB is still fragile; when
this debugging format stabilizes, however, C++ support will also
be available on systems that use it.
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 have 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
Program variables: Variables.).

File: gdb.info, Node: C Defaults, Next: C Checks, Prev: Cplus 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 or
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 or C++ on entering code compiled from a source
file whose name ends with `.c', `.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
-------------------------------
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:
Expressions.

File: gdb.info, Node: Debugging C plus plus, Prev: Debugging C, Up: C
GDB features 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 breakpoint menus help you specify which function definition
you want. *Note Breakpoint menus: 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 Setting breakpoints: Set Breaks.
`catch EXCEPTIONS'
`info catch'
Debug C++ exception handling using these commands. *Note
Breakpoints and exceptions: Exception Handling.
`ptype TYPENAME'
Print inheritance relationships as well as other information for
type TYPENAME. *Note Examining the Symbol Table: 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: Print Settings.
`set print object'
`show print object'
Choose whether to print derived (actual) or declared types of
objects. *Note Print settings: Print Settings.
`set print vtbl'
`show print vtbl'
Control the format for printing virtual function tables. *Note
Print settings: Print Settings.
`Overloaded symbol names'
You can specify a particular definition of an overloaded symbol,
using the same notation that is used to declare such symbols in
C++: type `SYMBOL(TYPES)' rather than just SYMBOL. You can also
use the GDB command-line word completion facilities to list the
available choices, or to finish the type list for you. *Note
Command completion: Completion, for details on how to do this.

File: gdb.info, Node: Modula-2, Prev: C, Up: Support
Modula-2
--------
The extensions made to GDB to support Modula-2 only 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
* Built-In 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: Built-In Func/Proc, 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' and `BITSET' types.
* *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:
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' and `REAL' data.
`^'
Pointer dereferencing. Defined on pointer types.
`NOT'
Boolean negation. Defined on boolean types. Same precedence as
`^'.
`.'
`RECORD' field selector. Defined on `RECORD' data. Same
precedence as `^'.
`[]'
Array indexing. Defined on `ARRAY' data. Same precedence as `^'.
`()'
Procedure argument list. Defined on `PROCEDURE' objects. 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: 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. 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: 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' 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 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 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 the C `union' type, which
has no direct analogue in Modula-2.
The `@' operator (*note Expressions: 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: 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 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.
`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: 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 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, 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 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 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.
`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').
Reference in New Issue View Git Blame Copy Permalink