1 /* -*- buffer-read-only: t -*- vi: set ro: */ 2 /* DO NOT EDIT! GENERATED AUTOMATICALLY! */ 3 /* A C macro for emitting warnings if a function is used. 4 Copyright (C) 2010-2019 Free Software Foundation, Inc. 5 6 This program is free software: you can redistribute it and/or modify it 7 under the terms of the GNU General Public License as published 8 by the Free Software Foundation; either version 3 of the License, or 9 (at your option) any later version. 10 11 This program is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with this program. If not, see <https://www.gnu.org/licenses/>. */ 18 19 /* _GL_WARN_ON_USE (function, "literal string") issues a declaration 20 for FUNCTION which will then trigger a compiler warning containing 21 the text of "literal string" anywhere that function is called, if 22 supported by the compiler. If the compiler does not support this 23 feature, the macro expands to an unused extern declaration. 24 25 _GL_WARN_ON_USE_ATTRIBUTE ("literal string") expands to the 26 attribute used in _GL_WARN_ON_USE. If the compiler does not support 27 this feature, it expands to empty. 28 29 These macros are useful for marking a function as a potential 30 portability trap, with the intent that "literal string" include 31 instructions on the replacement function that should be used 32 instead. 33 _GL_WARN_ON_USE is for functions with 'extern' linkage. 34 _GL_WARN_ON_USE_ATTRIBUTE is for functions with 'static' or 'inline' 35 linkage. 36 37 However, one of the reasons that a function is a portability trap is 38 if it has the wrong signature. Declaring FUNCTION with a different 39 signature in C is a compilation error, so this macro must use the 40 same type as any existing declaration so that programs that avoid 41 the problematic FUNCTION do not fail to compile merely because they 42 included a header that poisoned the function. But this implies that 43 _GL_WARN_ON_USE is only safe to use if FUNCTION is known to already 44 have a declaration. Use of this macro implies that there must not 45 be any other macro hiding the declaration of FUNCTION; but 46 undefining FUNCTION first is part of the poisoning process anyway 47 (although for symbols that are provided only via a macro, the result 48 is a compilation error rather than a warning containing 49 "literal string"). Also note that in C++, it is only safe to use if 50 FUNCTION has no overloads. 51 52 For an example, it is possible to poison 'getline' by: 53 - adding a call to gl_WARN_ON_USE_PREPARE([[#include <stdio.h>]], 54 [getline]) in configure.ac, which potentially defines 55 HAVE_RAW_DECL_GETLINE 56 - adding this code to a header that wraps the system <stdio.h>: 57 #undef getline 58 #if HAVE_RAW_DECL_GETLINE 59 _GL_WARN_ON_USE (getline, "getline is required by POSIX 2008, but" 60 "not universally present; use the gnulib module getline"); 61 #endif 62 63 It is not possible to directly poison global variables. But it is 64 possible to write a wrapper accessor function, and poison that 65 (less common usage, like &environ, will cause a compilation error 66 rather than issue the nice warning, but the end result of informing 67 the developer about their portability problem is still achieved): 68 #if HAVE_RAW_DECL_ENVIRON 69 static char *** 70 rpl_environ (void) { return &environ; } 71 _GL_WARN_ON_USE (rpl_environ, "environ is not always properly declared"); 72 # undef environ 73 # define environ (*rpl_environ ()) 74 #endif 75 or better (avoiding contradictory use of 'static' and 'extern'): 76 #if HAVE_RAW_DECL_ENVIRON 77 static char *** 78 _GL_WARN_ON_USE_ATTRIBUTE ("environ is not always properly declared") 79 rpl_environ (void) { return &environ; } 80 # undef environ 81 # define environ (*rpl_environ ()) 82 #endif 83 */ 84 #ifndef _GL_WARN_ON_USE 85 86 # if 4 < __GNUC__ || (__GNUC__ == 4 && 3 <= __GNUC_MINOR__) 87 /* A compiler attribute is available in gcc versions 4.3.0 and later. */ 88 # define _GL_WARN_ON_USE(function, message) \ 89 extern __typeof__ (function) function __attribute__ ((__warning__ (message))) 90 # define _GL_WARN_ON_USE_ATTRIBUTE(message) \ 91 __attribute__ ((__warning__ (message))) 92 # elif __GNUC__ >= 3 && GNULIB_STRICT_CHECKING 93 /* Verify the existence of the function. */ 94 # define _GL_WARN_ON_USE(function, message) \ 95 extern __typeof__ (function) function 96 # define _GL_WARN_ON_USE_ATTRIBUTE(message) 97 # else /* Unsupported. */ 98 # define _GL_WARN_ON_USE(function, message) \ 99 _GL_WARN_EXTERN_C int _gl_warn_on_use 100 # define _GL_WARN_ON_USE_ATTRIBUTE(message) 101 # endif 102 #endif 103 104 /* _GL_WARN_ON_USE_CXX (function, rettype, parameters_and_attributes, "string") 105 is like _GL_WARN_ON_USE (function, "string"), except that the function is 106 declared with the given prototype, consisting of return type, parameters, 107 and attributes. 108 This variant is useful for overloaded functions in C++. _GL_WARN_ON_USE does 109 not work in this case. */ 110 #ifndef _GL_WARN_ON_USE_CXX 111 # if 4 < __GNUC__ || (__GNUC__ == 4 && 3 <= __GNUC_MINOR__) 112 # define _GL_WARN_ON_USE_CXX(function,rettype,parameters_and_attributes,msg) \ 113 extern rettype function parameters_and_attributes \ 114 __attribute__ ((__warning__ (msg))) 115 # elif __GNUC__ >= 3 && GNULIB_STRICT_CHECKING 116 /* Verify the existence of the function. */ 117 # define _GL_WARN_ON_USE_CXX(function,rettype,parameters_and_attributes,msg) \ 118 extern rettype function parameters_and_attributes 119 # else /* Unsupported. */ 120 # define _GL_WARN_ON_USE_CXX(function,rettype,parameters_and_attributes,msg) \ 121 _GL_WARN_EXTERN_C int _gl_warn_on_use 122 # endif 123 #endif 124 125 /* _GL_WARN_EXTERN_C declaration; 126 performs the declaration with C linkage. */ 127 #ifndef _GL_WARN_EXTERN_C 128 # if defined __cplusplus 129 # define _GL_WARN_EXTERN_C extern "C" 130 # else 131 # define _GL_WARN_EXTERN_C extern 132 # endif 133 #endif 134