Commit | Line | Data |
---|---|---|
9bcc06ef RP |
1 | _dnl__ -*- Texinfo -*- |
2 | _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc. | |
3 | _dnl__ This file is part of the source for the GDB manual. | |
4 | _dnl__ $Id$ | |
5 | @node Stopping, Stack, Running, Top | |
6 | @chapter Stopping and Continuing | |
7 | ||
8 | When you run a program normally, it runs until it terminates. The | |
9 | principal purpose of using a debugger is so that you can stop your | |
10 | program before it terminates; or so that, if the program runs into | |
11 | trouble, you can investigate and find out why. | |
12 | ||
13 | Inside _GDBN__, your program may stop for any of several reasons, such | |
14 | as a signal, a breakpoint, or reaching a new line after a _GDBN__ | |
15 | command such as @code{step}. Usually, the messages shown by _GDBN__ | |
16 | provide ample explanation of the status of your program---but you can | |
17 | also explicitly request this information at any time. | |
18 | ||
19 | @table @code | |
20 | @item info program | |
21 | @kindex info program | |
22 | Display information about the status of your program: whether it is | |
23 | running or not, what process it is, and why it stopped. | |
24 | @end table | |
25 | ||
26 | @menu | |
27 | * Breakpoints:: Breakpoints, Watchpoints, and Exceptions | |
28 | * Stepping:: Stepping | |
29 | * Continuing:: Continuing | |
30 | * Signals:: Signals | |
31 | @end menu | |
32 | ||
33 | @node Breakpoints, Stepping, Stopping, Stopping | |
34 | @section Breakpoints, Watchpoints, and Exceptions | |
35 | ||
36 | @cindex breakpoints | |
37 | A @dfn{breakpoint} makes your program stop whenever a certain point in | |
38 | the program is reached. For each breakpoint, you can add various | |
39 | conditions to control in finer detail whether the program will stop. | |
40 | You can set breakpoints with the @code{break} command and its variants | |
41 | (@pxref{Set Breaks}), to specify the place where the program should stop | |
42 | by line number, function name or exact address in the program. In | |
43 | languages with exception handling (such as GNU C++), you can also set | |
44 | breakpoints where an execption is raised (@pxref{Exception Handling}). | |
45 | ||
46 | @cindex watchpoints | |
47 | A @dfn{watchpoint} is a special breakpoint that stops your program when | |
48 | the value of an expression changes. You must use a different command to | |
49 | set watchpoints (@pxref{Set Watchpoints}), but aside from that, you can | |
50 | manage a watchpoint exactly like any other breakpoint: you enable, disable, and | |
51 | delete both breakpoints and watchpoints using exactly the same commands. | |
52 | ||
53 | Each breakpoint or watchpoint is assigned a number when it is created; | |
54 | these numbers are successive integers starting with one. In many of the | |
55 | commands for controlling various features of breakpoints you use the | |
56 | breakpoint number to say which breakpoint you want to change. Each | |
57 | breakpoint may be @dfn{enabled} or @dfn{disabled}; if disabled, it has | |
58 | no effect on the program until you enable it again. | |
59 | ||
60 | @menu | |
61 | * Set Breaks:: Setting Breakpoints | |
62 | * Set Watchpoints:: Setting Watchpoints | |
63 | * Exception Handling:: Breakpoints and Exceptions | |
64 | * Delete Breaks:: Deleting Breakpoints | |
65 | * Disabling:: Disabling Breakpoints | |
66 | * Conditions:: Break Conditions | |
67 | * Break Commands:: Breakpoint Command Lists | |
68 | * Breakpoint Menus:: Breakpoint Menus | |
69 | * Error in Breakpoints:: | |
70 | @end menu | |
71 | ||
72 | @node Set Breaks, Set Watchpoints, Breakpoints, Breakpoints | |
73 | @subsection Setting Breakpoints | |
74 | ||
75 | @kindex break | |
76 | @kindex b | |
77 | Breakpoints are set with the @code{break} command (abbreviated @code{b}). | |
78 | ||
79 | You have several ways to say where the breakpoint should go. | |
80 | ||
81 | @table @code | |
82 | @item break @var{function} | |
83 | Set a breakpoint at entry to function @var{function}. When using source | |
84 | languages that permit overloading of symbols, such as C++, | |
85 | @var{function} may refer to more than one possible place to break. | |
86 | @xref{Breakpoint Menus}, for a discussion of that situation. | |
87 | ||
88 | @item break +@var{offset} | |
89 | @itemx break -@var{offset} | |
90 | Set a breakpoint some number of lines forward or back from the position | |
91 | at which execution stopped in the currently selected frame. | |
92 | ||
93 | @item break @var{linenum} | |
94 | Set a breakpoint at line @var{linenum} in the current source file. | |
95 | That file is the last file whose source text was printed. This | |
96 | breakpoint will stop the program just before it executes any of the | |
97 | code on that line. | |
98 | ||
99 | @item break @var{filename}:@var{linenum} | |
100 | Set a breakpoint at line @var{linenum} in source file @var{filename}. | |
101 | ||
102 | @item break @var{filename}:@var{function} | |
103 | Set a breakpoint at entry to function @var{function} found in file | |
104 | @var{filename}. Specifying a file name as well as a function name is | |
105 | superfluous except when multiple files contain similarly named | |
106 | functions. | |
107 | ||
108 | @item break *@var{address} | |
109 | Set a breakpoint at address @var{address}. You can use this to set | |
110 | breakpoints in parts of the program which do not have debugging | |
111 | information or source files. | |
112 | ||
113 | @item break | |
114 | When called without any arguments, @code{break} sets a breakpoint at the | |
115 | next instruction to be executed in the selected stack frame | |
116 | (@pxref{Stack}). In any selected frame but the innermost, this will | |
117 | cause the program to stop as soon as control returns to that frame. | |
118 | This is similar to the effect of a @code{finish} command in the frame | |
119 | inside the selected frame---except that @code{finish} doesn't leave an | |
120 | active breakpoint. If you use @code{break} without an argument in the | |
121 | innermost frame, _GDBN__ will stop the next time it reaches the current | |
122 | location; this may be useful inside loops. | |
123 | ||
124 | _GDBN__ normally ignores breakpoints when it resumes execution, until at | |
125 | least one instruction has been executed. If it did not do this, you | |
126 | would be unable to proceed past a breakpoint without first disabling the | |
127 | breakpoint. This rule applies whether or not the breakpoint already | |
128 | existed when the program stopped. | |
129 | ||
130 | @item break @dots{} if @var{cond} | |
131 | Set a breakpoint with condition @var{cond}; evaluate the expression | |
132 | @var{cond} each time the breakpoint is reached, and stop only if the | |
133 | value is nonzero. @samp{@dots{}} stands for one of the possible | |
134 | arguments described above (or no argument) specifying where to break. | |
135 | @xref{Conditions}, for more information on breakpoint conditions. | |
136 | ||
137 | @item tbreak @var{args} | |
138 | @kindex tbreak | |
139 | Set a breakpoint enabled only for one stop. @var{args} are the | |
140 | same as in the @code{break} command, and the breakpoint is set in the same | |
141 | way, but the breakpoint is automatically disabled the first time it | |
142 | is hit. @xref{Disabling}. | |
143 | ||
144 | @item rbreak @var{regex} | |
145 | @kindex rbreak | |
146 | Set a breakpoint on all functions matching @var{regex}. This is | |
147 | useful for setting breakpoints on overloaded functions that are not | |
148 | members of any special classes. This command sets an unconditional | |
149 | breakpoint on all matches, printing a list of all breakpoints it set. | |
150 | Once these breakpoints are set, they are treated just like the | |
151 | breakpoints set with the @code{break} command. They can be deleted, | |
152 | disabled, made conditional, etc., in the standard ways. | |
153 | ||
154 | @kindex info breakpoints | |
155 | @kindex $_ | |
156 | @item info breakpoints | |
157 | The command @code{info breakpoints} prints a list of all breakpoints | |
158 | (but not watchpoints) set and not deleted, showing their numbers, where | |
159 | in the program they are, and any special features in use for them. | |
160 | Disabled breakpoints are included in the list, but marked as disabled. | |
161 | @code{info break} with a breakpoint number as argument lists only that | |
162 | breakpoint. The convenience variable @code{$_} and the default | |
163 | examining-address for the @code{x} command are set to the address of the | |
164 | last breakpoint listed (@pxref{Memory}). The equivalent command for | |
165 | watchpoints is @code{info watch}. | |
166 | @end table | |
167 | ||
168 | _GDBN__ allows you to set any number of breakpoints at the same place in the | |
169 | program. There is nothing silly or meaningless about this. When the | |
170 | breakpoints are conditional, this is even useful (@pxref{Conditions}). | |
171 | ||
172 | @node Set Watchpoints, Exception Handling, Set Breaks, Breakpoints | |
173 | @subsection Setting Watchpoints | |
174 | @cindex setting watchpoints | |
175 | You can use a watchpoint to stop execution whenever the value of an | |
176 | expression changes, without having to predict a particular place in the | |
177 | inferior process where this may happen. | |
178 | ||
179 | Watchpoints currently execute two orders of magnitude more slowly than | |
180 | other breakpoints, but this can well be worth it to catch errors where | |
181 | you have no clue what part of your program is the culprit. Some | |
182 | processors provide special hardware to implement this feature; future | |
183 | releases of _GDBN__ will use such hardware if it is available. | |
184 | ||
185 | @table @code | |
186 | @kindex watch | |
187 | @item watch @var{expr} | |
188 | Set a watchpoint for an expression. | |
189 | ||
190 | @kindex info watchpoints | |
191 | @item info watchpoints | |
192 | This command prints a list of watchpoints; it is otherwise similar to | |
193 | @code{info break}. | |
194 | @end table | |
195 | ||
196 | @node Exception Handling, Delete Breaks, Set Watchpoints, Breakpoints | |
197 | @subsection Breakpoints and Exceptions | |
198 | @cindex exception handlers | |
199 | ||
200 | Some languages, such as GNU C++, implement exception handling. _GDBN__ | |
201 | can be used to examine what caused the program to raise an exception | |
202 | and to list the exceptions the program is prepared to handle at a | |
203 | given point in time. | |
204 | ||
205 | @table @code | |
206 | @item catch @var{exceptions} | |
207 | @kindex catch | |
208 | ||
209 | You can set breakpoints at active exception handlers by using the | |
210 | @code{catch} command. @var{exceptions} is a list of names of exceptions | |
211 | to catch. | |
212 | @end table | |
213 | ||
214 | You can use @code{info catch} to list active exception handlers; | |
215 | @pxref{Frame Info}. | |
216 | ||
217 | There are currently some limitations to exception handling in _GDBN__. | |
218 | These will be corrected in a future release. | |
219 | ||
220 | @itemize @bullet | |
221 | @item | |
222 | If you call a function interactively, _GDBN__ normally returns | |
223 | control to you when the function has finished executing. If the call | |
224 | raises an exception, however, the call may bypass the mechanism that | |
225 | returns control to the user and cause the program to simply continue | |
226 | running until it hits a breakpoint, catches a signal that _GDBN__ is | |
227 | listening for, or exits. | |
228 | @item | |
229 | You cannot raise an exception interactively. | |
230 | @item | |
231 | You cannot interactively install an exception handler. | |
232 | @end itemize | |
233 | ||
234 | @cindex raise exceptions | |
235 | Sometimes @code{catch} is not the best way to debug exception handling: | |
236 | if you need to know exactly where an exception is raised, it's better to | |
237 | stop @emph{before} the exception handler is called, since that way you | |
238 | can see the stack before any unwinding takes place. If you set a | |
239 | breakpoint in an exception handler instead, it may not be easy to find | |
240 | out where the exception was raised. | |
241 | ||
242 | To stop just before an exception handler is called, you need some | |
243 | knowledge of the implementation. In the case of GNU C++ exception are | |
244 | raised by calling a library function named @code{__raise_exception} | |
245 | which has the following ANSI C interface: | |
246 | ||
247 | @example | |
248 | /* ADDR is where the exception identifier is stored. | |
249 | ID is the exception identifier. */ | |
250 | void __raise_exception (void **@var{addr}, void *@var{id}); | |
251 | @end example | |
252 | ||
253 | @noindent | |
254 | To make the debugger catch all exceptions before any stack | |
255 | unwinding takes place, set a breakpoint on @code{__raise_exception} | |
256 | (@pxref{Breakpoints}). | |
257 | ||
258 | With a conditional breakpoint (@xref{Conditions}) that depends on the | |
259 | value of @var{id}, you can stop your program when a specific exception | |
260 | is raised. You can use multiple conditional breakpoints to stop the | |
261 | program when any of a number of exceptions are raised. | |
262 | ||
263 | @node Delete Breaks, Disabling, Exception Handling, Breakpoints | |
264 | @subsection Deleting Breakpoints | |
265 | ||
266 | @cindex clearing breakpoints, watchpoints | |
267 | @cindex deleting breakpoints, watchpoints | |
268 | It is often necessary to eliminate a breakpoint or watchpoint once it | |
269 | has done its job and you no longer want the program to stop there. This | |
270 | is called @dfn{deleting} the breakpoint. A breakpoint that has been | |
271 | deleted no longer exists in any sense; it is forgotten. | |
272 | ||
273 | With the @code{clear} command you can delete breakpoints according to | |
274 | where they are in the program. With the @code{delete} command you can | |
275 | delete individual breakpoints or watchpoints by specifying their | |
276 | breakpoint numbers. | |
277 | ||
278 | It is not necessary to delete a breakpoint to proceed past it. _GDBN__ | |
279 | automatically ignores breakpoints on the first instruction to be executed | |
280 | when you continue execution without changing the execution address. | |
281 | ||
282 | @table @code | |
283 | @item clear | |
284 | @kindex clear | |
285 | Delete any breakpoints at the next instruction to be executed in the | |
286 | selected stack frame (@pxref{Selection}). When the innermost frame | |
287 | is selected, this is a good way to delete a breakpoint that the program | |
288 | just stopped at. | |
289 | ||
290 | @item clear @var{function} | |
291 | @itemx clear @var{filename}:@var{function} | |
292 | Delete any breakpoints set at entry to the function @var{function}. | |
293 | ||
294 | @item clear @var{linenum} | |
295 | @itemx clear @var{filename}:@var{linenum} | |
296 | Delete any breakpoints set at or within the code of the specified line. | |
297 | ||
298 | @item delete breakpoints @var{bnums}@dots{} | |
299 | @itemx delete @var{bnums}@dots{} | |
300 | @itemx delete | |
301 | @cindex delete breakpoints | |
302 | @kindex delete | |
303 | @kindex d | |
304 | Delete the breakpoints or watchpoints of the numbers specified as | |
305 | arguments. If no argument is specified, delete all breakpoints. You | |
306 | can abbreviate this command as @code{d}. | |
307 | @end table | |
308 | ||
309 | @node Disabling, Conditions, Delete Breaks, Breakpoints | |
310 | @subsection Disabling Breakpoints | |
311 | ||
312 | @cindex disabled breakpoints | |
313 | @cindex enabled breakpoints | |
314 | Rather than deleting a breakpoint or watchpoint, you might prefer to | |
315 | @dfn{disable} it. This makes the breakpoint inoperative as if it had | |
316 | been deleted, but remembers the information on the breakpoint so that | |
317 | you can @dfn{enable} it again later. | |
318 | ||
319 | You disable and enable breakpoints and watchpoints with the | |
320 | @code{enable} and @code{disable} commands, optionally specifying one or | |
321 | more breakpoint numbers as arguments. Use @code{info break} or | |
322 | @code{info watch} to print a list of breakpoints or watchpoints if you | |
323 | don't know which numbers to use. | |
324 | ||
325 | A breakpoint or watchpoint can have any of four different states of | |
326 | enablement: | |
327 | ||
328 | @itemize @bullet | |
329 | @item | |
330 | Enabled. The breakpoint will stop the program. A breakpoint made | |
331 | with the @code{break} command starts out in this state. | |
332 | @item | |
333 | Disabled. The breakpoint has no effect on the program. | |
334 | @item | |
335 | Enabled once. The breakpoint will stop the program, but | |
336 | when it does so it will become disabled. A breakpoint made | |
337 | with the @code{tbreak} command starts out in this state. | |
338 | @item | |
339 | Enabled for deletion. The breakpoint will stop the program, but | |
340 | immediately after it does so it will be deleted permanently. | |
341 | @end itemize | |
342 | ||
343 | You can use the following commands to enable or disable breakpoints and | |
344 | watchpoints: | |
345 | ||
346 | @table @code | |
347 | @item disable breakpoints @var{bnums}@dots{} | |
348 | @itemx disable @var{bnums}@dots{} | |
349 | @itemx disable | |
350 | @kindex disable breakpoints | |
351 | @kindex disable | |
352 | @kindex dis | |
353 | Disable the specified breakpoints---or all breakpoints, if none are | |
354 | listed. A disabled breakpoint has no effect but is not forgotten. All | |
355 | options such as ignore-counts, conditions and commands are remembered in | |
356 | case the breakpoint is enabled again later. You may abbreviate | |
357 | @code{disable} as @code{dis}. | |
358 | ||
359 | @item enable breakpoints @var{bnums}@dots{} | |
360 | @itemx enable @var{bnums}@dots{} | |
361 | @itemx enable | |
362 | @kindex enable breakpoints | |
363 | @kindex enable | |
364 | Enable the specified breakpoints (or all defined breakpoints). They | |
365 | become effective once again in stopping the program, until you specify | |
366 | otherwise. | |
367 | ||
368 | @item enable breakpoints once @var{bnums}@dots{} | |
369 | @itemx enable once @var{bnums}@dots{} | |
370 | Enable the specified breakpoints temporarily. Each will be disabled | |
371 | again the next time it stops the program (unless you have used one of | |
372 | these commands to specify a different state before that time comes). | |
373 | ||
374 | @item enable breakpoints delete @var{bnums}@dots{} | |
375 | @itemx enable delete @var{bnums}@dots{} | |
376 | Enable the specified breakpoints to work once and then die. Each of | |
377 | the breakpoints will be deleted the next time it stops the program | |
378 | (unless you have used one of these commands to specify a different | |
379 | state before that time comes). | |
380 | @end table | |
381 | ||
382 | Save for a breakpoint set with @code{tbreak} (@pxref{Set Breaks}), | |
383 | breakpoints that you set initially enabled; subsequently, they become | |
384 | disabled or enabled only when you use one of the commands above. (The | |
385 | command @code{until} can set and delete a breakpoint of its own, but it | |
386 | will not change the state of your other breakpoints; | |
387 | @pxref{Stepping}.) | |
388 | ||
389 | @node Conditions, Break Commands, Disabling, Breakpoints | |
390 | @subsection Break Conditions | |
391 | @cindex conditional breakpoints | |
392 | @cindex breakpoint conditions | |
393 | ||
394 | The simplest sort of breakpoint breaks every time the program reaches a | |
395 | specified place. You can also specify a @dfn{condition} for a | |
396 | breakpoint. A condition is just a Boolean expression in your | |
397 | programming language. (@xref{Expressions}). A breakpoint with a | |
398 | condition evaluates the expression each time the program reaches it, and | |
399 | the program stops only if the condition is true. | |
400 | ||
401 | Conditions are also accepted for watchpoints; you may not need them, | |
402 | since a watchpoint is inspecting the value of an expression anyhow---but | |
403 | it might be simpler, say, to just set a watchpoint on a variable name, | |
404 | then have a condition that tests whether the new value is an interesting | |
405 | one. | |
406 | ||
407 | Break conditions may have side effects, and may even call functions in your | |
408 | program. These may sound like strange things to do, but their effects are | |
409 | completely predictable unless there is another enabled breakpoint at the | |
410 | same address. (In that case, _GDBN__ might see the other breakpoint first and | |
411 | stop the program without checking the condition of this one.) Note that | |
412 | breakpoint commands are usually more convenient and flexible for the | |
413 | purpose of performing side effects when a breakpoint is reached | |
414 | (@pxref{Break Commands}). | |
415 | ||
416 | Break conditions can be specified when a breakpoint is set, by using | |
417 | @samp{if} in the arguments to the @code{break} command. @xref{Set Breaks}. | |
418 | They can also be changed at any time with the @code{condition} command. | |
419 | The @code{watch} command doesn't recognize the @code{if} keyword; | |
420 | @code{condition} is the only way to impose a further condition on a | |
421 | watchpoint. | |
422 | ||
423 | @table @code | |
424 | @item condition @var{bnum} @var{expression} | |
425 | @kindex condition | |
426 | Specify @var{expression} as the break condition for breakpoint or | |
427 | watchpoint number @var{bnum}. From now on, this breakpoint will stop | |
428 | the program only if the value of @var{expression} is true (nonzero, in | |
429 | C). When you call @code{condition}, the expression you specify is | |
430 | checked immediately for syntactic correctness, and to determine whether | |
431 | symbols in it have referents in the context of your breakpoint. _GDBN__ | |
432 | does not actually evaluate @var{expression} at the time the | |
433 | @code{condition} command is given, however. @xref{Expressions}. | |
434 | ||
435 | @item condition @var{bnum} | |
436 | Remove the condition from breakpoint number @var{bnum}. It becomes | |
437 | an ordinary unconditional breakpoint. | |
438 | @end table | |
439 | ||
440 | @cindex ignore count (of breakpoint) | |
441 | A special case of a breakpoint condition is to stop only when the | |
442 | breakpoint has been reached a certain number of times. This is so | |
443 | useful that there is a special way to do it, using the @dfn{ignore | |
444 | count} of the breakpoint. Every breakpoint has an ignore count, which | |
445 | is an integer. Most of the time, the ignore count is zero, and | |
446 | therefore has no effect. But if the program reaches a breakpoint whose | |
447 | ignore count is positive, then instead of stopping, it just decrements | |
448 | the ignore count by one and continues. As a result, if the ignore count | |
449 | value is @var{n}, the breakpoint will not stop the next @var{n} times it | |
450 | is reached. | |
451 | ||
452 | @table @code | |
453 | @item ignore @var{bnum} @var{count} | |
454 | @kindex ignore | |
455 | Set the ignore count of breakpoint number @var{bnum} to @var{count}. | |
456 | The next @var{count} times the breakpoint is reached, your program's | |
457 | execution will not stop; other than to decrement the ignore count, _GDBN__ | |
458 | takes no action. | |
459 | ||
460 | To make the breakpoint stop the next time it is reached, specify | |
461 | a count of zero. | |
462 | ||
463 | @item continue @var{count} | |
464 | @itemx c @var{count} | |
465 | @itemx fg @var{count} | |
466 | @kindex continue @var{count} | |
467 | Continue execution of the program, setting the ignore count of the | |
468 | breakpoint that the program stopped at to @var{count} minus one. | |
469 | Thus, the program will not stop at this breakpoint until the | |
470 | @var{count}'th time it is reached. | |
471 | ||
472 | An argument to this command is meaningful only when the program stopped | |
473 | due to a breakpoint. At other times, the argument to @code{continue} is | |
474 | ignored. | |
475 | ||
476 | The synonym @code{fg} is provided purely for convenience, and has | |
477 | exactly the same behavior as other forms of the command. | |
478 | @end table | |
479 | ||
480 | If a breakpoint has a positive ignore count and a condition, the condition | |
481 | is not checked. Once the ignore count reaches zero, the condition will | |
482 | be checked. | |
483 | ||
484 | You could achieve the effect of the ignore count with a | |
485 | condition such as _0__@w{@samp{$foo-- <= 0}}_1__ using a debugger convenience | |
486 | variable that is decremented each time. @xref{Convenience Vars}. | |
487 | ||
488 | @node Break Commands, Breakpoint Menus, Conditions, Breakpoints | |
489 | @subsection Breakpoint Command Lists | |
490 | ||
491 | @cindex breakpoint commands | |
492 | You can give any breakpoint (or watchpoint) a series of commands to | |
493 | execute when the program stops due to that breakpoint. For example, you | |
494 | might want to print the values of certain expressions, or enable other | |
495 | breakpoints. | |
496 | ||
497 | @table @code | |
498 | @item commands @var{bnum} | |
499 | @itemx @dots{} @var{command-list} @dots{} | |
500 | @itemx end | |
501 | @kindex commands | |
502 | @kindex end | |
503 | Specify a list of commands for breakpoint number @var{bnum}. The commands | |
504 | themselves appear on the following lines. Type a line containing just | |
505 | @code{end} to terminate the commands. | |
506 | ||
507 | To remove all commands from a breakpoint, use the command | |
508 | @code{commands} and follow it immediately by @code{end}; that is, give | |
509 | no commands. | |
510 | ||
511 | With no @var{bnum} argument, @code{commands} refers to the last | |
512 | breakpoint or watchpoint set (not to the breakpoint most recently | |
513 | encountered). | |
514 | @end table | |
515 | ||
516 | Pressing @key{RET} as a means of repeating the last _GDBN__ command is | |
517 | disabled from the time you enter @code{commands} to just after the | |
518 | corresponding @code{end}. | |
519 | ||
520 | You can use breakpoint commands to start the program up again. Simply | |
521 | use the @code{continue} command, or @code{step}, or any other command to | |
522 | resume execution. However, if you do this, any further commands in the | |
523 | same breakpoint's command list are ignored. When the program stops | |
524 | again, _GDBN__ will act according to the cause of that stop. | |
525 | ||
526 | @kindex silent | |
527 | If the first command specified is @code{silent}, the usual message about | |
528 | stopping at a breakpoint is not printed. This may be desirable for | |
529 | breakpoints that are to print a specific message and then continue. | |
530 | If the remaining commands too print nothing, you will see no sign that | |
531 | the breakpoint was reached at all. @code{silent} is not really a command; | |
532 | it is meaningful only at the beginning of the commands for a breakpoint. | |
533 | ||
534 | The commands @code{echo} and @code{output} that allow you to print precisely | |
535 | controlled output are often useful in silent breakpoints. @xref{Output}. | |
536 | ||
537 | For example, here is how you could use breakpoint commands to print the | |
538 | value of @code{x} at entry to @code{foo} whenever @code{x} is positive. | |
539 | ||
540 | _0__@example | |
541 | break foo if x>0 | |
542 | commands | |
543 | silent | |
544 | echo x is\040 | |
545 | output x | |
546 | echo \n | |
547 | cont | |
548 | end | |
549 | _1__@end example | |
550 | ||
551 | One application for breakpoint commands is to correct one bug so you can | |
552 | test another. Put a breakpoint just after the erroneous line of code, give | |
553 | it a condition to detect the case in which something erroneous has been | |
554 | done, and give it commands to assign correct values to any variables that | |
555 | need them. End with the @code{continue} command so that the program does not | |
556 | stop, and start with the @code{silent} command so that no output is | |
557 | produced. Here is an example: | |
558 | ||
559 | @example | |
560 | break 403 | |
561 | commands | |
562 | silent | |
563 | set x = y + 4 | |
564 | cont | |
565 | end | |
566 | @end example | |
567 | ||
568 | @cindex lost output | |
569 | One deficiency in the operation of automatically continuing breakpoints | |
570 | under Unix appears when your program uses raw mode for the terminal. | |
571 | _GDBN__ switches back to its own terminal modes (not raw) before executing | |
572 | commands, and then must switch back to raw mode when your program is | |
573 | continued. This causes any pending terminal input to be lost. | |
574 | In the GNU system, this will be fixed by changing the behavior of | |
575 | terminal modes. | |
576 | ||
577 | Under Unix, when you have this problem, you might be able to get around | |
578 | it by putting your actions into the breakpoint condition instead of | |
579 | commands. For example | |
580 | ||
581 | @example | |
582 | condition 5 (x = y + 4), 0 | |
583 | @end example | |
584 | ||
585 | @noindent | |
586 | specifies a condition expression (@xref{Expressions}) that will change | |
587 | @code{x} as needed, then always have the value zero so the program will not | |
588 | stop. Loss of input is avoided here because break conditions are | |
589 | evaluated without changing the terminal modes. When you want to have | |
590 | nontrivial conditions for performing the side effects, the operators | |
591 | @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful. | |
592 | ||
593 | @node Breakpoint Menus, Error in Breakpoints, Break Commands, Breakpoints | |
594 | @subsection Breakpoint Menus | |
595 | @cindex C++ overloading | |
596 | @cindex symbol overloading | |
597 | ||
598 | Some programming languages (notably C++) permit a single function name | |
599 | to be defined several times, for application in different contexts. | |
600 | This is called @dfn{overloading}. When a function name is overloaded, | |
601 | @samp{break @var{function}} is not enough to tell _GDBN__ where you want | |
602 | a breakpoint. _GDBN__ responds to this situation by offering you a menu | |
603 | of numbered choices for different possible breakpoints, and waiting for | |
604 | your selection with the prompt @samp{>}. The first two | |
605 | options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1} | |
606 | will set a breakpoint at all the definitions available for | |
607 | @var{function}, and typing @kbd{0} will abort the @code{break} command | |
608 | without setting any new breakpoints. | |
609 | ||
610 | For example, the following session excerpt shows an attempt to set a | |
611 | breakpoint at the overloaded symbol @code{String::after}. In the | |
612 | example, we choose three particular definitions of the function: | |
613 | ||
614 | @example | |
615 | (_GDBP__) b String::after | |
616 | [0] cancel | |
617 | [1] all | |
618 | [2] file:String.cc; line number:867 | |
619 | [3] file:String.cc; line number:860 | |
620 | [4] file:String.cc; line number:875 | |
621 | [5] file:String.cc; line number:853 | |
622 | [6] file:String.cc; line number:846 | |
623 | [7] file:String.cc; line number:735 | |
624 | > 2 4 6 | |
625 | Breakpoint 1 at 0xb26c: file String.cc, line 867. | |
626 | Breakpoint 2 at 0xb344: file String.cc, line 875. | |
627 | Breakpoint 3 at 0xafcc: file String.cc, line 846. | |
628 | Multiple breakpoints were set. | |
629 | Use the "delete" command to delete unwanted breakpoints. | |
630 | (_GDBP__) | |
631 | @end example | |
632 | ||
633 | ||
634 | @node Error in Breakpoints, , Breakpoint Menus, Breakpoints | |
635 | @subsection ``Cannot Insert Breakpoints'' | |
636 | ||
637 | @c FIXME: "cannot insert breakpoints" error, v unclear. | |
638 | @c Q in pending mail to Gilmore. ---pesch@cygnus.com, 26mar91 | |
639 | Under some operating systems, breakpoints cannot be used in a program if | |
640 | any other process is running that program. In this situation, | |
641 | attempting to run or continue a program with a breakpoint will cause _GDBN__ | |
642 | to stop the other process. | |
643 | ||
644 | When this happens, you have three ways to proceed: | |
645 | ||
646 | @enumerate | |
647 | @item | |
648 | Remove or disable the breakpoints, then continue. | |
649 | ||
650 | @item | |
651 | Suspend _GDBN__, and copy the file containing the program to a new name. | |
652 | Resume _GDBN__ and use the @code{exec-file} command to specify that _GDBN__ | |
653 | should run the program under that name. Then start the program again. | |
654 | ||
655 | @c FIXME: RMS commented here "Show example". Maybe when someone | |
656 | @c explains the first FIXME: in this section... | |
657 | ||
658 | @item | |
659 | Relink the program so that the text segment is nonsharable, using the | |
660 | linker option @samp{-N}. The operating system limitation may not apply | |
661 | to nonsharable executables. | |
662 | @end enumerate | |
663 | ||
664 | @node Stepping, Continuing, Breakpoints, Stopping | |
665 | @section Stepping | |
666 | ||
667 | @cindex stepping | |
668 | @dfn{Stepping} means setting your program in motion for a limited time, | |
669 | so that control will return automatically to _GDBN__ after one line of | |
670 | code or one machine instruction. @footnote{Your program might stop even | |
671 | sooner, during stepping, since a signal may arrive before your program | |
672 | reaches the next source line. Also, since breakpoints are active during | |
673 | stepping, your program will stop for them even if it has not gone as far | |
674 | as the stepping command specifies.} | |
675 | ||
676 | A typical technique for using stepping is to put a breakpoint | |
677 | (@pxref{Breakpoints}) at the beginning of the function or the section of | |
678 | the program in which a problem is believed to lie, run the program until | |
679 | it stops at that breakpoint, and then step through the suspect area, | |
680 | examining the variables that are interesting, until you see the problem | |
681 | happen. | |
682 | ||
683 | @table @code | |
684 | @item step | |
685 | @kindex step | |
686 | @kindex s | |
687 | Continue running the program until control reaches a different source | |
688 | line, then stop it and return control to the debugger. This command is | |
689 | abbreviated @code{s}. | |
690 | ||
691 | You may use the @code{step} command when control is within a function | |
692 | for which there is no debugging information. In that case, execution | |
693 | will proceed until control reaches a different function, or is about to | |
694 | return from this function. | |
695 | ||
696 | @item step @var{count} | |
697 | Continue running as in @code{step}, but do so @var{count} times. If a | |
698 | breakpoint is reached or a signal not related to stepping occurs before | |
699 | @var{count} steps, stepping stops right away. | |
700 | ||
701 | @item next | |
702 | @kindex next | |
703 | @kindex n | |
704 | Continue to the next source line in the current stack frame. Similar to | |
705 | @code{step}, but any function calls appearing within the line of code | |
706 | are executed without stopping. Execution stops when control reaches a | |
707 | different line of code at the stack level which was executing when the | |
708 | @code{next} command was given. This command is abbreviated @code{n}. | |
709 | ||
710 | An argument is a repeat count, as in @code{step}. | |
711 | ||
712 | @code{next} within a function that lacks debugging information acts like | |
713 | @code{step}, but any function calls appearing within the code of the | |
714 | function are executed without stopping. | |
715 | ||
716 | @item finish | |
717 | @kindex finish | |
718 | Continue running until just after the selected stack frame returns (or | |
719 | until there is some other reason to stop, such as a fatal signal or a | |
720 | breakpoint). Print the value returned by the selected stack frame (if | |
721 | any). | |
722 | ||
723 | Contrast this with the @code{return} command (@pxref{Returning}). | |
724 | ||
725 | @item until | |
726 | @kindex until | |
727 | @item u | |
728 | @kindex u | |
729 | Continue running until a source line past the current line, in the | |
730 | current stack frame, is reached. This command is used to avoid single | |
731 | stepping through a loop more than once. It is like the @code{next} | |
732 | command, except that when @code{until} encounters a jump, it | |
733 | automatically continues execution until the program counter is greater | |
734 | than the address of the jump. | |
735 | ||
736 | This means that when you reach the end of a loop after single stepping | |
737 | though it, @code{until} will cause the program to continue execution | |
738 | until the loop is exited. In contrast, a @code{next} command at the end | |
739 | of a loop will simply step back to the beginning of the loop, which | |
740 | would force you to step through the next iteration. | |
741 | ||
742 | @code{until} always stops the program if it attempts to exit the current | |
743 | stack frame. | |
744 | ||
745 | @code{until} may produce somewhat counterintuitive results if the order | |
746 | of the source lines does not match the actual order of execution. For | |
747 | example, in the following excerpt from a debugging session, the @code{f} | |
748 | (@code{frame}) command shows that execution is stopped at line | |
749 | @code{206}; yet when we use @code{until}, we get to line @code{195}: | |
750 | ||
751 | @example | |
752 | (_GDBP__) f | |
753 | #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 | |
754 | 206 expand_input(); | |
755 | (_GDBP__) until | |
756 | 195 for ( ; argc > 0; NEXTARG) @{ | |
757 | @end example | |
758 | ||
759 | In this case, (as for any C @code{for}-loop), the loop-step expression | |
760 | (here, @samp{argc > 0}) is executed @emph{after} the statements in the | |
761 | body of the loop, but is written before them. Therefore, the | |
762 | @code{until} command appeared to step back to the beginning of the loop | |
763 | when it advanced to this expression. However, it has not really gone to | |
764 | an earlier statement---not in terms of the actual machine code. | |
765 | ||
766 | @code{until} with no argument works by means of single | |
767 | instruction stepping, and hence is slower than @code{until} with an | |
768 | argument. | |
769 | ||
770 | @item until @var{location} | |
771 | @item u @var{location} | |
772 | Continue running the program until either the specified location is | |
773 | reached, or the current (innermost) stack frame returns. @var{location} | |
774 | is any of the forms of argument acceptable to @code{break} (@pxref{Set | |
775 | Breaks}). This form of the command uses breakpoints, and hence is | |
776 | quicker than @code{until} without an argument. | |
777 | ||
778 | @item stepi | |
779 | @itemx si | |
780 | @kindex stepi | |
781 | @kindex si | |
782 | Execute one machine instruction, then stop and return to the debugger. | |
783 | ||
784 | It is often useful to do @samp{display/i $pc} when stepping by machine | |
785 | instructions. This will cause the next instruction to be executed to | |
786 | be displayed automatically at each stop. @xref{Auto Display}. | |
787 | ||
788 | An argument is a repeat count, as in @code{step}. | |
789 | ||
790 | @item nexti | |
791 | @itemx ni | |
792 | @kindex nexti | |
793 | @kindex ni | |
794 | Execute one machine instruction, but if it is a function call, | |
795 | proceed until the function returns. | |
796 | ||
797 | An argument is a repeat count, as in @code{next}. | |
798 | @end table | |
799 | ||
800 | The @code{continue} command can be used after stepping to resume execution | |
801 | until the next breakpoint or signal. | |
802 | ||
803 | @node Continuing, Signals, Stepping, Stopping | |
804 | @section Continuing | |
805 | ||
806 | After your program stops, most likely you will want it to run some more if | |
807 | the bug you are looking for has not happened yet. | |
808 | ||
809 | @table @code | |
810 | @item continue | |
811 | @kindex continue | |
812 | Continue running the program at the place where it stopped. | |
813 | @end table | |
814 | ||
815 | If the program stopped at a breakpoint, the place to continue running | |
816 | is the address of the breakpoint. You might expect that continuing would | |
817 | just stop at the same breakpoint immediately. In fact, @code{continue} | |
818 | takes special care to prevent that from happening. You do not need | |
819 | to disable the breakpoint to proceed through it after stopping there. | |
820 | You can, however, specify an ignore-count for the breakpoint that the | |
821 | program stopped at, by means of an argument to the @code{continue} command. | |
822 | @xref{Conditions}. | |
823 | ||
824 | If the program stopped because of a signal other than @code{SIGINT} or | |
825 | @code{SIGTRAP}, continuing will cause the program to see that signal. | |
826 | You may not want this to happen. For example, if the program stopped | |
827 | due to some sort of memory reference error, you might store correct | |
828 | values into the erroneous variables and continue, hoping to see more | |
829 | execution; but the program would probably terminate immediately as | |
830 | a result of the fatal signal once it sees the signal. To prevent this, | |
831 | you can continue with @samp{signal 0}. @xref{Signaling}. You can | |
832 | also act in advance to control what signals your program will see, using | |
833 | the @code{handle} command (@pxref{Signals}). | |
834 | ||
835 | @node Signals, , Continuing, Stopping | |
836 | @section Signals | |
837 | @cindex signals | |
838 | ||
839 | A signal is an asynchronous event that can happen in a program. The | |
840 | operating system defines the possible kinds of signals, and gives each | |
841 | kind a name and a number. For example, in Unix @code{SIGINT} is the | |
842 | signal a program gets when you type an interrupt (often @kbd{C-c}); | |
843 | @code{SIGSEGV} is the signal a program gets from referencing a place in | |
844 | memory far away from all the areas in use; @code{SIGALRM} occurs when | |
845 | the alarm clock timer goes off (which happens only if the program has | |
846 | requested an alarm). | |
847 | ||
848 | @cindex fatal signals | |
849 | Some signals, including @code{SIGALRM}, are a normal part of the | |
850 | functioning of the program. Others, such as @code{SIGSEGV}, indicate | |
851 | errors; these signals are @dfn{fatal} (kill the program immediately) if the | |
852 | program has not specified in advance some other way to handle the signal. | |
853 | @code{SIGINT} does not indicate an error in the program, but it is normally | |
854 | fatal so it can carry out the purpose of the interrupt: to kill the program. | |
855 | ||
856 | _GDBN__ has the ability to detect any occurrence of a signal in the program | |
857 | running under _GDBN__'s control. You can tell _GDBN__ in advance what to do for | |
858 | each kind of signal. | |
859 | ||
860 | @cindex handling signals | |
861 | Normally, _GDBN__ is set up to ignore non-erroneous signals like @code{SIGALRM} | |
862 | (so as not to interfere with their role in the functioning of the program) | |
863 | but to stop the program immediately whenever an error signal happens. | |
864 | You can change these settings with the @code{handle} command. | |
865 | ||
866 | @table @code | |
867 | @item info signals | |
868 | @kindex info signals | |
869 | Print a table of all the kinds of signals and how _GDBN__ has been told to | |
870 | handle each one. You can use this to see the signal numbers of all | |
871 | the defined types of signals. | |
872 | ||
873 | @item handle @var{signal} @var{keywords}@dots{} | |
874 | @kindex handle | |
875 | Change the way _GDBN__ handles signal @var{signal}. @var{signal} can be the | |
876 | number of a signal or its name (with or without the @samp{SIG} at the | |
877 | beginning). The @var{keywords} say what change to make. | |
878 | @end table | |
879 | ||
880 | @group | |
881 | The keywords allowed by the @code{handle} command can be abbreviated. | |
882 | Their full names are: | |
883 | ||
884 | @table @code | |
885 | @item nostop | |
886 | _GDBN__ should not stop the program when this signal happens. It may | |
887 | still print a message telling you that the signal has come in. | |
888 | ||
889 | @item stop | |
890 | _GDBN__ should stop the program when this signal happens. This implies | |
891 | the @code{print} keyword as well. | |
892 | ||
893 | @item print | |
894 | _GDBN__ should print a message when this signal happens. | |
895 | ||
896 | @item noprint | |
897 | _GDBN__ should not mention the occurrence of the signal at all. This | |
898 | implies the @code{nostop} keyword as well. | |
899 | ||
900 | @item pass | |
901 | _GDBN__ should allow the program to see this signal; the program will be | |
902 | able to handle the signal, or may be terminated if the signal is fatal | |
903 | and not handled. | |
904 | ||
905 | @item nopass | |
906 | _GDBN__ should not allow the program to see this signal. | |
907 | @end table | |
908 | @end group | |
909 | ||
910 | When a signal has been set to stop the program, the program cannot see the | |
911 | signal until you continue. It will see the signal then, if @code{pass} is | |
912 | in effect for the signal in question @i{at that time}. In other words, | |
913 | after _GDBN__ reports a signal, you can use the @code{handle} command with | |
914 | @code{pass} or @code{nopass} to control whether that signal will be seen by | |
915 | the program when you later continue it. | |
916 | ||
917 | You can also use the @code{signal} command to prevent the program from | |
918 | seeing a signal, or cause it to see a signal it normally would not see, | |
919 | or to give it any signal at any time. @xref{Signaling}. | |
920 |