From 6a391e06f953c3390b14020d8cacb6d55f81b2b9 Mon Sep 17 00:00:00 2001 From: Szabolcs Nagy Date: Thu, 28 May 2020 10:28:30 +0100 Subject: [PATCH] doc: Clarify __builtin_return_address [PR94891] The expected semantics and valid usage of __builtin_return_address is not clear since it exposes implementation internals that are normally not meaningful to portable c code. This documentation change tries to clarify the semantics in case the return address is stored in a mangled form. This affects AArch64 when pointer authentication is used for the return address signing (i.e. -mbranch-protection=pac-ret). 2020-07-13 Szabolcs Nagy gcc/ChangeLog: PR target/94891 * doc/extend.texi: Update the text for __builtin_return_address. --- gcc/doc/extend.texi | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index c800b741acf..0fb7e27d9ce 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -11159,18 +11159,31 @@ The @var{level} argument must be a constant integer. 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 @code{0} or a -random value. In addition, @code{__builtin_frame_address} may be used +of the stack has been reached, this function returns an unspecified +value. In addition, @code{__builtin_frame_address} may be used to determine if the top of the stack has been reached. 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 +whereas the address returned by @code{__builtin_return_address} is not. + 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 an address may be used with @code{dladdr} or other interfaces that work +with code addresses. @end deftypefn @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr}) -- 2.30.2