| 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 | @c M4 FRAGMENT: $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 | @c @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 | @c @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 | |