darling-gdb/gdb/doc/gdb.data-m4

_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
_dnl__ This file is part of the source for the GDB manual.
@c M4 FRAGMENT: $Id$
@node Data, Symbols, Source, Top
@chapter Examining Data

@cindex printing data
@cindex examining data
@kindex print
@kindex inspect
@c "inspect" isn't quite a synonym if you're using Epoch, which we don't
@c document because it's nonstandard...  Under Epoch it displays in a
@c different window or something like that.
The usual way to examine data in your program is with the @code{print}
command (abbreviated @code{p}), or its synonym @code{inspect}.  It
evaluates and prints the value of any valid expression of the language
the program is written in (for now, C or C++).  You type

@example
print @var{exp}
@end example

@noindent
where @var{exp} is any valid expression (in the source language), and
the value of @var{exp} is printed in a format appropriate to its data
type.

A more low-level way of examining data is with the @code{x} command.
It examines data in memory at a specified address and prints it in a
specified format.  @xref{Memory}.

@menu
* Expressions::			Expressions
* Variables::			Program Variables
* Arrays::			Artificial Arrays
* Output formats::		Output formats
* Memory::			Examining Memory
* Auto Display::		Automatic Display
* Print Settings::		Print Settings
* Value History::		Value History
* Convenience Vars::		Convenience Variables
* Registers::			Registers
* Floating Point Hardware::	Floating Point Hardware
@end menu

@node Expressions, Variables, Data, Data
@section Expressions

@cindex expressions
@code{print} and many other _GDBN__ commands accept an expression and
compute its value.  Any kind of constant, variable or operator defined
by the programming language you are using is legal in an expression in
_GDBN__.  This includes conditional expressions, function calls, casts
and string constants.  It unfortunately does not include symbols defined
by preprocessor @code{#define} commands, or C++ expressions involving
@samp{::}, the name resolution operator.
@c FIXME: actually C++ a::b works except in obscure circumstances where it
@c FIXME...can conflict with GDB's own name scope resolution.

Casts are supported in all languages, not just in C, because it is so
useful to cast a number into a pointer so as to examine a structure
at that address in memory.

_GDBN__ supports three kinds of operator in addition to those of programming
languages:

@table @code
@item @@
@samp{@@} is a binary operator for treating parts of memory as arrays.
@xref{Arrays}, for more information.

@item ::
@samp{::} allows you to specify a variable in terms of the file or
function where it is defined.  @xref{Variables}.

@item @{@var{type}@} @var{addr}
Refers to an object of type @var{type} stored at address @var{addr} in
memory.  @var{addr} may be any expression whose value is an integer or
pointer (but parentheses are required around binary operators, just as in
a cast).  This construct is allowed regardless of what kind of data is
normally supposed to reside at @var{addr}.@refill
@end table

@node Variables, Arrays, Expressions, Data
@section Program Variables

The most common kind of expression to use is the name of a variable
in your program.

Variables in expressions are understood in the selected stack frame
(@pxref{Selection}); they must either be global (or static) or be visible
according to the scope rules of the programming language from the point of
execution in that frame.  This means that in the function

@example
foo (a)
     int a;
@{
  bar (a);
  @{
    int b = test ();
    bar (b);
  @}
@}
@end example

@noindent
the variable @code{a} is usable whenever the program is executing
within the function @code{foo}, but the variable @code{b} is visible
only while the program is executing inside the block in which @code{b}
is declared.

@cindex variable name conflict
There is an exception: you can refer to a variable or function whose
scope is a single source file even if the current execution point is not
in this file.  But it is possible to have more than one such variable or
function with the same name (in different source files).  If that happens,
referring to that name has unpredictable effects.  If you wish, you can
specify a variable in a particular file, using the colon-colon notation:

@cindex colon-colon
@kindex ::
@example
@var{file}::@var{variable}
@end example

@noindent
Here @var{file} is the name of the source file whose variable you want.

@cindex C++ name resolution
This use of @samp{::} is very rarely in conflict with the very similar
use of the same notation in C++.  _GDBN__ also supports use of the C++
name resolution operator in _GDBN__ expressions.

@node Arrays, Output formats, Variables, Data
@section Artificial Arrays

@cindex artificial array
@kindex @@
It is often useful to print out several successive objects of the
same type in memory; a section of an array, or an array of
dynamically determined size for which only a pointer exists in the
program.

This can be done by constructing an @dfn{artificial array} with the
binary operator @samp{@@}.  The left operand of @samp{@@} should be
the first element of the desired array, as an individual object.
The right operand should be the desired length of the array.  The result is
an array value whose elements are all of the type of the left argument.
The first element is actually the left argument; the second element
comes from bytes of memory immediately following those that hold the
first element, and so on.  Here is an example.  If a program says

@example
int *array = (int *) malloc (len * sizeof (int));
@end example

@noindent
you can print the contents of @code{array} with

@example
p *array@@len
@end example

The left operand of @samp{@@} must reside in memory.  Array values made
with @samp{@@} in this way behave just like other arrays in terms of
subscripting, and are coerced to pointers when used in expressions.
Artificial arrays most often appear in expressions via the value history
(@pxref{Value History}), after printing one out.)

@node Output formats, Memory, Arrays, Data
@section Output formats

@cindex formatted output
@cindex output formats
By default, _GDBN__ prints a value according to its data type.  Sometimes
this is not what you want.  For example, you might want to print a number
in hex, or a pointer in decimal.  Or you might want to view data in memory
at a certain address as a character string or as an instruction.  To do
these things, specify an @dfn{output format} when you print a value.

The simplest use of output formats is to say how to print a value
already computed.  This is done by starting the arguments of the
@code{print} command with a slash and a format letter.  The format
letters supported are:

@table @code
@item x
Regard the bits of the value as an integer, and print the integer in
hexadecimal.

@item d
Print as integer in signed decimal.

@item u
Print as integer in unsigned decimal.

@item o
Print as integer in octal.

@item t
Print as integer in binary.  The letter @samp{t} stands for ``two''.

@item a
Print as an address, both absolute in hex and as an offset from the
nearest preceding symbol.  This format can be used to discover where (in
what function) an unknown address is located:
@example
(_GDBP__) p/a 0x54320
_0__$3 = 0x54320 <_initialize_vx+396>_1__
@end example


@item c
Regard as an integer and print it as a character constant.

@item f
Regard the bits of the value as a floating point number and print
using typical floating point syntax.
@end table

For example, to print the program counter in hex (@pxref{Registers}), type

@example
p/x $pc
@end example

@noindent
Note that no space is required before the slash; this is because command
names in _GDBN__ cannot contain a slash.

To reprint the last value in the value history with a different format,
you can use the @code{print} command with just a format and no
expression.  For example, @samp{p/x} reprints the last value in hex.

@node Memory, Auto Display, Output formats, Data
@section Examining Memory

@cindex examining memory
@table @code
@kindex x
@item x/@var{nfu} @var{expr}
The command @code{x} (for `examine') can be used to examine memory
without being constrained by your program's data types.  You can specify
the unit size @var{u} of memory to inspect, and a repeat count @var{n} of how
many of those units to display.  @code{x} understands the formats
@var{f} used by @code{print}; two additional formats, @samp{s} (string)
and @samp{i} (machine instruction) can be used without specifying a unit
size.
@end table

For example, @samp{x/3uh 0x54320} is a request to display three halfwords
(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
starting at address @code{0x54320}.  @samp{x/4xw $sp} prints the four
words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
@pxref{Registers}) in hexadecimal (@samp{x}).

Since the letters indicating unit sizes are all distinct from the
letters specifying output formats, you don't have to remember whether
unit size or format comes first; either order will work.  The output
specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.

After the format specification, you supply an expression for the address
where _GDBN__ is to begin reading from memory.  The expression need not
have a pointer value (though it may); it is always interpreted as an
integer address of a byte of memory.  @xref{Expressions} for more
information on expressions.

These are the memory units @var{u} you can specify with the @code{x}
command:

@table @code
@item b
Examine individual bytes.

@item h
Examine halfwords (two bytes each).

@item w
Examine words (four bytes each).

@cindex word
Many assemblers and cpu designers still use `word' for a 16-bit quantity,
as a holdover from specific predecessor machines of the 1970's that really
did use two-byte words.  But more generally the term `word' has always
referred to the size of quantity that a machine normally operates on and
stores in its registers.  This is 32 bits for all the machines that _GDBN__
runs on.

@item g
Examine giant words (8 bytes).
@end table

You can combine these unit specifications with any of the formats
described for @code{print}.  @xref{Output formats}.

@code{x} has two additional output specifications which derive the unit
size from the data inspected:

@table @code
@item s
Print a null-terminated string of characters.  Any explicitly specified
unit size is ignored; instead, the unit is however many bytes it takes
to reach a null character (including the null character).

@item i
Print a machine instruction in assembler syntax (or nearly).  Any
specified unit size is ignored; the number of bytes in an instruction
varies depending on the type of machine, the opcode and the addressing
modes used.  The command @code{disassemble} gives an alternative way of
inspecting machine instructions.  @xref{Machine Code}.
@end table

If you omit either the format @var{f} or the unit size @var{u}, @code{x}
will use the same one that was used last.  If you don't use any letters
or digits after the slash, you can omit the slash as well.

You can also omit the address to examine.  Then the address used is just
after the last unit examined.  This is why string and instruction
formats actually compute a unit-size based on the data: so that the next
string or instruction examined will start in the right place.  

When the @code{print} command shows a value that resides in memory,
@code{print} also sets the default address for the @code{x} command.
@code{info line} also sets the default for @code{x}, to the address of
the start of the machine code for the specified line (@pxref{Machine
Code}), and @code{info breakpoints} sets it to the address of the last
breakpoint listed (@pxref{Set Breaks}).

When you use @key{RET} to repeat an @code{x} command, the address
specified previously (if any) is ignored, so that the repeated command
examines the successive locations in memory rather than the same ones.

You can examine several consecutive units of memory with one command by
writing a repeat-count after the slash (before the format letters, if
any).  Omitting the repeat count @var{n} displays one unit of the
appropriate size.  The repeat count must be a decimal integer.  It has
the same effect as repeating the @code{x} command @var{n} times except
that the output may be more compact, with several units per line.  For
example,

@example
x/10i $pc
@end example

@noindent
prints ten instructions starting with the one to be executed next in the
selected frame.  After doing this, you could print a further seven
instructions with

@example
x/7
@end example

@noindent
---where the format and address are allowed to default.

@kindex $_
@kindex $__
The addresses and contents printed by the @code{x} command are not put
in the value history because there is often too much of them and they
would get in the way.  Instead, _GDBN__ makes these values available for
subsequent use in expressions as values of the convenience variables
@code{$_} and @code{$__}.  After an @code{x} command, the last address
examined is available for use in expressions in the convenience variable
@code{$_}.  The contents of that address, as examined, are available in
the convenience variable @code{$__}.

If the @code{x} command has a repeat count, the address and contents saved
are from the last memory unit printed; this is not the same as the last
address printed if several units were printed on the last line of output.

@node Auto Display, Print Settings, Memory, Data
@section Automatic Display
@cindex automatic display
@cindex display of expressions

If you find that you want to print the value of an expression frequently
(to see how it changes), you might want to add it to the @dfn{automatic
display list} so that _GDBN__ will print its value each time the program stops.
Each expression added to the list is given a number to identify it;
to remove an expression from the list, you specify that number.
The automatic display looks like this:

@example
2: foo = 38
3: bar[5] = (struct hack *) 0x3804
@end example

@noindent
showing item numbers, expressions and their current values.  As with
displays you request manually using @code{x} or @code{print}, you can
specify the output format you prefer; in fact, @code{display} decides
whether to use @code{print} or @code{x} depending on how elaborate your
format specification is---it uses @code{x} if you specify a unit size,
or one of the two formats (@samp{i} and @samp{s}) that are only
supported by @code{x}; otherwise it uses @code{print}.

@table @code
@item display @var{exp}
@kindex display
Add the expression @var{exp} to the list of expressions to display
each time the program stops.  @xref{Expressions}.

@code{display} will not repeat if you press @key{RET} again after using it.

@item display/@var{fmt} @var{exp}
For @var{fmt} specifying only a display format and not a size or
count, add the expression @var{exp} to the auto-display list but
arranges to display it each time in the specified format @var{fmt}.
@xref{Output formats}.

@item display/@var{fmt} @var{addr}
For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
number of units, add the expression @var{addr} as a memory address to
be examined each time the program stops.  Examining means in effect
doing @samp{x/@var{fmt} @var{addr}}.  @xref{Memory}.
@end table

For example, @samp{display/i $pc} can be helpful, to see the machine
instruction about to be executed each time execution stops (@samp{$pc}
is a common name for the program counter; @pxref{Registers}).

@table @code
@item undisplay @var{dnums}@dots{}
@itemx delete display @var{dnums}@dots{}
@kindex delete display
@kindex undisplay
Remove item numbers @var{dnums} from the list of expressions to display.

@code{undisplay} will not repeat if you press @key{RET} after using it.
(Otherwise you would just get the error @samp{No display number @dots{}}.)

@item disable display @var{dnums}@dots{}
@kindex disable display
Disable the display of item numbers @var{dnums}.  A disabled display
item is not printed automatically, but is not forgotten.  It may be
enabled again later.

@item enable display @var{dnums}@dots{}
@kindex enable display
Enable display of item numbers @var{dnums}.  It becomes effective once
again in auto display of its expression, until you specify otherwise.

@item display
Display the current values of the expressions on the list, just as is
done when the program stops.

@item info display
@kindex info display
Print the list of expressions previously set up to display
automatically, each one with its item number, but without showing the
values.  This includes disabled expressions, which are marked as such.
It also includes expressions which would not be displayed right now
because they refer to automatic variables not currently available.
@end table

If a display expression refers to local variables, then it does not make
sense outside the lexical context for which it was set up.  Such an
expression is disabled when execution enters a context where one of its
variables is not defined.  For example, if you give the command
@code{display last_char} while inside a function with an argument
@code{last_char}, then this argument will be displayed while the program
continues to stop inside that function.  When it stops elsewhere---where
there is no variable @code{last_char}---display is disabled.  The next time
your program stops where @code{last_char} is meaningful, you can enable the
display expression once again.

@node Print Settings, Value History, Auto Display, Data
@section Print Settings

@cindex format options
@cindex print settings
_GDBN__ provides the following ways to control how arrays, structures,
and symbols are printed.  

@noindent
These settings are useful for debugging programs in any language:

@table @code
@item set print address
@item set print address on
@kindex set print address
_GDBN__ will print memory addresses showing the location of stack
traces, structure values, pointer values, breakpoints, and so forth,
even when it also displays the contents of those addresses.  The default
is on.  For example, this is what a stack frame display looks like, with
@code{set print address on}:
@smallexample
(_GDBP__) f
#0  set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") 
    at input.c:530
530	    if (lquote != def_lquote)
@end smallexample

@item set print address off
Do not print addresses when displaying their contents.  For example,
this is the same stack frame displayed with @code{set print address off}:
@example
(_GDBP__) set print addr off
(_GDBP__) f
#0  set_quotes (lq="<<", rq=">>") at input.c:530
530	    if (lquote != def_lquote)
@end example

@item show print address
@kindex show print address
Show whether or not addresses are to be printed.

@item set print array
@itemx set print array on
@kindex set print array
_GDBN__ will pretty print arrays.  This format is more convenient to read,
but uses more space.  The default is off.

@item set print array off.
Return to compressed format for arrays.

@item show print array
@kindex show print array
Show whether compressed or pretty format is selected for displaying
arrays. 

@item set print elements @var{number-of-elements}
@kindex set print elements
If _GDBN__ is printing a large array, it will stop printing after it has
printed the number of elements set by the @code{set print elements} command.
This limit also applies to the display of strings.

@item show print elements
@kindex show print elements
Display the number of elements of a large array that _GDBN__ will print
before losing patience.

@item set print pretty on
@kindex set print pretty
Cause _GDBN__ to print structures in an indented format with one member per
line, like this:

@example
$1 = @{
  next = 0x0,
  flags = @{
    sweet = 1,
    sour = 1
  @},
  meat = 0x54 "Pork"
@}
@end example

@item set print pretty off
Cause _GDBN__ to print structures in a compact format, like this:

@smallexample
$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \
= 0x54 "Pork"@}
@end smallexample

@noindent
This is the default format.

@item show print pretty
@kindex show print pretty
Show which format _GDBN__ will use to print structures.

@item set print sevenbit-strings on
Print using only seven-bit characters; if this option is set, 
_GDBN__ will display any eight-bit characters (in strings or character
values) using the notation @code{\}@var{nnn}.  For example, @kbd{M-a} is
displayed as @code{\341}.

@item set print sevenbit-strings off
Print using either seven-bit or eight-bit characters, as required.  This
is the default.

@item show print sevenbit-strings
Show whether or not _GDBN__ will print only seven-bit characters.

@item set print union on
@kindex set print union
Tell _GDBN__ to print unions which are contained in structures.  This is the
default setting.

@item set print union off
Tell _GDBN__ not to print unions which are contained in structures.

@item show print union
@kindex show print union
Ask _GDBN__ whether or not it will print unions which are contained in
structures. 

For example, given the declarations

@smallexample
typedef enum @{Tree, Bug@} Species;
typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
typedef enum @{Caterpillar, Cocoon, Butterfly@} Bug_forms;

struct thing @{
  Species it;
  union @{
    Tree_forms tree;
    Bug_forms bug;
  @} form;
@};

struct thing foo = @{Tree, @{Acorn@}@};
@end smallexample

@noindent
with @code{set print union on} in effect @samp{p foo} would print

@smallexample
$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
@end smallexample

@noindent
and with @code{set print union off} in effect it would print

@smallexample
$1 = @{it = Tree, form = @{...@}@}
@end smallexample
@end table

@noindent
These settings are of interest when debugging C++ programs:

@table @code
@item set print demangle 
@itemx set print demangle on 
@kindex set print demangle
Print C++ names in their source form rather than in the mangled form
in which they are passed to the assembler and linker for type-safe linkage.
The default is on.

@item show print demangle
@kindex show print demangle
Show whether C++ names will be printed in mangled or demangled form.

@item set print asm-demangle 
@itemx set print asm-demangle on 
@kindex set print asm-demangle
Print C++ names in their source form rather than their mangled form, even
in assembler code printouts such as instruction disassemblies.
The default is off.

@item show print asm-demangle
@kindex show print asm-demangle
Show whether C++ names in assembly listings will be printed in mangled
or demangled form.

@item set print object
@itemx set print object on
@kindex set print object
When displaying a pointer to an object, identify the @emph{actual}
(derived) type of the object rather than the @emph{declared} type, using
the virtual function table.

@item set print object off
Display only the declared type of objects, without reference to the
virtual function table.  This is the default setting.

@item show print object
@kindex show print object
Show whether actual, or declared, object types will be displayed.

@item set print vtbl 
@itemx set print vtbl on 
@kindex set print vtbl
Pretty print C++ virtual function tables.  The default is off.

@item set print vtbl off
Do not pretty print C++ virtual function tables.

@item show print vtbl
@kindex show print vtbl
Show whether C++ virtual function tables are pretty printed, or not.

@end table

@node Value History, Convenience Vars, Print Settings, Data
@section Value History

@cindex value history
Values printed by the @code{print} command are saved in _GDBN__'s @dfn{value
history} so that you can refer to them in other expressions.  Values are
kept until the symbol table is re-read or discarded (for example with
the @code{file} or @code{symbol-file} commands).  When the symbol table
changes, the value history is discarded, since the values may contain
pointers back to the types defined in the symbol table.

@cindex @code{$}
@cindex @code{$$}
@cindex history number
The values printed are given @dfn{history numbers} for you to refer to them
by.  These are successive integers starting with one.  @code{print} shows you
the history number assigned to a value by printing @samp{$@var{num} = }
before the value; here @var{num} is the history number.

To refer to any previous value, use @samp{$} followed by the value's
history number.  The way @code{print} labels its output is designed to
remind you of this.  Just @code{$} refers to the most recent value in
the history, and @code{$$} refers to the value before that.
@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
is the value just prior to @code{$$}, @code{$$1} is equivalent to
@code{$$}, and @code{$$0} is equivalent to @code{$}.

For example, suppose you have just printed a pointer to a structure and
want to see the contents of the structure.  It suffices to type

@example
p *$
@end example

If you have a chain of structures where the component @code{next} points
to the next one, you can print the contents of the next one with this:

@example
p *$.next
@end example

@noindent
You can print successive links in the chain by repeating this
command---which you can do by just typing @key{RET}.

Note that the history records values, not expressions.  If the value of
@code{x} is 4 and you type these commands:

@example
print x
set x=5
@end example

@noindent
then the value recorded in the value history by the @code{print} command
remains 4 even though the value of @code{x} has changed.

@table @code
@kindex show values
@item show values
Print the last ten values in the value history, with their item numbers.
This is like @samp{p@ $$9} repeated ten times, except that @code{show
values} does not change the history.

@item show values @var{n}
Print ten history values centered on history item number @var{n}.

@item show values +
Print ten history values just after the values last printed.  If no more
values are available, produces no display.
@end table

Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
same effect as @samp{show values +}.  

@node Convenience Vars, Registers, Value History, Data
@section Convenience Variables

@cindex convenience variables
_GDBN__ provides @dfn{convenience variables} that you can use within
_GDBN__ to hold on to a value and refer to it later.  These variables
exist entirely within _GDBN__; they are not part of your program, and
setting a convenience variable has no direct effect on further execution
of your program.  That's why you can use them freely.

Convenience variables are prefixed with @samp{$}.  Any name preceded by
@samp{$} can be used for a convenience variable, unless it is one of
the predefined machine-specific register names (@pxref{Registers}).
(Value history references, in contrast, are @emph{numbers} preceded
by @samp{$}.  @xref{Value History}.)

You can save a value in a convenience variable with an assignment
expression, just as you would set a variable in your program.  Example:

@example
set $foo = *object_ptr
@end example

@noindent
would save in @code{$foo} the value contained in the object pointed to by
@code{object_ptr}.

Using a convenience variable for the first time creates it; but its value
is @code{void} until you assign a new value.  You can alter the value with
another assignment at any time.

Convenience variables have no fixed types.  You can assign a convenience
variable any type of value, including structures and arrays, even if
that variable already has a value of a different type.  The convenience
variable, when used as an expression, has the type of its current value.

@table @code
@item show convenience
@kindex show convenience
Print a list of convenience variables used so far, and their values.
Abbreviated @code{show con}.
@end table

One of the ways to use a convenience variable is as a counter to be
incremented or a pointer to be advanced.  For example, to print
a field from successive elements of an array of structures:

_0__@example
set $i = 0
print bar[$i++]->contents
@i{@dots{} repeat that command by typing @key{RET}.}
_1__@end example

Some convenience variables are created automatically by _GDBN__ and given
values likely to be useful.

@table @code
@item $_
The variable @code{$_} is automatically set by the @code{x} command to
the last address examined (@pxref{Memory}).  Other commands which
provide a default address for @code{x} to examine also set @code{$_}
to that address; these commands include @code{info line} and @code{info
breakpoint}.

@item $__
The variable @code{$__} is automatically set by the @code{x} command
to the value found in the last address examined.
@end table

@node Registers, Floating Point Hardware, Convenience Vars, Data
@section Registers

@cindex registers
Machine register contents can be referred to in expressions as variables
with names starting with @samp{$}.  The names of registers are different
for each machine; use @code{info registers} to see the names used on
your machine.  

@table @code
@item info registers
@kindex info registers
Print the names and values of all registers (in the selected stack frame).

@item info registers @var{regname}
Print the relativized value of register @var{regname}.  @var{regname}
may be any register name valid on the machine you are using, with
or without the initial @samp{$}.
@end table

The register names @code{$pc} and @code{$sp} are used on most machines
for the program counter register and the stack pointer.  For example,
you could print the program counter in hex with
@example
p/x $pc
@end example

@noindent
or print the instruction to be executed next with
@example
x/i $pc
@end example

@noindent
or add four to the stack pointer with
@example
set $sp += 4
@end example

@noindent
The last 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 @code{$sp} is
not allowed when other stack frames are selected.  (To pop entire frames
off the stack, regardless of machine architecture, use @code{return};
@pxref{Returning}.)

Often @code{$fp} is used for a register that contains a pointer to the
current stack frame, and @code{$ps} is sometimes used for a register
that contains the processor status.  These standard register names may
be available on your machine even though the @code{info registers}
command shows other names.  For example, on the SPARC, @code{info
registers} displays the processor status register as @code{$psr} but you
can also refer to it as @code{$ps}.

_GDBN__ 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 @emph{print} it as a floating point value with
@samp{print/f $@var{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, _GDBN__ normally works with the virtual format only (the format that
makes sense for your program), but the @code{info registers} command
prints the data in both formats.

Normally, register values are relative to the selected stack frame
(@pxref{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
@samp{frame 0}).

However, _GDBN__ must deduce where registers are saved, from the machine
code generated by your compiler.  If some registers are not saved, or if
_GDBN__ is unable to locate the saved registers, the selected stack
frame will make no difference.

@node Floating Point Hardware,  , Registers, Data
@section Floating Point Hardware
@cindex floating point
Depending on the host machine architecture, _GDBN__ may be able to give
you more information about the status of the floating point hardware.

@table @code
@item info float
@kindex info float
If available, provides hardware-dependent information about the floating
point unit.  The exact contents and layout vary depending on the
floating point chip.
@end table
@c FIXME: this is a cop-out.  Try to get examples, explanations.  Only
@c FIXME...supported currently on arm's and 386's.  Mark properly with 
@c FIXME... m4 macros to isolate general statements from hardware-dep, 
@c FIXME... at that point.