1166 lines
47 KiB
Plaintext
1166 lines
47 KiB
Plaintext
This is Info file ./gdb.info, produced by Makeinfo-1.52 from the input
|
||
file gdb.texinfo.
|
||
|
||
START-INFO-DIR-ENTRY
|
||
* Gdb:: The GNU debugger.
|
||
END-INFO-DIR-ENTRY
|
||
This file documents the GNU debugger GDB.
|
||
|
||
This is Edition 4.09, August 1993, of `Debugging with GDB: the GNU
|
||
Source-Level Debugger' for GDB Version 4.11.
|
||
|
||
Copyright (C) 1988, '89, '90, '91, '92, '93 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 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.
|
||
|
||
|
||
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', your program must be running in an environment
|
||
which supports processes; for example, `attach' does not work for
|
||
programs on bare-board targets that lack an operating system. You must
|
||
also have permission to send the process a signal.
|
||
|
||
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 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 IDs 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 purposes of using a debugger are 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.
|
||
|
||
You can arrange to have values from your program displayed
|
||
automatically whenever GDB stops at a breakpoint. *Note Automatic
|
||
display: Auto Display.
|
||
|
||
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:: "Cannot insert 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: 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.
|
||
|
||
If a breakpoint is conditional, `info break' shows the condition on
|
||
the line following the affected breakpoint; breakpoint commands,
|
||
if any, are listed after that.
|
||
|
||
`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 be well 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.
|
||
|
||
When you use `continue' to resume execution of your program from a
|
||
breakpoint, you can specify an ignore count directly as an
|
||
argument to `continue', rather than using `ignore'. *Note
|
||
Continuing and stepping: Continuing and Stepping.
|
||
|
||
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.
|
||
|
||
Any other commands in the command list, after a command that resumes
|
||
execution, are ignored. This is because any time you resume execution
|
||
(even with a simple `next' or `step'), you may encounter another
|
||
breakpoint--which could have its own command list, leading to
|
||
ambiguities about which list to execute.
|
||
|
||
If the first command you specify in a command list 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 none of the remaining commands print anything, you
|
||
will see no sign that the breakpoint was reached. `silent' is
|
||
meaningful only at the beginning of a breakpoint command list.
|
||
|
||
The commands `echo', `output', and `printf' allow you to print
|
||
precisely controlled output, and 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
|
||
printf "x is %d\n",x
|
||
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
|
||
|
||
|
||
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 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]'
|
||
`c [IGNORE-COUNT]'
|
||
`fg [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.).
|
||
|
||
The argument IGNORE-COUNT is meaningful only when your program
|
||
stopped due to a breakpoint. At other times, the argument to
|
||
`continue' is ignored.
|
||
|
||
The synonyms `c' and `fg' are provided purely for convenience, and
|
||
have exactly the same behavior as `continue'.
|
||
|
||
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 proceeds until control reaches a
|
||
function that does have debugging information.
|
||
|
||
`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'
|
||
`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 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'
|
||
`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 Automatic
|
||
display: 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 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 stops your program, the signal is not visible until you
|
||
continue. Your program 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
|
||
|
||
* MIPS Stack:: MIPS machines and the function stack
|
||
|
||
|
||
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 provide a way to compile functions 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'
|
||
`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 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'.
|
||
|