From 9bcc06ef1645086025bd7a5ecbe423f7fc1d6fc8 Mon Sep 17 00:00:00 2001 From: Roland Pesch Date: Thu, 23 May 1991 00:14:26 +0000 Subject: *** empty log message *** --- gdb/doc/gdb.alter-m4 | 205 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100755 gdb/doc/gdb.alter-m4 (limited to 'gdb/doc/gdb.alter-m4') 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. -- cgit v1.1