[PATCH v2] stdlib: Describe __cxa_finalize usage in function comment

[Jonathan Wakely]

On 31/05/24 14:53 +0200, Florian Weimer wrote:
>---
>v2: Typo fixes from Joe & Jonathan.
> stdlib/cxa_finalize.c | 17 ++++++++++++++++-
> 1 file changed, 16 insertions(+), 1 deletion(-)


+Reviewed-by: Jonathan Wakely <jwakely@redhat.com>


>diff --git a/stdlib/cxa_finalize.c b/stdlib/cxa_finalize.c
>index 258fa56ce5..496141d802 100644
>--- a/stdlib/cxa_finalize.c
>+++ b/stdlib/cxa_finalize.c
>@@ -24,7 +24,22 @@
>
> /* If D is non-NULL, call all functions registered with `__cxa_atexit'
>    with the same dso handle.  Otherwise, if D is NULL, call all of the
>-   registered handlers.  */
>+   registered handlers.
>+
>+   A __cxa_finalize function is declared in the libstdc++ <cxxabi.h>
>+   header, and the libstdc++ implementation calls this function.  GCC
>+   calls the glibc variant directly from its CRT files, from an ELF
>+   destructor.  this call always passes a non-null D argument.  In the
>+   current implementation, the GCC-provided __cxa_finalize call is
>+   responsible for removing the registered __cxa_atexit (C++)
>+   destructors of an object that is undergoing dlclose.  Note that
>+   this is specific to dlclose.  During process termination, glibc
>+   invokes the __run_exit_handlers, which calls registered
>+   __cxa_atexit (C++) destructors in reverse registration order,
>+   across all objects.  The subsequent GCC-provided __cxa_finalize
>+   calls (which are ordered according to ELF object dependencies, not
>+   __cxa_atexit call order, and group destructor calls per object
>+   during dlclose) do not result in further destructor invocations.  */
> void
> __cxa_finalize (void *d)
> {
>
>base-commit: 46b5e98ef6f1b9f4b53851f152ecb8209064b26c
>