path: root/gdb/doc/gdb.info-2

This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
the input file gdb.texinfo.

START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY
   This file documents the GNU debugger GDB.

   This is the Seventh Edition, February 1999, of `Debugging with GDB:
the GNU Source-Level Debugger' for GDB Version 4.18.

   Copyright (C) 1988-1999 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: Starting,  Next: Arguments,  Prev: Compilation,  Up: Running

Starting your program
=====================

`run'
`r'
     Use the `run' command to start your program under GDB.  You must
     first specify the program name (except on VxWorks) with an
     argument to GDB (*note Getting In and Out of GDB: Invocation.), or
     by using the `file' or `exec-file' command (*note Commands to
     specify files: Files.).

   If you are running your program in an execution environment that
supports processes, `run' creates an inferior process and makes that
process run your program.  (In environments without processes, `run'
jumps to the start of your program.)

   The execution of a program is affected by certain information it
receives from its superior.  GDB provides ways to specify this
information, which you must do *before* starting your program.  (You
can change it after starting your program, but such changes only affect
your program the next time you start it.)  This information may be
divided into four categories:

The *arguments.*
     Specify the arguments to give your program as the arguments of the
     `run' command.  If a shell is available on your target, the shell
     is used to pass the arguments, so that you may use normal
     conventions (such as wildcard expansion or variable substitution)
     in describing the arguments.  In Unix systems, you can control
     which shell is used with the `SHELL' environment variable.  *Note
     Your program's arguments: Arguments.

The *environment.*
     Your program normally inherits its environment from GDB, but you
     can use the GDB commands `set environment' and `unset environment'
     to change parts of the environment that affect your program.
     *Note Your program's environment: Environment.

The *working directory.*
     Your program inherits its working directory from GDB.  You can set
     the GDB working directory with the `cd' command in GDB.  *Note
     Your program's working directory: Working Directory.

The *standard input and output.*
     Your program normally uses the same device for standard input and
     standard output as GDB is using.  You can redirect input and output
     in the `run' command line, or you can use the `tty' command to set
     a different device for your program.  *Note Your program's input
     and output: Input/Output.

     *Warning:* While input and output redirection work, you cannot use
     pipes to pass the output of the program you are debugging to
     another program; if you attempt this, GDB is likely to wind up
     debugging the wrong program.

   When you issue the `run' command, your program begins to execute
immediately.  *Note Stopping and continuing: Stopping, for discussion
of how to arrange for your program to stop.  Once your program has
stopped, you may call functions in your program, using the `print' or
`call' commands.  *Note Examining Data: Data.

   If the modification time of your symbol file has changed since the
last time GDB read its symbols, GDB discards its symbol table, and
reads it again.  When it does this, GDB tries to retain your current
breakpoints.


File: gdb.info,  Node: Arguments,  Next: Environment,  Prev: Starting,  Up: Running

Your program's arguments
========================

   The arguments to your program can be specified by the arguments of
the `run' command.  They are passed to a shell, which expands wildcard
characters and performs redirection of I/O, and thence to your program.
Your `SHELL' environment variable (if it exists) specifies what shell
GDB uses.  If you do not define `SHELL', GDB uses `/bin/sh'.

   `run' with no arguments uses the same arguments used by the previous
`run', or those set by the `set args' command.

`set args'
     Specify the arguments to be used the next time your program is
     run.  If `set args' has no arguments, `run' executes your program
     with no arguments.  Once you have run your program with arguments,
     using `set args' before the next `run' is the only way to run it
     again without arguments.

`show args'
     Show the arguments to give your program when it is started.


File: gdb.info,  Node: Environment,  Next: Working Directory,  Prev: Arguments,  Up: Running

Your program's environment
==========================

   The "environment" consists of a set of environment variables and
their values.  Environment variables conventionally record such things
as your user name, your home directory, your terminal type, and your
search path for programs to run.  Usually you set up environment
variables with the shell and they are inherited by all the other
programs you run.  When debugging, it can be useful to try running your
program with a modified environment without having to start GDB over
again.

`path DIRECTORY'
     Add DIRECTORY to the front of the `PATH' environment variable (the
     search path for executables), for both GDB and your program.  You
     may specify several directory names, separated by `:' or
     whitespace.  If DIRECTORY is already in the path, it is moved to
     the front, so it is searched sooner.

     You can use the string `$cwd' to refer to whatever is the current
     working directory at the time GDB searches the path.  If you use
     `.' instead, it refers to the directory where you executed the
     `path' command.  GDB replaces `.' in the DIRECTORY argument (with
     the current path) before adding DIRECTORY to the search path.

`show paths'
     Display the list of search paths for executables (the `PATH'
     environment variable).

`show environment [VARNAME]'
     Print the value of environment variable VARNAME to be given to
     your program when it starts.  If you do not supply VARNAME, print
     the names and values of all environment variables to be given to
     your program.  You can abbreviate `environment' as `env'.

`set environment VARNAME [=] VALUE'
     Set environment variable VARNAME to VALUE.  The value changes for
     your program only, not for GDB itself.  VALUE may be any string;
     the values of environment variables are just strings, and any
     interpretation is supplied by your program itself.  The VALUE
     parameter is optional; if it is eliminated, the variable is set to
     a null value.

     For example, this command:

          set env USER = foo

     tells a Unix program, when subsequently run, that its user is named
     `foo'.  (The spaces around `=' are used for clarity here; they are
     not actually required.)

`unset environment VARNAME'
     Remove variable VARNAME from the environment to be passed to your
     program.  This is different from `set env VARNAME ='; `unset
     environment' removes the variable from the environment, rather
     than assigning it an empty value.

   *Warning:* GDB runs your program using the shell indicated by your
`SHELL' environment variable if it exists (or `/bin/sh' if not).  If
your `SHELL' variable names a shell that runs an initialization
file--such as `.cshrc' for C-shell, or `.bashrc' for BASH--any
variables you set in that file affect your program.  You may wish to
move setting of environment variables to files that are only run when
you sign on, such as `.login' or `.profile'.


File: gdb.info,  Node: Working Directory,  Next: Input/Output,  Prev: Environment,  Up: Running

Your program's working directory
================================

   Each time you start your program with `run', it inherits its working
directory from the current working directory of GDB.  The GDB working
directory is initially whatever it inherited from its parent process
(typically the shell), but you can specify a new working directory in
GDB with the `cd' command.

   The GDB working directory also serves as a default for the commands
that specify files for GDB to operate on.  *Note Commands to specify
files: Files.

`cd DIRECTORY'
     Set the GDB working directory to DIRECTORY.

`pwd'
     Print the GDB working directory.


File: gdb.info,  Node: Input/Output,  Next: Attach,  Prev: Working Directory,  Up: Running

Your program's input and output
===============================

   By default, the program you run under GDB does input and output to
the same terminal that GDB uses.  GDB switches the terminal to its own
terminal modes to interact with you, but it records the terminal modes
your program was using and switches back to them when you continue
running your program.

`info terminal'
     Displays information recorded by GDB about the terminal modes your
     program is using.

   You can redirect your program's input and/or output using shell
redirection with the `run' command.  For example,

     run > outfile

starts your program, diverting its output to the file `outfile'.

   Another way to specify where your program should do input and output
is with the `tty' command.  This command accepts a file name as
argument, and causes this file to be the default for future `run'
commands.  It also resets the controlling terminal for the child
process, for future `run' commands.  For example,

     tty /dev/ttyb

directs that processes started with subsequent `run' commands default
to do input and output on the terminal `/dev/ttyb' and have that as
their controlling terminal.

   An explicit redirection in `run' overrides the `tty' command's
effect on the input/output device, but not its effect on the controlling
terminal.

   When you use the `tty' command or redirect input in the `run'
command, only the input *for your program* is affected.  The input for
GDB still comes from your terminal.


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' shows 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' does 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 you use `attach', the debugger finds the program running in the
process first by looking in the current working directory, then (if the
program is not found) by using the source file search path (*note
Specifying source directories: Source Path.).  You can also use the
`file' command to load the program.  *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' does 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, GDB asks 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 notices that the file has changed, and reads
the symbol table again (while trying to preserve your current
breakpoint settings).


File: gdb.info,  Node: Process Information,  Next: Threads,  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' works only on SVR4 systems that support `procfs'.

`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: Threads,  Next: Processes,  Prev: Process Information,  Up: Running

Debugging programs with multiple threads
========================================

   In some operating systems, such as HP-UX and Solaris, a single
program may have more than one "thread" of execution.  The precise
semantics of threads differ from one operating system to another, but
in general the threads of a single program are akin to multiple
processes--except that they share one address space (that is, they can
all examine and modify the same variables).  On the other hand, each
thread has its own registers and execution stack, and perhaps private
memory.

   GDB provides these facilities for debugging multi-thread programs:

   * automatic notification of new threads

   * `thread THREADNO', a command to switch among threads

   * `info threads', a command to inquire about existing threads

   * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command
     to a list of threads

   * thread-specific breakpoints

     *Warning:* These facilities are not yet available on every GDB
     configuration where the operating system supports threads.  If
     your GDB does not support threads, these commands have no effect.
     For example, a system without thread support shows no output from
     `info threads', and always rejects the `thread' command, like this:

          (gdb) info threads
          (gdb) thread 1
          Thread ID 1 not known.  Use the "info threads" command to
          see the IDs of currently known threads.

   The GDB thread debugging facility allows you to observe all threads
while your program runs--but whenever GDB takes control, one thread in
particular is always the focus of debugging.  This thread is called the
"current thread".  Debugging commands show program information from the
perspective of the current thread.

   Whenever GDB detects a new thread in your program, it displays the
target system's identification for the thread with a message in the
form `[New SYSTAG]'.  SYSTAG is a thread identifier whose form varies
depending on the particular system.  For example, on LynxOS, you might
see

     [New process 35 thread 27]

when GDB notices a new thread.  In contrast, on an SGI system, the
SYSTAG is simply something like `process 368', with no further
qualifier.

   For debugging purposes, GDB associates its own thread number--always
a single integer--with each thread in your program.

`info threads'
     Display a summary of all threads currently in your program.  GDB
     displays for each thread (in this order):

       1. the thread number assigned by GDB

       2. the target system's thread identifier (SYSTAG)

       3. the current stack frame summary for that thread

     An asterisk `*' to the left of the GDB thread number indicates the
     current thread.

     For example,

     (gdb) info threads
       3 process 35 thread 27  0x34e5 in sigpause ()
       2 process 35 thread 23  0x34e5 in sigpause ()
     * 1 process 35 thread 13  main (argc=1, argv=0x7ffffff8)
         at threadtest.c:68

`thread THREADNO'
     Make thread number THREADNO the current thread.  The command
     argument THREADNO is the internal GDB thread number, as shown in
     the first field of the `info threads' display.  GDB responds by
     displaying the system identifier of the thread you selected, and
     its current stack frame summary:

          (gdb) thread 2
          [Switching to process 35 thread 23]
          0x34e5 in sigpause ()

     As with the `[New ...]' message, the form of the text after
     `Switching to' depends on your system's conventions for identifying
     threads.

`thread apply [THREADNO] [ALL]  ARGS'
     The `thread apply' command allows you to apply a command to one or
     more threads.  Specify the numbers of the threads that you want
     affected with the command argument THREADNO.  THREADNO is the
     internal GDB thread number, as shown in the first field of the
     `info threads' display.  To apply a command to all threads, use
     `thread apply all' ARGS.

   Whenever GDB stops your program, due to a breakpoint or a signal, it
automatically selects the thread where that breakpoint or signal
happened.  GDB alerts you to the context switch with a message of the
form `[Switching to SYSTAG]' to identify the thread.

   *Note Stopping and starting multi-thread programs: Thread Stops, for
more information about how GDB behaves when you stop and start programs
with multiple threads.

   *Note Setting watchpoints: Set Watchpoints, for information about
watchpoints in programs with multiple threads.


File: gdb.info,  Node: Processes,  Prev: Threads,  Up: Running

Debugging programs with multiple processes
==========================================

   GDB has no special support for debugging programs which create
additional processes using the `fork' function.  When a program forks,
GDB will continue to debug the parent process and the child process
will run unimpeded.  If you have set a breakpoint in any code which the
child then executes, the child will get a `SIGTRAP' signal which
(unless it catches the signal) will cause it to terminate.

   However, if you want to debug the child process there is a workaround
which isn't too painful.  Put a call to `sleep' in the code which the
child process executes after the fork.  It may be useful to sleep only
if a certain environment variable is set, or a certain file exists, so
that the delay need not occur when you don't want to run GDB on the
child.  While the child is sleeping, use the `ps' program to get its
process ID.  Then tell GDB (a new invocation of GDB if you are also
debugging the parent process) to attach to the child process (see *Note
Attach::).  From that point on you can debug the child process just
like any other process which you attached to.


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 catchpoints
* Continuing and Stepping::     Resuming execution

* Signals::                     Signals


* Thread Stops::                Stopping and starting multi-thread programs


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

Breakpoints, watchpoints, and catchpoints
=========================================

   A "breakpoint" makes your program stop whenever a certain point in
the program is reached.  For each breakpoint, you can add conditions to
control in finer detail whether your program stops.  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 HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can
set breakpoints in shared libraries before the executable is run.
There is a minor limitation on HP-UX systems: you must wait until the
executable is run in order to set breakpoints in shared library
routines that are not called directly by the program (for example,
routines that are arguments in a `pthread_create' call).

   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.

   A "catchpoint" is another special breakpoint that stops your program
when a certain kind of event occurs, such as the throwing of a C++
exception or the loading of a library.  As with watchpoints, you use a
different command to set a catchpoint (*note Setting catchpoints: Set
Catchpoints.), but aside from that, you can manage a catchpoint like any
other breakpoint.  (To stop when your program receives a signal, use the
`handle' command; *note Signals: Signals..)

   GDB assigns a number to each breakpoint, watchpoint, or catchpoint
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
* Set Catchpoints::             Setting catchpoints
* Delete Breaks::               Deleting breakpoints
* Disabling::                   Disabling breakpoints
* Conditions::                  Break conditions
* Break Commands::              Breakpoint command lists

* Breakpoint Menus::            Breakpoint menus


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

Setting breakpoints
-------------------

   Breakpoints are set with the `break' command (abbreviated `b').  The
debugger convenience variable `$bpnum' records the number of the
breakpoints 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 stops 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 makes your program 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 stops 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 deleted after the first
     time your program stops there.  *Note Disabling breakpoints:
     Disabling.

`hbreak ARGS'
     Set a hardware-assisted breakpoint.  ARGS are the same as for the
     `break' command and the breakpoint is set in the same way, but the
     breakpoint requires hardware support and some target hardware may
     not have this support.  The main purpose of this is EPROM/ROM code
     debugging, so you can set a breakpoint at an instruction without
     changing the instruction.  This can be used with the new
     trap-generation provided by SPARClite DSU.  DSU will generate
     traps when a program accesses some data or instruction address
     that is assigned to the debug registers.  However the hardware
     breakpoint registers can only take two data breakpoints, and GDB
     will reject this command if more than two are used.  Delete or
     disable unused hardware breakpoints before setting new ones.
     *Note Break conditions: Conditions.

`thbreak ARGS'
     Set a hardware-assisted breakpoint enabled only for one stop.  ARGS
     are the same as for the `hbreak' command and the breakpoint is set
     in the same way.  However, like the `tbreak' command, the
     breakpoint is automatically deleted after the first time your
     program stops there.  Also, like the `hbreak' command, the
     breakpoint requires hardware support and some target hardware may
     not have this support.  *Note Disabling breakpoints: Disabling.
     Also *Note Break conditions: Conditions.

`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.  You can delete them, disable them,
     or make them conditional the same way as any other breakpoint.

     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, watchpoints, and catchpoints set
     and not deleted, with the following columns for each breakpoint:

    *Breakpoint Numbers*

    *Type*
          Breakpoint, watchpoint, or catchpoint.

    *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.).

     `info break' displays a count of the number of times the breakpoint
     has been hit.  This is especially useful in conjunction with the
     `ignore' command.  You can ignore a large number of breakpoint
     hits, look at the breakpoint info to see how many times the
     breakpoint was hit, and then run again, ignoring one less than
     that number.  This will get you quickly to the last hit of that
     breakpoint.

   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: Set Catchpoints,  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.

   Depending on your system, watchpoints may be implemented in software
or hardware.  GDB does software watchpointing by single-stepping your
program and testing the variable's value each time, which is hundreds of
times slower than normal execution.  (But this may still be worth it, to
catch errors where you have no clue what part of your program is the
culprit.)

   On some systems, such as HP-UX and Linux, GDB includes support for
hardware watchpoints, which do not slow down the running of your
program.

`watch EXPR'
     Set a watchpoint for an expression.  GDB will break when EXPR is
     written into by the program and its value changes.

`rwatch EXPR'
     Set a watchpoint that will break when watch EXPR is read by the
     program.  If you use both watchpoints, both must be set with the
     `rwatch' command.

`awatch EXPR'
     Set a watchpoint that will break when ARGS is read and written into
     by the program.  If you use both watchpoints, both must be set
     with the `awatch' command.

`info watchpoints'
     This command prints a list of watchpoints, breakpoints, and
     catchpoints; it is the same as `info break'.

   GDB sets a "hardware watchpoint" if possible.  Hardware watchpoints
execute very quickly, and the debugger reports a change in value at the
exact instruction where the change occurs.  If GDB cannot set a
hardware watchpoint, it sets a software watchpoint, which executes more
slowly and reports the change in value at the next statement, not the
instruction, after the change occurs.

   When you issue the `watch' command, GDB reports

     Hardware watchpoint NUM: EXPR

if it was able to set a hardware watchpoint.

   The SPARClite DSU will generate traps when a program accesses some
data or instruction address that is assigned to the debug registers.
For the data addresses, DSU facilitates the `watch' command.  However
the hardware breakpoint registers can only take two data watchpoints,
and both watchpoints must be the same kind.  For example, you can set
two watchpoints with `watch' commands, two with `rwatch' commands, *or*
two with `awatch' commands, but you cannot set one watchpoint with one
command and the other with a different command.  GDB will reject the
command if you try to mix watchpoints.  Delete or disable unused
watchpoint commands before setting new ones.

   If you call a function interactively using `print' or `call', any
watchpoints you have set will be inactive until GDB reaches another
kind of breakpoint or the call completes.

     *Warning:* In multi-thread programs, watchpoints have only limited
     usefulness.  With the current watchpoint implementation, GDB can
     only watch the value of an expression *in a single thread*.  If
     you are confident that the expression can only change due to the
     current thread's activity (and if you are also confident that no
     other thread can become current), then you can use watchpoints as
     usual.  However, GDB may not notice when a non-current thread's
     activity changes the expression.


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

Setting catchpoints
-------------------

   You can use "catchpoints" to cause the debugger to stop for certain
kinds of program events, such as C++ exceptions or the loading of a
shared library.  Use the `catch' command to set a catchpoint.

`catch EVENT'
     Stop when EVENT occurs.  EVENT can be any of the following:
    `throw'
          The throwing of a C++ exception.

    `catch'
          The catching of a C++ exception.

    `exec'
          A call to `exec'.  This is currently only available for HP-UX.

    `fork'
          A call to `fork'.  This is currently only available for HP-UX.

    `vfork'
          A call to `vfork'.  This is currently only available for
          HP-UX.

    `load'
    `load LIBNAME'
          The dynamic loading of any shared library, or the loading of
          the library LIBNAME.  This is currently only available for
          HP-UX.

    `unload'
    `unload LIBNAME'
          The unloading of any dynamically loaded shared library, or
          the unloading of the library LIBNAME.  This is currently only
          available for HP-UX.

`tcatch EVENT'
     Set a catchpoint that is enabled only for one stop.  The
     catchpoint is automatically deleted after the first time the event
     is caught.

   Use the `info break' command to list the current catchpoints.

   There are currently some limitations to C++ exception handling
(`catch throw' and `catch catch') in GDB:

   * 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 either to abort
     or to simply continue running until it hits a breakpoint, catches
     a signal that GDB is listening for, or exits.  This is the case
     even if you set a catchpoint for the exception; catchpoints on
     exceptions are disabled within interactive calls.

   * You cannot raise an exception interactively.

   * You cannot install an exception handler interactively.

   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: Set Catchpoints,  Up: Breakpoints

Deleting breakpoints
--------------------

   It is often necessary to eliminate a breakpoint, watchpoint, or
catchpoint 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, watchpoints, or catchpoints 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, watchpoints, or catchpoints 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, watchpoint, or catchpoint, 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, watchpoints, and catchpoints 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, watchpoints, and catchpoints if you do not
know which numbers to use.

   A breakpoint, watchpoint, or catchpoint can have any of four
different states of enablement:

   * Enabled.  The breakpoint stops 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 stops your program, but then becomes
     disabled.  A breakpoint set with the `tbreak' command starts out in
     this state.

   * Enabled for deletion.  The breakpoint stops your program, but
     immediately after it does so it is deleted permanently.

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

`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.  GDB disables any of
     these breakpoints immediately after stopping your program.

`enable [breakpoints] delete BNUMS...'
     Enable the specified breakpoints to work once, then die.  GDB
     deletes any of these breakpoints as soon as your program stops
     there.

   Except 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 does 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,
     watchpoint, or catchpoint number BNUM.  After you set a condition,
     breakpoint BNUM stops 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 does not stop the next N times your program reaches
it.

`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
     does 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, GDB
     resumes checking the condition.

     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.

   Ignore counts apply to breakpoints, watchpoints, and catchpoints.