From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 62622 invoked by alias); 21 May 2015 20:06:47 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Received: (qmail 62613 invoked by uid 89); 21 May 2015 20:06:47 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.1 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_LOW,SPF_PASS autolearn=ham version=3.3.2 X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Thu, 21 May 2015 20:06:45 +0000 Received: from svr-orw-fem-04.mgc.mentorg.com ([147.34.97.41]) by relay1.mentorg.com with esmtp id 1YvWjp-0004b1-LT from Sandra_Loosemore@mentor.com ; Thu, 21 May 2015 13:06:41 -0700 Received: from [IPv6:::1] (147.34.91.1) by svr-orw-fem-04.mgc.mentorg.com (147.34.97.41) with Microsoft SMTP Server id 14.3.224.2; Thu, 21 May 2015 13:06:41 -0700 Message-ID: <555E3A88.3060009@codesourcery.com> Date: Thu, 21 May 2015 20:50:00 -0000 From: Sandra Loosemore User-Agent: Mozilla/5.0 (X11; Linux i686; rv:17.0) Gecko/20130329 Thunderbird/17.0.5 MIME-Version: 1.0 To: Martin Sebor CC: Gcc Patch List Subject: Re: [PATCH] clarify doc for __builtin_return_address References: <555E2FC6.60804@redhat.com> In-Reply-To: <555E2FC6.60804@redhat.com> Content-Type: text/plain; charset="UTF-8"; format=flowed Content-Transfer-Encoding: 7bit X-SW-Source: 2015-05/txt/msg02037.txt.bz2 On 05/21/2015 01:19 PM, Martin Sebor wrote: > 2015-05-21 Martin Sebor > > * 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