From patchwork Thu Jan 18 18:42:32 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 84362 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id E92E43858D1E for ; Thu, 18 Jan 2024 18:43:22 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa2.mentor.iphmx.com (esa2.mentor.iphmx.com [68.232.141.98]) by sourceware.org (Postfix) with ESMTPS id 38F053858D1E for ; Thu, 18 Jan 2024 18:42:52 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 38F053858D1E Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 38F053858D1E Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=68.232.141.98 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705603374; cv=none; b=owlvQdZJIe+L4AeiyfdF2PrbZVjaRa/+dTxVBWbTJKufban+AYAlBjgvvoK7ksNUJkdrbNs/cnpkI5D5nGS3zjFSA3rF/MNIycC5I1aIiNZpgPm0wB+5T5UfqmM3oziDPu/OjbOCa1bXAWZCCI0Y7JFayUZSaULhO0GqTMsdrA4= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705603374; c=relaxed/simple; bh=eS7EXgVcCKYPbS+uwuZKu7rRB0QUX1l4KGjp9K1oas8=; h=From:To:Subject:Date:Message-ID:MIME-Version; b=v951n4Xs52BsRPuhyayTXrk79X+LVzOj7uAdVydJEiFSJ0bzrCtCTDIDOfZZbuiM3nu8Ud3KMzZzlgiQX4CNTs6ZTFxVs03WYZMVk4tnvG7llufwFKPrvEpIgakfA0DnfLcYSWID1bOzewhQ/UBaQGjtHprxRFNF1Q4omQhdLzc= ARC-Authentication-Results: i=1; server2.sourceware.org X-CSE-ConnectionGUID: dutuqPh7R0qmZLxmW4d5cw== X-CSE-MsgGUID: AC76NzB3TA2bH4tlMdeQ/g== X-IronPort-AV: E=Sophos;i="6.05,203,1701158400"; d="scan'208";a="31617970" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa2.mentor.iphmx.com with ESMTP; 18 Jan 2024 10:42:51 -0800 IronPort-SDR: +tvTFA/lDnRCTxW1w6LK2EsBqCFMoNwqHaSgTXXLUjAx9t2Xi7TxThp+TQaxVvXjPgLjNxlc0f S5TXTx8h8riN31dMWkRLvUbxm7QxC+S9ydPfTQUSlse6Swi7l0432xPUJ7gxEXZK5Pa6WQTw0+ 8PjklnArd6aWR0F8+rAxugyZOKl+o/pwEocEpHpkIEWhCXj5Wo8lj2W0wFAL1n42784ECTwOU9 DbLdpECz/i3U52o1f15U+4/rhVsOVe5OWKXbUB5UhmpdleN04czDB/XddOZCgfQVX3dHEjf6fr Yt8= From: Sandra Loosemore To: Subject: [COMMITTED] Restore documentation for const/volatile functions [PR107942] Date: Thu, 18 Jan 2024 11:42:32 -0700 Message-ID: <20240118184233.2418060-1-sandra@codesourcery.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 X-ClientProxiedBy: svr-orw-mbx-15.mgc.mentorg.com (147.34.90.215) To svr-orw-mbx-13.mgc.mentorg.com (147.34.90.213) X-Spam-Status: No, score=-10.1 required=5.0 tests=BAYES_00, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, SPF_HELO_PASS, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org In r5-7698-g8648c55f3b703a I accidentally removed the documentation of GCC's special interpretation of const/volatile qualifiers on functions from the function attributes section, thinking this was just a bit-rotten leftover from old versions of GCC. PR107942 points out that this functionality is still present even though the docs are now gone. I decided this material didn't really belong in the function attributes discussion, but a new subsection in the general list of GCC extensions to the C language. And I agree with the comment in the issue that we shouldn't really recommend this usage any more. gcc/ChangeLog PR c/107942 * doc/extend.texi (C Extensions): Add new section to menu. (Function Attributes): Move dangling index entries to.... (Const and Volatile Functions): New section. --- gcc/doc/extend.texi | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index d1893ad860c..d879ad544b5 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -70,6 +70,7 @@ extensions, accepted by GCC in C90 mode and in C++. * Character Escapes:: @samp{\e} stands for the character @key{ESC}. * Alignment:: Determining the alignment of a function, type or variable. * Inline:: Defining inline functions (as fast as macros). +* Const and Volatile Functions :: GCC interprets these specially in C. * Volatiles:: What constitutes an access to a volatile object. * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. @@ -2522,8 +2523,6 @@ the enclosing block. @section Declaring Attributes of Functions @cindex function attributes @cindex declaring attributes of functions -@cindex @code{volatile} applied to function -@cindex @code{const} applied to function In GNU C and C++, you can use function attributes to specify certain function properties that may help the compiler optimize calls or @@ -10397,6 +10396,40 @@ The definition in the header file causes most calls to the function to be inlined. If any uses of the function remain, they refer to the single copy in the library. +@node Const and Volatile Functions +@section Const and Volatile Functions +@cindex @code{const} applied to function +@cindex @code{volatile} applied to function + +The C standard explicitly leaves the behavior of the @code{const} and +@code{volatile} type qualifiers applied to functions undefined; these +constructs can only arise through the use of @code{typedef}. As an extension, +GCC defines this use of the @code{const} qualifier to have the same meaning +as the GCC @code{const} function attribute, and the @code{volatile} qualifier +to be equivalent to the @code{noreturn} attribute. +@xref{Common Function Attributes}, for more information. + +As examples of this usage, + +@smallexample + +/* @r{Equivalent to:} + void fatal () __attribute__ ((noreturn)); */ +typedef void voidfn (); +volatile voidfn fatal; + +/* @r{Equivalent to:} + extern int square (int) __attribute__ ((const)); */ +typedef int intfn (int); +extern const intfn square; +@end smallexample + +In general, using function attributes instead is preferred, since the +attributes make both the intent of the code and its reliance on a GNU +extension explicit. Additionally, using @code{const} and +@code{volatile} in this way is specific to GNU C and does not work in +GNU C++. + @node Volatiles @section When is a Volatile Object Accessed? @cindex accessing volatiles