* NEW: Mention pending breakpoint changes and

	support for breakpoints at multiple locations.
	* gdb.texinfo (Setting Breakpoints): Revise
	documentation for pending breakpoints.  Document
	breakpoints with multiple locations.

2 files changed, 95 insertions, 33 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 67f74b9..4c8e7cd 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -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):
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 4378e0c..9b9d16e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -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 meaningless about this.  When
 the breakpoints are conditional, this is even useful
 (@pxref{Conditions, ,Break Conditions}).
 
+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.
+
+@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
-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.
-
-@value{GDBN} provides some additional commands for controlling pending
-breakpoint support:
+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 previously created.
 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