From 039dc49e7e584131dc304bfb99b6e52812092827 Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Wed, 16 Dec 2009 14:53:06 -0700 Subject: [PATCH] warn-on-use: new module The goal of GNULIB_POSIXCHECK is to allow a developer on a reasonably portable system to detect instances where they may have succeeded because their system is up-to-date, but where compilation would fail or create a misbehaving application on some other system due to some portability problem, all without requiring that the developer have access to other machines. In other words, we want to poison all interfaces that have a gnulib replacement if the corresponding gnulib module is not in use. For macros, the solution is undefining the macro; unfortunately this causes compilation error without many details as to why, but it is better than nothing. For functions, the solution is to cause a warning if the function is used. Previously, the link-warning could poison functions, but only on glibc systems and with gcc. This module introduces _GL_WARN_ON_USE as a way of poisoning functions for a few more systems. Using the gcc __warning__ attribute (added in 4.3.0, early 2008) rather than using link-warning.h is favorable because: 1) Provides a warning immediately at compile-time. The user does not have to wait until he links a program. 2) Less use of C macros. Less risk of collision. 3) It's available on more platforms. Depends only on GCC. 4) The formatting of the message is nicer. There is a minor regression: the gcc attribute is currently not as powerful as a link warning at detecting uses via function pointers: http://gcc.gnu.org/bugzilla/show_bug.cgi?id=42384 However, that style of coding is less frequent. * modules/warn-on-use: New file. * build-aux/warn-on-use.h: Likewise. * m4/warn-on-use.m4: Likewise. * MODULES.html.sh (Support for building): Mention it. Signed-off-by: Eric Blake --- ChangeLog | 8 ++++++ MODULES.html.sh | 4 ++- build-aux/warn-on-use.h | 75 +++++++++++++++++++++++++++++++++++++++++++++++++ m4/warn-on-use.m4 | 45 +++++++++++++++++++++++++++++ modules/warn-on-use | 35 +++++++++++++++++++++++ 5 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 build-aux/warn-on-use.h create mode 100644 m4/warn-on-use.m4 create mode 100644 modules/warn-on-use diff --git a/ChangeLog b/ChangeLog index e722b4dab..08a43904c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2010-01-11 Eric Blake + + warn-on-use: new module + * modules/warn-on-use: New file. + * build-aux/warn-on-use.h: Likewise. + * m4/warn-on-use.m4: Likewise. + * MODULES.html.sh (Support for building): Mention it. + 2010-01-10 Bruno Haible Tests for module 'unistr/u32-strdup'. diff --git a/MODULES.html.sh b/MODULES.html.sh index 5bbb18c26..e3602efd6 100755 --- a/MODULES.html.sh +++ b/MODULES.html.sh @@ -3172,6 +3172,7 @@ func_all_modules () func_begin_table func_module absolute-header + func_module arg-nonnull func_module config-h func_module configmake func_module dummy @@ -3184,14 +3185,15 @@ func_all_modules () func_module lib-msvc-compat func_module lib-symbol-versions func_module link-warning + func_module manywarnings func_module no-c++ func_module relocatable-lib func_module relocatable-lib-lgpl func_module relocatable-prog func_module relocatable-prog-wrapper func_module relocatable-script + func_module warn-on-use func_module warnings - func_module manywarnings func_end_table element="Support for building documentation" diff --git a/build-aux/warn-on-use.h b/build-aux/warn-on-use.h new file mode 100644 index 000000000..3d93a9e97 --- /dev/null +++ b/build-aux/warn-on-use.h @@ -0,0 +1,75 @@ +/* A C macro for emitting warnings if a function is used. + Copyright (C) 2010 Free Software Foundation, Inc. + + This program is free software: you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published + by the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with this program. If not, see . */ + +/* _GL_WARN_ON_USE(function, "literal string") issues a declaration + for FUNCTION which will then trigger a compiler warning containing + the text of "literal string" anywhere that function is called, if + supported by the compiler. If the compiler does not support this + feature, the macro expands to an unused extern declaration. + + This macro is useful for marking a function as a potential + portability trap, with the intent that "literal string" include + instructions on the replacement function that should be used + instead. However, one of the reasons that a function is a + portability trap is if it has the wrong signature. Declaring + FUNCTION with a different signature in C is a compilation error, so + this macro must use the same type as any existing declaration so + that programs that avoid the problematic FUNCTION do not fail to + compile merely because they included a header that poisoned the + function. But this implies that _GL_WARN_ON_USE is only safe to + use if FUNCTION is known to already have a declaration. Use of + this macro implies that there must not be any other macro hiding + the declaration of FUNCTION; but undefining FUNCTION first is part + of the poisoning process anyway (although for symbols that are + provided only via a macro, the result is a compilation error rather + than a warning containing "literal string"). Also note that in + C++, it is only safe to use if FUNCTION has no overloads. + + For an example, it is possible to poison 'getline' by: + - adding a call to gl_WARN_ON_USE_PREPARE([[#include ]], + [getline]) in configure.ac, which potentially defines + HAVE_RAW_DECL_GETLINE + - adding this code to a header that wraps the system : + #undef getline + #if HAVE_RAW_DECL_GETLINE + _GL_WARN_ON_USE (getline, "getline is required by POSIX 2008, but" + "not universally present; use the gnulib module getline"); + #endif + + It is not possible to directly poison global variables. But it is + possible to write a wrapper accessor function, and poison that + (less common usage, like &environ, will cause a compilation error + rather than issue the nice warning, but the end result of informing + the developer about their portability problem is still achieved): + #if HAVE_RAW_DECL_ENVIRON + static inline char ***rpl_environ (void) { return &environ; } + _GL_WARN_ON_USE (rpl_environ, "environ is not always properly declared"); + # undef environ + # define environ (*rpl_environ ()) + #endif + */ +#ifndef _GL_WARN_ON_USE + +# if 4 < __GNUC__ || (__GNUC__ == 4 && 3 <= __GNUC_MINOR__) +/* A compiler attribute is available in gcc versions 4.3.0 and later. */ +# define _GL_WARN_ON_USE(function, message) \ +extern __typeof__ (function) function __attribute__ ((__warning__ (message))) + +# else /* Unsupported. */ +# define _GL_WARN_ON_USE(function, message) \ +extern int _gl_warn_on_use +# endif +#endif diff --git a/m4/warn-on-use.m4 b/m4/warn-on-use.m4 new file mode 100644 index 000000000..ab46422ba --- /dev/null +++ b/m4/warn-on-use.m4 @@ -0,0 +1,45 @@ +# warn-on-use.m4 serial 1 +dnl Copyright (C) 2010 Free Software Foundation, Inc. +dnl This file is free software; the Free Software Foundation +dnl gives unlimited permission to copy and/or distribute it, +dnl with or without modifications, as long as this notice is preserved. + +# gl_WARN_ON_USE_PREPARE(INCLUDES, NAMES) +# --------------------------------------- +# For each whitespace-separated element in the list of NAMES, define +# HAVE_RAW_DECL_name if the function has a declaration among INCLUDES +# even after being undefined as a macro. +# +# See warn-on-use.h for some hints on how to poison function names, as +# well as ideas on poisoning global variables and macros. NAMES may +# include global variables, but remember that only functions work with +# _GL_WARN_ON_USE. Typically, INCLUDES only needs to list a single +# header, but if the replacement header pulls in other headers because +# some systems declare functions in the wrong header, then INCLUDES +# should do likewise. +# +# If you assume C89, then it is generally safe to assume declarations +# for functions declared in that standard (such as gets) without +# needing gl_WARN_ON_USE_PREPARE. +AC_DEFUN([gl_WARN_ON_USE_PREPARE], +[ + m4_foreach_w([gl_decl], [$2], + [AH_TEMPLATE([HAVE_RAW_DECL_]AS_TR_CPP(m4_defn([gl_decl])), + [Define to 1 if ]m4_defn([gl_decl])[ is declared even after + undefining macros.])])dnl + for gl_func in m4_flatten([$2]); do + AS_VAR_PUSHDEF([gl_Symbol], [gl_cv_have_raw_decl_$gl_func])dnl + AC_CACHE_CHECK([whether $gl_func is declared without a macro], + [gl_Symbol], + [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([$1], +[@%:@undef $gl_func + (void) $gl_func;])], + [AS_VAR_SET([gl_Symbol], [yes])], [AS_VAR_SET([gl_Symbol], [no])])]) + AS_VAR_IF([gl_Symbol], [yes], + [AC_DEFINE_UNQUOTED(AS_TR_CPP([HAVE_RAW_DECL_$gl_func]), [1]) + dnl shortcut - if the raw declaration exists, then set a cache + dnl variable to allow skipping any later AC_CHECK_DECL efforts + eval ac_cv_have_decl_$gl_func=yes]) + AS_VAR_POPDEF([gl_Symbol])dnl + done +]) diff --git a/modules/warn-on-use b/modules/warn-on-use new file mode 100644 index 000000000..f0ee83b86 --- /dev/null +++ b/modules/warn-on-use @@ -0,0 +1,35 @@ +Description: +A C macro for emitting a warning if a function is used. + +Applicability: +all + +Files: +build-aux/warn-on-use.h +m4/warn-on-use.m4 + +Depends-on: + +configure.ac: + +Makefile.am: +BUILT_SOURCES += warn-on-use.h +# The warn-on-use.h that gets inserted into generated .h files is the same as +# build-aux/warn-on-use.h, except that it has the copyright header cut off. +warn-on-use.h: $(top_srcdir)/build-aux/warn-on-use.h + $(AM_V_GEN)rm -f $@-t $@ && \ + sed -n -e '/^.ifndef/,$$p' \ + < $(top_srcdir)/build-aux/warn-on-use.h \ + > $@-t && \ + mv $@-t $@ +MOSTLYCLEANFILES += warn-on-use.h warn-on-use.h-t + +WARN_ON_USE_H=warn-on-use.h + +Include: + +License: +LGPLv2+ + +Maintainer: +Eric Blake -- 2.11.0