*** empty log message ***

1 files changed, 926 insertions, 0 deletions

diff --git a/gdb/doc/gdb.data-m4 b/gdb/doc/gdb.data-m4
new file mode 100755
index 0000000000..8685a13479
--- /dev/null
+++ b/gdb/doc/gdb.data-m4
@@ -0,0 +1,926 @@
+_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
+_dnl__ This file is part of the source for the GDB manual.
+_dnl__ $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.