Commit | Line | Data |
---|---|---|
9bcc06ef RP |
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. | |
27189593 | 3 | @c M4 FRAGMENT: $Id$ |
9bcc06ef RP |
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 | ||
9bcc06ef | 141 | @node Signaling, Returning, Jumping, Altering |
27189593 | 142 | @c @group |
9bcc06ef RP |
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 | |
27189593 | 160 | @c @end group |
9bcc06ef RP |
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. |