diff options
Diffstat (limited to 'gdb/doc/gdb.stop-m4')
| -rwxr-xr-x | gdb/doc/gdb.stop-m4 | 920 |
1 files changed, 920 insertions, 0 deletions
diff --git a/gdb/doc/gdb.stop-m4 b/gdb/doc/gdb.stop-m4 new file mode 100755 index 0000000..13ad8a4 --- /dev/null +++ b/gdb/doc/gdb.stop-m4 @@ -0,0 +1,920 @@ +_dnl__ -*- Texinfo -*- +_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc. +_dnl__ This file is part of the source for the GDB manual. +_dnl__ $Id$ +@node Stopping, Stack, Running, Top +@chapter Stopping and Continuing + +When you run a program normally, it runs until it terminates. The +principal purpose of using a debugger is so that you can stop your +program before it terminates; or so that, if the program runs into +trouble, you can investigate and find out why. + +Inside _GDBN__, your program may stop for any of several reasons, such +as a signal, a breakpoint, or reaching a new line after a _GDBN__ +command such as @code{step}. Usually, the messages shown by _GDBN__ +provide ample explanation of the status of your program---but you can +also explicitly request this information at any time. + +@table @code +@item info program +@kindex info program +Display information about the status of your program: whether it is +running or not, what process it is, and why it stopped. +@end table + +@menu +* Breakpoints:: Breakpoints, Watchpoints, and Exceptions +* Stepping:: Stepping +* Continuing:: Continuing +* Signals:: Signals +@end menu + +@node Breakpoints, Stepping, Stopping, Stopping +@section Breakpoints, Watchpoints, and Exceptions + +@cindex breakpoints +A @dfn{breakpoint} makes your program stop whenever a certain point in +the program is reached. For each breakpoint, you can add various +conditions to control in finer detail whether the program will stop. +You can set breakpoints with the @code{break} command and its variants +(@pxref{Set Breaks}), to specify the place where the program should stop +by line number, function name or exact address in the program. In +languages with exception handling (such as GNU C++), you can also set +breakpoints where an execption is raised (@pxref{Exception Handling}). + +@cindex watchpoints +A @dfn{watchpoint} is a special breakpoint that stops your program when +the value of an expression changes. You must use a different command to +set watchpoints (@pxref{Set Watchpoints}), but aside from that, you can +manage a watchpoint exactly like any other breakpoint: you enable, disable, and +delete both breakpoints and watchpoints using exactly the same commands. + +Each breakpoint or watchpoint is assigned a number when it is created; +these numbers are successive integers starting with one. In many of the +commands for controlling various features of breakpoints you use the +breakpoint number to say which breakpoint you want to change. Each +breakpoint may be @dfn{enabled} or @dfn{disabled}; if disabled, it has +no effect on the program until you enable it again. + +@menu +* Set Breaks:: Setting Breakpoints +* Set Watchpoints:: Setting Watchpoints +* Exception Handling:: Breakpoints and Exceptions +* Delete Breaks:: Deleting Breakpoints +* Disabling:: Disabling Breakpoints +* Conditions:: Break Conditions +* Break Commands:: Breakpoint Command Lists +* Breakpoint Menus:: Breakpoint Menus +* Error in Breakpoints:: +@end menu + +@node Set Breaks, Set Watchpoints, Breakpoints, Breakpoints +@subsection Setting Breakpoints + +@kindex break +@kindex b +Breakpoints are set with the @code{break} command (abbreviated @code{b}). + +You have several ways to say where the breakpoint should go. + +@table @code +@item break @var{function} +Set a breakpoint at entry to function @var{function}. When using source +languages that permit overloading of symbols, such as C++, +@var{function} may refer to more than one possible place to break. +@xref{Breakpoint Menus}, for a discussion of that situation. + +@item break +@var{offset} +@itemx break -@var{offset} +Set a breakpoint some number of lines forward or back from the position +at which execution stopped in the currently selected frame. + +@item break @var{linenum} +Set a breakpoint at line @var{linenum} in the current source file. +That file is the last file whose source text was printed. This +breakpoint will stop the program just before it executes any of the +code on that line. + +@item break @var{filename}:@var{linenum} +Set a breakpoint at line @var{linenum} in source file @var{filename}. + +@item break @var{filename}:@var{function} +Set a breakpoint at entry to function @var{function} found in file +@var{filename}. Specifying a file name as well as a function name is +superfluous except when multiple files contain similarly named +functions. + +@item break *@var{address} +Set a breakpoint at address @var{address}. You can use this to set +breakpoints in parts of the program which do not have debugging +information or source files. + +@item break +When called without any arguments, @code{break} sets a breakpoint at the +next instruction to be executed in the selected stack frame +(@pxref{Stack}). In any selected frame but the innermost, this will +cause the program to stop as soon as control returns to that frame. +This is similar to the effect of a @code{finish} command in the frame +inside the selected frame---except that @code{finish} doesn't leave an +active breakpoint. If you use @code{break} without an argument in the +innermost frame, _GDBN__ will stop the next time it reaches the current +location; this may be useful inside loops. + +_GDBN__ normally ignores breakpoints when it resumes execution, until at +least one instruction has been executed. If it did not do this, you +would be unable to proceed past a breakpoint without first disabling the +breakpoint. This rule applies whether or not the breakpoint already +existed when the program stopped. + +@item break @dots{} if @var{cond} +Set a breakpoint with condition @var{cond}; evaluate the expression +@var{cond} each time the breakpoint is reached, and stop only if the +value is nonzero. @samp{@dots{}} stands for one of the possible +arguments described above (or no argument) specifying where to break. +@xref{Conditions}, for more information on breakpoint conditions. + +@item tbreak @var{args} +@kindex tbreak +Set a breakpoint enabled only for one stop. @var{args} are the +same as in the @code{break} command, and the breakpoint is set in the same +way, but the breakpoint is automatically disabled the first time it +is hit. @xref{Disabling}. + +@item rbreak @var{regex} +@kindex rbreak +Set a breakpoint on all functions matching @var{regex}. This is +useful for setting breakpoints on overloaded functions that are not +members of any special classes. This command sets an unconditional +breakpoint on all matches, printing a list of all breakpoints it set. +Once these breakpoints are set, they are treated just like the +breakpoints set with the @code{break} command. They can be deleted, +disabled, made conditional, etc., in the standard ways. + +@kindex info breakpoints +@kindex $_ +@item info breakpoints +The command @code{info breakpoints} prints a list of all breakpoints +(but not watchpoints) set and not deleted, showing their numbers, where +in the program they are, and any special features in use for them. +Disabled breakpoints are included in the list, but marked as disabled. +@code{info break} with a breakpoint number as argument lists only that +breakpoint. The convenience variable @code{$_} and the default +examining-address for the @code{x} command are set to the address of the +last breakpoint listed (@pxref{Memory}). The equivalent command for +watchpoints is @code{info watch}. +@end table + +_GDBN__ allows you to set any number of breakpoints at the same place in the +program. There is nothing silly or meaningless about this. When the +breakpoints are conditional, this is even useful (@pxref{Conditions}). + +@node Set Watchpoints, Exception Handling, Set Breaks, Breakpoints +@subsection Setting Watchpoints +@cindex setting watchpoints +You can use a watchpoint to stop execution whenever the value of an +expression changes, without having to predict a particular place in the +inferior process where this may happen. + +Watchpoints currently execute two orders of magnitude more slowly than +other breakpoints, but this can well be worth it to catch errors where +you have no clue what part of your program is the culprit. Some +processors provide special hardware to implement this feature; future +releases of _GDBN__ will use such hardware if it is available. + +@table @code +@kindex watch +@item watch @var{expr} +Set a watchpoint for an expression. + +@kindex info watchpoints +@item info watchpoints +This command prints a list of watchpoints; it is otherwise similar to +@code{info break}. +@end table + +@node Exception Handling, Delete Breaks, Set Watchpoints, Breakpoints +@subsection Breakpoints and Exceptions +@cindex exception handlers + +Some languages, such as GNU C++, implement exception handling. _GDBN__ +can be used to examine what caused the program to raise an exception +and to list the exceptions the program is prepared to handle at a +given point in time. + +@table @code +@item catch @var{exceptions} +@kindex catch + +You can set breakpoints at active exception handlers by using the +@code{catch} command. @var{exceptions} is a list of names of exceptions +to catch. +@end table + +You can use @code{info catch} to list active exception handlers; +@pxref{Frame Info}. + +There are currently some limitations to exception handling in _GDBN__. +These will be corrected in a future release. + +@itemize @bullet +@item +If you call a function interactively, _GDBN__ normally returns +control to you when the function has finished executing. If the call +raises an exception, however, the call may bypass the mechanism that +returns control to the user and cause the program to simply continue +running until it hits a breakpoint, catches a signal that _GDBN__ is +listening for, or exits. +@item +You cannot raise an exception interactively. +@item +You cannot interactively install an exception handler. +@end itemize + +@cindex raise exceptions +Sometimes @code{catch} is not the best way to debug exception handling: +if you need to know exactly where an exception is raised, it's better to +stop @emph{before} the exception handler is called, since that way you +can see the stack before any unwinding takes place. If you set a +breakpoint in an exception handler instead, it may not be easy to find +out where the exception was raised. + +To stop just before an exception handler is called, you need some +knowledge of the implementation. In the case of GNU C++ exception are +raised by calling a library function named @code{__raise_exception} +which has the following ANSI C interface: + +@example + /* ADDR is where the exception identifier is stored. + ID is the exception identifier. */ + void __raise_exception (void **@var{addr}, void *@var{id}); +@end example + +@noindent +To make the debugger catch all exceptions before any stack +unwinding takes place, set a breakpoint on @code{__raise_exception} +(@pxref{Breakpoints}). + +With a conditional breakpoint (@xref{Conditions}) that depends on the +value of @var{id}, you can stop your program when a specific exception +is raised. You can use multiple conditional breakpoints to stop the +program when any of a number of exceptions are raised. + +@node Delete Breaks, Disabling, Exception Handling, Breakpoints +@subsection Deleting Breakpoints + +@cindex clearing breakpoints, watchpoints +@cindex deleting breakpoints, watchpoints +It is often necessary to eliminate a breakpoint or watchpoint once it +has done its job and you no longer want the program to stop there. This +is called @dfn{deleting} the breakpoint. A breakpoint that has been +deleted no longer exists in any sense; it is forgotten. + +With the @code{clear} command you can delete breakpoints according to +where they are in the program. With the @code{delete} command you can +delete individual breakpoints or watchpoints by specifying their +breakpoint numbers. + +It is not necessary to delete a breakpoint to proceed past it. _GDBN__ +automatically ignores breakpoints on the first instruction to be executed +when you continue execution without changing the execution address. + +@table @code +@item clear +@kindex clear +Delete any breakpoints at the next instruction to be executed in the +selected stack frame (@pxref{Selection}). When the innermost frame +is selected, this is a good way to delete a breakpoint that the program +just stopped at. + +@item clear @var{function} +@itemx clear @var{filename}:@var{function} +Delete any breakpoints set at entry to the function @var{function}. + +@item clear @var{linenum} +@itemx clear @var{filename}:@var{linenum} +Delete any breakpoints set at or within the code of the specified line. + +@item delete breakpoints @var{bnums}@dots{} +@itemx delete @var{bnums}@dots{} +@itemx delete +@cindex delete breakpoints +@kindex delete +@kindex d +Delete the breakpoints or watchpoints of the numbers specified as +arguments. If no argument is specified, delete all breakpoints. You +can abbreviate this command as @code{d}. +@end table + +@node Disabling, Conditions, Delete Breaks, Breakpoints +@subsection Disabling Breakpoints + +@cindex disabled breakpoints +@cindex enabled breakpoints +Rather than deleting a breakpoint or watchpoint, you might prefer to +@dfn{disable} it. This makes the breakpoint inoperative as if it had +been deleted, but remembers the information on the breakpoint so that +you can @dfn{enable} it again later. + +You disable and enable breakpoints and watchpoints with the +@code{enable} and @code{disable} commands, optionally specifying one or +more breakpoint numbers as arguments. Use @code{info break} or +@code{info watch} to print a list of breakpoints or watchpoints if you +don't know which numbers to use. + +A breakpoint or watchpoint can have any of four different states of +enablement: + +@itemize @bullet +@item +Enabled. The breakpoint will stop the program. A breakpoint made +with the @code{break} command starts out in this state. +@item +Disabled. The breakpoint has no effect on the program. +@item +Enabled once. The breakpoint will stop the program, but +when it does so it will become disabled. A breakpoint made +with the @code{tbreak} command starts out in this state. +@item +Enabled for deletion. The breakpoint will stop the program, but +immediately after it does so it will be deleted permanently. +@end itemize + +You can use the following commands to enable or disable breakpoints and +watchpoints: + +@table @code +@item disable breakpoints @var{bnums}@dots{} +@itemx disable @var{bnums}@dots{} +@itemx disable +@kindex disable breakpoints +@kindex disable +@kindex dis +Disable the specified breakpoints---or all breakpoints, if none are +listed. A disabled breakpoint has no effect but is not forgotten. All +options such as ignore-counts, conditions and commands are remembered in +case the breakpoint is enabled again later. You may abbreviate +@code{disable} as @code{dis}. + +@item enable breakpoints @var{bnums}@dots{} +@itemx enable @var{bnums}@dots{} +@itemx enable +@kindex enable breakpoints +@kindex enable +Enable the specified breakpoints (or all defined breakpoints). They +become effective once again in stopping the program, until you specify +otherwise. + +@item enable breakpoints once @var{bnums}@dots{} +@itemx enable once @var{bnums}@dots{} +Enable the specified breakpoints temporarily. Each will be disabled +again the next time it stops the program (unless you have used one of +these commands to specify a different state before that time comes). + +@item enable breakpoints delete @var{bnums}@dots{} +@itemx enable delete @var{bnums}@dots{} +Enable the specified breakpoints to work once and then die. Each of +the breakpoints will be deleted the next time it stops the program +(unless you have used one of these commands to specify a different +state before that time comes). +@end table + +Save for a breakpoint set with @code{tbreak} (@pxref{Set Breaks}), +breakpoints that you set initially enabled; subsequently, they become +disabled or enabled only when you use one of the commands above. (The +command @code{until} can set and delete a breakpoint of its own, but it +will not change the state of your other breakpoints; +@pxref{Stepping}.) + +@node Conditions, Break Commands, Disabling, Breakpoints +@subsection Break Conditions +@cindex conditional breakpoints +@cindex breakpoint conditions + +The simplest sort of breakpoint breaks every time the program reaches a +specified place. You can also specify a @dfn{condition} for a +breakpoint. A condition is just a Boolean expression in your +programming language. (@xref{Expressions}). A breakpoint with a +condition evaluates the expression each time the program reaches it, and +the program stops only if the condition is true. + +Conditions are also accepted for watchpoints; you may not need them, +since a watchpoint is inspecting the value of an expression anyhow---but +it might be simpler, say, to just set a watchpoint on a variable name, +then have a condition that tests whether the new value is an interesting +one. + +Break conditions may have side effects, and may even call functions in your +program. These may sound like strange things to do, but their effects are +completely predictable unless there is another enabled breakpoint at the +same address. (In that case, _GDBN__ might see the other breakpoint first and +stop the program without checking the condition of this one.) Note that +breakpoint commands are usually more convenient and flexible for the +purpose of performing side effects when a breakpoint is reached +(@pxref{Break Commands}). + +Break conditions can be specified when a breakpoint is set, by using +@samp{if} in the arguments to the @code{break} command. @xref{Set Breaks}. +They can also be changed at any time with the @code{condition} command. +The @code{watch} command doesn't recognize the @code{if} keyword; +@code{condition} is the only way to impose a further condition on a +watchpoint. + +@table @code +@item condition @var{bnum} @var{expression} +@kindex condition +Specify @var{expression} as the break condition for breakpoint or +watchpoint number @var{bnum}. From now on, this breakpoint will stop +the program only if the value of @var{expression} is true (nonzero, in +C). When you call @code{condition}, the expression you specify is +checked immediately for syntactic correctness, and to determine whether +symbols in it have referents in the context of your breakpoint. _GDBN__ +does not actually evaluate @var{expression} at the time the +@code{condition} command is given, however. @xref{Expressions}. + +@item condition @var{bnum} +Remove the condition from breakpoint number @var{bnum}. It becomes +an ordinary unconditional breakpoint. +@end table + +@cindex ignore count (of breakpoint) +A special case of a breakpoint condition is to stop only when the +breakpoint has been reached a certain number of times. This is so +useful that there is a special way to do it, using the @dfn{ignore +count} of the breakpoint. Every breakpoint has an ignore count, which +is an integer. Most of the time, the ignore count is zero, and +therefore has no effect. But if the program reaches a breakpoint whose +ignore count is positive, then instead of stopping, it just decrements +the ignore count by one and continues. As a result, if the ignore count +value is @var{n}, the breakpoint will not stop the next @var{n} times it +is reached. + +@table @code +@item ignore @var{bnum} @var{count} +@kindex ignore +Set the ignore count of breakpoint number @var{bnum} to @var{count}. +The next @var{count} times the breakpoint is reached, your program's +execution will not stop; other than to decrement the ignore count, _GDBN__ +takes no action. + +To make the breakpoint stop the next time it is reached, specify +a count of zero. + +@item continue @var{count} +@itemx c @var{count} +@itemx fg @var{count} +@kindex continue @var{count} +Continue execution of the program, setting the ignore count of the +breakpoint that the program stopped at to @var{count} minus one. +Thus, the program will not stop at this breakpoint until the +@var{count}'th time it is reached. + +An argument to this command is meaningful only when the program stopped +due to a breakpoint. At other times, the argument to @code{continue} is +ignored. + +The synonym @code{fg} is provided purely for convenience, and has +exactly the same behavior as other forms of the command. +@end table + +If a breakpoint has a positive ignore count and a condition, the condition +is not checked. Once the ignore count reaches zero, the condition will +be checked. + +You could achieve the effect of the ignore count with a +condition such as _0__@w{@samp{$foo-- <= 0}}_1__ using a debugger convenience +variable that is decremented each time. @xref{Convenience Vars}. + +@node Break Commands, Breakpoint Menus, Conditions, Breakpoints +@subsection Breakpoint Command Lists + +@cindex breakpoint commands +You can give any breakpoint (or watchpoint) a series of commands to +execute when the program stops due to that breakpoint. For example, you +might want to print the values of certain expressions, or enable other +breakpoints. + +@table @code +@item commands @var{bnum} +@itemx @dots{} @var{command-list} @dots{} +@itemx end +@kindex commands +@kindex end +Specify a list of commands for breakpoint number @var{bnum}. The commands +themselves appear on the following lines. Type a line containing just +@code{end} to terminate the commands. + +To remove all commands from a breakpoint, use the command +@code{commands} and follow it immediately by @code{end}; that is, give +no commands. + +With no @var{bnum} argument, @code{commands} refers to the last +breakpoint or watchpoint set (not to the breakpoint most recently +encountered). +@end table + +Pressing @key{RET} as a means of repeating the last _GDBN__ command is +disabled from the time you enter @code{commands} to just after the +corresponding @code{end}. + +You can use breakpoint commands to start the program up again. Simply +use the @code{continue} command, or @code{step}, or any other command to +resume execution. However, if you do this, any further commands in the +same breakpoint's command list are ignored. When the program stops +again, _GDBN__ will act according to the cause of that stop. + +@kindex silent +If the first command specified is @code{silent}, the usual message about +stopping at a breakpoint is not printed. This may be desirable for +breakpoints that are to print a specific message and then continue. +If the remaining commands too print nothing, you will see no sign that +the breakpoint was reached at all. @code{silent} is not really a command; +it is meaningful only at the beginning of the commands for a breakpoint. + +The commands @code{echo} and @code{output} that allow you to print precisely +controlled output are often useful in silent breakpoints. @xref{Output}. + +For example, here is how you could use breakpoint commands to print the +value of @code{x} at entry to @code{foo} whenever @code{x} is positive. + +_0__@example +break foo if x>0 +commands +silent +echo x is\040 +output x +echo \n +cont +end +_1__@end example + +One application for breakpoint commands is to correct one bug so you can +test another. Put a breakpoint just after the erroneous line of code, give +it a condition to detect the case in which something erroneous has been +done, and give it commands to assign correct values to any variables that +need them. End with the @code{continue} command so that the program does not +stop, and start with the @code{silent} command so that no output is +produced. Here is an example: + +@example +break 403 +commands +silent +set x = y + 4 +cont +end +@end example + +@cindex lost output +One deficiency in the operation of automatically continuing breakpoints +under Unix appears when your program uses raw mode for the terminal. +_GDBN__ switches back to its own terminal modes (not raw) before executing +commands, and then must switch back to raw mode when your program is +continued. This causes any pending terminal input to be lost. +In the GNU system, this will be fixed by changing the behavior of +terminal modes. + +Under Unix, when you have this problem, you might be able to get around +it by putting your actions into the breakpoint condition instead of +commands. For example + +@example +condition 5 (x = y + 4), 0 +@end example + +@noindent +specifies a condition expression (@xref{Expressions}) that will change +@code{x} as needed, then always have the value zero so the program will not +stop. Loss of input is avoided here because break conditions are +evaluated without changing the terminal modes. When you want to have +nontrivial conditions for performing the side effects, the operators +@samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful. + +@node Breakpoint Menus, Error in Breakpoints, Break Commands, Breakpoints +@subsection Breakpoint Menus +@cindex C++ overloading +@cindex symbol overloading + +Some programming languages (notably C++) permit a single function name +to be defined several times, for application in different contexts. +This is called @dfn{overloading}. When a function name is overloaded, +@samp{break @var{function}} is not enough to tell _GDBN__ where you want +a breakpoint. _GDBN__ responds to this situation by offering you a menu +of numbered choices for different possible breakpoints, and waiting for +your selection with the prompt @samp{>}. The first two +options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1} +will set a breakpoint at all the definitions available for +@var{function}, and typing @kbd{0} will abort the @code{break} command +without setting any new breakpoints. + +For example, the following session excerpt shows an attempt to set a +breakpoint at the overloaded symbol @code{String::after}. In the +example, we choose three particular definitions of the function: + +@example +(_GDBP__) b String::after +[0] cancel +[1] all +[2] file:String.cc; line number:867 +[3] file:String.cc; line number:860 +[4] file:String.cc; line number:875 +[5] file:String.cc; line number:853 +[6] file:String.cc; line number:846 +[7] file:String.cc; line number:735 +> 2 4 6 +Breakpoint 1 at 0xb26c: file String.cc, line 867. +Breakpoint 2 at 0xb344: file String.cc, line 875. +Breakpoint 3 at 0xafcc: file String.cc, line 846. +Multiple breakpoints were set. +Use the "delete" command to delete unwanted breakpoints. +(_GDBP__) +@end example + + +@node Error in Breakpoints, , Breakpoint Menus, Breakpoints +@subsection ``Cannot Insert Breakpoints'' + +@c FIXME: "cannot insert breakpoints" error, v unclear. +@c Q in pending mail to Gilmore. ---pesch@cygnus.com, 26mar91 +Under some operating systems, breakpoints cannot be used in a program if +any other process is running that program. In this situation, +attempting to run or continue a program with a breakpoint will cause _GDBN__ +to stop the other process. + +When this happens, you have three ways to proceed: + +@enumerate +@item +Remove or disable the breakpoints, then continue. + +@item +Suspend _GDBN__, and copy the file containing the program to a new name. +Resume _GDBN__ and use the @code{exec-file} command to specify that _GDBN__ +should run the program under that name. Then start the program again. + +@c FIXME: RMS commented here "Show example". Maybe when someone +@c explains the first FIXME: in this section... + +@item +Relink the program so that the text segment is nonsharable, using the +linker option @samp{-N}. The operating system limitation may not apply +to nonsharable executables. +@end enumerate + +@node Stepping, Continuing, Breakpoints, Stopping +@section Stepping + +@cindex stepping +@dfn{Stepping} means setting your program in motion for a limited time, +so that control will return automatically to _GDBN__ after one line of +code or one machine instruction. @footnote{Your program might stop even +sooner, during stepping, since a signal may arrive before your program +reaches the next source line. Also, since breakpoints are active during +stepping, your program will stop for them even if it has not gone as far +as the stepping command specifies.} + +A typical technique for using stepping is to put a breakpoint +(@pxref{Breakpoints}) at the beginning of the function or the section of +the program in which a problem is believed to lie, run the program until +it stops at that breakpoint, and then step through the suspect area, +examining the variables that are interesting, until you see the problem +happen. + +@table @code +@item step +@kindex step +@kindex s +Continue running the program until control reaches a different source +line, then stop it and return control to the debugger. This command is +abbreviated @code{s}. + +You may use the @code{step} command when control is within a function +for which there is no debugging information. In that case, execution +will proceed until control reaches a different function, or is about to +return from this function. + +@item step @var{count} +Continue running as in @code{step}, but do so @var{count} times. If a +breakpoint is reached or a signal not related to stepping occurs before +@var{count} steps, stepping stops right away. + +@item next +@kindex next +@kindex n +Continue to the next source line in the current stack frame. Similar to +@code{step}, but any function calls appearing within the line of code +are executed without stopping. Execution stops when control reaches a +different line of code at the stack level which was executing when the +@code{next} command was given. This command is abbreviated @code{n}. + +An argument is a repeat count, as in @code{step}. + +@code{next} within a function that lacks debugging information acts like +@code{step}, but any function calls appearing within the code of the +function are executed without stopping. + +@item finish +@kindex finish +Continue running until just after the selected stack frame returns (or +until there is some other reason to stop, such as a fatal signal or a +breakpoint). Print the value returned by the selected stack frame (if +any). + +Contrast this with the @code{return} command (@pxref{Returning}). + +@item until +@kindex until +@item u +@kindex u +Continue running until a source line past the current line, in the +current stack frame, is reached. This command is used to avoid single +stepping through a loop more than once. It is like the @code{next} +command, except that when @code{until} encounters a jump, it +automatically continues execution until the program counter is greater +than the address of the jump. + +This means that when you reach the end of a loop after single stepping +though it, @code{until} will cause the program to continue execution +until the loop is exited. In contrast, a @code{next} command at the end +of a loop will simply step back to the beginning of the loop, which +would force you to step through the next iteration. + +@code{until} always stops the program if it attempts to exit the current +stack frame. + +@code{until} may produce somewhat counterintuitive results if the order +of the source lines does not match the actual order of execution. For +example, in the following excerpt from a debugging session, the @code{f} +(@code{frame}) command shows that execution is stopped at line +@code{206}; yet when we use @code{until}, we get to line @code{195}: + +@example +(_GDBP__) f +#0 main (argc=4, argv=0xf7fffae8) at m4.c:206 +206 expand_input(); +(_GDBP__) until +195 for ( ; argc > 0; NEXTARG) @{ +@end example + +In this case, (as for any C @code{for}-loop), the loop-step expression +(here, @samp{argc > 0}) is executed @emph{after} the statements in the +body of the loop, but is written before them. Therefore, the +@code{until} command appeared to step back to the beginning of the loop +when it advanced to this expression. However, it has not really gone to +an earlier statement---not in terms of the actual machine code. + +@code{until} with no argument works by means of single +instruction stepping, and hence is slower than @code{until} with an +argument. + +@item until @var{location} +@item u @var{location} +Continue running the program until either the specified location is +reached, or the current (innermost) stack frame returns. @var{location} +is any of the forms of argument acceptable to @code{break} (@pxref{Set +Breaks}). This form of the command uses breakpoints, and hence is +quicker than @code{until} without an argument. + +@item stepi +@itemx si +@kindex stepi +@kindex si +Execute one machine instruction, then stop and return to the debugger. + +It is often useful to do @samp{display/i $pc} when stepping by machine +instructions. This will cause the next instruction to be executed to +be displayed automatically at each stop. @xref{Auto Display}. + +An argument is a repeat count, as in @code{step}. + +@item nexti +@itemx ni +@kindex nexti +@kindex ni +Execute one machine instruction, but if it is a function call, +proceed until the function returns. + +An argument is a repeat count, as in @code{next}. +@end table + +The @code{continue} command can be used after stepping to resume execution +until the next breakpoint or signal. + +@node Continuing, Signals, Stepping, Stopping +@section Continuing + +After your program stops, most likely you will want it to run some more if +the bug you are looking for has not happened yet. + +@table @code +@item continue +@kindex continue +Continue running the program at the place where it stopped. +@end table + +If the program stopped at a breakpoint, the place to continue running +is the address of the breakpoint. You might expect that continuing would +just stop at the same breakpoint immediately. In fact, @code{continue} +takes special care to prevent that from happening. You do not need +to disable the breakpoint to proceed through it after stopping there. +You can, however, specify an ignore-count for the breakpoint that the +program stopped at, by means of an argument to the @code{continue} command. +@xref{Conditions}. + +If the program stopped because of a signal other than @code{SIGINT} or +@code{SIGTRAP}, continuing will cause the program to see that signal. +You may not want this to happen. For example, if the program stopped +due to some sort of memory reference error, you might store correct +values into the erroneous variables and continue, hoping to see more +execution; but the program would probably terminate immediately as +a result of the fatal signal once it sees the signal. To prevent this, +you can continue with @samp{signal 0}. @xref{Signaling}. You can +also act in advance to control what signals your program will see, using +the @code{handle} command (@pxref{Signals}). + +@node Signals, , Continuing, Stopping +@section Signals +@cindex signals + +A signal is an asynchronous event that can happen in a program. The +operating system defines the possible kinds of signals, and gives each +kind a name and a number. For example, in Unix @code{SIGINT} is the +signal a program gets when you type an interrupt (often @kbd{C-c}); +@code{SIGSEGV} is the signal a program gets from referencing a place in +memory far away from all the areas in use; @code{SIGALRM} occurs when +the alarm clock timer goes off (which happens only if the program has +requested an alarm). + +@cindex fatal signals +Some signals, including @code{SIGALRM}, are a normal part of the +functioning of the program. Others, such as @code{SIGSEGV}, indicate +errors; these signals are @dfn{fatal} (kill the program immediately) if the +program has not specified in advance some other way to handle the signal. +@code{SIGINT} does not indicate an error in the program, but it is normally +fatal so it can carry out the purpose of the interrupt: to kill the program. + +_GDBN__ has the ability to detect any occurrence of a signal in the program +running under _GDBN__'s control. You can tell _GDBN__ in advance what to do for +each kind of signal. + +@cindex handling signals +Normally, _GDBN__ is set up to ignore non-erroneous signals like @code{SIGALRM} +(so as not to interfere with their role in the functioning of the program) +but to stop the program immediately whenever an error signal happens. +You can change these settings with the @code{handle} command. + +@table @code +@item info signals +@kindex info signals +Print a table of all the kinds of signals and how _GDBN__ has been told to +handle each one. You can use this to see the signal numbers of all +the defined types of signals. + +@item handle @var{signal} @var{keywords}@dots{} +@kindex handle +Change the way _GDBN__ handles signal @var{signal}. @var{signal} can be the +number of a signal or its name (with or without the @samp{SIG} at the +beginning). The @var{keywords} say what change to make. +@end table + +@group +The keywords allowed by the @code{handle} command can be abbreviated. +Their full names are: + +@table @code +@item nostop +_GDBN__ should not stop the program when this signal happens. It may +still print a message telling you that the signal has come in. + +@item stop +_GDBN__ should stop the program when this signal happens. This implies +the @code{print} keyword as well. + +@item print +_GDBN__ should print a message when this signal happens. + +@item noprint +_GDBN__ should not mention the occurrence of the signal at all. This +implies the @code{nostop} keyword as well. + +@item pass +_GDBN__ should allow the program to see this signal; the program will be +able to handle the signal, or may be terminated if the signal is fatal +and not handled. + +@item nopass +_GDBN__ should not allow the program to see this signal. +@end table +@end group + +When a signal has been set to stop the program, the program cannot see the +signal until you continue. It will see the signal then, if @code{pass} is +in effect for the signal in question @i{at that time}. In other words, +after _GDBN__ reports a signal, you can use the @code{handle} command with +@code{pass} or @code{nopass} to control whether that signal will be seen by +the program when you later continue it. + +You can also use the @code{signal} command to prevent the program from +seeing a signal, or cause it to see a signal it normally would not see, +or to give it any signal at any time. @xref{Signaling}. + |