diff options
Diffstat (limited to 'gdb/doc/gdb.stop-m4')
| -rwxr-xr-x | gdb/doc/gdb.stop-m4 | 920 |
1 files changed, 0 insertions, 920 deletions
diff --git a/gdb/doc/gdb.stop-m4 b/gdb/doc/gdb.stop-m4 index 934d786..e69de29 100755 --- a/gdb/doc/gdb.stop-m4 +++ b/gdb/doc/gdb.stop-m4 @@ -1,920 +0,0 @@ -_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. -@c M4 FRAGMENT: $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 - -@c @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 -@c @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}. - |