[PATCH] clarify doc for __builtin_return_address

[Pedro Alves]

On 05/21/2015 08:19 PM, Martin Sebor wrote:
> A program I instrumented to help me debug an otherwise unrelated
> problem in 5.1.0 has been crashing in calls to
> __builtin_return_address. After checking the manual, I didn't
> think I was doing anything wrong. I then did some debugging and
> found that the function simply isn't safe to call with non-zero
> arguments near the top of the stack. That seemed like a bug to
> me so I created a small test case and ran it on a few targets
> to see if the problem was isolated to just powerpc (where I'm
> working at the moment) or more general. It turned out not to
> be target-specific. Before opening a bug, I checked Bugzilla
> to see if it's already been reported but couldn't find any open
> reports. To be sure I wasn't missing something, I expanded my
> search to already resolved bugs. That's when I finally found
> pr8743 which had been closed years ago as a documentation issue,
> after adding the following to the manual:
> 
>    This function should only be used with a nonzero argument
>    for debugging purposes.
> 
> Since I was using the function exactly for this purpose, I'd
> like to propose the patch below to clarify the effects of the
> function to set the right expectations and help others avoid
> the effort it took me to figure out this is by design.
> 
> Does anyone have any concerns with this update or is it okay
> to check in?

Sounds like a good candidate for a warning.

Thanks,
Pedro Alves