*** empty log message ***

1 files changed, 205 insertions, 0 deletions

diff --git a/gdb/doc/gdb.alter-m4 b/gdb/doc/gdb.alter-m4
new file mode 100755
index 0000000..3ed4f24
--- /dev/null
+++ b/gdb/doc/gdb.alter-m4
@@ -0,0 +1,205 @@
+_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.