From: Guinevere Larsen <guinevere@redhat.com>
Date: Fri, 6 Jun 2025 14:59:24 +0000 (-0300)
Subject: gdb/doc: Explain linker namespaces
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=d89a57526d1714a0030705145798e5499feef87e;p=thirdparty%2Fbinutils-gdb.git

gdb/doc: Explain linker namespaces

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.

Approved-By: Eli Zaretskii <eliz@gnu.org>
---

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d14777b648f..c41aa89a3c4 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -13106,15 +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
-@samp{0}.
+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 @samp{0}.
 
 @end table
 
@@ -22242,11 +22242,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
+@dfn{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}.