libdap
Updated for version 3.17.0
|
00001 /* A C macro for emitting warnings if a function is used. 00002 Copyright (C) 2010-2015 Free Software Foundation, Inc. 00003 00004 This program is free software: you can redistribute it and/or modify it 00005 under the terms of the GNU General Public License as published 00006 by the Free Software Foundation; either version 3 of the License, or 00007 (at your option) any later version. 00008 00009 This program is distributed in the hope that it will be useful, 00010 but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00012 General Public License for more details. 00013 00014 You should have received a copy of the GNU General Public License 00015 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 00016 00017 /* _GL_WARN_ON_USE (function, "literal string") issues a declaration 00018 for FUNCTION which will then trigger a compiler warning containing 00019 the text of "literal string" anywhere that function is called, if 00020 supported by the compiler. If the compiler does not support this 00021 feature, the macro expands to an unused extern declaration. 00022 00023 This macro is useful for marking a function as a potential 00024 portability trap, with the intent that "literal string" include 00025 instructions on the replacement function that should be used 00026 instead. However, one of the reasons that a function is a 00027 portability trap is if it has the wrong signature. Declaring 00028 FUNCTION with a different signature in C is a compilation error, so 00029 this macro must use the same type as any existing declaration so 00030 that programs that avoid the problematic FUNCTION do not fail to 00031 compile merely because they included a header that poisoned the 00032 function. But this implies that _GL_WARN_ON_USE is only safe to 00033 use if FUNCTION is known to already have a declaration. Use of 00034 this macro implies that there must not be any other macro hiding 00035 the declaration of FUNCTION; but undefining FUNCTION first is part 00036 of the poisoning process anyway (although for symbols that are 00037 provided only via a macro, the result is a compilation error rather 00038 than a warning containing "literal string"). Also note that in 00039 C++, it is only safe to use if FUNCTION has no overloads. 00040 00041 For an example, it is possible to poison 'getline' by: 00042 - adding a call to gl_WARN_ON_USE_PREPARE([[#include <stdio.h>]], 00043 [getline]) in configure.ac, which potentially defines 00044 HAVE_RAW_DECL_GETLINE 00045 - adding this code to a header that wraps the system <stdio.h>: 00046 #undef getline 00047 #if HAVE_RAW_DECL_GETLINE 00048 _GL_WARN_ON_USE (getline, "getline is required by POSIX 2008, but" 00049 "not universally present; use the gnulib module getline"); 00050 #endif 00051 00052 It is not possible to directly poison global variables. But it is 00053 possible to write a wrapper accessor function, and poison that 00054 (less common usage, like &environ, will cause a compilation error 00055 rather than issue the nice warning, but the end result of informing 00056 the developer about their portability problem is still achieved): 00057 #if HAVE_RAW_DECL_ENVIRON 00058 static char ***rpl_environ (void) { return &environ; } 00059 _GL_WARN_ON_USE (rpl_environ, "environ is not always properly declared"); 00060 # undef environ 00061 # define environ (*rpl_environ ()) 00062 #endif 00063 */ 00064 #ifndef _GL_WARN_ON_USE 00065 00066 # if 4 < __GNUC__ || (__GNUC__ == 4 && 3 <= __GNUC_MINOR__) 00067 /* A compiler attribute is available in gcc versions 4.3.0 and later. */ 00068 # define _GL_WARN_ON_USE(function, message) \ 00069 extern __typeof__ (function) function __attribute__ ((__warning__ (message))) 00070 # elif __GNUC__ >= 3 && GNULIB_STRICT_CHECKING 00071 /* Verify the existence of the function. */ 00072 # define _GL_WARN_ON_USE(function, message) \ 00073 extern __typeof__ (function) function 00074 # else /* Unsupported. */ 00075 # define _GL_WARN_ON_USE(function, message) \ 00076 _GL_WARN_EXTERN_C int _gl_warn_on_use 00077 # endif 00078 #endif 00079 00080 /* _GL_WARN_ON_USE_CXX (function, rettype, parameters_and_attributes, "string") 00081 is like _GL_WARN_ON_USE (function, "string"), except that the function is 00082 declared with the given prototype, consisting of return type, parameters, 00083 and attributes. 00084 This variant is useful for overloaded functions in C++. _GL_WARN_ON_USE does 00085 not work in this case. */ 00086 #ifndef _GL_WARN_ON_USE_CXX 00087 # if 4 < __GNUC__ || (__GNUC__ == 4 && 3 <= __GNUC_MINOR__) 00088 # define _GL_WARN_ON_USE_CXX(function,rettype,parameters_and_attributes,msg) \ 00089 extern rettype function parameters_and_attributes \ 00090 __attribute__ ((__warning__ (msg))) 00091 # elif __GNUC__ >= 3 && GNULIB_STRICT_CHECKING 00092 /* Verify the existence of the function. */ 00093 # define _GL_WARN_ON_USE_CXX(function,rettype,parameters_and_attributes,msg) \ 00094 extern rettype function parameters_and_attributes 00095 # else /* Unsupported. */ 00096 # define _GL_WARN_ON_USE_CXX(function,rettype,parameters_and_attributes,msg) \ 00097 _GL_WARN_EXTERN_C int _gl_warn_on_use 00098 # endif 00099 #endif 00100 00101 /* _GL_WARN_EXTERN_C declaration; 00102 performs the declaration with C linkage. */ 00103 #ifndef _GL_WARN_EXTERN_C 00104 # if defined __cplusplus 00105 # define _GL_WARN_EXTERN_C extern "C" 00106 # else 00107 # define _GL_WARN_EXTERN_C extern 00108 # endif 00109 #endif