Re: [PATCH 11/11] Add TLS NEWS entry and document 'set force-internal-tls-address-lookup' command

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 10 Oct 2024 16:27:50 -0700
> From: Kevin Buettner <kevinb@redhat.com>
> Cc: gdb-patches@sourceware.org
> 
> I'm trying to figure out where in the doc to add background
> material regarding TLS.
> 
> Adding it to the text explaining the new command doesn't really
> fit with the way that other commands are documented.  It seems
> to me that it ought to be placed in some prefatory remarks.
> 
> If so, should it stay within "Debugging Programs with Multiple
> Threads"?  Or would it make sense to make a new section, perhaps named
> "Thread Local Storage"?

We could leave it in the multiple-threads section (as the text is not
too long, and is related to threads), or we could add a new section
under "Data".  In the latter case, you'd need to use cross-references
judiciously, both in the new section and in "Threads", to provide the
reader with all the relevant information, since libthread_db and the
commands related to it are only discussed in "Threads", and the new
command will be described there as well.

> Without getting bogged down with texinfo markup yet, here
> is what I propose saying about TLS:
> 
>     For some debugging targets, GDB has support for accessing
>     variables that reside in Thread Local Storage (TLS).  TLS
>     variables are similar to global variables, except that each thread
>     has its own copy of the variable.  While often used in
>     multi-threaded programs, TLS variables can also be used in
>     programs without threads.  The C library variable 'errno' is,
>     perhaps, the most prominent example of a TLS variable that is
>     frequently used in non-threaded programs.  For targets where GDB
>     does not have good TLS support, printing the value of errno might
>     not be directly possible.
> 
>     Linux and FreeBSD targets have support for printing TLS variables. 
>     On Linux, the helper library, libthread_db, is used to help
>     resolve the addresses of TLS variables.  Some FreeBSD and some
>     Linux targets also have GDB-internal TLS resolution code.  Linux
>     targets will attempt to use the TLS address lookup functionality
>     provided by libthread_db, but will fall back to using its
>     internal TLS support when libthread_db is not available.  This can
>     happen in cross-debugging scenarios or when debugging programs
>     that are linked in such a way that libthread_db support is
>     unavailable - this includes statically linked programs, GLIBC
>     versions earlier than 2.34, and use of other (non-GLIBC) C libraries.

LGTM.

> There's a lot more that could be said about errno.  Earlier this
> year, I wrote an article about it.  See:
> 
> https://developers.redhat.com/articles/2024/06/05/why-your-errno-value-isnt-printing-gdb-and-what-do-about-it
> 
> That article dealt with errno problems on Linux, but some of the same
> tricks, with some tweaks, might apply to other environments too.  It
> might make sense to try document some ways to obtain the value of
> errno when "print errno" doesn't just work.  But that can be the
> topic of another patch.

We can have a summary of that in this new section.

Btw, the MS-Windows situation is similar to what you describe for
Linux.  The MinGW <errno.h> says:

  _CRTIMP int *__cdecl  _errno(void);
  #define errno           (*_errno())

So one can display errno by calling this function with an explicit
type-cast.  Maybe we should mention that if and when we add this to
the GDB manual.

> With regard to the question of why you might want to force use of
> internal TLS lookup, it's mostly for testing purposes.

If this is for testing, shouldn't it be a maint command?