OS/2 Professional/OS2PRO194.ISO/os2/prgramer/unix/info/gdb.i02

GNU Info File | 1993-06-12 | 50KB | 901 lines

This is Info file gdb.info, produced by Makeinfo-1.47 from the input
file gdb-all.tex.
START-INFO-DIR-ENTRY
* Gdb: (gdb).                   The GNU debugger.
END-INFO-DIR-ENTRY
   This file documents the GNU debugger GDB.
   This is Edition 4.06, October 1992, of `Debugging with GDB: the GNU
Source-Level Debugger' for GDB Version 4.7.
   Copyright (C) 1988, 1989, 1990, 1991, 1992 Free Software Foundation,
   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: Attach,  Next: Kill Process,  Prev: Input/Output,  Up: Running
Debugging an Already-Running Process
====================================
`attach PROCESS-ID'
     This command attaches to a running process--one that was started
     outside GDB. (`info files' will show your active targets.)  The
     command takes as argument a process ID.  The usual way to find out
     the process-id of a Unix process is with the `ps' utility, or with
     the `jobs -l' shell command.
     `attach' will not repeat if you press RET a second time after
     executing the command.
   To use `attach', you must be debugging in an environment which
supports processes.  You must also have permission to send the process a
signal, and it must have the same effective user ID as the GDB process.
   When using `attach', you should first use the `file' command to
specify the program running in the process and load its symbol table.
*Note Commands to Specify Files: Files.
   The first thing GDB does after arranging to debug the specified
process is to stop it.  You can examine and modify an attached process
with all the GDB commands that are ordinarily available when you start
processes with `run'.  You can insert breakpoints; you can step and
continue; you can modify storage.  If you would rather the process
continue running, you may use the `continue' command after attaching
GDB to the process.
`detach'
     When you have finished debugging the attached process, you can use
     the `detach' command to release it from GDB's control.  Detaching
     the process continues its execution.  After the `detach' command,
     that process and GDB become completely independent once more, and
     you are ready to `attach' another process or start one with `run'.
     `detach' will not repeat if you press RET again after executing
     the command.
   If you exit GDB or use the `run' command while you have an attached
process, you kill that process.  By default, you will be asked for
confirmation if you try to do either of these things; you can control
whether or not you need to confirm by using the `set confirm' command
(*note Optional Warnings and Messages: Messages/Warnings.).
File: gdb.info,  Node: Kill Process,  Next: Process Information,  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 cannot 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 your program outside
the debugger.
   The `kill' command is also useful if you wish to recompile and
relink your 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: Process Information,  Prev: Kill Process,  Up: Running
Additional Process Information
==============================
   Some operating systems provide a facility called `/proc' that can be
used to examine the image of a running process using file-system
subroutines.  If GDB is configured for an operating system with this
facility, the command `info proc' is available to report on several
kinds of information about the process running your program.
`info proc'
     Summarize available information about the process.
`info proc mappings'
     Report on the address ranges accessible in the program, with
     information on whether your program may read, write, or execute
     each range.
`info proc times'
     Starting time, user CPU time, and system CPU time for your program
     and its children.
`info proc id'
     Report on the process ID's related to your program: its own
     process id, the id of its parent, the process group id, and the
     session id.
`info proc status'
     General information on the state of the process.  If the process is
     stopped, this report includes the reason for stopping, and any
     signal received.
`info proc all'
     Show all the above information about the process.
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 your 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,  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 your program will stop.
You can set breakpoints with the `break' command and its variants
(*note Setting Breakpoints: Set Breaks.), to specify the place where
your 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
Breakpoints and Exceptions: 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 Setting Watchpoints: 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.
   GDB assigns a number to each breakpoint or watchpoint when you
create it; 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 your 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,  Up: Breakpoints
Setting Breakpoints
-------------------
   Breakpoints are set with the `break' command (abbreviated `b').  The
debugger convenience variable `$bpnum' records the number of the
beakpoint you've set most recently; see *Note Convenience Variables:
Convenience Vars, for a discussion of what you can do with convenience
variables.
   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 your 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 your 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 Examining the Stack: Stack.).  In any selected frame but the
     innermost, this will cause your 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' does not 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 your 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 Break Conditions: 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 after the first
     time your program stops there.  *Note Disabling Breakpoints:
     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]'
`info watchpoints [N]'
     Print a table of all breakpoints and watchpoints set and not
     deleted, with the following columns for each breakpoint:
    *Breakpoint Numbers*
    *Type*
          Breakpoint or watchpoint.
    *Disposition*
          Whether the breakpoint is marked to be disabled or deleted
          when hit.
    *Enabled or Disabled*
          Enabled breakpoints are marked with `y'.  `n' marks
          breakpoints that are not enabled.
    *Address*
          Where the breakpoint is in your program, as a memory address
    *What*
          Where the breakpoint is in the source for your program, as a
          file and line number.
     Breakpoint commands, if any, are listed after the line for the
     corresponding breakpoint.
     `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 Examining Memory: Memory.).
   GDB allows you to set any number of breakpoints at the same place in
your program.  There is nothing silly or meaningless about this.  When
the breakpoints are conditional, this is even useful (*note Break
Conditions: Conditions.).
   GDB itself sometimes sets breakpoints in your program for special
purposes, such as proper handling of `longjmp' (in C programs). These
internal breakpoints are assigned negative numbers, starting with `-1';
`info breakpoints' does not display them.
   You can see these breakpoints with the GDB maintenance command
`maint info breakpoints'.
`maint info breakpoints'
     Using the same format as `info breakpoints', display both the
     breakpoints you've set explicitly, and those GDB is using for
     internal purposes.  Internal breakpoints are shown with negative
     breakpoint numbers.  The type column identifies what kind of
     breakpoint is shown:
    `breakpoint'
          Normal, explicitly set breakpoint.
    `watchpoint'
          Normal, explicitly set watchpoint.
    `longjmp'
          Internal breakpoint, used to handle correctly stepping through
          `longjmp' calls.
    `longjmp resume'
          Internal breakpoint at the target of a `longjmp'.
    `until'
          Temporary internal breakpoint used by the GDB `until' command.
    `finish'
          Temporary internal breakpoint used by the GDB `finish'
          command.
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 and breakpoints; it is
     the same as `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 your program to raise an exception,
and to list the exceptions your 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
Information About a Frame: 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 you and cause your 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 is 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
Watchpoints and Exceptions: Breakpoints.).
   With a conditional breakpoint (*note Break Conditions: 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 your 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 your 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 your 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 Selecting a Frame: Selection.).
     When the innermost frame is selected, this is a good way to delete
     a breakpoint where your program just stopped.
`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 have `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 do not know which numbers to use.
   A breakpoint or watchpoint can have any of four different states of
enablement:
   * Enabled.  The breakpoint will stop your program.  A breakpoint set
     with the `break' command starts out in this state.
   * Disabled.  The breakpoint has no effect on your program.
   * Enabled once.  The breakpoint will stop your 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 your 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 your program.
`enable [breakpoints] once BNUMS...'
     Enable the specified breakpoints temporarily.  Each will be
     disabled again the next time it stops your 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 your
     program.
   Save for a breakpoint set with `tbreak' (*note Setting Breakpoints:
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; see *Note Continuing and Stepping: 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 your 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: Expressions.).  A breakpoint
with a condition evaluates the expression each time your program
reaches it, and your 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 can 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 your 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 Breakpoint
Command Lists: Break Commands.).
   Break conditions can be specified when a breakpoint is set, by using
`if' in the arguments to the `break' command.  *Note Setting
Breakpoints: Set Breaks.  They can also be changed at any time with the
`condition' command.  The `watch' command does not 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
     your 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: 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 your 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 your program, setting the ignore count of the
     breakpoint where your program stopped to COUNT minus one. Thus,
     your program will not stop at this breakpoint until the COUNT'th
     time it is reached.
     An argument to this command is meaningful only when your 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 Variables: 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 your 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' and
     follow it immediately with `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 your 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
Commands for Controlled Output: 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 your 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: Expressions.) that
will change `x' as needed, then always have the value zero so your
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.
 If you realize this will be a problem, you can use something like
`break FUNCTION(TYPES)' to specify which particular version of the
function you want.  Otherwise, 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 your program to a new
     name. Resume GDB and use the `exec-file' command to specify that
     GDB should run your program under that name.  Then start your
     program again.
  3. Relink your 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, your
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: Signals.)
`continue [IGNORE-COUNT]'
     Resume program execution, at the address where your 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 Break Conditions:
     Conditions.).
     To resume execution at a different place, you can use `return'
     (*note Returning from a Function: Returning.) to go back to the
     calling function; or `jump' (*note Continuing at a Different
     Address: Jumping.) to go to an arbitrary location in your program.
   A typical technique for using stepping is to set a breakpoint (*note
Breakpoints Watchpoints and Exceptions: Breakpoints.) at the beginning
of the function or the section of your program where a problem is
believed to lie, run your 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 your 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 from a
     Function: Returning.).
`until'
     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 your 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 your 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 your 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 Setting
     Breakpoints: Set Breaks.).  This form of the command uses
     breakpoints, and hence is quicker than `until' without an argument.
`stepi'
     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 Automatic
     Display: Auto Display.
     An argument is a repeat count, as in `step'.
`nexti'
     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 your program has requested an alarm).
   Some signals, including `SIGALRM', are a normal part of the
functioning of your program.  Others, such as `SIGSEGV', indicate
errors; these signals are "fatal" (kill your program immediately) if the
program has not specified in advance some other way to handle the
signal. `SIGINT' does not indicate an error in your 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 your
program.  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
your program) but to stop your 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 your program when this signal happens.  It may
     still print a message telling you that the signal has come in.
`stop'
     GDB should stop your 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 your program to see this signal; your 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 your program to see this signal.
   When a signal has been set to stop your program, your 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 your program when you later continue it.
   You can also use the `signal' command to prevent your 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 your 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 your program would probably terminate immediately as
a result of the fatal signal once it saw the signal.  To prevent this,
you can continue with `signal 0'.  *Note Giving your Program a Signal:
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 your 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 your program, the value is found in
the selected frame.  There are special GDB commands to select whichever
frame you are interested in.
   When your program stops, GDB automatically selects the currently
executing frame and describes it briefly as the `frame' command does
(*note Information About a Frame: 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,  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 your 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'
     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 does not begin with a program counter value,
indicating that your program has stopped at the beginning of the code
for line `993' of `builtin.c'.