From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS22989 209.51.188.0/24 X-Spam-Status: No, score=-3.7 required=3.0 tests=AWL,BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id 266441F8C6 for ; Sun, 22 Aug 2021 20:03:03 +0000 (UTC) Received: from localhost ([::1]:47088 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mHtgL-0005Ad-Vf for normalperson@yhbt.net; Sun, 22 Aug 2021 16:03:01 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:42062) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mHtgH-0005AQ-Tv for bug-gnulib@gnu.org; Sun, 22 Aug 2021 16:02:58 -0400 Received: from mo4-p00-ob.smtp.rzone.de ([85.215.255.20]:14276) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mHtgD-0005aC-9i for bug-gnulib@gnu.org; Sun, 22 Aug 2021 16:02:57 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; t=1629662569; s=strato-dkim-0002; d=clisp.org; h=Message-ID:Date:Subject:To:From:Cc:Date:From:Subject:Sender; bh=6VefAK7cTlsMdUdkjUUrxU/bgcVUJCF2YttxC3/qnwo=; b=ISMcHuFLit2ERKGbrMUSkb2ZKe7yXVuW49rE7MtHG9dXSceS4T2OsRVmke7ogfJceH yGahM88992vBT/yemP/s8mJrPwzxVvu+oMGwCo22eXY7yzIVJAy1jQz/gWNuVgPOkKLS 12CtGP0F2tGm5VlsZN9HKmDulr5r8nLtnuDcsIDhgtwQXB9wQT245Sj/pkd6GV+GCW+X NRgvbVbz3TgkM/JEqTsyoZM9IzpKX8Glnce5v8gbFJBFhNJqltGna9RcamRkpI0mMoF4 rEVVSQ8O+SsDTotaPaSD0yeJ1NvvspXq4vpRORn/hDvbk+3MKK0EiGgPUqnMqgHvV6t+ Zonw== Authentication-Results: strato.com; dkim=none X-RZG-AUTH: ":Ln4Re0+Ic/6oZXR1YgKryK8brlshOcZlIWs+iCP5vnk6shH0WWb0LN8XZoH94z26ll5ip69ukEWxMMoz6TatjeiwMVn8eJlEag==" X-RZG-CLASS-ID: mo00 Received: from omega.localnet by smtp.strato.de (RZmta 47.31.0 AUTH) with ESMTPSA id I0a189x7MK2ncUg (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits)) (Client did not present a certificate); Sun, 22 Aug 2021 22:02:49 +0200 (CEST) From: Bruno Haible To: bug-gnulib@gnu.org Subject: gnulib-common.m4: Document the gnulib-internal _GL_ATTRIBUTE_* macros Date: Sun, 22 Aug 2021 22:02:49 +0200 Message-ID: <2999685.yKVeVyVuyW@omega> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Received-SPF: none client-ip=85.215.255.20; envelope-from=bruno@clisp.org; helo=mo4-p00-ob.smtp.rzone.de X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_PASS=-0.001, SPF_NONE=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: bug-gnulib@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Gnulib discussion list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnulib-bounces+normalperson=yhbt.net@gnu.org Sender: "bug-gnulib" When we use the _GL_ATTRIBUTE_* macros, neither the GCC documentation nor the attribute.h comments directly apply, because of different syntax. Therefore, this patch adds documentation to these macros. 2021-08-22 Bruno Haible gnulib-common.m4: Document the gnulib-internal _GL_ATTRIBUTE_* macros. * m4/gnulib-common.m4 (gl_COMMON_BODY): Add comments to the _GL_ATTRIBUTE_* macros, based on lib/attribute.h. diff --git a/m4/gnulib-common.m4 b/m4/gnulib-common.m4 index c801b3de9..174113b28 100644 --- a/m4/gnulib-common.m4 +++ b/m4/gnulib-common.m4 @@ -111,24 +111,39 @@ AC_DEFUN([gl_COMMON_BODY], [ ]dnl There is no _GL_ATTRIBUTE_ALIGNED; use stdalign's _Alignas instead. [ +/* _GL_ATTRIBUTE_ALLOC_SIZE ((N)) declares that the Nth argument of the function + is the size of the returned memory block. + _GL_ATTRIBUTE_ALLOC_SIZE ((M, N)) declares that the Mth argument multiplied + by the Nth argument of the function is the size of the returned memory block. + */ +/* Applies to: function, pointer to function, function types. */ #if _GL_HAS_ATTRIBUTE (alloc_size) # define _GL_ATTRIBUTE_ALLOC_SIZE(args) __attribute__ ((__alloc_size__ args)) #else # define _GL_ATTRIBUTE_ALLOC_SIZE(args) #endif +/* _GL_ATTRIBUTE_ALWAYS_INLINE tells that the compiler should always inline the + function and report an error if it cannot do so. */ +/* Applies to: function. */ #if _GL_HAS_ATTRIBUTE (always_inline) # define _GL_ATTRIBUTE_ALWAYS_INLINE __attribute__ ((__always_inline__)) #else # define _GL_ATTRIBUTE_ALWAYS_INLINE #endif +/* _GL_ATTRIBUTE_ARTIFICIAL declares that the function is not important to show + in stack traces when debugging. The compiler should omit the function from + stack traces. */ +/* Applies to: function. */ #if _GL_HAS_ATTRIBUTE (artificial) # define _GL_ATTRIBUTE_ARTIFICIAL __attribute__ ((__artificial__)) #else # define _GL_ATTRIBUTE_ARTIFICIAL #endif +/* _GL_ATTRIBUTE_COLD declares that the function is rarely executed. */ +/* Applies to: functions. */ /* Avoid __attribute__ ((cold)) on MinGW; see thread starting at . Also, Oracle Studio 12.6 requires 'cold' not '__cold__'. */ @@ -142,18 +157,25 @@ AC_DEFUN([gl_COMMON_BODY], [ # define _GL_ATTRIBUTE_COLD #endif +/* _GL_ATTRIBUTE_CONST declares that it is OK for a compiler to omit duplicate + calls to the function with the same arguments. + This attribute is safe for a function that neither depends on nor affects + observable state, and always returns exactly once - e.g., does not loop + forever, and does not call longjmp. + (This attribute is stricter than _GL_ATTRIBUTE_PURE.) */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (const) # define _GL_ATTRIBUTE_CONST __attribute__ ((__const__)) #else # define _GL_ATTRIBUTE_CONST #endif -/* _GL_ATTRIBUTE_DEALLOC (F, I) is for functions returning pointers +/* _GL_ATTRIBUTE_DEALLOC (F, I) declares that the function returns pointers that can be freed by passing them as the Ith argument to the - function F. _GL_ATTRIBUTE_DEALLOC_FREE is for functions that - return pointers that can be freed via 'free'; it can be used - only after including stdlib.h. These macros cannot be used on - inline functions. */ + function F. + _GL_ATTRIBUTE_DEALLOC_FREE declares that the function returns pointers that + can be freed via 'free'; it can be used only after including . */ +/* Applies to: functions. Cannot be used on inline functions. */ #if _GL_GNUC_PREREQ (11, 0) # define _GL_ATTRIBUTE_DEALLOC(f, i) __attribute__ ((__malloc__ (f, i))) #else @@ -161,6 +183,14 @@ AC_DEFUN([gl_COMMON_BODY], [ #endif #define _GL_ATTRIBUTE_DEALLOC_FREE _GL_ATTRIBUTE_DEALLOC (free, 1) +/* _GL_ATTRIBUTE_DEPRECATED: Declares that an entity is deprecated. + The compiler may warn if the entity is used. */ +/* Applies to: + - function, variable, + - struct, union, struct/union member, + - enumeration, enumeration item, + - typedef, + in C++ also: namespace, class, template specialization. */ #if _GL_HAS_C_ATTRIBUTE (deprecated) # define _GL_ATTRIBUTE_DEPRECATED [[__deprecated__]] #elif _GL_HAS_ATTRIBUTE (deprecated) @@ -169,6 +199,11 @@ AC_DEFUN([gl_COMMON_BODY], [ # define _GL_ATTRIBUTE_DEPRECATED #endif +/* _GL_ATTRIBUTE_ERROR(msg) requests an error if a function is called and + the function call is not optimized away. + _GL_ATTRIBUTE_WARNING(msg) requests a warning if a function is called and + the function call is not optimized away. */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (error) # define _GL_ATTRIBUTE_ERROR(msg) __attribute__ ((__error__ (msg))) # define _GL_ATTRIBUTE_WARNING(msg) __attribute__ ((__warning__ (msg))) @@ -180,13 +215,20 @@ AC_DEFUN([gl_COMMON_BODY], [ # define _GL_ATTRIBUTE_WARNING(msg) #endif +/* _GL_ATTRIBUTE_EXTERNALLY_VISIBLE declares that the entity should remain + visible to debuggers etc., even with '-fwhole-program'. */ +/* Applies to: functions, variables. */ #if _GL_HAS_ATTRIBUTE (externally_visible) # define _GL_ATTRIBUTE_EXTERNALLY_VISIBLE __attribute__ ((externally_visible)) #else # define _GL_ATTRIBUTE_EXTERNALLY_VISIBLE #endif -/* FALLTHROUGH is special, because it always expands to something. */ +/* _GL_ATTRIBUTE_FALLTHROUGH declares that it is not a programming mistake if + the control flow falls through to the immediately following 'case' or + 'default' label. The compiler should not warn in this case. */ +/* Applies to: Empty statement (;), inside a 'switch' statement. */ +/* Always expands to something. */ #if _GL_HAS_C_ATTRIBUTE (fallthrough) # define _GL_ATTRIBUTE_FALLTHROUGH [[__fallthrough__]] #elif _GL_HAS_ATTRIBUTE (fallthrough) @@ -195,24 +237,47 @@ AC_DEFUN([gl_COMMON_BODY], [ # define _GL_ATTRIBUTE_FALLTHROUGH ((void) 0) #endif +/* _GL_ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) + declares that the STRING-INDEXth function argument is a format string of + style ARCHETYPE, which is one of: + printf, gnu_printf + scanf, gnu_scanf, + strftime, gnu_strftime, + strfmon, + or the same thing prefixed and suffixed with '__'. + If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK + are suitable for the format string. */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (format) # define _GL_ATTRIBUTE_FORMAT(spec) __attribute__ ((__format__ spec)) #else # define _GL_ATTRIBUTE_FORMAT(spec) #endif +/* _GL_ATTRIBUTE_LEAF declares that if the function is called from some other + compilation unit, it executes code from that unit only by return or by + exception handling. This declaration lets the compiler optimize that unit + more aggressively. */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (leaf) # define _GL_ATTRIBUTE_LEAF __attribute__ ((__leaf__)) #else # define _GL_ATTRIBUTE_LEAF #endif +/* _GL_ATTRIBUTE_MALLOC declares that the function returns a pointer to freshly + allocated memory. */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (malloc) # define _GL_ATTRIBUTE_MALLOC __attribute__ ((__malloc__)) #else # define _GL_ATTRIBUTE_MALLOC #endif +/* _GL_ATTRIBUTE_MAY_ALIAS declares that pointers to the type may point to the + same storage as pointers to other types. Thus this declaration disables + strict aliasing optimization. */ +/* Applies to: types. */ /* Oracle Studio 12.6 mishandles may_alias despite __has_attribute OK. */ #if _GL_HAS_ATTRIBUTE (may_alias) && !defined __SUNPRO_C # define _GL_ATTRIBUTE_MAY_ALIAS __attribute__ ((__may_alias__)) @@ -220,6 +285,18 @@ AC_DEFUN([gl_COMMON_BODY], [ # define _GL_ATTRIBUTE_MAY_ALIAS #endif +/* _GL_ATTRIBUTE_MAYBE_UNUSED declares that it is not a programming mistake if + the entity is not used. The compiler should not warn if the entity is not + used. */ +/* Applies to: + - function, variable, + - struct, union, struct/union member, + - enumeration, enumeration item, + - typedef, + in C++ also: class. */ +/* In C++ and C2x, this is spelled [[__maybe_unused__]]. + GCC's syntax is __attribute__ ((__unused__)). + clang supports both syntaxes. */ #if _GL_HAS_C_ATTRIBUTE (maybe_unused) # define _GL_ATTRIBUTE_MAYBE_UNUSED [[__maybe_unused__]] #else @@ -228,6 +305,10 @@ AC_DEFUN([gl_COMMON_BODY], [ /* Earlier spellings of this macro. */ #define _UNUSED_PARAMETER_ _GL_ATTRIBUTE_MAYBE_UNUSED +/* _GL_ATTRIBUTE_NODISCARD declares that the caller of the function should not + discard the return value. The compiler may warn if the caller does not use + the return value, unless the caller uses something like ignore_value. */ +/* Applies to: function, enumeration, class. */ #if _GL_HAS_C_ATTRIBUTE (nodiscard) # define _GL_ATTRIBUTE_NODISCARD [[__nodiscard__]] #elif _GL_HAS_ATTRIBUTE (warn_unused_result) @@ -236,18 +317,30 @@ AC_DEFUN([gl_COMMON_BODY], [ # define _GL_ATTRIBUTE_NODISCARD #endif +/* _GL_ATTRIBUTE_NOINLINE tells that the compiler should not inline the + function. */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (noinline) # define _GL_ATTRIBUTE_NOINLINE __attribute__ ((__noinline__)) #else # define _GL_ATTRIBUTE_NOINLINE #endif +/* _GL_ATTRIBUTE_NONNULL ((N1, N2,...)) declares that the arguments N1, N2,... + must not be NULL. + _GL_ATTRIBUTE_NONNULL () declares that all pointer arguments must not be + null. */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (nonnull) # define _GL_ATTRIBUTE_NONNULL(args) __attribute__ ((__nonnull__ args)) #else # define _GL_ATTRIBUTE_NONNULL(args) #endif +/* _GL_ATTRIBUTE_NONSTRING declares that the contents of a character array is + not meant to be NUL-terminated. */ +/* Applies to: struct/union members and variables that are arrays of element + type '[[un]signed] char'. */ #if _GL_HAS_ATTRIBUTE (nonstring) # define _GL_ATTRIBUTE_NONSTRING __attribute__ ((__nonstring__)) #else @@ -256,47 +349,75 @@ AC_DEFUN([gl_COMMON_BODY], [ /* There is no _GL_ATTRIBUTE_NORETURN; use _Noreturn instead. */ +/* _GL_ATTRIBUTE_NOTHROW declares that the function does not throw exceptions. + */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (nothrow) && !defined __cplusplus # define _GL_ATTRIBUTE_NOTHROW __attribute__ ((__nothrow__)) #else # define _GL_ATTRIBUTE_NOTHROW #endif +/* _GL_ATTRIBUTE_PACKED declares: + For struct members: The member has the smallest possible alignment. + For struct, union, class: All members have the smallest possible alignment, + minimizing the memory required. */ +/* Applies to: struct members, struct, union, + in C++ also: class. */ #if _GL_HAS_ATTRIBUTE (packed) # define _GL_ATTRIBUTE_PACKED __attribute__ ((__packed__)) #else # define _GL_ATTRIBUTE_PACKED #endif +/* _GL_ATTRIBUTE_PURE declares that It is OK for a compiler to omit duplicate + calls to the function with the same arguments if observable state is not + changed between calls. + This attribute is safe for a function that does not affect + observable state, and always returns exactly once. + (This attribute is looser than _GL_ATTRIBUTE_CONST.) */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (pure) # define _GL_ATTRIBUTE_PURE __attribute__ ((__pure__)) #else # define _GL_ATTRIBUTE_PURE #endif +/* _GL_ATTRIBUTE_RETURNS_NONNULL declares that the function's return value is + a non-NULL pointer. */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (returns_nonnull) # define _GL_ATTRIBUTE_RETURNS_NONNULL __attribute__ ((__returns_nonnull__)) #else # define _GL_ATTRIBUTE_RETURNS_NONNULL #endif +/* _GL_ATTRIBUTE_SENTINEL(pos) declares that the variadic function expects a + trailing NULL argument. + _GL_ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99). + _GL_ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */ +/* Applies to: functions. */ #if _GL_HAS_ATTRIBUTE (sentinel) # define _GL_ATTRIBUTE_SENTINEL(pos) __attribute__ ((__sentinel__ pos)) #else # define _GL_ATTRIBUTE_SENTINEL(pos) #endif +/* A helper macro. Don't use it directly. */ #if _GL_HAS_ATTRIBUTE (unused) # define _GL_ATTRIBUTE_UNUSED __attribute__ ((__unused__)) #else # define _GL_ATTRIBUTE_UNUSED #endif -/* Earlier spellings of this macro. */ +/* Alternative spelling of this macro, for convenience. */ #define _GL_UNUSED _GL_ATTRIBUTE_UNUSED ]dnl There is no _GL_ATTRIBUTE_VISIBILITY; see m4/visibility.m4 instead. [ -/* To support C++ as well as C, use _GL_UNUSED_LABEL with trailing ';'. */ +/* _GL_UNUSED_LABEL; declares that it is not a programming mistake if the + immediately preceding label is not used. The compiler should not warn + if the label is not used. */ +/* Applies to: label (both in C and C++). */ #if !defined __cplusplus || _GL_GNUC_PREREQ (4, 5) # define _GL_UNUSED_LABEL _GL_ATTRIBUTE_UNUSED #else