gdb/doc/gdb.alter-m4

   1 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
   2 _dnl__ This file is part of the source for the GDB manual.
   3 @c M4 FRAGMENT: $Id$
   4 @node Altering, _GDBN__ Files, Symbols, Top
   5 @chapter Altering Execution
   6
   7 Once you think you have found an error in the program, you might want to
   8 find out for certain whether correcting the apparent error would lead to
   9 correct results in the rest of the run.  You can find the answer by
  10 experiment, using the _GDBN__ features for altering execution of the
  11 program.
  12
  13 For example, you can store new values into variables or memory
  14 locations, give the program a signal, restart it at a different address,
  15 or even return prematurely from a function to its caller.
  16
  17 @menu
  18 * Assignment::                  Assignment to Variables
  19 * Jumping::                     Continuing at a Different Address
  20 * Signaling::                   Giving the Program a Signal
  21 * Returning::                   Returning from a Function
  22 * Calling::                     Calling your Program's Functions
  23 @end menu
  24
  25 @node Assignment, Jumping, Altering, Altering
  26 @section Assignment to Variables
  27
  28 @cindex assignment
  29 @cindex setting variables
  30 To alter the value of a variable, evaluate an assignment expression.
  31 @xref{Expressions}.  For example,
  32
  33 @example
  34 print x=4
  35 @end example
  36
  37 @noindent
  38 would store the value 4 into the variable @code{x}, and then print the
  39 value of the assignment expression (which is 4).  All the assignment
  40 operators of C are supported, including the increment operators
  41 @samp{++} and @samp{--}, and combining assignments such as @samp{+=} and
  42 _0__@samp{<<=}_1__.
  43
  44 @kindex set
  45 @kindex set variable
  46 @cindex variables, setting
  47 If you are not interested in seeing the value of the assignment, use the
  48 @code{set} command instead of the @code{print} command.  @code{set} is
  49 really the same as @code{print} except that the expression's value is not
  50 printed and is not put in the value history (@pxref{Value History}).  The
  51 expression is evaluated only for its effects.
  52
  53 If the beginning of the argument string of the @code{set} command
  54 appears identical to a @code{set} subcommand, use the @code{set
  55 variable} command instead of just @code{set}.  This command is identical
  56 to @code{set} except for its lack of subcommands.  For example, a
  57 program might well have a variable @code{width}---which leads to
  58 an error if we try to set a new value with just @samp{set width=13}, as
  59 we might if @code{set width} didn't happen to be a _GDBN__ command:
  60 @example
  61 (_GDBP__) whatis width
  62 type = double
  63 (_GDBP__) p width
  64 $4 = 13
  65 (_GDBP__) set width=47
  66 Invalid syntax in expression.
  67 @end example
  68 @noindent
  69 The invalid expression, of course, is @samp{=47}.  What we can do in
  70 order to actually set our program's variable @code{width} is
  71 @example
  72 (_GDBP__) set var width=47
  73 @end example
  74
  75 _GDBN__ allows more implicit conversions in assignments than C does; you can
  76 freely store an integer value into a pointer variable or vice versa, and
  77 any structure can be converted to any other structure that is the same
  78 length or shorter.
  79 @comment FIXME: how do structs align/pad in these conversions?
  80 @comment        /pesch@cygnus.com 18dec1990
  81
  82 To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
  83 construct to generate a value of specified type at a specified address
  84 (@pxref{Expressions}).  For example, @code{@{int@}0x83040} refers
  85 to memory location @code{0x83040} as an integer (which implies a certain size
  86 and representation in memory), and
  87
  88 @example
  89 set @{int@}0x83040 = 4
  90 @end example
  91
  92 @noindent
  93 stores the value 4 into that memory location.
  94
  95 @node Jumping, Signaling, Assignment, Altering
  96 @section Continuing at a Different Address
  97
  98 Ordinarily, when you continue the program, you do so at the place where
  99 it stopped, with the @code{continue} command.  You can instead continue at
 100 an address of your own choosing, with the following commands:
 101
 102 @table @code
 103 @item jump @var{linespec}
 104 @kindex jump
 105 Resume execution at line @var{linespec}.  Execution will stop
 106 immediately if there is a breakpoint there.  @xref{List} for a
 107 description of the different forms of @var{linespec}.
 108
 109 The @code{jump} command does not change the current stack frame, or
 110 the stack pointer, or the contents of any memory location or any
 111 register other than the program counter.  If line @var{linespec} is in
 112 a different function from the one currently executing, the results may
 113 be bizarre if the two functions expect different patterns of arguments or
 114 of local variables.  For this reason, the @code{jump} command requests
 115 confirmation if the specified line is not in the function currently
 116 executing.  However, even bizarre results are predictable if you are
 117 well acquainted with the machine-language code of the program.
 118
 119 @item jump *@var{address}
 120 Resume execution at the instruction at address @var{address}.
 121 @end table
 122
 123 You can get much the same effect as the @code{jump} command by storing a
 124 new value into the register @code{$pc}.  The difference is that this
 125 does not start the program running; it only changes the address where it
 126 @emph{will} run when it is continued.  For example,
 127
 128 @example
 129 set $pc = 0x485
 130 @end example
 131
 132 @noindent
 133 causes the next @code{continue} command or stepping command to execute at
 134 address 0x485, rather than at the address where the program stopped.
 135 @xref{Stepping}.
 136
 137 The most common occasion to use the @code{jump} command is to back up,
 138 perhaps with more breakpoints set, over a portion of a program that has
 139 already executed, in order to examine its execution in more detail.
 140
 141 @node Signaling, Returning, Jumping, Altering
 142 @c @group
 143 @section Giving the Program a Signal
 144
 145 @table @code
 146 @item signal @var{signalnum}
 147 @kindex signal
 148 Resume execution where the program stopped, but give it immediately the
 149 signal number @var{signalnum}.
 150
 151 Alternatively, if @var{signalnum} is zero, continue execution without
 152 giving a signal.  This is useful when the program stopped on account of
 153 a signal and would ordinary see the signal when resumed with the
 154 @code{continue} command; @samp{signal 0} causes it to resume without a
 155 signal.
 156
 157 @code{signal} does not repeat when you press @key{RET} a second time
 158 after executing the command.
 159 @end table
 160 @c @end group
 161
 162 @node Returning, Calling, Signaling, Altering
 163 @section Returning from a Function
 164
 165 @table @code
 166 @item return
 167 @itemx return @var{expression}
 168 @cindex returning from a function
 169 @kindex return
 170 You can cancel execution of a function call with the @code{return}
 171 command.  If you give an
 172 @var{expression} argument, its value is used as the function's return
 173 value.
 174 @end table
 175
 176 When you use @code{return}, _GDBN__ discards the selected stack frame
 177 (and all frames within it).  You can think of this as making the
 178 discarded frame return prematurely.  If you wish to specify a value to
 179 be returned, give that value as the argument to @code{return}.
 180
 181 This pops the selected stack frame (@pxref{Selection}), and any other
 182 frames inside of it, leaving its caller as the innermost remaining
 183 frame.  That frame becomes selected.  The specified value is stored in
 184 the registers used for returning values of functions.
 185
 186 The @code{return} command does not resume execution; it leaves the
 187 program stopped in the state that would exist if the function had just
 188 returned.  In contrast, the @code{finish} command (@pxref{Stepping})
 189 resumes execution until the selected stack frame returns naturally.
 190
 191 @node     Calling,  , Returning, Altering
 192 @section Calling your Program's Functions
 193
 194 @cindex calling functions
 195 @kindex call
 196 @table @code
 197 @item call @var{expr}
 198 Evaluate the expression @var{expr} without displaying @code{void}
 199 returned values.
 200 @end table
 201
 202 You can use this variant of the @code{print} command if you want to
 203 execute a function from your program, but without cluttering the output
 204 with @code{void} returned values.  The result is printed and saved in
 205 the value history, if it is not void.