gdb.info: Set Breaks

Go forward to Set Watchpoints
Go up to Breakpoints
Go to the top op gdb

Setting breakpoints

Breakpoints are set with the `break' command (abbreviated `b').  The
debugger convenience variable `$bpnum' records the number of the
breakpoint 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
     "stack frame".  (*Note Frames: Frames, for a description of stack
     frames.)
`break LINENUM'
     Set a breakpoint at line LINENUM in the current source file.  The
     current source file is the last file whose source text was printed.
     The 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 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 and some x86-based
     targets.  These targets 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
     take a limited number of breakpoints.  For example, on the DSU,
     only two data breakpoints can be set at a time, and GDB will
     reject this command if more than two are used.  Delete or disable
     unused hardware breakpoints before setting new ones (*note
     Disabling: Disabling.).  *Note Break conditions: Conditions.
     *Note set remote hardware-breakpoint-limit::.
`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.
     See 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.
     The syntax of the regular expression is the standard one used with
     tools like `grep'.  Note that this is different from the syntax
     used by shells, so for instance `foo*' matches all functions that
     include an `fo' followed by zero or more `o's.  There is an
     implicit `.*' leading and trailing the regular expression you
     supply, so to match only functions that begin with `foo', use
     `^foo'.
     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.
          If the breakpoint is pending (see below for details) on a
          future load of a shared library, the address will be listed
          as `<PENDING>'.
    _What_
          Where the breakpoint is in the source for your program, as a
          file and line number.  For a pending breakpoint, the original
          string passed to the breakpoint command will be listed as it
          cannot be resolved until the appropriate shared library is
          loaded in the future.
     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.  A pending breakpoint is allowed to
     have a condition specified for it.  The condition is not parsed
     for validity until a shared library is loaded that allows the
     pending breakpoint to resolve to a valid location.
     `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.).
   If a specified breakpoint location cannot be found, it may be due to
the fact that the location is in a shared library that is yet to be
loaded.  In such a case, you may want GDB to create a special
breakpoint (known as a "pending breakpoint") that attempts to resolve
itself in the future when an appropriate shared library gets loaded.
   Pending breakpoints are useful to set at the start of your GDB
session for locations that you know will be dynamically loaded later by
the program being debugged.  When shared libraries are loaded, a check
is made to see if the load resolves any pending breakpoint locations.
If a pending breakpoint location gets resolved, a regular breakpoint is
created and the original pending breakpoint is removed.
   GDB provides some additional commands for controlling pending
breakpoint support:
`set breakpoint pending auto'
     This is the default behavior.  When GDB cannot find the breakpoint
     location, it queries you whether a pending breakpoint should be
     created.
`set breakpoint pending on'
     This indicates that an unrecognized breakpoint location should
     automatically result in a pending breakpoint being created.
`set breakpoint pending off'
     This indicates that pending breakpoints are not to be created.  Any
     unrecognized breakpoint location results in an error.  This
     setting does not affect any pending breakpoints previously created.
`show breakpoint pending'
     Show the current behavior setting for creating pending breakpoints.
   Normal breakpoint operations apply to pending breakpoints as well.
You may specify a condition for a pending breakpoint and/or commands to
run when the breakpoint is reached.  You can also enable or disable the
pending breakpoint.  When you specify a condition for a pending
breakpoint, the parsing of the condition will be deferred until the
point where the pending breakpoint location is resolved.  Disabling a
pending breakpoint tells GDB to not attempt to resolve the breakpoint
on any subsequent shared library load.  When a pending breakpoint is
re-enabled, GDB checks to see if the location is already resolved.
This is done because any number of shared library loads could have
occurred since the time the breakpoint was disabled and one or more of
these loads could resolve the location.
   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'
(*note maint info breakpoints::).