Some more source code documentation.
[adu.git] / gcc-compat.h
1 /*
2 * Copyright (C) 2008 Andre Noll <maan@systemlinux.org>
3 *
4 * Licensed under the GPL v2. For licencing details see COPYING.
5 */
6
7 /** \file gcc-compat.h Compatibility defines and macros. */
8
9 /** We want you-asked-for-it-you-got-it behavior. */
10 # define inline inline __attribute__ ((always_inline))
11
12 /** Using \p __malloc for malloc-type functions often improves optimization. */
13 # define __malloc __attribute__ ((malloc))
14
15 /**
16 * This allows to enable gcc's -Wunused messages.
17 *
18 * This gcc option can print warnings that can not be avoided easily. For
19 * example when using an array of (structures containing) function pointers.
20 * If not all the functions (handlers) use all arguments, gcc will print
21 * a warning.
22 *
23 * Marking those few unused function parameters with \p __a_unused to supress
24 * the gcc warnings allows us to get a clean build _and_ the benefit of the
25 * warning in other cases where we do care about unused parameters.
26 */
27 # define __a_unused __attribute__ ((unused))
28
29 /** The result \a x is expected to be non-zero. */
30 # define likely(x) __builtin_expect (!!(x), 1)
31 /** The result \a x is expected to be zero (or \p NULL). */
32 # define unlikely(x) __builtin_expect (!!(x), 0)
33
34 /**
35 * Let gcc check format strings also for our own functions.
36 *
37 * Functions marked with \p __printf will be cheked by gcc for format string
38 * bugs, just like printf() if -Wformat-security is enabled.
39 *
40 * \param p The number of the "format string" parameter.
41 * \param q The Number of the first variadic parameter.
42 */
43 # define __printf(p,q) __attribute__ ((format (printf, p, q)))
44
45 /*
46 * as direct use of __printf(p,q) confuses doxygen, here are two extra macros
47 * for those values p,q that are actually used.
48 */
49
50 /** First parameter is the format string, second the first variadic parameter. */
51 #define __printf_1_2 __printf(1,2)
52 /** Second parameter is the format string, third the first variadic parameter. */
53 #define __printf_2_3 __printf(2,3)
54
55 /** Print a warning if the return value is not used by the caller. */
56 # if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ > 3)
57 # define __must_check __attribute__ ((warn_unused_result))
58 # else
59 # define __must_check /* no warn_unused_result */
60 # endif
61
62
63 /**
64 * A variant of static inline that requires the object being documented.
65 *
66 * If doxygen finds the \p static keyword in any context, that part will not be
67 * included in the documentation. However, we want static inline functions in
68 * header files to be documented while static functions in C files and
69 * statically declared variables should be left out. As a workaround for this
70 * flaw we use \p _static_inline_ for static inline functions declared in
71 * header files.
72 */
73 #define _static_inline_ static inline