[PATCH v2] gdb/doc: Explain linker namespaces

[Guinevere Larsen]

Recent GDB commits added more features related to linker namespaces and
documented them on the manual, but did not add a convenient way for a
user to understand what they are. This commit adds a quick explanation
of what they are.

It also fixes the inconsistency of using "linker namespaces" and
"linkage namespaces", by always using the first form to avoid user
confusion.
---
 gdb/doc/gdb.texinfo | 30 +++++++++++++++++++-----------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7d06e1f5fa4..39a04b9b6ee 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -13106,14 +13106,15 @@ environment variable.
 
 @vindex $_active_linker_namespaces@r{, convenience variable}
 @item $_active_linker_namespaces
-Number of active linkage namespaces in the inferior.  In systems with no
-support for linkage namespaces, this variable will always be set to @samp{1}.
+Number of active linker namespaces in the inferior(@pxref{Files}).  In systems
+with no support for linker namespaces, this variable will always be set to
+@samp{1}.
 
 @vindex $_linker_namespace@r{, convenience variable}
 @item $_linker_namespace
-The namespace which contains the current location in the inferior.  This
-returns @value{GDBN}'s internal numbering for the namespace.  In systems with no
-support for linker namespaces, this variable will always be set to
+The namespace which contains the current location in the inferior(@pxref{Files}).
+This returns @value{GDBN}'s internal numbering for the namespace.  In systems
+with no support for linker namespaces, this variable will always be set to
 @samp{0}.
 
 @end table
@@ -22242,11 +22243,18 @@ be determined then the address range for the @code{.text} section from
 the library will be listed.  If the @code{.text} section cannot be
 found then no addresses will be listed.
 
-On systems that support linkage namespaces, the output includes an
+On systems that support linker namespaces, the output includes an
 additional column @code{NS} if the inferior has more than one active
-namespace when the command is used.  This column the linkage namespace
+namespace when the command is used.  This column the linker namespace
 that the shared library was loaded into.
 
+@cindex linker namespaces
+Linker namespaces are a feature of some standard libraries, that allow
+shared objects to be loaded in isolated environment, eliminating the
+possibility that those objects may cross-talk.  Each set of isolated
+shared objects is said to belong to a "namespace", and linker related
+actions such as relocations do not cross namespace boundaries.
+
 @kindex info dll
 @item info dll @var{regex}
 This is an alias of @code{info sharedlibrary}.
@@ -22286,10 +22294,10 @@ conditions or commands as a catchpoint does.
 @item info linker-namespaces
 @item info linker-namespaces @code{[[@var{n}]]}
 
-With no argument, print the number of linker namespaces which are
-currently active --- that is, namespaces that have libraries loaded
-into them.  Then, it prints the number of libraries loaded into each
-namespace, and all the libraries loaded into them, in the same way
+With no argument, print the number of linker namespaces (@pxref{Files})
+which are currently active --- that is, namespaces that have libraries
+loaded into them.  Then, it prints the number of libraries loaded into
+each namespace, and all the libraries loaded into them, in the same way
 as @code{info sharedlibrary}.
 
 If an argument @code{[[@var{n}]]} is provided, only prints the

base-commit: 21b25b168dc6ed25a14c88fa43ae8128487cb557
-- 
2.49.0