From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 42965 invoked by alias); 1 Dec 2018 04:57:57 -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 42953 invoked by uid 89); 1 Dec 2018 04:57:56 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-16.9 required=5.0 tests=BAYES_00,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,RCVD_IN_DNSWL_NONE,SPF_PASS autolearn=ham version=3.3.2 spammy=draft, restores, intptr_t, arranges 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; Sat, 01 Dec 2018 04:57:54 +0000 Received: from svr-orw-mbx-03.mgc.mentorg.com ([147.34.90.203]) by relay1.mentorg.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-SHA384:256) id 1gSxLj-0002cb-0z from Sandra_Loosemore@mentor.com for gcc-patches@gcc.gnu.org; Fri, 30 Nov 2018 20:57:51 -0800 Received: from [127.0.0.1] (147.34.91.1) by svr-orw-mbx-03.mgc.mentorg.com (147.34.90.203) with Microsoft SMTP Server (TLS) id 15.0.1320.4; Fri, 30 Nov 2018 20:57:48 -0800 To: "gcc-patches@gcc.gnu.org" From: Sandra Loosemore Subject: [doc, rfc] document __builtin_setjmp and __builtin_longjmp Message-ID: <610c694c-9610-b193-9597-64509e06e761@codesourcery.com> Date: Sat, 01 Dec 2018 04:57:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.2.1 MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="------------B177C450D8318405174C02BD" X-SW-Source: 2018-12/txt/msg00004.txt.bz2 --------------B177C450D8318405174C02BD Content-Type: text/plain; charset="utf-8"; format=flowed Content-Transfer-Encoding: 7bit Content-length: 227 I have written a new patch for PR 59039 to address more of the comments there, as well as my own complaints about the draft patch attached to the issue. I'd like to get some feedback on this one before I commit it. -Sandra --------------B177C450D8318405174C02BD Content-Type: text/x-log; name="gcc.log" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="gcc.log" Content-length: 126 2018-11-30 Sandra Loosemore PR c/59039 gcc/ * doc/extend.texi (Nonlocal gotos): New section. --------------B177C450D8318405174C02BD Content-Type: text/x-patch; name="gcc.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="gcc.patch" Content-length: 3262 Index: gcc/doc/extend.texi =================================================================== --- gcc/doc/extend.texi (revision 266688) +++ gcc/doc/extend.texi (working copy) @@ -27,6 +27,7 @@ extensions, accepted by GCC in C90 mode * Local Labels:: Labels local to a block. * Labels as Values:: Getting pointers to labels, and computed gotos. * Nested Functions:: Nested function in GNU C. +* Nonlocal Gotos:: Nonlocal gotos. * Constructing Calls:: Dispatching a call to another function. * Typeof:: @code{typeof}: referring to the type of an expression. * Conditionals:: Omitting the middle operand of a @samp{?:} expression. @@ -520,6 +521,61 @@ bar (int *array, int offset, int size) @} @end smallexample +@node Nonlocal Gotos +@section Nonlocal Gotos +@cindex nonlocal gotos + +GCC provides the built-in functions @code{__builtin_setjmp} and +@code{__builtin_longjmp} which are similar to, but not interchangeable +with, the C library functions @code{setjmp} and @code{longjmp}. +The built-in versions are used internally by GCC's libraries +to implement exception handling on some targets. You should use the +standard C library functions declared in @code{} in user code +instead of the builtins. + +@code{__builtin_setjmp} and @code{__builtin_longjmp} use GCC's normal +mechanisms to save and restore registers using the stack on function +entry and exit. The jump buffer argument @var{buf} holds only the +information needed to restore the stack frame, rather than the entire +set of saved register values. + +An important caveat is that GCC arranges to save and restore only +those registers known to the specific architecture variant being +compiled for. This can make @code{__builtin_setjmp} and +@code{__builtin_longjmp} more efficient than their library +counterparts in some cases, but it can also cause incorrect and +mysterious behavior when mixing with code that uses the full register +set. + +You should declare the jump buffer argument @var{buf} to the +built-in functions as: + +@smallexample +#include +intptr_t @var{buf}[5]; +@end smallexample + +@deftypefn {Built-in Function} {int} __builtin_setjmp (intptr_t *@var{buf}) +This function saves the current stack context in @var{buf}. +@code{__builtin_setjmp} returns 0 when returning directly, +and 1 when returning from @code{__builtin_longjmp} using the same +@var{buf}. +@end deftypefn + +@deftypefn {Built-in Function} {void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val}) +This function restores the stack context in @var{buf}, +saved by a previous call to @code{__builtin_setjmp}. After +@code{__builtin_longjmp} is finished, the program resumes execution as +if the matching @code{__builtin_setjmp} returns the value @var{val}, +which must be 1. + +Because @code{__builtin_longjmp} depends on the function return +mechanism to restore the stack context, it cannot be called +from the same function calling @code{__builtin_setjmp} to +initialize @var{buf}. It can only be called from a function called +(directly or indirectly) from the function calling @code{__builtin_setjmp}. +@end deftypefn + @node Constructing Calls @section Constructing Function Calls @cindex constructing calls --------------B177C450D8318405174C02BD--