First cut.

[deliverable/binutils-gdb.git] / gdb / doc / gdb.alter-m4

_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 Altering, _GDBN__ Files, Symbols, Top
@chapter Altering Execution

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

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

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

@node Assignment, Jumping, Altering, Altering
@section Assignment to Variables

@cindex assignment
@cindex setting variables
To alter the value of a variable, evaluate an assignment expression.
@xref{Expressions}.  For example,

@example
print x=4
@end example

@noindent
would store the value 4 into the variable @code{x}, and then print the
value of the assignment expression (which is 4).  All the assignment
operators of C are supported, including the increment operators
@samp{++} and @samp{--}, and combining assignments such as @samp{+=} and
_0__@samp{<<=}_1__.

@kindex set
@kindex set variable
@cindex variables, setting
If you are not interested in seeing the value of the assignment, use the
@code{set} command instead of the @code{print} command.  @code{set} is
really the same as @code{print} except that the expression's value is not
printed and is not put in the value history (@pxref{Value History}).  The
expression is evaluated only for its effects.

If the beginning of the argument string of the @code{set} command
appears identical to a @code{set} subcommand, use the @code{set
variable} command instead of just @code{set}.  This command is identical
to @code{set} except for its lack of subcommands.  For example, a
program might well have a variable @code{width}---which leads to
an error if we try to set a new value with just @samp{set width=13}, as
we might if @code{set width} didn't happen to be a _GDBN__ command:
@example
(_GDBP__) whatis width
type = double
(_GDBP__) p width
$4 = 13
(_GDBP__) set width=47
Invalid syntax in expression.
@end example
@noindent
The invalid expression, of course, is @samp{=47}.  What we can do in
order to actually set our program's variable @code{width} is 
@example
(_GDBP__) set var width=47
@end example

_GDBN__ allows more implicit conversions in assignments than C does; you can
freely store an integer value into a pointer variable or vice versa, and
any structure can be converted to any other structure that is the same
length or shorter.
@comment FIXME: how do structs align/pad in these conversions? 
@comment        /pesch@cygnus.com 18dec1990

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

@example
set @{int@}0x83040 = 4
@end example

@noindent
stores the value 4 into that memory location.

@node Jumping, Signaling, Assignment, Altering
@section Continuing at a Different Address

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

@table @code
@item jump @var{linespec}
@kindex jump
Resume execution at line @var{linespec}.  Execution will stop
immediately if there is a breakpoint there.  @xref{List} for a
description of the different forms of @var{linespec}.

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

@item jump *@var{address}
Resume execution at the instruction at address @var{address}.
@end table

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

@example
set $pc = 0x485
@end example

@noindent
causes the next @code{continue} command or stepping command to execute at
address 0x485, rather than at the address where the program stopped.
@xref{Stepping}.

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

@group
@node Signaling, Returning, Jumping, Altering
@section Giving the Program a Signal

@table @code
@item signal @var{signalnum}
@kindex signal
Resume execution where the program stopped, but give it immediately the
signal number @var{signalnum}.

Alternatively, if @var{signalnum} is zero, continue execution without
giving a signal.  This is useful when the program stopped on account of
a signal and would ordinary see the signal when resumed with the
@code{continue} command; @samp{signal 0} causes it to resume without a
signal.

@code{signal} does not repeat when you press @key{RET} a second time
after executing the command.
@end table
@end group

@node Returning, Calling, Signaling, Altering
@section Returning from a Function

@table @code
@item return
@itemx return @var{expression}
@cindex returning from a function
@kindex return
You can cancel execution of a function call with the @code{return}
command.  If you give an
@var{expression} argument, its value is used as the function's return
value. 
@end table

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

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

The @code{return} command does not resume execution; it leaves the
program stopped in the state that would exist if the function had just
returned.  In contrast, the @code{finish} command (@pxref{Stepping})
resumes execution until the selected stack frame returns naturally.

@node     Calling,  , Returning, Altering
@section Calling your Program's Functions

@cindex calling functions
@kindex call
@table @code
@item call @var{expr}
Evaluate the expression @var{expr} without displaying @code{void}
returned values.
@end table

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