Info file gdb.info, produced by Makeinfo, -*- Text -*- from input
file gdb-all.texi.

   This file documents the GNU debugger GDB.

   Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of
this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this
manual under the conditions for verbatim copying, provided also that
the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for
modified versions, except that the section entitled "GNU General
Public License" may be included in a translation approved by the
Free Software Foundation instead of in the original English.


File: gdb.info,  Node: Kill Process,  Prev: Attach,  Up: Running

Killing the Child Process
=========================

`kill'
     Kill the child process in which your program is running under GDB.

   This command is useful if you wish to debug a core dump instead of
a
running process.  GDB ignores any core dump file while your program
is running.

   On some operating systems, a program can't be executed outside GDB
while
you have breakpoints set on it inside GDB.  You can use the `kill'
command in this situation to permit running the program outside the
debugger.

   The `kill' command is also useful if you wish to recompile and
relink the program, since on many systems it is impossible to modify
an executable file while it is running in a process.  In this case,
when you next type `run', GDB will notice that the file has changed,
and will re-read the symbol table (while trying to preserve your
current breakpoint settings).


File: gdb.info,  Node: Stopping,  Next: Stack,  Prev: Running,  Up: Top

Stopping and Continuing
***********************

   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 GDB, your program may stop for any of several reasons, such
as a signal, a breakpoint, or reaching a new line after a GDB
command such as `step'.  You may then examine and change variables,
set
new breakpoints or remove old ones, and then continue execution. 
Usually, the messages shown by GDB provide ample explanation of the
status of your program--but you can also explicitly request this
information at any time.

`info program'
     Display information about the status of your program: whether it
     is running or not, what process it is, and why it stopped.

* Menu:

* Breakpoints::                 Breakpoints, Watchpoints, and Exceptions
* Continuing and Stepping::     Resuming Execution
* Signals::                     Signals


File: gdb.info,  Node: Breakpoints,  Next: Continuing and Stepping,  Prev: Stopping,  Up: Stopping

Breakpoints, Watchpoints, and Exceptions
========================================

   A "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 `break' command and its variants
(*note 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 exception is raised (*note Exception
Handling::.).

   A "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 (*note Set Watchpoints::.), but aside
from that, you can manage a watchpoint like any other breakpoint:
you enable, disable, and delete both breakpoints and watchpoints
using 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 "enabled" or "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::


File: gdb.info,  Node: Set Breaks,  Next: Set Watchpoints,  Prev: Breakpoints,  Up: Breakpoints

Setting Breakpoints
-------------------

   Breakpoints are set with the `break' command (abbreviated `b').

   You have several ways to say where the breakpoint should go.

`break FUNCTION'
     Set a breakpoint at entry to function FUNCTION.  When using
     source languages that permit overloading of symbols, such as
     C++, FUNCTION may refer to more than one possible place to break.
     *Note Breakpoint Menus::, for a discussion of that situation.

`break +OFFSET'
`break -OFFSET'
     Set a breakpoint some number of lines forward or back from the
     position at which execution stopped in the currently selected
     frame.

`break LINENUM'
     Set a breakpoint at line 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.

`break FILENAME:LINENUM'
     Set a breakpoint at line LINENUM in source file FILENAME.

`break FILENAME:FUNCTION'
     Set a breakpoint at entry to function FUNCTION found in file
     FILENAME.  Specifying a file name as well as a function name is
     superfluous except when multiple files contain similarly named
     functions.

`break *ADDRESS'
     Set a breakpoint at address ADDRESS.  You can use this to set
     breakpoints in parts of the program which do not have debugging
     information or source files.

`break'
     When called without any arguments, `break' sets a breakpoint at
     the next instruction to be executed in the selected stack frame
     (*note 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 `finish'
     command in the frame inside the selected frame--except that
     `finish' doesn't leave an active breakpoint.  If you use
     `break' without an argument in the innermost frame, GDB will
     stop the next time it reaches the current location; this may be
     useful inside loops.

     GDB 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.

`break ... if COND'
     Set a breakpoint with condition COND; evaluate the expression
     COND each time the breakpoint is reached, and stop only if the
     value is nonzero--that is, if COND evaluates as true.  `...'
     stands for one of the possible arguments described above (or no
     argument) specifying where to break.  *Note Conditions::, for
     more information on breakpoint conditions.

`tbreak ARGS'
     Set a breakpoint enabled only for one stop.  ARGS are the same
     as for the `break' command, and the breakpoint is set in the
     same way, but the breakpoint is automatically disabled the
     first time it is hit.  *Note Disabling::.

`rbreak REGEX'
     Set breakpoints on all functions matching the regular expression
     REGEX.  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 `break' command.  They can be deleted, disabled,
     made conditional, etc., in the standard ways.

     When debugging C++ programs, `rbreak' is useful for setting
     breakpoints on overloaded functions that are not members of any
     special classes.

`info breakpoints [N]'
`info break [N]'
     Print 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.
     `info break' with a breakpoint number N as argument lists only
     that breakpoint.  The convenience variable `$_' and the default
    
     examining-address for the `x' command are set to the address of
     the last breakpoint listed (*note Memory::.).  The equivalent
     command for watchpoints is `info watch'.

   GDB 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 (*note
Conditions::.).


File: gdb.info,  Node: Set Watchpoints,  Next: Exception Handling,  Prev: Set Breaks,  Up: Breakpoints

Setting Watchpoints
-------------------

   You can use a watchpoint to stop execution whenever the value of
an expression changes, without having to predict a particular place
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 support
watchpoint evaluation; future releases of GDB will use such hardware
if it is available.

`watch EXPR'
     Set a watchpoint for an expression.

`info watchpoints'
     This command prints a list of watchpoints; it is otherwise
     similar to `info break'.


File: gdb.info,  Node: Exception Handling,  Next: Delete Breaks,  Prev: Set Watchpoints,  Up: Breakpoints

Breakpoints and Exceptions
--------------------------

   Some languages, such as GNU C++, implement exception handling. 
You can use GDB 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.

`catch EXCEPTIONS'
     You can set breakpoints at active exception handlers by using
     the `catch' command.  EXCEPTIONS is a list of names of
     exceptions to catch.

   You can use `info catch' to list active exception handlers; *note
Frame Info::..

   There are currently some limitations to exception handling in GDB.
These will be corrected in a future release.

   * If you call a function interactively, GDB 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 GDB is listening for, or exits.

   * You cannot raise an exception interactively.

   * You cannot interactively install an exception handler.

   Sometimes `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 *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++, exceptions
are raised by calling a library function named `__raise_exception'
which has the following ANSI C interface:

         /* ADDR is where the exception identifier is stored.
            ID is the exception identifier.  */
         void __raise_exception (void **ADDR, void *ID);

To make the debugger catch all exceptions before any stack unwinding
takes place, set a breakpoint on `__raise_exception' (*note
Breakpoints::.).

   With a conditional breakpoint (*Note Conditions::) that depends on
the value of 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.


File: gdb.info,  Node: Delete Breaks,  Next: Disabling,  Prev: Exception Handling,  Up: Breakpoints

Deleting Breakpoints
--------------------

   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 "deleting" the breakpoint.  A breakpoint that
has been deleted no longer exists; it is forgotten.

   With the `clear' command you can delete breakpoints according to
where they are in the program.  With the `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. 
GDB automatically ignores breakpoints on the first instruction to be
executed when you continue execution without changing the execution
address.

`clear'
     Delete any breakpoints at the next instruction to be executed in
     the selected stack frame (*note Selection::.).  When the
     innermost frame is selected, this is a good way to delete a
     breakpoint that the program just stopped at.

`clear FUNCTION'
`clear FILENAME:FUNCTION'
     Delete any breakpoints set at entry to the function FUNCTION.

`clear LINENUM'
`clear FILENAME:LINENUM'
     Delete any breakpoints set at or within the code of the
     specified line.

`delete [breakpoints] [BNUMS...]'
     Delete the breakpoints or watchpoints of the numbers specified
     as arguments.  If no argument is specified, delete all
     breakpoints (GDB asks confirmation, unless you've `set confirm
     off').  You can abbreviate this command as `d'.


File: gdb.info,  Node: Disabling,  Next: Conditions,  Prev: Delete Breaks,  Up: Breakpoints

Disabling Breakpoints
---------------------

   Rather than deleting a breakpoint or watchpoint, you might prefer
to "disable" it.  This makes the breakpoint inoperative as if it had
been deleted, but remembers the information on the breakpoint so
that you can "enable" it again later.

   You disable and enable breakpoints and watchpoints with the
`enable' and `disable' commands, optionally specifying one or more
breakpoint numbers as arguments.  Use `info break' or `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:

   * Enabled.  The breakpoint will stop the program.  A breakpoint
     set with the `break' command starts out in this state.

   * Disabled.  The breakpoint has no effect on the program.

   * Enabled once.  The breakpoint will stop the program, but when it
     does so it will become disabled.  A breakpoint set with the
     `tbreak' command starts out in this state.

   * Enabled for deletion.  The breakpoint will stop the program, but
     immediately after it does so it will be deleted permanently.

   You can use the following commands to enable or disable
breakpoints and watchpoints:

`disable [breakpoints] [BNUMS...]'
     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 `disable' as `dis'.

`enable [breakpoints] [BNUMS...]'
     Enable the specified breakpoints (or all defined breakpoints). 
     They become effective once again in stopping the program.

`enable [breakpoints] once BNUMS...'
     Enable the specified breakpoints temporarily.  Each will be
     disabled again the next time it stops the program.

`enable [breakpoints] delete BNUMS...'
     Enable the specified breakpoints to work once and then die. 
     Each of the breakpoints will be deleted the next time it stops
     the program.

   Save for a breakpoint set with `tbreak' (*note Set Breaks::.),
breakpoints that you set are initially enabled; subsequently, they
become disabled or enabled only when you use one of the commands
above.  (The command `until' can set and delete a breakpoint of its
own,
but it will not change the state of your other breakpoints; *note
Continuing and Stepping::..)


File: gdb.info,  Node: Conditions,  Next: Break Commands,  Prev: Disabling,  Up: Breakpoints

Break Conditions
----------------

   The simplest sort of breakpoint breaks every time the program
reaches a specified place.  You can also specify a "condition" for a
breakpoint.  A condition is just a Boolean expression in your
programming language.  (*Note 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*.

   This is the converse of using assertions for program validation;
in that situation, you want to stop when the assertion is
violated--that is, when the condition is false.  In C, if you want
to test an assertion expressed by the condition ASSERT, you should
set the condition `! ASSERT' on the appropriate breakpoint.

   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, and specify a condition that tests whether the new
value is an interesting one.

   Break conditions ca have side effects, and may even call functions
in your program.  This can be useful, for example, to activate
functions that log program progress, or to use your own print
functions to format special data structures. The effects are
completely
predictable unless there is another enabled breakpoint at the same
address.  (In that case, GDB 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 (*note Break Commands::.).

   Break conditions can be specified when a breakpoint is set, by
using `if' in the arguments to the `break' command.  *Note Set
Breaks::.  They can also be changed at any time with the `condition'
command.  The `watch' command doesn't recognize the `if' keyword;
`condition' is the only way to impose a further condition on a
watchpoint.

`condition BNUM EXPRESSION'
     Specify EXPRESSION as the break condition for breakpoint or
     watchpoint number BNUM.  From now on, this breakpoint will stop
     the program only if the value of EXPRESSION is true (nonzero,
     in C).  When you use `condition', GDB checks EXPRESSION
     immediately for syntactic correctness, and to determine whether
     symbols in it have referents in the context of your breakpoint.
     GDB does not actually evaluate EXPRESSION at the time the
     `condition' command is given, however.  *Note Expressions::.

`condition BNUM'
     Remove the condition from breakpoint number BNUM.  It becomes an
     ordinary unconditional 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 "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 N, the breakpoint will not stop the
next N times it is reached.

`ignore BNUM COUNT'
     Set the ignore count of breakpoint number BNUM to COUNT.  The
     next COUNT times the breakpoint is reached, your program's
     execution will not stop; other than to decrement the ignore
     count, GDB takes no action.

     To make the breakpoint stop the next time it is reached, specify
     a count of zero.

`continue COUNT'
`c COUNT'
`fg COUNT'
     Continue execution of the program, setting the ignore count of
     the breakpoint that the program stopped at to COUNT minus one. 
     Thus, the program will not stop at this breakpoint until the
     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
     `continue' is ignored.

     The synonym `fg' is provided purely for convenience, and has
     exactly the same behavior as other forms of the command.

   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 `$foo-- <= 0' using a debugger convenience variable that is
decremented each time.  *Note Convenience Vars::.


File: gdb.info,  Node: Break Commands,  Next: Breakpoint Menus,  Prev: Conditions,  Up: Breakpoints

Breakpoint Command Lists
------------------------

   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.

`commands [BNUM]'
`... COMMAND-LIST ...'
`end'
     Specify a list of commands for breakpoint number BNUM.  The
     commands themselves appear on the following lines.  Type a line
     containing just `end' to terminate the commands.

     To remove all commands from a breakpoint, type `commands'
     followed immediately by `end'; that is, give no commands.

     With no BNUM argument, `commands' refers to the last breakpoint
     or watchpoint set (not to the breakpoint most recently
     encountered).

   Pressing RET as a means of repeating the last GDB command is
disabled within a COMMAND-LIST.

   You can use breakpoint commands to start the program up again. 
Simply use the `continue' command, or `step', or any other command
that resumes execution.  Subsequent commands in the command list are
ignored.

   If the first command specified is `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.  `silent'
is meaningful only at the beginning of a breakpoint command list.

   The commands `echo' and `output' that allow you to print precisely
controlled output are often useful in silent breakpoints.  *Note
Output::.

   For example, here is how you could use breakpoint commands to
print the value of `x' at entry to `foo' whenever `x' is positive.

     break foo if x>0
     commands
     silent
     echo x is\040
     output x
     echo \n
     cont
     end

   One application for breakpoint commands is to compensate for one
bug so you can test for 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
`continue' command so that the program does not stop, and start with
the `silent' command so that no output is produced.  Here is an
example:

     break 403
     commands
     silent
     set x = y + 4
     cont
     end

   One deficiency in the operation of automatically continuing
breakpoints under Unix appears when your program uses raw mode for
the
terminal.  GDB 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.

   Under Unix, you can get around this problem by writing actions
into the breakpoint condition rather than in commands.  For example

     condition 5  (x = y + 4), 0

specifies a condition expression (*Note Expressions::) that will
change `x' as needed, then always have the value zero so the program
will not stop.  No input is lost here, because GDB evaluates break
conditions  without changing the terminal modes.  When you want to
have nontrivial conditions for performing the side effects, the
operators `&&', `||' and `?...:' may be useful.


File: gdb.info,  Node: Breakpoint Menus,  Next: Error in Breakpoints,  Prev: Break Commands,  Up: Breakpoints

Breakpoint Menus
----------------

   Some programming languages (notably C++) permit a single function
name to be defined several times, for application in different
contexts.  This is called "overloading".  When a function name is
overloaded, `break FUNCTION' is not enough to tell GDB where you
want a breakpoint.  GDB offers you a menu of numbered choices for
different possible breakpoints, and waits for your selection with
the prompt `>'.  The first two options are always `[0] cancel' and
`[1] all'.  Typing `1' sets a breakpoint at each definition of
FUNCTION, and typing `0' aborts the `break' command without setting
any new breakpoints.

   For example, the following session excerpt shows an attempt to set
a breakpoint at the overloaded symbol `String::after'.  We choose
three particular definitions of that function name:

     (gdb) 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.
     (gdb)


File: gdb.info,  Node: Error in Breakpoints,  Prev: Breakpoint Menus,  Up: Breakpoints

"Cannot Insert Breakpoints"
---------------------------

   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
causes GDB to stop the other process.

   When this happens, you have three ways to proceed:

  1. Remove or disable the breakpoints, then continue.

  2. Suspend GDB, and copy the file containing the program to a new
     name.  Resume GDB and use the `exec-file' command to specify
     that GDB should run the program under that name.  Then start
     the program again.

  3. Relink the program so that the text segment is nonsharable,
     using the linker option `-N'.  The operating system limitation
     may not apply to nonsharable executables.


File: gdb.info,  Node: Continuing and Stepping,  Next: Signals,  Prev: Breakpoints,  Up: Stopping

Continuing and Stepping
=======================

   "Continuing" means resuming program execution until your program
completes normally.  In contrast, "stepping" means executing just
one more "step" of your program, where "step" may mean either one
line of source code, or one machine instruction (depending on what
particular command you use).  Either when continuing or when
stepping, the program may stop even sooner, due to a breakpoint or
to a signal.  (If due to a signal, you may want to use `handle', or
use `signal 0' to resume execution; *note Signals::..)

`continue [IGNORE-COUNT]'
     Resume program execution, at the address where the program last
     stopped; any breakpoints set at that address are bypassed.  The
     optional argument IGNORE-COUNT allows you to specify a further
     number of times to ignore a breakpoint at this location; its
     effect is like that of `ignore' (*note Conditions::.).

     To resume execution at a different place, you can use `return'
     (*note Returning::.) to go back to the calling function; or
     `jump' (*note Jumping::.) to go to an arbitrary location in
     your program.

   A typical technique for using stepping is to set a breakpoint
(*note 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.

`step'
     Continue running the program until control reaches a different
     source line, then stop it and return control to GDB.  This
     command is abbreviated `s'.

          *Warning:* If you use the `step' command while control is
          within a function that was compiled without debugging
          information, execution will proceed until control reaches
          another function.

`step COUNT'
     Continue running as in `step', but do so COUNT times.  If a
     breakpoint is reached or a signal not related to stepping
     occurs before COUNT steps, stepping stops right away.

`next [COUNT]'
     Continue to the next source line in the current (innermost)
     stack frame.  Similar to `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
    
     `next' command was given.  This command is abbreviated `n'.

     An argument COUNT is a repeat count, as for `step'.

     `next' within a function that lacks debugging information acts
     like `step', but any function calls appearing within the code
     of the function are executed without stopping.

`finish'
     Continue running until just after function in the selected stack
     frame returns.  Print the returned value (if any).

     Contrast this with the `return' command (*note Returning::.).

`until'
`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 `next' command, except that when `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, `until' will cause the program to continue
     execution until the loop is exited.  In contrast, a `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.

     `until' always stops the program if it attempts to exit the
     current stack frame.

     `until' may produce somewhat counterintuitive results if the
     order of machine code does not match the order of the source
     lines.  For example, in the following excerpt from a debugging
     session, the `f' (`frame') command shows that execution is
     stopped at line `206'; yet when we use `until', we get to line
     `195':

          (gdb) f
          #0  main (argc=4, argv=0xf7fffae8) at m4.c:206
          206                 expand_input();
          (gdb) until
          195             for ( ; argc > 0; NEXTARG) {

     This happened because, for execution efficiency, the compiler
     had generated code for the loop closure test at the end, rather
    
     than the start, of the loop--even though the test in a C
     `for'-loop is written before the body of the loop.  The `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.

     `until' with no argument works by means of single instruction
     stepping, and hence is slower than `until' with an argument.

`until LOCATION'
`u LOCATION'
     Continue running the program until either the specified location
     is reached, or the current stack frame returns.  LOCATION is
     any of the forms of argument acceptable to `break' (*note Set
     Breaks::.).  This form of the command uses breakpoints, and
     hence is quicker than `until' without an argument.

`stepi'
`si'
     Execute one machine instruction, then stop and return to the
     debugger.

     It is often useful to do `display/i $pc' when stepping by
     machine instructions.  This will cause the next instruction to
     be executed to be displayed automatically at each stop.  *Note
     Auto Display::.

     An argument is a repeat count, as in `step'.

`nexti'
`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 `next'.


File: gdb.info,  Node: Signals,  Prev: Continuing and Stepping,  Up: Stopping

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 `SIGINT'
is the signal a program gets when you type an interrupt (often
`C-c'); `SIGSEGV' is the signal a program gets from referencing a
place in memory far away from all the areas in use; `SIGALRM' occurs
when the alarm clock timer goes off (which happens only if the
program has requested an alarm).

   Some signals, including `SIGALRM', are a normal part of the
functioning of the program.  Others, such as `SIGSEGV', indicate
errors; these signals are "fatal" (kill the program immediately) if
the program has not specified in advance some other way to handle
the signal.  `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.

   GDB has the ability to detect any occurrence of a signal in the
program running under GDB's control.  You can tell GDB in advance
what to do for each kind of signal.

   Normally, GDB is set up to ignore non-erroneous signals like
`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
`handle' command.

`info signals'
     Print a table of all the kinds of signals and how GDB has been
     told to handle each one.  You can use this to see the signal
     numbers of all the defined types of signals.

`handle SIGNAL KEYWORDS...'
     Change the way GDB handles signal SIGNAL.  SIGNAL can be the
     number of a signal or its name (with or without the `SIG' at
     the beginning).  The KEYWORDS say what change to make.

   The keywords allowed by the `handle' command can be abbreviated. 
Their full names are:

`nostop'
     GDB should not stop the program when this signal happens.  It
     may still print a message telling you that the signal has come
     in.

`stop'
     GDB should stop the program when this signal happens.  This
     implies the `print' keyword as well.

`print'
     GDB should print a message when this signal happens.

`noprint'
     GDB should not mention the occurrence of the signal at all. 
     This implies the `nostop' keyword as well.

`pass'
     GDB 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.

`nopass'
     GDB should not allow the program to see this signal.

   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
`pass' is in effect for the signal in question at that time.  In
other words, after GDB reports a signal, you can use the `handle'
command with `pass' or `nopass' to control whether that signal will
be seen by the program when you later continue it.

   You can also use the `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.  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 `signal
0'.  *Note Signaling::.


File: gdb.info,  Node: Stack,  Next: Source,  Prev: Stopping,  Up: Top

Examining the Stack
*******************

   When your program has stopped, the first thing you need to know is
where it stopped and how it got there.

   Each time your program performs a function call, the information
about where in the program the call was made from is saved in a
block of data called a "stack frame".  The frame also contains the
arguments of the call and the local variables of the function that
was called.  All the stack frames are allocated in a region of
memory called the "call stack".

   When your program stops, the GDB commands for examining the stack
allow you to see all of this information.

   One of the stack frames is "selected" by GDB and many GDB commands
refer implicitly to the selected frame.  In particular, whenever you
ask GDB for the value of a variable in the program, the value is
found in the selected frame.  There are special GDB commands to
select whichever frame you are interested in.

   When the program stops, GDB automatically selects the currently
executing frame and describes it briefly as the `frame' command does
(*note Frame Info::.).

* Menu:

* Frames::                      Stack Frames
* Backtrace::                   Backtraces
* Selection::                   Selecting a Frame
* Frame Info::                  Information on a Frame


File: gdb.info,  Node: Frames,  Next: Backtrace,  Prev: Stack,  Up: Stack

Stack Frames
============

   The call stack is divided up into contiguous pieces called "stack
frames", or "frames" for short; each frame is the data associated
with one call to one function.  The frame contains the arguments
given to the function, the function's local variables, and the
address at which the function is executing.

   When your program is started, the stack has only one frame, that
of the function `main'.  This is called the "initial" frame or the
"outermost" frame.  Each time a function is called, a new frame is
made.  Each time a function returns, the frame for that function
invocation is eliminated.  If a function is recursive, there can be
many frames for the same function.  The frame for the function in
which execution is actually occurring is called the "innermost"
frame.  This is the most recently created of all the stack frames
that still exist.

   Inside your program, stack frames are identified by their
addresses.  A stack frame consists of many bytes, each of which has
its own address; each kind of computer has a convention for choosing
one of those bytes whose address serves as the address of the frame.
Usually this address is kept in a register called the "frame pointer
register" while execution is going on in that frame.

   GDB assigns numbers to all existing stack frames, starting with
zero for the innermost frame, one for the frame that called it, and
so on upward.  These numbers do not really exist in your program;
they are assigned by GDB to give you a way of designating stack
frames in GDB commands.

   Some compilers allow functions to be compiled so that they operate
without stack frames.  (For example, the `gcc' option
`-fomit-frame-pointer' will generate functions without a frame.)
This is occasionally done with heavily used library functions to
save the frame setup time.  GDB has limited facilities for dealing
with these function invocations.  If the innermost function
invocation has no stack frame, GDB will nevertheless regard it as
though it had a separate frame, which is numbered zero as usual,
allowing correct tracing of the function call chain.  However, GDB
has no provision for frameless functions elsewhere in the stack.


File: gdb.info,  Node: Backtrace,  Next: Selection,  Prev: Frames,  Up: Stack

Backtraces
==========

   A backtrace is a summary of how the program got where it is.  It
shows one line per frame, for many frames, starting with the
currently executing frame (frame zero), followed by its caller
(frame one), and on up the stack.

`backtrace'
`bt'
     Print a backtrace of the entire stack: one line per frame for
     all frames in the stack.

     You can stop the backtrace at any time by typing the system
     interrupt character, normally `C-c'.

`backtrace N'
`bt N'
     Similar, but print only the innermost N frames.

`backtrace -N'
`bt -N'
     Similar, but print only the outermost N frames.

   The names `where' and `info stack' (abbreviated `info s') are
additional aliases for `backtrace'.

   Each line in the backtrace shows the frame number and the function
name.  The program counter value is also shown--unless you use `set
print address off'.  The backtrace also shows the source file name
and line number, as well as the arguments to the function.  The
program counter value is omitted if it is at the beginning of the
code for that line number.

   Here is an example of a backtrace.  It was made with the command
`bt 3', so it shows the innermost three frames.

     #0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) at builtin.c:993
     #1  0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
     #2  0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
         at macro.c:71
     (More stack frames follow...)

The display for frame zero doesn't begin with a program counter
value, indicating that the program has stopped at the beginning of
the code for line `993' of `builtin.c'.


File: gdb.info,  Node: Selection,  Next: Frame Info,  Prev: Backtrace,  Up: Stack

Selecting a Frame
=================

   Most commands for examining the stack and other data in the
program work on whichever stack frame is selected at the moment. 
Here are the commands for selecting a stack frame; all of them
finish by printing a brief description of the stack frame just
selected.

`frame N'
`f N'
     Select frame number N.  Recall that frame zero is the innermost
     (currently executing) frame, frame one is the frame that called
     the innermost one, and so on.  The highest-numbered frame is
     `main''s frame.

`frame ADDR'
`f ADDR'
     Select the frame at address ADDR.  This is useful mainly if the
     chaining of stack frames has been damaged by a bug, making it
     impossible for GDB to assign numbers properly to all frames. 
     In addition, this can be useful when the program has multiple
     stacks and switches between them.

     On the SPARC architecture, `frame' needs two addresses to select
     an arbitrary frame: a frame pointer and a stack pointer.

`up N'
     Move N frames up the stack.  For positive numbers N, this
     advances toward the outermost frame, to higher frame numbers,
     to frames that have existed longer.  N defaults to one.

`down N'
     Move N frames down the stack.  For positive numbers N, this
     advances toward the innermost frame, to lower frame numbers, to
     frames that were created more recently.  N defaults to one. 
     You may abbreviate `down' as `do'.

   All of these commands end by printing two lines of output
describing the frame.  The first line shows the frame number, the
function name, the arguments, and the source file and line number of
execution in that frame.  The second line shows the text of that
source line.  For example:

     (gdb) up
     #1  0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) at env.c:10
     10              read_input_file (argv[i]);

   After such a printout, the `list' command with no arguments will
print ten lines centered on the point of execution in the frame. 
*Note List::.

`up-silently N'
`down-silently N'
     These two commands are variants of `up' and `down',
     respectively; they differ in that they do their work silently,
     without causing display of the new frame.  They are intended
     primarily for use in GDB command scripts, where the output
     might be unnecessary and distracting.


File: gdb.info,  Node: Frame Info,  Prev: Selection,  Up: Stack

Information About a Frame
=========================

   There are several other commands to print information about the
selected stack frame.

`frame'
`f'
     When used without any argument, this command does not change
     which frame is selected, but prints a brief description of the
     currently selected stack frame.  It can be abbreviated `f'. 
     With an argument, this command is used to select a stack frame
     (*note Selection::.).

`info frame'
`info f'
     This command prints a verbose description of the selected stack
     frame, including the address of the frame, the addresses of the
     next frame down (called by this frame) and the next frame up
     (caller of this frame), the language that the source code
     corresponding to this frame was written in, the address of the
     frame's arguments, the program counter saved in it (the address
     of execution in the caller frame), and which registers were
     saved in the frame.  The verbose description is useful when
     something has gone wrong that has made the stack format fail to
     fit the usual conventions.

`info frame ADDR'
`info f ADDR'
     Print a verbose description of the frame at address ADDR,
     without selecting that frame.  The selected frame remains
     unchanged by this command.

`info args'
     Print the arguments of the selected frame, each on a separate
     line.

`info locals'
     Print the local variables of the selected frame, each on a
     separate line.  These are all variables declared static or
     automatic within all program blocks that execution in this
     frame
     is currently inside of.

`info catch'
     Print a list of all the exception handlers that are active in
     the current stack frame at the current point of execution.  To
     see other exception handlers, visit the associated frame (using
     the `up', `down', or `frame' commands); then type `info catch'.
     *Note Exception Handling::.


File: gdb.info,  Node: Source,  Next: Data,  Prev: Stack,  Up: Top

Examining Source Files
**********************

   GDB can print parts of your program's source, since the debugging
information recorded in your program tells GDB what source files
were used to built it.  When your program stops, GDB spontaneously
prints the line where it stopped.  Likewise, when you select a stack
frame (*note Selection::.), GDB prints the line where execution in
that frame has stopped.  You can print other portions of source
files by explicit command.

   If you use GDB through its GNU Emacs interface, you may prefer to
use Emacs facilities to view source; *note Emacs::..

* Menu:

* List::                        Printing Source Lines
* Search::                      Searching Source Files
* Source Path::                 Specifying Source Directories
* Machine Code::                Source and Machine Code

