From: Frédéric Bérat <fberat@redhat.com>
Date: Thu, 2 Oct 2025 17:15:29 +0000 (+0200)
Subject: docs: Add dynamic linker environment variable docs
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d4d472366ba69df7b14eba22a75f887b99855d70;p=thirdparty%2Fglibc.git

docs: Add dynamic linker environment variable docs

The Dynamic Linker chapter now includes a new section detailing
environment variables that influence its behavior.

This new section documents the `LD_DEBUG` environment variable,
explaining how to enable debugging output and listing its various
keywords like `libs`, `reloc`, `files`, `symbols`, `bindings`,
`versions`, `scopes`, `tls`, `all`, `statistics`, `unused`, and `help`.

It also documents `LD_DEBUG_OUTPUT`, which controls where the debug
output is written, allowing redirection to a file with the process ID
appended.

This provides users with essential information for controlling and
debugging the dynamic linker.

Reviewed-by: DJ Delorie <dj@redhat.com>
---

diff --git a/manual/dynlink.texi b/manual/dynlink.texi
index cd05107e6c..1e99a5aab3 100644
--- a/manual/dynlink.texi
+++ b/manual/dynlink.texi
@@ -14,6 +14,8 @@ Dynamic linkers are sometimes called @dfn{dynamic loaders}.
 
 @menu
 * Dynamic Linker Invocation::   Explicit invocation of the dynamic linker.
+* Dynamic Linker Environment Variables:: Environment variables that control the
+                                          dynamic linker.
 * Dynamic Linker Introspection::    Interfaces for querying mapping information.
 * Dynamic Linker Hardening::    Avoiding unexpected issues with dynamic linking.
 @end menu
@@ -349,6 +351,70 @@ probed CPU are omitted.  Nothing is printed if the system does not
 support the XGETBV instruction.
 @end table
 
+@node Dynamic Linker Environment Variables
+@section Dynamic Linker Environment Variables
+
+The behavior of the dynamic linker can be modified through various environment
+variables.
+
+@table @code
+@item LD_DEBUG
+@cindex @code{LD_DEBUG} environment variable
+The @env{LD_DEBUG} environment variable can be set to a comma-separated list
+of keywords to enable debugging output from the dynamic linker.  Setting it to
+@code{help} will display a list of all available keywords.  The output is
+written to standard output by default.
+
+@table @code
+@item libs
+Display library search paths.
+
+@item reloc
+Display relocation processing.
+
+@item files
+Display progress for input file processing.
+
+@item symbols
+Display symbol table processing.
+
+@item bindings
+Display information about symbol binding.
+
+@item versions
+Display version dependencies.
+
+@item scopes
+Display scope information.
+
+@item tls
+Display information about Thread-Local Storage (TLS) handling, including TCB
+allocation, deallocation, and reuse. This is useful for debugging issues
+related to thread creation and lifecycle.
+
+@item all
+All previous options combined.
+
+@item statistics
+Display relocation statistics.
+
+@item unused
+Determined unused DSOs.
+
+@item help
+Display a help message with all available options and exit.
+@end table
+
+@item LD_DEBUG_OUTPUT
+@cindex @code{LD_DEBUG_OUTPUT} environment variable
+If @env{LD_DEBUG} is set, the output is written to standard output by
+default.  If @env{LD_DEBUG_OUTPUT} is set, the output is written to the
+file specified by its value, with the process ID appended. For example, if
+@env{LD_DEBUG_OUTPUT} is set to @file{/tmp/glibc.debug}, the output will be
+written to a file named @file{/tmp/glibc.debug.12345}, where @code{12345} is
+the process ID.
+@end table
+
 @node Dynamic Linker Introspection
 @section Dynamic Linker Introspection