[PATCH] gdb/doc: Explain linker namespaces

[PATCH] 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 | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7d06e1f5fa4..60e853ffc50 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -13106,8 +13106,8 @@ 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.  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
@@ -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
+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}.

base-commit: 96662aacaa0cf0a9766d874fc9577a5da417dbcc
-- 
2.49.0

Re: [PATCH] gdb/doc: Explain linker namespaces

[Eli Zaretskii]

> From: Guinevere Larsen <guinevere@redhat.com>
> Cc: eliz@gnu.org,
> 	Guinevere Larsen <guinevere@redhat.com>
> Date: Fri,  6 Jun 2025 12:24:23 -0300
> 
> 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 | 15 +++++++++++----
>  1 file changed, 11 insertions(+), 4 deletions(-)

Thanks.

> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -13106,8 +13106,8 @@ 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.  In systems with no
> +support for linker namespaces, this variable will always be set to @samp{1}.

Please add here a cross-reference to where linker namespaces are
described.

> +@cindex Linker Namespaces

Index entries should try not to use upper-case letters, unless really
necessary.  This is because in some locales upper-case letters'
sorting order is different from the US-ASCII locale, and we don't want
the sorting of the index entries depend on the locale where the manual
is produced.

> +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

Please use ``namespace'', not "namespace".  The former produces
prettier output in the printed version of the manual.

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

Re: [PATCH] gdb/doc: Explain linker namespaces

[Guinevere Larsen]

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

On 6/6/25 3:48 PM, Eli Zaretskii wrote:
>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -13106,8 +13106,8 @@ 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.  In systems with no
>> +support for linker namespaces, this variable will always be set to @samp{1}.
> Please add here a cross-reference to where linker namespaces are
> described.

I don't know how to do that, what texinfo macro(? command?) should I use?

-- 
Cheers,
Guinevere Larsen
She/Her/Hers

[-- Attachment #2: Type: text/html, Size: 1271 bytes --]

Re: [PATCH] gdb/doc: Explain linker namespaces

[Eli Zaretskii]

> Date: Fri, 6 Jun 2025 16:00:00 -0300
> Cc: gdb-patches@sourceware.org
> From: Guinevere Larsen <guinevere@redhat.com>
> 
> On 6/6/25 3:48 PM, Eli Zaretskii wrote:
> 
>  --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -13106,8 +13106,8 @@ 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.  In systems with no
> +support for linker namespaces, this variable will always be set to @samp{1}.
> 
> Please add here a cross-reference to where linker namespaces are
> described.
> 
> I don't know how to do that, what texinfo macro(? command?) should I use?

Something like this:

 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}.

[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

Re: [PATCH v2] gdb/doc: Explain linker namespaces

[Eli Zaretskii]

> From: Guinevere Larsen <guinevere@redhat.com>
> Cc: eliz@gnu.org,
> 	Guinevere Larsen <guinevere@redhat.com>
> Date: Fri,  6 Jun 2025 16:45:33 -0300
> 
> -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
                                                    ^^
Please leave a space before the open paren there.  These parentheses
are output to the formatted manual, so they need to adhere to rules of
English.

>  @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}).
                                                                    ^^^^^^^^^^^^^
There's no need to have the @pxref here, since we just had a cross
reference a dozen lines above.

> @@ -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})

Likewise here: the reference is to the same node as the one in which
this text appears, so there's no need to have a cross-reference here.

Thanks.

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

[PATCH v3] 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 | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 4d3a2d0bd5e..57eb3695e57 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
+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}.

base-commit: 8b9c9b26e18a63aae5b7fcac6b68cede5b61aaf3
-- 
2.49.0

Re: [PATCH v3] gdb/doc: Explain linker namespaces

[Eli Zaretskii]

> From: Guinevere Larsen <guinevere@redhat.com>
> Cc: Guinevere Larsen <guinevere@redhat.com>
> Date: Mon, 16 Jun 2025 08:55:21 -0300
> 
> 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 | 23 +++++++++++++++--------
>  1 file changed, 15 insertions(+), 8 deletions(-)

Thanks, this is okay, with two minor comments:

> +@cindex linker namespaces
> +Linker namespaces are a feature of some standard libraries, that allow

Please enclose "Linker namespaces" in @dfn, as this text introduces
new terminology.

> +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

The "namespace" part should be quote ``like this'', i.e. with single
quoting characters -- this will produce nicer results in the printed
output.

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

Re: [PATCH v3] gdb/doc: Explain linker namespaces

[Guinevere Larsen]

On 6/16/25 9:27 AM, Eli Zaretskii wrote:
>> From: Guinevere Larsen <guinevere@redhat.com>
>> Cc: Guinevere Larsen <guinevere@redhat.com>
>> Date: Mon, 16 Jun 2025 08:55:21 -0300
>>
>> 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 | 23 +++++++++++++++--------
>>   1 file changed, 15 insertions(+), 8 deletions(-)
> Thanks, this is okay, with two minor comments:
>
>> +@cindex linker namespaces
>> +Linker namespaces are a feature of some standard libraries, that allow
> Please enclose "Linker namespaces" in @dfn, as this text introduces
> new terminology.
>
>> +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
> The "namespace" part should be quote ``like this'', i.e. with single
> quoting characters -- this will produce nicer results in the printed
> output.
>
> Approved-By: Eli Zaretskii <eliz@gnu.org>
>
Thanks for the review, I've pushed this patch with the fixes

-- 
Cheers,
Guinevere Larsen
She/Her/Hers