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.
4 @node Altering, _GDBN__ Files, Symbols, Top
5 @chapter Altering Execution
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
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.
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
25 @node Assignment, Jumping, Altering, Altering
26 @section Assignment to Variables
29 @cindex setting variables
30 To alter the value of a variable, evaluate an assignment expression.
31 @xref{Expressions}. For example,
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
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.
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:
61 (_GDBP__) whatis width
65 (_GDBP__) set width=47
66 Invalid syntax in expression.
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
72 (_GDBP__) set var width=47
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
79 @comment FIXME: how do structs align/pad in these conversions?
80 @comment /pesch@cygnus.com 18dec1990
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
89 set @{int@}0x83040 = 4
93 stores the value 4 into that memory location.
95 @node Jumping, Signaling, Assignment, Altering
96 @section Continuing at a Different Address
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:
103 @item jump @var{linespec}
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}.
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.
119 @item jump *@var{address}
120 Resume execution at the instruction at address @var{address}.
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,
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.
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.
141 @node Signaling, Returning, Jumping, Altering
143 @section Giving the Program a Signal
146 @item signal @var{signalnum}
148 Resume execution where the program stopped, but give it immediately the
149 signal number @var{signalnum}.
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
157 @code{signal} does not repeat when you press @key{RET} a second time
158 after executing the command.
162 @node Returning, Calling, Signaling, Altering
163 @section Returning from a Function
167 @itemx return @var{expression}
168 @cindex returning from a function
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
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}.
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.
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.
191 @node Calling, , Returning, Altering
192 @section Calling your Program's Functions
194 @cindex calling functions
197 @item call @var{expr}
198 Evaluate the expression @var{expr} without displaying @code{void}
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.