[PATCH] doc: Clarify __builtin_return_address [PR94891]

[Florian Weimer]

* Szabolcs Nagy:

> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index cced19d2018..0fd32a22599 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi

>  On some machines it may be impossible to determine the return address of
>  any function other than the current one; in such cases, or when the top
> +of the stack has been reached, this function returns an unspecified
> +value.

Can it crash as well?  But that's a pre-existing issue with the wording.

>  Additional post-processing of the returned value may be needed, see
>  @code{__builtin_extract_return_addr}.
>  
> +The stored representation of the return address in memory may be different
> +from the address returned by @code{__builtin_return_address}.  For example
> +on AArch64 the stored address may be mangled with return address signing.
> +
>  Calling this function with a nonzero argument can have unpredictable
>  effects, including crashing the calling program.  As a result, calls
>  that are considered unsafe are diagnosed when the @option{-Wframe-address}
>  option is in effect.  Such calls should only be made in debugging
>  situations.
> +
> +On targets where code addresses are representable as @code{void *},
> +@smallexample
> +void *addr = __builtin_extract_return_addr (__builtin_return_address (0))
> +@end smallexample
> +gives the code address where the current function would return.  For example
> +such address may be used with @code{dladdr} or other interfaces that work
> +with code addresses.
>  @end deftypefn

The change looks reasonable to me.  It is worded in such a way that it
covers architectures which use function descriptors.

Thanks,
Florian