Back to index

nagios-plugins  1.4.16
warn-on-use.h
Go to the documentation of this file.
00001 /* A C macro for emitting warnings if a function is used.
00002    Copyright (C) 2010 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    Lesser 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 inline 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