Docs and NEWS for breakpoint changes

Docs and NEWS for breakpoint changes

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 586 bytes --]


Now that the code patches for my breakpoint changes are in,
here's the doc patch and NEWS addition.

The doc patch document that a breakpoint can have several
locations, and that individual locations can be enabled
and disabled.  It also rewords pending breakpoint docs
to better reflect current code -- where every breakpoint is
reevaluated when new shared libraries are loaded, and pending
breakpoint is merely a breakpoint that don't have a valid
address as yet, not a temporary kind of breakpoint that
tends to morph into ordinary breakpoint on any occasion.

Comments?

- Volodya

[-- Attachment #2: breakpoint_docs.diff --]
[-- Type: text/x-diff, Size: 7595 bytes --]

Index: NEWS
===================================================================
RCS file: /cvs/src/src/gdb/NEWS,v
retrieving revision 1.239
diff -u -p -r1.239 NEWS
--- NEWS	17 Sep 2007 19:30:05 -0000	1.239
+++ NEWS	26 Sep 2007 18:00:47 -0000
@@ -3,6 +3,13 @@
 
 *** Changes since GDB 6.7
 
+* Pending breakpoints where changed to not change its number when
+  resolved.
+
+* Support for breakpoints with multiple locations was implemented,
+  including breakpoints on C++ constructors, inside C++ templates,
+  and in inlined functions.
+
 *** Changes in GDB 6.6
 
 * Resolved 101 resource leaks, null pointer dereferences, etc. in gdb, 
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.432
diff -u -p -r1.432 gdb.texinfo
--- doc/gdb.texinfo	16 Sep 2007 14:59:30 -0000	1.432
+++ doc/gdb.texinfo	26 Sep 2007 18:00:57 -0000
@@ -2991,11 +2991,17 @@ Breakpoint, watchpoint, or catchpoint.
 Whether the breakpoint is marked to be disabled or deleted when hit.
 @item Enabled or Disabled
 Enabled breakpoints are marked with @samp{y}.  @samp{n} marks breakpoints
-that are not enabled.
+that are not enabled.  An optional @samp{(p)} suffix marks pending
+breakpoints --- breakpoints for which address is either not yet
+resolved, pending load of a shared library, or for which address was
+in a shared library that was since resolved.  Such breakpoint won't
+fire until a shared library that has the symbol or line referred by
+breakpoint is loaded.  See below for details.
 @item 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 @samp{<PENDING>}.
+Where the breakpoint is in your program, as a memory address.  For a
+pending breakpoint that never had its address known,  this field will
+contain @samp{<PENDING>}.  A breakpoint with several locations will
+have @samp{<MULTIPLE>} in this field -- see below for details.
 @item 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
@@ -3032,23 +3038,72 @@ your program.  There is nothing silly or
 the breakpoints are conditional, this is even useful
 (@pxref{Conditions, ,Break Conditions}).
 
-@cindex pending breakpoints
-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 @value{GDBN} to create a special breakpoint (known as
-a @dfn{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
-@value{GDBN} 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.
+It is possible that a breakpoints correspond to several locations 
+in your program.  Examples of this situation are:
+
+@itemize @bullet
+
+@item
+For a C++ constructor, the gcc compiler generates several function
+bodies used in different cases.
+
+@item
+For a C++ template function, a given line in the function can
+correspond to unbounded set of instantiations.
 
-@value{GDBN} provides some additional commands for controlling pending
-breakpoint support:
+@item
+For an inlined function, a given line can correspond to
+several places where that function is inlined.
+
+@end itemize
+
+In all those cases, @value{GDBN} will associate the breakpoint
+with all relevant locations.
+
+A breakpoint with multiple locations is displayed in the
+breakpoint table using several rows --- one header row, followed
+by one row for each breakpoint location. The header row
+has @samp{<MULTIPLE>} in the address column.  The rows for
+individual locations contain the actual addresses for locations,
+and say what functions those locations are in.  The number
+column for a location has number in the format 
+@var{breakpoint-number}.@var{location-number}.
+
+Each location can be individually enabled or disabled by passing
+the @var{breakpoint-number}.@var{location-number} to the @code{enable}
+or @code{disable} commands.
+
+@cindex pending breakpoints
+It's quite common to have a breakpoint inside a shared library.
+Further, the shared library may be loaded and unloaded explicitly,
+and possible repeatedly, as the program is executed.  To support
+this use case, @value{GDBN} updates breakpoint locations whenever
+any shared library is loaded or unloaded. Typically, you would
+set a breakpoint in a shared library at the beginning of your 
+debugging session, when the library is not loaded, and when the
+symbols from the library are not available.  When you try to set
+breakpoint, @value{GDBN} will ask you if you want to set
+a so called @dfn{pending breakpoint} --- breakpoint that is not yet
+resolved to address.
+
+After the program is run, whenever a new shared library is loaded,
+@value{GDBN} reevaluates all breakpoints.  In case a newly loaded
+shared library contains the symbol or line referred to by breakpoint,
+breakpoint is resolved and becomes an ordinary breakpoint.  If a
+library is unloaded, all breakpoints it in become pending again.
+
+This logic works for breakpoints with multiple locations, too.  For
+example, if you have a breakpoint in a C++ template function, and
+a newly loaded shared library has an instantiation of that template,
+a new location will be added to the existing breakpoint.
+
+Except for having unresolved address, pending breakpoints do not
+differ from regular breakpoints.  You can set conditions or commands,
+enable and disable them and perform other breakpoint operations.
+
+@value{GDBN} provides some additional commands for controlling what
+happens when the @samp{break} command cannot resolve breakpoint
+address specification to an address:
 
 @kindex set breakpoint pending
 @kindex show breakpoint pending
@@ -3070,19 +3125,9 @@ not affect any pending breakpoints previ
 Show the current behavior setting for creating pending breakpoints.
 @end table
 
-@cindex operations allowed on 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 @value{GDBN} to not attempt to resolve the breakpoint on any subsequent
-shared library load.  When a pending breakpoint is re-enabled,
-@value{GDBN} 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.
+The settings above only affect the @code{break} command and its
+variants.  Once breakpoint is set, it will be automatically updated
+as shared libraries are loaded and unloaded.
 
 @cindex automatic hardware breakpoints
 For some targets, @value{GDBN} can automatically decide if hardware or

Re: Docs and NEWS for breakpoint changes

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Wed, 26 Sep 2007 22:07:42 +0400
> Now that the code patches for my breakpoint changes are in,
> here's the doc patch and NEWS addition.

Thanks!

> Comments?

A few:

> +* Pending breakpoints where changed to not change its number when
> +  resolved.                                       ^^^

It's "breakpoints" (plural), so "its" is wrong.

"where" is also wrong; you meant "were".  But please don't use past
tense in NEWS, present tense is better:

  Pending breakpoints no longer change their number when their address
  is resolved.

> +* Support for breakpoints with multiple locations was implemented,

Avoiding passive voice makes text simpler and clearer:

   GDB now supports breakpoints with multiple locations,

(also present tense instead of past).

> +that are not enabled.  An optional @samp{(p)} suffix marks pending
> +breakpoints --- breakpoints for which address is either not yet
> +resolved, pending load of a shared library, or for which address was
> +in a shared library that was since resolved.  Such breakpoint won't
> +fire until a shared library that has the symbol or line referred by
> +breakpoint is loaded.  See below for details.

I'm left confused: if the address ``was since resolved'', then why do
we still mark the breakpoint with "(p)"?

If what matters is that the library is not yet loaded, why should we
confuse things by distinguishing the case where the address is not
resolved from the case where it is?

>                                                                  For a
> +pending breakpoint that never had its address known,

I think this is better:

  For a pending address whose address is not yet known,

> +have @samp{<MULTIPLE>} in this field -- see below for details.
                                        ^^
Please use "---" -- 3 dashes in a row, not 2 -- for an em-dash.

> +For a C++ constructor, the gcc compiler generates several function
> +bodies used in different cases.

Please use C@t{++}, it looks better in print (there are several more
instances like this one).  Also, we use "@value{NGCC}" instead of a
literal "gcc" in this manual.  And instead of "several function
bodies", isn't it more accurate to say "several instances of the
function body"?

> +For a C++ template function, a given line in the function can
> +correspond to unbounded set of instantiations.
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"to any number of instantiations" is better.

> +For an inlined function, a given line can correspond to
> +several places where that function is inlined.

"given source line" or even "a breakpoint at a given source line" will
make things clearer, I think.

> +In all those cases, @value{GDBN} will associate the breakpoint
> +with all relevant locations.

Perhaps we better say "@value{GDBN} will insert a breakpoint at all
the relevant locations".  "Associate the breakpoint" leaves me
wondering what does "associate" mean in this context.

> +A breakpoint with multiple locations is displayed in the
> +breakpoint table using several rows --- one header row, followed
> +by one row for each breakpoint location. The header row
> +has @samp{<MULTIPLE>} in the address column.  The rows for
> +individual locations contain the actual addresses for locations,
> +and say what functions those locations are in.  The number
> +column for a location has number in the format 
> +@var{breakpoint-number}.@var{location-number}.

Example, please.  A picture is worth a thousand words.

> +Each location can be individually enabled or disabled by passing
> +the @var{breakpoint-number}.@var{location-number} to the @code{enable}
> +or @code{disable} commands.

  Each location can be individually enabled or disabled by passing
  @var{breakpoint-number}.@var{location-number} as argument to the
  @code{enable} and @code{disable} commands.

> +It's quite common to have a breakpoint inside a shared library.
> +Further, the shared library may be loaded and unloaded explicitly,

This "further" thing does not add anything to the sentence; just
remove it.

> +and possible repeatedly, as the program is executed.  To support
       ^^^^^^^^
"and possibly repeatedly".

> +any shared library is loaded or unloaded. Typically, you would
                                           ^^^
Two spaces between sentences, please.

> +a so called @dfn{pending breakpoint} --- breakpoint that is not yet
> +resolved to address.

"breakpoint whose address is not yet resolved".

> +After the program is run, whenever a new shared library is loaded,
> +@value{GDBN} reevaluates all breakpoints.  In case a newly loaded
> +shared library contains the symbol or line referred to by breakpoint,
> +breakpoint is resolved and becomes an ordinary breakpoint.  If a
> +library is unloaded, all breakpoints it in become pending again.

Suggest to reword slightly like this:

  After the program is run, whenever a new shared library is loaded,
  @value{GDBN} reevaluates all the breakpoints.  When a newly loaded
  shared library contains the symbol or line referred to by some
  pending breakpoint, that breakpoint is resolved and becomes an
  ordinary breakpoint.  When a library is unloaded, all breakpoints
  that refer to its symbols or source lines become pending again.

> +a new location will be added to the existing breakpoint.

Suggest "a new location is added to the list of locations for the
breakpoint".

Re: Docs and NEWS for breakpoint changes

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 6174 bytes --]

On Thursday 27 September 2007 01:12:47 Eli Zaretskii wrote:
> > From: Vladimir Prus <vladimir@codesourcery.com>
> > Date: Wed, 26 Sep 2007 22:07:42 +0400
> > Now that the code patches for my breakpoint changes are in,
> > here's the doc patch and NEWS addition.
> 
> Thanks!
> 
> > Comments?
> 
> A few:
> 
> > +* Pending breakpoints where changed to not change its number when
> > +  resolved.                                       ^^^
> 
> It's "breakpoints" (plural), so "its" is wrong.
> 
> "where" is also wrong; you meant "were".  But please don't use past
> tense in NEWS, present tense is better:
> 
>   Pending breakpoints no longer change their number when their address
>   is resolved.
> 
> > +* Support for breakpoints with multiple locations was implemented,
> 
> Avoiding passive voice makes text simpler and clearer:
> 
>    GDB now supports breakpoints with multiple locations,
> 
> (also present tense instead of past).
> 
> > +that are not enabled.  An optional @samp{(p)} suffix marks pending
> > +breakpoints --- breakpoints for which address is either not yet
> > +resolved, pending load of a shared library, or for which address was
> > +in a shared library that was since resolved.  Such breakpoint won't
> > +fire until a shared library that has the symbol or line referred by
> > +breakpoint is loaded.  See below for details.
> 
> I'm left confused: if the address ``was since resolved'', then why do
> we still mark the breakpoint with "(p)"?

Sorry, "was since resolved" should read "was since unloaded"

> >                                                                  For a
> > +pending breakpoint that never had its address known,
> 
> I think this is better:
> 
>   For a pending address whose address is not yet known,
	          ^^^^^^^

Did you mean "breakpoint" instead of first "address"?

> > +have @samp{<MULTIPLE>} in this field -- see below for details.
>                                         ^^
> Please use "---" -- 3 dashes in a row, not 2 -- for an em-dash.
> 
> > +For a C++ constructor, the gcc compiler generates several function
> > +bodies used in different cases.
> 
> Please use C@t{++}, it looks better in print (there are several more
> instances like this one).  Also, we use "@value{NGCC}" instead of a
> literal "gcc" in this manual.  And instead of "several function
> bodies", isn't it more accurate to say "several instances of the
> function body"?

I'm not quite sure I see the difference; I've changed this.

> 
> > +For a C++ template function, a given line in the function can
> > +correspond to unbounded set of instantiations.
>               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> "to any number of instantiations" is better.


> 
> > +For an inlined function, a given line can correspond to
> > +several places where that function is inlined.
> 
> "given source line" or even "a breakpoint at a given source line" will
> make things clearer, I think.

I went with "given source line", since at this point we're still
talking about what language constructs can correspond to multiple PC
values.
 
> > +In all those cases, @value{GDBN} will associate the breakpoint
> > +with all relevant locations.
> 
> Perhaps we better say "@value{GDBN} will insert a breakpoint at all
> the relevant locations".  "Associate the breakpoint" leaves me
> wondering what does "associate" mean in this context.

You're right.

> 
> > +A breakpoint with multiple locations is displayed in the
> > +breakpoint table using several rows --- one header row, followed
> > +by one row for each breakpoint location. The header row
> > +has @samp{<MULTIPLE>} in the address column.  The rows for
> > +individual locations contain the actual addresses for locations,
> > +and say what functions those locations are in.  The number
> > +column for a location has number in the format 
> > +@var{breakpoint-number}.@var{location-number}.
> 
> Example, please.  A picture is worth a thousand words.

I've added one. Is example with a line as long as 75 characters OK?
It looked good to me in PDF and info formats, but just to check.

> > +Each location can be individually enabled or disabled by passing
> > +the @var{breakpoint-number}.@var{location-number} to the @code{enable}
> > +or @code{disable} commands.
> 
>   Each location can be individually enabled or disabled by passing
>   @var{breakpoint-number}.@var{location-number} as argument to the
>   @code{enable} and @code{disable} commands.
> 
> > +It's quite common to have a breakpoint inside a shared library.
> > +Further, the shared library may be loaded and unloaded explicitly,
> 
> This "further" thing does not add anything to the sentence; just
> remove it.
> 
> > +and possible repeatedly, as the program is executed.  To support
>        ^^^^^^^^
> "and possibly repeatedly".

Yes.

> 
> > +any shared library is loaded or unloaded. Typically, you would
>                                            ^^^
> Two spaces between sentences, please.
> 
> > +a so called @dfn{pending breakpoint} --- breakpoint that is not yet
> > +resolved to address.
> 
> "breakpoint whose address is not yet resolved".
> 
> > +After the program is run, whenever a new shared library is loaded,
> > +@value{GDBN} reevaluates all breakpoints.  In case a newly loaded
> > +shared library contains the symbol or line referred to by breakpoint,
> > +breakpoint is resolved and becomes an ordinary breakpoint.  If a
> > +library is unloaded, all breakpoints it in become pending again.
> 
> Suggest to reword slightly like this:
> 
>   After the program is run, whenever a new shared library is loaded,
>   @value{GDBN} reevaluates all the breakpoints.  When a newly loaded
>   shared library contains the symbol or line referred to by some
>   pending breakpoint, that breakpoint is resolved and becomes an
>   ordinary breakpoint.  When a library is unloaded, all breakpoints
>   that refer to its symbols or source lines become pending again.

Thanks, this is better.
 
> > +a new location will be added to the existing breakpoint.
> 
> Suggest "a new location is added to the list of locations for the
> breakpoint".

Thanks for review. I attach the revised version.

- Volodya
 



[-- Attachment #2: breakpoint_docs.diff --]
[-- Type: text/x-diff, Size: 8051 bytes --]

Index: NEWS
===================================================================
RCS file: /cvs/src/src/gdb/NEWS,v
retrieving revision 1.239
diff -u -p -r1.239 NEWS
--- NEWS	17 Sep 2007 19:30:05 -0000	1.239
+++ NEWS	27 Sep 2007 18:26:49 -0000
@@ -3,6 +3,13 @@
 
 *** Changes since GDB 6.7
 
+* Pending breakpoints no longer change their number when their address
+  is resolved.
+
+* GDB now supports breakpoints with multiple locations,
+  including breakpoints on C++ constructors, inside C++ templates,
+  and in inlined functions.
+
 *** Changes in GDB 6.6
 
 * Resolved 101 resource leaks, null pointer dereferences, etc. in gdb, 
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.432
diff -u -p -r1.432 gdb.texinfo
--- doc/gdb.texinfo	16 Sep 2007 14:59:30 -0000	1.432
+++ doc/gdb.texinfo	27 Sep 2007 18:26:58 -0000
@@ -2991,11 +2991,17 @@ Breakpoint, watchpoint, or catchpoint.
 Whether the breakpoint is marked to be disabled or deleted when hit.
 @item Enabled or Disabled
 Enabled breakpoints are marked with @samp{y}.  @samp{n} marks breakpoints
-that are not enabled.
+that are not enabled.  An optional @samp{(p)} suffix marks pending
+breakpoints --- breakpoints for which address is either not yet
+resolved, pending load of a shared library, or for which address was
+in a shared library that was since unloaded.  Such breakpoint won't
+fire until a shared library that has the symbol or line referred by
+breakpoint is loaded.  See below for details.
 @item 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 @samp{<PENDING>}.
+Where the breakpoint is in your program, as a memory address.  For a
+pending breakpoint whose address is not yet known,  this field will
+contain @samp{<PENDING>}.  A breakpoint with several locations will
+have @samp{<MULTIPLE>} in this field --- see below for details.
 @item 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
@@ -3032,23 +3038,83 @@ your program.  There is nothing silly or
 the breakpoints are conditional, this is even useful
 (@pxref{Conditions, ,Break Conditions}).
 
-@cindex pending breakpoints
-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 @value{GDBN} to create a special breakpoint (known as
-a @dfn{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
-@value{GDBN} 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.
+It is possible that a breakpoints correspond to several locations 
+in your program.  Examples of this situation are:
+
+@itemize @bullet
+
+@item
+For a C@t{++} constructor, the gcc compiler generates several
+instances of the function body, used in different cases.
 
-@value{GDBN} provides some additional commands for controlling pending
-breakpoint support:
+@item
+For a C@t{++} template function, a given line in the function can
+correspond to any number of instantiations.
+
+@item
+For an inlined function, a given source line can correspond to
+several places where that function is inlined.
+
+@end itemize
+
+In all those cases, @value{GDBN} will insert a breakpoint at all
+the relevant locations.
+
+A breakpoint with multiple locations is displayed in the
+breakpoint table using several rows --- one header row, followed
+by one row for each breakpoint location. The header row
+has @samp{<MULTIPLE>} in the address column.  The rows for
+individual locations contain the actual addresses for locations,
+and say what functions those locations are in.  The number
+column for a location has number in the format 
+@var{breakpoint-number}.@var{location-number}.
+
+For example:
+@smallexample
+Num     Type           Disp Enb  Address    What
+1       breakpoint     keep y    <MULTIPLE>
+        stop only if i==1
+        breakpoint already hit 1 time
+1.1                         y    0x080486a2 in void foo<int>() at t.cc:8
+1.2                         y    0x080486ca in void foo<double>() at t.cc:8
+@end smallexample
+
+Each location can be individually enabled or disabled by passing
+@var{breakpoint-number}.@var{location-number} as argument to the
+@code{enable} and @code{disable} commands.
+
+@cindex pending breakpoints
+It's quite common to have a breakpoint inside a shared library.
+The shared library may be loaded and unloaded explicitly,
+and possibly repeatedly, as the program is executed.  To support
+this use case, @value{GDBN} updates breakpoint locations whenever
+any shared library is loaded or unloaded. Typically, you would
+set a breakpoint in a shared library at the beginning of your 
+debugging session, when the library is not loaded, and when the
+symbols from the library are not available.  When you try to set
+breakpoint, @value{GDBN} will ask you if you want to set
+a so called @dfn{pending breakpoint} --- breakpoint whose address 
+is not yet resolved.
+
+After the program is run, whenever a new shared library is loaded,
+@value{GDBN} reevaluates all the breakpoints.  When a newly loaded
+shared library contains the symbol or line referred to by some
+pending breakpoint, that breakpoint is resolved and becomes an
+ordinary breakpoint.  When a library is unloaded, all breakpoints
+that refer to its symbols or source lines become pending again.
+
+This logic works for breakpoints with multiple locations, too.  For
+example, if you have a breakpoint in a C@t{++} template function, and
+a newly loaded shared library has an instantiation of that template,
+a new location is added to the list of locations for the breakpoint.
+
+Except for having unresolved address, pending breakpoints do not
+differ from regular breakpoints.  You can set conditions or commands,
+enable and disable them and perform other breakpoint operations.
+
+@value{GDBN} provides some additional commands for controlling what
+happens when the @samp{break} command cannot resolve breakpoint
+address specification to an address:
 
 @kindex set breakpoint pending
 @kindex show breakpoint pending
@@ -3070,19 +3136,9 @@ not affect any pending breakpoints previ
 Show the current behavior setting for creating pending breakpoints.
 @end table
 
-@cindex operations allowed on 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 @value{GDBN} to not attempt to resolve the breakpoint on any subsequent
-shared library load.  When a pending breakpoint is re-enabled,
-@value{GDBN} 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.
+The settings above only affect the @code{break} command and its
+variants.  Once breakpoint is set, it will be automatically updated
+as shared libraries are loaded and unloaded.
 
 @cindex automatic hardware breakpoints
 For some targets, @value{GDBN} can automatically decide if hardware or

Re: Docs and NEWS for breakpoint changes

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Thu, 27 Sep 2007 22:27:34 +0400
> Cc: gdb-patches@sources.redhat.com
> 
> > > +pending breakpoint that never had its address known,
> > 
> > I think this is better:
> > 
> >   For a pending address whose address is not yet known,
> 	          ^^^^^^^
> 
> Did you mean "breakpoint" instead of first "address"?

Yes, sorry.

> > Example, please.  A picture is worth a thousand words.
> 
> I've added one. Is example with a line as long as 75 characters OK?

@smallexample can handle this (which is why we use it instead of
@example).

> Thanks for review. I attach the revised version.

It's fine, except for a few small gotchas:

> +It is possible that a breakpoints correspond to several locations 
                       ^^^^^^^^^^^^^^^^^^^^^^^^
"a breakpoint corresponds".

> +For a C@t{++} constructor, the gcc compiler generates several
                                  ^^^
You forgot to replace with @value{NGCC}.

> +by one row for each breakpoint location. The header row
                                          ^^
Still only one space.

> +any shared library is loaded or unloaded. Typically, you would
                                           ^^
And here.

Re: Docs and NEWS for breakpoint changes

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 1423 bytes --]

On Friday 28 September 2007 00:49:07 Eli Zaretskii wrote:
> > From: Vladimir Prus <vladimir@codesourcery.com>
> > Date: Thu, 27 Sep 2007 22:27:34 +0400
> > Cc: gdb-patches@sources.redhat.com
> > 
> > > > +pending breakpoint that never had its address known,
> > > 
> > > I think this is better:
> > > 
> > >   For a pending address whose address is not yet known,
> > 	          ^^^^^^^
> > 
> > Did you mean "breakpoint" instead of first "address"?
> 
> Yes, sorry.
> 
> > > Example, please.  A picture is worth a thousand words.
> > 
> > I've added one. Is example with a line as long as 75 characters OK?
> 
> @smallexample can handle this (which is why we use it instead of
> @example).
> 
> > Thanks for review. I attach the revised version.
> 
> It's fine, except for a few small gotchas:
> 
> > +It is possible that a breakpoints correspond to several locations 
>                        ^^^^^^^^^^^^^^^^^^^^^^^^
> "a breakpoint corresponds".
> 
> > +For a C@t{++} constructor, the gcc compiler generates several
>                                   ^^^
> You forgot to replace with @value{NGCC}.
> 
> > +by one row for each breakpoint location. The header row
>                                           ^^
> Still only one space.
> 
> > +any shared library is loaded or unloaded. Typically, you would
>                                            ^^
> And here.

Thanks. I've checked in the attached.

- Volodya





[-- Attachment #2: breakpoint_docs.diff --]
[-- Type: text/x-diff, Size: 9225 bytes --]

Index: ChangeLog
===================================================================
RCS file: /cvs/src/src/gdb/ChangeLog,v
retrieving revision 1.8721
diff -u -p -r1.8721 ChangeLog
--- ChangeLog	27 Sep 2007 18:48:32 -0000	1.8721
+++ ChangeLog	28 Sep 2007 06:21:01 -0000
@@ -1,3 +1,8 @@
+2007-09-28  Vladimir Prus  <vladimir@codesourcery.com>
+
+	* NEW: Mention pending breakpoint changes and
+	support for breakpoints at multiple locations.
+	
 2007-09-27  Daniel Jacobowitz  <dan@codesourcery.com>
 
 	* arm-linux-tdep.c (arm_linux_software_single_step): New.
Index: NEWS
===================================================================
RCS file: /cvs/src/src/gdb/NEWS,v
retrieving revision 1.239
diff -u -p -r1.239 NEWS
--- NEWS	17 Sep 2007 19:30:05 -0000	1.239
+++ NEWS	28 Sep 2007 06:21:03 -0000
@@ -3,6 +3,13 @@
 
 *** Changes since GDB 6.7
 
+* Pending breakpoints no longer change their number when their address
+  is resolved.
+
+* GDB now supports breakpoints with multiple locations,
+  including breakpoints on C++ constructors, inside C++ templates,
+  and in inlined functions.
+
 *** Changes in GDB 6.6
 
 * Resolved 101 resource leaks, null pointer dereferences, etc. in gdb, 
Index: doc/ChangeLog
===================================================================
RCS file: /cvs/src/src/gdb/doc/ChangeLog,v
retrieving revision 1.700
diff -u -p -r1.700 ChangeLog
--- doc/ChangeLog	16 Sep 2007 14:59:30 -0000	1.700
+++ doc/ChangeLog	28 Sep 2007 06:21:05 -0000
@@ -1,3 +1,9 @@
+2007-09-28  Vladimir Prus  <vladimir@codesourcery.com>
+
+	* gdb.texinfo (Setting Breakpoints): Revise
+	documentation for pending breakpoints.  Document
+	breakpoints with multiple locations.
+	
 2007-09-19  Vladimir Prus  <vladimir@codesourcery.com>
 
 	* gdb.texinfo (Miscellaneous gdb/mi Commands):
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.432
diff -u -p -r1.432 gdb.texinfo
--- doc/gdb.texinfo	16 Sep 2007 14:59:30 -0000	1.432
+++ doc/gdb.texinfo	28 Sep 2007 06:21:14 -0000
@@ -2991,11 +2991,17 @@ Breakpoint, watchpoint, or catchpoint.
 Whether the breakpoint is marked to be disabled or deleted when hit.
 @item Enabled or Disabled
 Enabled breakpoints are marked with @samp{y}.  @samp{n} marks breakpoints
-that are not enabled.
+that are not enabled.  An optional @samp{(p)} suffix marks pending
+breakpoints --- breakpoints for which address is either not yet
+resolved, pending load of a shared library, or for which address was
+in a shared library that was since unloaded.  Such breakpoint won't
+fire until a shared library that has the symbol or line referred by
+breakpoint is loaded.  See below for details.
 @item 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 @samp{<PENDING>}.
+Where the breakpoint is in your program, as a memory address.  For a
+pending breakpoint whose address is not yet known,  this field will
+contain @samp{<PENDING>}.  A breakpoint with several locations will
+have @samp{<MULTIPLE>} in this field --- see below for details.
 @item 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
@@ -3032,23 +3038,83 @@ your program.  There is nothing silly or
 the breakpoints are conditional, this is even useful
 (@pxref{Conditions, ,Break Conditions}).
 
-@cindex pending breakpoints
-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 @value{GDBN} to create a special breakpoint (known as
-a @dfn{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
-@value{GDBN} 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.
+It is possible that a breakpoint correspond to several locations 
+in your program.  Examples of this situation are:
+
+@itemize @bullet
+
+@item
+For a C@t{++} constructor, the @value{NGCC} compiler generates several
+instances of the function body, used in different cases.
 
-@value{GDBN} provides some additional commands for controlling pending
-breakpoint support:
+@item
+For a C@t{++} template function, a given line in the function can
+correspond to any number of instantiations.
+
+@item
+For an inlined function, a given source line can correspond to
+several places where that function is inlined.
+
+@end itemize
+
+In all those cases, @value{GDBN} will insert a breakpoint at all
+the relevant locations.
+
+A breakpoint with multiple locations is displayed in the
+breakpoint table using several rows --- one header row, followed
+by one row for each breakpoint location.  The header row
+has @samp{<MULTIPLE>} in the address column.  The rows for
+individual locations contain the actual addresses for locations,
+and say what functions those locations are in.  The number
+column for a location has number in the format 
+@var{breakpoint-number}.@var{location-number}.
+
+For example:
+@smallexample
+Num     Type           Disp Enb  Address    What
+1       breakpoint     keep y    <MULTIPLE>
+        stop only if i==1
+        breakpoint already hit 1 time
+1.1                         y    0x080486a2 in void foo<int>() at t.cc:8
+1.2                         y    0x080486ca in void foo<double>() at t.cc:8
+@end smallexample
+
+Each location can be individually enabled or disabled by passing
+@var{breakpoint-number}.@var{location-number} as argument to the
+@code{enable} and @code{disable} commands.
+
+@cindex pending breakpoints
+It's quite common to have a breakpoint inside a shared library.
+The shared library may be loaded and unloaded explicitly,
+and possibly repeatedly, as the program is executed.  To support
+this use case, @value{GDBN} updates breakpoint locations whenever
+any shared library is loaded or unloaded.  Typically, you would
+set a breakpoint in a shared library at the beginning of your 
+debugging session, when the library is not loaded, and when the
+symbols from the library are not available.  When you try to set
+breakpoint, @value{GDBN} will ask you if you want to set
+a so called @dfn{pending breakpoint} --- breakpoint whose address 
+is not yet resolved.
+
+After the program is run, whenever a new shared library is loaded,
+@value{GDBN} reevaluates all the breakpoints.  When a newly loaded
+shared library contains the symbol or line referred to by some
+pending breakpoint, that breakpoint is resolved and becomes an
+ordinary breakpoint.  When a library is unloaded, all breakpoints
+that refer to its symbols or source lines become pending again.
+
+This logic works for breakpoints with multiple locations, too.  For
+example, if you have a breakpoint in a C@t{++} template function, and
+a newly loaded shared library has an instantiation of that template,
+a new location is added to the list of locations for the breakpoint.
+
+Except for having unresolved address, pending breakpoints do not
+differ from regular breakpoints.  You can set conditions or commands,
+enable and disable them and perform other breakpoint operations.
+
+@value{GDBN} provides some additional commands for controlling what
+happens when the @samp{break} command cannot resolve breakpoint
+address specification to an address:
 
 @kindex set breakpoint pending
 @kindex show breakpoint pending
@@ -3070,19 +3136,9 @@ not affect any pending breakpoints previ
 Show the current behavior setting for creating pending breakpoints.
 @end table
 
-@cindex operations allowed on 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 @value{GDBN} to not attempt to resolve the breakpoint on any subsequent
-shared library load.  When a pending breakpoint is re-enabled,
-@value{GDBN} 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.
+The settings above only affect the @code{break} command and its
+variants.  Once breakpoint is set, it will be automatically updated
+as shared libraries are loaded and unloaded.
 
 @cindex automatic hardware breakpoints
 For some targets, @value{GDBN} can automatically decide if hardware or