On 05/21/2015 01:19 PM, Martin Sebor wrote:
2015-05-21 Martin Sebor <mse...@redhat.com>
* extend.texi (Return Address): Clarify possible effects
of calling the functions with non-zero arguments.
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 7470e40..b37e893 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -7959,7 +7959,8 @@ Additional post-processing of the returned value
may be needed, see
@code{__builtin_extract_return_addr}.
This function should only be used with a nonzero argument for debugging
-purposes.
+purposes since such calls to it can have unpredictable effects, including
+crashing the calling program.
@end deftypefn
@deftypefn {Built-in Function} {void *} __builtin_extract_return_addr
(void *@var{addr})
I think the problem is that the original sentence parses ambiguously --
is it telling you that you must pass a nonzero argument to use it for
debugging purposes, or telling you that you must use calls with a
nonzero argument only for debugging? And adding an additional clause
onto the end only makes it harder to parse.
I suggest rewriting it as something like
Calling this function with a nonzero argument can have unpredictable
effects, including crashing the calling program. Such calls are
typically only useful in debugging situations.
@@ -7998,7 +7999,8 @@ of the stack has been reached, this function
returns @code{0} if
the first frame pointer is properly initialized by the startup code.
This function should only be used with a nonzero argument for debugging
-purposes.
+purposes since such calls to it can have unpredictable effects, including
+crashing the calling program.
@end deftypefn
@node Vector Extensions
Same applies here as well.
-Sandra
