public inbox for gcc-cvs@sourceware.org
help / color / mirror / Atom feed
* [gcc r10-8487] doc: Clarify __builtin_return_address [PR94891]
@ 2020-07-13 18:15 Szabolcs Nagy
0 siblings, 0 replies; only message in thread
From: Szabolcs Nagy @ 2020-07-13 18:15 UTC (permalink / raw)
To: gcc-cvs
https://gcc.gnu.org/g:7e5bb3ce7c784844b1e14b754b58dee08ed5bac8
commit r10-8487-g7e5bb3ce7c784844b1e14b754b58dee08ed5bac8
Author: Szabolcs Nagy <szabolcs.nagy@arm.com>
Date: Thu May 28 10:28:30 2020 +0100
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 <szabolcs.nagy@arm.com>
gcc/ChangeLog:
PR target/94891
* doc/extend.texi: Update the text for __builtin_return_address.
(cherry picked from commit 6a391e06f953c3390b14020d8cacb6d55f81b2b9)
Diff:
---
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 106e2db594e..3743f66dc88 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -11061,18 +11061,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})
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2020-07-13 18:15 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-13 18:15 [gcc r10-8487] doc: Clarify __builtin_return_address [PR94891] Szabolcs Nagy
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).