*** empty log message ***

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}.
+