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