X-Git-Url: http://git.tuebingen.mpg.de/?p=adu.git;a=blobdiff_plain;f=gcc-compat.h;h=1964e78bfd527d7c9ade762c7473ecc60ba72e93;hp=61c3c88d1c4551a965aaa22c626ddf8fabec31ba;hb=c7d5ddb6906ab8a18181fee29ac78d604db5fdb9;hpb=a4cf08e8062d1d73c343a628563acf4d9f454742

diff --git a/gcc-compat.h b/gcc-compat.h
index 61c3c88..1964e78 100644
--- a/gcc-compat.h
+++ b/gcc-compat.h
@@ -1,25 +1,84 @@
-# define inline		inline __attribute__ ((always_inline))
-# define __noreturn	__attribute__ ((noreturn))
-# define __malloc	__attribute__ ((malloc))
+/*
+ * Copyright (C) 2008 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
+/** \file gcc-compat.h Compatibility defines and macros. */
+
+/** We want you-asked-for-it-you-got-it behavior. */
+# define inline	inline __attribute__ ((always_inline))
+
+/** Using \p __malloc for malloc-type functions often improves optimization. */
+# define __malloc __attribute__ ((malloc))
+
+/**
+ * This allows to enable gcc's -Wunused messages.
+ *
+ * This gcc option can print warnings that can not be avoided easily.  For
+ * example when using an array of (structures containing) function pointers.
+ * If not all the functions (handlers) use all arguments, gcc will print
+ * a warning.
+ *
+ * Marking those few unused function parameters with \p __a_unused to supress
+ * the gcc warnings allows us to get a clean build _and_ the benefit of the
+ * warning in other cases where we do care about unused parameters.
+ */
 # define __a_unused	__attribute__ ((unused))
+
+/** The result \a x is expected to be non-zero. */
 # define likely(x)	__builtin_expect (!!(x), 1)
+/** The result \a x is expected to be zero (or \p NULL). */
 # define unlikely(x)	__builtin_expect (!!(x), 0)
-/* 
- * p is the number of the "format string" parameter, and q is 
- * the number of the first variadic parameter 
+
+/**
+ * Let gcc check format strings also for our own functions.
+ *
+ * Functions marked with \p __printf will be cheked by gcc for format string
+ * bugs, just like printf() if -Wformat-security is enabled.
+ *
+ * \param p The number of the "format string" parameter.
+ * \param q The Number of the first variadic parameter.
  */
 # define __printf(p,q) __attribute__ ((format (printf, p, q)))
+
 /*
  * as direct use of __printf(p,q) confuses doxygen, here are two extra macros
- * for those values p,q that are actually used by paraslash.
+ * for those values p,q that are actually used.
  */
+
+/** First parameter is the format string, second the first variadic parameter. */
 #define  __printf_1_2 __printf(1,2)
+/** Second parameter is the format string, third the first variadic parameter. */
 #define  __printf_2_3 __printf(2,3)
 
+/** Print a warning if the return value is not used by the caller. */
 # if __GNUC__ > 3  || (__GNUC__ == 3 && __GNUC_MINOR__ > 3)
 # define __must_check	__attribute__ ((warn_unused_result))
 # else
 # define __must_check	/* no warn_unused_result */
 # endif
 
+
+/**
+ *  A variant of static inline that requires the object being documented.
+ *
+ * If doxygen finds the \p static keyword in any context, that part will not be
+ * included in the documentation. However, we want static inline functions in
+ * header files to be documented while static functions in C files and
+ * statically declared variables should be left out. As a workaround for this
+ * flaw we use \p _static_inline_ for static inline functions declared in
+ * header files.
+ */
 #define _static_inline_ static inline
+
+/**
+ * On systems whihout large file support (BSD) there is no * struct stat64 and
+ * no lstat64().
+ */
+#ifndef HAVE_STAT64
+	/** Use the usual stat structure. */
+	#define stat64 stat
+	/** Use the usual lstat() function. */
+	#define lstat64 lstat
+#endif